Step 8: Compile the Java Control and Add a Property

In the previous steps you built a control that encapsulates some useful business logic. In this step, you’ll compile the Investigate Java control into a JAR file for greater portability.

For many needs, it’s perfectly fine to use the control’s source files directly within the same project as the control's container or client, as is the case with Investigate's web service container, InvestigateTest.jws. But what if you’re designing a control that might be useful from many containers? It could get tedious to copy a set of source files from project to project. To solve this problem we will package the control in a JAR file that’s much easier to copy into different containers.

You begin the process of packaging by moving the control into its own control project. A control project includes files and annotations that support the control as a separately distributable package. You can even develop the sources for multiple controls within a single project, and package them all in a single JAR file for distribution.

Before you compile the Investigate Java control, you will add one more layer of functionality. You will add a property to the Investigate control, which will allow developers using the control to change the way it functions.

You'll start by creating a project in which to further develop your Java control's source files.

The tasks in the step are:

To Move Investigate to a Control Project

In this task you will move two items. First you will move the test web service InvestigateTest.jws into its own folder. Second you will move the Investigate Java control into its own Control project. It is necessary to separate the Investigate Java control from its test web service because web services aren't enabled in Control projects.

     

  1. On the Application tab, right click the JavaControlTutorialWeb folder and select New-->Folder.
  2. In the Create New Folder dialog, enter test.

  3. Click Ok.
  4. On the Application tab, hold the mouse button down over the test web service InvestigateTest.jws and drag it into the folder JavaControlTutorialWeb/test.
  5. On the Application tab, right-click the JavaControlTutorial folder and choose New-->Project.
  6. In the New Project dialog, in the upper left-hand pane, confirm that All is selected.
    In the upper right-hand pane, select Control Project.
    In the Project Name field, enter Investigate.

  7. Click Create.
    WebLogic Workshop adds a new control project called Investigate.
  8. On the Application tab, hold down the mouse button over folder investigateJCS, drag it into the Investigate project folder.

    The Application tab should look like the following.



To Set Investigate's Properties

  1. Open the investigateJCS folder you just moved, then double-click InvestigateImpl.jcs. Click the Design View tab.
  2. Make sure that the control's design is selected by clicking its title bar in Design View.

  3. On the Property Editor tab, in the section labeled jc-jar, edit the property attributes as shown in the following figure. (You may want to re-size the Property Editor tab to make it easier to work with.)




  4. These properties provide information that WebLogic Workshop will present to a developer using the Investigate Java control. The label corresponds to the control's name on menus and palettes; the icon-16 attribute value is a relative path to the image associated with the control in the IDE. Finally, if you look at the InvestigateImpl.jcs source code, you'll see that the values for these attributes have been written into the source as annotation attributes.

  5. Press Ctrl+S to save your work.
  6. Right-click the investigateJCS folder and select New-->Folder.
  7. In the Create New Folder dialog, type images and click OK.
  8. Holding down the mouse button over the image below, drag it to WebLogic Workshop's Application tab, and drop it in the images folder you just created.



    Before packaging and testing the control project, you’ll make one more enhancement to the control. With a little more code, you’ll make it possible for an application developer using your control to set the phone number users should call if they run into an error.
    You’ll start by defining a property for the Investigate Java control. To do this, you’ll create an InvestigateProperties.xml file to hold a description of the control's new property.

To Create a New Property for Investigate

  1. In the Application tab, right-click the investigateJCS folder and select New-->Other File Types.
  2. In the New File dialog, in the left-hand pane, click Business Logic.
    In the right-hand pane, click Control Annotation File.
    In the File name box, type InvestigateProperties.xml.

  3. Click Create.

    WebLogic Workshop creates the new XML file and displays it in the main work area. It contains a simple XML declaration and sample tags.

  4. Edit InvestigateProperties.xml so it appears as follows. Overwrite any XML elements already appearing in the file.
    <?xml version="1.0" ?>
    <control-tags xmlns="http://www.bea.com/2003/03/controls/">
        <control-tag name="error-message">
            <description>Properties relating to the error message.</description>
            <attribute name="phone-number" required="false">
                <description>
                    Sets the phone number to call in case of an error.
                </description>
                <type>
                    <text/>
                </type>
                <default-value>(555) 555-5555</default-value>
            </attribute>
        </control-tag>
    </control-tags>
    The <control-tag> element has a name attribute that specifies what the property will be called (error-message). The <description> element describes the property. The <attribute> element defines an attribute for the property: phone-number. The <attribute> element's "required" attribute is set to false, meaning that it's not necessary for a developer using the control to actually set the attribute in order for the control to work. As a result, the <default-value> element must be included here so that WebLogic Workshop knows what value to use if the developer doesn't explicitly set it. Finally, the <type> element specifies the attribute's type, similar to a data type. WebLogic Workshop will use this <type> value to do a bit of validation when the developer tries to set its value.
  5. Press Ctrl+S to save your work. Press Ctrl+F4 to close InvestigateProperties.xml.

To Edit Investigate to Use the New Property

  1. On the Application tab, double-click InvestigateImpl.jcs.
  2. Click the Design View tab, if necessary.
  3. On the Property Editor tab, in the section labeled control-tags, to the right of the property named file, click the ellipses symbol.

  4. In the Property Text Editor, enter InvestigateProperties.xml.

  5. Click Ok.
  6. Click the Source View tab.
  7. Add the following code to the the body of InvestigateImpl.jcs.
  8.     private String _phoneNumber;
  9. Add the following code to the top of the requestCreditReport method. Code to add appears in red.
  10.     /**
         * @common:operation
         * @common:message-buffer enable="true"
         */
        public void requestCreditReport(String taxID)
        {
            _phoneNumber = context.getControlAttribute("jc:error-message", "phone-number");
                
            m_currentApplicant.taxID = taxID;
        
            /*
             * Retrieve data from the database and store it in the rec object.
             */
            Record rec = bankruptciesDB.checkForBankruptcies(taxID);
    
  11. Press Ctrl+R.
  12. In the Replace Text dialog, in the Text to find field, enter (555) 555-5555
    In the Replace with field, enter " + _phoneNumber + "

  13. Click Replace.
  14. In the Confirm Replace dialog click All.
  15. Press Ctrl+S to save your work.

To Compile the Investigate Control

Note that this is a distributable JAR file: place it the the Libraries folder of any application to use the functionality of the Investigate Java control. (Note that any application that uses the JAR file must also have access to the Database, web service, JMS application, and EJB application that are used by the Java control.)

Also note that once you have compiled a Java control, WebLogic Workshop uses the JAR version by default, instead of working directly from the source code contained in the control project. For this reason, you could remove the control project from your application, and your test web service would still run successfully, because it would use the JAR version of the Java control.

To Test the Investigate Java Control

  1. On the Application tab, double-click InvestigateTest.jws.
  2. Click the Design View.
  3. Select the icon for the Investigate control. (Note that the GIF file has been incorporated into the new icon.)

  4. On the Property Editor tab, in the section labeled error-message, locate the phone-number property, and enter (123) 456-7890.
  5. Click the Start button, shown here:

    Workshop builds TestClient.jws and launches the Test Browser.
  6. In the Workshop Test Browser, in the taxID field, enter wrong_taxid and click the requestCreditReport button.
    Note that you are intentionally entering an invalid taxID to cause an error message. When the callback arrives you should see the following message.



    Note the value of the <ns:message> element has incorporated the phone number you specified: (123) 456-7890.

Click one of the following arrows to navigate through the tutorial: