Copyright 2009,2010, Lapetus Systems Ltd. (All rights reserved)

com.lapetus_ltd.api.common.logger
Class TLptsLogger

java.lang.Object
  extended by com.lapetus_ltd.api.common.logger.TLptsLogger

public class TLptsLogger
extends java.lang.Object

Class Description : Class responsible for controlling the logs.

This is the class responsible for logging all the issues in the system at runtime. These issues can be
errors, messages, warnings or debugs. Every call to the logXXXX functions causes a TLptsLog to be generated.
This log class contains all the message and exception information for the issue that was logged.

The logs are stored in a list until they are cleared.
Furthermore, there is a listener called TLptsLogOutputListener which records the logs to a text file.
The default directory for storing the log window log files is /{user.home}/lapetus.

$LastChangedRevision: 1177 $
$LastChangedDate:: 2010-11-09 15:27:48#$


Nested Class Summary
static class TLptsLogger.LOG_TYPE
          Type of log to record.
 
Method Summary
static void addListener(ILptsLogListener listener)
           Add a listener (that implements ILptsLogListener) to be informed of all logs.
static boolean clearLogList()
          Clears and deletes the current list of logs in the logger.
static java.util.List<TLptsLog> getLogList(boolean showLastFirst)
          Gets a copy of the list of all the logs in the logger.
static int getLogListSize()
          Gets the size of the Log List.
static TLptsLog logDebug(java.lang.String text, java.lang.Exception exception)
          Logs a debug and informs all registered log listeners.
static TLptsLog logDebug(java.lang.String errorCode, java.lang.String supportingText, java.lang.Exception exception)
          Like logDebug, but uses an internal resource error code.
static TLptsLog logError(java.lang.String text, java.lang.Exception exception)
          Logs an error and informs all registered log listeners.
static TLptsLog logError(java.lang.String errorCode, java.lang.String supportingText, java.lang.Exception exception)
          Like logError, but it uses a resource error code to find the string.
static TLptsLog logMessage(java.lang.String text, java.lang.Exception exception)
          Log a message and inform all registered log listeners.
static TLptsLog logMessage(java.lang.String errorCode, java.lang.String supportingText, java.lang.Exception exception)
          Like logMessage, but uses a resource error code.
static TLptsLog logWarning(java.lang.String text, java.lang.Exception exception)
          Logs a warning and informs all registered log listeners.
static TLptsLog logWarning(java.lang.String errorCode, java.lang.String supportingText, java.lang.Exception exception)
          Like logWarning, but uses an internal resource error code.
static void removeListener(ILptsLogListener listener)
           Remove a previously added listener.
static void removeStdoutListener()
          By default all error logs go to stdout.
static void sendResetToListeners()
          Sends a reset to all the log listeners.
static void setMaxLogListSize(int logListSize)
          Sets the maximum size of the log list.
static void setPopupParentFrame(javax.swing.JFrame frame)
           Sets the message popup parent frame so that it is centred on that frame.
static void setRecipientId(int recipientId)
          Sets the ID of all logs that follow, so that a recipient can identify them.
static void zI()
          Obfuscated, as it is not required by the application.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

addListener

public static void addListener(ILptsLogListener listener)

Add a listener (that implements ILptsLogListener) to be informed of all logs.

Thread Safe : Yes

Spawns its own Thread : No

May Return NULL : No

Notes : If any given log listener is added twice, the first item is removed.

This means that the remove is called before every add, so that there are no duplicates.

Example :

 

public class TLogListener implements ILptsLogListener { public TLogListener() { TLptsLogger.addListener(this); }

// every time a log is generated this function will be called. void newLogGenerated(TLptsLog log) { if (log.getType()== ... } }

// somewhere else in the code of this application. try { // Doing something here that throws and exception. } catch (Exception e) { TLptsLogger.logWarning("This is a log with an exception.",e); // All listeners are informed, including TLogListener }

Parameters:
listener - The implementation of ILptsLogListener to add as a listener. ILptsLogListener)

clearLogList

public static boolean clearLogList()
Clears and deletes the current list of logs in the logger.

Thread Safe : Yes

Spawns its own Thread : No

May Return NULL : No

Notes : This may be necessary if many logs are generated at a high rate.
At the end of this a RESET log type is sent to all listeners.

Example :

 

for (TLptsLog log : TLptsLogger.getLogList(true)) // get the latest log first processToMyLogs(log);

TLptsLogger.clearLogList();

Returns:
Returns true if the list had items in it. False if it was empty.

getLogList

public static java.util.List<TLptsLog> getLogList(boolean showLastFirst)
Gets a copy of the list of all the logs in the logger.

Thread Safe : Yes

Spawns its own Thread : No

