Invoking a Control Method

The following topic explains how to utilize a (system or custom) control resource in an application. This topic is divided into the following sections:

Adding a Control Declaration

Invoking a Method

Adding a Control Declaration

To invoke a control method, first add a control declaration to the calling client and then invoke a method on that control.

To add a control declaration, open the J2EE perspective (Window > Open Perspective > J2EE ), right-click anywhere with the Java source of the client class and select Insert > Control. Select from the list of controls available to your client.

See the topic Select Control Dialog for a complete description of the dialog below.

Selecting a control from the dialog will add two things to your client class: (1) a control class import statement and (2) a control class declaration:

    MyClient.java

    import controls.CustomerControl;
  
    @Control
    private CustomerControl customerControl;
  

Once the control class declaration is in place, you can call the control's methods.

Invoking a Method

Once you've added a control class declaration to your client class, you can invoke its methods using the standard Java dot notation. For example, assume that you have added a declaration for the control class CustomerControl:

    @Control
    private CustomerControl customerControl;

Also assume that the control defines a method getCustomers():

    public Customer[] getCustomers();

You can invoke this method from your client code as follows:

    Customer[] custResult = customerControl.getCustomers();

Overriding Default Control Properties

Sometimes it is desirable to override a control property from within client code without editing the control code. For example, suppose you have a database control where the JNDI data source name is set by an annotation.

@JdbcControl.ConnectionDataSource(jndiName = "myDataSource")
public interface CustomerDB extends JdbcControl

But also suppose the JNDI name has changed, or you want to reuse the database control in another context where the JNDI name of the data source is different. It might be inconvenient (or impossible) to manually change the annotation value and recompile the control. In this case it is desirable to override the JNDI value directly from within client code. To override the annotation value you call into another class: the control's associated ControlBean class. The ControlBean class implements all of the control's methods but also gives you programmatic access to the control's annotation-based properties. The ControlBean is a generated JavaBean class that is created automatically when a control is built.

The following sections explain what this generated ControlBean class is and how to use it to override default control annotation values.

You can also override annotation values that are set in the client class. For details see Overriding Control Annotation Values Through the ControlBean below.

The ControlBean Generated Class

Every control has an associated ControlBean class. The ControlBean is generated automatically and provides a programmatic way to access settings that otherwise would only be available through the controls annotations. The ControlBean class typically does not exist as a JAVA source file; instead only the compiled CLASS file is present within the application.

The ControlBean generated class is derived from the members and methods in the control. The ControlBean generated class is really a superset of the original control class that provides a broader set of access points into the control. In the case of the Timer control, the shape of the ControlBean generated class is fixed (because the members and methods of the Timer control are fixed). But in the case of extensible system controls (EJB, JDBC, and JMS controls) and custom controls the ControlBean generated class is variable (because the members and methods of the source controls are variable).

The name of the generated ControlBean class is the control name appended with 'Bean'. If the control name is CustomerDB.java, then the generated ControlBean class will be CustomerDBBean.class.

For more infomation about the ControlBean generated from control sources see: The Control Authoring Model.

Related Topics

The Control Authoring Model

Overriding Control Properties


Still need help? Post a question on the Workshop newsgroup.