5.6 Configuring the Server Component

All properties within KineticFusion are managed by a single configuration manager, implementing the interface com.kinesis.configuration.api.ConfigurationManagerType. The single instance can be obtained from the KineticFusionServerFactory:

The ConfigurationManagerType instance is responsible for providing instances of property objects to users for reading and manipulating property values. There are two type of properties served by the configuration manager: general configuration properties and ActionScript warning level properties. The ConfigurationManagerType interfaces provides the following methods:

public URL[] getConfigurationURLs()

Returns an array of the URLs of documents used in populating the configuration Session Values

public PropertyType getConfigurationProperty( String propertyName)

Returns an object for reading and manipulating a single property value

public WarningMessageType getWarningLevel( int messageID)

Returns an object for reading and manipulating a single ActionScript warning level

public void updateGlobalProperties( Map nameValueMap)

Updates global properties en-masse from a map

public void updateThreadProperties( Map nameValueMap)

Update thread-local properties en-masse from a map

General configuration properties all implement a sub-type of the com.kinesis.configuration.types.PropertyType interface. An instance of the property is provided by the getConfigurationProperty( ) method:

    /**
     * Get the current property object for the specified property name. 
     * 
     * @param propertyName The full name of the property option
     * @throws IllegalPropertyNameException
     *                      If the specified property is not supported
     */
    public PropertyType getConfigurationProperty( String propertyName)  throws IllegalPropertyNameException;
    

For example, to read the property 'kinesis.actionscript.optimizeFunctions':

String name = "kinesis.actionscript.optimizeFunctions";
PropertyType property = myConfigMgr.getConfigurationProperty( name );

The PropertyType interface is the base interface for all the general configuration value types. It provides methods for reading and writing property values. The following methods are provided:

public int getPropertyType()

Get the type constant for the property.

public String getPropertyName()

Get the full property name as used in the configuration files.

public Object getSessionValueObject()

Get the Sesssion Value of the property - this is the value defined by the external configuration files and command line arguments. The actual type of the Object is determined by the Property class as described below.

public Object getGlobalValueObject()

Get the Global Value of the property - this is the value set using setGlobalValueObject. If the Global Value has not been set, the Session Value is returned. The actual type of the Object is determined by the Property class as described below.

public Object getThreadValueObject()

Get the Thread Value of the property - this is the value set using setThreadValueObject. If the Thread Value has not been set, the Global Value is returned. The actual type of the Object is determined by the Property class as described below.

public boolean canUpdateGlobal()

Returns true if the use can change the global value of this property.

public boolean setGlobalValueObject( Object value) throws ChangeUnsupportedException

Set the global value of the propertyl. The value can be a String or an object appropriate to the type of the property as described below.

public boolean canUpdateThread()

Returns true if the use can change the thread-local value of this property. Some properties can only be set for the entire component and cannot be overridden for a single thread.

public boolean setThreadValueObject( Object value) throws ChangeUnsupportedException

Set the thread-local value of the property. The value can be a String or an object appropriate to the type of the property as described below.

public void addValueChangeListener(ConfigurationEventListenerType listener)

Add a change listener to the property

public void removeValueChangeListener(ConfigurationEventListenerType listener)

Remove a change listener from the property

There are currently six property types supported by the configuration manager. Constants for each type are defined in the PropertyType interface as follows:

public final int I_BOOLEAN = 1;
public final int I_FILE = 2;
public final int I_INTEGER = 3;
public final int I_LOCALE = 4;
public final int I_PATH = 5;
public final int I_STRING = 6;

The following table lists each type, the interface that implements the type and the object type of the property:

As illustrated in the table, each type is also implemented by a corresponding sub-type so that values can be access natively if necessary. These are described in a later section.

Each property value can have three different values: the Session Value, created from external configuration files and command-line parameters, The Global Value, that can override the Session Value for all threads, and the Thread Value which is the value of the property for the current thread. Accessors for these values are available in the PropertyType interface and represented by the following methods:

    /**
     * Get the default value for this property
     * @return The default value for this property
     */
    public Object getSessionValueObject();
    
    /**
     * Get the overall global value that is defined for this property
     * @return The overall global value that is defined for this property
     */
    public Object getGlobalValueObject();
    
    /**
     * Get the value that is currently valid for this property in the current thread
     * @return The value that is currently valid for this property in the current thread
     */
    public Object getThreadValueObject();

The getSessionValueObject() will always return the externally configured value for the property. The getGlobalValueObject() will return the Global Value if one has been defined, otherwise it will return the Session Value. The getThreadValueObject() method will return the thread-specific value if one exists otherwise it will return the same value as that from getGlobalValueObject().

The KineticFusion application always uses the getThreadValueObject() to retrieve the value for any configuration option. If thread-specific values are not required by the user application the it is sufficient to set the global value for the option as this will be automatically returned by the property to the application.

The Session Value of a configuration option is read-only. It is the value of the property only as determined by the external configuration files and command-line arguments. Consequently, only the Global Value and the Thread Value can be updated using the API.

Not all properties can be set within the API - the PropertyType interface defines two methods for checking whether updates to a value are permitted:

    /**
     * Can the global value of the property be updated programmatically
     * @return true if the global value of the property can be updated programmatically
     */
    public boolean canUpdateGlobal();
    
    /**
     * Can the thread-local value of the property be updated programmatically
     * @return true if the thread-local value of the property can be updated programmatically
     */
    public boolean canUpdateThread();

