Configuration Contract Tags
The configuration contract XML document is specified using the tags and attributes described in the following tables and sections.
The tables list all the tags and attributes available when writing the configuration contract. It also indicates whether these are optional or required.
Name | Attribute(s) | May occur in | Required |
---|---|---|---|
contract | object-version | - | Yes (exactly 1) |
class-name | - | contract | Yes (exactly 1) |
package-name | - | contract | Yes (exactly 1) |
storable-id | - | contract | Yes (exactly 1) |
delegate | id | contract | No (exactly 1) |
upgradable-delegate | - | delegate | No (exactly 1) |
field | active, hidden, id, level, since | section | Yes (min 1) |
title | - | field | Yes (exactly 1) |
name | - | field | Yes (exactly 1) |
description | - | field | Yes (max 1) |
type | - | field | Yes (exactly 1) |
primitive-type | name | type, list-of, array-of, map-of, set-of | No (max 1) |
object-type | name | type, list-of, array-of, map-of, set-of | No (max 1) |
enum-type | name | type, list-of, array-of, map-of, set-of | No (max 1) |
password-type | - | type, list-of, array-of, map-of, set-of | No (max 1) |
drstorable-type | name, profileType | type, list-of, array-of, map-of, set-of | No (max 1) |
drdate-type | - | type, list-of, array-of, map-of, set-of | No (max 1) |
list-of | - | type | No (max 1) |
array-of | - | type | No (max 1) |
set-of | - | type | No (max 1) |
default-value | - | field | Yes (max 1) |
null-value | - | field | Yes (max 1) |
allow-null | - | field | Yes (max 1) |
tooltip | - | field | Yes (max 1) |
validation | - | field | Yes (max 1) |
validate | minLength, maxLength, minValue, maxValue, isValidRegExp, isValidTZ, notNull, matchRegexp, negateRegexp, matchValue, message | validation | No (unlimited) |
These are the available attributes:
Name | May occur in | Required |
---|---|---|
object-version | contract | Yes |
id | field, section, delegate | Yes |
active | field | No |
hidden | field | No |
level | field | No |
since | field | No |
minLength | validate | No |
maxLength | validate | No |
minValue | validate | No |
maxValue | validate | No |
isValidRegExp | validate | No |
isValidTZ | validate | No |
notNull | validate | No |
matchRegexp | validate | No |
negateRegexp | validate | No |
matchValue | validate | No |
message | validate | Yes |
name | primitive-type, object-type, enum-type, drstorable-type | Yes |
profileType | drstorable-type | No |
contract
The configuration contract starts with a contract declaration. The contract
tags should enclose all other tags.
Syntax:
<contract object-version='1.0'>
The object-version
attribute specifies the configuration version that this contract was designed for.
Note!
The mz-version
attribute for contract
is deprecated and has been replaced with the object-version
attribute. However, to enable backward compatibility, the mz-version
attribute will still work.
class-name
This tag specifies the name of the the Java class that should be generated, and is part of the header in the configuration contract.
Syntax:
<class-name>DiskCollectionConfig</class-name>
package-name
This tag specifies the package name of the the Java class that should be generated, and is part of the header in the configuration contract.
Syntax:
<package-name>com.digitalroute.diskcollection</package-name>
The package name will determine in which directory you must be located when creating the *.jar file as described in Creating a User Defined Jar File in chapter 3, [copy of]3. Creating a DTK Plugin. With the package name stated in the syntax above, you will have to be where the /com/digitalroute/diskcollection/ directory is located when creating the *.jar file.
storable-id
When specified, the storable-id will be used instead of the classname in exported configurations, and when configurations are persisted to the database. As a result of this, the class can be moved or renamed without breaking existing configurations. This tag is part of the header in the configuration contract.
Syntax:
<storable-id>Prefix.DiskCollectionConfig</storable-id>
Suggested prefix is the company name or similar.
delegate
The delegate
tag is a place holder for various types of sub delegate tags, which are used for triggering specific functions defined in the stated Java class. All sub delegate tags must be enclosed by the main delegate
tags, which are part of the header in the configuration contract.
Syntax:
<delegate id='com.companyname.myagent.AgentDelegate'> <upgradable-delegate/> </delegate>
The delegate
tag has the following attributes:
Attribute | Description |
---|---|
| The Java class that shall be called when the delegate is triggered. This Java class must implement the java interface for the delegate. |
upgradable-delegate
The upgradable-delegate is used for handling upgrades in configuration contracts If the upgradable-delegate
tag is included, the Java class stated as id
in the main delegate
tag is called when the mzsh upgradeconfig command, or the mzsh systemimport with the -u|-upgrade flag, is used.
The upgradeable-delegate
tag must be enclosed by delegate
tags, and the delegate class must implement java interface UpgradableDelegate
.
Syntax:
<upgradable-delegate>
Â
In the class called you can configure the changes to be made, e g if a field has been changed, added, or renamed, or if types have been changed.
Example - Upgrade procedure
This is an example of how an upgrade procedure may be performed:
- In the configuration contract for Agent Z, some fields have been changed in version Y.
- A new Java class is needed to implement the UpgradeDelegate interface. This interface is then used as ID in the
<delegate>...</delegate>
section in the configuration contract, i eagentz.Delegate.java.
- In the configuration contract for Agent Z a
<delegate>...</delegate>
section is added with the IDagentzDelegate.java
and containing an<upgradable-delegate>
tag. - The configuration contract is sent to the Contract Tool which generates a new Java file that should be compiled. The resulting package should be committed using
pcommit
. - By running the
mzsh upgradeconfig
command, the configurations containing this agent will be upgraded with the changes and information about the upgrade will be stored in a an upgrader-log.
section
The section
tag specifies a logical grouping of a number of fields that may be configured in the the agent's configuration dialog.
Syntax:
<section id='Disk Collection'/>
The id
attribute is the identifier for the section.
field
The field tag is the heart of the configuration contract. Each field tag defines a piece of data that can be configured for the agent, and encloses all of the field related tags.
Syntax:
<field id='directory' level='any' active='true'/> <title>Directory</title> <name>Directory</name> <type> ... </type> </field>
The field
tag has the following attributes:
Attribute | Description | ||||||
---|---|---|---|---|---|---|---|
| The | ||||||
| The | ||||||
id | The id attribute is mandatory and must be unique within the configuration contract. | ||||||
| The
| ||||||
| The |
title
The title
tag identifies the field in the GUI, and should be enclosed by the field
tags.
Syntax:
<title>Directory</title>
name
The name
tag identifies a field when the object is serialized. The value must therefore be unique within the contract document. This tag should be enclosed by the field
tags.
Syntax:
<name>Directory</name>
description
The description
tag defines a descriptive text for the field, and should be enclosed by the field
tags. The value is currently not used.
Syntax:
<description>The source directory</description>
type
Types are described using a small language which represents the different types. The type
tags should be enclosed by the field
tags.
The following types are supported:
primitive-type
object-type
enum-type
password-type
drstorable-type
drdate-typeÂ
Syntax:
<type>specific type</type>
Example - Primitive int type
Example - Type indicating a List of String objects
<type> <list-of> <object-type name='java.lang.String'/> </list-of> </type>