Connection (RapidContext 0.16 Java API)

java.lang.Object
- org.rapidcontext.core.storage.StorableObject
- - org.rapidcontext.core.type.Connection

```
public abstract class Connection
extends StorableObject
```
A connection to an external system. This is an abstract base class, providing a number of services:
- On-Demand Creation -- Both connections and their managed communication channels are created and initialized on demand.
- Usage Limits -- Configurable limits for the maximum number of communication channels are automatically upheld.
- Connection Pooling -- Communication channel pooling is built-in and enabled by implementing a few simple methods.
- Connection Sharing -- Communication channel sharing (multiple tasks sharing the same channel) is also built-in and easily enabled.
- Validation & Keep-Alive -- All channels are validated before usage and kept-alive with regular validation requests when pooled for reuse.
Version:

1.0

Author:

Per Cederberg

Field Summary

Fields
Modifier and Type	Field and Description
`static java.lang.String`	`KEY_MAX_IDLE_SECS` The dictionary key for the maximum idle time (in seconds).
`static java.lang.String`	`KEY_MAX_OPEN` The dictionary key for the maximum number of open channels.
`protected java.lang.String`	`lastError` The error message for the last error.
`protected long`	`lastUsedTime` The timestamp (in milliseconds) of the last usage time.
`static Path`	`PATH` The connection object storage path.

Fields inherited from class org.rapidcontext.core.storage.StorableObject
dict, KEY_CLASSNAME, KEY_ID, KEY_TYPE

Constructor Summary

Constructors
Modifier	Constructor and Description
`protected`	`Connection(java.lang.String id, java.lang.String type, Dict dict)` Creates a new connection from a serialized representation.

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`protected void`	`cleanupChannel(Channel channel)` Destroys and removes references to a channel.
`protected abstract Channel`	`createChannel()` Creates a new connection channel.
`protected void`	`destroy()` Destroys this connection.
`protected abstract void`	`destroyChannel(Channel channel)` Destroys a connection channel, freeing any resources used (such as database connections, networking sockets, etc).
`static Connection`	`find(Storage storage, java.lang.String id)` Searches for a specific connection in the storage.
`static Connection[]`	`findAll(Storage storage)` Searches for all connections in the storage.
`protected void`	`init()` Initializes this connection after loading it from a storage.
`protected boolean`	`isActive()` Checks if this object is in active use.
`java.lang.String`	`lastError()` Returns the error message for the last error.
`java.util.Date`	`lastUsed()` Returns the timestamp of the last connection usage.
`int`	`maxIdleSeconds()` Returns the maximum number of seconds a channel is allowed to be idle (in a pool).
`int`	`maxOpen()` Returns the maximum number of open channels.
`int`	`openChannels()` Returns the total number of open channels.
`protected void`	`passivate()` Attempts to deactivate this object.
`void`	`release(Channel channel)` Releases a previously reserved communication channel for this connection.
`Channel`	`reserve()` Reserves a communication channel for this connection.
`Dict`	`serialize()` Returns a serialized representation of this object.
`int`	`usedChannels()` Returns the number of channels in use (reserved).

Methods inherited from class org.rapidcontext.core.storage.StorableObject
activate, id, isModified, path, toString, type

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

- Field Detail
  - KEY_MAX_OPEN
```
public static final java.lang.String KEY_MAX_OPEN
```
    The dictionary key for the maximum number of open channels.
    
    See Also:
    
    Constant Field Values
  - KEY_MAX_IDLE_SECS
```
public static final java.lang.String KEY_MAX_IDLE_SECS
```
    The dictionary key for the maximum idle time (in seconds).
    
    See Also:
    
    Constant Field Values
  - PATH
```
public static final Path PATH
```
    The connection object storage path.
  - lastUsedTime
```
protected long lastUsedTime
```
    The timestamp (in milliseconds) of the last usage time. This will be updated on each connection reservation or release. It is used in the default mechanism for determining if the connection is active.
  - lastError
```
protected java.lang.String lastError
```
    The error message for the last error. This will set or cleared on each connection reservation.
- Constructor Detail
  - Connection
```
protected Connection(java.lang.String id,
                     java.lang.String type,
                     Dict dict)
```
    Creates a new connection from a serialized representation.
    
    Parameters:
    
    id - the object identifier
    
    type - the object type name
    
    dict - the serialized representation
    
    See Also:
    
    init()
- Method Detail
  - find
```
public static Connection find(Storage storage,
                              java.lang.String id)
```
    Searches for a specific connection in the storage.
    
    Parameters:
    
    storage - the storage to search in
    
    id - the connection identifier
    
    Returns:
    
    the connection found, or null if not found
  - findAll
