Class SL4B_AbstractJavaRttpProvider

Object
   |
   +--SL4B_AbstractRttpProvider
         |
         +--SL4B_AbstractJavaRttpProvider

Direct Known Subclasses:

SL4B_AppletRttpProvider

class SL4B_AbstractJavaRttpProvider

extends SL4B_AbstractRttpProvider

Abstract extension of SL4B_AbstractRttpProvider which should be used as the base class for all Java implementations of the interface. It provides standard implementations for the majority of the methods, allowing the sub class to focus primarily on the creation of the applet itself (whether through an applet or an object tag).

Field Detail

const_ALL_FIELDS

<final> String const_ALL_FIELDS

The string that is used to request or discard all fields if the the field list argument is omitted.

See Also:

Constant Field Values

SL4B_AbstractJavaRttpProvider

SL4B_AbstractJavaRttpProvider()

Constructs a SL4B_AbstractJavaRttpProvider.

appletCheckDownloadComplete

void appletCheckDownloadComplete()

Invoked after the GLOBALS.AppletCheckLoaded() method has been called. Since the AppletCheck applet has successfully been loaded, this method cancels the download timeout.

appletCheckDownloadFailed

void appletCheckDownloadFailed()

Invoked if the AppletCheck download timeout period expires before the applet has been loaded. This typically indicates that the client might be behind a firewall that prevents Java (.class) files from being loaded.

blockObjectListeners

void blockObjectListeners(<SL4B_AbstractSubscriber> l_oSubscriber, <String> l_sObjectList)

Stops the specified SL4B_AbstractSubscriber from receiving updates for the specified objects. The Liberator will continue to send the updates, however they are not passed onto the subscriber.

Parameters:
l_oSubscriber - The SL4B_AbstractSubscriber that will have updates to its requested objects blocked.
l_sObjectList - [optional] A space separated list of the names of the RTTP objects to be have their updates blocked. If omitted, all the objects that the SL4B_AbstractSubscriber has subscribed to will have their updates blocked.

clearObjectListeners

void clearObjectListeners(<SL4B_AbstractSubscriber> l_oSubscriber, <int> l_nDiscardTime)

Removes all the subscriptions for the specified SL4B_AbstractSubscriber.

Parameters:
l_oSubscriber - The SL4B_AbstractSubscriber that will have all its object requests discarded.
l_nDiscardTime - [optional] The length of time (in milliseconds) to wait before discarding the subscriptions from the Liberator. If this is omitted, a value of 10000 is used.

connect

void connect()

Invoked when a connection to the Liberator needs to be established. It is the responsibility of the SL4B_AbstractRttpProvider subclass to know when it can safely invoke this method.

Any concrete class that extends SL4B_AbstractRttpProvider must have an implementation for this method.

contribObject

void contribObject(<SL4B_AbstractSubscriber> l_oSubscriber, <String> l_sObjectName, <SL4B_ContributionFieldData> l_oFieldData)

Contributes the specified field name/value data to the RTTP object with the specified name. The specified SL4B_AbstractSubscriber will be informed if the contribution is successful or not.

Parameters:
l_oSubscriber - The SL4B_AbstractSubscriber that will be informed whether the contribution was successful or not.
l_sObjectName - The name of the RTTP object the specified data will be contributed to.
l_oFieldData - The field name/value pair data to be contributed.

Throws:
- SL4B_Exception If the specified contribution field data object is null or empty.

createObject

boolean createObject(<String> l_sObjectName, <String> l_sRttpType)

Attempts to create an RTTP object with the specified name and type on the Liberator.

Parameters:
l_sObjectName - The name of the RTTP object to be created on the Liberator.
l_sRttpType - The type of object to be created. The SL4B_ObjectType singleton defines the possible values.

Returns:
true if the object was successfully created, otherwise false.

debug

void debug(<String> l_sLevelName, <String> l_sMessage)

Adds the specified debug message to the debug log provided the specified level is of equal or higher priority to the current debug level of the RTTP provider (see SL4B_AbstractRttpProvider.setDebugLevel()).

