/**
* Copyright 2010 JBoss Inc
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package bitronix.tm.resource.common;
import java.util.List;
import java.util.Date;
/**
* Any pooled connection class must implement the {@link XAStatefulHolder} interface. It defines all the services
* that must be implemented by the connection as well as the pooling lifecycle states.
* Instances of this interface have to create and manage {@link XAResourceHolder}s.
* <p>© <a href="http://www.bitronix.be">Bitronix Software</a></p>
*
* @author lorban
*/
public interface XAStatefulHolder {
/**
* The state in which the resource is when it is closed and unusable.
*/
public final static int STATE_CLOSED = 0;
/**
* The state in which the resource is when it is available in the pool.
*/
public final static int STATE_IN_POOL = 1;
/**
* The state in which the resource is when it out of the pool but accessible by the application.
*/
public final static int STATE_ACCESSIBLE = 2;
/**
* The state in which the resource is when it out of the pool but not accessible by the application.
*/
public final static int STATE_NOT_ACCESSIBLE = 3;
/**
* Get the current resource state.
* <p>This method is thread-safe.</p>
* @return the current resource state.
*/
public int getState();
/**
* Set the current resource state.
* <p>This method is thread-safe.</p>
* @param state the current resource state.
*/
public void setState(int state);
/**
* Register an implementation of {@link StateChangeListener}.
* @param listener the {@link StateChangeListener} implementation to register.
*/
public void addStateChangeEventListener(StateChangeListener listener);
/**
* Unregister an implementation of {@link StateChangeListener}.
* @param listener the {@link StateChangeListener} implementation to unregister.
*/
public void removeStateChangeEventListener(StateChangeListener listener);
/**
* Get the list of {@link bitronix.tm.resource.common.XAResourceHolder}s created by this
* {@link bitronix.tm.resource.common.XAStatefulHolder} that are still open.
* <p>This method is thread-safe.</p>
* @return the list of {@link XAResourceHolder}s created by this
* {@link bitronix.tm.resource.common.XAStatefulHolder} that are still open.
*/
public List getXAResourceHolders();
/**
* Create a disposable handler used to drive a pooled instance of
* {@link bitronix.tm.resource.common.XAStatefulHolder}.
* <p>This method is thread-safe.</p>
* @return a resource-specific disaposable connection object.
* @throws Exception a resource-specific exception thrown when the disaposable connection cannot be created.
*/
public Object getConnectionHandle() throws Exception;
/**
* Close the physical connection that this {@link bitronix.tm.resource.common.XAStatefulHolder} represents.
* @throws Exception a resource-specific exception thrown when there is an error closing the physical connection.
*/
public void close() throws Exception;
/**
* Get the date at which this object was last released to the pool. This is required to check if it is eligible
* for discard when the containing pool needs to shrink.
* @return the date at which this object was last released to the pool or null if it never left the pool.
*/
public Date getLastReleaseDate();
}