View Javadoc

1   package org.apache.torque.dsfactory;
2   
3   /*
4    * Copyright 2001-2005 The Apache Software Foundation.
5    *
6    * Licensed under the Apache License, Version 2.0 (the "License")
7    * you may not use this file except in compliance with the License.
8    * You may obtain a copy of the License at
9    *
10   *     http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing, software
13   * distributed under the License is distributed on an "AS IS" BASIS,
14   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15   * See the License for the specific language governing permissions and
16   * limitations under the License.
17   */
18  
19  import javax.sql.DataSource;
20  import org.apache.commons.configuration.Configuration;
21  import org.apache.torque.TorqueException;
22  
23  /***
24   * A factory that returns a DataSource.
25   *
26   * @author <a href="mailto:jmcnally@apache.org">John McNally</a>
27   * @author <a href="mailto:fischer@seitenbau.de">Thomas Fischer</a>
28   * @version $Id: DataSourceFactory.java 239636 2005-08-24 12:38:09Z henning $
29   */
30  public interface DataSourceFactory
31  {
32      /***
33       * Key for the configuration which contains DataSourceFactories
34       */
35      public static final String DSFACTORY_KEY = "dsfactory";
36  
37      /***
38       *  Key for the configuration which contains the fully qualified name
39       *  of the factory implementation class
40       */
41      public static final String FACTORY_KEY = "factory";
42  
43      /***
44       * @return the <code>DataSource</code> configured by the factory.
45       * @throws TorqueException if the source can't be returned
46       */
47      DataSource getDataSource() throws TorqueException;
48  
49      /***
50       * Initialize the factory.
51       *
52       * @param configuration where to load the factory settings from
53       * @throws TorqueException Any exceptions caught during processing will be
54       *         rethrown wrapped into a TorqueException.
55       */
56      void initialize(Configuration configuration)
57          throws TorqueException;
58  
59      /***
60       * Sets the current schema for the database connection
61       *
62       * @param schema The current schema name
63       */
64      void setSchema(String schema);
65  
66      /***
67       * This method returns the current schema for the database connection
68       *
69       * @return The current schema name. Null means, no schema has been set.
70       * @throws TorqueException Any exceptions caught during processing will be
71       *         rethrown wrapped into a TorqueException.
72       */
73      String getSchema();
74  
75      /***
76       * A hook which is called when the resources of the associated DataSource
77       * can be released.
78       * After close() is called, the other methods may not work any more
79       * (e.g. getDataSource() might return null).
80       * It is not guaranteed that this method does anything. For example,
81       * we do not want to close connections retrieved via JNDI, so the
82       * JndiDataSouurceFactory does not close these connections
83       *
84       * @throws TorqueException Any exceptions caught during processing will be
85       *         rethrown wrapped into a TorqueException.
86       */
87      void close()
88          throws TorqueException;
89  
90  }