mds.wave.DataProvider Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of jscope Show documentation
Show all versions of jscope Show documentation
MDSplus data display program for waveforms, images and more.
package mds.wave;
import java.io.IOException;
import javax.swing.JFrame;
import mds.connection.*;
/**
* 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 WaveData
*/
public interface DataProvider extends AutoCloseable
{
static final int LOGIN_OK = 1, LOGIN_ERROR = 2, LOGIN_CANCEL = 3;
/**
* 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.
*
* @param l The ConnectionListener which has to be notified by means of method
* processConnectionEvent(ConnenctionEvent)
* @see ConnectionListener
* @see ConnectionEvent
*/
public void addConnectionListener(ConnectionListener l);
/**
* 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
*
* @param l The passed instance of UpdateEventListener.
* @param event The name of the event for which the UpdateEventListener is
* registering.
* @exception java.io.IOException
* @see UpdateEventListener
* @see UpdateEvent
*/
public void addUpdateEventListener(UpdateEventListener l, String event) throws IOException;
/**
* 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.
*/
@Override
public void close();
/**
* 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.
*
* @return A verbose description of the last error.
*/
public String getError();
/**
* 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.
*
* @param in The specification of the value.
* @return The evaluated value.
*/
public double getFloat(String in, int row, int col, int index) 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.
*
* @param in_frame The frame sequence specification as defined in the frames
* field of the setup data popup dialog
* @param start_time Initial considered time for the frame sequence.
* @param end_time Final considered time for the frame sequence.
* @param in_times The definition of the time specification for the frame list
* as defined in the times field of the setup data popup
* dialog.
* @return An implementation of the FrameData interface representing the
* corresponding frame sequence
* @exception java.io.IOException
* @see FrameData
*/
public FrameData getFrameData(String in_frame, String in_times, float start_time, float end_time)
throws IOException;
/**
* Evaluate the passed string to provide an array of shot numbers.
*
* @param inShots The shot(s) specification as typed in the "Shot" field of
* jScope panel
*/
public long[] getShots(String inShots, String experiment) 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.
*
* @param in The specification of the label or title.
* @return The evaluated label or title.
*/
public String getString(String in, int row, int col, int index) throws IOException;
/**
* 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.
*
* @param 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.
* @param row Row number of the corresponding panel
* @param col Column number of the corresponding panel
* @param index Index the corresponding panel
* @return The evaluated signal embedded in a WaveData object, or null if an
* error is encountered.
* @see WaveData
*/
public WaveData getWaveData(String in, 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.
*
* @param in_y Y axis specification as typed in the setup data source popupo
* dialog.
* @param in_x X axis specification as typed in the setup data source popupo
* dialog.
* @param row Row number of the corresponding panel
* @param col Column number of the corresponding panel
* @param index Index the corresponding panel
* @return The evaluated signal, embedded in a WaveData object, or null if an
* error is encountered.
* @see WaveData
*/
public WaveData getWaveData(String in_y, String in_x, int row, int col, int index);
/**
* 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.
*
* @param frame The container Frame.
* @return The status of the DataProvider specific validation process
*/
public int inquireCredentials(JFrame frame, DataServerItem server_item);
/**
* Can be used to check if provider is busy (helps scheduling).
*
* @return true is busy.
*/
public boolean isBusy();
/**
* Called by jScope when transfer notification is no more requested. Empty if
* the DataProvider implementation does not support transfer status
* notification.
*
* @param l The previously registered ConnectionListener.
* @see ConnectionListener
*/
public void removeConnectionListener(ConnectionListener l);
/**
* Method RemoveUpdateEventListeneris called by jScope when the display of a
* waveform panel is no more triggered by an event.
*
* @param l The instance of UpdateEventListener previously registered.
* @param event The event to which the listener was previously registered.
* @exception java.io.IOException
* @see UpdateEventListener
*/
public void removeUpdateEventListener(UpdateEventListener l, String event) 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.
*
* @param arg The argument passed to the DataProvider implementation.
* @exception java.io.IOException
*/
public void setArgument(String arg) 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.
*
* @param exp The variable definition expressed as name value pair.
* @exception java.io.IOException
*/
public void setEnvironment(String exp) throws IOException;
/**
* Enable tunneling activation. Return False if no ssh tunneling available.
*
* @return Tunneling flag
**/
public boolean supportsTunneling();
/**
* 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.
*
* @param exp The experiment name
* @param s The shot number.
*/
public void update(String exp, long shot);
}