Creating a New Database Control

A Database control provides a Java interface to database operations, making those operations very simple to access from the Java code in a web service. A specific instance of the Database control must be created that includes the particular operations desired. This customized Database control is defined in a CTRL file.

This topic discusses the mechanics of creating a Database control.

To learn about controls, see Controls: Using Resources from a Web Service.

To learn about the Database control, see Database Control: Using a Database from Your Web Service.

To learn about the issues you should consider when designing a Database control, see Database Control Design Issues.

# Creating a Database Control

You can create a new Database control and add it to your web service by using the Add Database Control Dialog. The Add Database Control Dialog can be accessed via the Service menu on the Menu Bar; via the right-button context menu on the service in the Design View; or via the Add Control option menu in the upper right corner of Design View.

For an explanation of the steps in the Add Database Control dialog, see Add Database Control Dialog.

Alternatively, you may create a Database control CTRL file manually. For example, you may copy an existing Database control CTRL file and modify the copy.

To learn how to add a method to a Database control, see Adding a Method to a Database Control.

# The Template Database Control CTRL File

If you create a new Database control in WebLogic Workshop, the new CTRL file will look like this:

    import weblogic.jws.*;
    import weblogic.jws.control.*;
    import java.sql.SQLException;
    /**
     * Defines a new database control.
     *
     * The @jws:connection tag indicates which WebLogic data source will be used
     * by this database control. Please change this to suit your needs. You can
     * see a list of available data sources by going to the WebLogic console
     * in a browser (typically http://localhost:7001/console) and clicking
     * Services, JDBC, Data Sources.
     *
     * @jws:connection data-source-jndi-name="cgSampleDataSource"
     */
    public interface CustomerDBControl extends DatabaseControl
    {
        // Sample database function. Uncomment to use
        // static public class Customer
        // {
        //   public int id;
        //   public String name;
        // }
        //
        // /**
        //  * @jws:sqlstatement="SELECT ID, NAME FROM CUSTOMERS WHERE ID = {id}"
        //  */
        // Customer findCustomer(int id) throws SQLException, ControlException;
    }

The name that was specified for this Database control is CustomerDBControl. It is customary for CTRL files to have names that end with "Control". Whenever WebLogic Workshop creates a CTRL file, it appends "Control" to the end of the name you specify. In Java, the main class or interface in a file must have the same name as the file. So the name of the interface in this case is CustomerDBControl.

There are three characteristics of this CTRL file that pertain to Database controls:

- The main interface in the file extends weblogic.jws.control.DatabaseControl.

- The Javadoc comment on the main interface contains a @jws:connection tag to indicate how to connect to the database.

- The file contains methods that are annotated with @jws:sql tags that define the database operations available via this control.

To learn how to add a method to a Database control, see Adding a Method to a Database Control.

# Transactions and the Database Control

Database operations occur within the context of an implicit transaction that wraps each web service method invocation. To learn more about WebLogic Workshop's default transaction semantics, see Transactions in WebLogic Workshop.

# The Database Connection: The @jws:connection Tag

Before you can perform operations on a database, you must have a connection to the database. The Database control will handle all of the details of managing the database connection, but you must supply the name of a data source that has been configured with the information necessary to access a database.

A default data source called cgSampleDataSource is configured when WebLogic Workshop is installed; it uses the PointBase database.

To learn how to create, configure and register a data source, see How Do I: Connect a Database Control to a Database Such as SQL Server or Oracle.

Once the data source is configured and registered in the JNDI registry, the data source name may be used in the data-source-jndi-name attribute of the @jws:connection tag.

For detailed information on the @jws:connection tag, see @jws:connection Tag.

Related Topics

Controls Overview

Database Control: Using a Database from Your Web Service

How Do I: Connect a Database Control to a Database Such as SQL Server or Oracle

Adding a Method to a Database Control

Using an Existing Database Control

CustomerDBClient.jws Sample

LuckyNumberDBClient.jws Sample

DatabaseControl Interface

@jws:sql Tag

@jws:connection Tag