com.sl.gmsjrtviewds
Class GmsRtViewDs

java.lang.Object
  com.sl.gmsjrtview.GmsRtViewDs
      com.sl.gmsjrtviewds.GmsRtViewDs

All Implemented Interfaces:

java.util.Comparator

public abstract class GmsRtViewDs
extends com.sl.gmsjrtview.GmsRtViewDs
implements java.util.Comparator

The GmsRtViewDs class is the base class for an Enterprise RTView datasource, providing methods to customize information about the files, classes, and resources available with the datasource, the data objects used to create data attachments, the conn info objects used to establish connections with external systems, the options object used to provide datasource-specific options, and the dialogs that are displayed in the Enterprise RTView Builder.

This class also identifies the GmsRtViewDsAdapter class for the datasource, which provides methods to initialize and update the data objects used by the datasource from external data, to manage connections with the external data source, to apply custom options, execute commands, and validate information entered into dialogs.

The GmsRtViewDs class manages the following types of objects:

• Data Tables: All data stored in the database is maintained in a collection of data tables (GmsTabularData). Data tables are stored and updated using the storeData methods in this class. The getStoredDataTable() method is used to retrieve a data table from the datasource.

  When storing data, the table name is specified either directly by supplying a data key, or indirectly by supplying a Data Object. When a data object is supplied, the data key is automatically constructed from the values of the data key column fields defined during initialization. If a data object is not available, the data key can be constructed using the method buildDataKey().

  Note that this datasource does not store historical data. Whenever new data is stored, the previous data table is replaced. To store historical data, use the Cache Datasource in conjunction with attachments to data from this datasource.

• Data Objects: A data object (GmsRtViewDataObject) specifies an active attachment between a property of an Enterprise RTView object and the datasource. Data objects are created and freed as displays are loaded and unloaded by a running application.
• Conn Info Objects: A conn info object (GmsRtViewDsConnInfo) holds information that can be used to establish a connection to the external data source. The datasource monitors the status of connections, and instructs the GmsRtViewDsAdapter to attempt or close a connection. Connections are defined and edited in the Connections Tab of the Options Dialog in the Enterprise RTView Builder.
• DS Options Object: The ds options object (GmsRtViewDsOptions) holds information about custom options specific to this datasource. The options are entered in the Options Tab of the Options Dialog in the Enterprise RTView Builder.

To configure the datasource, subclasses are responsible for providing implementations of the following abstract methods:

• In the initDsBaseProperties() method the subclass sets information in a GmsRtViewDsBaseProperties object to configure the base metadata for the datasource. The metadata includes descriptive information, the names of auxiliary classes and files, available datasource behaviors, and localization information. This method is called when the class is constructed, before any command-line arguments or ds options have been processed.
• In the initDsControlProperties() method the subclass sets information in a GmsRtViewDsControlProperties object to configure the control metadata for the datasource. The metadata includes descriptive information, the names of auxiliary classes and files, available datasource behaviors, and localization information. This method is called after the command-line arguments and ds options have been processed, so information from these sources is available for customization.
• In the initDataObjectExemplar() method the subclass defines the structure of the Data Object used to specify data attachments. The method will add fields, with optional information about the UI elements used to display the fields in the Attach To Data Dialog. The method will also specify the fields used to identify the data key, and will optionally specify index fields to be included with the data when it is stored in the datasource.
• In the initConnInfoExemplar() method the subclass defines the structure of the ConnInfo Object, which describes a named connection to the external data source. The method will add fields, with optional information about the UI elements used to display the fields in the Connections Tab of the Options Dialog.
• In the initDsOptionsExemplar() method the subclass defines the structure of the DS Options Object, which describes the custom options available for the datasource. The method will add fields, with optional information about the UI elements used to display the fields in the DS Options Tab of the Options Dialog.

Nested Class Summary

static class

GmsRtViewDs.UpdateMode Update mode used to update polled data

Field Summary

static java.util.Set	ALL_UPDATE_MODES Convenience to enable all update modes
static java.util.Set	DEFAULT_UPDATE_MODES Update modes enabled by default
static java.util.Set	NO_UPDATE_MODES Convenience to disable all update modes

Fields inherited from class com.sl.gmsjrtview.GmsRtViewDs

