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.
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.
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:
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:
Values for instance properties are scoped to the control instance as a unit, rather than to specific methods or callbacks.
For example, the Database control exposes an instance-scoped connection property whose data-source-jndi-name attribute specifies the data source that all methods of the control will use. For a control that is not extensible (does not generate a JCX file as a extension), all properties must be scoped to the instance.
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.
Values for interface method properties are scoped to the method they're applied to. For example, in the Database control the sql property is applied to a method, where its statement attribute specifies the SQL expression to use when the method is called.
Values for interface callback properties are scoped to the callback they're applied to. In the JMS control, a user can use attributes of the jms-header property to specify values for predefined JMS headers.
WebLogic Workshop provides a way for you get property values at run time. You use the ControlContext class to retrieve these values.
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:
@jc:department abbreviation="ACCT"
@jc:credentials username="gladyskravitz" password="snoop"
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.
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");
None.