com.rbnb.sapi.Client
com.rbnb.sapi.Sink
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
java.lang.Object
public class Sink
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:
ChannelMap.Add(String). Subscribe(ChannelMap),
Monitor(ChannelMap,int),
or Request(ChannelMap,double,double,String timeRef).Fetch(long,ChannelMap) data from RBNB server. ChannelMap.GetData(int).
| 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 |
|---|
public Sink()
cacheSize = 1 framearchiveSize = 0 frames (off)
public Sink(int cacheSize,
String archiveMode,
int archiveSize)
Sink() instead, since caching
and archiving of requests is not supported by the server.
(int, String, int) with the specified options.
cacheSize - Size of the memory cache, in frames.archiveMode - The mode for the optional archive. Should be one of the
following: archiveSize - The size of the desired archive, in frames. Ignored except for
"create" and "append".Client.CloseRBNBConnection(),
Client.SetRingBuffer(int,String,int)| Method Detail |
|---|
public long BytesTransferred()
Client
BytesTransferred in class Client
public final void Request(ChannelMap cm,
double start,
double duration,
String timeRef,
int repeatCount,
double repeatInterval,
boolean fetchByFrame)
throws SAPIException
Request(ChannelMap,double,double,
String) instead.
Fetch().
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.
IllegalStateException - If not connected.
IllegalArgumentException - If any parameters are illegal.
SAPIExceptionFetch(long,ChannelMap)
public final void Request(ChannelMap cm,
double start,
double duration,
String timeRef,
boolean fetchByFrame)
throws SAPIException
Request(ChannelMap,double,double,String).
This method is only here for binary compatibility; calling it throws
a SAPIException.
SAPIException
public final void Request(ChannelMap cm,
double start,
double duration,
String reference)
throws SAPIException
Fetch().
The reference parameter determines the
origin of the start parameter, and must be one of the
following:
start
time, it will be taken from before the start time.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:
There are two wildcards:
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:
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:
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 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:
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:
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.
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.
SAPIException - If not connected.
IllegalArgumentException - If any parameters are illegal.Fetch(long,ChannelMap),
RequestRegistration(ChannelMap)
public final void Request(ChannelMap cm,
double start,
double duration,
String reference,
RequestOptions ro)
throws SAPIException
RequestOptions object to the server
before making the request.
SAPIExceptionRequest(ChannelMap,double,double,String)
public final void RequestRegistration()
throws SAPIException
Delegates to RequestRegistration(ChannelMap) with
a null parameter.
SAPIException
public final void RequestRegistration(ChannelMap requestMap)
throws SAPIException
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:
To request registration maps from local and routed servers, use a requestMap
with one channel named as follows:
Similarly, targeted requests could also be made using absolute paths, such as:
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:
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.
requestMap - The channels to obtain from the registration map,
or a null or empty ChannelMap to obtain all.
SAPIException - If not connected to a server or there
is a problem with the connection.Fetch(long,ChannelMap)
public final void Monitor(ChannelMap cm,
int gapControl)
throws SAPIException
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.
gapControl - Identifies the number of frames sent without gaps
before a gap may be inserted to resynchronize this sink's output
with the source.
IllegalArgumentException - If gapControl < 0.
SAPIException - If not connected or no channels have been
specified.Fetch(long,ChannelMap),
Subscribe(ChannelMap)
public final void Subscribe(ChannelMap cm)
throws SAPIException
Subscribe(ChannelMap, String) with
"newest" as the time reference.
SAPIException - If not connected or no channels have
been specified.Fetch(long,ChannelMap)
public final void Subscribe(ChannelMap cm,
String timeReference)
throws SAPIException
Subscribe(ChannelMap,double,double,String) instead.
Subscription from oldest by frames can have problems reading from compressed archives.
Fetch().
timeReference - One of "newest" or "oldest".
SAPIException - If not connected or no channels have been
specified.
NullPointerException - If timeReference is null.
IllegalArgumentException - If timeReference is illegal.Fetch(long,ChannelMap)
public final void Subscribe(ChannelMap channelMap,
String timeReference,
double duration)
throws SAPIException
Subscribe(ChannelMap,double,double,String) instead. A start time
of zero provides the functionality of this method for "newest" and
"oldest" start times.
Fetch(). Each block retrieved
by Fetch will be duration time units in length.
channelMap - ChannelMap of desired channels.timeReference - One of "newest" or "oldest".duration - The number of time units of data for each Fetch().
SAPIException - If not connected or no channels have been
specified.
NullPointerException - If timeReference is null.
IllegalArgumentException - If timeReference is illegal.Fetch(long,ChannelMap)
public final void Subscribe(ChannelMap channelMap,
double startTime,
double duration,
String timeReference)
throws SAPIException
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 Requests, 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.
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".
SAPIException - If not connected or no channels have been
specified.
NullPointerException - If timeReference is null.
IllegalArgumentException - If timeReference is illegal.Fetch(long,ChannelMap),
Request(ChannelMap,double,double,String)
public final ChannelMap Fetch(long blockTimeout,
ChannelMap cm)
throws SAPIException
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.
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.
SAPIException - If there are problems obtaining data from
the server.Request(ChannelMap,double,double,String),
Subscribe(ChannelMap),
Monitor(ChannelMap,int),
ChannelMap.GetData(int)
public final ChannelMap Fetch(long blockTimeout)
throws SAPIException
ChannelMap.Add(java.lang.String) and stores them in
a newly created ChannelMap.
Calls Fetch(null,long).
SAPIExceptionFetch(long, ChannelMap)
public final void RequestFrame(ChannelMap cm)
throws SAPIException
Monitor(ChannelMap, int),
except only one response is given.
Note: this is only applicable to new data, as archived data never has new frames.
SAPIException
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||