appMgr, connectToDatasource, dataEnabled, editFlag, Graphs, loginMode, loginPassword, loginUserName, MULTI_CLIENT_DSSTRING_LOGIN, MULTI_CLIENT_SUB_LOGIN, NO_LOGIN, rtvHome, SINGLE_CLIENT_LOGIN, subDelims, timeTrace, traceLevel

Constructor Summary

GmsRtViewDs()
Construct a GmsRtViewDs.

Method Summary

protected void	addConnection(GmsRtViewDsConnInfo connInfo) This is called from the command line, applet params, options file and options dialog to add a new or modified connInfo.
java.lang.String	buildDataKey(GmsRtViewDataObject dataObject) Construct the data key for a data object, using the current values of the data key fields.
java.lang.String	buildDataKey(java.lang.String[] values) Construct a data key given an array of values.
void	closeConnection(GmsRtViewDsConnInfo connInfo) Close a connection.
GmsRtViewDsConnInfo	getConnInfoFromName(java.lang.String name) Get the GmsRtViewDsConnInfo with the given name.
java.util.Set	getConnInfoNames() Get the set of GmsRtViewDsConnInfo names for this datasource.
java.util.Collection	getConnInfos() Get the collection of GmsRtViewDsConnInfo objects for this datasource.
GmsRtViewDataObject	getDataObjectByKey(java.lang.String key) Get the GmsRtViewDataObject with the specified name.
java.util.List	getDataObjects() Get a List of all currently active GmsRtViewDataObjects.
java.util.Vector	getDsFileNames() Returns the Vector containing names of jars, dlls or other application files needed for this data source.
GmsRtViewDsOptions	getDsOptions() Get the GmsRtViewDsOptions object for this datasource.
java.lang.String	getLoginPassword() Get the login password for RTView.
java.lang.String	getLoginUserName() Get the login user name for RTView.
GmsTabularData	getStoredDataTable(java.lang.String dataKey) Retrieve a data table from the datasource, using the given key.
protected abstract void	initConnInfoExemplar(GmsRtViewDsConnInfo exemplar) Define the fields available in the conn infos used by this datasource.
protected abstract void	initDataObjectExemplar(GmsRtViewDataObject exemplar) Define the fields available in the data objects used by this datasource.
protected abstract void	initDsBaseProperties(GmsRtViewDsBaseProperties properties) Initialize the base properties associated with this datasource.
protected abstract void	initDsControlProperties(GmsRtViewDsControlProperties properties) Initialize the control properties associated with this datasource.
protected abstract void	initDsOptionsExemplar(GmsRtViewDsOptions exemplar) Define the fields available in the ds options used by this datasource.
protected void	removeConnection(GmsRtViewDsConnInfo connInfo) This is called to remove a connection.
void	storeData(GmsRtViewDataObject dataObj, GmsTabularData table) Store a table in the data object.
void	storeData(GmsRtViewDataObject dataObj, GmsTabularData table, java.lang.String[] indexColumnValues) Store a table in the data object, adding the specified index values.
void	storeData(GmsRtViewDataObject dataObj, GmsTabularData table, java.lang.String[] indexColumnValues, boolean replaceByIndex) Store a table in the data object, adding the specified index values.
void	storeData(java.lang.String dataKey, GmsTabularData table) Store a table in all data objects that match the data key.
void	storeData(java.lang.String dataKey, GmsTabularData table, java.lang.String[] indexColumnValues) Store a table in all data objects that match the data key, adding the specified index values.
void	storeData(java.lang.String dataKey, GmsTabularData table, java.lang.String[] indexColumnValues, boolean replaceByIndex) Store a table in all data objects that match the data key, adding the specified index values.

Methods inherited from class com.sl.gmsjrtview.GmsRtViewDs

addListener, applyData, applyDataField, dc, ec, escapeSingleQuotes, exec_command, executeCommand, executeCommand, executeCommand, fixDsStringForVersion, getAlertClassNames, getAttachDataDialogName, getCacheClassNames, getDataObject, getDefineCommandDialogName, getDsAttribute, getDsDescription, getDsKey, getObjectNames, getOptionFileName, getOptionTabClassName, getRowNameSubs, getStringPool, getTableSubs, initializeData, isDataServer, isGlobalPanel, loginPassthroughActive, makeTokenizer, nextString, nextString, nextString, parseOptionString, processAppletParameters, processMainArgument, removeEscapeOnQuotes, removeListener, saveOption, saveOptionString, setDsAttribute, setupGraph, standbyModeChanged, startData, synchData, terminateData, updateData, updateData, updateGraphsData

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.util.Comparator

