001: /*
002:
003: Derby - Class org.apache.derby.jdbc.EmbeddedDataSource40
004:
005: Licensed to the Apache Software Foundation (ASF) under one or more
006: contributor license agreements. See the NOTICE file distributed with
007: this work for additional information regarding copyright ownership.
008: The ASF licenses this file to You under the Apache License, Version 2.0
009: (the "License"); you may not use this file except in compliance with
010: the License. You may obtain a copy of the License at
011:
012: http://www.apache.org/licenses/LICENSE-2.0
013:
014: Unless required by applicable law or agreed to in writing, software
015: distributed under the License is distributed on an "AS IS" BASIS,
016: WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
017: See the License for the specific language governing permissions and
018: limitations under the License.
019:
020: */
021:
022: package org.apache.derby.jdbc;
023:
024: import java.sql.SQLException;
025: import javax.sql.DataSource;
026:
027: import org.apache.derby.impl.jdbc.Util;
028: import org.apache.derby.iapi.reference.SQLState;
029:
030: /**
031:
032:
033: EmbeddedDataSource40 is Derby's DataSource implementation for JDBC4.0.
034:
035:
036: <P>A DataSource is a factory for Connection objects. An object that
037: implements the DataSource interface will typically be registered with a
038: JNDI service provider.
039: <P>
040: EmbeddedDataSource40 supports the JDBC 4.0 specification
041: for the J2SE 6.0 Java Virtual Machine environment. Use EmbeddedDataSource
042: if your application is running in one of the following older
043: environments:
044: <UL>
045: <LI> JDBC 3.0 - Java 2 - JDK 1.4, J2SE 5.0
046: <LI> JDBC 2.0 - Java 2 - JDK 1.2,1.3
047: </UL>
048:
049: <P>The following is a list of properties that can be set on a Derby
050: DataSource object:
051: <P><B>Standard DataSource properties</B> (from JDBC 3.0 specification).
052:
053: <UL><LI><B><code>databaseName</code></B> (String): <I>Mandatory</I>
054: <BR>This property must be set and it
055: identifies which database to access. If a database named wombat located at
056: g:/db/wombat is to be accessed, then one should call
057: <code>setDatabaseName("g:/db/wombat")</code> on the data source object.</LI>
058:
059: <LI><B><code>dataSourceName</code></B> (String): <I>Optional</I>
060: <BR> Name for DataSource. Not used by the data source object. Used for
061: informational purpose only.</LI>
062:
063: <LI><B><code>description</code></B> (String): <I>Optional</I>
064: <BR>Description of the data source. Not
065: used by the data source object. Used for informational purpose only.</LI>
066:
067: <LI><B><code>password</code></B> (String): <I>Optional</I>
068: <BR>Database password for the no argument <code>DataSource.getConnection()</code>,
069: <code>ConnectionPoolDataSource.getPooledConnection()</code>
070: and <code>XADataSource.getXAConnection()</code> methods.
071:
072: <LI><B><code>user</code></B> (String): <I>Optional</I>
073: <BR>Database user for the no argument <code>DataSource.getConnection()</code>,
074: <code>ConnectionPoolDataSource.getPooledConnection()</code>
075: and <code>XADataSource.getXAConnection()</code> methods.
076: </UL>
077:
078: <BR><B>Derby specific DataSource properties.</B>
079:
080: <UL>
081:
082: <LI><B><code>attributesAsPassword</code></B> (Boolean): <I>Optional</I>
083: <BR>If true, treat the password value in a
084: <code>DataSource.getConnection(String user, String password)</code>,
085: <code>ConnectionPoolDataSource.getPooledConnection(String user, String password)</code>
086: or <code>XADataSource.getXAConnection(String user, String password)</code> as a set
087: of connection attributes. The format of the attributes is the same as the format
088: of the attributes in the property connectionAttributes. If false the password value
089: is treated normally as the password for the given user.
090: Setting this property to true allows a connection request from an application to
091: provide more authentication information that just a password, for example the request
092: can include the user's password and an encrypted database's boot password.</LI>
093:
094: <LI><B><code>connectionAttributes</code></B> (String): <I>Optional</I>
095: <BR>Defines a set of Derby connection attributes for use in all connection requests.
096: The format of the String matches the format of the connection attributes in a Derby JDBC URL.
097: That is a list of attributes in the form <code><I>attribute</I>=<I>value</I></code>, each separated by semi-colon (';').
098: E.g. <code>setConnectionAttributes("bootPassword=erd3234dggd3kazkj3000");</code>.
099: <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<?> interfaces)
199: throws SQLException {
200: return interfaces.isInstance(this );
201: }
202:
203: /**
204: * Returns <code>this</code> if this class implements the interface
205: *
206: * @param interfaces a Class defining an interface
207: * @return an object that implements the interface
208: * @throws java.sql.SQLExption if no object if found that implements the
209: * interface
210: */
211: public <T> T unwrap(java.lang.Class<T> interfaces)
212: throws SQLException {
213: //Derby does not implement non-standard methods on
214: //JDBC objects
215: //hence return this if this class implements the interface
216: //or throw an SQLException
217: try {
218: return interfaces.cast(this );
219: } catch (ClassCastException cce) {
220: throw Util.generateCsSQLException(
221: SQLState.UNABLE_TO_UNWRAP, interfaces);
222: }
223: }
224: }
|