com.rbnb.sapi
Class ChannelMap

java.lang.Object
  com.rbnb.sapi.ChannelMap

All Implemented Interfaces:

Serializable

Direct Known Subclasses:

PlugInChannelMap

public class ChannelMap
extends Object
implements Serializable

A class to encapsulate the concept of a list of channels, each of which contains data.

See Also:

Serialized Form

Author:

WHF

Version:

2005/03/31

Nested Class Summary

static class

ChannelMap.ByteOrderEnum Byte order enumerated type.

Field Summary

static ChannelMap.ByteOrderEnum	LOCAL The data is in whichever format is appropriate for this NATIVE machine.
static ChannelMap.ByteOrderEnum	LSB Least significant bytes are first in each point, ala Intel.
static ChannelMap.ByteOrderEnum	MSB Most significant bytes are first in each point, as is the case with many UNIX machines, and Java data on export.
static int	TYPE_BYTEARRAY
static int	TYPE_FLOAT32
static int	TYPE_FLOAT64
static int	TYPE_INT16
static int	TYPE_INT32
static int	TYPE_INT64
static int	TYPE_INT8
static int	TYPE_STRING
static int	TYPE_UNKNOWN
static int	TYPE_USER

Constructor Summary

ChannelMap()
Default constructor.

Method Summary

int	Add(String channelName) Adds a channel (or channels, if a wildcard is used) to the acqusition list.
void	AddFolder(String channelName) Add a folder to this channel map.
void	AddPlugInOption(String channel, String key, String value) Used in request maps, adds an option to configure a PlugIn's response to this request.
void	Clear() Removes all channels from the acquisition list.
String[]	GetChannelList() Convenience function to return the list of channels contained in this ChannelMap.
byte[]	GetData(int index) Determines the type of the data in the array, and then converts it to an array of bytes in local machine order.
Object	GetDataAsArray(int index) Returns the channel data as an untyped Object.
byte[][]	GetDataAsByteArray(int index) Returns the channel data as an array of arrays of bytes.
float[]	GetDataAsFloat32(int index) Returns the channel data as an array of floats.
double[]	GetDataAsFloat64(int index) Returns the channel data as an array of doubles.
short[]	GetDataAsInt16(int index) Returns the channel data as an array of shorts.
int[]	GetDataAsInt32(int index) Returns the channel data as an array of ints.
long[]	GetDataAsInt64(int index) Returns the channel data as an array of longs.
byte[]	GetDataAsInt8(int index) Returns the channel data as an array of bytes.
String[]	GetDataAsString(int index) Returns the channel data as an array of Strings.
String[]	GetFolderList() Returns the list of empty folders contained within this ChannelMap.
boolean	GetIfFetchTimedOut() Returns true if and only if this channel map was returned in reponse to a Fetch() which timed-out.
int	GetIndex(String channelName) Returns the index of a channel which has been added to this map if given its name.
String	GetMime(int index) Returns the MIME type identifier for this channel, if any.
String	GetName(int index) Get the fully qualified channel name from its index in constant time.
String[]	GetNodeList() Deprecated. Please use the ChannelTree class for per-node heirarchy construction and identification.
String[]	GetPlugInList() Deprecated. Please use the ChannelTree class for per-node heirarchy construction and identification.
String[]	GetServerList() Deprecated. Please use the ChannelTree class for per-node heirarchy construction and identification.
String[]	GetSinkList() Deprecated. Please use the ChannelTree class for per-node heirarchy construction and identification.
String[]	GetSourceList() Deprecated. Please use the ChannelTree class for per-node heirarchy construction and identification.
double	GetTimeDuration(int index) Yields the duration of this channel's data.
double[]	GetTimes(int index) Yields the times for each data point for the specified channel.
double	GetTimeStart(int index) Yields the start time of this channel's data.
int	GetType(int index) Returns the type of the data returned by the specified channel.
String	GetUserInfo(int channel) Returns user information for the specified channel, if any is available.
int	NumberOfChannels() Returns the number of channels available in the map.
void	PutData(int channelIndex, byte[] rawData, int typeID) Adds the data given in rawBytes to the channel identified with the specified channel index.
void	PutData(int channelIndex, byte[] rawData, int typeID, ChannelMap.ByteOrderEnum byteOrder) Adds the data given in rawBytes to the channel identified with the specified channel index.
void	PutDataAsByteArray(int channelIndex, byte[] data) Type safe version of PutData().
void	PutDataAsFloat32(int channelIndex, float[] data) Type safe version of PutData().
void	PutDataAsFloat64(int channelIndex, double[] data) Type safe version of PutData().
void	PutDataAsInt16(int channelIndex, short[] data) Type safe version of PutData().
void	PutDataAsInt32(int channelIndex, int[] data) Type safe version of PutData().
void	PutDataAsInt64(int channelIndex, long[] data) Type safe version of PutData().
void	PutDataAsInt8(int channelIndex, byte[] data) Type safe version of PutData().
void	PutDataAsString(int channelIndex, String data) Type safe version of PutData().
void	PutDataRef(int destChannel, ChannelMap sourceMap, int sourceChannel) Transfers a reference of the data in the sourceMap to this map.
void	PutMime(int index, String mime) Specifies the MIME (Multipurpose Internet Mail Extensions) type of this source data.
void	PutTime(double start, double duration) Sets the time range for all data subsequently added to the channel map.
void	PutTimeAuto(String timeMode) Sets the mode for automatic time stamp generation that will be used on the next call to Flush().
void	PutTimeRef(ChannelMap sourceMap, int channelIndex) Copies the time reference for the specified channel on the ChannelMap provided into the current time buffer for this channel.
void	PutTimes(double[] times) Sets the time vector for all data subsequently added to the channel map.
void	PutUserInfo(int channelIndex, String data) Specify user information for a given channel.
int[]	Search(String mimeType, String keywords) Convenience function to search this ChannelMap for the specified keyword and mimeType.
String	toString() Returns a descriptive String about the state of this channel map.
int	TypeID(String type) Determines the numerical constant used as the type ID for the specified data type.
String	TypeName(int typeID) Returns a string type identifier which matches the given typeID.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

