com.sl.gmsjrtviewds
Class GmsRtViewDsAdapter

java.lang.Object
  com.sl.gmsjrtviewds.GmsRtViewDsAdapter

public class GmsRtViewDsAdapter
extends java.lang.Object

The GmsRtViewDsAdapter class is the base class for an external data adapter in an Enterprise RTView datasource, with methods that allow the orderly initialization and shutdown of the datasource as well as the registration and updating of data objects, the management of connections and datasource-specific options, the execution of commands, and the validation of information entered into dialogs during the execution of an Enterprise RTView application.

In a datasource, the GmsRtViewDsAdapter works in conjunction with the GmsRtViewDs class to implement the functions required to make external data available to an Enterprise RTView application. Typically, the GmsRtViewDs class is used to provide metadata used to configure the datasource, while the GmsRtViewDsAdapter is used to access the external data and make it available for use in Enterprise RTView displays.

The methods in the GmsRtViewDsAdapter class may be overridden by a subclass to provide datasource-specific support in the following areas:

• Datasource Management: The initializeData(), startData(), and terminateData() methods are called during program startup and shutdown, and allow the application to perform any necessary initialization or termination of the external data source.

• Data Management: As the application runs and displays are loaded and freed, the datasource creates and removes Data Objects. When a data object is created, the registerData() method is called to allow the application to register interest in the data with the external data source. Likewise, when a data object is freed, the unregisterData() method is called to allow the application to unregister interest in the data with the external data source.

  While a data object is active, the updateDataObject() method is called periodically from the Enterprise RTView update timer, to allow the application to change the data for a data object. A polled datasource would override this method to periodically check and update data values when new data is available. The storeData methods in the GmsRtViewDs class are used to store the data in the datasource.

• Connection Management: The GmsRtViewDsAdapter also provides methods to control connections to the external data source. The information for a connection is contained in a ConnInfo Object. At startup the datasource will invoke the attemptConnection() method to allow the application to establish a connection with the external data source. Similarly, at shutdown the datasource will invoke the closeConnection() method to allow the application to terminate a connection.

• Datasource Options: The applyDsOption() method allows the application to apply Datasource Options. Options are applied during application initialization.

• Commands: The executeCommand() method allows the application to execute a command.

• Dialog Validation: The GmsRtViewDsAdapter provides methods to allow the application to validate the information entered into dialogs in the Enterprise RTView Builder. The validate(GmsRtViewDataObject) method validates data for the Attach To Data Dialog, the validate(GmsRtViewDsConnInfo) method validates the data in the Connections Tab of the Options Dialog, and the validate(GmsRtViewDsOptions) method validates the data entered in the Options Tab of the Options Dialog.

Field Summary

protected GmsRtViewDs

ds The datasource.

Constructor Summary

GmsRtViewDsAdapter()

Method Summary

protected boolean	applyDsOption(java.lang.String name, java.lang.String value) Apply an option to the datasource.
protected ConnectStatus	attemptConnection(GmsRtViewDsConnInfo connInfo) Attempt to open this connection.
protected void	beginUpdateData()
protected void	closeConnection(GmsRtViewDsConnInfo connInfo) Close this connection.
protected GmsRtViewDsCommandStatus	executeCommand(GmsRtViewDsCommand command) Execute the command and set status of executed command.
protected void	initializeData() Initialize this datasource.
protected void	registerData(GmsRtViewDataObject dataObj) Register interest in a data object.
protected void	startData() Start this datasource.
protected void	terminateData() Terminate this datasource.
protected void	unregisterData(GmsRtViewDataObject dataObj) Unregister interest in a data object.
protected void	updateDataObject(GmsRtViewDataObject dataObj) Update a single data object.
protected void	updateDataObject(GmsRtViewDataObject dataObj, boolean newSourcesOnlyFlag) Update a single data object.
protected void	validate(GmsRtViewDataObject dataObject) Validate a data object.
protected void	validate(GmsRtViewDsConnInfo connInfo) Validate a connection info object.
protected void	validate(GmsRtViewDsOptions dsOptions) Validate the datasource options.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ds

