Optional Configuration Schema

With the requirement to change component configuration from a Web Browser, or from a thick-client GUI, it would be nice to provide validation of the values being changed, values that are secret like passwords not shown, detailed descriptions of configuration fields, and descriptive displays of configuration parameter labels. Since this information cannot be obtained in a detailed fashion from Standard MBeans that may be used to create the Configuration MBeans, it is possible to provide these details in other ways that can be used by the UI to create appropriate renderers and Validators. If component developers want to leverage these features, here is what needs to be done.

The component developer has to provide a schema corresponding to the attributes that are available in their Configuration MBean, and xml data that correspond to detailed descriptions of the attributes. Based on this, the UI can create appropriate renderers and Validators.

This requires that the component developer provide a couple of operations to their Configuration MBeans. They are:

   1. public String retrieveConfigurationDisplaySchema();
   2. public String retrieveConfigurationDisplayData();

The retrieveConfigurationDisplaySchema Operation

The retrieveConfigurationDisplaySchema operation returns the schema (defined in XSD) of the attributes that the Component Config MBean exposes. The schema can define restrictions and thus allows the developer to specify Enumerated Strings (which may be displayed as DropDowns in the UI) or restrict the integer fields to positive integers, specify totalDigits, and minInclusive or maxExclusive – in effect any definition that can be expressed in XSD can be placed on these attributes.

Let’s illustrate this for a hypothetical Cache Aspect Service Engine that has a Configuration of 2 attributes:

   1. CachingStrategy – a String field that can have two values – GenericCache and FirstInFirstOutCache
   2. MaximumEntries – an Integer field that is a positive integer which can take values from 1 to 32765

The schema below is a typical string returned by the retrieveConfigurationDisplaySchema() operation of the hypothetical cache aspect service engine’s Configuration MBean:

<?xml version="1.0" encoding="UTF-8"?>

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
            targetNamespace="http://com.sun.jbi.component/schema/configuration"
            xmlns:tns="http://com.sun.jbi.component/schema/configuration"
            attributeFormDefault="unqualified"
            elementFormDefault="qualified">

    <xsd:element name="Configuration"
                 type="tns:ConfigurationType"/>

    <xsd:complexType name="ConfigurationType">
        <xsd:sequence>
            <xsd:element type="tns:CachingStrategyType" name="CachingStrategy">
                <xsd:annotation>           
                    <xsd:documentation>The Caching Strategy can be one of GenericCache or FirstInFirstOutCache.</xsd:documentation>       
                </xsd:annotation>                
            </xsd:element>
            <xsd:element type="tns:MaximumEntriesType" name="MaximumEntries">
                <xsd:annotation>           
                    <xsd:documentation>Maximum number of Cache Entries in case the Caching Strategy happens to be FistInFirstOutCache.</xsd:documentation>       
                </xsd:annotation>                
            </xsd:element>
        </xsd:sequence>

        <xsd:attribute type="xsd:string" name="name"/>
    </xsd:complexType>

    <xsd:complexType name="CachingStrategyType">
        <xsd:simpleContent>
            <xsd:extension base="tns:CachingStrategyRestrictedSimpleType">
                <xsd:attribute type="xsd:string" name="displayName"/>
                <xsd:attribute type="xsd:string" name="displayDescription"/>
                <xsd:attribute type="xsd:boolean" name="isPasswordField"/>
            </xsd:extension>
        </xsd:simpleContent>
    </xsd:complexType>
  
    <xsd:complexType name="MaximumEntriesType">
        <xsd:simpleContent>
            <xsd:extension base="tns:MaximumEntriesRestrictedSimpleType">
                <xsd:attribute type="xsd:string" name="displayName"/>
                <xsd:attribute type="xsd:string" name="displayDescription"/>
                <xsd:attribute type="xsd:boolean" name="isPasswordField"/>
            </xsd:extension>
        </xsd:simpleContent>
    </xsd:complexType>

    <xsd:simpleType name="MaximumEntriesRestrictedSimpleType">
        <xsd:restriction base="xsd:positiveInteger">
            <xsd:totalDigits value="5"/>
            <xsd:minInclusive value="1"/>
            <xsd:maxInclusive value="32765"/>
        </xsd:restriction>
    </xsd:simpleType>

    <xsd:simpleType name="CachingStrategyRestrictedSimpleType">
        <xsd:restriction base="xsd:string">
            <xsd:enumeration value="FirstInFirstOutCache"/>
            <xsd:enumeration value="GenericCache"/>
        </xsd:restriction>
    </xsd:simpleType> 

</xsd:schema>

The retrieveConfigurationDisplayData Operation

The retrieveConfigurationDisplayData operation returns the XML data corresponding to the schema (defined in XSD) of the attributes that the Component Config MBean exposes. It is here that the component developer can specify descriptive names for the attributes that can appear in label fields of the UI, descriptions of the fields that can appear in ToolTips, or whether the field is a secret field (like a password field) or not so the UI can hide the actual data the user be allowed to see from the UI.

The XML data below corresponds to the schema above and is a typical string returned by the retrieveConfigurationDisplayData() operation a hypothetical cache aspect service engine’s Configuration MBean:

<?xml version="1.0" encoding="UTF-8"?>

<componentConfig:Configuration name="com.sun.aspect.cachese-1.0.2"

                               xmlns:componentConfig="http://com.sun.jbi.component/schema/configuration"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://com.sun.jbi.component/schema/configuration/componentconfiguration.xsd">
  
    <componentConfig:CachingStrategy displayName="Caching Strategy to use"
                                     displayDescription="Determines Caching Strategy to use. Valid values are FirstInFirstOutCache or GenericCache"
                                     isPasswordField="false">FirstInFirstOutCache</componentConfig:CachingStrategy>
    <componentConfig:MaximumEntries displayName="Maximum Number of Entries to cache"
                                    displayDescription="Maximum Number of Entries to cache if it is a FirstInFirstOutCache"
                                isPasswordField="false">100</componentConfig:MaximumEntries>

</componentConfig:Configuration>

This page (revision-6) was last changed on 26-Jun-07 16:43 PM, -0700 by Yoke Lee.
This page was created on 26-Jun-07 16:35 PM, -0700 by Yoke Lee.

More info...