## com.rbnb.sapi
Class Sink

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

All Implemented Interfaces:
  Serializable

    public class Sink

extends Client

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

A data sink client has the following tasks:

1. Build a channel request with `ChannelMap.Add(String)`.
2. Select a sink mode, using `Subscribe(ChannelMap)`, `Monitor(ChannelMap,int)`, or `Request(ChannelMap,double,double,String timeRef)`.
3. `Fetch(long,ChannelMap)` data from RBNB server.
4. Extract data and time from API buffers, using the various GetData functions, such as `ChannelMap.GetData(int)`.
5. Repeat step 3 as desired for Subscribe and Monitor, or 2 and 3 for Request mode.

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

Constructor Summary
`Sink()` Default constructor.
`Sink(int cacheSize, String archiveMode, int archiveSize)` Deprecated. This constructor calls `Sink()` instead, since caching and archiving of requests is not supported by the server.

Method Summary
`long` `BytesTransferred()` Reports the total number of bytes read and written by this Client.
`ChannelMap` `Fetch(long blockTimeout)` Obtains the data and time values for the set of channels added via `ChannelMap.Add(java.lang.String)` and stores them in a newly created `ChannelMap`.
`ChannelMap` `Fetch(long blockTimeout, ChannelMap cm)` Obtains the data and time values for the set of channels added via `ChannelMap.Add(java.lang.String)` and stores them in the `ChannelMap` you provide.
`void` `Monitor(ChannelMap cm, int gapControl)` Similar to Subscribe, but allows for continuous frames of data without gaps.
`void` `Request(ChannelMap cm, double start, double duration, String reference)` Initiates a request for a specific time slice of data; the data may then be extracted with `Fetch()`.
`void` `Request(ChannelMap cm, double start, double duration, String timeRef, boolean fetchByFrame)` Deprecated. Support for requests by frame has been removed from the API. Please use `Request(ChannelMap,double,double,String)`. This method is only here for binary compatibility; calling it throws a SAPIException.
`void` `Request(ChannelMap cm, double start, double duration, String timeRef, int repeatCount, double repeatInterval, boolean fetchByFrame)` Deprecated. Please use `Request(ChannelMap,double,double, String)` instead.
`void` `Request(ChannelMap cm, double start, double duration, String reference, RequestOptions ro)` Sends the specified `RequestOptions` object to the server before making the request.
`void` `RequestFrame(ChannelMap cm)` Makes a request for the next new frame.
`void` `RequestRegistration()` Sends a request for the current registration map of all channels on the server.
`void` `RequestRegistration(ChannelMap requestMap)` Sends a request to the server for the current registration map for the channels in the provided `ChannelMap`.
`void` `Subscribe(ChannelMap cm)` Makes a subscription for newest data with the server.
`void` `Subscribe(ChannelMap channelMap, double startTime, double duration, String timeReference)` Starts a continuous feed of data on the specified channels to this sink, for retrieval with `Fetch()`.
`void` `Subscribe(ChannelMap cm, String timeReference)` Deprecated. Please use `Subscribe(ChannelMap,double,double,String)` instead. Subscription from oldest by frames can have problems reading from compressed archives.
`void` `Subscribe(ChannelMap channelMap, String timeReference, double duration)` Deprecated. Please use `Subscribe(ChannelMap,double,double,String)` instead. A start time of zero provides the functionality of this method for "newest" and "oldest" start times.

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

### Sink

    public Sink()

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

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

### Sink

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

  Deprecated. This constructor calls `Sink()` instead, since caching and archiving of requests is not supported by the server.

  A convenience constructor which initializes values for the cache size, archive mode, and archive size. Calls `(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.

### Request

    public final void Request(ChannelMap cm,
                              double start,
                              double duration,
                              String timeRef,
                              int repeatCount,
                              double repeatInterval,
                              boolean fetchByFrame)
                       throws SAPIException

  Deprecated. Please use `Request(ChannelMap,double,double, String)` instead.

  Initiates a request for a specific time slice of data. The data may then be extracted with `Fetch()`.

  Parameters:
    `start` - The start time for the request. If `fetchByFrame` is set, this is calculated in frames; otherwise, it is in seconds.
    `duration` - The duration of the request. Again, its unit is seconds unless `fetchByFrame` is set.
    `timeRef` - One of "absolute", "newest", or "oldest". Determines how the start parameter is interpreted.
    `repeatCount` - The number of times the request will be repeated automatically.
    `repeatInterval` - The multiple of duration which is used to advance each repeated request from the start time.
    `fetchByFrame` - If true, the time range is interpreted as frame indices. All frames that match are returned in a consolidated response.
  Throws:
    `IllegalStateException` - If not connected.
    `IllegalArgumentException` - If any parameters are illegal.
    `SAPIException`
  Since:
    V2.0
  See Also:
    `Fetch(long,ChannelMap)`
  Author:
    WHF
  Version:
    01/13/2003

### Request

    public final void Request(ChannelMap cm,
                              double start,
                              double duration,
                              String timeRef,
                              boolean fetchByFrame)
                       throws SAPIException

  Deprecated. Support for requests by frame has been removed from the API. Please use `Request(ChannelMap,double,double,String)`. This method is only here for binary compatibility; calling it throws a SAPIException.

  Throws:
    `SAPIException`

### Request

    public final void Request(ChannelMap cm,
                              double start,
                              double duration,
                              String reference)
                       throws SAPIException

  Initiates a request for a specific time slice of data; the data may then be extracted with `Fetch()`.

  The `reference` parameter determines the origin of the `start` parameter, and must be one of the following:

  - "absolute" -- The start parameter is absolute time from midnight, Jan 1st, 1970 UTC.
  - "newest" -- The start parameter is measured from the most recent data available in the server at the time this request is received. Note that for this case, the start parameter actually represents the end of the duration, and positive times proceed toward oldest data. Thus if there is data at times 1, 2, and 3, Request(map, 1, 0, "newest") will return the data at time 2, while Request(map, -1, 2.5, "newest") will return the data at times 2 and 3.
  - "oldest" -- As "newest", but relative to the oldest data.
  - "aligned" -- As "newest", but rather than per channel, this is relative to the newest for all of the channels.
  - "after" -- A combination between "absolute" and "newest", this flag causes the server to return the newest data available after the specified start time. Unlike "newest", you do not have to request the data to find out that you already have it. Unlike "absolute", a gap may be inserted in the data to provide you with the freshest data.
  - "modified" -- Similar to "after", but attempts to return a duration's worth of data in a contiguous block. If the data is not available after the `start` time, it will be taken from before the start time.
  - "next" - gets the data that immediately follows the time range specified. This will skip over gaps.
  - "previous" - get the data that immediately preceeds the time range specified. This will skip over gaps.

  If registration and/or meta-data are desired, please use `RequestRegistration(ChannelMap)`. (As a convenience to PlugIn developers, this method will also accept "registration" as a reference, and will pass it through to the RequestRegistration method.

  The amount of data returned is determined by the `duration` parameter. A duration of zero represents a special case, where one single point is returned. For the "newest", "oldest", and "absolute" time references, if an exact time match does not occur the point closest to the desired time in the direction of the origin is returned.

  The way channel names are matched can be somewhat confusing. There are two primary ways of specifying names:

  1. Absolute names start with a leading slash, while
  2. Relative names do not have a leading slash.

  There are two wildcards:

  1. * means match anything within the current server at the current point in the request, and
  2. ... means match anything within the current server from the current point in the request down.

  Additionally, it is possible to move up using a relative request by specifying the name '../'.

  Absolute names are matched by starting at the local server's representation of the root of the server hierarchy (termed a "RoutingMap", indicated by the leading slash). Relative names are matched by starting with the children of the local server.

  Consider the following hierarchy of servers:

    /
      AAA/
        [client handlers for AAA]
        BBB/
          [client handlers for BBB]
          CCC/
            [client handlers for CCC]

  This hierarchy has three servers. The top level server AAA has a child named BBB and a grandchild named CCC. At each level, there may be additional client handlers (for source, sink, and plugin connections).

  Each server has its own routing map hierarchy that contains the part of the above hierarchy known to that server. The hierarchy known to the AAA server, for example, is:

    / - the routing map hierarchy root
      AAA/ - the local server
        [client handlers for AAA]
        BBB/ - representation of the child BBB server

  Note that this only goes down to the child BBB server. AAA has no knowledge of any children of BBB. The BBB server's known hierarchy is:

    / - the routing map hierarchy root
      AAA/ - representation of the parent AAA server
        BBB/ - the local server
          [client handlers for BBB]
          CCC/ - representation of the child CCC server

  The BBB server knows about its parent AAA and its child CCC servers, but not their other children.

  Some example requests and an explanation of how they are matched follows. These examples use the preceeding hierarchy.

  Absolute requests are the simplest to understand because they always produce the same answer, regardless of which server the request is sent to. The difference is in the specifics of how the request is matched. Consider the following three requests:

  1. /AAA/...,
  2. /AAA/BBB/..., and
  3. /AAA/BBB/CCC/...

  Each of these requests asks for the hierarchy known to and starting at a specific server. For example, the request '/AAA/BBB/...' would return the following:

    /
      AAA/
        BBB/
          [client handlers, except for plugins, for BBB and their children
          [plugins for BBB]
          CCC/

  Neither plugins nor child servers of BBB are expanded because this information is not known to the BBB server.

  If this request is sent to the BBB server, it answers the request directly out of its routing map hierarchy. If the request is sent to either the AAA or CCC servers, they will match /AAA/BBB locally and then send the remainder ('...') as a relative request to the BBB server.

  Relative requests depend on which server the request is sent to. They are matched starting with the children of the local server rather than at the top of the routing map. For example, consider the request 'CCC/...'. If this request is sent to the BBB server, it will find the child CCC server as a local child and then send the remainder ('...') to the CCC server as a relative request.

  If, on the other hand, this request is sent to the AAA server, it will fail to match anything because the AAA server does not have a child named CCC.

  Parameters:
    `start` - The start time for the request in seconds.
    `duration` - The duration of the request, in seconds.
    `reference` - One of the options listed above. Determines how the start parameter is interpreted.
  Throws:
    `SAPIException` - If not connected.
    `IllegalArgumentException` - If any parameters are illegal.
  Since:
    V2.0
  See Also:
    `Fetch(long,ChannelMap)`, `RequestRegistration(ChannelMap)`
  Author:
    WHF
  Version:
    08/19/2004

### Request

    public final void Request(ChannelMap cm,
                              double start,
                              double duration,
                              String reference,
                              RequestOptions ro)
                       throws SAPIException

  Sends the specified `RequestOptions` object to the server before making the request.

  Throws:
    `SAPIException`
  Since:
    V2.1B4
  See Also:
    `Request(ChannelMap,double,double,String)`
  Version:
    10/14/2004

### RequestRegistration

    public final void RequestRegistration()
                                   throws SAPIException

  Sends a request for the current registration map of all channels on the server.

  Delegates to `RequestRegistration(ChannelMap)` with a null parameter.

  Throws:
    `SAPIException`
  Author:
    WHF
  Version:
    05/06/2002

### RequestRegistration

    public final void RequestRegistration(ChannelMap requestMap)
                                   throws SAPIException

  Sends a request to the server for the current registration map for the channels in the provided `ChannelMap`. The registration map contains information such as channel names, and the size, time range, and MIME type of channel data. If the input `ChannelMap` is empty or null, it will be treated as if it were a request for "..." (all local channels).

  The result of the request can be obtained using `Fetch(long, ChannelMap)`. The result will also contain the meta-data and time ranges for each requested channel.

  You can use wildcards to match channels. Available wildcards and their meanings are:

  - "*" match all objects at this level
  - "..." match from here down recursively (but not across routing links or PlugIns)
  - ".." up a level

  To request registration maps from local and routed servers, use a `requestMap` with one channel named as follows:

  - Local channels: "..."
  - Parent channels: "../..."
  - Parent and local channels: "../*/..."
  - Local and child channels: "*/..."

  Similarly, targeted requests could also be made using absolute paths, such as:

  - Uncle's children: "/myparent/myuncle/..."

  Note that it is impossible to explicity request the registration of all child servers and plugins with one request. This is by design, as such a request might be infinite. Instead of making large wildcard requests, consider breaking them into one request per branch.

  For example, consider a channel viewer application. To present the initial view, the application might request first "/*", and get:

  - Child (Server)
  - FFT (PlugIn)
  - Data (Source)

  If the user is interested in the channels under the Child server, the application might then request "Child/*". This would reveal the first level of nodes under the child server. This minimal on-demand style of requests minimizes bandwidth and server load and ensures that if an error occurs, it is with the level in question and not some peer.

  Parameters:
    `requestMap` - The channels to obtain from the registration map, or a null or empty ChannelMap to obtain all.
  Throws:
    `SAPIException` - If not connected to a server or there is a problem with the connection.
  Since:
    V2.0
  See Also:
    `Fetch(long,ChannelMap)`
  Author:
    WHF
  Version:
    11/20/2006

### Monitor

    public final void Monitor(ChannelMap cm,
                              int gapControl)
                       throws SAPIException

  Similar to Subscribe, but allows for continuous frames of data without gaps.

  In this mode, the server will attempt to send the most recent data available. If the client cannot maintain synchronicity, the server will omit some frames in an effort to keep the client up to date.

  Note: The gap control feature is currently not implemented.

  Parameters:
    `gapControl` - Identifies the number of frames sent without gaps before a gap may be inserted to resynchronize this sink's output with the source.
  Throws:
    `IllegalArgumentException` - If gapControl < 0.
    `SAPIException` - If not connected or no channels have been specified.
  Since:
    V2.0
  See Also:
    `Fetch(long,ChannelMap)`, `Subscribe(ChannelMap)`
  Author:
    WHF
  Version:
    05/17/2001

### Subscribe

    public final void Subscribe(ChannelMap cm)
                         throws SAPIException

  Makes a subscription for newest data with the server. Effectively calls `Subscribe(ChannelMap, String)` with "newest" as the time reference.

  Throws:
    `SAPIException` - If not connected or no channels have been specified.
  Since:
    V2.0
  See Also:
    `Fetch(long,ChannelMap)`
  Author:
    WHF
  Version:
    06/20/2003

### Subscribe

    public final void Subscribe(ChannelMap cm,
                                String timeReference)
                         throws SAPIException

  Deprecated. Please use `Subscribe(ChannelMap,double,double,String)` instead. Subscription from oldest by frames can have problems reading from compressed archives.

  Starts a continuous feed of data on the specified channels to this sink, for retrieval with `Fetch()`.

  Parameters:
    `timeReference` - One of "newest" or "oldest".
  Throws:
    `SAPIException` - If not connected or no channels have been specified.
    `NullPointerException` - If timeReference is null.
    `IllegalArgumentException` - If timeReference is illegal.
  Since:
    V2.1B4
  See Also:
    `Fetch(long,ChannelMap)`
  Author:
    WHF
  Version:
    08/19/2004

### Subscribe

    public final void Subscribe(ChannelMap channelMap,
                                String timeReference,
                                double duration)
                         throws SAPIException

  Deprecated. Please use `Subscribe(ChannelMap,double,double,String)` instead. A start time of zero provides the functionality of this method for "newest" and "oldest" start times.

  Starts a continuous feed of data on the specified channels to this sink, for retrieval with `Fetch()`. Each block retrieved by Fetch will be `duration` time units in length.

  Parameters:
    `channelMap` - ChannelMap of desired channels.
    `timeReference` - One of "newest" or "oldest".
    `duration` - The number of time units of data for each Fetch().
  Throws:
    `SAPIException` - If not connected or no channels have been specified.
    `NullPointerException` - If timeReference is null.
    `IllegalArgumentException` - If timeReference is illegal.
  Since:
    V2.2B5
  See Also:
    `Fetch(long,ChannelMap)`
  Author:
    WHF
  Version:
    2003/11/10

### Subscribe

    public final void Subscribe(ChannelMap channelMap,
                                double startTime,
                                double duration,
                                String timeReference)
                         throws SAPIException

  Starts a continuous feed of data on the specified channels to this sink, for retrieval with `Fetch()`. Each block retrieved by Fetch will be `duration` time units in length.

  The `Subscribe` method is essentially the same as an infinite series of `Request`s, except that performance and latency are improved. After the first Fetch(), the start time is adjusted automatically as appropriate for the time reference provided.

  Please see `Request(ChannelMap, double, double, String)` for the definition of the time references, and the meaning of the start parameter for each case.

  Parameters:
    `channelMap` - ChannelMap of desired channels.
    `startTime` - the start time of the request.
    `duration` - The number of time units of data for each Fetch().
    `timeReference` - Any of "newest", "oldest", "absolute", "next", or "previous".
  Throws:
    `SAPIException` - If not connected or no channels have been specified.
    `NullPointerException` - If timeReference is null.
    `IllegalArgumentException` - If timeReference is illegal.
  Since:
    V2.2B5
  See Also:
    `Fetch(long,ChannelMap)`, `Request(ChannelMap,double,double,String)`
  Author:
    Ian Brown
  Version:
    2004/19/08

### Fetch

    public final ChannelMap Fetch(long blockTimeout,
                                  ChannelMap cm)
                           throws SAPIException

  Obtains the data and time values for the set of channels added via `ChannelMap.Add(java.lang.String)` and stores them in the `ChannelMap` you provide. This function returns a ChannelMap filled with the channels which matched the request; if none, an empty map is returned. This may be less than the number of calls to Add(), if some channels lack data, or it may be greater, if wildcards were used.

  Parameters:
    `cm` - 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 ChannelMap object provided, or a newly created one.
  Throws:
    `SAPIException` - If there are problems obtaining data from the server.
  Since:
    V2.0
  See Also:
    `Request(ChannelMap,double,double,String)`, `Subscribe(ChannelMap)`, `Monitor(ChannelMap,int)`, `ChannelMap.GetData(int)`
  Author:
    WHF
  Version:
    01/11/2002

### Fetch

    public final ChannelMap Fetch(long blockTimeout)
                           throws SAPIException

  Obtains the data and time values for the set of channels added via `ChannelMap.Add(java.lang.String)` and stores them in a newly created `ChannelMap`.

  Calls `Fetch(null,long)`.

  Throws:
    `SAPIException`
  See Also:
    `Fetch(long, ChannelMap)`

### RequestFrame

    public final void RequestFrame(ChannelMap cm)
                            throws SAPIException

  Makes a request for the next new frame. This is similar to `Monitor(ChannelMap, int)`, except only one response is given.

  Note: this is only applicable to new data, as archived data never has new frames.

  Throws:
    `SAPIException`