org.rapidcontext.core.type

Class Channel

java.lang.Object

org.rapidcontext.core.type.Channel

public abstract class Channel
extends java.lang.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

Author:

Per Cederberg

Field Summary

Fields

Modifier and Type	Field and Description
protected Connection	connection The parent connection for this channel.
protected boolean	valid The valid channel flag.

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method and 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.
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 Detail

valid

protected boolean valid

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

connection

protected Connection connection

The parent connection for this channel.

Constructor Detail

Channel

protected Channel(Connection con)

Creates a new communications channel for the specified connection.

Parameters:

con - the parent connection

Method Detail

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:

isValid(), invalidate()

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:

isValid(), validate()

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.