Chapter 7   Utility APIs


The iPlanet Directory Server Access Management Edition (DSAME) provides utility application programming interfaces (APIs) that can be used by applications. This chapter explains these APIs. It contains the following sections:

• Overview

• API Summary

Overview

---

The utilities package is called com.iplanet.am.util. It contains utility programs that can be used by applications accessing DSAME. The APIs include:

• StatsListener

• AdminUtils

• AMClientDetector

• Debug

• Locale

• Stats

• SystemProperties

• ThreadPool

API Summary

---

Following is a summary of the utility APIs and their functions.

StatsListener

The StatsListener interface must be implemented by each module in order to print the statistics. This interface invokes the printStats() method.

AdminUtils

This class contains the methods used to retrieve TopLevelAdmin information. The information comes from the server configuration file (serverconfig.xml).

AMClientDetector

This is a utility that gets the client type. It executes the Client Detection Class (provided in Client Detection service) to get the client type. The default client type will be returned if there is no Client Detection Implementation provided.

Debug

Debug allows an interface to file debug and exception information in a uniform format. It supports different levels of filing debug information (in the ascending order): OFF, ERROR, WARNING, MESSAGE and ON. A given debug level is enabled if it is set to at least that level. For example, if the debug state is ERROR, only errors will be filed. If the debug state is WARNING, only errors and warnings will be filed. If the debug state is MESSAGE, everything will be filed. MESSAGE and ON are the same level except MESSAGE writes to a file, whereas ON writes to System.out.

---

Note

Debugging is an intensive operation and may hurt performance when abused. Java evaluates the arguments to message() and warning() even when debugging is turned off. It is recommended that the debug state be checked before invoking any message() or warning() methods to avoid unnecessary argument evaluation and to maximize application performance.

---

Locale

This class Locale.java is a utility that provides the functionality for applications and services to internationalize their messages.

Stats

This class writes statistics information in a uniform format. It supports different states of filing information:

• OFF statistics is turned off.

• FILE statistics information is written to a file.

• CONSOLE statistics information is written to the console.

The Stats service uses the property file, AMConfig.properties, to set the default stats level and the output directory where the stats files will be placed. The properties file is located (using ResourceBundle semantics) from one of the directories in the CLASSPATH.

SystemProperties

This class provides functionality that allows single-point-of-access to all related system properties. First, the class tries to find AMConfig.class, and then a file, AMConfig.properties, in the CLASSPATH accessible to this code. The class takes precedence over the flat file. If multiple servers are running, each may have their own configuration file. The naming convention for such scenarios is AMConfig_serverName.

ThreadPool

ThreadPool is a generic thread pool that manages and recycles threads instead of creating them when a task needs to be run on a different thread. Thread pooling saves the virtual machine the work of creating brand new threads for every short-lived task. In addition, it minimizes the overhead associated with getting a thread started and cleaning it up after it dies. By creating a pool of threads, a single thread from the pool can be reused any number of times for different tasks. This reduces response time because a thread is already constructed and started and is simply waiting for its next task.

Another characteristic of this thread pool is that it is fixed in size at the time of construction. All the threads are started, and then each goes into a wait state until a task is assigned to it. If all the threads in the pool are currently assigned a task, the pool is empty and new requests (tasks) will have to wait before being scheduled to run. This is a way to put an upper bound on the amount of resources any pool can use up. In the future, this class may be enhanced to provide support growing the size of the pool at runtime to facilitate dynamic tuning.