Module org.apache.derby.tools
Package org.apache.derby.jdbc

# Class EmbeddedDataSource

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

All Implemented Interfaces:
  `Serializable`, `Wrapper`, `Referenceable`, `ObjectFactory`, `CommonDataSource`, `DataSource`, `org.apache.derby.iapi.jdbc.EmbeddedDataSourceInterface`

Direct Known Subclasses:
  `EmbeddedConnectionPoolDataSource`, `EmbeddedXADataSource`

public class EmbeddedDataSource extends org.apache.derby.jdbc.ReferenceableDataSource implements Referenceable

This data source is suitable for an application using embedded Derby, running on full Java SE 6 and higher, corresponding to 4.0 and higher.

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 4.0 - Java SE 6
- JDBC 4.1 - Java SE 7
- JDBC 4.2 - full Java SE 8

Use BasicEmbeddedDataSource40 if your application runs on Java 8 Compact Profile 2.

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

  Constructors
  Constructor
  Description
  `EmbeddedDataSource()`
  No-arg constructor.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Object`
  `getObjectInstance(Object refObj, Name name, Context nameContext, Hashtable<?,?> environment)`
  Reconstructs a Derby embedded-driver data source object from a JNDI data source reference.
  `final Reference`
  `getReference()`
  This method creates a new `Reference` object to represent this data source.

  ### Methods inherited from class org.apache.derby.jdbc.BasicEmbeddedDataSource40

  `equals, getAttributesAsPassword, getConnection, getConnection, getConnection, getConnectionAttributes, getCreateDatabase, getDatabaseName, getDataSourceName, getDescription, getLoginTimeout, getLogWriter, getParentLogger, getPassword, getShutdownDatabase, getUser, hashCode, isWrapperFor, setAttributesAsPassword, setConnectionAttributes, setCreateDatabase, setDatabaseName, setDataSourceName, setDescription, setLoginTimeout, setLogWriter, setPassword, setShutdownDatabase, setUser, unwrap`

  ### Methods inherited from class java.lang.Object

  `getClass, notify, notifyAll, toString, wait, wait, wait`

  ### Methods inherited from interface javax.sql.CommonDataSource

  `createShardingKeyBuilder`

  ### Methods inherited from interface javax.sql.DataSource

  `createConnectionBuilder`

- ## Constructor Details

  - ### EmbeddedDataSource

    public EmbeddedDataSource()
    No-arg constructor.

- ## Method Details

  - ### getReference

    public final Reference getReference() throws NamingException
    This method creates a new `Reference` object to represent this data source. The class name of the data source object is saved in the `Reference`, so that an object factory will know that it should create an instance of that class when a lookup operation is performed. The class is also stored in the reference. This is not required by JNDI, but is recommend in practice. JNDI will always use the object factory class specified in the reference when reconstructing an object, if a class name has been specified. See the JNDI SPI documentation for further details on this topic, and for a complete description of the `Reference` and `StringRefAddr` classes.

    Derby data source classes class provides several standard JDBC properties. The names and values of the data source properties are also stored in the reference using the `StringRefAddr` class. This is all the information needed to reconstruct an embedded data source object.
    Specified by:
      `getReference` in interface `Referenceable`
    Returns:
      the created reference object for this data source
    Throws:
      `NamingException` - cannot find named object

  - ### getObjectInstance

    public Object getObjectInstance(Object refObj, Name name, Context nameContext, Hashtable<?,?> environment) throws Exception
    Description copied from class: `org.apache.derby.jdbc.ReferenceableDataSource`
    Reconstructs a Derby embedded-driver data source object from a JNDI data source reference.

    The `getObjectInstance` method is passed a reference that corresponds to the object being retrieved as its first parameter. The other parameters are optional in the case of JDBC data source objects. The object factory should use the information contained in the reference to reconstruct the data source. If for some reason, a data source object cannot be reconstructed from the reference, a value of `null` may be returned. This allows other object factories that may be registered in JNDI to be tried. If an exception is thrown then no other object factories are tried.

    Specified by:
      `getObjectInstance` in interface `ObjectFactory`
    Overrides:
      `getObjectInstance` in class `org.apache.derby.jdbc.ReferenceableDataSource`
    Parameters:
      `refObj` - the possibly `null` object containing location or reference information that can be used in creating an object
      `name` - the name of this object relative to `nameContext`, or `null` if no name is specified
      `nameContext` - context relative to which the name parameter is specified, or `null` if name is relative to the default initial context.
      `environment` - possibly `null` environment that is used in creating the object.
    Returns:
      Object created, or `null` if no attempt to create the object is made.
    Throws:
      `Exception` - if recreating the object fails