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(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.
void	revalidate()	Checks if the channel connection is still valid.
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:

• isValid()
• invalidate()

revalidate

public void revalidate()

Checks if the channel connection is still valid. This method also resets the last known error.

See Also:

• isValid()
• validate()

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()

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.