Database bindings

If the purpose of a resource binding is to specify the connection used for database access, the definition is called a database binding.

You can place the binding in the EGL deployment descriptor or can include the connection information directly in your code. Here are other capabilities:

If you place the binding in the EGL deployment descriptor, you can specify the connections details there or use connection details that are specified in an Eclipse connection profile.
If you reference an Eclipse connection profile, any subsequent change to that profile is available to your code at development and deployment time. After the EGL deployer has packaged the application, though, the changes have no effect on the deployed code unless you redeploy the application.
You can use an JNDI data source that is or will be defined in the application server. If code is running on an application server that is compliant with Java Enterprise Edition, JNDI allows for fast database access across multiple users.
If you intend to deploy your code to the Apache Tomcat server, you can configure a JNDI deployment entry when you define an SQL database binding in the EGL deployment descriptor. The entry results in a container-based authentication, which means that the server stores any user ID and password needed for database access.

Defining an SQL database binding in the EGL deployment descriptor

For details on defining an SQL database binding in the EGL deployment descriptor, see Adding an SQL database binding to the EGL deployment descriptor.

Retrieving an SQL database binding in your code

You enable a future connection to a database by declaring a connection variable. The connection itself occurs when you first run a database-access statement that uses the variable.

One way to enable a future connection is to retrieve an SQL database binding from the EGL deployment descriptor. For example, here is the declaration of a connection variable:

myDataSource SQLDataSource? { @Resource {uri="binding:"MyDatabaseBinding"} };

That declaration is valid whether the binding is for JNDI or not. You can specify a connection variable that is specific to a JNDI data source, but will cause a runtime error if the binding refers to a non-JNDI data source:

myJNDIDataSource SQLJNDIDataSource? { 
   { @Resource {uri="binding:MyDatabaseJNDIBinding"} };

Your code interacts with either variable in the same way, and the use of the SQLDataSource type is sufficient in many cases. Here is an exception: if your subsequent logic uses the EGL isa operator to test whether a variable is of type SQLDataSource or SQLJNDIDataSource, you must use the SQLJNDIDataSource type for JNDI data sources and must use the SQLDataSource type for others.

You can also access SQL database bindings in your logic, as shown here:

myDataSource SQLDataSource? = 
   SysLib.getResource("binding:MyBinding");

myJNDIDataSource SQLDataSource? = 
   SysLib.getResource("binding:MyJNDIBinding");

myOtherJNDIDataSource SQLJNDIDataSource? = 
   SysLib.getResource("binding:MyOtherJNDIBinding");

Creating an SQL database binding in your code

You can create an SQL database binding in your code, in which case the EGL deployment descriptor is not involved. For example, the following code enables a database connection for a non-JNDI data source:

connectURL string = "jdbc:derby:SomeDB;create=true;";
properties Dictionary{user = "MyID", password = "MyPassword"};
myDataSource SQLDataSource? = new SQLDataSource(connectURL, properties);

Here is equivalent code that is specifically for a JNDI data source:

connectURL string = "jdbc/myDataSource";
properties Dictionary{user = "MyID", password = "MyPassword"};
myJNDIDataSource SQLJNDIDataSource? = new SQLJNDIDataSource(connectURL, properties);

As noted earlier, any connection variable can be based on the SQLDataSource type. Here is code that enables a JNDI connection in the usual case, when container-managed security is in effect:

connectURL string = "jdbc/myDataSource";
myJNDIDataSource SQLJNDIDataSource? = new SQLJNDIDataSource(connectURL);

For a JNDI connection, if security detail is passed to a data source that operates under container-managed security, the result is not determined by the generated application or by the EGL runtime code. For details on what happens, see the documentation provided by the specific Java DataSource class in use.

Using the connection variable for additional purposes

You can use the connection variable for the following, additional purposes:

To set or get the isolation level, which specifies the level of independence of one user's database transaction from another user's database transaction.
To set or get the autoCommit value, which indicates whether updates are committed automatically.
To set the database schema to use in SQL statements that are issued by your code.
To test whether a connection is still in effect.
To access a set of exception records that give runtime warnings.

For details on these capabilities, see the "SQLDataSource external type" help topic, which is subordinate to "eglx.persistence.sql.package." The details there apply to both SQLDataSource and SQLJNDIDataSource.

For further information

For further details, see EGL support for relational databases.