Overriding Control Properties

Sometimes it is desirable to override a control definition property from within client code or from an external configuration file. Common examples overriding the endpoint address on a service control or the data source on a database control. Suppose that you have a database control definition where the data source is configured as follows.

DatabaseControl.java (Control Definition Code)

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

What if you want to reuse the database control in another context where the data source is different? It might be inconvenient (or impossible) to manually change the annotation value and recompile the control definition. In this case it is desirable to override the data source value from another source.

To override the annotation value in the control definition, you can do one of the following:

Developers use option (2) when the properties of the control instance are not known until runtime. In this case you will typically first determine the appropriate control properties and then reset those properties programmatically using the ControlBean API.

Option (3) is for use by server administrators who are managing the deployment of an application into a different environment. For example, if an application is being promoted from a testing environment into a real world production environment. A deployment plan can override annotation values on any of the control contexts in the application, including either the control definition or the control declaration in client code. Note that deployment plans can only override contexts already established by annotations, they cannot add new contexts or override any value set through the ControlBean.

The hierarchical rules of precedence for these override methods are described below in Order of Precedence.

The diagram below shows the different options available to developers and administrators.

Requirements for Annotation Overrides

Annotation overrides are supported only when the following requirements are met:

Method 1: Overriding Control Annotation Values Through the Control Declaration Field

You can override a control's default properties on the control's declaration field in your client code.

The database control above is declared with its default properties in the following way.

MyWebService.java (Client Code)

    @Control
    private DatabaseControl dbControl;

To override the default jndiName property, use the following declaration.

    @Control
    @DatabaseControl.ConnectionDataSource(jndiName = "myOtherDataSource")
    private DatabaseControl dbControl;

In the above declaration, the database control will use myOtherDataSource instead of the value used in the control definition. This override value will apply to all method calls from within MyWebService.java.

Method 2: Overriding Control Annotation Values Through the 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 by Beehive when a control is built. (Note that the control author may disable overrides of control properties. See the @PropertySet annotation for details.)

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.

Use caution when you use this approach because it cannot be overridden by a deployment plan (method 3 below).

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

Calling ControlBean Methods

Suppose you have a database control where jndiName attribute points at the data source myDataSource.

DatabaseControl.java

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

To override all other competing values of the urls property, add the database control's generated ControlBean class to your client and reset the JNDI (by calling the appropriate method). Note that using the ControlBean class will override all competing values, including the value in the control definition, any value set on a control declaration field, and any external configuration through a deployment plan.

To reference the ControlBean class, use the following declaration.

    @Control
    private controls.CustomerDBBean customerDBBean;	

To override the JNDI value, call the setConnectionDataSourceJndiName(String name) method.

    customerDBBean.setConnectionDataSourceJndiName("myOtherDataSource");

Calling Methods on the Control Definition Class

In some cases the appropriate setter method is not on the ControlBean class, but on the control definition class. For example, to override the target url of a service control, you call a method on a service control definition. The following control definition property:

@ServiceControl.Location(urls = {"http://some.domain.com/WebServices/HelloWorld"})
...
public interface HelloWorldServiceControl extends ServiceControl

is overridden by the setEndpointAddress(String url) method on the control definition class.

Method 3: External Configuration in a Deployment Plan

Some annotation values can be overridden through an external configuration file as part of a deployment plan. For details on deployment plans see Configuring Applications for Production Deployment in the WebLogic Server documentation.

Deployment plan configuration files can override annotation values both in the control definition class and on the control declaration field (in client code). Also deployment plans can only change the values for annotations that are already present in the code. You cannot create a new configuration context through a deployment plan.

Control authors have control over which control properties can be overridden using external configuration in a deployment plan. For details see the @PropertySet annotation.

To create a deployment plan for a control, follow these steps:

Order of Precedence

The ControlBean always takes the highest order of precedence when overriding annotations values. The following order of precedence is used:

Note that programmatically calling ControlBean methods takes precedence over all other values.

For example, suppose you declare a timer control in your client code and set the timeoutSeconds value with an annotation:

    @TimerControl.TimerSettings(repeatsEverySeconds=2, timeoutSeconds = 100)
    @Control
    private TimerControl timerControl;

You can override this timeout value programmatically by calling into the TimerControlBean class.

First declare the TimerControlBean in your client.

    @Control
    private com.bea.control.TimerControlBean timerControlBean;

Then call the appropriate method to reset the timeout value.

    timerControlBean.setTimerSettingTimeoutSeconds(200);

Related Topics

The Control Authoring Model