mds.wave

Interface DataProvider

All Superinterfaces:

AutoCloseable

All Known Implementing Classes:

AsciiDataProvider, AsdexDataProvider, FtuDataProvider, JetDataProvider, MdsDataProvider, MdsDataProviderAsync, MdsDataProviderLocal, MdsDataProviderSsh, TsDataProvider, TwuDataProvider, UniversalDataProvider

public interface DataProvider
extends AutoCloseable

The DataProvider interface is used by jScope to deal with signals, regardless their origin. DataProvider defines a set of method for providing the signal and supporting several features which may be enabled or disabled depending on the current implementation of the DataProvider interface. Signals are not directly returned by DataProvider access methods as vectors (as it was done in earlier jScope versions). Rather DataProvider GetWaveData method returns an implementation of WaveData. Interface WaveData defines the methods for collecting signal data.

See Also:

WaveData

Field Summary

Fields

Modifier and Type	Field and Description
static int	LOGIN_CANCEL
static int	LOGIN_ERROR
static int	LOGIN_OK

Method Summary

Modifier and Type	Method and Description
void	addConnectionListener(ConnectionListener l) Method AddConnectionListener is called by jScope after the instantiation of a DataProvider implementation, in order to be notified of the status of data transfer.
void	addUpdateEventListener(UpdateEventListener l, String event) Method AddUpdateEventListener is called by jScope when asynchronous update on event is defined.
void	close() Method Dispose is called by jScope each time a DataProvider is no more used.
String	getError() If an error is encountered in the evaluation of a signal (GetWaveData or GetResampledWaveData returning null or generating IOException), jScope calls ErrorString method to retrieve the description of the error just occurred.
double	getFloat(String in, int row, int col, int index) Method GetFloat is called by jScope to evaluate x min, x max, y min, y max when defined in the stup data source popup form.
FrameData	getFrameData(String in_frame, String in_times, float start_time, float end_time) GetFrameData is called by jScope to retrieve and display a frame sequence.
long[]	getShots(String inShots, String experiment) Evaluate the passed string to provide an array of shot numbers.
String	getString(String in, int row, int col, int index) GetString is called by jScope to evaluate title, X label and Y label.
WaveData	getWaveData(String in, int row, int col, int index) Method GetWaveData called by jScope when a waveform has to be evaluated and only the Y axis is defined.
WaveData	getWaveData(String in_y, String in_x, int row, int col, int index) Method GetWaveData called by jScope when a waveform has to be evaluated and both X and Y axis are defined.
int	inquireCredentials(JFrame frame, DataServerItem server_item) Some DataProvider implemenations may require additional information (e.g.
boolean	isBusy() Can be used to check if provider is busy (helps scheduling).
void	removeConnectionListener(ConnectionListener l) Called by jScope when transfer notification is no more requested.
void	removeUpdateEventListener(UpdateEventListener l, String event) Method RemoveUpdateEventListeneris called by jScope when the display of a waveform panel is no more triggered by an event.
void	setArgument(String arg) As DataProvider implementations are instantiated by jScope by means of the Class.newInstance(), no arguments can be passed to the constructor method.
void	setEnvironment(String exp) Defines the environment for data retrieval.
boolean	supportsTunneling() Enable tunneling activation.
void	update(String exp, long shot) Method Update is called by jScope to notify the experiment name and the shot number.

Field Detail

LOGIN_OK

static final int LOGIN_OK

See Also:

Constant Field Values

LOGIN_ERROR

static final int LOGIN_ERROR

See Also:

Constant Field Values

LOGIN_CANCEL

static final int LOGIN_CANCEL

See Also:

Constant Field Values

Method Detail

addConnectionListener

void addConnectionListener(ConnectionListener l)

Method AddConnectionListener is called by jScope after the instantiation of a DataProvider implementation, in order to be notified of the status of data transfer. If a DataProvider implementation has to handle the transfer of large chunks of data (e.g. frame sequences) requiring a relatively long time, it should be able to communicate the current status of the transfer to jScope which displays then a status bar. To do this, the DataProvider implementation calls ConnectionListener's method processConnectionEvent, passing an istance of ConnectionEvent as argument. Class ConnectionEvent defines the following information:
- int total_size: total size of the data to be transferred
- int current_size: the size of the data transferred so far
- String info: an additional information string which is displayed by jScope
If the DataProvider implementation does not support transfer notification, method AddConnectionListener is empty.

Parameters:

l - The ConnectionListener which has to be notified by means of method processConnectionEvent(ConnenctionEvent)

See Also:

ConnectionListener, ConnectionEvent

addUpdateEventListener

void addUpdateEventListener(UpdateEventListener l,
                            String event)
                     throws IOException

Method AddUpdateEventListener is called by jScope when asynchronous update on event is defined. To connect data visualization to asynchronous event an event name has to be defined in the Update event field of the setup data form popup dialog. DataProvider implementations supporting asynchronous signal updating should notify event occurrence to all registered listeners by calling method processUpdateEvent(UpdateEvent e). UpdateEvent defines the following field, in addition to those defined in the AWTEvent superclass:
- String name: the name of the event
The possibility of connecting data display to asynchronous events is useful when jScope is used during data acquisition, for an automatic display update when a signal has been acquired. In this case the data acquisition system would generate an event when the signal has been acquired, and the DataProvider implementation would call method processUpdateEvent (defined in UpdateEventListener interface) to request the display update to jScope.
If the DataProvider implementation does not support asynchronous events, the method is void

Parameters:

l - The passed instance of UpdateEventListener.

event - The name of the event for which the UpdateEventListener is registering.

Throws:

IOException

See Also:

UpdateEventListener, UpdateEvent

close

void close()

Method Dispose is called by jScope each time a DataProvider is no more used. Unlike Object.finalize(), method Dispose is guaranteed to be called at the time the DataProvider implementation is no more used by jScope.

Specified by:

close in interface AutoCloseable

getError

String getError()

If an error is encountered in the evaluation of a signal (GetWaveData or GetResampledWaveData returning null or generating IOException), jScope calls ErrorString method to retrieve the description of the error just occurred.

Returns:

A verbose description of the last error.

getFloat

double getFloat(String in,
                int row,
                int col,
                int index)
         throws IOException

Method GetFloat is called by jScope to evaluate x min, x max, y min, y max when defined in the stup data source popup form. The argument is in fact the string typed by the user in the form. In its simplest implementation, method GetFloat converts the string into a float value and returns it. Other data providers, such as MdsDataProvider, evaluate, possibly remotely, the passed string which may therefore be represented by an expression.

Parameters:

in - The specification of the value.

Returns:

The evaluated value.

Throws:

IOException

getFrameData

FrameData getFrameData(String in_frame,
                       String in_times,
                       float start_time,
                       float end_time)
                throws IOException

GetFrameData is called by jScope to retrieve and display a frame sequence. The frame sequence is returned by means of an object implementing the FrameData interface.

Parameters:

in_frame - The frame sequence specification as defined in the frames field of the setup data popup dialog

start_time - Initial considered time for the frame sequence.

end_time - Final considered time for the frame sequence.

in_times - The definition of the time specification for the frame list as defined in the times field of the setup data popup dialog.

Returns:

An implementation of the FrameData interface representing the corresponding frame sequence

Throws:

IOException

See Also:

FrameData

getShots

long[] getShots(String inShots,
                String experiment)
         throws IOException

Evaluate the passed string to provide an array of shot numbers.

Parameters:

inShots - The shot(s) specification as typed in the "Shot" field of jScope panel

Throws:

IOException

getString

String getString(String in,
                 int row,
                 int col,
                 int index)
          throws IOException

GetString is called by jScope to evaluate title, X label and Y label. These labels are defined as string in the Setup data source popup form. In the simplest case labels are exactly the same as defined, and therefore GetString simply returns its argument. In any case the data provider is free to interpret differently the argument.

Parameters:

in - The specification of the label or title.

Returns:

The evaluated label or title.

Throws:

IOException

getWaveData

WaveData getWaveData(String in,
                     int row,
                     int col,
                     int index)

Method GetWaveData called by jScope when a waveform has to be evaluated and only the Y axis is defined. In this case jScope assumes that the specification is enough and it is up to the data provider implementation to retrieve X and Y axis. The evaluated signal is not directly returned as a vector, rather as a object implementing the WaveData interface.

Parameters:

in - The specification of the signal, typed in the Y axis field of the setup data source popup form, or in the lower right window of jScope.

row - Row number of the corresponding panel

col - Column number of the corresponding panel

index - Index the corresponding panel

Returns:

The evaluated signal embedded in a WaveData object, or null if an error is encountered.

See Also:

WaveData

getWaveData

WaveData getWaveData(String in_y,
                     String in_x,
                     int row,
                     int col,
                     int index)

Method GetWaveData called by jScope when a waveform has to be evaluated and both X and Y axis are defined. The evaluated signal is not directly treturned as a vector, rather as a object implementing the WaveData interface. jScope the uses the returned object to retieve X and Y axis.

Parameters:

in_y - Y axis specification as typed in the setup data source popupo dialog.

in_x - X axis specification as typed in the setup data source popupo dialog.

row - Row number of the corresponding panel

col - Column number of the corresponding panel

index - Index the corresponding panel

Returns:

The evaluated signal, embedded in a WaveData object, or null if an error is encountered.

See Also:

WaveData

inquireCredentials

int inquireCredentials(JFrame frame,
                       DataServerItem server_item)

Some DataProvider implemenations may require additional information (e.g. username and password) typed by users in a login form. As jScope does not make any assumption on this kind of information it is up to the DataProvider implementation to realize such a form (if any). For this reason jScope calls method InquireCredential passing as argument the container JFrame. InquireCredentials may return:
-DataProvider.LOGIN_OK if the DataProvider has been succesfully validated
-DataProvider.LOGIN_ERROR if the DataProvided did not succeed in validation
-DataProvider.LOGIN_CANCEL if the login proess has been aborted by user (usually pressing
a cancel button)
Only in the first case jScope will proceede with the usega of the DataProvider implementation. In the secon case a warning dialog is shown, and in the third case the DataProvider is simply discarded.

Parameters:

frame - The container Frame.

Returns:

The status of the DataProvider specific validation process

isBusy

boolean isBusy()

Can be used to check if provider is busy (helps scheduling).

Returns:

true is busy.

removeConnectionListener

void removeConnectionListener(ConnectionListener l)

Called by jScope when transfer notification is no more requested. Empty if the DataProvider implementation does not support transfer status notification.

Parameters:

l - The previously registered ConnectionListener.

See Also:

ConnectionListener

removeUpdateEventListener

void removeUpdateEventListener(UpdateEventListener l,
                               String event)
                        throws IOException

Method RemoveUpdateEventListeneris called by jScope when the display of a waveform panel is no more triggered by an event.

Parameters:

l - The instance of UpdateEventListener previously registered.

event - The event to which the listener was previously registered.

Throws:

IOException

See Also:

UpdateEventListener

setArgument

void setArgument(String arg)
          throws IOException

As DataProvider implementations are instantiated by jScope by means of the Class.newInstance(), no arguments can be passed to the constructor method. If an additional argument is required for the proper initialization of the DataProvider implementation (e.g. the ip address for the MdsDataProvider), the argument, defined in the server_n.argument item of the property file is passed through method SetArgument called by jScope just after the DataProvider instantiation.

Parameters:

arg - The argument passed to the DataProvider implementation.

Throws:

IOException

setEnvironment

void setEnvironment(String exp)
             throws IOException

Defines the environment for data retrieval. Depending on the nature of the provider of data, some environment variable may be defined. For example the MdsDataProvider allows the definition of TDI variables which may be useful for configuring remote data access. jScope allows the definition of an arbitrary set of environment variable using the customize--public variables... option. As jScope does not make any assumption on the syntax of the defined variables, each variable definition is passed to the Data provider by means of the SetEnvironment method, whose argument is a String which defines name value pairs. If the DataProvider implementation does not support such a feature, it simply returns.

Parameters:

exp - The variable definition expressed as name value pair.

Throws:

IOException

supportsTunneling

boolean supportsTunneling()

Enable tunneling activation. Return False if no ssh tunneling available.

Returns:

Tunneling flag

update

void update(String exp,
            long shot)

Method Update is called by jScope to notify the experiment name and the shot number. Update can be called several time by jScope for the same DataProvider implementation in the case user changes either the experiment name or the shot number.

Parameters:

exp - The experiment name

s - The shot number.