## com.rbnb.api
Interface SourceInterface

All Superinterfaces:
  ClientInterface, Cloneable, RegisteredInterface, RmapInterface, Serializable, UsernameInterface

All Known Subinterfaces:
  Sink, SinkInterface, Source

    public interface SourceInterface

extends ClientInterface

Common representation of a source client application connection to the RBNB server.

Since:
  V2.0
Author:
  Ian Brown
Version:
  09/29/2004

Field Summary
`static byte` `ACCESS_APPEND` append to an existing archive.
`static byte` `ACCESS_CREATE` create a new archive.
`static byte` `ACCESS_LOAD` read an existing archive.
`static byte` `ACCESS_NONE` do not access an archive.

Fields inherited from interface com.rbnb.api.ClientInterface
`CLIENT, FOREVER, MIRROR, PLUGIN`

Method Summary
`void` `clearCache()` Clears the contents of the `Cache`.
`Object` `clone()` Clones this object.
`Rmap` `deleteChannels(Rmap channelsI)` Deletes one or more channels from the `SourceInterface`.
`long` `getAframes()` Gets the maximum number of frames allowed in the archive.
`boolean` `getAkeep()` Gets the keep archive flag.
`byte` `getAmode()` Gets the archive access mode.
`long` `getAsize()` Gets the maximum amount of memory usage allowed for the archive.
`long` `getCframes()` Gets the maximum number of frames allowed in the cache.
`boolean` `getCkeep()` Gets the keep cache flag.
`long` `getCsize()` Gets the maximum amount of memory usage allowed for the cache.
`int` `getNfs()` Gets the number of cache `FrameSets`.
`void` `register(Rmap rmapI)` Updates the registration for this `Source`.
`void` `reset()` Reset this `Source's` ring buffer.
`void` `setAframes(long archiveFramesI)` Sets the maximum number of frames allowed in the archive.
`void` `setAkeep(boolean keepI)` Sets the keep archive flag.
`void` `setAmode(byte modeI)` Sets the archive access mode.
`void` `setAsize(long archiveSizeI)` Sets the maximum amount of memory usage allowed for the archive.
`void` `setCframes(long cacheFramesI)` Sets the maximum number of frames allowed in the cache.
`void` `setCkeep(boolean keepI)` Sets the keep cache flag.
`void` `setCsize(long cacheSizeI)` Sets the maximum amount of memory usage allowed for the cache.
`void` `setNfs(int frameSetsI)` Sets the number of cache `FrameSets`.

Methods inherited from interface com.rbnb.api.ClientInterface
`getRemoteID, getType, isRunning, setRemoteID, setType, tryReconnect`

Methods inherited from interface com.rbnb.api.RegisteredInterface
`getRegistered`

Methods inherited from interface com.rbnb.api.RmapInterface
`addChild, compareNames, compareNames, compareTo, findChild, findDescendant, getFullName, getName, getParent, removeChild, removeChildAt, setName, toString, toString`

Methods inherited from interface com.rbnb.api.UsernameInterface
`getUsername, setUsername`

Field Detail

### ACCESS_NONE

    static final byte ACCESS_NONE

  do not access an archive.

  Since:
    V2.0
  See Also:
    `ACCESS_APPEND`, `ACCESS_CREATE`, `ACCESS_LOAD`, Constant Field Values
  Author:
    Ian Brown
  Version:
    05/09/2001

### ACCESS_LOAD

    static final byte ACCESS_LOAD

  read an existing archive.

  Since:
    V2.0
  See Also:
    `ACCESS_APPEND`, `ACCESS_CREATE`, `ACCESS_NONE`, Constant Field Values
  Author:
    Ian Brown
  Version:
    05/09/2001

### ACCESS_CREATE

    static final byte ACCESS_CREATE

  create a new archive.

  Since:
    V2.0
  See Also:
    `ACCESS_APPEND`, `ACCESS_LOAD`, `ACCESS_NONE`, Constant Field Values
  Author:
    Ian Brown
  Version:
    05/09/2001

