## com.rbnb.api
Class ControllerHandle

    java.lang.Object
      com.rbnb.api.Rmap
          com.rbnb.api.ControllerHandle

All Implemented Interfaces:
  Client, ClientInterface, Controller, RegisteredInterface, RmapInterface, UsernameInterface, com.rbnb.utility.SortCompareInterface, com.rbnb.utility.SortInterface, Serializable, Cloneable

    public class ControllerHandle

extends Rmap
implements Controller

Client-side object that represents a client controller application connection to an RBNB server.

Since:
  V2.0
See Also:
  Serialized Form
Author:
  Ian Brown
Version:
  11/19/2002

Field Summary

Fields inherited from class com.rbnb.api.Rmap
`PATHDELIMITER`

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

Method Summary
`long` `bytesTransferred()` Calculates the total number of bytes transferred.
`String` `fetchAddressAuthorization(com.rbnb.api.ServerInterface si)`
`protected void` `finalize()` Finalizes this connection to the server.
`Rmap` `getRegistered(Rmap requestI)` Gets the list of registered `Rmaps` matching the requested `Rmap` hierarchy.
`String` `getRemoteID()` Gets the remote identification.
`byte` `getType()` Gets the type of client connection.
`Username` `getUsername()` Gets the `Username` associated with this object.
`boolean` `isRunning()` Is this `ClientHandle` running?
`boolean` `isSynchronized()` Is this `ClientHandle` synchronized with the server?
`void` `mirror(Mirror mirrorI)` Mirrors data from or to a remote RBNB server.
`void` `sendAddressAuthorization(com.rbnb.api.ServerInterface si, String auth)`
`void` `setRemoteID(String remoteIDI)` Sets the remote identification.
`void` `setType(byte typeI)` Sets the type of client connection.
`void` `setUsername(Username usernameI)` Sets the `Username` for this object.
`void` `start()` Starts the `ClientHandle`.
`void` `start(Client clientI)` Starts the specified `Client`.
`void` `start(Shortcut shortcutI)` Starts a shortcut connection.
`void` `stop()` Stops the `ClientHandle`.
`void` `stop(Client clientI)` Stops the `Client`.
`void` `stop(Server serverI)` Stops the local <bold>RBNB</bold> server.
`void` `stop(Shortcut shortcutI)` Stops a local `Shortcut`.
`void` `synchronizeWserver()` Synchronizes with the server.
`boolean` `tryReconnect()` Try to reconnect to an existing `ClientHandler`?

Methods inherited from class com.rbnb.api.Rmap

`addChannel, addChild, addChildAt, addDataWithTimeReference, addMember, clone, collapse, compareNames, compareNames, compareNames, compareTo, compareTo, createFromName, extract, extract, extractFolders, extractFoldersAndChannels, extractNames, extractRmap, findChild, findDescendant, findMember, getChildAt, getChildren, getDblock, getFrange, getFullName, getMemberAt, getMembers, getName, getNchildren, getNmembers, getParent, getTrange, isImplemented, markLeaf, mergeWith, moveToBottom, moveToTop, nullify, removeChild, removeChildAt, removeMember, removeMemberAt, setDblock, setFrange, setName, setTrange, sortField, toNameHierarchy, toString, toString, xmlRegistration, xmlRegistration`

Methods inherited from class java.lang.Object
`equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Methods inherited from interface com.rbnb.api.Controller
`clone`

Methods inherited from interface com.rbnb.api.Client
`isSynchronized, start, start, start, stop, stop, stop, stop, synchronizeWserver`

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`

Method Detail

### bytesTransferred

    public final long bytesTransferred()

  Calculates the total number of bytes transferred.

  Returns:
    the number of bytes transferred.
  Since:
    V2.0
  Author:
    Ian Brown
  Version:
    11/19/2002

