| EmbeddedDataSource is Derby's DataSource implementation for JDBC3.0 and JDBC2.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
- JDBC 2.0 - Java 2 - JDK 1.2,1.3
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");
|