### ACCESS_APPEND

    static final byte ACCESS_APPEND

  append to an existing archive.

  Since:
    V2.0
  See Also:
    `ACCESS_CREATE`, `ACCESS_LOAD`, `ACCESS_NONE`, Constant Field Values
  Author:
    Ian Brown
  Version:
    05/09/2001

Method Detail

### clearCache

    void clearCache()
                    throws AddressException,
                           SerializeException,
                           EOFException,
                           IOException,
                           InterruptedException

  Clears the contents of the `Cache`.

  If there is an `Archive`, all data will be flushed to it before the `Cache` is cleared to ensure that the data is not lost.

  Throws:
    `AddressException` - thrown if there is a problem with an address.
    `SerializeException` - thrown if there is a problem with the serialization.
    `EOFException` - thrown if the end of the input stream is reached.
    `IOException` - thrown if there is an error during I/O.
    `InterruptedException` - thrown if the operation is interrupted.
  Since:
    V2.2
  Author:
    Ian Brown
  Version:
    01/08/2004

### clone

    Object clone()

  Clones this object.

  This same abstract declaration is also included in RmapInterface.java, but for some unknown reason J# gives a compiler error if it is not also included here.

  Specified by:
    `clone` in interface `ClientInterface`
  Specified by:
    `clone` in interface `RmapInterface`
  Returns:
    the clone.
  Since:
    V2.5
  See Also:
    `Cloneable`
  Author:
    John Wilson
  Version:
    09/29/2004

### deleteChannels

    Rmap deleteChannels(Rmap channelsI)
                        throws AddressException,
                               SerializeException,
                               EOFException,
                               IOException,
                               InterruptedException

  Deletes one or more channels from the `SourceInterface`.

  Channels are deleted by deleting the `RingBuffer` that contains them. If that `RingBuffer` contains more than one channel, then the request must specify that all of the channels are to be deleted or those that are specified will not be deleted.

  Parameters:
    `channelsI` - `Rmap` hierarchy specifying the channels to be deleted.
  Returns:
    `Rmap` containing status information for each of the channels.
  Throws:
    `AddressException` - thrown if there is a problem with an address.
    `SerializeException` - thrown if there is a problem with the serialization.
    `EOFException` - thrown if the end of the input stream is reached.
    `IOException` - thrown if there is an error during I/O.
    `IllegalArgumentException` - thrown if the input `Rmap` is already a child of another `Rmap` or if the input is null.
    `InterruptedException` - thrown if the operation is interrupted.
  Since:
    V2.2
  Author:
    Ian Brown
  Version:
    07/30/2003

### getAframes

    long getAframes()

  Gets the maximum number of frames allowed in the archive.

  Returns:
    the archive limit in frames.
  Since:
    V2.0
  See Also:
    `setAframes(long)`
  Author:
    Ian Brown
  Version:
    05/09/2001

### getAkeep

    boolean getAkeep()

  Gets the keep archive flag.

  Returns:
    keep the archive on disk?
  Since:
    V2.0
  See Also:
    `setAkeep(boolean)`
  Author:
    Ian Brown
  Version:
    10/08/2002

### getAmode

    byte getAmode()

  Gets the archive access mode.

  Returns:
    the archive access mode.
  Since:
    V2.0
  See Also:
    `ACCESS_APPEND`, `ACCESS_CREATE`, `ACCESS_LOAD`, `ACCESS_NONE`, `setAmode(byte)`
  Author:
    Ian Brown
  Version:
    05/09/2001

### getAsize

    long getAsize()

  Gets the maximum amount of memory usage allowed for the archive.

  This method is not currently supported.

  Returns:
    the archive size in bytes.
  Since:
    V2.0
  See Also:
    `setAsize(long)`
  Author:
    Ian Brown
  Version:
    09/26/2001