### mirror

    public final void mirror(Mirror mirrorI)
                      throws AddressException,
                             SerializeException,
                             EOFException,
                             IOException,
                             InterruptedException

  Mirrors data from or to a remote RBNB server.

  Specified by:
    `mirror` in interface `Controller`
  Parameters:
    `mirrorI` - the `Mirror` command.
  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 check is interrupted.
  Since:
    V2.0
  Author:
    Ian Brown
  Version:
    12/18/2001

### fetchAddressAuthorization

    public String fetchAddressAuthorization(com.rbnb.api.ServerInterface si)
                                     throws AddressException,
                                            SerializeException,
                                            InterruptedIOException,
                                            IOException,
                                            InterruptedException

  Throws:
    `AddressException`
    `SerializeException`
    `InterruptedIOException`
    `IOException`
    `InterruptedException`

### sendAddressAuthorization

    public void sendAddressAuthorization(com.rbnb.api.ServerInterface si,
                                         String auth)
                                  throws AddressException,
                                         SerializeException,
                                         InterruptedIOException,
                                         IOException,
                                         InterruptedException

  Throws:
    `AddressException`
    `SerializeException`
    `InterruptedIOException`
    `IOException`
    `InterruptedException`

### finalize

    protected final void finalize()

  Finalizes this connection to the server.

  Overrides:
    `finalize` in class `Object`
  Since:
    V2.0
  Author:
    Ian Brown
  Version:
    03/11/2002

### getRegistered

    public Rmap getRegistered(Rmap requestI)
                       throws AddressException,
                              SerializeException,
                              EOFException,
                              IOException,
                              InterruptedException

  Gets the list of registered `Rmaps` matching the requested `Rmap` hierarchy.

  At this time the following `Rmap` hierarchies are implemented:

  - {unnamed}[/...],
  - [{unnamed}/]servername[/...],
  - [{unnamed}/]servername/clientname[/...],
  - [{unnamed}/]servername/clientname1[/....],/clientname2[/...], ...

  Syntax notes:
  / indicates a child `Rmap`.
  [/...] indicates an optional child `Rmap` with a name of "...". This causes the registration maps of the children of the `Rmap` to be expanded.
  , indicates multiple children.

  Specified by:
    `getRegistered` in interface `RegisteredInterface`
  Parameters:
    `requestI` - the requested `Rmap` hierarchy.
  Returns:
    the `Rmap` hierarchy containing the registered `Rmaps`.
  Throws:
    `AddressException` - thrown if there is a problem with an address.
    `SerializeException` - thrown if there is a problem during serialization.
    `EOFException` - thrown if an EOF is encountered while getting the response.
    `IOException` - thrown if there is a problem during I/O.
    `InterruptedException` - thrown if the get is interrupted.
  Since:
    V2.0
  Author:
    Ian Brown
  Version:
    11/12/2002

### isRunning

    public final boolean isRunning()
                            throws AddressException,
                                   SerializeException,
                                   EOFException,
                                   IOException,
                                   InterruptedException

  Is this `ClientHandle` running?

  Specified by:
    `isRunning` in interface `ClientInterface`
  Returns:
    is this `Client` running?
  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.
    `IllegalStateException` - thrown if the `Client` is in a bad state.
    `InterruptedException` - thrown if the check is interrupted.
  Since:
    V2.0
  Author:
    Ian Brown
  Version:
    05/22/2001

### start

    public void start()
               throws AddressException,
                      SerializeException,
                      EOFException,
                      InterruptedIOException,
                      IOException,
                      InterruptedException

  Starts the `ClientHandle`.

  Specified by:
    `start` in interface `Client`
  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.
    `IllegalStateException` - thrown if:

    - the `ClientHandle` has not been connected to a server,
    - the `ClientHandle` is already running.

    `InterruptedException` - thrown if the start is interrupted.
  Since:
    V2.0
  See Also:
    `stop()`
  Author:
    Ian Brown
  Version:
    03/31/2003

