View Javadoc

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