Chapter 13 Using jagtool and jagant

XML configuration files

Rather than using jagtool or jagant to configure an entity's properties individually, you can define entity properties in XML. You can define and configure multiple entities in one XML file.

With jagtool, you can use the exportconfig command to create an XML configuration file that replicates an existing entity, and the configure command to apply the settings in an XML file to the repository.

You can also embed EAServer XML configuration files in J2EE-format archive files for components, applications, Web applications, and connectors, as described in "Using EAServer configuration files in J2EE archives".

Format of the XML configuration file

Configuration files must use this DTD, located in your EAServer installation:

java/lib/dtds/sybase-easerver-config_1_0.dtd

sybase-easerver-config element

The sybase-easerver-config element is the root element and can contain zero or more macro elements followed by one or more configure elements. You can use the description attribute for comment text; this text does not affect any properties set in the repository. Here is an example:

<sybase-easerver-config description="Configuring EAServer properties">
... deleted ...
</sybase-easerver-config

macro elements

You can use macro elements to define abbreviations for commonly used strings in the XML file, such as the com.sybase.jaguar.component prefix used in most component property names. macro elements have optional begin and end attributes to specify the delimiters. If you do not specify them, the default begin and end delimiters are ${ and } , respectively. The macro element can contain one or more definition elements to specify the macro abbreviations, for example:

<macro begin="${" end="}">
    <definition name="comp" value="com.sybase.jaguar.component"/>
    <definition name="desc" value="com.sybase.jaguar.description"/>
</macro>

configure elements

A configure element creates and updates an entity. The value of the type attribute specifies the operation to perform, as follows:

Value of type attribute	Action
create	Create a new entity with the specified name and with the specified properties. The operation fails if the entity already exists.
update	Update the specified properties for an existing entity. The operation fails if the entity does not exist.
delete	Deletes the specified property settings from an existing entity. The operation fails if the entity does not exist.

If you are embedding an XML file in a J2EE archive to configure entities defined in the archive, use the update operation. Entities defined in the file will exist when the XML configuration file is applied.

The entity attribute specifies the entity to operate on, using the format described in "Entity identifiers". The configure element can contain 0 or more property elements to configure the entity's properties.

Here is an example configure element:

  <configure type="create" entity="Package:DocTest">
    <property name="${desc}" value="New package" />
  </configure>

property elements

The property element specifies a property setting for the entity, for example:

<property name="com.sybase.jaguar.component.stateless" value="true" />

Sample configuration file

Here is a sample configuration file that defines a package, DocTest, and a component in the package, FooComponent:

<!DOCTYPE sybase-easerver-config PUBLIC '-//Sybase, Inc.//DTD EAServer configuration 1.0//EN' 'http://www.sybase.com/dtds/easerver/sybase-easerver-config_1_0.dtd'>

<sybase-easerver-config description="Configuring EAServer properties">
  <macro begin="${" end="}">
        <definition name="comp" value="com.sybase.jaguar.component"/>
        <definition name="desc" value="com.sybase.jaguar.description"/>
  </macro>
  <configure type="create" entity="Package:DocTest">
    <property name="${desc}" value="New package" />
  </configure>
  <configure type="create" entity="Component:DocTest/FooComponent">
    <property name="${comp}.debug" value="true" />
    <property name="${comp}.name" value="DocTest/FooComponent" />
    <property name="${desc}" value="New description" />
    <property name="com.sybase.jaguar.component.type" value="java" />
    <property name="com.sybase.jaguar.component.control" value="JaguarEJB::ServerBean" />
    <property name="com.sybase.jaguar.component.sharing" value="true" />
    <property name="com.sybase.jaguar.component.roles" value="" />
    <property name="com.sybase.jaguar.component.tx_outcome" value="always" />
    <property name="com.sybase.jaguar.component.pooling" value="false" />
    <property name="com.sybase.jaguar.component.java.class" value="com.sybase.jaguar.sample.events.StockManagerImpl" />
    <property name="com.sybase.jaguar.component.thread.safe" value="true" />
    <property name="com.sybase.jaguar.component.stateless" value="false" />
    <property name="com.sybase.jaguar.component.java.classes" value="" />
    <property name="com.sybase.jaguar.component.interfaces" value="EventSamples::StockManager" />
    <property name="com.sybase.jaguar.component.ids" value="IDL:EventSamples/StockManager:1.0" />
    <property name="com.sybase.jaguar.component.transient" value="false" />
    <property name="com.sybase.jaguar.component.auto.failover" value="false" />
    <property name="com.sybase.jaguar.component.tx_type" value="not_supported" />
    <property name="com.sybase.jaguar.component.tx_control" value="true" />
    <property name="com.sybase.jaguar.component.refresh" value="true" />
    <property name="com.sybase.jaguar.component.model" value="com" />
    <property name="com.sybase.jaguar.component.tx_vote" value="false" />
  </configure>
 </sybase-easerver-config>