--- /dev/null
+/*\r
+\r
+ Derby - Class org.apache.derby.jdbc.EmbeddedDataSource40\r
+\r
+ Licensed to the Apache Software Foundation (ASF) under one or more\r
+ contributor license agreements. See the NOTICE file distributed with\r
+ this work for additional information regarding copyright ownership.\r
+ The ASF licenses this file to You under the Apache License, Version 2.0\r
+ (the "License"); you may not use this file except in compliance with\r
+ the License. You may obtain a copy of the License at\r
+\r
+ http://www.apache.org/licenses/LICENSE-2.0\r
+\r
+ Unless required by applicable law or agreed to in writing, software\r
+ distributed under the License is distributed on an "AS IS" BASIS,\r
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\r
+ See the License for the specific language governing permissions and\r
+ limitations under the License.\r
+\r
+ */\r
+\r
+package org.apache.derby.jdbc;\r
+\r
+import java.sql.SQLException;\r
+import javax.sql.DataSource;\r
+\r
+import org.apache.derby.impl.jdbc.Util;\r
+import org.apache.derby.iapi.reference.SQLState;\r
+\r
+/** \r
+ \r
+\r
+ EmbeddedDataSource40 is Derby's DataSource implementation for JDBC4.0.\r
+ \r
+\r
+ <P>A DataSource is a factory for Connection objects. An object that\r
+ implements the DataSource interface will typically be registered with a\r
+ JNDI service provider.\r
+ <P>\r
+ EmbeddedDataSource40 supports the JDBC 4.0 specification\r
+ for the J2SE 6.0 Java Virtual Machine environment. Use EmbeddedDataSource\r
+ if your application is running in one of the following older\r
+ environments:\r
+ <UL>\r
+ <LI> JDBC 3.0 - Java 2 - JDK 1.4, J2SE 5.0\r
+ </UL> \r
+\r
+ <P>The following is a list of properties that can be set on a Derby\r
+ DataSource object:\r
+ <P><B>Standard DataSource properties</B> (from JDBC 3.0 specification).\r
+\r
+ <UL><LI><B><code>databaseName</code></B> (String): <I>Mandatory</I>\r
+ <BR>This property must be set and it\r
+ identifies which database to access. If a database named wombat located at\r
+ g:/db/wombat is to be accessed, then one should call\r
+ <code>setDatabaseName("g:/db/wombat")</code> on the data source object.</LI>\r
+\r
+ <LI><B><code>dataSourceName</code></B> (String): <I>Optional</I>\r
+ <BR> Name for DataSource. Not used by the data source object. Used for\r
+ informational purpose only.</LI>\r
+\r
+ <LI><B><code>description</code></B> (String): <I>Optional</I>\r
+ <BR>Description of the data source. Not\r
+ used by the data source object. Used for informational purpose only.</LI> \r
+\r
+ <LI><B><code>password</code></B> (String): <I>Optional</I>\r
+ <BR>Database password for the no argument <code>DataSource.getConnection()</code>,\r
+ <code>ConnectionPoolDataSource.getPooledConnection()</code>\r
+ and <code>XADataSource.getXAConnection()</code> methods.\r
+\r
+ <LI><B><code>user</code></B> (String): <I>Optional</I>\r
+ <BR>Database user for the no argument <code>DataSource.getConnection()</code>,\r
+ <code>ConnectionPoolDataSource.getPooledConnection()</code>\r
+ and <code>XADataSource.getXAConnection()</code> methods.\r
+ </UL>\r
+\r
+ <BR><B>Derby specific DataSource properties.</B>\r
+\r
+ <UL>\r
+\r
+ <LI><B><code>attributesAsPassword</code></B> (Boolean): <I>Optional</I>\r
+ <BR>If true, treat the password value in a\r
+ <code>DataSource.getConnection(String user, String password)</code>,\r
+ <code>ConnectionPoolDataSource.getPooledConnection(String user, String password)</code>\r
+ or <code>XADataSource.getXAConnection(String user, String password)</code> as a set\r
+ of connection attributes. The format of the attributes is the same as the format\r
+ of the attributes in the property connectionAttributes. If false the password value\r
+ is treated normally as the password for the given user.\r
+ Setting this property to true allows a connection request from an application to\r
+ provide more authentication information that just a password, for example the request\r
+ can include the user's password and an encrypted database's boot password.</LI>\r
+\r
+ <LI><B><code>connectionAttributes</code></B> (String): <I>Optional</I>\r
+ <BR>Defines a set of Derby connection attributes for use in all connection requests.\r
+ The format of the String matches the format of the connection attributes in a Derby JDBC URL.\r
+ That is a list of attributes in the form <code><I>attribute</I>=<I>value</I></code>, each separated by semi-colon (';').\r
+ E.g. <code>setConnectionAttributes("bootPassword=erd3234dggd3kazkj3000");</code>.\r
+ <BR>The database name must be set by the DataSource property <code>databaseName</code> and not by setting the <code>databaseName</code>\r
+ connection attribute in the <code>connectionAttributes</code> property.\r
+ <BR>\r
+ Any attributes that can be set using a property of this DataSource implementation\r
+ (e.g user, password) should not be set in connectionAttributes. Conflicting\r
+ settings in connectionAttributes and properties of the DataSource will lead to\r
+ unexpected behaviour. \r
+ <BR>Please see the Derby documentation for a complete list of connection attributes. </LI>\r
+\r
+ <LI><B><code>createDatabase</code></B> (String): <I>Optional</I>\r
+ <BR>If set to the string "create", this will\r
+ cause a new database of <code>databaseName</code> if that database does not already\r
+ exist. The database is created when a connection object is obtained from\r
+ the data source. </LI> \r
+\r
+ <LI><B><code>shutdownDatabase</code></B> (String): <I>Optional</I>\r
+ <BR>If set to the string "shutdown",\r
+ this will cause the database to shutdown when a java.sql.Connection object\r
+ is obtained from the data source. E.g., If the data source is an\r
+ XADataSource, a getXAConnection().getConnection() is necessary to cause the\r
+ database to shutdown.\r
+\r
+ </UL>\r
+\r
+ <P><B>Examples.</B>\r
+\r
+ <P>This is an example of setting a property directly using Derby's\r
+ EmbeddedDataSource40 object. This code is typically written by a system integrator :\r
+ <PRE> \r
+ *\r
+ * import org.apache.derby.jdbc.*;\r
+ *\r
+ * // dbname is the database name\r
+ * // if create is true, create the database if necessary\r
+ * javax.sql.DataSource makeDataSource (String dbname, boolean create)\r
+ * throws Throwable \r
+ * { \r
+ * EmbeddedDataSource40 ds = new EmbeddedDataSource40(); \r
+ * ds.setDatabaseName(dbname);\r
+ *\r
+ * if (create)\r
+ * ds.setCreateDatabase("create");\r
+ * \r
+ * return ds;\r
+ * }\r
+ </PRE>\r
+\r
+ <P>Example of setting properties thru reflection. This code is typically\r
+ generated by tools or written by a system integrator: <PRE>\r
+ * \r
+ * javax.sql.DataSource makeDataSource(String dbname) \r
+ * throws Throwable \r
+ * {\r
+ * Class[] parameter = new Class[1];\r
+ * parameter[0] = dbname.getClass();\r
+ * DataSource ds = new EmbeddedDataSource40();\r
+ * Class cl = ds.getClass();\r
+ *\r
+ * Method setName = cl.getMethod("setDatabaseName", parameter);\r
+ * Object[] arg = new Object[1];\r
+ * arg[0] = dbname;\r
+ * setName.invoke(ds, arg);\r
+ *\r
+ * return ds;\r
+ * }\r
+ </PRE>\r
+\r
+ <P>Example on how to register a data source object with a JNDI naming\r
+ service.\r
+ <PRE>\r
+ * DataSource ds = makeDataSource("mydb");\r
+ * Context ctx = new InitialContext();\r
+ * ctx.bind("jdbc/MyDB", ds);\r
+ </PRE>\r
+\r
+ <P>Example on how to retrieve a data source object from a JNDI naming\r
+ service. \r
+ <PRE>\r
+ * Context ctx = new InitialContext();\r
+ * DataSource ds = (DataSource)ctx.lookup("jdbc/MyDB");\r
+ </PRE>\r
+\r
+*/\r
+public class EmbeddedDataSource40 extends EmbeddedDataSource {\r
+ \r
+ public EmbeddedDataSource40() {\r
+ }\r
+ \r
+ /**\r
+ * Returns false unless <code>interfaces</code> is implemented \r
+ * \r
+ * @param interfaces a Class defining an interface.\r
+ * @return true if this implements the interface or \r
+ * directly or indirectly wraps an object \r
+ * that does.\r
+ * @throws java.sql.SQLException if an error occurs while determining \r
+ * whether this is a wrapper for an object \r
+ * with the given interface.\r
+ */\r
+ public boolean isWrapperFor(Class<?> interfaces) throws SQLException {\r
+ return interfaces.isInstance(this);\r
+ }\r
+ \r
+ /**\r
+ * Returns <code>this</code> if this class implements the interface\r
+ *\r
+ * @param interfaces a Class defining an interface\r
+ * @return an object that implements the interface\r
+ * @throws java.sql.SQLExption if no object if found that implements the \r
+ * interface\r
+ */\r
+ public <T> T unwrap(java.lang.Class<T> interfaces) \r
+ throws SQLException{\r
+ //Derby does not implement non-standard methods on \r
+ //JDBC objects\r
+ //hence return this if this class implements the interface \r
+ //or throw an SQLException\r
+ try {\r
+ return interfaces.cast(this);\r
+ } catch (ClassCastException cce) {\r
+ throw Util.generateCsSQLException(SQLState.UNABLE_TO_UNWRAP,\r
+ interfaces);\r
+ }\r
+ }\r
+}\r