LSB

public static final ChannelMap.ByteOrderEnum LSB

Least significant bytes are first in each point, ala Intel.

MSB

public static final ChannelMap.ByteOrderEnum MSB

Most significant bytes are first in each point, as is the case with many UNIX machines, and Java data on export.

LOCAL

public static final ChannelMap.ByteOrderEnum LOCAL

The data is in whichever format is appropriate for this NATIVE machine. Please note that this is not appropriate for Java generated data.

TYPE_FLOAT64

public static final int TYPE_FLOAT64

See Also:

Constant Field Values

TYPE_FLOAT32

public static final int TYPE_FLOAT32

See Also:

Constant Field Values

TYPE_INT64

public static final int TYPE_INT64

See Also:

Constant Field Values

TYPE_INT32

public static final int TYPE_INT32

See Also:

Constant Field Values

TYPE_INT16

public static final int TYPE_INT16

See Also:

Constant Field Values

TYPE_INT8

public static final int TYPE_INT8

See Also:

Constant Field Values

TYPE_STRING

public static final int TYPE_STRING

See Also:

Constant Field Values

TYPE_UNKNOWN

public static final int TYPE_UNKNOWN

See Also:

Constant Field Values

TYPE_BYTEARRAY

public static final int TYPE_BYTEARRAY

See Also:

Constant Field Values

TYPE_USER

public static final int TYPE_USER

See Also:

Constant Field Values

Constructor Detail

ChannelMap

public ChannelMap()

Default constructor.

Method Detail

Add

public final int Add(String channelName)
              throws SAPIException

Adds a channel (or channels, if a wildcard is used) to the acqusition list. Parameter channelName must be fully qualified name of the channel, including the server name.

If the channel is already present, its current index is returned, and no other action is taken.

