com.rbnb.sapi
Class PlugIn

java.lang.Object
  com.rbnb.sapi.Client
      com.rbnb.sapi.PlugIn

All Implemented Interfaces:

Serializable

public class PlugIn
extends Client

A simple PlugIn for RBNB servers.

NOTE: it is not recommended that this class be used directly. Instead consider subclassing PlugInTemplate for a more streamlined plug-in development.

This class is designed to present a simple interface for generating data to match requests.

A plug-in client has the following tasks:

1. Build the list of channels to which this PlugIn responds with ChannelMap.Add(String) and Register(ChannelMap). This step may be omitted, in which case all channels which request from this PlugIn's name will be forwarded by the server.
2. Fetch(long,PlugInChannelMap) requests from the RBNB server.
3. The PlugInChannelMap will be filled with the channels requested by the client, as well as the request mode and time range. These can be determined using PlugInChannelMap.GetRequestStart(), PlugInChannelMap.GetRequestDuration(), and PlugInChannelMap.GetRequestReference(). This last method may return "regsitration", in which case the registered channels should be returned, with any matching meta-data.
4. By default, the time-range requested will be used for the output, although this may be overridden by PutTime(). Push data into the map to fullfill the request using the PutData() methods.
5. When all channels have been set, Flush(PlugInChannelMap) the response to the server.
6. Reat steps 2 through 4 indefinitely. For some applications, it will be necessary to spawn a new thread in step 2 to handle each new request. It should NOT be necessary to synchronize on the PlugIn object, as it can Fetch and Flush simultaneously; however, a new PlugInChannelMap object should be created before returning to step 2.

Since:

V2.0

See Also:

Serialized Form

Author:

WHF

Version:

2006/11/09

Constructor Summary

PlugIn()
Default constructor.

Method Summary

long	BytesTransferred() Reports the total number of bytes read and written by this Client.
PlugInChannelMap	Fetch(long blockTimeout) Queries the server to see if any requests have been made of this PlugIn.
PlugInChannelMap	Fetch(long blockTimeout, PlugInChannelMap picm) Queries the server to see if any requests have been made of this PlugIn.
int	Flush(PlugInChannelMap ch) Sends the pending channels to the server, as single-response (non-streaming).
int	Flush(PlugInChannelMap ch, boolean doStream) Deprecated. PlugIns no longer receive streaming requests directly, so it is no longer necessary to call this method with true.
void	Register(ChannelMap cm) Tells the server which channels this PlugIn answers to.
void	SetRingBuffer(int cache, String mode, int archive) This operation is not supported in PlugIns.

Methods inherited from class com.rbnb.sapi.Client

CloseRBNBConnection, CloseRBNBConnection, GetArchiveMode, GetArchiveSize, GetCacheSize, GetChannelList, GetChannelList, GetClientName, GetServerName, OpenRBNBConnection, OpenRBNBConnection, OpenRBNBConnection, VerifyConnection

Methods inherited from class java.lang.Object

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

Constructor Detail

PlugIn

public PlugIn()

Default constructor.

Since:

V2.0

Author:

WHF

Version:

01/30/2002

Method Detail

BytesTransferred

public long BytesTransferred()

Description copied from class: Client

Reports the total number of bytes read and written by this Client.

Specified by:

BytesTransferred in class Client

Returns:

The total number of bytes read and written.

Fetch

public final PlugInChannelMap Fetch(long blockTimeout,
                                    PlugInChannelMap picm)
                             throws SAPIException

Queries the server to see if any requests have been made of this PlugIn. If so, the channel names will be placed in the provided (or a newly created) PlugInChannelMap object.

PutTime() is called internally on the ChannelMap in this function with the start and duration specified in the request. This may be overridden with successive calls to PutTime().

Parameters:

picm - The ChannelMap object which is filled with the data received from the server. If this parameter is null, a new ChannelMap is created.

blockTimeout - The amount of time (ms) to wait for data to become available. Use 0 for no delay or any negative number for an infinite delay.

Returns:

The PlugInChannelMap provided, or a newly created one.

Throws:

SAPIException - If there are problems obtaining data from the server.

Since:

V2.0

See Also:

PlugInChannelMap, ChannelMap.PutTime(double,double)

Author:

WHF

Version:

01/30/2002

Fetch

public final PlugInChannelMap Fetch(long blockTimeout)
                             throws SAPIException

Queries the server to see if any requests have been made of this PlugIn. The channel names are placed in a newly created PlugInChannelMap object.

Calls Fetch(long,null).

Throws:

SAPIException

See Also:

Fetch(long, PlugInChannelMap)

Flush

public int Flush(PlugInChannelMap ch,
                 boolean doStream)
          throws SAPIException

Deprecated. PlugIns no longer receive streaming requests directly, so it is no longer necessary to call this method with true.

Sends the pending channels to the server, optionally waiting for confirmation before returning.

Note: This version replaces the old doSynch flag with the doStream flag. Synchronization was not recommended for plug-ins, so this new function was substituted in its place. Behavior for a false value of this flag is the same as before.

Parameters:

ch - The plugin channelmap to send

doStream - If true, does not wrap response with EOS (end of stream), i.e. multi-part streaming response is being provided.

Returns:

The number of channels that PutData was called on, between this Flush() and the previous one.

Throws:

SAPIException - If there is an error while sending data to the server.

Since:

V2.0

Author:

WHF

Version:

01/30/2002

Flush

public int Flush(PlugInChannelMap ch)
          throws SAPIException

Sends the pending channels to the server, as single-response (non-streaming). Calls Flush(PlugInChannelMap,boolean) with a false value for the streaming parameter.

Returns:

The number of channels flushed.

Throws:

SAPIException - If there is an error while sending data to the server.

Since:

V2.0

See Also:

Flush(PlugInChannelMap,boolean)

Author:

WHF

Version:

01/30/2002

Register

public void Register(ChannelMap cm)
              throws SAPIException

Tells the server which channels this PlugIn answers to. If this method is omitted, the server will forward any channel that identifies this PlugIn as its source.

For example, for a PlugIn called "MyPlugIn", if Register is called with a channel "MyChannel", only the channel "MyPlugIn/MyChannel" will be passed through. If Register is not called, any channel that begins with "MyPlugIn/" will be forwarded to the PlugIn.

Any data which is present in the ChannelMap will be passed to the server as time-independent meta-data.

Throws:

SAPIException - If there is an error while sending the map to the server.

Since:

V2.0

Author:

WHF

Version:

01/31/2002

SetRingBuffer

public void SetRingBuffer(int cache,
                          String mode,
                          int archive)

This operation is not supported in PlugIns.

Overrides:

SetRingBuffer in class Client

Throws:

UnsupportedOperationException - Not supported.

Author:

WHF