protected GmsRtViewDs ds

The datasource.

Constructor Detail

GmsRtViewDsAdapter

public GmsRtViewDsAdapter()

Method Detail

applyDsOption

protected boolean applyDsOption(java.lang.String name,
                                java.lang.String value)

Apply an option to the datasource. Options may come from the options file or the command line. This method should return true if the option was successfully processed.

Parameters:

name - The name of the DS option

value - The value of the DS option

attemptConnection

protected ConnectStatus attemptConnection(GmsRtViewDsConnInfo connInfo)

Attempt to open this connection. The user should overide this method to provide a custom connection implementation

Parameters:

connInfo - Information on the connection to be opened

Returns:

The status of the attempt connection

beginUpdateData

protected void beginUpdateData()

closeConnection

protected void closeConnection(GmsRtViewDsConnInfo connInfo)

Close this connection. The user should provide a method to override this implemention for closing their connection.

Parameters:

connInfo -

executeCommand

protected GmsRtViewDsCommandStatus executeCommand(GmsRtViewDsCommand command)

Execute the command and set status of executed command. The user should override this method to provide command execution handling for thier custom datasource. Set the return status and any message in the custom status.

Parameters:

command -

Returns:

status, OK or ERROR + message.

initializeData

protected void initializeData()

Initialize this datasource. Subclasses should override this method to perform any required initialization of the external data source.

registerData

protected void registerData(GmsRtViewDataObject dataObj)

Register interest in a data object. This method is invoked the first time that a data attachment is made by the RTView datasource. Subclasses should override this method to register interest in the data with their external data source.

Parameters:

dataObj - the data object to register

startData

protected void startData()

Start this datasource. Subclasses should override this method to perform any required operations which initiate data generation in the external data source.

terminateData

protected void terminateData()

Terminate this datasource. Subclasses should override this method to perform any required operations to terminate data generation in the external data source.

unregisterData

protected void unregisterData(GmsRtViewDataObject dataObj)

Unregister interest in a data object. This method is invoked when a data attachment is no longer needed by the RTView datasource. Subclasses should override this method to remove interest in the data with their external data source.

Parameters:

dataObj - the data object to unregister

updateDataObject

protected void updateDataObject(GmsRtViewDataObject dataObj)

Update a single data object. This method is called periodically for each active data object, based upon the Enterprise RTView Update Rate.

Subclasses should override this method to implement a "polled" data update strategy. Typically, the fields of the data object would be queried to identify it, data would be retrieved from the external data source, and GmsRtViewDs.storeData would be called to update the data.

updateDataObject

protected void updateDataObject(GmsRtViewDataObject dataObj,
                                boolean newSourcesOnlyFlag)

Update a single data object. This method is called periodically for each active data object, based upon the Enterprise RTView Update Rate.

Subclasses should override this method to implement a "polled" data update strategy. Typically, the fields of the data object would be queried to identify it, data would be retrieved from the external data source, and GmsRtViewDs.storeData would be called to update the data. If the newSourcesOnly Flag is true, then the custom adapater should only update data attchments recently defined.

validate

protected void validate(GmsRtViewDataObject dataObject)

Validate a data object. The user application will examine the object's field values and determine which are valid or invalid, and will set this information on the object before returning.

Parameters:

dataObject - the data object to validate

validate

protected void validate(GmsRtViewDsConnInfo connInfo)

Validate a connection info object. The user application will examine the object's field values and determine which are valid or invalid, and will set this information on the object before returning.

Parameters:

connInfo - the connection info object to validate

validate

protected void validate(GmsRtViewDsOptions dsOptions)

Validate the datasource options. The user application will examine the object's field values and determine which are valid or invalid, and will set this information on the object before returning.

Parameters:

dsOptions - the datasource options object to validate.