Note: When making requests of PlugIns, a double slash should be used when signalling the PlugIn to forward or filter an absolute channel. For example, use:

"PlugInTest//Server/rbnbSource/c0"
to filter or forward absolute channel "/Server/rbnbSource/c0". If the slash is omitted, the extra portion of the name will be interpreted as a relative name.

Returns:

The index which refers to this channel.

Throws:

SAPIException - If there is a problem parsing the channel name.

NullPointerException - If the channel name is null.

IllegalArgumentException - If the channel name ends in a slash "/".

Since:

V2.0

See Also:

Clear(), PutData(int,byte[],int,ChannelMap.ByteOrderEnum)

Author:

WHF

Version:

05/17/2001

AddFolder

public final void AddFolder(String channelName)
                     throws SAPIException

Add a folder to this channel map. Useful primarily for registration. The name may end in a slash '/', but this is not required.

Throws:

SAPIException - If there is a problem parsing the channel name.

NullPointerException - If the channel name is null.

Since:

V2.1

See Also:

Source.Register(ChannelMap)

Author:

WHF

AddPlugInOption

public final void AddPlugInOption(String channel,
                                  String key,
                                  String value)
                           throws SAPIException

Used in request maps, adds an option to configure a PlugIn's response to this request.

For example, if you have a ResamplePlugIn running with the name resample and you want to get a maximum of 1200 points from each channel in the request, you would use:

channelMap.AddPlugInOption("resample", "maxSamples", "1200")

If you wanted to then display a plot of the data through an instance of PNGPlugIn called png, with a width of 640 and a height of 480, you would instead use:

channelMap.AddPlugInOption("png/resample", "maxSamples", "1200")

channelMap.AddPlugInOption("png", "width", "640")

channelMap.AddPlugInOption("png", "height", "480")

Parameters:

channel - The fully qualified channel representing the PlugIn to configure.

key - The case-sensitive name of the option to set.

value - The value, a string, of the option to set.

Throws:

SAPIException

Since:

V3.0B4

Author:

WHF

Clear

public final void Clear()

Removes all channels from the acquisition list. Also clears any cached channel memory which may have been retained for efficiency.

Since:

V2.0

See Also:

Add(String)

Author:

WHF

Version:

05/17/2001

GetTimes

public double[] GetTimes(int index)

Yields the times for each data point for the specified channel. A reference to the double array stored in this map is returned, which should not be modified by the end user.

The array returned is calculated only when this method is first called on the channel index. The same array is returned on successive calls.

A zero length array is returned in cases where no time is available for this channel.

Parameters:

index - The channel index.

Returns:

An array of doubles representing the times, or null if no data is available.

Throws:

ArrayIndexOutOfBoundsException - If index out of bounds.

Since:

V2.0

See Also:

GetData(int)

Author:

WHF

Version:

05/17/2001

GetTimeStart

public double GetTimeStart(int index)

Yields the start time of this channel's data. Should only be on the map resulting from a Fetch().

Parameters:

index - The channel index.

Returns:

The start time for this channel's data.

Throws:

ArrayIndexOutOfBoundsException - If index out of bounds.

Since:

V2.0

See Also:

GetData(int), GetTimeDuration(int)

Author:

WHF

Version:

04/15/2002

GetTimeDuration

public double GetTimeDuration(int index)

Yields the duration of this channel's data. Should only be on the map resulting from a Fetch().

Parameters:

index - The channel index.

Returns:

The start time for this channel's data.

Throws:

ArrayIndexOutOfBoundsException - If index out of bounds.

Since:

V2.0

See Also:

GetData(int), GetTimeStart(int)

Author:

WHF

Version:

04/15/2002

GetData

public byte[] GetData(int index)

Determines the type of the data in the array, and then converts it to an array of bytes in local machine order.

Parameters:

index - The channel index.

Returns:

The data as raw bytes.

Throws:

ArrayIndexOutOfBoundsException - If index out of bounds.

Since:

