001: /*
002: * JBoss, Home of Professional Open Source.
003: * Copyright 2006, Red Hat Middleware LLC, and individual contributors
004: * as indicated by the @author tags. See the copyright.txt file in the
005: * distribution for a full listing of individual contributors.
006: *
007: * This is free software; you can redistribute it and/or modify it
008: * under the terms of the GNU Lesser General Public License as
009: * published by the Free Software Foundation; either version 2.1 of
010: * the License, or (at your option) any later version.
011: *
012: * This software is distributed in the hope that it will be useful,
013: * but WITHOUT ANY WARRANTY; without even the implied warranty of
014: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
015: * Lesser General Public License for more details.
016: *
017: * You should have received a copy of the GNU Lesser General Public
018: * License along with this software; if not, write to the Free
019: * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
021: */
022: package javax.resource.spi;
023:
024: import java.io.PrintWriter;
025:
026: import javax.resource.ResourceException;
027: import javax.security.auth.Subject;
028: import javax.transaction.xa.XAResource;
029:
030: /**
031: * A ManagedConnection instance represents a connection to the underlying
032: * recource. A ManagedConnection provides access to the two transaction
033: * interfaces, XAResource and LocalTransaction. These interfaces are used to
034: * manage transactions on the resource.
035: */
036: public interface ManagedConnection {
037: /**
038: * Creates a new connection handle for the underlying connection.
039: *
040: * @param subject the subject
041: * @param cxRequestInfo the connection request info
042: * @throws ResourceException for a generic error
043: * @throws ResourceAdapterInternalException for an internal error in the
044: * resource adapter
045: * @throws SecurityException for a security problem
046: * @throws CommException for a communication failure with the EIS
047: * @throws EISSystemException for an error from the EIS
048: */
049: public Object getConnection(Subject subject,
050: ConnectionRequestInfo cxRequestInfo)
051: throws ResourceException;
052:
053: /**
054: * Destroys the connection to the underlying resource.
055: *
056: * @throws ResourceException for a generic error
057: * @throws IllegalStateException if the connection is not a legal state for destruction
058: */
059: public void destroy() throws ResourceException;
060:
061: /**
062: * Application server calls this to force cleanup of connection.
063: * @throws ResourceException for a generic error
064: * @throws ResourceAdapterInternalException for an internal error in the
065: * resource adapter
066: * @throws IllegalStateException if the connection is not a legal state for cleanup
067: */
068: public void cleanup() throws ResourceException;
069:
070: /**
071: * Associates a new application level connection handle with the connection.
072: *
073: * @param connection the connection
074: * @throws ResourceException for a generic error
075: * @throws IllegalStateException for an illegal state
076: * @throws ResourceAdapterInternalException for an internal error in the
077: * resource adapter
078: */
079: public void associateConnection(Object connection)
080: throws ResourceException;
081:
082: /**
083: * Adds a connection event listener
084: *
085: * @param listener the listener
086: */
087: public void addConnectionEventListener(
088: ConnectionEventListener listener);
089:
090: /**
091: * Removes a connection event listener
092: *
093: * @param listener the listener
094: */
095: public void removeConnectionEventListener(
096: ConnectionEventListener listener);
097:
098: /**
099: * Returns an XAResource instance.
100: *
101: * @return the XAResource
102: * @throws ResourceException for a generic error
103: * @throws NotSupportedException if not supported
104: * @throws ResourceAdapterInternalException for an internal error in the
105: * resource adapter
106: */
107: public XAResource getXAResource() throws ResourceException;
108:
109: /**
110: * Returns a LocalTransaction instance.
111: *
112: * @return the local transaction
113: * @throws ResourceException for a generic error
114: * @throws NotSupportedException if not supported
115: * @throws ResourceAdapterInternalException for an internal error in the
116: * resource adapter
117: */
118: public LocalTransaction getLocalTransaction()
119: throws ResourceException;
120:
121: /**
122: * Gets metadata inormation for this instances underlying resource manager
123: * instance.
124: *
125: * @return the managed connection meta data
126: * @throws ResourceException for a generic error
127: * @throws NotSupportedException if not supported
128: */
129: public ManagedConnectionMetaData getMetaData()
130: throws ResourceException;
131:
132: /**
133: * Gets the logwriter for this instance.
134: *
135: * @return the log writer
136: * @throws ResourceException for a generic error
137: */
138: public PrintWriter getLogWriter() throws ResourceException;
139:
140: /**
141: * Sets the logwriter for this instance.
142: *
143: * @param out the writer
144: * @throws ResourceException for a generic error
145: * @throws ResourceAdapterInternalException for an internal error in the
146: * resource adapter
147: */
148: public void setLogWriter(PrintWriter out) throws ResourceException;
149: }
|