uk.ac.starlink.connect

## Class Connection

- java.lang.Object
- - uk.ac.starlink.connect.Connection

-     public abstract class Connection
      extends java.lang.Object

  Represents a connection to a remote resource. Currently this resource is defined to provide access to a virtual filesystem as provided by the `getRoot()` method. This functionality may be broadened or narrowed in the future.

  When constructed, a Connection should be live, and hopefully remain so until `logOut()` is called.

  Since:
    18 Feb 2005

- - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `Connection()` Constructs a connection with no information.
    `protected` | `Connection(Connector connector, java.util.Map<AuthKey,?> keys)` Constructs a connection recording the circumstances under which it was created.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.lang.Object` | `getAuthValue(AuthKey key)` Returns the value for a given authorization key used when opening this connection, if known
    `Connector` | `getConnector()` Returns the connector which generated this connection, if known.
    `abstract Branch` | `getRoot()` Returns the root of the remote filesystem provided by this connection.
    `abstract boolean` | `isConnected()` Indicates whether this connection is currently up and running.
    `abstract void` | `logOut()` Closes this connection.
    `void` | `setLogoutOnExit(boolean tidy)` Controls whether an attempt is made to shut down this connection when the JVM exits if it has not been done within the program.
    `java.lang.String` | `toString()`

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### Connection

          protected Connection()

      Constructs a connection with no information.

    - #### Connection

          protected Connection(Connector connector,
                               java.util.Map<AuthKey,?> keys)

      Constructs a connection recording the circumstances under which it was created.
      Parameters:
        `connector` - Connector which generated this connection
        `keys` - map giving the set of authorization values used when opening this connection

  - ### Method Detail

    - #### getAuthValue

          public java.lang.Object getAuthValue(AuthKey key)

      Returns the value for a given authorization key used when opening this connection, if known
      Parameters:
        `key` - authorization key
      Returns:
        value for `key` (of type `key.getValueType()`), or null

    - #### getConnector

          public Connector getConnector()

      Returns the connector which generated this connection, if known.
      Returns:
        connector, or null

    - #### isConnected

          public abstract boolean isConnected()

      Indicates whether this connection is currently up and running. Hopefully it will return true until `logOut()` has been called, but it's possible that the connection may expire for some reason before that.
      Returns:
        true iff connection is up

    - #### logOut

          public abstract void logOut()
                               throws java.io.IOException

      Closes this connection.
      Throws:
        `java.io.IOException` - if something went wrong

    - #### getRoot

          public abstract Branch getRoot()

      Returns the root of the remote filesystem provided by this connection. This method should not do work, but only return an existing branch (acquired at login time); that is the root branch should not be constructed lazily.
      Returns:
        root of the virtual filesystem associated with this connection

    - #### setLogoutOnExit

          public void setLogoutOnExit(boolean tidy)

      Controls whether an attempt is made to shut down this connection when the JVM exits if it has not been done within the program. If set true, at system exit if `isConnected()` returns true an attempt is made to call `logOut()`. Note this might cause JVM shutdown to be prolonged. This is set false by default.
      Parameters:
        `tidy` - true if you want this connection to be shut down on exit

    - #### toString

          public java.lang.String toString()

      Overrides:
        `toString` in class `java.lang.Object`