Component Configuration

---

Rules to Minimize data type mismatch problems

Runtime Management and Monitoring MBeans will only use data types that can be expressed unambiguously through an XML-Schema. That means, only use a set of basic data types that can be marshaled and unmarshaled in a platform and programming language-neutral manner for attributes, operation parameters and return types. These data types include:

• Primitive types (int, long, boolean, etc.),
• Primitive wrapper classes (Integer, Long, Boolean, etc.) - http://java.sun.com/j2se/1.5.0/docs/api/javax/management/openmbean/OpenType.html#ALLOWED_CLASSNAMES,
• Enumeration classes (Enum),
• Classes that define a mechanism to convert from an input CompositeData class to an instance of that class.
• List and Map types are supported as long as the contained objects are primitive types, primitive wrapper classes, enumerations, or a class supporting CompositeData conversion.

The above guidelines follow the same restrictions imposed by the new MXBeans (http://java.sun.com/j2se/1.5.0/docs/api/java/lang/management/ManagementFactory.html#MXBean), a new kind of MBeans introduced in J2SE 5.0 which do exactly this to minimize data type mismatch problems.

---

Runtime Configuration and Installer MBeans

Installer Extension MBeans should have names of the format:

• com.sun.ebi:ComponentName= stchttpsoap-b393-4f54-aaad-9294ae9c5a23,ComponentType=Installed,ControlType=InstallerExtension,InstalledType=Binding
• com.sun.ebi:ComponentName= bpelserviceengine-9bfbff60-467d-11d9-9669-0800200c9a66,ComponentType=Installed,ControlType=InstallerExtension,InstalledType=Engine

Similarly, Runtime configuration MBeans should have names of the format:

• com.sun.ebi:ServiceType= Configuration,InstallationType=bindingComponents,IdentificationName=stchttpsoap-b393-4f54-aaad-9294ae9c5a23
• com.sun.ebi:ServiceType= Configuration,InstallationType=serviceEngines,IdentificationName=bpelserviceengine-9bfbff60-467d-11d9-9669-0800200c9a66

---

Object Naming

A valid ObjectName will be of the form: SUN_EBI_DOMAIN:
SERVICE_TYPE=SERVICE_TYPE_NAME,
INSTALLATION_TYPE=INSTALLATION_TYPE_NAME,
IDENTIFICATION_NAME_TYPE=IDENTIFICATION_NAME
Where:
SUN_ EBI_DOMAIN is com.sun.ebi

SERVICE_TYPE is ServiceType

SERVICE_TYPE_NAME will have one of the following values:

1. Status
2. Configuration

INSTALLATION_TYPE is InstallationType INSTALLATION_TYPE_NAME will have one of the following values:

1. bindingComponents
2. serviceEngines
3. sharedLibraries
4. serviceAssemblies

IDENTIFICATION_NAME_TYPE is IdentificationName IDENTIFICATION_NAME will have the Identification Name of the installed JBI component (ServiceEngine or Binding Component or Shared Library or Service Assembly) Examples of valid ObjectNames

• An MBean that allows configuration changes at runtime for a Binding Component type with an Identification Name stchttpsoap-b393-4f54-aaad-9294ae9c5a23 will be:

com.sun.ebi:ServiceType=Configuration,InstallationType=bindingComponents,IdentificationName=stchttpsoap-b393-4f54-aaad-9294ae9c5a23

• An MBean that provides Status updates at runtime for a Service Engine type with an Identification Name bpelserviceengine-9bfbff60-467d-11d9-9669-0800200c9a66 will be:

com.sun.ebi:ServiceType=Status,InstallationType=serviceEngines,IdentificationName=bpelserviceengine-9bfbff60-467d-11d9-9669-0800200c9a66

---

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>

---

Back to CAM

This page (revision-8) was last changed on 26-Jun-07 18:47 PM, -0700 by Gopalan Suresh Raj.
This page was created on 26-Jun-07 18:28 PM, -0700 by Gopalan Suresh Raj.

More info...