SL4B_DebugLevel defines all the available debug levels.

Parameters:
l_sLevelName - The name of the debug level at which the message should be output to the debug log.
l_sMessage - The message to be output to the debug log.

deleteObject

boolean deleteObject(<String> l_sObjectName)

Attempts to delete the RTTP object with the specified name from the Liberator.

Parameters:
l_sObjectName - The name of the RTTP object to be deleted.

Returns:
true if the object was successfully deleted, otherwise false.

dequeueUpdates

void dequeueUpdates()

Pops the first item from the update queue and invokes the doAllUpdates method on it.

This method is only invoked in Internet Explorer. In Mozilla Firefox the updates are sent directly from the applet to the relevant subscriber without this intermediate step.

disableWTStatsTimeout

void disableWTStatsTimeout(<int> l_nTime)

Disables the WTStats timeout for the specfied period of time. This timeout is one of the mechanisms used to detect connection problems over RTTP. It may be necessary to disable it for a brief period of time if lots of objects are requested simultaneously, since the images for these requests may prevent the WTStats NOOP from being processed until after the timeout period has expired, resulting in an unnecessary reconnection.

Parameters:
l_nTime - The number of milliseconds the WTStats timeout will be disabled for.

getAppletParameterHtml

Object getAppletParameterHtml()

Gets the HTML for the parameters that must be included in the RTTP applet tag in order for it to be configured correctly, according to the configuration that has been specified within the web page.

getFieldNames

String getFieldNames()

Gets a comma separated list of the names of all the fields that are available from the Liberator.

Returns:
A comma separated list of all the fields availalble from the Liberator.

getObject

void getObject(<SL4B_AbstractSubscriber> l_oSubscriber, <String> l_sObjectName, <String> l_sFieldList)

Requests the specified list of fields for the specified RTTP object from the Liberator. Updates for that object will be received by the specified SL4B_AbstractSubscriber.

Parameters:
l_oSubscriber - The SL4B_AbstractSubscriber that will be informed of updates to the specified object.
l_sObjectName - The name of the RTTP object to be requested from the Liberator.
l_sFieldList - [optional] A comma separated list of the fields to be requested for the specified object. If this argument is omitted, all the fields will be requested.

getObjects

void getObjects(<SL4B_AbstractSubscriber> l_oSubscriber, <String> l_sObjectList, <String> l_sFieldList)

Requests the specified list of fields for the specified RTTP objects from the Liberator. Updates for these objects will be received by the specified SL4B_AbstractSubscriber.

Parameters:
l_oSubscriber - The SL4B_AbstractSubscriber that will be informed of updates to the specified objects.
l_sObjectList - A space separated list of the names of the RTTP objects to be requested from the Liberator.
l_sFieldList - [optional] A comma separated list of the fields to be requested for the specified objects. If this argument is omitted, all the fields will be requested.

getObjectType

void getObjectType(<SL4B_AbstractSubscriber> l_oSubscriber, <String> l_sObjectName)

Requests the specified type of the RTTP object from the Liberator. The specified SL4B_AbstractSubscriber will be notified of the objects type.

Parameters:
l_oSubscriber - The SL4B_AbstractSubscriber that will be informed of the specified objects type.
l_sObjectName - The name of the RTTP object to be requested from the Liberator.

getRttpAppletId

String getRttpAppletId()

Gets the idendifier that must be given to the RTTP applet HTML element.

Returns:
The identifier that must be given to the RTTP applet.

getVersion

String getVersion()

Gets the version number of the RTTP provider.

Returns:
The version number for the RTTP provider that is being used.

getVersionInfo

String getVersionInfo()

Gets the full version details of the RTTP provider. This will include its version number and build date and time.

Returns:
The full version information for the RTTP provider that is being used.

login

void login(<String> l_sUsername, <String> l_sPassword)

This method must be invoked by the SL4B_AbstractCredentialsProvider that was responsible for getting the username and password to login to the Liberator. Once the credentials have been validated, the SL4B_SubscriptionManager.ready() method should be invoked.

