6 Adding Configuration Data for a Component

To Define an Element

1. Define a Java language interface to represent the element.

   Define one interface for each element. Do not represent multiple elements in a single interface.

   The name that you give to the interface determines name of the element as follows:

   • A change from lowercase to uppercase in the interface name is transformed to the hyphen (-) separator character.

   • The element name is all lowercase.

   For example, to define an interface to represent the wombat-container-config element, give the name WombatContainerConfig to the interface.

2. Specify the parent of the element.

   To specify the parent, extend the interface that identifies the parent as shown in the following table.

   Parent Element	Interface to Extend
   config	org.glassfish.api.admin.config.Container
   applications	org.glassfish.api.admin.config.ApplicationName
   Another element that you are defining	org.jvnet.hk2.config.ConfigBeanProxy

   
   

3. Annotate the declaration of the interface with the org.jvnet.hk2.config.Configured annotation.

...
import org.jvnet.hk2.config.Configured;
...
import org.glassfish.api.admin.config.Container;
...
@Configured
public interface WombatContainerConfig extends Container {
...
} 

How Interfaces That Are Annotated With @Configured Are Implemented

You are not required to implement any interfaces that you annotate with the @Configured annotation. GlassFish Server implements these interfaces by using the Dom class. GlassFish Server creates a Java Platform, Standard Edition (Java SE) proxy for each Dom object to implement the interface.

Representing an Attribute of an Element

Represent each attribute of an element as the property of a pair of JavaBeans specification getter and setter methods of the interface that defines the element. The component for which the configuration data is being defined can then access the attribute through the getter method. The setter method enables the attribute to be updated.

Specifying the Data Type of an Attribute

The data type of an attribute is the return type of the getter method that is associated with the attribute. To enable the attribute take properties in the form ${property-name} as values, specify the data type as String.

Identifying an Attribute of an Element

To identify an attribute of an element, annotate the declaration of the getter method that is associated with the attribute with the org.jvnet.hk2.config.Attribute annotation.

To specify the properties of the attribute, use the elements of the @Attribute annotation as explained in the sections that follow.

Specifying the Name of an Attribute

To specify the name of an attribute, set the value element of the @Attribute annotation to a string that specifies the name. If you do not set this element, the name is derived from the name of the property as follows:

• A change from lowercase to uppercase in the interface name is transformed to the hyphen (-) separator character.

• The element name is all lowercase.

For example, if the getter method getNumberOfInstances is defined for the property NumberOfInstances to represent an attribute, the name of the attribute is number-of-instances.

Specifying the Default Value of an Attribute

The default value of an attribute is the value that is applied if the attribute is omitted when the element is written to the domain configuration file.

To specify the default value of an attribute, set the defaultValue element of the @Attribute annotation to a string that contains the default value. If you do not set this element, the parameter has no default value.

Specifying Whether an Attribute Is Required or Optional

Whether an attribute is required or optional determines how GlassFish Server responds if the parameter is omitted when the element is written to the domain configuration file:

• If the attribute is required, an error occurs.

• If the attribute is optional, the element is written successfully to the domain configuration file.

To specify whether an attribute is required or optional, set the required element of the @Attribute annotation as follows:

• If the attribute is required, set the required element to true.

• If the attribute is optional, set the required element to false. This value is the default.

Example of Defining an Attribute of an Element

import org.jvnet.hk2.config.Attribute;
...
    @Attribute
    public String getNumberOfInstances();
    public void setNumberOfInstances(String instances) throws PropertyVetoException;
...

To Define a Subelement

1. Define an interface to represent the subelement.

   For more information, see Defining an Element.

   The interface that represents the subelement must extend the org.jvnet.hk2.config.ConfigBeanProxy interface.

2. In the interface that defines the parent element, identify the subelement to its parent element.

   1. Represent the subelement as the property of a JavaBeans specification getter or setter method.

   2. Annotate the declaration of the getter or setter method that is associated with the subelement with the org.jvnet.hk2.config.Element annotation.

...
import org.jvnet.hk2.config.ConfigBeanProxy;
import org.jvnet.hk2.config.Configured;
...
@Configured
public interface WombatElement extends ConfigBeanProxy {
...
}
...

...
import org.jvnet.hk2.config.Element;
...
import java.beans.PropertyVetoException;
...
@Element
    public WombatElement getElement();
    public void setElement(WombatElement element) throws PropertyVetoException;
...

To Define a Component's Initial Configuration Data

1. Create a plain-text file that contains an XML fragment to represent the configuration data.

   • Ensure that each XML element accurately represents the interface that is defined for the element.

   • Ensure that any subelements that you are initializing are correctly nested.

   • Set attributes of the elements to their required initial values.

