Email Answering System
Version 1.0

com.ninecode.email.connector
Class EmailManagedConnection

java.lang.Object
  |
  +--com.ninecode.email.connector.EmailManagedConnection
All Implemented Interfaces:
LocalTransaction, ManagedConnection

public class EmailManagedConnection
extends Object
implements ManagedConnection, LocalTransaction

Managed connection for the Connector architecture.

Author:
Derrick Oswald

Field Summary
protected  ArrayList mConnections
          The list of Connections handed out.
protected  EmailConfigurationData mData
          The configuration data associated with this managed connection.
protected  ArrayList mListeners
          The ConnectionListeners list.
protected  PrintWriter mPrintWriter
          The logging output stream.
protected  Session mSession
          The email session.
protected  EmailSource mSource
          The source corresponding to the 'store' configuration data.
protected  Transport mTransport
          The javax.mail Transport object for this connection.
 
Constructor Summary
EmailManagedConnection()
          Creates a new instance of EmailManagedConnection.
 
Method Summary
 void addConnectionEventListener(ConnectionEventListener listener)
          Adds a connection event listener to the ManagedConnection instance.
 void associateConnection(Object connection)
          Used by the container to change the association of an application-level connection handle with a ManagedConneciton instance.
 void begin()
          Begins a local transaction on an EIS instance.
 void cleanup()
          Application server calls this method to force any cleanup on the ManagedConnection instance.
protected  void closeConnection(EmailConnection connection)
          Close a connection created by this managed connection.
 void commit()
          Commits the current local transaction and release all locks held by the underlying EIS instance.
protected  Transport connectTransport()
          Connect to the transport.
 void destroy()
          Destroys the physical connection to the underlying resource manager.
protected  void disconnectTransport()
          Disconnect the Transport.
protected  EmailConfigurationData getConfigurationData()
          Getter for property configurationData.
protected  boolean getConnected()
          Report the connected state of this managed connection.
 Object getConnection(Subject subject, ConnectionRequestInfo info)
          Creates a new connection handle for the underlying physical connection represented by the ManagedConnection instance.
 LocalTransaction getLocalTransaction()
          Returns an javax.resource.spi.LocalTransaction instance.
 PrintWriter getLogWriter()
          Gets the log writer for this ManagedConnection instance.
protected  Message[] getMessages()
          Get any messages.
 ManagedConnectionMetaData getMetaData()
          Gets the metadata information for this connection's underlying EIS resource manager instance.
protected  Session getSession()
          Get the session associated with this connection.
protected  EmailSource getSource()
          Get the source associated with the 'store' connection data.
protected  Transport getTransport()
          Get the transport associated with this connection.
 XAResource getXAResource()
          Returns an javax.transaction.xa.XAresource instance.
protected  void notifyListeners(ConnectionEvent event, String call)
          Send an event to all listeners.
 void removeConnectionEventListener(ConnectionEventListener listener)
          Removes an already registered connection event listener from the ManagedConnection instance.
 void rollback()
          Rollbacks the current resource manager local transaction.
protected  void setConfigurationData(EmailConfigurationData data)
          Setter for property configurationData.
protected  void setConnected(boolean connect)
          Connect or disconnect the email session.
 void setLogWriter(PrintWriter writer)
          Sets the log writer for this ManagedConnection instance.
protected  void setSession(Session session)
          Set the session associated with this connection.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

mSession

protected Session mSession
The email session.


mData

protected EmailConfigurationData mData
The configuration data associated with this managed connection.


mTransport

protected Transport mTransport
The javax.mail Transport object for this connection.


mSource

protected EmailSource mSource
The source corresponding to the 'store' configuration data.


mPrintWriter

protected PrintWriter mPrintWriter
The logging output stream.


mListeners

protected ArrayList mListeners
The ConnectionListeners list.


mConnections

protected ArrayList mConnections
The list of Connections handed out.

Constructor Detail

EmailManagedConnection

public EmailManagedConnection()
Creates a new instance of EmailManagedConnection.

Method Detail

getSession

protected Session getSession()
Get the session associated with this connection.

Returns:
The session object.

setSession

protected void setSession(Session session)
Set the session associated with this connection.

Parameters:
session - The new session object.

getConfigurationData

protected EmailConfigurationData getConfigurationData()
Getter for property configurationData.

Returns:
Value of property connfigurationData.

setConfigurationData

protected void setConfigurationData(EmailConfigurationData data)
Setter for property configurationData.

Parameters:
data - New value of property configurationData.

getTransport

protected Transport getTransport()
Get the transport associated with this connection.

Returns:
The transport object.

getSource

protected EmailSource getSource()
                         throws ResourceException
Get the source associated with the 'store' connection data.

Returns:
The source object.
Throws:
ResourceException - If the source cannot be obtained.

getMessages

protected Message[] getMessages()
                         throws ResourceException,
                                MessagingException
Get any messages.

Returns:
Messages that were pending.
Throws:
ResourceException - If the source cannot be obtained.
MessagingException - If there is a problem retrieving messages.

connectTransport

protected Transport connectTransport()
                              throws ResourceException
