KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > derby > jdbc > EmbeddedDataSource40


1 /*
2
3    Derby - Class org.apache.derby.jdbc.EmbeddedDataSource40
4
5    Licensed to the Apache Software Foundation (ASF) under one or more
6    contributor license agreements. See the NOTICE file distributed with
7    this work for additional information regarding copyright ownership.
8    The ASF licenses this file to You under the Apache License, Version 2.0
9    (the "License"); you may not use this file except in compliance with
10    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, software
15    distributed under the License is distributed on an "AS IS" BASIS,
16    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17    See the License for the specific language governing permissions and
18    limitations under the License.
19
20  */
21
22 package org.apache.derby.jdbc;
23
24 import java.sql.SQLException JavaDoc;
25 import javax.sql.DataSource JavaDoc;
26
27 import org.apache.derby.impl.jdbc.Util;
28 import org.apache.derby.iapi.reference.SQLState;
29
30 /**
31     
32
33     EmbeddedDataSource40 is Derby's DataSource implementation for JDBC4.0.
34     
35
36     <P>A DataSource is a factory for Connection objects. An object that
37     implements the DataSource interface will typically be registered with a
38     JNDI service provider.
39     <P>
40     EmbeddedDataSource40 supports the JDBC 4.0 specification
41     for the J2SE 6.0 Java Virtual Machine environment. Use EmbeddedDataSource
42     if your application is running in one of the following older
43     environments:
44     <UL>
45     <LI> JDBC 3.0 - Java 2 - JDK 1.4, J2SE 5.0
46     <LI> JDBC 2.0 - Java 2 - JDK 1.2,1.3
47     </UL>
48
49     <P>The following is a list of properties that can be set on a Derby
50     DataSource object:
51     <P><B>Standard DataSource properties</B> (from JDBC 3.0 specification).
52
53     <UL><LI><B><code>databaseName</code></B> (String): <I>Mandatory</I>
54     <BR>This property must be set and it
55     identifies which database to access. If a database named wombat located at
56     g:/db/wombat is to be accessed, then one should call
57     <code>setDatabaseName("g:/db/wombat")</code> on the data source object.</LI>
58
59     <LI><B><code>dataSourceName</code></B> (String): <I>Optional</I>
60     <BR> Name for DataSource. Not used by the data source object. Used for
61     informational purpose only.</LI>
62
63     <LI><B><code>description</code></B> (String): <I>Optional</I>
64     <BR>Description of the data source. Not
65     used by the data source object. Used for informational purpose only.</LI>
66
67     <LI><B><code>password</code></B> (String): <I>Optional</I>
68     <BR>Database password for the no argument <code>DataSource.getConnection()</code>,
69     <code>ConnectionPoolDataSource.getPooledConnection()</code>
70     and <code>XADataSource.getXAConnection()</code> methods.
71
72     <LI><B><code>user</code></B> (String): <I>Optional</I>
73     <BR>Database user for the no argument <code>DataSource.getConnection()</code>,
74     <code>ConnectionPoolDataSource.getPooledConnection()</code>
75     and <code>XADataSource.getXAConnection()</code> methods.
76     </UL>
77
78     <BR><B>Derby specific DataSource properties.</B>
79
80   <UL>
81
82   <LI><B><code>attributesAsPassword</code></B> (Boolean): <I>Optional</I>
83     <BR>If true, treat the password value in a
84     <code>DataSource.getConnection(String user, String password)</code>,
85     <code>ConnectionPoolDataSource.getPooledConnection(String user, String password)</code>
86     or <code>XADataSource.getXAConnection(String user, String password)</code> as a set
87     of connection attributes. The format of the attributes is the same as the format
88     of the attributes in the property connectionAttributes. If false the password value
89     is treated normally as the password for the given user.
90     Setting this property to true allows a connection request from an application to
91     provide more authentication information that just a password, for example the request
92     can include the user's password and an encrypted database's boot password.</LI>
93
94   <LI><B><code>connectionAttributes</code></B> (String): <I>Optional</I>
95   <BR>Defines a set of Derby connection attributes for use in all connection requests.
96   The format of the String matches the format of the connection attributes in a Derby JDBC URL.
97   That is a list of attributes in the form <code><I>attribute</I>=<I>value</I></code>, each separated by semi-colon (';').
98   E.g. <code>setConnectionAttributes("bootPassword=erd3234dggd3kazkj3000");</code>.
99   <BR>The database name must be set by the DataSource property <code>databaseName</code> and not by setting the <code>databaseName</code>
100   connection attribute in the <code>connectionAttributes</code> property.
101     <BR>
102    Any attributes that can be set using a property of this DataSource implementation
103    (e.g user, password) should not be set in connectionAttributes. Conflicting
104    settings in connectionAttributes and properties of the DataSource will lead to
105    unexpected behaviour.
106   <BR>Please see the Derby documentation for a complete list of connection attributes. </LI>
107
108   <LI><B><code>createDatabase</code></B> (String): <I>Optional</I>
109     <BR>If set to the string "create", this will
110     cause a new database of <code>databaseName</code> if that database does not already
111     exist. The database is created when a connection object is obtained from
112     the data source. </LI>
113
114     <LI><B><code>shutdownDatabase</code></B> (String): <I>Optional</I>
115     <BR>If set to the string "shutdown",
116     this will cause the database to shutdown when a java.sql.Connection object
117     is obtained from the data source. E.g., If the data source is an
118     XADataSource, a getXAConnection().getConnection() is necessary to cause the
119     database to shutdown.
120
121     </UL>
122
123     <P><B>Examples.</B>
124
125     <P>This is an example of setting a property directly using Derby's
126     EmbeddedDataSource40 object. This code is typically written by a system integrator :
127     <PRE>
128     *
129     * import org.apache.derby.jdbc.*;
130     *
131     * // dbname is the database name
132     * // if create is true, create the database if necessary
133     * javax.sql.DataSource makeDataSource (String dbname, boolean create)
134     * throws Throwable
135     * {
136     * EmbeddedDataSource40 ds = new EmbeddedDataSource40();
137     * ds.setDatabaseName(dbname);
138     *
139     * if (create)
140     * ds.setCreateDatabase("create");
141     *
142     * return ds;
143     * }
144     </PRE>
145
146     <P>Example of setting properties thru reflection. This code is typically
147     generated by tools or written by a system integrator: <PRE>
148     *
149     * javax.sql.DataSource makeDataSource(String dbname)
150     * throws Throwable
151     * {
152     * Class[] parameter = new Class[1];
153     * parameter[0] = dbname.getClass();
154     * DataSource ds = new EmbeddedDataSource40();
155     * Class cl = ds.getClass();
156     *
157     * Method setName = cl.getMethod("setDatabaseName", parameter);
158     * Object[] arg = new Object[1];
159     * arg[0] = dbname;
160     * setName.invoke(ds, arg);
161     *
162     * return ds;
163     * }
164     </PRE>
165
166     <P>Example on how to register a data source object with a JNDI naming
167     service.
168     <PRE>
169     * DataSource ds = makeDataSource("mydb");
170     * Context ctx = new InitialContext();
171     * ctx.bind("jdbc/MyDB", ds);
172     </PRE>
173
174     <P>Example on how to retrieve a data source object from a JNDI naming
175     service.
176     <PRE>
177     * Context ctx = new InitialContext();
178     * DataSource ds = (DataSource)ctx.lookup("jdbc/MyDB");
179     </PRE>
180
181 */
182 public class EmbeddedDataSource40 extends EmbeddedDataSource {
183     
184     public EmbeddedDataSource40() {
185     }
186        
187     /**
188      * Returns false unless <code>interfaces</code> is implemented
189      *
190      * @param interfaces a Class defining an interface.
191      * @return true if this implements the interface or
192      * directly or indirectly wraps an object
193      * that does.
194      * @throws java.sql.SQLException if an error occurs while determining
195      * whether this is a wrapper for an object
196      * with the given interface.
197      */
198     public boolean isWrapperFor(Class JavaDoc<?> interfaces) throws SQLException JavaDoc {
199         return interfaces.isInstance(this);
200     }
201     
202     /**
203      * Returns <code>this</code> if this class implements the interface
204      *
205      * @param interfaces a Class defining an interface
206      * @return an object that implements the interface
207      * @throws java.sql.SQLExption if no object if found that implements the
208      * interface
209      */
210     public <T> T unwrap(java.lang.Class JavaDoc<T> interfaces)
211                             throws SQLException JavaDoc{
212         //Derby does not implement non-standard methods on
213 //JDBC objects
214 //hence return this if this class implements the interface
215 //or throw an SQLException
216 try {
217             return interfaces.cast(this);
218         } catch (ClassCastException JavaDoc cce) {
219             throw Util.generateCsSQLException(SQLState.UNABLE_TO_UNWRAP,
220                     interfaces);
221         }
222     }
223 }
224
Popular Tags