Interface DataProvider

public interface DataProvider

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

static int	LOGIN_CANCEL
static int	LOGIN_ERROR
static int	LOGIN_OK

Method Summary

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, java.lang.String event) Method AddUpdateEventListener is called by jScope when asynchronous update on event is defined.
boolean	DataPending() Method DataPending is called by jScope to verify whether the current signal has been fully displayed.
void	Dispose() Method Dispose is called by jScope each time a DataProvider is no more used.
java.lang.String	ErrorString() If an error is encountered in the evaluation of a signal (GetWaveData or GetResampledWaveData returning null or generation IOException), jScope calls ErrorString method to retrieve the description of the error just occurred.
float	GetFloat(java.lang.String in) 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(java.lang.String in_frame, java.lang.String in_times, float start_time, float end_time) GetFrameData is called by jScope to retrieve and display a frame sequence.
WaveData	GetResampledWaveData(java.lang.String in, float start, float end, int n_points) When the network->fast network access option is enabled, jScope uses GetResampledWaveData instead of GetWaveData to evaluate waveformes.
WaveData	GetResampledWaveData(java.lang.String in_y, java.lang.String in_x, float start, float end, int n_points) Same as the GetResampledWaveData, except that it is called when both X and Y axis are specified.
java.lang.String	GetString(java.lang.String in) GetString is called by jScope to evaluate title, X label and Y label.
WaveData	GetWaveData(java.lang.String in) Method GetWaveData is called by jScope when a waveform has to be avaluated and only the Y axis is defined.
WaveData	GetWaveData(java.lang.String in_y, java.lang.String in_x) Method GetWaveData is called by jScope when a waveform has to be avaluated and both X and Y axis are defined.
int	InquireCredentials(javax.swing.JFrame f) Some DataProvider implemenations, such as Jet RDA provider, may require additional information (e.g. username and password) typed by users in a login form.
void	RemoveConnectionListener(ConnectionListener l) Called by jScope when transfer notification is no more requested.
void	RemoveUpdateEventListener(UpdateEventListener l, java.lang.String event) Method RemoveUpdateEventListeneris called by jScope when the display of a waveform panel is no more triggered by an event.
void	SetArgument(java.lang.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	SetCompression(boolean state) Called by jScope to enable or disable data compression in transmission.
void	SetEnvironment(java.lang.String exp) Defines the environment for data retrieval.
boolean	SupportsCompression() Returns tre if the DataProvider impementation supports data compression in communication. jScope does not make any assumption about compression, simply provides the user interface for enablin or disabling compression, by means Network->Enable compression option.
boolean	SupportsContinuous() If SupportsContinuous returns true, jScope is prepared to handle a signal changing over time.
boolean	SupportsFastNetwork() Called by jScope to verify whether the DataProvider impementation supports the Fast Network option.
void	Update(java.lang.String exp, int s) Method Update is called by jScope to notify the experiment name and the shot number.

Field Detail

LOGIN_OK

public static final int LOGIN_OK

LOGIN_ERROR

public static final int LOGIN_ERROR

LOGIN_CANCEL

public static final int LOGIN_CANCEL

Method Detail

SetEnvironment

public void SetEnvironment(java.lang.String exp)
                    throws java.io.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:

java.io.IOException -

Update

public void Update(java.lang.String exp,
                   int s)

Method Update is called by jScope to notify the experiment name and the shot number. Update can be called several time by jScope dfor 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.

GetString

public java.lang.String GetString(java.lang.String in)
                           throws java.io.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:

java.io.IOException -

GetFloat

public float GetFloat(java.lang.String in)
               throws java.io.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:

java.io.IOException -

GetWaveData

public WaveData GetWaveData(java.lang.String in)

Method GetWaveData is called by jScope when a waveform has to be avaluated 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 treturned as a vector, rather as a object implementing the WaveData interface. The WaveData interface defines the following methods:
- int GetNumDimensions() returns the number of dimensions. Currently only signals (dimension=1) are supported.
- float[] GetFloatData() returns the Y axis of the signal as a float array. For bidimensional signals (not yet supported) the array is organized in row order;
- float[] GetXData() returns the X axis of the signal;
- float[] GetYData() returns the Y axis for a bidimensional signal;
- String GetTitle() returns the associated title (if no title is defined in the setup data popup dialog);
- String GetXLabel() returns the associated X label(if no X label is defined in the setup data popup dialog);
- String GetYLabel() returns the associated Y label(if no Y label is defined in the setup data popup dialog);
- String GetZLabel() returns the associated Z label(if no Z label is defined in the setup data popup dialog);

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.

Returns:

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

See Also:

WaveData

GetWaveData

public WaveData GetWaveData(java.lang.String in_y,
                            java.lang.String in_x)

Method GetWaveData is called by jScope when a waveform has to be avaluated 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.

Returns:

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

See Also:

WaveData

GetResampledWaveData

public WaveData GetResampledWaveData(java.lang.String in,
                                     float start,
                                     float end,
                                     int n_points)

When the network->fast network access option is enabled, jScope uses GetResampledWaveData instead of GetWaveData to evaluate waveformes. Method GetResampledWaveData should return the resampled version of the specified waveform, and resampling should be done at the data server site in orer to reduce network transfer time for large signals. GetResampledData is also asynchronously called when users zoom a resampled waveform in order to collect more points of the selected region. DataProvider implementations can enable the ast network access option by returning true in method SupportsFastNetwork. Otherwise an empty implementation of GetResampledWaveData suffices.

Parameters:

in - Y axisi definition as typed in the setup data source popup dialog.

start - Start X value for the requested region.

end - End X valus for the requested region.

n_points - Number of points for the resampled signal.

Returns:

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

See Also:

WaveData

GetResampledWaveData

public WaveData GetResampledWaveData(java.lang.String in_y,
                                     java.lang.String in_x,
                                     float start,
                                     float end,
                                     int n_points)

Same as the GetResampledWaveData, except that it is called when both X and Y axis are specified.

Parameters:

in_y - Y axis definition for the requested signal.

in_x - X axis definition for the requested signal.

start - Start X value.

end - End X value.

n_points - Number of points for the resampling.

Returns:

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

See Also:

WaveData

SupportsFastNetwork

public boolean SupportsFastNetwork()

Called by jScope to verify whether the DataProvider impementation supports the Fast Network option. If SupportsFastNetwork return true, jScope retrieves data by calling GetResampledWaveData which has to be thread safe. GetResampledWaveData is in fact called by a separate thread each time a zoom is done, to retrieve more points for the selected region. If SupportsFastNetwork return false, GetWaveData is called instead of GetResampledWaveData, which can be empty.

Returns:

The ability of supporting fast network access.

ErrorString

public java.lang.String ErrorString()

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

Returns:

A verbose description of the last error.

AddUpdateEventListener

public void AddUpdateEventListener(UpdateEventListener l,
                                   java.lang.String event)
                            throws java.io.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 aynchronous 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 possiblity of connecting data display to asynchronous events is useful when jScope is used during data acquisition, for an atomatic 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 inetrafce) to request the display update to jScope.