These methods indicate to the user whether a PropertyType instance can be modified or not and directly correspond to the two mutator methods for the property value:

   /**
     * Set the global value of the property from the input argument. The argument must be appropriate for
     * the type of the property.
     * @param value
     * @return true if the update was successful
     */
    public boolean setGlobalValueObject( Object value) throws ChangeUnsupportedException;
    
    
    /**
     * Set the thread-local value of the property from the input argument. The argument must be appropriate for
     * the type of the property.
     * @param value
     * @return true if the update was successful
     */
   public boolean setThreadValueObject( Object value)throws ChangeUnsupportedException;

If the property does not support updating then a method will throw a com.kinesis.configuration.types.ChangeUnsupportedException. The value used to update the value of a property using these methods depends on the type of the property. The following table indicates the acceptable arguments:

Changes occurring in the values or properties can be monitored by adding a com.kinesis.ConfigurationEventListenerType listener to a property. This will be notified of all changes to the Session Value, Global Value and all Thread Values of a property. The PropertyType interface provides two methods to register and unregister a change listener:

  /**
    * Add a listener to receive events when the configuration value has been changed.
    * @param listener
    */
   public void addValueChangeListener(ConfigurationEventListenerType listener);

   /**
    * Remove an event-change listener
    * @param listener
    */
   public void removeValueChangeListener(ConfigurationEventListenerType listener) ;

It is up to the listener object to determine whether any 'visible' value has changed.

Each supported value type of a PropertyType is implemented by a type-specific sub-class to which PropertyType instances can be downcast in order to provide native accessor and mutator methods. These classes all provide the same five methods but with different argument types or return values :

public <Type> getSessionValue()

Return the Session Value of the property. For BooleanType and IntegerType sub-classes, the return <Type> is the primitive boolean/integer type.

public <Type> getGlobalValue()

Return the Global Value of the property. For BooleanType and IntegerType sub-classes, the return <Type> is the primitive boolean/integer type.

public <Type> getThreadValue()

Return the Thread-specific value of the property. For BooleanType and IntegerType sub-classes, the return <Type> is the primitive boolean/integer type.

public void setGlobalValue(<Type> value)

Set the Global Value of the property. For BooleanType and IntegerType sub-classes, the value argument is the primitive boolean/integer type.

public void setThreadValue(<Type> value)

Set the Thread-specific value of the property. For BooleanType and IntegerType sub-classes, the value argument is the primitive boolean/integer type.

When it is required to updated multiple property values at once, the ConfigurationManagerType class provides two methods that will update the Global or Thread Values of multiple properties from String values. The two methods are:

    /**
     * Set the global value of each of the properties stored as keys in the
     * input map to their corresponding string values.
     * 
     * @param nameValueMap
     *                      A map containing a mapping of string property names and their
     *                      corresponding new property values stored as strings. If a
     *                      specified value is not a string, a log message is posted and
     *                      the map entry is ignored.
     * @throws IllegalPropertyNameException
     *                      if any of the property names are invalid
     * @throws LocalChangeUnsupportedException
     *                      if the specified property name is not a string or if the
     *                      property is not modifable
     */
    public void updateGlobalProperties( Map nameValueMap) 
                    throws IllegalPropertyNameException, ChangeUnsupportedException;
    

    /**
     * Set the thread-local value of each of the properties stored as keys in
     * the input map to their corresponding string values.
     * 
     * @param nameValueMap
     *                      A map containing a mapping of string property names and their
     *                      corresponding new property values stored as strings. If a
     *                      specified value is not a string, a log message is posted and
     *                      the map entry is ignored.
     * @throws IllegalPropertyNameException
     *                      if any of the property names are invalid
     * @throws LocalChangeUnsupportedException
     *                      if the specified property name is not a string or if the
     *                      property is not locally modifable
     */
   public void updateThreadProperties( Map nameValueMap)
               throws IllegalPropertyNameException, ChangeUnsupportedException;

The nameValueMap argument for both methods is a Map of property name to the new String value of the property being defined. So, for example, to read all the properties from a file and set them for a particular thread:

    try{
        myConfigProperties = new Properties();
        myConfigProperties.load( new FileInputStream( configFile));
		
        ConfigurationManagerType myConfigMgr = KineticFusionServerFactory.getInstance().getConfigurationManager();	
        myConfigMgr.updateThreadProperties( myConfigProperties );
    } catch( IOException e)
    {
        // Process IO Error
    }	

The priority levels or ActionScript messages can be retrieved and set using the getWarningLevel() method in the ConfigurationManagerType:

	   /**
     * Get the WarningLevelType associated with the specified message ID 
     * @param messageID
     * @return The  object allowing the user to read and write the message levels or null 
     * if the specified error ID is not supported
     */
    public WarningMessageType getWarningLevel( int messageID);

The WarningMessageType provides methods for reading the priority level of a message and setting the priority level. For WarningMessageType properties, there are only two types of configuration value: Session Value and Thread Value. Unlike configuration values, the Session Value is writable by users, however any value set throught the API can be overridden.

The WarningMessageType procides the following methods:

public int getThreadValue()

Return the Thread Value priority for this message

public int getSessionValue()

Return the Session Value priority for this message

public boolean canUpdate()

Can the priority value be updated? Fatal messages cannot have their error levels modified.

public void setThreadValue(int priorityLevel) throws ChangeUnsupportedException

Set the Thread Value priority for this message. If canUpdate() is false, this will throw an exception

public void setSessionValue(int priorityLevel) throws ChangeUnsupportedException

Set the Session Value priority for this message. If canUpdate() is false, this will throw an exception

public int getMessageID()

Get the message ID for this warning level

The priority level constants are defined in the interface com.kinesis.log.MessagePriorityType:

	static public final int I_IGNORE_PRIORITY = 2;
	static public final int I_WARN_PRIORITY = 4;
	static public final int I_ERROR_PRIORITY = 5;

Copyright 2003-2005 Kinesis Software. All rights reserved.