Parameters:
l_sUsername - The username to use to login to the Liberator.
l_sPassword - The password (or token) to use to login to the Liberator.

logout

void logout()

Logs out of the Liberator. No more updates will be received.

This method is not intended for direct use by end users since it does not handle any other necessary cleanup operations. End users are advised to use the SL4B_AbstractRttpProvider.stop() method instead.

reconnect

void reconnect()

Invoked when a connection to the Liberator is lost and the user wants to attempt a reconnect. It is the responsibility of the SL4B_AbstractRttpProvider subclass to know when it can safely invoke this method.

Any concrete class that extends SL4B_AbstractRttpProvider must have an implementation for this method.

removeObject

void removeObject(<SL4B_AbstractSubscriber> l_oSubscriber, <String> l_sObjectName, <String> l_sFieldList)

Cancels the specified SL4B_AbstractSubscribers subscription for the list of fields for the specified RTTP object. This can be used to discard a subset of the fields that have previously been requested for the object.

Parameters:
l_oSubscriber - The SL4B_AbstractSubscriber that will cease to be informed of updates to the specified object.
l_sObjectName - The name of the RTTP object to be discarded from the Liberator.
l_sFieldList - [optional] A comma separated list of the fields to be discarded for the specified object. If this argument is omitted, all the fields will be discarded.

removeObjects

void removeObjects(<SL4B_AbstractSubscriber> l_oSubscriber, <String> l_sObjectList, <String> l_sFieldList)

Cancels the specified SL4B_AbstractSubscribers subscription for the list of fields for the specified RTTP objects. This can be used to discard a subset of the fields that have previously been requested for these objects.

Parameters:
l_oSubscriber - The SL4B_AbstractSubscriber that will cease to be informed of updates to the specified objects.
l_sObjectList - A space separated list of the names of the RTTP objects to be discarded from the Liberator.
l_sFieldList - [optional] A comma separated list of the fields to be discarded for the specified objects. If this argument is omitted, all the fields will be discarded.

rttpAppletDownloadComplete

void rttpAppletDownloadComplete()

Invoked after the GLOBALS.WTAppletLoaded() method has been called. Since the RTTP applet has successfully been loaded, this method cancels the download timeout. It then gets a reference to the RTTP applet element from the DOM and invokes the SL4B_AbstractJavaRttpProvider.setRttpApplet() method.

rttpAppletDownloadFailed

void rttpAppletDownloadFailed()

Invoked if the RTTP applet download timeout period expires before the applet has been loaded. This typically indicates that the client is either behind a firewall that prevents Java (.jar) files from being loaded, or that they have a very slow connection.

setDebugLevel

boolean setDebugLevel(<String> l_sLevelName)

Sets the level that is used to determine whether or not a debug message is added to the debug log or not.

SL4B_DebugLevel defines all the available debug levels.

Parameters:
l_sLevelName - The name of the debug level to be set.

Returns:
true if the specified level was successfully set, false otherwise.

setGlobalThrottle

void setGlobalThrottle(<String> l_sThrottleLevel)

Sets the throttle level that will be applied to all the objects that the client subscribes to. This level will not be used for objects that have not had their throttle level set specifically, using either SL4B_AbstractRttpProvider.setThrottleObject() or SL4B_AbstractRttpProvider.setThrottleObjects(). To call any of those methods on the AbstractRttpProvider get an instance of it from SL4B_Accessor.getRttpProvider().

SL4B_ThrottleLevel defines all the available throttle levels.

Parameters:
l_sThrottleLevel - The throttle level to be applied to for all requested objects.

Throws:
- SL4B_Exception if l_sThrottleLevel is not a valid throttle level.

setThrottleObject

void setThrottleObject(<String> l_sObjectName, <String> l_sThrottleLevel)

Sets the throttle level for the specified RTTP object.

