Apache Derby 10.5

## org.apache.derby.jdbc
Class EmbeddedDataSource

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

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

Direct Known Subclasses:
  EmbeddedConnectionPoolDataSource, EmbeddedXADataSource

    public class EmbeddedDataSource

extends org.apache.derby.jdbc.ReferenceableDataSource
implements javax.sql.DataSource

EmbeddedDataSource is Derby's DataSource implementation for JDBC3.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.

EmbeddedDataSource automatically supports the correct JDBC specification version for the Java Virtual Machine's environment.

- 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 EmbeddedDataSource 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
     {
            EmbeddedDataSource ds = new EmbeddedDataSource();
            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 EmbeddedDataSource();
            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
`EmbeddedDataSource()` No-arg constructor.

Method Summary
`boolean` `equals(java.lang.Object p0)`
`boolean` `getAttributesAsPassword()` Return the value of the attributesAsPassword property.
`java.sql.Connection` `getConnection()` Attempt to establish a database connection.
`java.sql.Connection` `getConnection(java.lang.String username, java.lang.String password)` Attempt to establish a database connection with the given username and password.
`java.lang.String` `getConnectionAttributes()`
`java.lang.String` `getCreateDatabase()`
`java.lang.String` `getShutdownDatabase()`
`void` `setAttributesAsPassword(boolean attributesAsPassword)` Set attributeAsPassword property to enable passing connection request attributes in the password argument of getConnection.
`void` `setConnectionAttributes(java.lang.String prop)` Set this property to pass in more Derby specific connection URL attributes.
`void` `setCreateDatabase(java.lang.String create)` Set this property to create a new database.
`void` `setShutdownDatabase(java.lang.String shutdown)` Set this property if one wishes to shutdown the database identified by databaseName.

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.DataSource
`getLoginTimeout, getLogWriter, setLoginTimeout, setLogWriter`

Constructor Detail

### EmbeddedDataSource

    public EmbeddedDataSource()

  No-arg constructor.

Method Detail

### equals

    public boolean equals(java.lang.Object p0)

  Overrides:
    `equals` in class `java.lang.Object`

### setCreateDatabase

    public final void setCreateDatabase(java.lang.String create)

  Set this property to create a new database. If this property is not set, the database (identified by databaseName) is assumed to be already existing.

  Parameters:
    `create` - if set to the string "create", this data source will try to create a new database of databaseName, or boot the database if one by that name already exists.

### getCreateDatabase

    public final java.lang.String getCreateDatabase()

  Returns:
    "create" if create is set, or null if not

### setShutdownDatabase

    public final void setShutdownDatabase(java.lang.String shutdown)

  Set this property if one wishes to shutdown the database identified by databaseName.

  Parameters:
    `shutdown` - if set to the string "shutdown", this data source will shutdown the database if it is running.

### getShutdownDatabase

    public final java.lang.String getShutdownDatabase()

  Returns:
    "shutdown" if shutdown is set, or null if not

### setConnectionAttributes

    public final void setConnectionAttributes(java.lang.String prop)

  Set this property to pass in more Derby specific connection URL attributes.
  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.

  Parameters:
    `prop` - set to the list of Derby connection attributes separated by semi-colons. E.g., to specify an encryption bootPassword of "x8hhk2adf", and set upgrade to true, do the following:

                                ds.setConnectionAttributes("bootPassword=x8hhk2adf;upgrade=true");

    See the Derby documentation for complete list.

### getConnectionAttributes

    public final java.lang.String getConnectionAttributes()

  Returns:
    Derby specific connection URL attributes

### setAttributesAsPassword

    public final void setAttributesAsPassword(boolean attributesAsPassword)

  Set attributeAsPassword property to enable passing connection request attributes in the password argument of getConnection. If the property is set to true then the password argument of the DataSource.getConnection(String user, String password) method call is taken to be a list of connection attributes with the same format as the connectionAttributes property.

  Parameters:
    `attributesAsPassword` - true to encode password argument as a set of connection attributes in a connection request.

### getAttributesAsPassword

    public final boolean getAttributesAsPassword()

  Return the value of the attributesAsPassword property.

### getConnection

    public java.sql.Connection getConnection()
                                      throws java.sql.SQLException

  Attempt to establish a database connection.

  Specified by:
    `getConnection` in interface `javax.sql.DataSource`
  Returns:
    a Connection to the database
  Throws:
    `java.sql.SQLException` - if a database-access error occurs.

### getConnection

    public java.sql.Connection getConnection(java.lang.String username,
                                             java.lang.String password)
                                      throws java.sql.SQLException

  Attempt to establish a database connection with the given username and password. If the attributeAsPassword property is set to true then the password argument is taken to be a list of connection attributes with the same format as the connectionAttributes property.

  Specified by:
    `getConnection` in interface `javax.sql.DataSource`
  Parameters:
    `username` - the database user on whose behalf the Connection is being made
    `password` - the user's password
  Returns:
    a Connection to the database
  Throws:
    `java.sql.SQLException` - if a database-access error occurs.

Built on Mon 2009-08-10 13:17:35-0700, from revision 802917

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