Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "EDT:Resource Binding Databases"

(Defining an SQL database binding in the EGL deployment descriptor)
 
(29 intermediate revisions by 3 users not shown)
Line 1: Line 1:
If the purpose of a resource binding is to connect to a relational database, the definition is called an ''SQL database binding''. <br>  
+
<span style="font-size:smaller;">&lt;&nbsp;[[EDT:Resource Binding Introduction|Resource Binding Introduction]]</span> <br> If the purpose of a resource binding is to connect to a relational database, the definition is called an ''SQL database binding''. <br>  
  
 
= Defining an SQL database binding in the EGL deployment descriptor  =
 
= Defining an SQL database binding in the EGL deployment descriptor  =
  
When you define an SQL database binding in the EGL deployment descriptor, you specify a set of details for use at application run time. In some cases, you also specify a set of server configuration details that are provided to the EGL deployer. <br>
+
When you define an SQL database binding, you specify connection details that are used at development time. In addition, you can identify a JNDI name:
  
Here is the overall process:
+
*If you are deploying to the Apache Tomcat Server, EGL deployment uses both the JNDI name and the connection details to create the JNDI &lt;resource-ref&gt; entry in the WEB-INF\web.xml and the &lt;resource&gt; entry in the META-INF\context.xml file that will be used at run time. The only additional thing you need to do is make sure the derbyclient jar is copied to the Tomcat lib directory.
  
#In an EGL project, expand the EGLSource folder and double-click the deployment descriptor, which has the file extension .egldd.
+
If the same-name JNDI entry is already in place, your connection details supplement the existing entry. The fields that are available in the EGL deployment descriptor override the equivalent attributes in the existing entry. The override occurs even if you do not specify a value at all. However, if a JNDI attribute is not represented, the JNDI attribute in the existing entry is unaffected.  
#Click the Resource Bindings tab. The Resource Bindings Configuraton page is displayed.  
+
#Click '''Add''' and, at the Add a Resource Binding page, select '''SQL Database Binding'''. The Add an SQL Database Binding page is displayed, as shown here: <br><br>[ this screen shot is for .7 and is under review for .8.&nbsp; the main point is this:&nbsp; you can specify what detail is used at deployment time:&nbsp; either the connection profile (the first option) or details that you type at this screen (the second option). <br><br>and now, please skip to the next section. ]<br>
+
  
[[Image:AddaSQLDatabaseBinding7.png]]
+
*If you are deploying to IBM WebSphere Application Server, the connection details you specify are not used to configure the server, but the name will be used at run time. In this case, you need to configure the data source at the Administrative Console of that server.<br>
 +
*If you are deploying to another server, the connection details you specify are not used to configure the server, but the name will be used at run time. For details on the configuring the data source, consult the server documentation.
  
<br>  
+
<br>Here is the overall process:
  
To specify where the binding details are stored, select one of the first three options:<br>
+
*#In an EGL project, expand the EGLSource folder and double-click the deployment descriptor, which has the file extension .egldd.
 
+
*#Click the Resource Bindings tab. The Resource Bindings Configuraton page is displayed.
*To use connection details that are or will be specified in an Eclipse connection profile, select the first option. Reference an existing connection profile or press '''New''' to define one.  
+
*#Click '''Add''' and, at the Add a Resource Binding page, select '''SQL Database Binding'''. The Add an SQL Database Binding page is displayed, as shown here: <br><br>[ this screen shot is for .7 and is under review for .8.&nbsp; the main point is this:&nbsp; you can specify what detail is used at deployment time:&nbsp; either the connection profile (the first option) or details that you type at this screen (the second option). ]<br><br> [[Image:AddaSQLDatabaseBinding7.png]] <br> After you have created an SQL database binding, you can make additional changes at the following screen, which is new in version .8:<br><br> [[Image:AddaSQLDatabaseBinding8.png]] <br> At that screen you select one of the first two options to specify where the binding details are stored:  
*To specify connection details directly in the binding definition, select the second option instead.  
+
**To use connection details that are specified in an Eclipse connection profile, select the first option. Reference an existing connection profile or press '''New''' to define one.<br><br>If you select this option, any subsequent change to the Eclipse connection 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.<br>
*To use an JNDI data source that is or will be defined in the application server, select the third option. In this case, the details that you specify are the only ones on this page.<br>
+
**To specify connection details directly in the binding definition, select the second option instead. To configure a JNDI entry, do as follows:  
 