V2.0

See Also:

GetTimes(int)

Author:

WHF

Version:

05/17/2001

GetDataAsFloat64

public double[] GetDataAsFloat64(int index)

Returns the channel data as an array of doubles.

Parameters:

index - The channel index.

Returns:

The data.

Throws:

ArrayIndexOutOfBoundsException - If index out of bounds.

ClassCastException - Channel data is not the correct type.

Since:

V2.0

See Also:

GetData(int)

Author:

WHF

Version:

05/17/2001

GetDataAsFloat32

public float[] GetDataAsFloat32(int index)

Returns the channel data as an array of floats.

Parameters:

index - The channel index.

Returns:

The data.

Throws:

ArrayIndexOutOfBoundsException - If index out of bounds.

ClassCastException - Channel data is not the correct type.

Since:

V2.0

See Also:

GetData(int)

Author:

WHF

Version:

05/17/2001

GetDataAsInt64

public long[] GetDataAsInt64(int index)

Returns the channel data as an array of longs.

Parameters:

index - The channel index.

Returns:

The data.

Throws:

ArrayIndexOutOfBoundsException - If index out of bounds.

ClassCastException - Channel data is not the correct type.

Since:

V2.0

See Also:

GetData(int)

Author:

WHF

Version:

05/17/2001

GetDataAsInt32

public int[] GetDataAsInt32(int index)

Returns the channel data as an array of ints.

Parameters:

index - The channel index.

Returns:

The data.

Throws:

ArrayIndexOutOfBoundsException - If index out of bounds.

ClassCastException - Channel data is not the correct type.

Since:

V2.0

See Also:

GetData(int)

Author:

WHF

Version:

05/17/2001

GetDataAsInt16

public short[] GetDataAsInt16(int index)

Returns the channel data as an array of shorts.

Parameters:

index - The channel index.

Returns:

The data.

Throws:

ArrayIndexOutOfBoundsException - If index out of bounds.

ClassCastException - Channel data is not the correct type.

Since:

V2.0

See Also:

GetData(int)

Author:

WHF

Version:

05/17/2001

GetDataAsInt8

public byte[] GetDataAsInt8(int index)

Returns the channel data as an array of bytes.

Parameters:

index - The channel index.

Returns:

The data.

Throws:

ArrayIndexOutOfBoundsException - If index out of bounds.

ClassCastException - Channel data is not the correct type.

Since:

V2.0

See Also:

GetData(int)

Author:

WHF

Version:

05/17/2001

GetDataAsString

public String[] GetDataAsString(int index)

Returns the channel data as an array of Strings.

Parameters:

index - The channel index.

Returns:

The data.

Throws:

ArrayIndexOutOfBoundsException - If index out of bounds.

ClassCastException - Channel data is not the correct type.

Since:

V2.0

See Also:

GetData(int)

Author:

WHF

Version:

08/31/2001

GetDataAsByteArray

public byte[][] GetDataAsByteArray(int index)

Returns the channel data as an array of arrays of bytes. This is most useful when the data, instead of a time series of bytes (int8), is in fact an object, such as a file or files, which exist all at one particular time stamp.

Parameters:

index - The channel index.

Returns:

The data.

Throws:

ArrayIndexOutOfBoundsException - If index out of bounds.

ClassCastException - Channel data is not the correct type.

Since:

V2.0

See Also:

GetData(int), GetDataAsInt8(int)

Author:

WHF

Version:

09/13/2002

GetDataAsArray

public Object GetDataAsArray(int index)

Returns the channel data as an untyped Object. The java.lang.reflect.Array class may then be used to extract doubles. This is most useful when writing PlugIns which must deal with multiple input data types.

Parameters:

index - The channel index.

Returns:

The data.

Throws:

ArrayIndexOutOfBoundsException - If index out of bounds.

Since:

V3.1

Author:

WHF

Version:

2007/11/15

GetName

public String GetName(int index)

Get the fully qualified channel name from its index in constant time.

