Package jade.util

This package contains utility classes and in particular: classes for handling properties and the leap subpackage that is a replacement for the Java collection framework that is not supported by J2ME.

See:
Description

Class Summary

BasicProperties	Provides the foundation class for property management.
EnhancedProperties	Provides a concrete implementation of ImportableProperties useable in the J2SE (desktop) world.
Event	This class represents a generic event carrying some information (accessible in the form of Object parameters) and provides support for synchronous processing through the waitUntilProcessed() and notifyProcessed() methods.
ExpandedProperties	Extends EnhancedProperties and adds support for fetching system environment variables (those usable from the OS shell).
ImportableProperties	This class serves as a basis for supporting the ability to import properties from files.
InputQueue	This class implements a FIFO queue of objects that can be put and got in a synchronized way.
Logger	This class provides a uniform way to produce logging printouts in a device dependent way.

Exception Summary

PropertiesException	Property related exception.
WrapperException	This class acts as a base class for all the exceptions that wrap another (nested) exception.

Package jade.util Description

This package contains utility classes and in particular: classes for handling properties and the leap subpackage that is a replacement for the Java collection framework that is not supported by J2ME.

These property classes provide a convenient method to easily provide an agent with configuration data. For example, the following would be usable in any agent running in an environment supporting ExpandedProperties:

     // Add and initialize the following in your agent.
     protected myProperties = new ExpandedProperties();

     // Called by JADE with any arguments given to the agent from the command line.
     public void setArguments(String[] args) {
         myProperties.parseArgs(args);
         // myPropeties may now be used throughout your agent code.
         // See the class BasicProperties for all its easy to use getters.
     }

Properties are of the form: key=value or key:value. The special property import:foo.properties causes the property file foo.properties to be read. The ".properties" suffix is simply a common convention and is not required or enforced by these classes. One property file may import from others. Circular imports are checked for and if detected will throw a PropertiesException (extension of RuntimeException). Here is an example of a properties file:

     # Specifies one or more user IDs to notify.
     # Separate each with a space.
     jabber.notify=smith
     # The Jabber server.
     jabber.server=theserver.hpl.hp.com

     SimpleCalendar.input=${AGENT_HOME}/config/simplecalendar.properties
     weather.state=CA
     weather.city=MOFFETT ARPT
     weather.zonecode=CAZ006

Property files may contain as many pairs as necessary. Blank lines as well as lines beginning with '#' or '!' are ignored. A line ending with '\' is interpreted as continued to the next line. Within a collection of continued lines, any beginning with '#' or '!' are ignored making it easy to comment out particular ones.

To fetch the value associated with a key, use the format ${xxx}. An all uppercase key, such as ${AGENT_HOME} in the above example will cause the environment space (full not just those in the JVM's System properties) to be checked if the key doesn't exist in the properties collection.

A property may be set such that it can't be altered by ending the key value with a '!'. For example:

     agentClass!=com.hp.agent.Foo

One still references this property as ${agentClass}. This is particularly handy when you want to make a property collection available but prevent the changing of particular values. We have used this in conjunction with loading a property collection from the same jar file as a particul class. This is demonstrated below:

    String defaultPropName = "com/hp/agent/smartagent/setup.properties";
    properties = new ExpandedProperties();
    InputStream propertyStream = this.getClass().getClassLoader().getResourceAsStream(defaultPropName);
    if (propertyStream != null) {
        try {
            properties.load(propertyStream);
        } catch (IOException ioe) {
            throw new PropertiesException("Error reading:" + defaultPropName);
        }
    }

Consult each classes documentation for further information but they relate as follows:

1. BasicProperties - This class provides the foundation class. It is designed to be usable in the restrictive J2ME CLDC environment. It provides enhanced property management as well as providing support for values containing strings of the form ${xxx}. To increases the portability of your property files, it provides useful default handling for common cases. For example, when the value of a property whose key name has the string "path" as part of it (ex: "classpath", "sourcepath", "mypath") is fetched any occurance of '|' will be converted to the value from System.getProperty("path.separator").
2. ImportableProperties - This abstract class extends BasicProperties and serves as a basis for supporting the ability to import properties from files. Those files may also contain further import directives. It is also usable in the restrictive J2ME CLDC environment. Since file support will be handled differently in different environments, it contains one abstract method fileReader which given the name of a file (its URL) must return a Reader object. Extending classes will provide that method in a suitable fashion. For example, in the desktop world this would be:

        return new InputStreamReader(new FileInputStream(aFileName));
   

   whereas in the CLDC environment it would be:

    
        return new InputStreamReader(Connector.openInputStream(aFileName));
   

3. EnhancedProperties - Provides a concrete implementation of ImportableProperties useable in the J2SE (desktop) world.
4. ExpandedProperties - Extends EnhancedProperties and adds support for fetching system environment variables (those usable from the OS shell). This class would need to be carefully considered in different environments. When a key is all uppercase we first attempt to fetch its value from the property collection and if not found there then from the systems environment space. With this class you may fetch all environment variables, not just those the JVM puts into its System properties collection.
5. PropertiesException - Extends RuntimeException and is thrown under various error conditions by these classes.