SL4B_ThrottleLevel defines all the available throttle levels. Call this methods on an instance of AbstractRttpProvider, which you can get from SL4B_Accessor.getRttpProvider().

Parameters:
l_sObjectName - The name of the RTTP object to be throttled.
l_sThrottleLevel - The throttle level to be applied to the specified object.

Throws:
- SL4B_Exception if l_sThrottleLevel is not a valid throttle level.

setThrottleObjects

void setThrottleObjects(<String> l_sObjectList, <String> l_sThrottleLevel)

Sets the throttle level for all of the specified RTTP objects.

SL4B_ThrottleLevel defines all the available throttle levels. Call this methods on an instance of AbstractRttpProvider, which you can get from SL4B_Accessor.getRttpProvider().

Parameters:
l_sObjectList - A space separated list of the names of the RTTP objects to be throttled.
l_sThrottleLevel - The throttle level to be applied to the specified objects.

Throws:
- SL4B_Exception if l_sThrottleLevel is not a valid throttle level.

startAppletCheckTimeout

void startAppletCheckTimeout()

Starts the timeout for the AppletCheck applet. The timeout period is specified by the SL4B_Configuration.getAppletCheckTimeout() method. If the AppletCheck applet fails to load within this period of time the SL4B_AbstractJavaRttpProvider.appletCheckDownloadFailed() method will be invoked.

startRttpAppletTimeout

void startRttpAppletTimeout()

Starts the timeout for the RTTP applet. The timeout period is specified by the SL4B_Configuration.getRttpAppletTimeout() method. If the RTTP applet fails to load within this period of time the SL4B_AbstractJavaRttpProvider.rttpAppletDownloadFailed() method will be invoked.

unblockObjectListeners

void unblockObjectListeners(<SL4B_AbstractSubscriber> l_oSubscriber, <String> l_sObjectList)

Allows the specified SL4B_AbstractSubscriber to start receiving updates for the specified objects which had previously been blocked (see SL4B_AbstractRttpProvider.blockObjectListeners()).

Parameters:
l_oSubscriber - The SL4B_AbstractSubscriber that will have updates to its requested objects unblocked.
l_sObjectList - [optional] A space separated list of the names of the RTTP objects to be have their updates unblocked. If omitted, all the objects that the SL4B_AbstractSubscriber has subscribed to will have their updates unblocked.

urlCheckDownloadFailed

void urlCheckDownloadFailed()

Invoked if the urlcheck.js file cannot be loaded from the Liberator. This typically indicates that an invalid Liberator URL has been specified, or the Liberator is down.

validateFieldList

String validateFieldList(<String> l_sFieldList)

Checks whether the field list has been defined or not, and returns the field list that must be requested from the Liberator accordingly.

Parameters:
l_sFieldList - The list of fields to be requested or discarded.

Returns:
SL4B_AbstractJavaRttpProvider.const_ALL_FIELDS if the specified field list is null or undefined, otherwise it returns l_sFieldList.

writeAppletToDocument

void writeAppletToDocument(<String> l_sAppletHtml)

Writes the specified applet HTML to the document, wrapping it within DIV element to ensure that the applet is not visible within the web page.

Parameters:
l_sAppletHtml - The HTML of the applet to be written out to the document.

WTConnectionError

void WTConnectionError(<String> l_sMessage)

Invoked by the RTTP applet when there is a problem with the connection, such as the connection being lost, or failing to connect. This will invoke the SL4B_AbstractRttpProvider.notifyConnectionListeners() method on a setTimeout (using the C_CallbackQueue singleton) with the relevant arguments.

Parameters:
l_sMessage - A brief description of the connection error.

WTConnectionInfo

void WTConnectionInfo(<String> l_sMessage)

Invoked by the RTTP applet to provide an informational message about the connection to the Liberator. This will invoke the SL4B_AbstractRttpProvider.notifyConnectionListeners() method on a setTimeout (using the C_CallbackQueue singleton) with the relevant arguments.

Parameters:
l_sMessage - An informational message about the connection.

WTConnectionOk