Parameters:

index - The channel index.

Returns:

Its corresponding name.

Throws:

ArrayIndexOutOfBoundsException - If the index is out of bounds.

Since:

V2.0

See Also:

GetIndex(String)

Author:

WHF

Version:

05/17/2001

GetIndex

public final int GetIndex(String channelName)

Returns the index of a channel which has been added to this map if given its name. This search takes approximately constant time. Note that the value returned by this function will change with each call to Fetch(), even if this map is reused, and should not be stored.

Parameters:

channelName - The fully qualified channel name, including the server name.

Returns:

The corresponding channel index, or -1 if not found.

Since:

V2.0

See Also:

GetName(int)

Author:

WHF

Version:

10/05/2001

GetType

public final int GetType(int index)

Returns the type of the data returned by the specified channel. Note that this function never returns TYPE_USER. The reason for this is that a registration channel map which does contain user info will also contain server meta-data, and thus is of the more general type TYPE_STRING. To test if user info is available, call GetUserInfo, which will return an empty string if there is none.

Parameters:

index - The desired channel index.

Returns:

The corresponding data type ID.

Throws:

ArrayIndexOutOfBoundsException - If index out of bounds.

Since:

V2.0

See Also:

TYPE_FLOAT64

Author:

WHF

Version:

04/09/2001

GetMime

public final String GetMime(int index)

Returns the MIME type identifier for this channel, if any.

GetIfFetchTimedOut

public final boolean GetIfFetchTimedOut()

Returns true if and only if this channel map was returned in reponse to a Fetch() which timed-out.

A call to Sink.Fetch(long) may return a ChannelMap with no channels. This method allows you to determine whether this map is empty because the request timed out, or because the request made matches no data on the server.

GetUserInfo

public final String GetUserInfo(int channel)

Returns user information for the specified channel, if any is available.

User information corresponds to the string in server registration data between the <user> and </user> tags. It is placed into the server by registering a ChannelMap containing one or more channels to which PutUserInfo(int, String) has been applied.

Returns:

The user info, or an empty string if the mime type is not "text/xml" or the underlying data type is not String.

Since:

V2.5B4

Author:

WHF

Version:

2005/03/31

PutMime

public void PutMime(int index,
                    String mime)

Specifies the MIME (Multipurpose Internet Mail Extensions) type of this source data. Typical MIME types include "text/plain", "text/xml", for String data, and "application/octet-stream" for binary data.

A full list can be found at:

ftp://ftp.isi.edu/in-notes/iana/assignments/media-types/media-types

NOTE: The MIME type information will only be sent to the server if one of the PutData() methods is called on this channel.

TypeID

public int TypeID(String type)

Determines the numerical constant used as the type ID for the specified data type. This function is intended primarily for use by the COM interface; Java users should use the appropriate public static final int TYPE_* constants.

The String should be one of "int8", "int16", "int32", "int64" "float32", "float64", "string", "bytearray", or "unknown". Case is ignored. For example, calling this function with "int8" returns TYPE_INT8.

Throws:

IllegalArgumentException - if the type is not one of the ones listed above;

NullPointerException - if type is null.

TypeName

public String TypeName(int typeID)

Returns a string type identifier which matches the given typeID.

Throws:

ArrayOutOfBoundsException - If the typeID does not match any of the allowed types.

PutData

public void PutData(int channelIndex,
                    byte[] rawData,
                    int typeID)
             throws SAPIException

Adds the data given in rawBytes to the channel identified with the specified channel index. This assumes that the byte ordering of the data is the same as the local system. (Not Java byte ordering, which is always MSB!)

Note: the data is not copied, so do not overwrite it until it is Flushed.

Parameters:

channelIndex - The channel index.

rawData - An array of bytes representing the data.

typeID - An integer representing the type of the data.

Throws:

SAPIException - If there is an error creating the channel locally.

Since:

V2.0

See Also:

Source.Flush(ChannelMap), PutData(int,byte[],int,ChannelMap.ByteOrderEnum)