```
public static Connection[] findAll(Storage storage)
```
    Searches for all connections in the storage.
    
    Parameters:
    
    storage - the storage to search in
    
    Returns:
    
    an array of all connections found
  - isActive
```
protected boolean isActive()
```
    Checks if this object is in active use. This method will only return false if the object haven't been used for 60 seconds and no channels remain open.
    
    Overrides:
    
    isActive in class StorableObject
    
    Returns:
    
    true if the object is considered active, or false otherwise
  - init
```
protected void init()
             throws StorageException
```
    Initializes this connection after loading it from a storage. Any object initialization that may fail or that causes the object to interact with any other part of the system (or external systems) should be implemented here.
    
    Overrides:
    
    init in class StorableObject
    
    Throws:
    
    StorageException - if the initialization failed
  - destroy
```
protected void destroy()
```
    Destroys this connection. This method is used to free any resources used when this object is no longer used. This method is called when an object is removed from the in-memory storage (object cache).
    
    Overrides:
    
    destroy in class StorableObject
  - passivate
```
protected void passivate()
```
    Attempts to deactivate this object. This method will evict old connection channels from the pool and should only be called from a background job.
    
    Overrides:
    
    passivate in class StorableObject
  - serialize
```
public Dict serialize()
```
    Returns a serialized representation of this object. Used when accessing the object from outside pure Java.
    
    Overrides:
    
    serialize in class StorableObject
    
    Returns:
    
    the serialized representation of this object
  - maxOpen
```
public int maxOpen()
```
    Returns the maximum number of open channels. If the config parameter hasn't been set, a default value of four (4) will be returned.
    
    Returns:
    
    the maximum number of open channels
  - maxIdleSeconds
```
public int maxIdleSeconds()
```
    Returns the maximum number of seconds a channel is allowed to be idle (in a pool). If the configuration parameter hasn't been set, a default value of 600 seconds (10 minutes) will be returned.
    
    Returns:
    
    the maximum number of seconds to idle a channel
  - openChannels
```
public int openChannels()
```
    Returns the total number of open channels. This is the number of reserved channels plus any idle channels in the pool (if any).
    
    Returns:
    
    the total number of open channels, or zero (0) if no channels are currently open
  - usedChannels
```
public int usedChannels()
```
    Returns the number of channels in use (reserved).
    
    Returns:
    
    the number of channels in use
  - lastUsed
```
public java.util.Date lastUsed()
```
    Returns the timestamp of the last connection usage. This will be updated on each connection reservation or release. It is used in the default mechanism for determining if the connection is active.
    
    Returns:
    
    the timestamp of the last connection usage
  - lastError
```
public java.lang.String lastError()
```
    Returns the error message for the last error. This will set or cleared on each connection reservation.
    
    Returns:
    
    the error message for the last error
  - reserve
```
public Channel reserve()
                throws ConnectionException
```
    Reserves a communication channel for this connection. If the channels supports being pooled, a previously created channel may be returned from this method.
    
    Returns:
    
    the reserved connection channel
    
    Throws:
    
    ConnectionException - if no communication channel could be created and validated
  - release
```
public void release(Channel channel)
```
    Releases a previously reserved communication channel for this connection. If the channel supports being pooled, it will be added to the pool of channels, otherwise it will be destroyed immediately.
    
    Parameters:
    
    channel - the channel to release
  - cleanupChannel
```
protected void cleanupChannel(Channel channel)
```
    Destroys and removes references to a channel. No errors are logged, so this method should only be used after other errors have already been reported.
    
    Parameters:
    
    channel - the channel to destroy
  - createChannel
```
protected abstract Channel createChannel()
                                  throws ConnectionException
```
    Creates a new connection channel.
    
    Returns:
    
    the channel created
    
    Throws:
    
    ConnectionException - if the channel couldn't be created properly
  - destroyChannel
```
protected abstract void destroyChannel(Channel channel)
```
    Destroys a connection channel, freeing any resources used (such as database connections, networking sockets, etc).
    
    Parameters:
    
    channel - the channel to destroy

Class Connection

Field Summary

Fields inherited from class org.rapidcontext.core.storage.StorableObject

Constructor Summary

Method Summary

Methods inherited from class org.rapidcontext.core.storage.StorableObject

Methods inherited from class java.lang.Object

Field Detail

KEY_MAX_OPEN

KEY_MAX_IDLE_SECS

PATH

lastUsedTime

lastError

Constructor Detail

Connection

Method Detail

find

findAll

isActive

init

destroy

passivate

serialize

maxOpen

maxIdleSeconds

openChannels

usedChannels

lastUsed

lastError

reserve

release

cleanupChannel

createChannel

destroyChannel