Previous Next vertical dots separating previous/next from contents/index/pdf

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. (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:

  1. configure the value in the client code's control declaration (for use by developers)
  2. set the value programmatically using the ControlBean API (for use by developers)
  3. configure the value using a deployment plan (for use by administrators)

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. (Client Code)

    private DatabaseControl dbControl;

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

    @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

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, 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.

    @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.

    private controls.CustomerDBBean customerDBBean;	

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


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 = {""})
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:

  1. Ensure that the application is packaged and deployed as an EAR file. The WebLogic Server console does not support deployment plans for exploded applications.

    To package your application as an EAR, select File > Export > EAR file.

    To use the WebLogic Server console to deploy the application EAR, see Install an Enterprise Application in the WebLogic Server documentation.
  2. Click the Lock & Edit button and click the Deployments link to go to the Summary of Deployments page and click the application name.
  3. Select the Deployment Plan tab and then the Resource Dependencies (sub-)tab.
  4. Within the Controls node, controls are located either under the module's name or Application (if the controls are part of a utility project). Controls are organized by classname, then instances, then fields. Select the annotation to be overridden. This will display the Array Value Overrides table.
  5. Select a cell in the Override Value column, enter the override value, and press the Enter key.
  6. After entering the new value click Save button on the Array Value Overrides table.
  7. Select a location to store the deployment plan and click Finish.
  8. Return to the Deployments page by clicking the Deployments link.

    If the application is not started (its state is marked as "Prepared"), then select the checkbox next to the application, and click the Start button.

    If the application is already running (its state is marked as "Active"), then select the checkbox next to the application and click the Update button. Select the first choice: Update this application in place, then click the Finish button.
  9. Click the Activate Changes button.

Order of Precedence

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

  1. First, the values programmatically set through the ControlBean are consulted (see Method 2 above).
  2. Second, any deployment plan overrides of values configured on the control declaration field are consulted (see Method 3 above).
  3. Third, the values configured on the field declaration are consulted (Method 1 above).
  4. Fourth, any deployment plan overrides of values set in the control definition are consulted (see Method 3 above).
  5. Finally, the values in the control definition class are consulted.

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)
    private TimerControl timerControl;

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

First declare the TimerControlBean in your client.

    private com.bea.control.TimerControlBean timerControlBean;

Then call the appropriate method to reset the timeout value.


Related Topics

The Control Authoring Model


Skip navigation bar   Back to Top