### getCframes

    long getCframes()

  Gets the maximum number of frames allowed in the cache.

  Returns:
    the cache limit in frames.
  Since:
    V2.0
  See Also:
    `setCframes(long)`
  Author:
    Ian Brown
  Version:
    05/09/2001

### getCkeep

    boolean getCkeep()

  Gets the keep cache flag.

  Returns:
    keep the cache in the server on disconnect?
  Since:
    V2.0
  See Also:
    `setCkeep(boolean)`
  Author:
    Ian Brown
  Version:
    10/08/2002

### getCsize

    long getCsize()

  Gets the maximum amount of memory usage allowed for the cache.

  This method is not currently supported.

  Returns:
    the cache size in bytes.
  Since:
    V2.0
  See Also:
    `setCsize(long)`
  Author:
    Ian Brown
  Version:
    09/26/2001

### getNfs

    int getNfs()

  Gets the number of cache `FrameSets`.

  Returns:
    the number of `FrameSets`.
  Since:
    V2.0
  See Also:
    `setNfs(int)`
  Author:
    Ian Brown
  Version:
    05/09/2001

### register

    void register(Rmap rmapI)
                  throws AddressException,
                         SerializeException,
                         EOFException,
                         InterruptedIOException,
                         IOException,
                         InterruptedException

  Updates the registration for this `Source`.

  The input `Rmap` hierarchy is used to update the registration for this `Source`. The hierarchy may contain `DataBlocks`, but not time information. Those `DataBlocks` are copied into the appropriate locations in the registration map.

  Parameters:
    `rmapI` - the registration `Rmap` hierarchy.
  Throws:
    `AddressException` - thrown if there is an addressing problem.
    `SerializeException` - thrown if there is a problem with the serialization.
    `EOFException` - thrown if the end of the input stream is reached.
    `InterruptedIOException` - thrown if this operation is interrupted during I/O.
    `IOException` - thrown if there is an error during I/O.
    `InterruptedException` - thrown if this operation is interrupted.
  Since:
    V2.0
  Author:
    Ian Brown
  Version:
    09/25/2001

### reset

    void reset()
               throws AddressException,
                      SerializeException,
                      EOFException,
                      InterruptedIOException,
                      IOException,
                      InterruptedException

  Reset this `Source's` ring buffer.

  This method performs the functional equivalent of closing and re-opening the `Source`. A completely new ring buffer is created to replace the existing one.

  Throws:
    `AddressException` - thrown if there is an addressing problem.
    `SerializeException` - thrown if there is a problem with the serialization.
    `EOFException` - thrown if the end of the input stream is reached.
    `InterruptedIOException` - thrown if this operation is interrupted during I/O.
    `IOException` - thrown if there is an error during I/O.
    `InterruptedException` - thrown if this operation is interrupted.
  Since:
    V2.0
  Author:
    Ian Brown
  Version:
    02/12/2002

### setAframes

    void setAframes(long archiveFramesI)

  Sets the maximum number of frames allowed in the archive.

  A value of -1 means that the archive is not limited to a maximum number of frames.

  The following ratios should be positive integers:

  - cache frames/number of sets, and
  - archive frames/cache frames.

  If these ratios are not positive integers, then the <bold>RBNB</bold> server increases the numerator until the result is a positive integer.

  Parameters:
    `archiveFramesI` - the archive limit in frames.
  Throws:
    `IllegalArgumentException` - thrown if the archive limit specified is not a legal value:

    - negative values other than -1,
    - larger than some server-imposed limit.

  Since:
    V2.0
  See Also:
    `getAframes()`, `setCframes(long)`, `setNfs(int)`
  Author:
    Ian Brown
  Version:
    05/09/2001

### setAkeep

    void setAkeep(boolean keepI)

  Sets the keep archive flag.

  Parameters:
    `keepI` - keep the archive on disk?
  Since:
    V2.0
  See Also:
    `getAkeep()`
  Author:
    Ian Brown
  Version:
    10/08/2002

