001: /*
002: * Copyright 2001-2007 Geert Bevin <gbevin[remove] at uwyn dot com>
003: * Distributed under the terms of either:
004: * - the common development and distribution license (CDDL), v1.0; or
005: * - the GNU Lesser General Public License, v2.1 or later
006: * $Id: DbConnectionUser.java 3634 2007-01-08 21:42:24Z gbevin $
007: */
008: package com.uwyn.rife.database;
009:
010: /**
011: * By extending this class it's possible to provide the logic that should be
012: * executed by the {@link DbQueryManager#reserveConnection(DbConnectionUser)
013: * reserveConnection} method in the {@link DbQueryManager} class.
014: * <p>This class has both a default constructor and one that can take a data
015: * object. This can be handy when using it as an extending anonymous inner
016: * class when you need to use variables inside the inner class that are
017: * cumbersome to change to <code>final</code> in the enclosing class.
018: *
019: * @author JR Boyens (jboyens[remove] at uwyn dot com)
020: * @author Geert Bevin (gbevin[remove] at uwyn dot com)
021: * @version $Revision: 3634 $
022: * @see DbConnection
023: * @see DbQueryManager#reserveConnection(DbConnectionUser)
024: * @since 1.0
025: */
026: import com.uwyn.rife.tools.ExceptionUtils;
027: import com.uwyn.rife.tools.InnerClassException;
028: import java.util.logging.Logger;
029:
030: public abstract class DbConnectionUser<ResultType, DataType> implements
031: Cloneable {
032: protected DataType mData = null;
033:
034: /**
035: * Create a new DbConnectionUser.
036: *
037: * @since 1.0
038: */
039: public DbConnectionUser() {
040: }
041:
042: /**
043: * Create a new DbConnectionUser with a data object.
044: *
045: * @param data a user data object to be stored locally
046: * @since 1.0
047: */
048: public DbConnectionUser(DataType data) {
049: mData = data;
050: }
051:
052: /**
053: * Retrieve the data object that was provided to the constructor.
054: *
055: * @return the provided data object; or
056: * <p><code>null</code> if no data object was provided
057: * @since 1.0
058: */
059: public DataType getData() {
060: return mData;
061: }
062:
063: /**
064: * Calling this method makes it possible to throw a checked exception
065: * from within this class.
066: * <p>To catch it you should surround the {@link
067: * DbQueryManager#reserveConnection(DbConnectionUser)
068: * reserveConnection} with a <code>try-catch</code> block that catches
069: * <code>InnerClassException</code>. The original exception is then
070: * available through <code>getCause()</code> and can for example be
071: * rethrown.
072: *
073: * @param exception the exception to be thrown
074: * @exception InnerClassException when a checked exception needs to be
075: * thrown from within this class and caught outside the caller.
076: * @since 1.0
077: */
078: public void throwException(Exception exception)
079: throws InnerClassException {
080: throw new InnerClassException(exception);
081: }
082:
083: /**
084: * Should be implemented by all extending classes.
085: *
086: * @param connection the connection that should be used
087: * @since 1.0
088: */
089: public abstract ResultType useConnection(DbConnection connection)
090: throws InnerClassException;
091:
092: /**
093: * Simply clones the instance with the default clone method since this
094: * class contains no member variables.
095: *
096: * @since 1.0
097: */
098: public Object clone() {
099: try {
100: return super .clone();
101: } catch (CloneNotSupportedException e) {
102: // this should never happen
103: Logger.getLogger("com.uwyn.rife.database").severe(
104: ExceptionUtils.getExceptionStackTrace(e));
105: return null;
106: }
107: }
108: }
|