If the DataProvider implementation does not support asynchronous events, the method is defined empty.
NOTE: asynchronous update on event is not required for displaying evolving signals such as trend recording. See the description of methods SupportsContinuous() and DataPending() for the management of evolving signals.

Parameters:

l - The passed instance of UpdateEventListener.

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

Throws:

java.io.IOException -

See Also:

UpdateEventListener, UpdateEvent

RemoveUpdateEventListener

public void RemoveUpdateEventListener(UpdateEventListener l,
                                      java.lang.String event)
                               throws java.io.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 proeviously registered.

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

Throws:

java.io.IOException -

GetFrameData

public FrameData GetFrameData(java.lang.String in_frame,
                              java.lang.String in_times,
                              float start_time,
                              float end_time)
                       throws java.io.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 FramesData interface. The methods defined in the FrameData interface are the following:
- int GetFrameType() returning the type of the corresponding frames, as returned by GetFrameAt, which can be:
-FramesData.BITMAP if the frames are returned by method GetFrameAt as a byte matrix
-FrameData.AWT_IMAGE if the frames are returned by method GetFrameAt as the
content of a gif or jpg file
-FrameData.JAI_IMAGE if the frames are returned by method GetFrameAt as the content of every other file format supported by JAI.
- int GetNumFrames() returning the number of frames in the sequence
- Dimension GetFrameDimension() returning the dimension of the single frame
- float [] GetFrameTimes returning the times associated with each frame
- byte[] GetFrameAt(int idx) returning the corresponding frame

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:

java.io.IOException -

See Also:

FrameData

SupportsContinuous

public boolean SupportsContinuous()

If SupportsContinuous returns true, jScope is prepared to handle a signal changing over time. An example is the display of a trend recording showing a waveform which is updated each time a new set of samples has been acquired. More generally, an arbitrarily evolving signal can be diaplayed this way. If a DataProvider implentation returns true, a separate thread calls repeadetly methods GetWaveData() and DataPending() until the second method returns false. In this case GetWaveData() will wait until a new set of samples is ready and has to be dispalyed by jScope, while method DataPending() notifies to jScope whether new data has to be displayed for the signal, i.e. whether the signal has not yet finished to be produced.
If SupportsContinuous returns false, method GetWaveData (or GetResampledWaveData) is called only once to retrieve the whole signal.
NOTE in the current implementation, update frequencies up to few Hz can be handled by jScope with a limited CPU usage.

Returns:

The indication whether support for evolving signals is provided.

DataPending

public boolean DataPending()

Method DataPending is called by jScope to verify whether the current signal has been fully displayed. It DataPending returns false, method GetWaveData is alled again to retrieve a new version (usually with some more saples) of the signal.
If method SupportsContinuous() returned false, DataPending is never called by jScope, and can therefore be empty.

Returns:

Indicates whether the current signal is complete.

SupportsCompression

public boolean SupportsCompression()

Returns tre if the DataProvider impementation supports data compression in communication. jScope does not make any assumption about compression, simply provides the user interface for enablin or disabling compression, by means Network->Enable compression option. If compression is not supported by the DataProvider implementation, the Network->Enable option id disabled.

Returns:

true if the DataProvider implementation supports compression.

SetCompression

public void SetCompression(boolean state)

Called by jScope to enable or disable data compression in transmission. If the DataProvider implementation doe not support compression and returned false in SupportsCompression(), SetCompression is never called.

Parameters:

state - Indicates whether compression is enabled or disabled.

Dispose

public void Dispose()

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.

AddConnectionListener

public 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 chuncks 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

RemoveConnectionListener

public 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.

InquireCredentials

public int InquireCredentials(javax.swing.JFrame f)

Some DataProvider implemenations, such as Jet RDA provider, 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 passingf 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 canel 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:

f - The container Frame.

Returns:

The status of the DataProvider specific validation process

SetArgument

public void SetArgument(java.lang.String arg)
                 throws java.io.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 fotr 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:

java.io.IOException -