+
**Define the connection by specifying the first or second option.  
If code is running on an application server that is compliant with Java Enterprise Edition, JNDI allows for fast database access across multiple users. <br>
+
**Select the third option. In relation to Apache Tomcat, the JNDI name and other details that you specify here are associated with the other details. The information is packaged during EGL deployment.<br><br>By default, the JNDI details result in a container-based authentication, which means that the server stores any user ID and password needed for database access. If you are handling authentication in your code, select Use application-based authentication.<br> <br>
 
+
If you intend to deploy your code to the Apache Tomcat server, you can configure a JNDI entry:  
+
 
+
*Define most of the binding details by specifying the first or second option.  
+
*Also select the fourth option. The JNDI name and other details that you specify here are associated with the details from the first or second option. The information is packaged during EGL deployment. The JNDI details result in a container-based authentication, which means that the server stores any user ID and password needed for database access.&nbsp;<br>
+
 
+
If you select the first option, any subsequent change to the Eclipse connection 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 re-deploy the application.<br>
+
  
 
= Retrieving an SQL database binding in your code <br>  =
 
= Retrieving an SQL database binding in your code <br>  =
Line 35: Line 27:
  
 
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: <br>  
 
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: <br>  
<pre>myDataSource SQLDataSource? { @Resource {uri="binding:"MyDatabaseBinding"} };  
+
<pre>myDataSource SQLDataSource?  
 +
  { @Resource {uri="binding:"MyDatabaseBinding"} };     // .8 syntax
 
</pre>  
 
</pre>  
 
That declaration is valid whether the binding is for JNDI or not.&nbsp; 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: <br>  
 
That declaration is valid whether the binding is for JNDI or not.&nbsp; 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: <br>  
 
<pre>myJNDIDataSource SQLJNDIDataSource? {  
 
<pre>myJNDIDataSource SQLJNDIDataSource? {  
   { @Resource {uri="binding:MyDatabaseJNDIBinding"} };
+
   { @Resource {uri="binding:MyDatabaseJNDIBinding"} };   // .8 syntax 
 
</pre>  
 
</pre>  
 
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:&nbsp; if your subsequent logic uses the EGL <code>isa</code> 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.  
 
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:&nbsp; if your subsequent logic uses the EGL <code>isa</code> 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.  
Line 45: Line 38:
 
You can also access SQL database bindings in your logic, as shown here:&nbsp;  
 
You can also access SQL database bindings in your logic, as shown here:&nbsp;  
 
<pre>myDataSource SQLDataSource? =  
 
<pre>myDataSource SQLDataSource? =  
   SysLib.getResource("binding:MyBinding");
+
   Resources.getResource("binding:MyBinding");               // .8 syntax
 +
 
 +
 
 +
myOtherDataSource SQLDataSource? =
 +
  Resources.getResource("binding:file:MyFile#MyBinding2");  // .8 syntax
 +
 
  
 
myJNDIDataSource SQLDataSource? =  
 
myJNDIDataSource SQLDataSource? =  
   SysLib.getResource("binding:MyJNDIBinding");
+
   Resources.getResource("binding:MyJNDIBinding");           // .8 syntax
  
 
myOtherJNDIDataSource SQLJNDIDataSource? =  
 
myOtherJNDIDataSource SQLJNDIDataSource? =  
   SysLib.getResource("binding:MyOtherJNDIBinding");
+
   Resources.getResource("binding:MyOtherJNDIBinding");     // .8 syntax
 
   
 
   
 
</pre>  
 
</pre>  
Line 64: Line 62:
 
<pre>connectURL string = "jdbc/myDataSource";
 
<pre>connectURL string = "jdbc/myDataSource";
 
properties Dictionary{user = "MyID", password = "MyPassword"};
 
properties Dictionary{user = "MyID", password = "MyPassword"};
myJNDIDataSource SQLJNDIDataSource? = new SQLJNDIDataSource(connectURL, properties);
+
myJNDIDataSource SQLJNDIDataSource? =  
 +
  new SQLJNDIDataSource(connectURL, properties);
 
</pre>  
 
</pre>  
 
As noted earlier, any connection variable can be based on the SQLDataSource type. <br>  
 
As noted earlier, any connection variable can be based on the SQLDataSource type. <br>  
Line 84: Line 83:
 
*To access a set of exception records that give runtime warnings. <br>
 
*To access a set of exception records that give runtime warnings. <br>
  
For details on these capabilities, see the "SQLDataSource external type" help topic, which is subordinate to "eglx.persistence.sql.package."&nbsp; The details there apply to both SQLDataSource and SQLJNDIDataSource. <br> <br> ♦ '''Previous''':&nbsp;&nbsp;[http://wiki.eclipse.org/EDT:Resource_Binding_Services Service bindings]  
+
For details on these capabilities, see the "SQLDataSource external type" help topic, which is subordinate to "eglx.persistence.sql.package."&nbsp; The details there apply to both SQLDataSource and SQLJNDIDataSource. <br> <br> ♦ '''Previous''':&nbsp;&nbsp;[[EDT:Resource Binding Services|Service bindings]]  
  
♦ '''First''':&nbsp;&nbsp;[http://wiki.eclipse.org/EDT:Resource_Binding_Introduction Resource binding introduction]<br>
+
♦ '''First''':&nbsp;&nbsp;[[EDT:Resource Binding Introduction|Resource binding introduction]]

Latest revision as of 23:59, 14 May 2012

Resource Binding Introduction
If the purpose of a resource binding is to connect to a relational database, the definition is called an SQL database binding.

Defining an SQL database binding in the EGL deployment descriptor

When you define an SQL database binding, you specify connection details that are used at development time. In addition, you can identify a JNDI name:

  • If you are deploying to the Apache Tomcat Server, EGL deployment uses both the JNDI name and the connection details to create the JNDI <resource-ref> entry in the WEB-INF\web.xml and the <resource> entry in the META-INF\context.xml file that will be used at run time. The only additional thing you need to do is make sure the derbyclient jar is copied to the Tomcat lib directory.

If the same-name JNDI entry is already in place, your connection details supplement the existing entry. The fields that are available in the EGL deployment descriptor override the equivalent attributes in the existing entry. The override occurs even if you do not specify a value at all. However, if a JNDI attribute is not represented, the JNDI attribute in the existing entry is unaffected.

  • If you are deploying to IBM WebSphere Application Server, the connection details you specify are not used to configure the server, but the name will be used at run time. In this case, you need to configure the data source at the Administrative Console of that server.
  • If you are deploying to another server, the connection details you specify are not used to configure the server, but the name will be used at run time. For details on the configuring the data source, consult the server documentation.


Here is the overall process:

    1. In an EGL project, expand the EGLSource folder and double-click the deployment descriptor, which has the file extension .egldd.
    2. Click the Resource Bindings tab. The Resource Bindings Configuraton page is displayed.
    3. Click Add and, at the Add a Resource Binding page, select SQL Database Binding. The Add an SQL Database Binding page is displayed, as shown here:

      [ this screen shot is for .7 and is under review for .8.  the main point is this:  you can specify what detail is used at deployment time:  either the connection profile (the first option) or details that you type at this screen (the second option). ]

      AddaSQLDatabaseBinding7.png
      After you have created an SQL database binding, you can make additional changes at the following screen, which is new in version .8:

      AddaSQLDatabaseBinding8.png
      At that screen you select one of the first two options to specify where the binding details are stored:
    • To use connection details that are specified in an Eclipse connection profile, select the first option. Reference an existing connection profile or press New to define one.

      If you select this option, any subsequent change to the Eclipse connection 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.
    • To specify connection details directly in the binding definition, select the second option instead. To configure a JNDI entry, do as follows:
    • Define the connection by specifying the first or second option.
    • Select the third option. In relation to Apache Tomcat, the JNDI name and other details that you specify here are associated with the other details. The information is packaged during EGL deployment.

      By default, the JNDI details result in a container-based authentication, which means that the server stores any user ID and password needed for database access. If you are handling authentication in your code, select Use application-based authentication.

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"} };      // .8 syntax

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"} };   // .8 syntax  

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? = 
   Resources.getResource("binding:MyBinding");               // .8 syntax


myOtherDataSource SQLDataSource? =
   Resources.getResource("binding:file:MyFile#MyBinding2");  // .8 syntax 


myJNDIDataSource SQLDataSource? = 
   Resources.getResource("binding:MyJNDIBinding");           // .8 syntax

myOtherJNDIDataSource SQLJNDIDataSource? = 
   Resources.getResource("binding:MyOtherJNDIBinding");      // .8 syntax
 

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.

Previous:  Service bindings

First:  Resource binding introduction

Back to the top