compare, equals

Field Detail

ALL_UPDATE_MODES

public static final java.util.Set ALL_UPDATE_MODES

Convenience to enable all update modes

DEFAULT_UPDATE_MODES

public static final java.util.Set DEFAULT_UPDATE_MODES

Update modes enabled by default

NO_UPDATE_MODES

public static final java.util.Set NO_UPDATE_MODES

Convenience to disable all update modes

Constructor Detail

GmsRtViewDs

public GmsRtViewDs()

Construct a GmsRtViewDs.

Method Detail

addConnection

protected void addConnection(GmsRtViewDsConnInfo connInfo)

This is called from the command line, applet params, options file and options dialog to add a new or modified connInfo. If this is the first connection added, the default connection is also set. A subclass may override this method to perform validation on the connInfo object before adding the connection.

Parameters:

connInfo - the GmsRtViewDsConnInfo to add

buildDataKey

public java.lang.String buildDataKey(GmsRtViewDataObject dataObject)

Construct the data key for a data object, using the current values of the data key fields.

Returns:

the data key

buildDataKey

public java.lang.String buildDataKey(java.lang.String[] values)

Construct a data key given an array of values. The number of values should match the number of data key fields defined on the data object exemplar.

Parameters:

values - the values of each of the data key fields

Returns:

the data key

closeConnection

public void closeConnection(GmsRtViewDsConnInfo connInfo)

Close a connection.

Parameters:

connInfo - the connection to close

getConnInfoFromName

public GmsRtViewDsConnInfo getConnInfoFromName(java.lang.String name)

Get the GmsRtViewDsConnInfo with the given name.

Returns:

the GmsRtViewDsConnInfo object

getConnInfoNames

public java.util.Set getConnInfoNames()

Get the set of GmsRtViewDsConnInfo names for this datasource.

Returns:

Set of GmsRtViewDsConnInfo names

getConnInfos

public java.util.Collection getConnInfos()

Get the collection of GmsRtViewDsConnInfo objects for this datasource.

Returns:

collection of GmsRtViewDsConnInfo objects

getDataObjectByKey

public GmsRtViewDataObject getDataObjectByKey(java.lang.String key)

Get the GmsRtViewDataObject with the specified name.

Leading and trailing whitespace are removed from the name before searching for the data object. If the name begins with the datasource key, the key is removed from the name before searching for the data object.

This method will return null if there is no GmsRtViewDataObject with the specified name.

This method will also return null if the datasource key returned from the method getDsKey() is null or empty.

Parameters:

key - the name of the GmsRtViewDataObject

Returns:

the data object

getDataObjects

public java.util.List getDataObjects()

Get a List of all currently active GmsRtViewDataObjects.

Returns:

List of all active data objects

getDsFileNames

public java.util.Vector getDsFileNames()

Returns the Vector containing names of jars, dlls or other application files needed for this data source. Only files included the RTView distribution should be in the returned Vector. All files must have a path relative to (and within)RTV_HOME. Forward slash (/) should be used for all path separators. If the file is listed that is in a subdirectory other than /bin or /lib, the directory must be included in the Vector before any files from that directory are included.

This method is called from the Deployment Wizard to package up the correct files for this data source. If the data source returns null, no files will be included in the generated deployment for this data source.

Specified by:

getDsFileNames in class com.sl.gmsjrtview.GmsRtViewDs

Returns:

the Vector of file names

getDsOptions

public GmsRtViewDsOptions getDsOptions()

Get the GmsRtViewDsOptions object for this datasource.

Returns:

the ds options object

getLoginPassword

public java.lang.String getLoginPassword()

Get the login password for RTView. This returns null if RTView application logon is not used

Returns:

the login password

getLoginUserName

public java.lang.String getLoginUserName()

Get the login user name for RTView. This returns null if RTView application logon is not used

