## com.rbnb.sapi
Class Client

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

All Implemented Interfaces:
  Serializable

Direct Known Subclasses:
  Control, PlugIn, Sink, Source

    public abstract class Client

extends Object
implements Serializable

Base class of all simple clients to RBNB servers. This class encapsulates functionality common to all clients. It is not intended for end-user subclassing.

Since:
  V2.0
See Also:
  Serialized Form
Author:
  WHF
Version:
  03/25/2008

Method Summary
`abstract long` `BytesTransferred()` Reports the total number of bytes read and written by this Client.
`void` `CloseRBNBConnection()` Close the connection with the server, and free up associated resources.
`void` `CloseRBNBConnection(boolean keepCache, boolean keepArchive)` Deprecated. Flags were counter-intuitive and allowed certain impossible requests, such as a deleted archive with a kept cache. Use `CloseRBNBConnection()` and `Source.Detach()` instead.
`String` `GetArchiveMode()` Returns the archive mode used.
`int` `GetArchiveSize()` Returns the number of archive frames used.
`int` `GetCacheSize()` Returns the number of cache frames used.
`String[]` `GetChannelList()` Deprecated. Please use `Sink.RequestRegistration( ChannelMap)` instead.
`String[]` `GetChannelList(String matchStr)` Deprecated. Please use `Sink.RequestRegistration( ChannelMap)` instead.
`String` `GetClientName()` Returns the name of this client.
`String` `GetServerName()` Returns the name of the server to which this client is connected.
`void` `OpenRBNBConnection()` Opens a connection to the server, using default parameters.
`void` `OpenRBNBConnection(String serverAddress, String clientName)` Opens a connection to the server, using some default parameters.
`void` `OpenRBNBConnection(String serverAddress, String clientName, String userName, String password)` Opens a connection to the server.
`void` `SetRingBuffer(int cache, String mode, int archive)` Allows the cache size, archive mode, and archive size to be specified outside of the constructor.
`boolean` `VerifyConnection()` Returns true if the connection to the server is still valid; false, if the connection has been severed.

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

Method Detail

### BytesTransferred

    public abstract long BytesTransferred()

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

  Returns:
    The total number of bytes read and written.
  Since:
    V2.6
  Author:
    EMF
  Version:
    10/25/2005

