Source Files for Java Controls

At their most basic, Java controls you develop include a Java control source (JCS) file. You can also add properties to the control by including an annotation XML file.

For a step-by-step introduction to building Java controls, see Tutorial: Java Control.

Java Control Source Files

A Java control source (JCS) file contains the control's logic — the code that defines what the control does. In this file you define what each of the control's methods do. You can also define how control property values set by a developer influence the control's behavior, as in the following example.

When you add a new Java control source file to a project, WebLogic Workshop also adds a JAVA file that contains the control's public interface. Under most circumstances, you should not edit this file. By default, as you work in the JCS file, adding methods, callbacks, and implementation code, WebLogic Workshop keeps the interface in sync. For example, adding an operation to the JCS will also add a corresponding method to the JAVA file. Note that the JAVA file will be kept in sync only with respect to those methods with an @common:operation annotation. This means that if you add a method to the JCS, then remove it's @common:operation annotation, WebLogic Workshop will remove the method from the JAVA file.

For information on creating a new Java control, see How Do I: Begin a New Custom Java Control?

package hello; 

import com.bea.control.ControlContext;
import com.bea.control.ControlException;
	
/** 
 * A control implementation class contains the logic for a control.
 *
 * The code-gen annotation tells WebLogic Workshop to create and maintain this
 * control's interface. This removes the necessity for you to do so.
 *
 * The control-tags annotation associates this control source file
 * with the annotation XML file that describes the properties it
 * exposes.
 * 
 * @jcs:control-tags file="Hello-tags.xml"
 */
public class Hello 
{
    /** 
     * A constant to hold the name of the demeanor annotation.
     */
    public static final String TAG_DEMEANOR = "demeanor";
	
    /**
     * A constant to hold the name of the greetingStyle attribute.
     */ 
    public static final String ATTR_GREETING_STYLE = "greetingStyle";
	
    /** 
     * The ControlContext interface provides access to aspects of a control's
     * container, including the properties stored for the control.
     *
     * @common:context
     */
    ControlContext context;
	
    /** 
     * Control methods are operations, just as with the methods of a 
     * web service.
     *
     * @common:operation 
     */
    public String sayHello()
    {
        String response = null;
	
        /* 
         * Use the ControlContext interface to get the value of this control's 
         * greetingStyle property attribute.
         */
        String greetingStyle = context.getControlAttribute(TAG_DEMEANOR, ATTR_GREETING_STYLE);
	
        /* 
         * Return a greeting depending on the value the developer set in
         * the greetingStyle property attribute.
         */
        try {
            if (greetingStyle.equals("Cordial")) {
                response = "Hi! Nice weather we're having, eh?";
            }
            else if (greetingStyle.equals("Familiar")) {
                response = "Hi! How's the family?";
            }
            else if (greetingStyle.equals("Professional")) {
                response = "Hi! Great job on that presentation!";
            }

        /* 
         * Throw a ControlException if something unexpected happened. 
         */
        } catch (Exception e) {
            throw new ControlException("There was an error greeting you!", e); 
        }
        return response;
    }
} 

Control Property Definition File

The property definition file is an annotation XML file that defines the properties a control exposes, including their data types.

You create a property definition file based on a particular schema. For more information about the schema, see Control Property Schema Reference. For step-by-step instructions on creating an annotations XML file and connecting it with your Java control, see How Do I: Define Properties for a Java Control?

The following example illustrates how you might define the properties for the preceding Hello sample. The property characteristics specified in this example include:

    <control-tags xmlns="http://www.bea.com/2003/03/controls/">
        <control-tag name="demeanor">
            <description>Defines the style of greeting this control returns.</description>
            <attribute name="greetingStyle" required="false">
                <description>Defines the style of greeting this control returns.</description>
                <type>
                    <enumeration>
                        <value>Cordial</value>
                        <value>Familiar</value>
                        <value>Professional</value>
                    </enumeration>
                </type>
                <default-value>Cordial</default-value>
            </attribute>
        </control-tag>
    </control-tags>

Related Topics

Tutorial: Java Control