Author:

WHF

Version:

08/16/2001

PutData

public void PutData(int channelIndex,
                    byte[] rawData,
                    int typeID,
                    ChannelMap.ByteOrderEnum byteOrder)
             throws SAPIException

Adds the data given in rawBytes to the channel identified with the specified channel index.

Note: the data is not copied, so do not overwrite it until it is Flushed.

Note that this version of PutData is not available in the JavaBean/ActiveX API.

Parameters:

channelIndex - The index of the channel, obtained via Add(String) or GetIndex(String).

rawData - An array of bytes representing the data.

typeID - An integer representing the type of the data.

byteOrder - An enumerated type, one of LOCAL, LSB, or MSB.

Throws:

SAPIException - If there is an error creating the channel locally.

Since:

V2.0

See Also:

Source.Flush(ChannelMap), Add(String), GetIndex(String)

Author:

WHF

Version:

08/31/2001

PutDataAsFloat64

public void PutDataAsFloat64(int channelIndex,
                             double[] data)
                      throws SAPIException

Type safe version of PutData().

Note: the data is not copied, so do not overwrite it until it is Flushed.

Throws:

SAPIException

See Also:

PutData(int,byte[],int)

PutDataAsFloat32

public void PutDataAsFloat32(int channelIndex,
                             float[] data)
                      throws SAPIException

Type safe version of PutData().

Note: the data is not copied, so do not overwrite it until it is Flushed.

Throws:

SAPIException

See Also:

PutData(int,byte[],int)

PutDataAsInt64

public void PutDataAsInt64(int channelIndex,
                           long[] data)
                    throws SAPIException

Type safe version of PutData().

Note: the data is not copied, so do not overwrite it until it is Flushed.

Throws:

SAPIException

See Also:

PutData(int,byte[],int)

PutDataAsInt32

public void PutDataAsInt32(int channelIndex,
                           int[] data)
                    throws SAPIException

Type safe version of PutData().

Note: the data is not copied, so do not overwrite it until it is Flushed.

Throws:

SAPIException

See Also:

PutData(int,byte[],int)

PutDataAsInt16

public void PutDataAsInt16(int channelIndex,
                           short[] data)
                    throws SAPIException

Type safe version of PutData().

Note: the data is not copied, so do not overwrite it until it is Flushed.

Throws:

SAPIException

See Also:

PutData(int,byte[],int)

PutDataAsInt8

public void PutDataAsInt8(int channelIndex,
                          byte[] data)
                   throws SAPIException

Type safe version of PutData().

Note: the data is not copied, so do not overwrite it until it is Flushed.

Throws:

SAPIException

See Also:

PutData(int,byte[],int)

PutDataAsString

public void PutDataAsString(int channelIndex,
                            String data)
                     throws SAPIException

Type safe version of PutData().

Note: the data is not copied, so do not overwrite it until it is Flushed.

Throws:

SAPIException

See Also:

PutData(int,byte[],int)

PutDataAsByteArray

public void PutDataAsByteArray(int channelIndex,
                               byte[] data)
                        throws SAPIException

Type safe version of PutData(). Places a block of bytes into the ChannelMap as a contiguous object.

Note: the data is not copied, so do not overwrite it until it is Flushed.

Throws:

SAPIException

See Also:

PutData(int,byte[],int)

PutUserInfo

public final void PutUserInfo(int channelIndex,
                              String data)
                       throws SAPIException

Specify user information for a given channel. For use with server registration, this method signals the server to place the provided string inside the <user> and </user> tags of the server XML file. This is prefered to placing data directly in the registration map, as that overrides the server registration data.

Although there is no official standard for user data information, many viewers understand key/value pairs in the following form:

key1=value1,key2=value2,...,keyN=valueN

This method will work along with GetUserInfo(int) with data (non registration) ChannelMaps. However, PutDataAsString( int, String)/GetDataAsString(int) has more functionality in this case and is recommended.

Throws:

SAPIException

