com.adventnet.afp.log
Interface Logger

All Known Implementing Classes:

AbstractLogger

public interface Logger

The Logger interface available in the Logging Framework, decides which messages are to be logged based on the LogLevel specified. It provides various convenient methods for the Logging mechanism. It passes the output and error messages to the LogWriter in accordance with the specified LogLevel.

Through the methods available in Logger, the Logger Properties such as LogLevel, DisplayName and Class Name can be modified at runtime.

Writing Your Own Logger

Reference Implementation

The following code snippet explains how implementation can be given for writing your own logger. Keeping this as reference, you may give your own implementation. Detailed explanation has been provided alongside the code snippet itself for ease of reference.

package test;
import java.util.*;
import java.text.*;
import com.adventnet.afp.log.LogWriter;
import com.adventnet.afp.log.LoggerProperties;
import com.adventnet.afp.log.AbstractLogger;

// An example implementation class of the Logger interface explaining how you can have your own custom properties and handle them in accordance with your needs.

public class ExampleLogger extends AbstractLogger

{
// The default properties needed for a logger.
// The name by which the logger will be identified.
private String instanceName = null;

// The default logging level of the logger.
private int logLevel = 2;

// The Writer used by the Logger.
private LogWriter writer = null;

// Some custom properties for a Logger (specified in the logging.xml file).
// A custom property specifying whether the message will have timestamp.
private boolean needTimeStamp = false;

// Initializing the various parameters of the Logger. All default parameters and the custom properties will be set by this method. The respective Writer is mentioned for every Logger properties.
public void init(LoggerProperties loggerProps, LogWriter writer)
{
this.instanceName = loggerProps.getInstanceName(); // Setting the instanceName
of the Logger.

// Setting the LogLevel.
this.logLevel = loggerProps.getLogLevel();

// Setting the writer.
this.writer = writer;

// Setting the custom properties
Boolean tempVal;

// To get the custom property(needTimeStamp). If it is true, the message will have a timestamp.
tempVal = new Boolean((String) loggerProps.getCustomProperty("needTimeStamp"));
if(tempVal!= null)
{
this.needTimeStamp = tempVal.booleanValue();

}

}

// To get the instanceName of the Logger.
public String getLoggerInstanceName()
{
return instanceName;
}

// Method to write the output message. The message will be logged only if its level is less than or equal to the level of the Logger. The message will have TimeStamp prepended if needTimeStamp is true.
// To direct the message to the writer
public void out(String message, int level)

{
if (level > logLevel)
{
return;
}
writer.out(formatMessage(message, level));
}

// Method to log an error message. The message will be logged only if its level is less than or equal to the level of the Logger. The message will have TimeStamp prepended if needTimeStamp is true. Since there is no exception trace, it is forwarded to err(string,exception,level) with exception as null.

public void err(String message, int level)

{
err(message, null, level);
}

// To log an error message. The message will be logged only if its level is less than or equal to the level of the Logger. The message will have TimeStamp prepended if needTimeStamp is true.
// The exception trace will have no formatting.
public void err(String message, Throwable excep, int level)
{
if (level > logLevel)
{
return;
}
writer.err(formatMessage(message, level), excep);

}

// To set the LogLevel.

public void setLoggingLevel(int level)

{

this.logLevel = level;

}

// To get the LogLevel.
public int getLoggingLevel()
{
return logLevel;
}

// To format the messages in the required format.

// Here, the custom property needTimeStamp is used, based on which formatting is done.

public String formatMessage(String message, int level)

{

StringBuffer str = new StringBuffer();

// If time stamp is needed, it can be added to the message.

if (needTimeStamp)

{

SimpleDateFormat dateFormat = new SimpleDateFormat("EEE, MMM d, yyyy hh:mm aaa");

str.append(dateFormat.format(new Date()));
str.append(": ");
}

// To append the InstanceName in any format. (In Lowercase in this example).
str.append(instanceName.toLowerCase());
str.append(": ");

// Finally, append the string and return it.
str.append(message);
return str.toString();
}
}

Integrating Your Logger

The above code snippet explained you how to create your own Logger. You need to follow the steps given below for integrating it with the Logging Mechanism. You can add the Loggers either in the configuration details or at Runtime programmatically.

Adding in Configuration details

Step 1

Write a class implementing the AbstractLogger. You can give your own implementation for the methods available in the interface. You may add new methods, if need be.

Step 2

Add a new Logger in the source from where LogConfigReader would read the configuration details. In this framework, by default, the LogConfigReader reads the details from a file. The tags which you find below, can be added to the logging.xml, (as Logger), if you wish to use the default setup. This Logger's InstanceName is given as "SERVEROUT". It will be associated to the Writer which has the same InstanceName (i.e) SERVEROUT.