Returns:

the login user name

getStoredDataTable

public GmsTabularData getStoredDataTable(java.lang.String dataKey)

Retrieve a data table from the datasource, using the given key.

Parameters:

dataKey - the name of the table to retrieve

Returns:

the data table

initConnInfoExemplar

protected abstract void initConnInfoExemplar(GmsRtViewDsConnInfo exemplar)

Define the fields available in the conn infos used by this datasource.

Parameters:

exemplar - the conn info exemplar for this datasource

initDataObjectExemplar

protected abstract void initDataObjectExemplar(GmsRtViewDataObject exemplar)

Define the fields available in the data objects used by this datasource.

Parameters:

exemplar - the data object exemplar for this datasource

initDsBaseProperties

protected abstract void initDsBaseProperties(GmsRtViewDsBaseProperties properties)

Initialize the base properties associated with this datasource. All subclasses must implement this method to set the values of the GmsRtViewDsBaseProperties for this datasource. This method is called from the base class constructor.

Parameters:

properties - the datasource base properties

initDsControlProperties

protected abstract void initDsControlProperties(GmsRtViewDsControlProperties properties)

Initialize the control properties associated with this datasource. All subclasses must implement this method to set the values of the GmsRtViewDsControlProperties for this datasource. This method is called at the start of the initializeData method in the base class.

Parameters:

properties - the datasource control properties

initDsOptionsExemplar

protected abstract void initDsOptionsExemplar(GmsRtViewDsOptions exemplar)

Define the fields available in the ds options used by this datasource.

Parameters:

exemplar - the ds options exemplar for this datasource

removeConnection

protected void removeConnection(GmsRtViewDsConnInfo connInfo)

This is called to remove a connection. User application may override if it requires custom validation, etc.

Parameters:

connInfo - the GmsRtViewDsConnInfo to remove

storeData

public void storeData(GmsRtViewDataObject dataObj,
                      GmsTabularData table)

Store a table in the data object.

Parameters:

dataObj - the data object

table - the table to store

storeData

public void storeData(GmsRtViewDataObject dataObj,
                      GmsTabularData table,
                      java.lang.String[] indexColumnValues)

Store a table in the data object, adding the specified index values. Note that this method does not use the specified index values to replace previously stored data. All data previously stored in the table is overwritten.

Parameters:

dataObj - the data object

table - the table to store

indexColumnValues - the values to store in the index columns

storeData

public void storeData(GmsRtViewDataObject dataObj,
                      GmsTabularData table,
                      java.lang.String[] indexColumnValues,
                      boolean replaceByIndex)

Store a table in the data object, adding the specified index values. If the replaceByIndex parameter is set to true, previously stored data for the specified index values is replaced with new data, while data for other index values is left unchanged. If the replaceByIndex parameter is set to false, all previously stored data in the table is overwritten.

Parameters:

dataObj - the data object

table - the table to store

indexColumnValues - the values to store in the index columns

replaceByIndex - should the indexColumnValues be used to replace previously-stored data

storeData

public void storeData(java.lang.String dataKey,
                      GmsTabularData table)

Store a table in all data objects that match the data key.

Parameters:

dataKey - the key to locate the data objects

table - the table to store

storeData

public void storeData(java.lang.String dataKey,
                      GmsTabularData table,
                      java.lang.String[] indexColumnValues)

Store a table in all data objects that match the data key, adding the specified index values. Note that this method does not use the specified index values to replace previously stored data. All data previously stored in the table is overwritten.

Parameters:

dataKey - the key to locate the data objects

table - the table to store

indexColumnValues - the values to store in the index columns

storeData

public void storeData(java.lang.String dataKey,
                      GmsTabularData table,
                      java.lang.String[] indexColumnValues,
                      boolean replaceByIndex)

Store a table in all data objects that match the data key, adding the specified index values. If the replaceByIndex parameter is set to true, previously stored data for the specified index values is replaced with new data, while data for other index values is left unchanged. If the replaceByIndex parameter is set to false, all previously stored data in the table is overwritten.

Parameters:

dataKey - the key to locate the data objects

table - the table to store

indexColumnValues - the values to store in the index columns

replaceByIndex - should the indexColumnValues be used to replace previously stored data