Since:

V2.5B4

See Also:

Sink.RequestRegistration(), Source.Register(ChannelMap)

Author:

WHF

Version:

2005/03/22

PutDataRef

public void PutDataRef(int destChannel,
                       ChannelMap sourceMap,
                       int sourceChannel)
                throws SAPIException

Transfers a reference of the data in the sourceMap to this map. The primary application of this method is in "pass-through" PlugIns, such as VSource, which do nothing with the data other than transfer it from one channel to another.

Throws:

IndexOutOfRange - If either destChannel >= this.NumberOfChannels() or sourceChannel >= sourceMap.NumberOfChannels().

SAPIException - If there is a problem transferring the data.

Since:

V2.0B10

See Also:

PutTimeRef(ChannelMap, int)

Author:

WHF

PutTime

public void PutTime(double start,
                    double duration)

Sets the time range for all data subsequently added to the channel map. This function may be called once per frame, once per channel, or once per point for a multi-point block, depending on your application.

Clears the AutoTimeStamp setting, if any.

Parameters:

start - The absolute start time of the next frame.

duration - The duration of the next frame.

Since:

V2.0

See Also:

PutTimeAuto(String), PutData(int,byte[],int), Source.Flush(ChannelMap,boolean)

Author:

WHF

Version:

05/17/2001

PutTimes

public void PutTimes(double[] times)

Sets the time vector for all data subsequently added to the channel map. This function may be called once per frame, once per channel, or once per point for a multi-point block, depending on your application. The array should have the same number of points as the data subsequently added, or else an exception will be thrown on the PutData call.

Clears the AutoTimeStamp setting, if any.

Parameters:

times - The array of time points that applies to the data set.

Since:

V2.0

See Also:

PutTimeAuto(String), PutData(int,byte[],int), Source.Flush(ChannelMap,boolean)

Author:

WHF

Version:

05/17/2001

PutTimeRef

public void PutTimeRef(ChannelMap sourceMap,
                       int channelIndex)

Copies the time reference for the specified channel on the ChannelMap provided into the current time buffer for this channel. This is done in the most efficient way possible, usually much better than:

PutTimes(sourceMap.GetTimes(channelIndex))

This function may be called once per frame, once per channel, or once per point for a multi-point block, depending on your application. The time reference must be compatable with the data subsequently added, or else an exception will be thrown on the PutData call.

Clears the PutTimeAuto setting, if any.

Parameters:

sourceMap - The map from which to copy the time reference.

channelIndex - The index of the channel whose reference to copy.

Since:

V2.0

See Also:

PutTimeAuto(String), PutTimes(double[]), PutData(int,byte[],int), Source.Flush(ChannelMap,boolean)

Author:

WHF

Version:

04/15/2002

PutTimeAuto

public void PutTimeAuto(String timeMode)
                 throws IllegalArgumentException

Sets the mode for automatic time stamp generation that will be used on the next call to Flush(). Case is not significant.

If the timeMode is "next", then the time-stamp increments starting from 1 each time Source.Flush is called.

If the timeMode is "timeofday", then the time-stamp is set equal to the client-side system clock time each time PutData is called.

If the timeMode is "server", then the time-stamp is set equal to the server-side system clock time at the point when the flushed frame is placed in the ring buffer. This mode should not be used in conjunction with any other time-stamping style within a single frame, although it can be changed from flush to flush.

If the mode is not set, it defaults to "server".

The default units for auto timestamps are seconds since 1970, stored in a double precision number (System.currentTimeMillis()/1000.). Note that this results in approximately 1 micro-second time resolution. For higher resolution, use manual (non-auto) timestamps, e.g. use a relative (zero-based) start time instead of 1970.

Parameters:

timeMode - The mode setting, one of "next", "timeofday", or "server".

Throws:

IllegalArgumentException - If the mode is not correct.

Since:

V2.0

See Also:

Source.Flush(ChannelMap,boolean)

Author:

WHF

Version:

05/17/2001

