Adding a Method to a Database Control

This topic discusses the mechanics of adding a method to a Database control.

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

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

To lean how to create a Database control, see Creating a New Database Control.

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

# Adding a Method to a Database Control

## The Database Control Method Pattern

A method in a Database control always associates a Java method definition with a SQL database operation. The SQL statement that defines the database operation may optionally contain substitutions from the parameter list of the Java method. The return type of the database operation is determined by the return type of the Java method.

The example Database control method below illustrates the pattern used to define Database control methods.

    /**
     * @jws:sql statement="UPDATE customer SET address = {customerAddress} WHERE custid={customerID}"
     */
    public int changeAddress(int customerID, String customerAddress);

The method signature declares a method that a user of this control may invoke. You should design this method such that its arguments and return value are convenient and useful to developers of web services that will use this control.

The @jws:sql tag describes the SQL statement that is associated with the method. The SQL statement may include substitution parameters that reference the parameter names in the method signature. In the example above, the SQL statement includes the substitutions {customerAddress} and {customerID}. These are a references to the customerID and customerAddress parameters of the findCustomer method. When the method is invoked, the values of any referenced parameters are substituted in the SQL statement before it is executed. Note that parameter substitution is case-sensitive; parameters mentioned in substitutions must exactly match the spelling and case of the parameters to the method.

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

# Adding a Method in Design View

If you are editing a web service in Design View and you wish to add a method to a Database control your web service is using, you may add the method directly by right-clicking on the Database control instance in Design View, as shown here:

In the example above, the CustomerDBClient web service is using a Database control whose instance name is custDB. Right-clicking on the custDB object will present a menu that contains the Add Method action. Select the Add Method action to add a method to the Database control of which custDB is an instance.

Note: The Database control variable declared in a web service's JWS file is an instance of a Database control. The actual control is defined in a CTRL file. When you add a method to a Database control from Design View, the method is added to the CTRL file. The method will subsequently be available in all web services that are using that Database control.

When a method is added, it will initially have no parameters and no associated SQL statement. To edit the parameter list and the associated SQL statement, see The Edit SQL and Interface Dialog section below.

# The Edit SQL and Interface Dialog

The Edit SQL and Interface Dialog allows you to customize the parameter list and associated SQL statement for a Database control method. To display the Edit SQL and Interface Dialog, double-click on the map icon associated with the method you wish to customize.

The map icon for a Database control method is shown here:

The Edit SQL and Interface dialog is shown here:

You may edit all aspects of the Database control method in the Edit SQL and Interface Dialog. The Java signature that is available to web services that use this Database control is defined in the lower portion. The SQL statement that is executed whenever the Java method is invoked is defined in the upper portion.

The rules of parameter substitution in Database control method SQL statements are described in Parameter Substitution in @jws:sql Statements.

The various types that may be returned by a Database control method are defined in Return Values of Database Control Methods, below.

# Return Values of Database Control Methods

Database control methods may return a single value, a single row, or multiple rows.

## Returning a Single Value

Some database operations return a single value. Example of such operations include INSERT and UPDATE operations, which return the number of rows affected by the INSERT or UPDATE. Another example is a SELECT operation that returns a single column of a single row.

To learn how to write Database control methods that return a single value, see Returning a Single Value from a Database Control Method.

## Returning a Single Row

Some database operations return multiple columns from a single row. An example of such an operation is a SELECT operation the returns all or a subset of columns from a single row.

To learn how to write Database control methods that return a single row, see Returning a Single Row from a Database Control Method.

## Returning Multiple Rows

Some database operations return one or more columns from multiple rows. An example of such an operation is a SELECT operation that returns one or more columns from multiple rows.

To learn how to write Database control methods that return multiple rows, see Returning Multiple Rows from a Database Control Method.

Related Topics

Controls: Using Resources from a Web Service

Database Control: Using a Database from Your Web Service

Creating a New Database Control

Using an Existing Database Control

CustomerDBClient.jws Sample

LuckyNumberDBClient.jws Sample

DatabaseControl Interface