## 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