Using an SQL database connection at run time

To use an SQL connection at run time, you must point to the connection from your project's build descriptor and, for EGL web projects, set options in the J2EE deployment descriptors based on information in the connection.

Prerequisites

You will need a working connection to an SQL database, or you can create one in the process. For instructions on setting up this connection, see Creating an SQL database connection.

Creating the runtime connection for EGL web projects

For EGL web projects, you need to set options in the project based on the information in the connection. Through the project's EGL Runtime Data Source property page, EGL can do much of this work for you automatically:

  • EGL updates the following build descriptor options in the project's master build descriptor:
    • dbms
    • sqlDB
    • sqlID
    • sqlJDBCDriverClass
    • sqlJNDIName
    • sqlPassword
    • sqlValidationConnectionURL
    Whether EGL updates the build descriptor options or not depends on the build descriptor preferences, as explained in Setting build descriptor preferences. If you want EGL to update your build descriptor options, set Update default build options for project when runtime data source is modified to Prompt or Always.
  • If the web project is acting as a module of an enterprise application resource (EAR) project, EGL adds a data source to the EAR project's deployment descriptor. This data source associates the JNDI name with the database itself. Now, other projects acting as modules within this EAR project can access the database through the JNDI name.

    If the web project is not a module within an EAR project, you must associate the JNDI name with a database on the server manually. Refer to the server documentation for how to create a JDBC data source.

  • EGL adds a reference to the JNDI name in the project's web deployment descriptor. Now the project can use the data source through the JNDI name, as long as the EAR project or server links that JNDI name to a data source.
  1. Right-click your project and then click Properties.
  2. In the Properties window, click EGL Runtime Data Source.
  3. On the EGL Runtime Data Source page, select Load values from a data tools connection and select your database connection in the Connection list. You can also click New and create a new connection; for information on creating the connection, see Creating an SQL database connection.
  4. When you select a connection, EGL uses the information in that connection to fill in the fields on the page. To edit these values, you can select Input/modify values manually and edit the values in the fields. For information on the individual fields, see Fields in the New Connection wizard.

    In addition to the information from the database connection, EGL creates a JNDI name for the connection. By default, this name is the name of the database connection plus the prefix jdbc/. You can accept the default or edit the JNDI name field.

  5. If you do not want EGL to set up a data source in the EAR deployment descriptor associated with this project, click Input/modify values manually and clear the Deploy database and connection properties when application is run on unit test server.
  6. Click OK to make the updates to your project.

    If the Update default build options for project when runtime data source is modified preference is set to Always, EGL automatically updates the build descriptor options based on the connection information. If the preference is set to Prompt, EGL asks before updating the build descriptor options. If the preference is set to Never, no changes are made to the build descriptor options.

Creating the runtime connection for EGL projects

  1. Double-click the build descriptor for your project. Typically, the build descriptor file is located in the top level of the EGLSource directory of your project and is named project.eglbld. The build descriptor opens in the build parts editor.
  2. Select the database connection to use from the Load DB options using Connection list. If you have not already created this connection, see Creating an SQL database connection.
    When you select a connection, the build parts editor updates the following build descriptor options to match the connection:
    • dbms
    • sqlDB
    • sqlID
    • sqlJDBCDriverClass
    • sqlPassword
    • sqlValidationConnectionURL
  3. Save the build descriptor and close the window.
  4. Generate any parts that use the database connection.

Error conditions

EGL uses a different process to connect with the database at run time than it does at design time. These differences might result in errors when you try to run your code:
  • EGL might not be able to find the Java™ class containing the driver for your database manager, even though you specified a Class location in the New Connection wizard. To correct this error, make sure the driver is on the classpath for your project:
    1. Right-click on your project name in the Project Explorer view and click Properties from the pop-up menu.
    2. Select Java Build Path from the left pane of the Properties window.
    3. Click the Libraries tab on the Java™ Build Path page.
    4. If the correct class location is not displayed, click Add External JARs and add the class and location. You can copy this information from your Connection; see Editing or deleting an SQL database connection
    .