Defining configuration objects

Defining configuration objects
Prev	Chapter 9. Configuration	Next

An TIBCO ActiveSpaces® Transactions configuration object is defined as a Java class that extends a known base type. A configuration notifier is also defined using inheritance.

Table 9.1. Configuration object definitions

Identification Mechanism	Description
`extends com.kabira.platform.kcs.Configuration`	A configuration object.
`extends com.kabira.platform.switchconfig.ConfigurationListener`	A configuration notifier.

Configuration objects and notifiers are managed objects - they can only be manipulated in a transaction. See Chapter 5, Managed objects for more details on Managed Objects.

Here is an example of a configuration object.

Example 9.1. Configuration object

//     $Revision: 1.1.2.1 $
package com.kabira.snippets.configuring;

import com.kabira.platform.kcs.Configuration;
import com.kabira.platform.annotation.Key;
import com.kabira.platform.annotation.KeyField;
import java.util.Date;

enum Gender
{
    MALE,
    FEMALE
}

/**
 * User configuration
 *
 * A key was added to allow the configuration data to be accessed
 * by last name. Notice that the versionId field also is in the
 * key.  This is required since there may be multiple versions
 * of this configuration data loaded, both with the same last name.
 */
@Key(name = "ByLastName",
fields =
{
    "lastName", "versionId"
},
unique = true,
ordered = false)
public class User extends Configuration
{

    User(
        @KeyField(fieldName = "lastName")
        final String lastName,
        @KeyField(fieldName = "versionId")
        final String version)
    {
        this.versionId = version;
        this.lastName = lastName;
    }
    String firstName;
    final String lastName;
    Long age;
    Gender gender;
    Date joined;

    //
    //  Phone number is an optional field
    //
    String phoneNumber = "Not provided";
}

See Example 9.9, “Configuration notifier” for an example of a configuration notifier.

Configuration type

By default the configuration type of a configuration object is the Java package name. All configuration objects defined in the same package will have the same configuration type For example, the configuration type of the configuration object defined in Example 9.1, “Configuration object” is com.kabira.snippets.configuring.

The default configuration type can be changed by overriding the getType() method. This method returns a string that is used for the configuration type.


	For historical reasons the configuration type is called `GroupKind` in some parts of the configuration API. The documentation will always use type to describe this concept.

Example 9.2. Overriding default configuration type

//     $Revision: 1.1.2.1 $
package com.kabira.snippets.configuring;

import com.kabira.platform.kcs.Configuration;

/**
 * A configuration object that overrides the default configuration type.
 *
 * This configuration object has a configuration type of MyConfigurationType
 */
public class TypeOverride extends Configuration
{
    @Override
    public String getType()
    {
        return "MyConfigurationType";
    }
    public String   value;
}

Optional fields

By default all fields specified in a configuration class are required in the configuration file. Adding a field initializer in a configuration object definition makes that field optional in the configuration file. If the field is not set in the configuration value, the configuration object will have the initializer value specified in the class definition. The User.phoneNumber field is optional in the User configuration object in Example 9.1, “Configuration object”.

Supported field and array types

The supported types for fields and array elements in configuration objects are:

boolean and Boolean
byte and Byte
long and Long
java.lang.String
java.util.Date
Enumerations
Managed Objects (including other configuration objects)
Arrays containing one of the supported types.

Managed Objects and Array nesting is supported. See Example 9.3, “Nested configuration definition” for an example of defining nested configuration. See Example 9.4, “Nested configuration file” for an example of how nested configuration data is specified in a configuration file.

An exception is thrown during configuration load if the configuration data contains unsupported types.

Fields in a configuration object can be either public, package private, or private.

Keys are supported, but not required, on configuration objects. See the section called “Keys and Queries” for details on defining keys.


	Configuration classes must be resolved by the JVM before configuration data can be loaded. See Example 9.7, “Locating configuration objects” for details on one way to ensure that a configuration class has been resolved by the JVM. If the configuration class has not been resolved, the configuration will fail to load with an unresolved class error.

Example 9.3. Nested configuration definition

//     $Revision: 1.1.2.1 $
package com.kabira.snippets.configuring;

import com.kabira.platform.annotation.Managed;
import com.kabira.platform.kcs.Configuration;

@Managed
class Player
{
    String name;
    String position;
}

/**
 */
public class Team extends Configuration
{
    /**
     * Team name
     */
     String   name;

    /**
     * Team players
     */
     Player [] players;
}

Example 9.4. Nested configuration file

//     $Revision: 1.1.2.1 $
configuration "team" version "1.0" type "com.kabira.snippets.configuring"
{
        configure com.kabira.snippets.configuring
        {
                Team
                {
                        name = "giants";
                        players =
                        {
                            {
                                name = "Tim Lincecum";
                                position = "Pitcher";
                            },
                            {
                                name = "Matt Cain";
                                position = "Pitcher";
                            },
                            {
                                name = "Buster Posey";
                                position = "Catcher";
                            }
			};
                  };
        };
};

Data Format

A Date value in a configuration file must be a string using a format of Y-M-D T where:

Y is the year, including a century, expressed as a decimal number, e.g. 2011.
M is the month expressed as a decimal number from 01 to 12, e.g. 12 for December.
D is the day of the month expressed as a decimal number from 01 to 31, e.g. 04.
T is the time expressed as H:M:S where H is a decimal number between representing a 24 hour clock from 00 to 23, M is the minute expressed as a decimal number from 00 to 59, and S is the second expressed as a decimal number from 00-60, e.g. 11:05:23.

Configuration object life cycle

The creation and deletion of all configuration objects is done by the TIBCO ActiveSpaces® Transactions configuration framework. Any nested Managed Objects contained in a configuration object are also created and deleted by the configuration framework. They must not be deleted by the application.

Restrictions

Configuration objects have the following restrictions:

all fields must be a supported Java type.
all arrays must contain only supported Java types.
nested Managed Objects cannot contain fields named groupId or versionId. This is because the configuration loader automatically populates these fields with the current configuration name (groupId) and version (versionId) when the data is loaded. These fields are removed from the configuration data when it is exported using the configuration exporter. If these fields are defined in nested Managed Objects, round-tripping of the configuration data will not work.