May Return NULL : Never, an empty list in the worst case.

Notes : This is a duplicate list. Any changes to this list will not affect the logging system.

Example :


 

try { // Doing something here that throws and exception. } catch (Exception e) { // I don't have a clue what just happened. // There are no log listeners declared, so lets look at the log list. for (TLptsLog log : TLptsLogger.getLogList(true)) // true = get the latest log first System.out.println("Log text: " + log.getMessage() + " : " + log.getExceptionMessage()); }

Parameters:
showLastFirst - if true, the last log is first in the list. The second last is second etc. Otherwise it is chronological.
Returns:
Returns a synchronised copy of the list in the log system.

getLogListSize

public static int getLogListSize()
Gets the size of the Log List.

Thread Safe : Yes.

Spawns its own Thread : No.

May Return NULL : No, zero in the worst case.

Notes : Use this instead of getLogList().size().

Example :


 //We clear the logList
 TLptsLogger.clearLogList();

 {

  //Write your code here and catch any exceptions

 }

 if(TLptsLogger.getLogListSize() > 0)
    System.out.println("There are Logs : The number of logs are : " + TLptsLogger.getLogListSize());
 else
    System.out.println("There are no logs in the Logger!");

 

Returns:
the size of the Log List.

logDebug

public static TLptsLog logDebug(java.lang.String text,
                                java.lang.Exception exception)
Logs a debug and informs all registered log listeners.

Thread Safe : Yes

Spawns its own Thread : No

May Return NULL : No

Notes :

Example :

 

try { // Doing something here that throws and exception. } catch (Exception e) { TLptsLogger.logDebug("This is a debug. Module XXX and function YYY and it did the following : ",e); } ... // In one of the listeners of the logger public class TLogListener implements ILptsLogListener { void newLogGenerated(TLptsLog log) { if (log.getType()==TLptsLogger.LOG_TYPE.DEBUG) { // ### This is some thing that the users should not be informed of. ### // ### They may realise that we don't have a clue .... ### } } }

Parameters:
text - The text that should accompany the debug being logged here.
exception - If an exception generated this log then include it here. It will be stored with the log for later retrieval.
Returns:
A newly created log TLptsLog. This log is also sent to all listeners.

logDebug

public static TLptsLog logDebug(java.lang.String errorCode,
                                java.lang.String supportingText,
                                java.lang.Exception exception)
Like logDebug, but uses an internal resource error code.

Thread Safe : Yes

Spawns its own Thread : No

May Return NULL : No

Notes : For internal multi-language support only. Use (@link #logDebug((final String text, final Exception exception)))

Example :


 try
 {
   // Doing something here that throws and exception.
 } catch (Exception e)
 {
   TLptsLogger.logDebug("debug.error.code","This is the supporting debug.",e);
 }
 ...
 // In one of the listeners of the logger
 public class TLogListener implements ILptsLogListener
 {
   void newLogGenerated(TLptsLog log)
   {
      if (log.getType()==TLptsLogger.LOG_TYPE.DEBUG)
      {
        // ### This is some thing that the users should not be informed of. ###
        // ### They may realise that we are totally lost ...                ###
      }
   }
 }

 

Parameters:
errorCode - the text we set for this exception.
supportingText - The text that should accompany the error being logged here.
exception - If an exception generated this log then include it here. It will be stored with the log for later retrieval.
Returns:
A newly created log TLptsLog. This is also sent to all listeners.

logError

public static TLptsLog logError(java.lang.String text,
                                java.lang.Exception exception)
Logs an error and informs all registered log listeners.

Thread Safe : Yes

Spawns its own Thread : No

May Return NULL : No

Notes :

Example :



 try
 {
   // Doing something here that throws and exception.
 } catch (Exception e)
 {
   // Something unexpected happened and the application caught it.
   TLptsLogger.logError("The application threw an exception.",e);
 }
 ...
 // In one of the listeners of the logger
 public class TLogListener implements ILptsLogListener
 {
   void newLogGenerated(TLptsLog log)
   {
      if (log.getType()==TLptsLogger.LOG_TYPE.ERROR)
      {
        System.out.println("Error logger: " + log.getMessage());
        System.out.println("Exception message: " + log.getExceptionMessage());
        processException(log.getException());
      }
   }
 }
 

Parameters:
text - The text that should accompany the error being logged here.
exception - If an exception generated this log then include it here. It will be stored with the log for later retrieval by the listener.
Returns:
A newly created log TLptsLog which is also sent to all listeners.

logError

public static TLptsLog logError(java.lang.String errorCode,
                                java.lang.String supportingText,
                                java.lang.Exception exception)
Like logError, but it uses a resource error code to find the string.

Thread Safe : Yes

Spawns its own Thread : No

May Return NULL : No

Notes : For internal multi-language support only. Use (@link #logError((final String text, final Exception exception)))

Example :



 try
 {
   // Doing something here that throws and exception.
 } catch (Exception e)
 {
   // Something unexpected happened and the application caught it.
   TLptsLogger.logError("mywindow.error.code.txt","The application threw an exception.",e);
 }
 ...
 // In one of the listeners of the logger
 public class TLogListener implements ILptsLogListener
 {
   void newLogGenerated(TLptsLog log)
   {
      if (log.getType()==TLptsLogger.LOG_TYPE.ERROR)
      {
        System.out.println("Error logger: " + log.getMessage());
        System.out.println("Exception message: " + log.getExceptionMessage());
        processException(log.getException());
      }
   }
 }

 * 

Parameters:
errorCode - the text we set for this exception.
supportingText - The text that should accompany the error being logged here.
exception - If an exception generated this log then include it here. It will be stored with the log for later retrieval by the application listener.
Returns:
A newly created log TLptsLog which is also sent to all listeners.

logMessage

public static TLptsLog logMessage(java.lang.String text,
                                  java.lang.Exception exception)
Log a message and inform all registered log listeners.

Thread Safe : Yes

Spawns its own Thread : No

May Return NULL : No

Notes :

Example :

 

// I am doing something and the user should be informed. TLptsLogger.logMessage("This is a message.",e); ... // In one of the listeners of the logger public class TLogListener implements ILptsLogListener { void newLogGenerated(TLptsLog log) { if (log.getType()==TLptsLogger.LOG_TYPE.MESSAGE) { System.out.println("Message : " + log.getMessage()); } } }

Parameters:
text - The text that should accompany the message being logged here.
exception - If an exception generated this log then include it here. It will be stored with the log for later retrieval.
Returns:
A newly created log TLptsLog. This is also sent to all listeners.

logMessage

public static TLptsLog logMessage(java.lang.String errorCode,
                                  java.lang.String supportingText,
                                  java.lang.Exception exception)
Like logMessage, but uses a resource error code.

Thread Safe : Yes

Spawns its own Thread : No

May Return NULL : No

Notes : For internal multi-language support only. Use (@link #logMessage((final String text, final Exception exception)))

Example :


 try
 {
   // Doing something here that throws and exception.
 } catch (Exception e)
 {
   TLptsLogger.logMessage("an.internal.message.code.txt","This is the supporting message.",e);
 }
 ...
 // In one of the listeners of the logger
 public class TLogListener implements ILptsLogListener
 {
   void newLogGenerated(TLptsLog log)
   {
      if (log.getType()==TLptsLogger.LOG_TYPE.MESSAGE)
      {
        System.out.println("Message : " + log.getMessage());
      }
   }
 }

 

Parameters:
errorCode - the text we set for this exception.
supportingText - The text that should accompany the error being logged here.
exception - If an exception generated this log then include it here. It will be stored with the log for later retrieval.
Returns:
A newly created log TLptsLog. This log is also sent to all listeners.

logWarning

public static TLptsLog logWarning(java.lang.String text,
                                  java.lang.Exception exception)
Logs a warning and informs all registered log listeners.

Thread Safe : Yes

Spawns its own Thread : No

May Return NULL : No

Notes :

Example :

 

try { // Doing something here that throws and exception. } catch (Exception e) { TLptsLogger.logWarning("This is a warning.",e); } ... // In one of the listeners of the logger public class TLogListener implements ILptsLogListener { void newLogGenerated(TLptsLog log) { if (log.getType()==TLptsLogger.LOG_TYPE.WARNING) { System.out.println("Warning. An unwanted situation came about, but things are still under constrol : " + log.getMessage()); System.out.println("Exception message: " + log.getExceptionMessage()); } } }

Parameters:
text - The text that should accompany the warning being logged here.
exception - If an exception generated this log then include it here. It will be stored with the log for later retrieval by the application listener.
Returns:
A newly created log TLptsLog which is also sent to all listeners.

logWarning

public static TLptsLog logWarning(java.lang.String errorCode,
                                  java.lang.String supportingText,
                                  java.lang.Exception exception)
Like logWarning, but uses an internal resource error code.

Thread Safe : Yes

Spawns its own Thread : No

May Return NULL : No

Notes : For internal multi-language support only. Use (@link #logWarning((final String text, final Exception exception)))

Example :

 try
 {
   // Doing something here that throws and exception.
 } catch (Exception e)
 {
   TLptsLogger.logWarning("mycode.warming.txt","This is the supporting warning.",e);
 }
 ...
 // In one of the listeners of the logger
 public class TLogListener implements ILptsLogListener
 {
   void newLogGenerated(TLptsLog log)
   {
      if (log.getType()==TLptsLogger.LOG_TYPE.WARNING)
      {
        System.out.println("Warning. An unwanted situation came about, but things are still under constrol : " + log.getMessage());
        System.out.println("Exception message: " + log.getExceptionMessage());
      }
   }
 }

 

Parameters:
errorCode - the text we set for this exception.
supportingText - The text that should accompany the error being logged here.
exception - If an exception generated this log then include it here. It will be stored with the log for later retrieval.
Returns:
A newly created log TLptsLog. This is also sent to all listeners

removeListener

public static void removeListener(ILptsLogListener listener)

Remove a previously added listener. addListener(com.lapetus_ltd.api.common.logger.ILptsLogListener)

Thread Safe : Yes

Spawns its own Thread : No

May Return NULL : No

Notes :

Example :


 public class TLogListener implements ILptsLogListener
 {
   public TLogListener()
   {
      TLptsLogger.addListener(this);
   }

   // every time a log is generated this function will be called.
   void newLogGenerated(TLptsLog log)
   {
      if (log.getType()== ...
        .
        .
        .
   }
 }
 

// somewhere else in the code of this application. ILptsLogListener logListener; addListener(logListener = new TLogListener()); ... ... removeListener(logListener);

Parameters:
listener - The listener to remove from the log system listener list. If the listener to be removed is not in the list there is no error or negative reaction.

removeStdoutListener

public static void removeStdoutListener()
By default all error logs go to stdout. This removes the listener.

Thread Safe : Yes

Spawns its own Thread : No

May Return NULL : No

Notes : After performing this function, the logs will no longer appear on stdout.
They will be stored in the log list only.

Example :

 

TLptsLogger.removeStdoutListener();


sendResetToListeners

public static void sendResetToListeners()
Sends a reset to all the log listeners.

Thread Safe : Yes

Spawns its own Thread : No

May Return NULL : No

Notes : Sends a log with the type LOG_TYPE.RESET to all listeners.

Example :


 

TLptsLogger.sendResetToListeners(); ... // In one of the listeners of the logger public class TLogListener implements ILptsLogListener { void newLogGenerated(TLptsLog log) { if (log.getType()==TLptsLogger.LOG_TYPE.RESET) { // Clear my log list and reset the fields } } }


setMaxLogListSize

public static void setMaxLogListSize(int logListSize)
Sets the maximum size of the log list.

Thread Safe : Yes

Spawns its own Thread : No

May Return NULL : No

Notes : The default is 1000 logs.

Example :


 TLptsLogger.setMaxLogListSize (200);
 try
 {
   // I did something wrong here and was caught in the act 201 times
 } catch (Exception e)
 {
   TLptsLogger.logError("Wow - This is a serious error",e);
 }
 Result : The result is that the first log (chronologically) will be deleted.
 

Parameters:
logListSize - an integer of the max size.

setPopupParentFrame

public static void setPopupParentFrame(javax.swing.JFrame frame)

Sets the message popup parent frame so that it is centred on that frame.

Thread Safe : Yes

Spawns its own Thread : No

May Return NULL : No

Notes : The default is that the popup comes up in the middle of the (main) monitor.

Example :


 TLptsLogger.setPopupParentFrame(myApplicationMainFrame);

 // lets show ERROR messages in the popup, along with the already set types
 TLptsLogger.setMessageDialog(TLptsLogger.getMessageDialog()|TLptsLogger.SHOW_DIALOG_FOR_ERROR);
 TLptsLogger.logError("This is a test LOG message",null);
 
 Result: It pops up in the centre of the application main frame.

 

Parameters:
frame - The frame to be used for centering the popup message dialog.

setRecipientId

public static void setRecipientId(int recipientId)
Sets the ID of all logs that follow, so that a recipient can identify them.

Thread Safe : Yes

Spawns its own Thread : No

May Return NULL : No

Notes : The default is 0. Any number can be put here.

It is ignored by the system and is purely used for application filtering purposes.

Example :


 TLptsLogger.setRecipientId(123);
 TLptsLogger.logMessage("Log message for id 123",null);
 ...
 // In one of the listeners of the logger
 public class My123LogListener implements ILptsLogListener
 {
   void newLogGenerated(TLptsLog log)
   {
      if (log.getId()==123)
      {
        // this is my log. Let me process it now
      }
   }
 }
 

Parameters:
recipientId - The ID we wish to assign to all logs that follow (until it is set to something else that is).

zI

public static void zI()
Obfuscated, as it is not required by the application.



Copyright 2009,2010, Lapetus Systems Ltd. (All rights reserved)