Package org.rapidcontext.core.type

Class Connection

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 pooled channels are validated after usage and kept-alive with regular validation requests when pooled for reuse.
Version:
1.0

  • Field Details

    • KEY_MAX_OPEN

      public static final String KEY_MAX_OPEN
      The dictionary key for the maximum number of open channels.
      See Also:

    • KEY_MAX_IDLE_SECS

      public static final String KEY_MAX_IDLE_SECS
      The dictionary key for the maximum idle time (in seconds).
      See Also:

    • 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 String lastError
      The error message for the last error. This will set or cleared on each connection reservation.

  • Constructor Details

    • Connection

      protected Connection(String id, 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:

  • Method Details

    • find

      public static Connection find(Storage storage, 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

    • metrics

      public static Metrics metrics(Storage storage)
      Returns the connection usage metrics. The metrics will be loaded from storage if not already in memory.
      Parameters:
      storage - the storage to load from
      Returns:
      the connection usage metrics

    • 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

    • 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 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, or null if the connection hasn't been used

    • lastError

      public 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

    • report

      protected void report(long start, boolean success, String error)
      Reports connection usage metrics for a single query/request/etc. If the start time isn't positive, no actual usage and duration will be reported, only potential errors.
      Parameters:
      start - the start time (in millis), or zero (0) for none
      success - the success flag
      error - the optional error message

    • serialize

      public Dict serialize()
      Returns a serialized representation of this object. Used when persisting to permanent storage or when accessing the object from outside pure Java. Returns a shallow copy of the contained dictionary.
      Overrides:
      serialize in class StorableObject
      Returns:
      the serialized representation of this object