## 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 `Sink`s 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 `Source`s 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 `PlugIn`s 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