NumberOfChannels

public int NumberOfChannels()

Returns the number of channels available in the map.

Since:

V2.0

See Also:

Add(String)

Author:

WHF

Version:

01/25/2002

toString

public String toString()

Returns a descriptive String about the state of this channel map.

Overrides:

toString in class Object

Since:

V2.0

Author:

WHF

Version:

02/06/2002

GetNodeList

public final String[] GetNodeList()

Deprecated. Please use the ChannelTree class for per-node heirarchy construction and identification.

Returns a String array containing one string for every node in the channel hierarchy of this map. If all the channels in the map were placed in one or more trees, with the first token (using '/' to separate tokens) as the root, the second tokens as its children, etc., each node of this tree would be returned by this function. Each String is as qualified as possible.

For example, if a ChannelMap contains the channel "/Server/Source/Channel", the return result would be "/Server", "/Server/Source", and "/Server/Source/Channel". However, if the channel was "Source/Channel", only "Source" and "Source/Channel" would be returned.

Since:

V2.0

Author:

WHF

Version:

04/10/2002

GetChannelList

public final String[] GetChannelList()

Convenience function to return the list of channels contained in this ChannelMap. This could be implemented as:

ChannelMap map= ...
String[] list=new String[map.NumberOfChannels()];
for (int ii=0; ii<list.length; ++ii)
list[ii]=map.GetName(ii);

However, this function is slightly more efficient.

Returns:

The list of channels, or a zero length array if no channels are available.

Since:

V2.0

Author:

WHF

Version:

04/10/2002

GetFolderList

public final String[] GetFolderList()

Returns the list of empty folders contained within this ChannelMap. If there are no such folders, an array of length zero is returned. In general there will only be folders in a ChannelMap which is the result of a Sink.RequestRegistration(ChannelMap).

Since:

V2.1

See Also:

Sink.RequestRegistration(ChannelMap)

Author:

WHF

GetServerList

public final String[] GetServerList()

Deprecated. Please use the ChannelTree class for per-node heirarchy construction and identification.

Convenience function to return the list of child servers contained in this ChannelMap. This is only useful for maps returned from a registration request.

Returns:

The list of child servers, or a zero length array if no servers are available.

Since:

V2.0

Author:

WHF

Version:

06/12/2002

GetSinkList

public final String[] GetSinkList()

Deprecated. Please use the ChannelTree class for per-node heirarchy construction and identification.

Returns the list of Sinks contained in this ChannelMap. This is only useful for maps returned from a registration request.

Returns:

The list of Sinks, or a zero length array if no Sinks are present.

Since:

V2.0B10

Author:

WHF

Version:

01/23/2003

GetSourceList

public final String[] GetSourceList()

Deprecated. Please use the ChannelTree class for per-node heirarchy construction and identification.

Returns the list of Sources contained in this ChannelMap. This is only useful for maps returned from a registration request.

Returns:

The list of Sources, or a zero length array if no Sources are present.

Since:

V2.0B10

Author:

WHF

Version:

01/23/2003

GetPlugInList

public final String[] GetPlugInList()

Deprecated. Please use the ChannelTree class for per-node heirarchy construction and identification.

Returns the list of PlugIns contained in this ChannelMap. This is only useful for maps returned from a registration request.

Returns:

The list of PlugIns, or a zero length array if no PlugIns are present.

Since:

V2.0B10

Author:

WHF

Version:

01/23/2003

Search

public int[] Search(String mimeType,
                    String keywords)

Convenience function to search this ChannelMap for the specified keyword and mimeType. All channels of fetched data currently in the map are iterrogated to see if their MIME type exactly matches the specified mimeType parameter. If they do, the data for that channel is searched to see if every key word in the input set exists. If so, the channel is added to the array of channels returned.

Keywords should be separated by spaces. If either parameter is null, that constraint is ignored on the search.

Returns:

An array of channel indices for channels which match the search criteria.

Since:

V2.0

Author:

WHF

Version:

09/28/2004