Control Properties Overview

Java control properties provide a way for a control's user to specify values that should be in effect for the duration of a control's run-time use. A user sets a control's properties at design time, and those values are compiled into the control's logic. A control author writes the control's logic so it uses the property values to make the control's behavior specific to the user's needs.

As a control author, you define properties in an annotations XML file conforming to a special annotations schema. To connect the XML file to your control, you give the XML file's name as a value of the JCS file's jc-jar property, in the file attribute.

IDE Support

WebLogic Workshop provides the following built-in support for your control's properties:

As you define control properties, you may want to validate your XML file against its schema. The schema is defined in ControlAnnotations.xsd, which is provided with the ControlDevKit sample application. You can use a third-party authoring tool such as XMLSpy to validate your annotations XML file.

Property Annotations

The WebLogic Workshop IDE exposes properties in two ways: A control's user can set property attribute values using the Property Editor; also, attribute values that have been edited are visible as annotations in source code, where edited values are persisted. In general, the Property Editor (or a custom dialog available from it) is the way that users will interact with properties and their attributes. However, for a control author, who defines properties and attributes and handles them in code, properties and attributes are exposed as annotations and their attributes.

You create a control annotation XML file to define the properties and attributes your control will expose. Through this file, you define:

Property Scope

You can specify that a property be applicable in one of three contexts. As you design your control, the decisions you make will include the properties the control must expose, and the scope for each.

When you define you properties in a control annotation XML file, you will specify how a property is applied in the following contexts:

Note: Keep in mind that in WebLogic Workshop, it is possible for a user to set property values in both the container code, on the instance declaration, and in the JCX file. This is done by opening the JCX file in Design View, then setting control properties. However, annotations on an instance declaration, where they exist, will always override those in a JCX file.

WebLogic Workshop provides a way for you get property values at run time. You use the ControlContext class to retrieve these values.

Attribute Groups

The annotation XML schema supports creating attribute groups. You create an attribute group when you want to define a relationship between the attributes belong to a particular property. You can specify that when a user is setting a property's attributes, the control allows at most one, exactly one, or at least one. For more information, see the Control Property Schema Reference material in the WebLogic Workshop documentation.

The following is an example of a simple annotation XML file.

<control-tags editor-class="corp.controls.DeptEditorSupport">
    <control-tag name="department">
    <description>Specifies information about the department making requests.</description>
        <attribute-group group-type="exactly-one">
            <attribute name="abbreviation" required="true">
                <description>Specifies the department's four-letter abbreviation.</description>
                <type>
                    <text max-length="4"/>
                </type>
                </attribute>
            <attribute name="id" required="true">
                <description>Specifies the department's ID number.</description>
                <type>
                    <integer/>
                </type>
            </attribute>
        </attribute-group>
    </control-tag>
    <method-tag name="credentials">
        <description>Specifies authentication credentials. Default values will be useful 
            for calls to departments other than those above level 2.</description>
        <attribute name="username" required="false">
            <description>Specifies the name to use for authentication.</description>
            <type>
                <text/>
            </type>
            <default-value>anon</default-value>
        </attribute>
        <attribute name="password" required="false">
        <description>Specifies the password to use for authentication.</description>
            <type>
                <text/>
            </type>
            <default-value>anon</default-value>
        </attribute>
    </method-tag>
</control-tags>

This file defines the following:

Property Validation

By default, WebLogic Workshop provides validation for all but one of the property attribute types defined in the annotation schema -- including boolean, decimal, enumeration, and so on. The exception is the custom type, which is provided so that you can define you own type. You do this by writing a class that the IDE can use to validate values set by the user for a custom type. You can specify that validation occurs both in user interface (such as a custom attribute editor dialog) or in Source View. For more information, see Creating Attribute Editors and Validators.

The type supported for properties are boolean, class-name, class-names, date, decimal, enumeration, file-path, integer, QNAME, text, URI, URL, URN, XML, and custom. For more information on each of the types, see the Control Property Schema Reference in the WebLogic Workshop documentation.

Retrieving Attribute Values Set By a Control's User

You can retrieve the values set by users for your control's property attributes. You do this by calling one of the ControlContext methods designed for this purpose.

Note that all of these methods are context-specific. For example, if your control is extensible your JCS file will implement the Extensible interface's invoke method to handle calls to methods defined in a JCX extending the control. The context for each of those calls to invoke is a particular JCX method in a particular JCX. Calling getMethodAttributes from within an invoke implementation will return the attributes and values for the specified property on that method.

Code to get the credentials property's attribute values defined in the preceding example might look like the following. This code would be executed in the context of the invoke method implementation:

String username = context.getMethodAttribute("jc:credentials", "username");
String password = context.getMethodAttribute("jc:credentials", "password");

Related Topics

None.