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 org.jboss.resource.connectionmanager;
023:
024: import javax.resource.ResourceException;
025: import javax.resource.spi.ConnectionEventListener;
026: import javax.resource.spi.ManagedConnection;
027: import javax.transaction.SystemException;
028:
029: /**
030: * A jboss connection listener
031: *
032: * @author <a href="mailto:adrian@jboss.org">Adrian Brock</a>
033: * @author <a href="weston.price@jboss.com">Weston Price</a>
034: *
035: * @version $Revision: 57189 $
036: */
037: public interface ConnectionListener extends ConnectionEventListener {
038: /** Normal state */
039: public static final int NORMAL = 0;
040:
041: /** Destroy this connection */
042: public static final int DESTROY = 1;
043:
044: /** This connection has been destroyed */
045: public static final int DESTROYED = 2;
046:
047: /**
048: * Retrieve the managed connection for this listener
049: *
050: * @return the managed connection
051: */
052: ManagedConnection getManagedConnection();
053:
054: /**
055: * Retrieve the managed connection pool for this listener
056: *
057: * @return the managed connection pool
058: */
059: ManagedConnectionPool getManagedConnectionPool();
060:
061: /**
062: * Tidyup<p>
063: *
064: * Invoked just before returning the connection to the pool
065: * when the connection is not being destroyed
066: *
067: * @throws ResourceException for any error
068: */
069: void tidyup() throws ResourceException;
070:
071: /**
072: * Retrieve the context used by the pool
073: *
074: * @return the context
075: */
076: Object getContext();
077:
078: /**
079: * Retrieve the state of this connection
080: *
081: * @return the state
082: */
083: int getState();
084:
085: /**
086: * Set the state of this connection
087: */
088: void setState(int newState);
089:
090: /**
091: * Has the connection timed out?
092: *
093: * @param timeout the timeout
094: * @return true for timed out, false otherwise
095: */
096: boolean isTimedOut(long timeout);
097:
098: /**
099: * Mark the connection as used
100: */
101: void used();
102:
103: /**
104: * Register a new connection
105: *
106: * @param handle the connection handle
107: */
108: void registerConnection(Object handle);
109:
110: /**
111: * Unregister a connection
112: *
113: * @param handle the connection handle
114: */
115: void unregisterConnection(Object handle);
116:
117: /**
118: * Is the managed connection free?
119: *
120: * @return true when it is free
121: */
122: boolean isManagedConnectionFree();
123:
124: /**
125: * Enlist the managed connection
126: */
127: void enlist() throws SystemException;
128:
129: /**
130: * Delist the managed connection
131: */
132: void delist() throws ResourceException;
133:
134: /**
135: * Get whether the listener is track by transaction
136: *
137: * @return true for track by transaction, false otherwise
138: */
139: boolean isTrackByTx();
140:
141: /**
142: * Set whether the listener is track by transaction
143: *
144: * @param trackByTx true for track by transaction, false otherwise
145: */
146: void setTrackByTx(boolean trackByTx);
147:
148: /**
149: * Whether the connection has a permit
150: *
151: * @return true when it has permit, false otherwise
152: */
153: boolean hasPermit();
154:
155: /**
156: * Tell the connection listener whether it owns the permit.
157: *
158: * @param value true for owning the permit, false otherwise
159: */
160: void grantPermit(boolean value);
161:
162: /**
163: * Retrieve the last time this connection was validated.
164: *
165: * @return the last time the connection was validated
166: */
167: long getLastValidatedTime();
168:
169: /**
170: * Set the last time, in milliseconds, that this connection was validated.
171: *
172: * @param interval the last time the connection was validated in milliseconds.
173: */
174: void setLastValidatedTime(long interval);
175:
176: }
|