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