Connect to the transport. Performs the actual connect on a Transport object obtained from the session.

Returns:
The connected Transport object.
Throws:
ResourceException - If a problem occurs, examples are:
  • There is no such Transport provider as getTransportProtocol()
  • The connect to the Transport failed.

  • disconnectTransport

    protected void disconnectTransport()
                                throws ResourceException
    Disconnect the Transport.

    Throws:
    ResourceException - If the close fails.

    setConnected

    protected void setConnected(boolean connect)
                         throws ResourceException
    Connect or disconnect the email session.

    Parameters:
    connect - If true and this managed connection is not already connected it performs a connect operation by getting a new email session and connecting to the Transport. If false and this managed connection is connected it disconnects by closing the Transport and nulling out the session.
    ResourceException

    getConnected

    protected boolean getConnected()
    Report the connected state of this managed connection.

    Returns:
    true if this managed connection is already connected, false otherwise.

    closeConnection

    protected void closeConnection(EmailConnection connection)
                            throws ResourceException
    Close a connection created by this managed connection.

    Parameters:
    connection - The connection to close.
    Throws:
    ResourceException - If there is a problem closing.

    notifyListeners

    protected void notifyListeners(ConnectionEvent event,
                                   String call)
                            throws ResourceException
    Send an event to all listeners.

    Parameters:
    event - The event to send.
    call - The ConnectionEventListener method to call.
    Throws:
    ResourceException - If the reflection invocation fails for some reason.

    addConnectionEventListener

    public void addConnectionEventListener(ConnectionEventListener listener)
    Adds a connection event listener to the ManagedConnection instance. The registered ConnectionEventListener instances are notified of connection close and error events, also of local transaction related events on the Managed Connection.

    Specified by:
    addConnectionEventListener in interface ManagedConnection
    Parameters:
    listener - A new ConnectionEventListener to be registered.

    removeConnectionEventListener

    public void removeConnectionEventListener(ConnectionEventListener listener)
    Removes an already registered connection event listener from the ManagedConnection instance.

    Specified by:
    removeConnectionEventListener in interface ManagedConnection
    Parameters:
    listener - Already registered connection event listener to be removed.

    associateConnection

    public void associateConnection(Object connection)
                             throws ResourceException
    Used by the container to change the association of an application-level connection handle with a ManagedConneciton instance. The container should find the right ManagedConnection instance and call the associateConnection method. The resource adapter is required to implement the associateConnection method. The method implementation for a ManagedConnection should dissociate the connection handle (passed as a parameter) from its currently associated ManagedConnection and associate the new connection handle with itself.

    Specified by:
    associateConnection in interface ManagedConnection
    Parameters:
    connection - Application-level connection handle.
    Throws:
    ResourceException - Failed to associate the connection handle with this ManagedConnection instance.
    IllegalStateException - Illegal state for invoking this method.
    ResourceAdapterInternalException - Resource adapter internal error condition.

    cleanup

    public void cleanup()
                 throws ResourceException
    Application server calls this method to force any cleanup on the ManagedConnection instance. The method ManagedConnection.cleanup initiates a cleanup of any client-specific state as maintained by a ManagedConnection instance. The cleanup should invalidate all connection handles that had been created using this ManagedConnection instance. Any attempt by an application component to use the connection handle after cleanup of the underlying ManagedConnection should result in an exception. The cleanup of ManagedConnection is always driven by an application server. An application server should not invoke ManagedConnection.cleanup when there is an uncompleted transaction (associated with a ManagedConnection instance) in progress. The invocation of ManagedConnection.cleanup method on an already cleaned-up connection should not throw an exception. The cleanup of ManagedConnection instance resets its client specific state and prepares the connection to be put back in to a connection pool. The cleanup method should not cause resource adapter to close the physical pipe and reclaim system resources associated with the physical connection.

    Specified by:
    cleanup in interface ManagedConnection
    Throws:
    ResourceException - Generic exception if operation fails.
    ResourceAdapterInternalException - Resource adapter internal error condition.
    IllegalStateException - Illegal state for calling connection cleanup. Example - if a localtransaction is in progress that doesn't allow connection cleanup

    destroy

    public void destroy()
                 throws ResourceException
    Destroys the physical connection to the underlying resource manager. To manage the size of the connection pool, an application server can explictly call ManagedConnection.destroy to destroy a physical connection. A resource adapter should destroy all allocated system resources for this ManagedConnection instance when the method destroy is called.

    Specified by:
    destroy in interface ManagedConnection
    Throws:
    ResourceException - Generic exception if operation failed.
    IllegalStateException - Illegal state for destroying connection.

    getConnection

    public Object getConnection(Subject subject,
                                ConnectionRequestInfo info)
                         throws ResourceException
    Creates a new connection handle for the underlying physical connection represented by the ManagedConnection instance. This connection handle is used by the application code to refer to the underlying physical connection. A connection handle is tied to its ManagedConnection instance in a resource adapter implementation specific way. The ManagedConnection uses the Subject and additional ConnectionRequestInfo (which is specific to resource adapter and opaque to application server) to set the state of the physical connection.

    Specified by:
    getConnection in interface ManagedConnection
    Parameters:
    subject - Security context as JAAS subject.
    info - ConnectionRequestInfo instance.
    Returns:
    Generic Object instance representing the connection handle. For CCI, the connection handle created by a ManagedConnection instance is of the type javax.resource.cci.Connection.
    Throws:
    ResourceException - Generic exception if operation fails.
    ResourceAdapterInternalException - Resource adapter internal error condition.
    SecurityException - Security related error condition.
    CommException - Failed communication with EIS instance.
    EISSystemException - Internal error condition in EIS instance - used if EIS instance is involved in setting state of ManagedConnection.

    getLocalTransaction

    public LocalTransaction getLocalTransaction()
                                         throws ResourceException
    Returns an javax.resource.spi.LocalTransaction instance. The LocalTransaction interface is used by the container to manage local transactions for a RM instance.

    Specified by:
    getLocalTransaction in interface ManagedConnection
    Returns:
    LocalTransaction instance.
    Throws:
    ResourceException - Generic exception if operation fails.
    NotSupportedException - If the operation is not supported.
    ResourceAdapterInternalException - Resource adapter internal error condition.

    getLogWriter

    public PrintWriter getLogWriter()
                             throws ResourceException
    Gets the log writer for this ManagedConnection instance. The log writer is a character output stream to which all logging and tracing messages for this ManagedConnection instance will be printed. ConnectionManager manages the association of output stream with the ManagedConnection instance based on the connection pooling requirements. The Log writer associated with a ManagedConnection instance can be one set as default from the ManagedConnectionFactory (that created this connection) or one set specifically for this instance by the application server.

    Specified by:
    getLogWriter in interface ManagedConnection
    Returns:
    Character output stream associated with this ManagedConnection instance.
    Throws:
    ResourceException - Generic exception if operation fails.

    getMetaData

    public ManagedConnectionMetaData getMetaData()
                                          throws ResourceException
    Gets the metadata information for this connection's underlying EIS resource manager instance. The ManagedConnectionMetaData interface provides information about the underlying EIS instance associated with the ManagedConenction instance.

    Specified by:
    getMetaData in interface ManagedConnection
    Returns:
    ManagedConnectionMetaData instance.
    Throws:
    ResourceException - Generic exception if operation fails.
    NotSupportedException - If the operation is not supported.

    getXAResource

    public XAResource getXAResource()
                             throws ResourceException
    Returns an javax.transaction.xa.XAresource instance. An application server enlists this XAResource instance with the Transaction Manager if the ManagedConnection instance is being used in a JTA transaction that is being coordinated by the Transaction Manager.

    Specified by:
    getXAResource in interface ManagedConnection
    Returns:
    XAResource instance.
    Throws:
    ResourceException - Generic exception if operation fails.
    NotSupportedException - If the operation is not supported.
    ResourceAdapterInternalException - Resource adapter internal error condition.

    setLogWriter

    public void setLogWriter(PrintWriter writer)
                      throws ResourceException
    Sets the log writer for this ManagedConnection instance. The log writer is a character output stream to which all logging and tracing messages for this ManagedConnection instance will be printed. Application Server manages the association of output stream with the ManagedConnection instance based on the connection pooling requirements. When a ManagedConnection object is initially created, the default log writer associated with this instance is obtained from the ManagedConnectionFactory. An application server can set a log writer specific to this ManagedConnection to log/trace this instance using setLogWriter method.

    Specified by:
    setLogWriter in interface ManagedConnection
    Parameters:
    writer - - Character Output stream to be associated.
    Throws:
    ResourceException - Generic exception if operation fails.
    ResourceAdapterInternalException - Resource adapter related error condition.

    commit

    public void commit()
                throws ResourceException
    Commits the current local transaction and release all locks held by the underlying EIS instance.

    Specified by:
    commit in interface LocalTransaction
    Throws:
    ResourceException - Failed to commit a local transaction. Examples of error cases are:
  • Resource adapter internal or EIS-specific error.
  • Violation of integrity constraints, deadlock detection, communication failure during transaction completion, or any retry requirement.
  • Connection is participating in an active JTA transaction.
  • Invalid transaction context; commit operation invoked without an active transaction context.

  • begin

    public void begin()
               throws ResourceException
    Begins a local transaction on an EIS instance.

    Specified by:
    begin in interface LocalTransaction
    Throws:
    ResourceException - Failed to begin a local transaction. Examples of error cases are:
  • Resource adapter internal or EIS-specific error.
  • Connection is already participating in a local or JTA transaction.

  • rollback

    public void rollback()
                  throws ResourceException
    Rollbacks the current resource manager local transaction.

    Specified by:
    rollback in interface LocalTransaction
    Throws:
    ResourceException - Failed to rollback a local transaction. Examples of error cases are:
  • Resource adapter internal or EIS-specific error.
  • Connection is participating in an active JTA transaction.
  • Invalid transaction context; rollback operation invoked without an active transaction context

  • Email Answering System
    Version 1.0

    Copyright © 2003 Derrick Oswald. All rights reserved.