Previous     Contents     Index     Next     
iPlanet Portal Server Reference Guide



Chapter 4   Log API




Log API Overview

This chapter provides an overview of Log Application Programming Interface (API) which can be used by the iPlanet Portal Server applications to perform logging activities.

The Log API provides log management tools for the iPlanet Portal Server applications, and provides a set of Java classes so that the applications can create, retrieve, submit, or delete log information.

Some of the information that can be tracked and recorded by the Log API include:

  • User identification and actions taken

  • System usage, access time, and failures

Additionally, the Log API provides an XML DTD to define the format for data streams to provide to the server logging process and to define the format for data streams coming from the server logging process. These formats are required to access logging functions from non-Java client software, but can be transparently integrated into Java applications, as shown in the sample code in this chapter.

The logging server process resides on the same network as the iPlanet Portal Server application server and gateway. The log file format is ASCII text, so administrators may use any utilities available to them for viewing ASCII text files.


Note The details of the Log API's methods are in the Log API Javadocs, available from the server at http://yourserver:port/docs/en_US/javadocs




Implementing the Log API


As with the other APIs, implementing a client application in Java is substantially less complex than implementing in any other language. By referencing existing iPlanet Portal Server classes to create, write to, read from, or otherwise manipulate logs, masks much of the communication and protocol manipulation.

The Log API provides:

Log Manager

A set of Java classes to an application so that the application can create or delete a log, submit or retrieve log information, query a log, and retrieve a list of available logs.

Log Record

A Java class to allow an application to fill in a single log request information from the application so that the application can submit such single log request information to a log file.


iPlanet Portal Server Classes

At a minimum, the Java client application should import the logging and session classes, as shown here.

Code Example 4-1 Importing iPlanet Portal Server Classes
import java.io.*;
import java.util.*;
import java.net.*;
import com.iplanet.portalserver.session.*;

While directly access the classes as needed, importing the logging and session classes will allow better use of the Logging functions.

The sections below briefly describe some of the functionality available, but reference the Javadocs online at:

http://yourserver:port/docs/en_US/javadocs



Log API Functionality

The Log API offers the following capabilities to applications:


Creating Logs

Applications can create a log file by invoking the LogManager constructor and passing the requested log file name value to the create method.

Code Example 4-2 Create a New Log (Minimal Code)
LogManager logMgr = new LogManager(session);
try {
logMgr.create("logname");
} catch (LogException e) {
System.out.println("Log Creation fails: " + e);
}

Create throws an exception if:

  • The filename is invalid

  • The file already exists

  • The application does not have permission to create files


Deleting Logs

Applications can delete a log by constructing an object of type LogManager and passing the log file name to the object's delete method.

Code Example 4-3 Delete a Log (Minimal Code)
LogManager logMgr = new LogManager(session);
try {
logMgr.delete("logname");
} catch (LogException e) {
System.out.println("Log Deletion fails: " + e);
}

Delete throws an exception if:

  • The log does not exist

  • The filename is invalid

  • The application does not have permission to delete files


Writing to a Log

Applications submit key-value pairs to log records, to a log. First, the application must create a log record, then write to the log, and catch exceptions as required.

Code Example 4-4 Writing Records to a Log (Minimal Code)
LogManager logMgr = new LogManager(session);
LogRecord logrec = new LogRecord(key, value);
try {
logMgr.write("logname", logrec);
} catch (LogException e) {
System.out.println("Log info writing fails: " + e);
}

LogException is thrown if:

  • Failure of a log record submission

  • Privilege denied

  • Target log does not exist

  • Target log is inactive

  • Invalid session

  • Fatal system error


Reading from a Log

Applications retrieve information from a log and may selectively retrieve information with a query. See Querying Logs.

Code Example 4-5 Reading Records from a Log (Minimal Code)
LogManager logMgr = new LogManager(session);

Vector loginfo = new Vector();
try {
loginfo = logMgr.read("logname");
} catch (LogException e) {
System.out.println("Log Info Retrieval fails: " + e);
}

A LogException is thrown if an error occurs as follows:

  • Invalid session is encountered

  • The reading privilege is denied

  • The target log does not exist

  • Other fatal system errors are encountered


Log List Retrieval

Applications can get a list of all log names in the system.

Code Example 4-6 Retrieve Existing Log List (Minimal Code)
LogMgr logMgr = new LogManager(session);
Vector llist = new Vector();
try {
llist = logMgr.list();
} catch (LogException e) {
//System.out.println("Log List Retrieval fails: " + e);
}

A LogException is thrown if an error occurs for the following reasons:

  • Invalid session is encountered

  • The listing privilege is denied

  • The log list does not exist

  • Other fatal system errors are encountered


Querying Logs

To retrieve log records from a log with a query, the log should include such information as:

  • A valid and existing log name.

  • A query string.

    Code Example 4-7 Query Log Information (Minimal Code)
    LogManager logMgr = new LogManager(session);

    vector list = new vector()
    try {
    vector loginfo = logMgr.read("logname", "domain = iplanet.com");
    }
    catch (LogException e) {
    System.out.println("Log Info Retrieval fails: " + e);
    }

This queries the specified log with the boolean query provided. For example, query for "domain = sun.com".

A LogException is thrown if it an error occurs as follows:

  • Invalid session is encountered

  • The reading privilege is denied

  • The target log does not exist

  • Or other fatal system errors are encountered


Sample Code

The following sample code illustrates a basic implementation of logging functionality.

Code Example 4-8 Sample Log API 
LogManager lm = new LogManager(session);

//create a log
try {
lm.create("xyz");
} catch (LogException e) {
System.out.println("e");
}

//submit log information
try {
for (int i=0; i<10; i++) {
LogRecord lr = new LogRecord("typehello", "msghello");
lm.write(lr, "xyz");
}
} catch (LogException e) {
System.out.println("e");
}

//retrieve log information
try {
Vector r = new Vector();
r = lm.read("xyz");
for (int i=0; i<r.size(); i++) {
System.out.println(r.elementAt(i));
}
} catch (LogException e) {
System.out.println("e");
}

//delete a log
try {
lm.delete("xyz");
}
catch (LogException e) {
System.out.println("e");
}

//query log information
try {
loginfo = logMgr.read("xyz", "domain = iplanet.com");
}
catch (LogException e) {
System.out.println("e");
}

//obtain a list of log names in the system
try {
Vector ll = new Vector();
ll = lm.list();
for (int i = 0; i < ll.size(); i++) {
System.out.println( ll.elementAt(i) );
}
catch (LogException e) {
System.out.println("e");
}


Previous     Contents     Index     Next     
Copyright © 2000 Sun Microsystems, Inc. Some preexisting portions Copyright © 2000 Netscape Communications Corp. All rights reserved.

Last Updated May 04, 2000