void WTConnectionOk(<String> l_sHostName, <int> l_nConnectionType, <int> l_nTime)

Invoked by the RTTP applet when a connection to the Liberator is established. If this is the first time a connection has been established (i.e. this is not a reconnection), this method will invoke the {SL4B_AbstractJavaRttpProvider#connected} method. It will then invoke the SL4B_AbstractRttpProvider.notifyConnectionListeners() method on a setTimeout (using the C_CallbackQueue singleton) with the relevant arguments.

Parameters:
l_sHostName - The name of the Liberator host machine.
l_nConnectionType - The type of connection that has been established: type 1 (a direct socket connection), type 2 (a tunnelled HTTP(S) connection), or type 3 (a polling refresh connection).
l_nTime - The timestamp associated with the the connection, sent from the Liberator.

WTMessage

void WTMessage(<int> l_nRttpCode, <String> l_sMessage)

Invoked by the RTTP applet when a generic (non source/service) message is received from the Liberator. This method will invoke the SL4B_AbstractRttpProvider.notifyConnectionListeners() method on a setTimeout (using the C_CallbackQueue singleton) with the relevant arguments.

Parameters:
l_nRttpCode - The RTTP code specified for the message.
l_sMessage - The message.

WTReconnect

void WTReconnect()

Invoked by the RTTP applet when it has lost its connection to the Liberator, and its attempts to reconnect have been unsuccessful. This method will invoke the SL4B_AbstractRttpProvider.notifyConnectionListeners() method on a setTimeout (using the C_CallbackQueue singleton) with the relevant arguments.

WTServiceMessage

void WTServiceMessage(<int> l_nRttpCode, <String> l_sServiceId, <String> l_sServiceName, <String> l_sMessage)

Invoked by the RTTP applet when a service message is received from the Liberator. This method will invoke the SL4B_AbstractRttpProvider.notifyConnectionListeners() method on a setTimeout with the relevant arguments.

Parameters:
l_nRttpCode - The RTTP code specified for the service message.
l_sServiceId - The unique identifier for the service.
l_sServiceName - The name of the service.
l_sMessage - A brief message describing the state of the service.

WTSessionEjected

void WTSessionEjected(<int> l_nRttpCode, <String> l_sMessage)

Invoked by the RTTP applet when a session ejected message is received from the Liberator. This method will invoke the SL4B_AbstractRttpProvider.notifyConnectionListeners() method on a setTimeout with the relevant arguments.

Parameters:
l_nRttpCode - The RTTP code specified for the session eject.
l_sMessage - A brief description of why the session was ejected.

WTSourceMessage

void WTSourceMessage(<int> l_nRttpCode, <int> l_nSourceNumber, <String> l_sSourceId, <String> l_sMessage)

Invoked by the RTTP applet when a source message is received from the Liberator. This method will invoke the SL4B_AbstractRttpProvider.notifyConnectionListeners() method on a setTimeout with the relevant arguments.

Parameters:
l_nRttpCode - The RTTP code specified for the source message.
l_nSourceNumber - The unique DataSource number of the source.
l_sSourceId - The name of the source.
l_sMessage - A brief message describing the state of the source.

WTStats

void WTStats(<int> l_nNoopTime, <int> l_nNumItems, <int> l_nTime, <int> l_nBytes, <int> l_nQueueLength)

Invoked periodically by the RTTP applet to provide statistics about the clients connection to the Liberator, and other related information. This method will invoke the SL4B_AbstractRttpProvider.notifyConnectionListeners() method on a setTimeout (using the C_CallbackQueue singleton) with the relevant arguments.

Parameters:
l_nNoopTime - The round trip time taken by the last NOOP that was sent to the Liberator.
l_nNumItems - The number of RTTP objects that the client has subscribed to.
l_nTime - The length of time since the count for the number of bytes that have been read was reset.
l_nBytes - The number of bytes that have been read (since the last time the count was reset).
l_nQueueLength - The number of updates that have been received, but have not been sent onto the relevant subscribers yet.