### SetRingBuffer

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

  Allows the cache size, archive mode, and archive size to be specified outside of the constructor. This is useful for the following purposes:
  - For JavaBean / ActiveX users, who cannot call the constructors which take arguments.
  - To change the cache and archive settings while connected to the server.
  - To delete the cache and archive at the server.

  Note: This method will delete any data which lies in the current cache or archive, and replace it with a new cache or archive of the new size.

  Throws:
    `SAPIException` - If connected to a server when called, and the reset fails.
    `IllegalArgumentException` - If cache is less than one; mode is not one of "none", "load", "create", "append", or "delete"; or if archive size is less than zero (for mode other than null or "none".

### OpenRBNBConnection

    public final void OpenRBNBConnection()
                                  throws SAPIException

  Opens a connection to the server, using default parameters.

  - `serverAddress` = "localhost:3333"
  - `clientName` = "MyClient"
  - `userName` = ""
  - `password` = ""

  Throws:
    `SAPIException` - If there is a problem connecting to the server.
  Since:
    V2.0
  Author:
    WHF
  Version:
    05/17/2001

### OpenRBNBConnection

    public final void OpenRBNBConnection(String serverAddress,
                                         String clientName)
                                  throws SAPIException

  Opens a connection to the server, using some default parameters.

  - `userName` = ""
  - `password` = ""

  Throws:
    `SAPIException` - If there is a problem connecting to the server.
  Since:
    V2.0
  Author:
    WHF
  Version:
    05/17/2001

### OpenRBNBConnection

    public final void OpenRBNBConnection(String serverAddress,
                                         String clientName,
                                         String userName,
                                         String password)
                                  throws SAPIException

  Opens a connection to the server.

  Parameters:
    `serverAddress` - The address of the server to connect to.
    `clientName` - The name used to identify this client on the server.
    `userName` - The name used to log onto the server, if secure.

    The username is transmitted in plain-text. It is not actually used to restrict access.

    `password` - The password associated with the user name.

    This value is transmitted in plain-text. If set, only other clients with the same password will be allowed to access the data.

  Throws:
    `SAPIException` - If there are problems connecting to the server.
    `IllegalArgumentException` - If `clientName` is null, zero-length, or contains slashes.
  Since:
    V2.0
  Author:
    WHF, WHF
  Version:
    04/08/2002

### CloseRBNBConnection

    public final void CloseRBNBConnection()

  Close the connection with the server, and free up associated resources. Any cache on the server will be removed, but any connected archive will be preserved on disk, although the data is no longer available through the server.

  If you have a Source and you wish to close the connection, but allow the data to still be accessed, use `Source.Detach()`.

  Since:
    V2.0
  See Also:
    `Source.Detach()`
  Author:
    WHF
  Version:
    2004/01/08

### CloseRBNBConnection

    public final void CloseRBNBConnection(boolean keepCache,
                                          boolean keepArchive)

  Deprecated. Flags were counter-intuitive and allowed certain impossible requests, such as a deleted archive with a kept cache. Use `CloseRBNBConnection()` and `Source.Detach()` instead.

  Close the connection with the server, and free up associated resources.

  The two parameters keepCache and keepArchive determine the state of data on the server from this source, after the source has disconnected. If `keepCache` is true, the memory cache at the server will be preserved, so that Sinks can request the data even after the Source has closed. If `keepArchive` is true, the disk archive at the server will be preserved. Otherwise it will be deleted from the disk.

  In order to load a stored archive, a Source with the same name as the Source which created the archive must open a connection with the archive option set to "load". See `Source.Source(int, String,int)` and `SetRingBuffer(int,String,int)`.

  Currently the only implemented options are `keepCache = false` , and `keepArchive = true`. That is to say, regardless of the options passed to this function, it is impossible to disconnect a source from the server and leave the cache in the ring buffer, nor is it possible to delete an archive from the server's disk. These features will be implemented in a future release.

  Parameters:
    `keepCache` - If true, the memory cache at the server will be preserved.
    `keepArchive` - If true, the disk archive at the server will be preserved. Otherwise it will be deleted from the disk.
  Since:
    V2.0
  Author:
    WHF
  Version:
    2004/01/08

### GetChannelList

    public final String[] GetChannelList(String matchStr)
                                  throws SAPIException

  Deprecated. Please use `Sink.RequestRegistration( ChannelMap)` instead.

  Obtains the list of channels available at the server. Requires a live connection to the server and a valid match string.

  The wildcard for all channels is "...". The asterisk acts as it does in path names (i.e. not recursively). Therefore, to access all channels of a depth of three on a server you would use: /ServerName/ * / * / *

  Parameters:
    `matchStr` - A string against which the channels are compared to determine if they belong.
  Returns:
    An array of currently available channels.
  Throws:
    `SAPIException` - If not connected to a server or there is a problem with the connection.
  Since:
    V2.0
  Author:
    WHF
  Version:
    05/17/2001

### GetChannelList

    public final String[] GetChannelList()
                                  throws SAPIException

  Deprecated. Please use `Sink.RequestRegistration( ChannelMap)` instead.

  Gets all available channels.

  Throws:
    `SAPIException`
  Version:
    01/18/2002

### GetServerName

    public final String GetServerName()

  Returns the name of the server to which this client is connected. Note that this involves a round-trip to the server to verify the connection.

  Throws:
    `IllegalStateException` - If we are not currently connected to a server.
  Since:
    V2.0
  See Also:
    `OpenRBNBConnection(String, String, String, String)`
  Author:
    WHF
  Version:
    02/05/2002

### VerifyConnection

    public final boolean VerifyConnection()

  Returns true if the connection to the server is still valid; false, if the connection has been severed.

### GetClientName

    public final String GetClientName()

  Returns the name of this client. This may not be identical to the name given to OpenRBNBClient(), as the server will append additional identifiers of the form ".n", where n is the number of clients requesting that name minus one, in the case of duplicate client names.

  Throws:
    `IllegalStateException` - If we are not currently connected to a server.
  Since:
    V2.0
  See Also:
    `OpenRBNBConnection(String, String, String, String)`
  Author:
    WHF
  Version:
    02/05/2002

### GetCacheSize

    public final int GetCacheSize()

  Returns the number of cache frames used.

  Since:
    V2.6B5
  Author:
    WHF
  Version:
    11/13/2006

### GetArchiveSize

    public final int GetArchiveSize()

  Returns the number of archive frames used.

  Since:
    V2.6B5
  Author:
    WHF
  Version:
    11/13/2006

### GetArchiveMode

    public final String GetArchiveMode()

  Returns the archive mode used.

  Since:
    V2.6B5
  Author:
    WHF
  Version:
    11/13/2006