Package org.rapidcontext.core.type

Class Channel

java.lang.Object
org.rapidcontext.core.type.Channel
public abstract class Channel extends Object
A communications channel for a connection. A channel provides data transport to an external system, such as a database, a message bus or similar. Depending on the channel subclass, it might be possible to reuse a channel multiple times (resource pooling) or share it between several parallel tasks.
Version:
1.0

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected Connection
    connection
    The parent connection for this channel.
    protected int
    errors
    The recent error count.
    protected boolean
    valid
    The valid channel flag.

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    Channel(Connection con)
    Creates a new communications channel for the specified connection.

  • Method Summary

    Modifier and Type
    Method
    Description
    abstract void
    commit()
    Commits any pending changes.
    Connection
    getConnection()
    Returns the connection that this channel belongs to.
    void
    invalidate()
    Marks the channel as invalid, meaning that it should no longer be used and is scheduled for destruction when returned to the parent connection.
    protected abstract boolean
    isPoolable()
    Checks if this channel can be pooled (i.e.
    boolean
    isValid()
    Checks if this channel is considered valid.
    protected abstract void
    release()
    Releases and passivates the channel.
    void
    report(boolean success, String error)
    Deprecated, for removal: This API element is subject to removal in a future version.
    Use report(long, boolean, String) instead.
    void
    report(long start, boolean success, String error)
    Reports channel usage metrics for a single query/call/etc.
    protected abstract void
    reserve()
    Reserves and activates the channel.
    abstract void
    rollback()
    Rolls any pending changes back.
    abstract void
    validate()
    Checks if the channel connection is still valid.

    Methods inherited from class java.lang.Object

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

  • Field Details

    • valid

      protected boolean valid
      The valid channel flag. Should only be changed to false, never back to true.

    • errors

      protected int errors
      The recent error count. Will be set to zero (0) on success. If count reaches 3, the channel is invalidated.

    • connection

      protected Connection connection
      The parent connection for this channel.

  • Constructor Details

    • Channel

      protected Channel(Connection con)
      Creates a new communications channel for the specified connection.
      Parameters:
      con - the parent connection

  • Method Details

    • isValid

      public boolean isValid()
      Checks if this channel is considered valid.
      Returns:
      true if this channel is valid, or false otherwise

    • isPoolable

      protected abstract boolean isPoolable()
      Checks if this channel can be pooled (i.e. reused). This method should return the same value for all instances of a specific channel subclass.
      Returns:
      true if the channel can be pooled and reused, or false otherwise

    • getConnection

      public Connection getConnection()
      Returns the connection that this channel belongs to.
      Returns:
      the connection for this channel

    • reserve

      protected abstract void reserve() throws ConnectionException
      Reserves and activates the channel. This method is called just before a channel is to be used, i.e. when a new channel has been created or fetched from a resource pool.
      Throws:
      ConnectionException - if the channel couldn't be reserved (channel will be destroyed)

    • release

      protected abstract void release() throws ConnectionException
      Releases and passivates the channel. This method is called just after a channel has been used and returned. This should clear or reset the channel, so that it can safely be used again without affecting previous results or operations (if the channel is pooled).
      Throws:
      ConnectionException - if the channel couldn't be released (channel will be destroyed)

    • validate

      public abstract void validate()
      Checks if the channel connection is still valid. This method is called before using a channel and regularly when it is idle in the pool. It can be used to trigger a "ping" for a channel. This method can only mark a valid channel as invalid, never the other way around.
      See Also:

    • invalidate

      public void invalidate()
      Marks the channel as invalid, meaning that it should no longer be used and is scheduled for destruction when returned to the parent connection. During normal operations, this method should not be called, since it defeats the channel pooling capabilities used by some connections.
      See Also:

    • report

      @Deprecated(forRemoval=true) public void report(boolean success, String error)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use report(long, boolean, String) instead.
      Reports channel usage metrics for a single query/call/etc.
      Parameters:
      success - the success flag
      error - the optional error message

    • report

      public void report(long start, boolean success, String error)
      Reports channel usage metrics for a single query/call/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

    • commit

      public abstract void commit()
      Commits any pending changes. This method is called after each successful procedure tree execution that included this channel. This method may be implemented as a no-op, if no support for commit and rollback semantics is available.

      In case of error, a subclass should log the message and invalidate the channel.

    • rollback

      public abstract void rollback()
      Rolls any pending changes back. This method is called after an unsuccessful procedure tree execution that included this channel. This method may be implemented as a no-op, if no support for commit and rollback semantics is available.

      In case of error, a subclass should log the message and invalidate the channel.