/*
* $Id$
*
* Copyright 2006, The jCoderZ.org Project. All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions are
* met:
*
* * Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
* * Redistributions in binary form must reproduce the above
* copyright notice, this list of conditions and the following
* disclaimer in the documentation and/or other materials
* provided with the distribution.
* * Neither the name of the jCoderZ.org Project nor the names of
* its contributors may be used to endorse or promote products
* derived from this software without specific prior written
* permission.
*
* THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS "AS IS" AND
* ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
* PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS AND CONTRIBUTORS
* BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
* CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
* SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
* BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
* WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
* OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
* ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
package org.jcoderz.commons;
import java.io.Serializable;
import java.util.List;
import java.util.Set;
/**
* Interface for all loggable objects.
*
* @author Andreas Mandel
*/
public interface Loggable
extends Serializable
{
/**
* Add a new parameter to the <code>Loggable</code>.
* All parameters are always added to the <code>Loggable</code>.
* There is no way of changing or removing a parameter. Once the
* <code>Loggable</code> was asked for one of it's values there
* <b>should</b> not be a new parameter. Nevertheless
* implementations of this interface MUST not throw an exception
* if this happens.
* Multiple parameters with the same name are stored within
* the <code>Loggable</code>.
* Values must be <code>Serializable</code> and have a useful
* to String representation. If the value is not serializable
* it might be sufficient to store the String representation
* of the value. The <code>Loggable</code> is not responsible
* to make a deep copy of the value. The calling code should
* take care for this. To solve this a possible solution
* would again be to use the String representation of the
* value.
* @param name the name of the parameter to be added.
* @param value the value for the parameter.
*/
void addParameter (String name, Serializable value);
/**
* Returns a list of all parameters with the given name.
* Even if the objects in the list are mutable clients are
* expected not to modify them and to make deep copies as
* needed.
* The <code>name</code> must not start with an <code>_</code>
* character. These are reserved for internal use.
* @param name The name of the parameter to be retrieved.
* @return a list of serializable objects representing the values
* of the parameters with the given name.
*/
List getParameter (String name);
/**
* Returns a set of available parameters.
* @return a set of available parameters.
*/
Set getParameterNames ();
/**
* Returns the {@link LogMessageInfo} for this <code>Loggable</code>.
* @return the {@link LogMessageInfo} for this <code>Loggable</code>.
*/
LogMessageInfo getLogMessageInfo ();
/**
* Returns the (unique) tracking number of this
* <code>Loggable</code> instance.
* @return the (unique) tracking number of this
* <code>Loggable</code> instance.
*/
String getTrackingNumber ();
/**
* Returns the (Detail) message of this loggable.
* The message is created using the pattern of the associated
* {@link LogMessageInfo} and parameters.
* The field might get truncated on the presentation layer.
* @return the (Detail) message of this loggable.
*/
String getMessage ();
/**
* Returns the point in time when the event occurred.
* More general this is the point in time when the
* <code>Loggable</code> object was created.
* @return the point in time when the event occurred, measured in
* milliseconds, between the current time and midnight,
* January 1, 1970 UTC.
*/
long getEventTime ();
/**
* Returns the ip-address or the host name where the Loggable was
* created.
* The field might get truncated on the presentation layer.
* @return the ip-address or the host name where the process is
* running on.
*/
String getNodeId ();
/**
* Returns the instance identifier of the process that generated
* this Loggable.
* The instance id should be a descriptive name for the process
* running the application. For example, on Bea WLS,
* we could use the Server name. If no such information is
* available, the OS Process ID should be used.
* The field might get truncated on the presentation layer.
* @return the instance identifier of the process that generated
* this Loggable.
*/
String getInstanceId ();
/**
* Returns the thread id of the thread that created this
* <code>Loggable</code>.
* @return the thread id of the thread that created this
* <code>Loggable</Code>.
*/
long getThreadId ();
/**
* Returns the thread name as it was valid at the time of
* creation of this <code>Loggable</code>.
* @return the thread name as it was valid at the time of
* creation of this <code>Loggable</code>.
* @see Thread#getName()
*/
String getThreadName ();
/**
* Returns the cause of this throwable or <code>null</code> if the
* cause is nonexistent or unknown. (The cause is the throwable
* that caused this throwable to get thrown.)
* The returned object might be a <code>Loggable</code>.
* @return the cause of this throwable or <code>null</code> if the
* cause is nonexistent or unknown.
*/
Throwable getCause ();
/**
* The toString method of <code>Loggable</code> dumps the
* String representation of the class name of the loggable
* and the contained message.
* @return one line information about this <code>Loggable</code>.
*/
String toString ();
/**
* The toString method of <code>Loggable</code> must dump out all
* information stored within this loggable in a readable way. This
* includes the information of possible nested data.
* @return a exhaustive dump of the data stored within this
* <code>Loggable</code>.
*/
String toDetailedString ();
/**
* Logs this <code>Loggable</code> into the appropriate log
* sink.
*/
void log ();
/**
* Tries to find the source method where this log event was fired.
* @return the name of the method including the line number if available
* @see StackTraceElement#getMethodName()
* @see StackTraceElement#getLineNumber()
*/
String getSourceMethod ();
/**
* Tries to find the source class name where this log event was fired.
* @return the name of the class
* @see StackTraceElement#getClassName()
*/
String getSourceClass ();
}