EmbeddedDataSource40 (Apache Derby 10.3 API Documentation)
Date: 2007-08-01

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.apache.derby.jdbc
Class EmbeddedDataSource40

    java.lang.Object
      org.apache.derby.jdbc.ReferenceableDataSource
          org.apache.derby.jdbc.EmbeddedDataSource
              org.apache.derby.jdbc.EmbeddedDataSource40

All Implemented Interfaces:
  java.io.Serializable, java.sql.Wrapper, javax.naming.Referenceable, javax.naming.spi.ObjectFactory, javax.sql.CommonDataSource, javax.sql.DataSource

    public class EmbeddedDataSource40

extends org.apache.derby.jdbc.EmbeddedDataSource

EmbeddedDataSource40 is Derby's DataSource implementation for JDBC4.0.

A DataSource is a factory for Connection objects. An object that implements the DataSource interface will typically be registered with a JNDI service provider.

EmbeddedDataSource40 supports the JDBC 4.0 specification for the J2SE 6.0 Java Virtual Machine environment. Use EmbeddedDataSource if your application is running in one of the following older environments:

- JDBC 3.0 - Java 2 - JDK 1.4, J2SE 5.0

The following is a list of properties that can be set on a Derby DataSource object:

Standard DataSource properties (from JDBC 3.0 specification).

- `databaseName` (String): Mandatory
  This property must be set and it identifies which database to access. If a database named wombat located at g:/db/wombat is to be accessed, then one should call `setDatabaseName("g:/db/wombat")` on the data source object.
- `dataSourceName` (String): Optional
  Name for DataSource. Not used by the data source object. Used for informational purpose only.
- `description` (String): Optional
  Description of the data source. Not used by the data source object. Used for informational purpose only.
- `password` (String): Optional
  Database password for the no argument `DataSource.getConnection()`, `ConnectionPoolDataSource.getPooledConnection()` and `XADataSource.getXAConnection()` methods.
- `user` (String): Optional
  Database user for the no argument `DataSource.getConnection()`, `ConnectionPoolDataSource.getPooledConnection()` and `XADataSource.getXAConnection()` methods.

Derby specific DataSource properties.

- `attributesAsPassword` (Boolean): Optional
  If true, treat the password value in a `DataSource.getConnection(String user, String password)`, `ConnectionPoolDataSource.getPooledConnection(String user, String password)` or `XADataSource.getXAConnection(String user, String password)` as a set of connection attributes. The format of the attributes is the same as the format of the attributes in the property connectionAttributes. If false the password value is treated normally as the password for the given user. Setting this property to true allows a connection request from an application to provide more authentication information that just a password, for example the request can include the user's password and an encrypted database's boot password.
- `connectionAttributes` (String): Optional
  Defines a set of Derby connection attributes for use in all connection requests. The format of the String matches the format of the connection attributes in a Derby JDBC URL. That is a list of attributes in the form `attribute=value`, each separated by semi-colon (';'). E.g. `setConnectionAttributes("bootPassword=erd3234dggd3kazkj3000");`.
  The database name must be set by the DataSource property `databaseName` and not by setting the `databaseName` connection attribute in the `connectionAttributes` property.
  Any attributes that can be set using a property of this DataSource implementation (e.g user, password) should not be set in connectionAttributes. Conflicting settings in connectionAttributes and properties of the DataSource will lead to unexpected behaviour.
  Please see the Derby documentation for a complete list of connection attributes.
- `createDatabase` (String): Optional
  If set to the string "create", this will cause a new database of `databaseName` if that database does not already exist. The database is created when a connection object is obtained from the data source.
- `shutdownDatabase` (String): Optional
  If set to the string "shutdown", this will cause the database to shutdown when a java.sql.Connection object is obtained from the data source. E.g., If the data source is an XADataSource, a getXAConnection().getConnection() is necessary to cause the database to shutdown.

Examples.

This is an example of setting a property directly using Derby's EmbeddedDataSource40 object. This code is typically written by a system integrator :

     import org.apache.derby.jdbc.*;

     // dbname is the database name
     // if create is true, create the database if necessary
     javax.sql.DataSource makeDataSource (String dbname, boolean create)
            throws Throwable
     {
            EmbeddedDataSource40 ds = new EmbeddedDataSource40();
            ds.setDatabaseName(dbname);

            if (create)
                    ds.setCreateDatabase("create");

            return ds;
     }

Example of setting properties thru reflection. This code is typically generated by tools or written by a system integrator:

     javax.sql.DataSource makeDataSource(String dbname)
            throws Throwable
     {
            Class[] parameter = new Class[1];
            parameter[0] = dbname.getClass();
            DataSource ds =  new EmbeddedDataSource40();
            Class cl = ds.getClass();

            Method setName = cl.getMethod("setDatabaseName", parameter);
            Object[] arg = new Object[1];
            arg[0] = dbname;
            setName.invoke(ds, arg);

            return ds;
     }

Example on how to register a data source object with a JNDI naming service.

     DataSource ds = makeDataSource("mydb");
     Context ctx = new InitialContext();
     ctx.bind("jdbc/MyDB", ds);

Example on how to retrieve a data source object from a JNDI naming service.

     Context ctx = new InitialContext();
     DataSource ds = (DataSource)ctx.lookup("jdbc/MyDB");

See Also:
  Serialized Form

Constructor Summary
`EmbeddedDataSource40()`

Method Summary
`boolean` | `isWrapperFor(java.lang.Class<?> interfaces)` Returns false unless `interfaces` is implemented
`
`<T> T`
` | `unwrap(java.lang.Class<T> interfaces)` Returns `this` if this class implements the interface

Methods inherited from class org.apache.derby.jdbc.EmbeddedDataSource
`equals, getAttributesAsPassword, getConnection, getConnection, getConnectionAttributes, getCreateDatabase, getShutdownDatabase, setAttributesAsPassword, setConnectionAttributes, setCreateDatabase, setShutdownDatabase`

Methods inherited from class org.apache.derby.jdbc.ReferenceableDataSource
`getDatabaseName, getDataSourceName, getDescription, getLoginTimeout, getLogWriter, getObjectInstance, getPassword, getReference, getUser, setDatabaseName, setDataSourceName, setDescription, setLoginTimeout, setLogWriter, setPassword, setUser`

Methods inherited from class java.lang.Object
`clone, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Methods inherited from interface javax.sql.CommonDataSource
`getLoginTimeout, getLogWriter, setLoginTimeout, setLogWriter`

Constructor Detail

### EmbeddedDataSource40

    public EmbeddedDataSource40()

Method Detail

### isWrapperFor

    public boolean isWrapperFor(java.lang.Class<?> interfaces)
                         throws java.sql.SQLException

  Returns false unless `interfaces` is implemented

  Parameters:
    `interfaces` - a Class defining an interface.
  Returns:
    true if this implements the interface or directly or indirectly wraps an object that does.
  Throws:
    `java.sql.SQLException` - if an error occurs while determining whether this is a wrapper for an object with the given interface.

### unwrap

    public <T> T unwrap(java.lang.Class<T> interfaces)
             throws java.sql.SQLException

  Returns `this` if this class implements the interface

  Parameters:
    `interfaces` - a Class defining an interface
  Returns:
    an object that implements the interface
  Throws:
    `java.sql.SQLExption` - if no object if found that implements the interface
    `java.sql.SQLException`

Overview | Package | Class | Tree | Deprecated | Index | Help
| Built on Wed 2007-08-01 06:53:39-0700, from revision 561794
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Apache Derby 10.3 API Documentation - Copyright © 2004,2007 The Apache Software Foundation. All Rights Reserved.