### start

    public final void start(Client clientI)
                     throws AddressException,
                            SerializeException,
                            EOFException,
                            InterruptedIOException,
                            IOException,
                            InterruptedException

  Starts the specified `Client`.

  Specified by:
    `start` in interface `Client`
  Parameters:
    `clientI` - the `Client`.
  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
  See Also:
    `stop(com.rbnb.api.Client)`
  Author:
    Ian Brown
  Version:
    11/12/2002

### start

    public final void start(Shortcut shortcutI)
                     throws AddressException,
                            SerializeException,
                            EOFException,
                            InterruptedIOException,
                            IOException,
                            InterruptedException

  Starts a shortcut connection.

  Specified by:
    `start` in interface `Client`
  Parameters:
    `shortcutI` - the `Shortcut`.
  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
  See Also:
    `stop(com.rbnb.api.Server)`
  Author:
    Ian Brown
  Version:
    11/12/2002

### stop

    public void stop()
              throws AddressException,
                     SerializeException,
                     EOFException,
                     InterruptedIOException,
                     IOException,
                     InterruptedException

  Stops the `ClientHandle`.

  Specified by:
    `stop` in interface `Client`
  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.
    `java.lang.InterruptedIOException` - thrown if this operation is interrupted.
    `IOException` - thrown if there is an error during I/O.
    `IllegalStateException` - thrown if:

    - the `ClientHandle` has not been connected to a server,
    - the `ClientHandle` is already running.

    `InterruptedException` - thrown if the start is interrupted.
    `InterruptedIOException`
  Since:
    V2.0
  See Also:
    `start()`
  Author:
    Ian Brown
  Version:
    01/14/2004

### stop

    public final void stop(Client clientI)
                    throws AddressException,
                           SerializeException,
                           InterruptedIOException,
                           IOException,
                           InterruptedException

  Stops the `Client`.

  Specified by:
    `stop` in interface `Client`
  Parameters:
    `clientI` - the `Client`.
  Throws:
    `AddressException` - thrown if there is an addressing problem.
    `SerializeException` - thrown if there is a problem with the `Serialization`.
    `java.lang.InterruptedIOException` - thrown if this operation is interrupted.
    `IOException` - thrown if there is a I/O problem.
    `InterruptedException` - thrown if this operation is interrupted.
    `InterruptedIOException`
  Since:
    V2.0
  See Also:
    `start(com.rbnb.api.Client)`
  Author:
    Ian Brown
  Version:
    11/12/2002

### stop

    public final void stop(Server serverI)
                    throws AddressException,
                           SerializeException,
                           InterruptedIOException,
                           IOException,
                           InterruptedException

  Stops the local <bold>RBNB</bold> server.

  Specified by:
    `stop` in interface `Client`
  Parameters:
    `serverI` - the `Server`.
  Throws:
    `AddressException` - thrown if there is an addressing problem.
    `SerializeException` - thrown if there is a problem with the `Serialization`.
    `java.lang.InterruptedIOException` - thrown if this operation is interrupted.
    `IOException` - thrown if there is a I/O problem.
    `InterruptedException` - thrown if this operation is interrupted.
    `InterruptedIOException`
  Since:
    V2.0
  Author:
    Ian Brown
  Version:
    11/12/2002

### stop

    public final void stop(Shortcut shortcutI)
                    throws AddressException,
                           SerializeException,
                           InterruptedIOException,
                           IOException,
                           InterruptedException

  Stops a local `Shortcut`.

  Specified by:
    `stop` in interface `Client`
  Parameters:
    `shortcutI` - the `Shortcut`.
  Throws:
    `AddressException` - thrown if there is an addressing problem.
    `SerializeException` - thrown if there is a problem with the `Serialization`.
    `java.lang.InterruptedIOException` - thrown if this operation is interrupted.
    `IOException` - thrown if there is a I/O problem.
    `InterruptedException` - thrown if this operation is interrupted.
    `InterruptedIOException`
  Since:
    V2.0
  See Also:
    `start(com.rbnb.api.Shortcut)`
  Author:
    Ian Brown
  Version:
    11/12/2002