### setAmode

    void setAmode(byte modeI)

  Sets the archive access mode.

  Parameters:
    `modeI` - the archive access mode.
  Since:
    V2.0
  See Also:
    `ACCESS_APPEND`, `ACCESS_CREATE`, `ACCESS_LOAD`, `ACCESS_NONE`, `getAmode()`
  Author:
    Ian Brown
  Version:
    05/09/2001

### setAsize

    void setAsize(long archiveSizeI)

  Sets the maximum amount of memory usage allowed for the archive.

  A value of -1 means that the archive is not limited to a maximum amount of memory.

  This method is not currently supported.

  Parameters:
    `archiveSizeI` - the archive size in bytes.
  Throws:
    `IllegalArgumentException` - thrown if the archive size specified is not a legal value:

    - negative values other than -1,
    - larger than some server-imposed limit.

  Since:
    V2.0
  See Also:
    `getAsize()`
  Author:
    Ian Brown
  Version:
    09/26/2001

### setCframes

    void setCframes(long cacheFramesI)
                    throws SerializeException,
                           EOFException,
                           IOException,
                           InterruptedException

  Sets the maximum number of frames allowed in the cache.

  A value of -1 means that the cache is not limited to a maximum number of frames.

  The following ratios should be positive integers:

  - cache frames/number of sets, and
  - archive frames/cache frames.

  If these ratios are not positive integers, then the <bold>RBNB</bold> server increases the numerator until the result is a positive integer.

  Parameters:
    `cacheFramesI` - the cache limit in frames.
  Throws:
    `SerializeException` - thrown if there is a problem with the serialization.
    `EOFException` - thrown if the end of the input stream is reached.
    `IOException` - thrown if there is an error during I/O.
    `IllegalArgumentException` - thrown if the cache limit specified is not a legal value:

    - negative values other than -1,
    - larger than some server-imposed limit.

    `IndexOutOfBoundsException` - thrown if there are no children or the index is not in the range 0 to # of children - 1.
    `InterruptedException` - thrown if the operation is interrupted.
  Since:
    V2.0
  See Also:
    `getCframes()`, `setAframes(long)`, `setNfs(int)`
  Author:
    Ian Brown
  Version:
    09/26/2001

### setCkeep

    void setCkeep(boolean keepI)

  Sets the keep cache flag.

  Parameters:
    `keepI` - keep the cache in the server?
  Since:
    V2.0
  See Also:
    `getCkeep()`
  Author:
    Ian Brown
  Version:
    10/08/2002

### setCsize

    void setCsize(long cacheSizeI)

  Sets the maximum amount of memory usage allowed for the cache.

  A value of -1 means that the cache is not limited to a maximum amount of memory.

  This method is not currently supported.

  Parameters:
    `cacheSizeI` - the cache size in bytes.
  Throws:
    `IllegalArgumentException` - thrown if the cache size specified is not a legal value:

    - negative values other than -1,
    - larger than some server-imposed limit.

  Since:
    V2.0
  See Also:
    `getCsize()`
  Author:
    Ian Brown
  Version:
    09/26/2001

### setNfs

    void setNfs(int frameSetsI)

  Sets the number of cache `FrameSets`.

  The following ratios should be positive integers:

  - cache frames/number of sets, and
  - archive frames/cache frames.

  If these ratios are not positive integers, then the <bold>RBNB</bold> server increases the numerator until the result is a positive integer.

  Parameters:
    `frameSetsI` - the number of cache `FrameSets`.
  Throws:
    `IllegalArgumentException` - thrown if the number of cache `FrameSets` specified is not a legal value:

    - values less than 0, or
    - larger than some server-imposed limit.

  Since:
    V2.0
  See Also:
    `getNfs()`, `setAframes(long)`, `setCframes(long)`
  Author:
    Ian Brown
  Version:
    09/26/2001