Developing Custom Audit Publishers

This section documents how to create a new custom audit publisher in Java.

The Console, File, and JDBC custom publishers that are provided with Identity Manager implement the AuditLogPublisher interface. The source code of these publishers can be found in the REF kit. The documentation of the interfaces is also available in the REF kit, in Javadoc format. (Refer to the Javadoc for interface details.)

The REF (Resource Extension Facility) kit is provided in the /REF directory on your product CD or with your install image.

Developers are encouraged to extend the AbstractAuditLogPublisher class. This class parses the configuration and ensures that all required options have been provided to the publisher. (See the example publishers in the REF kit.)

Publishers must have a no-arg constructor.

Publisher Lifecycle

The following steps describe the lifecycle of a publisher:

1. The Object is instantiated.

2. The Formatter (if any) is set using the setFormatter() method.

3. Options are provided using the configure(Map) method.

4. Events are published using the publish(Map, LoggingErrorHandler) method.

5. Publisher is terminated using the shutdown() method.

Steps 1-3 are executed when Identity Manager starts up and whenever the audit configuration is updated. Step 4 will not occur if no audit event is generated before shutdown is called.

The configure(Map) is only called once on the same publisher object. (A publisher does not have to prepare for on-the-fly configuration changes). After the audit configuration is updated, the current publishers are first shut down and new publishers are created.

The configure() method in Step 3 may throw a WavesetException. In this case, the publisher will be ignored and no other calls will be made to the publisher.

Publisher Configuration

Publishers can have zero or more options. The getConfigurationOptions() method returns the list of options the publisher supports. The options are encapsulated using the PublisherOption class (see Javadoc for details of this class). The audit configuration viewer invokes this method when it builds the configuration interface for the publisher.

Identity Manager configures the publisher using the configure(Map) method at server startup and after audit configuration changes.

Developing Formatters

The REF kit includes the source code for the following formatters:

• XmlFormatter. Formats audit events as XML strings.

• UlfFormatter. Formats audit events according to the Universal Logging Format (ULF). The Sun Application Server uses this format.

Formatters must implement the AuditRecordFormatter interface. In addition, formatters must have a no-arg constructor. Refer to the Javadoc included in the REF kit for details.

Registering Publishers/Formatters

The audit attribute of #ID#Configuration:SystemConfiguration object lists all the registered publishers and formatters. Only these publishers and formatters are available in the audit configuration user interface.