### synchronizeWserver

    public void synchronizeWserver()
                            throws AddressException,
                                   SerializeException,
                                   InterruptedIOException,
                                   IOException,
                                   InterruptedException

  Synchronizes with the server.

  Specified by:
    `synchronizeWserver` in interface `Client`
  Throws:
    `AddressException` - thrown if there is a problem with an address.
    `SerializeException` - thrown if there is a problem with the `Serialization`.
    `IOException` - thrown if there is a I/O problem.
    `InterruptedException` - thrown if this operation is interrupted.
    `IllegalStateException` - thrown if:

    - the `ClientHandle` has not been connected to a server,
    - the `ClientHandle` is not running.

    `InterruptedException` - thrown if the synchronization is interrupted.
    `InterruptedIOException`
  Since:
    V2.0
  Author:
    Ian Brown
  Version:
    05/30/2001

### getRemoteID

    public final String getRemoteID()

  Gets the remote identification.

  Specified by:
    `getRemoteID` in interface `ClientInterface`
  Returns:
    the remote identification.
  Since:
    V2.0
  See Also:
    `setRemoteID(String)`
  Author:
    Ian Brown
  Version:
    06/01/2001

### getType

    public final byte getType()

  Gets the type of client connection.

  Specified by:
    `getType` in interface `ClientInterface`
  Returns:
    the client type.
  Since:
    V2.0
  See Also:
    `ClientInterface.CLIENT`, `ClientInterface.MIRROR`, `ClientInterface.PLUGIN`, `setType(byte)`
  Author:
    Ian Brown
  Version:
    06/01/2001

### getUsername

    public final Username getUsername()

  Gets the `Username` associated with this object.

  Specified by:
    `getUsername` in interface `UsernameInterface`
  Returns:
    the `Username`.
  Since:
    V2.0
  See Also:
    `setUsername(com.rbnb.api.Username usernameI)`
  Author:
    Ian Brown
  Version:
    01/14/2003

### isSynchronized

    public boolean isSynchronized()

  Is this `ClientHandle` synchronized with the server?

  Specified by:
    `isSynchronized` in interface `Client`
  Returns:
    is the client synchronized?
  Since:
    V2.0
  Author:
    Ian Brown
  Version:
    11/12/2002

### setRemoteID

    public final void setRemoteID(String remoteIDI)

  Sets the remote identification.

  The remote identification specifies the fully-qualified name of the remote RBNB object with which this RBNB object is communicating, if any.

  Specified by:
    `setRemoteID` in interface `ClientInterface`
  Parameters:
    `remoteIDI` - the remote identification.
  Since:
    V2.0
  See Also:
    `getRemoteID()`
  Author:
    Ian Brown
  Version:
    06/01/2001

### setType

    public final void setType(byte typeI)

  Sets the type of client connection.

  Specified by:
    `setType` in interface `ClientInterface`
  Parameters:
    `typeI` - the type of client connection.
  Since:
    V2.0
  See Also:
    `ClientInterface.CLIENT`, `getType()`, `ClientInterface.MIRROR`, `ClientInterface.PLUGIN`
  Author:
    Ian Brown
  Version:
    06/01/2001

### setUsername

    public final void setUsername(Username usernameI)

  Sets the `Username` for this object.

  Specified by:
    `setUsername` in interface `UsernameInterface`
  Parameters:
    `usernameI` - the `Username`.
  Since:
    V2.0
  See Also:
    `getUsername()`
  Author:
    Ian Brown
  Version:
    01/14/2003

### tryReconnect

    public boolean tryReconnect()

  Try to reconnect to an existing `ClientHandler`?

  Generally when a client logs into the server, and an existing `ClientHandler` is found that matches, the new client is renamed. This method should be overridden if that behavior needs to be changed.

  Specified by:
    `tryReconnect` in interface `ClientInterface`
  Returns:
    try to reconnect?
  Since:
    V2.1
  Author:
    Ian Brown
  Version:
    04/17/2003