<LOGGER>
<ClassName>test.ExampleLogger</ClassName>
<InstanceName>TestLogger</InstanceName>
<WriterInstanceName>SERVEROUT</WriterInstanceName>
<LogLevel>3</LogLevel>
<Properties>
<Property>
<Key>----</Key> //Specify the Custom property key
<Value>---</Value> // property value
</Property> .
//Enter all the custom properties here.
</Properties>
</LOGGER>

Step 3

The following steps are to be followed to implement Logging through the Logger created by you

Get the instances of Configuration reader and Configuration writer.
Get the instance of the LogFactory and initialize it.
Get the Logger( added by you) .

Creating Your Logger at Runtime

Step 1

• Write a class implementing the AbstractLogger. You can give your own implementation for the methods available in the interface. You may add new methods, if need be.

Step 2

• Get the Properties of your Logger

• Get the instance of LoggerProperties by passing the Logger's InstanceName and WriterInstanceName as arguments.

• Set the Class name of the Logger which will be the class name of your own Logger Implementation.

• Set the LogLevel for your Logger.

• Add custom properties, if any.

Step 3

• Create the Logger using the methods in LogFactory.

Step 4

• Get the Logger and do further Logging.

Method Summary

void	addPropertyChangeListener(java.beans.PropertyChangeListener listener) This method is used to add the PropertyChangeListener to the Logger instance.
void	err(java.lang.String message, int level) The err method is used to display error messages.
void	err(java.lang.String message, java.lang.Throwable exception, int level) The err method is used to display error messages.
java.lang.String	getInstanceName() The getLoggerInstanceName method is used to get the LoggerInstanceName of the Logger.
int	getLogLevel() The getLogLevel method is used to get the current LogLevel of the particular Logger.
void	init(LoggerProperties loggerProperties, LogWriter logWriter) The init method is used to initialize a Logger.The properties of the Logger and the LogWriter are passed to this method.
void	out(java.lang.String message, int level) The out method is used to display some output messages or debugging messages.
boolean	removePropertyChangeListener(java.beans.PropertyChangeListener listener) This method is used to remove the PropertyChangeListener from the Logger instance.
void	setLogLevel(int level) The setLogLevel method is used to set the LogLevel of a Logger at runtime.

Method Detail

init

public void init(LoggerProperties loggerProperties,
                 LogWriter logWriter)
          throws LogException

The init method is used to initialize a Logger.The properties of the Logger and the LogWriter are passed to this method. The Logger properties include Logging level, Log Instance name , Display name and Log Class name

Parameters:

loggerProperties - a LoggerProperties having the properties of the Logger

logWriter - a LogWriter value

Throws:

LogException - if an error occurs during initialization

out

public void out(java.lang.String message,
                int level)

The out method is used to display some output messages or debugging messages. The message will be logged if and only if the message's logging level is less than or equal to the logging level of the Logger specified in the LoggerProperties if the logging level is not set at runtime.

Parameters:

message - a String having the message that has to be logged

level - an int specifying the level of the log message

err

public void err(java.lang.String message,
                int level)

The err method is used to display error messages. The message will be logged only when the message's logging level is less than or equal to the logging level of the Logger mentioned in the Logger Properties if the level is not set at runtime.

Parameters:

message - a String value

level - an int value

err

public void err(java.lang.String message,
                java.lang.Throwable exception,
                int level)

The err method is used to display error messages. The message and the exception will be logged if and only if the logging for that Logger is enabled and the message's logging level is less than or equal to the logging level of the Logger mentioned in the Logger Properties if the level is not set at runtime. The stack trace is passed along with the error messages.

Parameters:

message - a String value

exception - a Throwable value

level - an int value

setLogLevel

public void setLogLevel(int level)

The setLogLevel method is used to set the LogLevel of a Logger at runtime. If this method is not invoked at runtime, the logging level is taken from the Logger properties

Parameters:

level - an int value specifying the new LogLevel.

getLogLevel

public int getLogLevel()

The getLogLevel method is used to get the current LogLevel of the particular Logger. If the setLogLevel is not invoked at runtime, then logging level is obtained from the Logger properties. If the method is invoked , then the level which is set using the method setLogLevelis retreived .

Returns:

an int value denoting the current LogLevel.

getInstanceName

public java.lang.String getInstanceName()

The getLoggerInstanceName method is used to get the LoggerInstanceName of the Logger. The key name for the Logger for example MISCOUT,MISCERR etc will be retreived from this method.

Returns:

a String value

addPropertyChangeListener

public void addPropertyChangeListener(java.beans.PropertyChangeListener listener)

This method is used to add the PropertyChangeListener to the Logger instance. Upon any change in any property in this implementation all registered property change listeners will be notified about it.

Parameters:

listener - PropertyChangeListener to listen for any property change in this Logger

removePropertyChangeListener

public boolean removePropertyChangeListener(java.beans.PropertyChangeListener listener)

This method is used to remove the PropertyChangeListener from the Logger instance.

Parameters:

listener - PropertyChangeListener which was added to the listener

Returns:

boolean true on successful removal , false if the listener is not present