## com.rbnb.sapi
Class Source

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

All Implemented Interfaces:
  Serializable

    public class Source

extends Client

A simple data source for RBNB servers. This class is designed to present a simple interface for sourcing data to RBNB servers, via the RMap API.

A data source client has the following tasks:

1. Create a `ChannelMap` object.
2. Define channels by name, via `ChannelMap.Add(java.lang.String)`.
3. Set a TimeStamp, using `ChannelMap.PutTime(double,double)` or `ChannelMap.PutTimeAuto(java.lang.String)`.
4. Add data for each channel, through the various PutChannel methods, such as `ChannelMap.PutData(int,byte[],int)`.
5. `Flush(ChannelMap)` data to RBNB server.

Steps 2 - 4 may be repeated as desired. Also note that the time may be set for the entire frame, that is only once per Flush() before any calls to PutData(); for each channel, that is once per PutData(); or for individual data blocks, where PutTime & PutData() are called multiple times per frame on the same channel.

Use `Register(ChannelMap)` to publicize channels in advance of sending them to the RBNB server.

Note: Multi-channel ChannelMaps must remain consistent (same number and names) from one flush to another for the life of the data source. This is because consistent sets of channels are written to unique ring-buffers in the server, which for efficiency are restricted to contain a consistent set of channels across all frames stored in each such ring-buffer.

Since:
  V2.0
See Also:
  Serialized Form
Author:
  WHF
Version:
  2004/01/08

Constructor Summary
`Source()` Default constructor.
`Source(int cacheSize, String archiveMode, int archiveSize)` A convenience constructor which initializes values for the cache size, archive mode, and archive size.

Method Summary
`long` `BytesTransferred()` Reports the total number of bytes read and written by this Client.
`void` `ClearCache()` Flushes any data currently in the Ring Buffer cache into the disk archive.
`ChannelMap` `Delete(ChannelMap toDelete)` Calls `Delete(ChannelMap, ChannelMap)` with null for the result parameter.
`ChannelMap` `Delete(ChannelMap toDelete, ChannelMap result)` Deletes the maps specified in toDelete.
`void` `Detach()` Close the connection with the server, but retain the server-side handler and its ring buffer(s) such that sink clients can continue to access previously written data.
`int` `Flush(ChannelMap ch)` Sends the pending channels to the server, unsynchronized.
`int` `Flush(ChannelMap ch, boolean doSynch)` Sends the pending channels to the server, optionally waiting for confirmation before returning.
`void` `Register(ChannelMap cm)` Tells the server which channels this `Source` will generate.

Methods inherited from class com.rbnb.sapi.Client
`CloseRBNBConnection, CloseRBNBConnection, GetArchiveMode, GetArchiveSize, GetCacheSize, GetChannelList, GetChannelList, GetClientName, GetServerName, OpenRBNBConnection, OpenRBNBConnection, OpenRBNBConnection, SetRingBuffer, VerifyConnection`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### Source

    public Source()

  Default constructor. Initializes default values of the parameters:
  - `cacheSize` = 100 frames
  - `archiveSize` = 0 frames (off)

  Since:
    V2.0
  Author:
    WHF
  Version:
    05/17/2001

### Source

    public Source(int cacheSize,
                  String archiveMode,
                  int archiveSize)

  A convenience constructor which initializes values for the cache size, archive mode, and archive size. Calls `Client.SetRingBuffer(int, String, int)` with the specified options.

  Parameters:
    `cacheSize` - Size of the memory cache, in frames.
    `archiveMode` - The mode for the optional archive. Should be one of the following:
    - "none" - no Archive is made.
    - "load" - load an archive, but do not allow any further writing to it.
    - "create" - create an archive.
    - "append" - load an archive, but allow writing new data to it.
    `archiveSize` - The size of the desired archive, in frames. Ignored except for "create" and "append".
  Since:
    V2.0
  See Also:
    `Client.CloseRBNBConnection()`, `Client.SetRingBuffer(int,String,int)`
  Author:
    WHF
  Version:
    06/04/2001

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.

### Flush

    public int Flush(ChannelMap ch)
              throws SAPIException

  Sends the pending channels to the server, unsynchronized. Calls `Flush(ChannelMap,boolean)` with a false value for the synchronization 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(ChannelMap,boolean)`
  Author:
    WHF
  Version:
    05/17/2001

### Flush

    public int Flush(ChannelMap ch,
                     boolean doSynch)
              throws SAPIException

  Sends the pending channels to the server, optionally waiting for confirmation before returning. The data and times in the provided `ChannelMap` are erased after they are sent, although the names are preserved.

  Parameters:
    `doSynch` - If true, this Source will communicate with the server to verify that the communication was successful.
  Returns:
    The number of channels flushed.
  Throws:
    `SAPIException` - If there is an error while sending data to the server.
  Since:
    V2.0
  Author:
    WHF
  Version:
    05/17/2001

### Register

    public void Register(ChannelMap cm)
                  throws SAPIException

  Tells the server which channels this `Source` will generate. It also sends any data present in the `ChannelMap` as time-independent meta-data.

  NOTE: It is strongly recommended that the data placed into the ChannelMap used with Register be placed with `ChannelMap.PutUserInfo(int, String)`. This allows the server to combine this data with its server generated meta-data. Otherwise the server generated data is overridden.

  Throws:
    `SAPIException` - If there is an error while sending the map to the server.
  Since:
    V2.0
  Author:
    WHF
  Version:
    01/31/2002

### Delete

    public ChannelMap Delete(ChannelMap toDelete,
                             ChannelMap result)
                      throws SAPIException

  Deletes the maps specified in toDelete. The results of the deletion, as determined by the server, are placed in result, which is returned.

  If result is null, a new channel map is created.

  Throws:
    `SAPIException`

### Delete

    public ChannelMap Delete(ChannelMap toDelete)
                      throws SAPIException

  Calls `Delete(ChannelMap, ChannelMap)` with null for the result parameter.

  Throws:
    `SAPIException`

### ClearCache

    public void ClearCache()
                    throws SAPIException

  Flushes any data currently in the Ring Buffer cache into the disk archive. If there is no archive, the data is discarded.

  Throws:
    `SAPIException`

### Detach

    public final void Detach()

  Close the connection with the server, but retain the server-side handler and its ring buffer(s) such that sink clients can continue to access previously written data.

  If you wish to close the connection and prevent access to the data at the server, use `Client.CloseRBNBConnection()`.

  A new client can reattach to the detached server-side handler by using the following calls:

  `Source src = new Source(cacheSize,"append",archiveSize)`
  `src.OpenRBNBConnection(rbnbAddress,clientName)`

  Note: while it is possible to `Detach` from a `Source` that does not have an archive, it is not possible at this time to reattach to it.

  Since:
    V2.0
  See Also:
    `Client.OpenRBNBConnection(String,String)`, `Client.CloseRBNBConnection()`
  Author:
    WHF
  Version:
    2004/02/16