How Do I: Define Properties for a Java Control?

When you create a Java control, you can define properties and attributes that a developer can set to elicit specific behavior when using the control. This topic lists the procedure for defining and handling properties and their attributes:

  1. Create a New Annotations XML File — You define the properties and attributes themselves in an XML file that specifies property and attribute names, data types, default values, descriptions, and so on.
  2. Connect an Annotations XML file with Your Control Source Code — You "connect" this XML file to the control source using a JCS property, and WebLogic Workshop uses the XML file to determine how to display the property in the Property Editor, as display its corresponding annotations in source code.
  3. Enable a Java control to Retrieve Its Property Attribute Values at Run Time — You write code to handle potential property attribute values by calling methods of the ControlContext interface.

Note. For an introduction to building Java controls, including specifying properties, see Tutorial: Java Control.

Create a New Annotations XML File

  1. In the Application tab, locate the folder in which you want to save your new annotations file.

    Typically, this is the same folder that contains the JCS for which the annotations will apply.

  2. Right-click the folder, then click New --> Other File Type.
  3. In the New File dialog, in the left-hand pane, click Business Logic.
  4. In the right-hand pane, click Control Annotation File.
  5. In the File name box, type a new for the new annotations XML file.

    This is typically a name that associates the file with the control. For example, if your control source file is called MyControl.jcs, you might call the annotations file MyControlAnnotations.xml.

  6. Click Create.

    WebLogic Workshop will display the contents of the new file, which includes template XML source code.

  7. Edit the new file so that it defines the properties and attributes your control should expose.

    The template in the new file is a starting place. It defines a sample-control-tag property that would be exposed on a control instance (that is, for the control as a whole). It also defines a sample-method-tag property that would be exposed on a control method.

    The sample-control-tag property defines a sample-attr attribute whose type is boolean. This attribute is marked as not being "required," which means that a developer using the control would not need to set the attribute explicitly. As a result, the sample-attr attribute specifies a default value of "false" to use if the developer does not set their own value.

    See Control Property Schema Reference for a complete list of the XML tags you can use to define Java control properties.

Once you have define properties in an annotation XML file, you must "connect" the file to your control source code.

Connect an Annotations XML file with Your Control Source Code

  1. Open your Java control source (JCS) file in Design View.
  2. Click the design for your control (you can click in the center of the design), so that its properties are displayed in the Property Editor.

    The control's name should be displayed just beneath the Property Editor tab.

  3. Locate the control-tags property, type the path to your annotations XML file in the box for the control-tags file attribute, then press Enter.

    This should be a relative path. If your XML file is in the same folder as the JCS, you need only type the XML file name. If the XML is in a subfolder, you must include that folder's name.

You can now write code that enables the control to retrieve values set by a developer using the control.

Enable a Java control to Retrieve Its Property Attribute Values at Run Time

In your source code, call methods of the ControlContext object, specifying the names of your property and its attributes.

For example, if you had used the sample-control-tag property and sample-attr attribute defined by the annotation template, you might use the following code to simply return the attribute's value from a method on the control called getSampleAttr:

/** @common:context */
ControlContext context;

/**
  * @common:operation
  */
public boolean getSampleAttr()
{
    /* 
     * Call the getControlAttribute method, passing a string with the name of the 
     * property as its annotation appears in source code, along with the name of the 
     * attribute whose value should be retrieved.
     */ 
    String sampleAttrValue = context.getControlAttribute("jc:sample-control-tag",
	    "sample-attr");        

    /* Because the method returns a String, convert the value to a boolean. */
    boolean booleanValue = new Boolean(sampleAttrValue).booleanValue();
    return booleanValue;
}

Samples

For a sample that uses control properties, see the POVerify sample included in the SamplesApp application installed with WebLogic Workshop.

Related Topics

Tutorial: Java Control

@jcs:control-tags Annotation

ControlContext Interface

Control Property Schema Reference