2. When you package the component, include the file that contains the XML fragment in the component's JAR file.

<wombat-container-config>
    <wombat-element foo="something" bar="anything"/>
</wombat-container-config>

To Write a Component's Initial Configuration Data to the domain.xml File

Add code to write the component's initial configuration data in the class that represents your add-on component. If your add-on component is a container, add this code to the sniffer class. For more information about adding a container, see Adding Container Capabilities.

1. Set an optional dependency on an instance of the class that represents the XML element that you are adding.

   1. Initialize the instance variable to null.

      If the element is not present in the domain.xml file when the add-on component is initialized, the instance variable remains null.

   2. Annotate the declaration of the instance variable with the org.jvnet.hk2.annotations.Inject annotation.

   3. Set the optional element of the @Inject annotation to true.

2. Set a dependency on an instance of the following classes:

   • org.glassfish.api.admin.config.ConfigParser

     The ConfigParser class provides methods to parse an XML fragment and to write the fragment to the correct location in the domain.xml file.

   • org.jvnet.hk2.component.Habitat

3. Invoke the parseContainerConfig method of the ConfigParser object only if the instance is null.

   If your add-on component is a container, invoke this method within the implementation of the setup method the sniffer class. When the container is first instantiated, GlassFish Server invokes the setup method.

   The test that the instance is null is required to ensure that the configuration data is added only if the data is not already present in the domain.xml file.

   In the invocation of the parseContainerConfig method, pass the following items as parameters:

   • The Habitat object on which you set a dependency

   • The URL to the file that contains the XML fragment that represents the configuration data

...
import org.glassfish.api.admin.config.ConfigParser;
import org.glassfish.examples.extension.config.WombatContainerConfig;
...
import org.jvnet.hk2.annotations.Inject;
import org.jvnet.hk2.component.Habitat;
import com.sun.enterprise.module.Module;

import java.util.logging.Logger;
...
import java.io.IOException;
import java.lang.annotation.Annotation;
import java.lang.reflect.Array;
import java.net.URL;
...
    @Inject(optional=true)
    WombatContainerConfig config=null;
...
@Inject
    ConfigParser configParser;

    @Inject
    Habitat habitat;

    public Module[] setup(String containerHome, Logger logger) throws IOException {
        if (config==null) {
            URL url = this.getClass().getClassLoader().getResource("init.xml");
            if (url!=null) {
               configParser.parseContainerConfig(habitat, url, 
                   WombatContainerConfig.class);
            }
        }
        return null;
    }
...

<domain...>
...
   <configs>
    <config name="server-config">
      <wombat-container-config number-of-instances="5">
        <wombat-element foo="something" bar="anything" />
      </wombat-container-config>
      <http-service>
...
</domain>  

To Create a Transaction to Update Configuration Data

Any transaction that you create to modify configuration data must use a configuration change transaction to ensure that the change is atomic, consistent, isolated, and durable (ACID).

1. Set a dependency on the configuration object to update.

2. Define a method to invoke to perform the transaction.

   1. Use the generic SimpleConfigCode interface to define the method that is to be invoked on a single configuration object, namely: SingleConfigCode<T extends ConfigBeanProxy>().

   2. In the body of this method, implement the run method of the SingleConfigCode<T extends ConfigBeanProxy> interface.

   3. In the body of the run method, invoke the setter methods that are defined for the attributes that you are setting.

      These setter methods are defined in the interface that represents the element whose elements you are setting.

3. Invoke the static method org.jvnet.hk2.config.ConfigSupport.ConfigSupport.apply.

   In the invocation, pass the following information as parameters to the method:

   • The code of the method that you defined in Step  2.

   • The configuration object to update, on which you set the dependency in Step 1.

...
import org.glassfish.api.Param;
...
import org.jvnet.hk2.annotations.Inject;
import org.jvnet.hk2.config.Transactions;
import org.jvnet.hk2.config.ConfigSupport;
import org.jvnet.hk2.config.SingleConfigCode;
import org.jvnet.hk2.config.TransactionFailure;
...
    @Param
    String instances;

    @Inject
    WombatContainerConfig config;

    public void execute(AdminCommandContext adminCommandContext) {
        try {
            ConfigSupport.apply(new SingleConfigCode<WombatContainerConfig>() {
                public Object run(WombatContainerConfig wombatContainerConfig) 
                        throws PropertyVetoException, TransactionFailure {
                    wombatContainerConfig.setNumberOfInstances(instances);
                    return null;
                }
            }, config);
        } catch(TransactionFailure e) {            
        }
    }
...