Using a Control

This topic describes how to use a control from within your web service. It explains how to:

- locate an existing control

- use an existing control

- import and declare a control

- invoke a control method

- handle control callbacks

- handle control-generated exceptions

This topic assumes you have access to a control that you either implemented yourself or that was implemented by another developer. You have access to a control if you have access to its CTRL file in your project. The sections below describe how to modify the control's CTRL file and your web service's JWS file in order to access the control.

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

# Using an Existing Control

You can bring an existing control into your web service in several ways: you can add it, you can copy it, or you can reference it. Each method has specific implications. The sections that follow describe each of these methods in greater detail so you can choose which method will work best for a given circumstance.

Wherever you decide to place the control's CTRL file, it must be in your WebLogic Workshop project. Java imposes rules on references between packages that prevent you from using a control if it is not located in the correct place. If you place the CTRL file in the root folder of your project, web services that are not in the root folder (i.e., the Java default package) will not be able to use the control.

To learn about WebLogic Workshop project organization, see WebLogic Workshop Projects.

To use an existing control from your web service, locate the control's CTRL file in the Project Tree and drag the CTRL file onto the Design View for your web service.

# Referencing an Existing Control

If you have an existing CTRL file in your project, you can add a reference to that control in any web service by dragging the CTRL file from the Project Tree to the Design View of the web service from which you would like to use the control. You may also use the Add Control menu in the upper right corner of Design View. Any change you make to the control in Design View will effect the referenced CTRL file, which means it will also effect any other web services that are referencing the same CTRL file.

## Copying the Control CTRL File

If the CTRL file for the control you wish to use is not in your project, you must copy it to your project. The destination to which you copy the control depends on your expected usage. If the control will be used only by a single web service in your project, you may choose to copy the CTRL file to the same folder as your web service. If multiple web services in different folders in your project may use the control, you may wish to copy the control's CTRL file to a common folder. Remember that the CTRL file must be in your WebLogic Workshop project.

Wherever you decide to place the control's CTRL file, it must be in your WebLogic Workshop project.

Note: In Java terminology, a class that is defined in the default package may not be referenced from a class that is in a named (non-default) package. This means that if you place a CTRL file in the root folder of your project, you cannot reference the control from any web service that is not in the root folder. To learn about Java packages, see Introduction to Java.

Be aware that if you copy a CTRL file to a new location, you are creating a new control. If you do not change the definition of the copy, you now have two identical but separate controls. If the original copy of the control is subsequently changed, the second copy will remain unchanged. This means that any bug fixes or feature enhancements made to the original control will not be reflected in the copy.

If you want multiple web services to use the same control and you want changes in the control to affect the behavior of all web services that use the control, then you want to reference the original control instead of copying the control.

You may reference any control in your project by creating an appropriate import statement in your web service's JWS file. To learn how to import a control, see the Importing and Declaring the Control section below.

## Modifying the Control's Package

If you drag a CTRL file from one location to another within your WebLogic Workshop project, the package statement is automatically modified for you and you don't need to read the remainder of this section. However, if you decide to copy a control's CTRL file in some other way than dragging it in the Project Tree, you must change the package statement in the CTRL file.

In Java the location of a source file in the directory hierarchy determines (and must agree with) the Java package to which the classes in the file belong. If a Java file is located in the <project>\controls\financial directory, the Java package statement in the file must be the following:

    package controls.financial;

After copying a control's CTRL file to a new location, you must change the package statement in the file to reflect the new location.

For more information on Java packages, see Introduction to Java.

# Importing and Declaring the Control

If you specify that you want your web service to use a control by dragging that control's CTRL file onto the Design View of your web service, the necessary code changes are made to your web service's JWS file automatically and you do not need to read the rest of this section. However, if you declare a control instance manually in your web service's JWS file, you need to do three things: import the control's class, declare the control instance, and annotate the control instance declaration correctly so that WebLogic Workshop can connect the control. These procedures are described in this section.

To use the control from within a web service, import the control's main interface in the web service's JWS file using a Java import statement. The import typically resembles the following form:

    import controls.financial.CurrencyExchangeControl;

For more information on Java import statements, see Introduction to Java.

Once you have imported the control, you must declare an instance of the control before you can use it in your web service. To declare the control you must provide an appropriate Javadoc comment that identifies the declaration as a control, and you must declare the member variable that will represent the control in your web service as shown in the following example:

    /**
     * @jws:control
     */
    private CurrentExchangeControl currency;

The @jws:control tag indicates to the WebLogic Workshop user interface that the object declared in the associated code should be treated as a control in WebLogic Workshop and that WebLogic Workshop should connect the control to its supporting code.

The declaration itself must mention an interface that extends (indirectly) the weblogic.jws.control.Control interface.

It is customary to declare control instances to be private within a web service's JWS file because it typically doesn't make sense to use a control instance from outside of a JWS method.

# Invoking a Control Method

Once a control has been declared as described in the preceding section, you can access the methods of the control using the standard Java dot notation. For example, if the control named CurrencyExchangeControl defines the method shown here:

    String [] getAllAvailableCurrencyNames();

then you can access the method from within your web service JWS file using the following code:

    String [] currencyNames;
    currencyNames = currency.getAllAvailableCurrencyNames();

# Handling Control Callbacks

Some control types allow the specification of callbacks. Callbacks provide a way for a control or a web service to asynchronously notify a client that an event has occurred.

For a discussion of asynchrony, see Using Asynchrony to Enable Long-Running Operations.

A callback is a method signature that is defined by the control (or web service) where the method implementation must be provided by the client. The client enables reception of a callback by implementing a callback handler.

## Callback Definition

A callback definition in a control may look like the following:

    void onReportStatus(String status);

This declaration would be made in the source code for the service or control that defines the callback.

It is common for callbacks to have names that begin with "on" because a callback represents an event and the callback handler in the client will be called on occurrence of the event.

## Callback Handler Definition

The client is responsible for implementing a handler for any callback it wishes to receive. To implement a callback handler for the example callback in the previous section, the JWS file for a web service would include the following:

    void exampleControl_onReportStatus(String status)
    {
        <take appropriate action given status>
    }

In WebLogic Workshop, callback handler names are determined by the name of the control instance and the name of the callback. In the example above, the control instance from which we wish to receive the callback is exampleControl and the callback defined by the control is named onReportStatus. The full name of the callback handler, exampleControl_onReportStatus, is the control instance name followed by an underscore and the name of the callback.

# Handling Control Method Exceptions

The designer of a control may choose whether or not to explicitly declare that exceptions are thrown by the control's methods. If a control method is declared to throw exceptions, you must enclose your invocations of that method in a try-catch block.

Even if the designer of the control choses not to declare exceptions, the support code that implements the control may still throw exceptions. Such exceptions are always thrown as weblogic.jws.control.ControlException.

You should strongly consider handling all exceptions that may be thrown by the controls you use in your web service. If you do not handle an exception thrown by a control, the web service method will fail and the exception will be passed on to the client of your web service. In most cases, the exception is useless to the client and the client does not have the necessary information to diagnose or remedy the problem.

To learn more about exceptions and try-catch blocks, see Introduction to Java.

Related Topics

Web Service Development Cycle