Project Report: fawkez

Packagesummary org.jcoderz.commons

org.jcoderz.commons.Loggable

LineHitsNoteSource
1  /*
2   * $Id: Loggable.java 1011 2008-06-16 17:57:36Z amandel $
3   *
4   * Copyright 2006, The jCoderZ.org Project. All rights reserved.
5   *
6   * Redistribution and use in source and binary forms, with or without
7   * modification, are permitted provided that the following conditions are
8   * met:
9   *
10   *    * Redistributions of source code must retain the above copyright
11   *      notice, this list of conditions and the following disclaimer.
12   *    * Redistributions in binary form must reproduce the above
13   *      copyright notice, this list of conditions and the following
14   *      disclaimer in the documentation and/or other materials
15   *      provided with the distribution.
16   *    * Neither the name of the jCoderZ.org Project nor the names of
17   *      its contributors may be used to endorse or promote products
18   *      derived from this software without specific prior written
19   *      permission.
20   *
21   * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS "AS IS" AND
22   * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
23   * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
24   * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS AND CONTRIBUTORS
25   * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
26   * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
27   * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
28   * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
29   * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
30   * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
31   * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
32   */
33  package org.jcoderz.commons;
34   
35  import java.io.Serializable;
36  import java.util.List;
37  import java.util.Set;
38   
39  /**
40   * Interface for all loggable objects.
41   *
42   * @author Andreas Mandel
43   */
44  public interface Loggable
45        extends Serializable
46  {
47     /**
48      * Add a new parameter to the <code>Loggable</code>.
49      * All parameters are always added to the <code>Loggable</code>.
50      * There is no way of changing or removing a parameter. Once the
51      * <code>Loggable</code> was asked for one of it's values there
52      * <b>should</b> not be a new parameter. Nevertheless
53      * implementations of this interface MUST not throw an exception
54      * if this happens.
55      * Multiple parameters with the same name are stored within
56      * the <code>Loggable</code>.
57      * Values must be <code>Serializable</code> and have a useful
58      * to String representation. If the value is not serializable
59      * it might be sufficient to store the String representation
60      * of the value. The <code>Loggable</code> is not responsible
61      * to make a deep copy of the value. The calling code should
62      * take care for this. To solve this a possible solution
63      * would again be to use the String representation of the
64      * value.
65      * @param name the name of the parameter to be added.
66      * @param value the value for the parameter.
67      */
68     void addParameter (String name, Serializable value);
69   
70     /**
71      * Returns a list of all parameters with the given name.
72      * Even if the objects in the list are mutable clients are
73      * expected not to modify them and to make deep copies as
74      * needed.
75      * The <code>name</code> must not start with an <code>_</code>
76      * character. These are reserved for internal use.
77      * @param name The name of the parameter to be retrieved.
78      * @return a list of serializable objects representing the values
79      *       of the parameters with the given name.
80      */
81     List getParameter (String name);
82   
83     /**
84      * Returns a set of available parameters.
85      * @return a set of available parameters.
86      */
87     Set getParameterNames ();
88   
89     /**
90      * Returns the {@link LogMessageInfo} for this <code>Loggable</code>.
91      * @return the {@link LogMessageInfo} for this <code>Loggable</code>.
92      */
93     LogMessageInfo getLogMessageInfo ();
94   
95     /**
96      * Returns the (unique) tracking number of this
97      * <code>Loggable</code> instance.
98      * @return the (unique) tracking number of this
99      * <code>Loggable</code> instance.
100      */
101     String getTrackingNumber ();
102   
103     /**
104      * Returns the (Detail) message of this loggable.
105      * The message is created using the pattern of the associated
106      * {@link LogMessageInfo} and parameters.
107      * The field might get truncated on the presentation layer.
108      * @return the (Detail) message of this loggable.
109      */
110     String getMessage ();
111   
112     /**
113      * Returns the point in time when the event occurred.
114      * More general this is the point in time when the
115      * <code>Loggable</code> object was created.
116      * @return the point in time when the event occurred, measured in
117      *       milliseconds, between the current time and midnight,
118      *       January 1, 1970 UTC.
119      */
120     long getEventTime ();
121   
122     /**
123      * Returns the ip-address or the host name where the Loggable was
124      * created.
125      * The field might get truncated on the presentation layer.
126      * @return the ip-address or the host name where the process is
127      * running on.
128      */
129     String getNodeId ();
130   
131     /**
132      * Returns the instance identifier of the process that generated
133      * this Loggable.
134      * The instance id should be a descriptive name for the process
135      * running the application. For example, on Bea WLS,
136      * we could use the Server name. If no such information is
137      * available, the OS Process ID should be used.
138      * The field might get truncated on the presentation layer.
139      * @return the instance identifier of the process that generated
140      * this Loggable.
141      */
142     String getInstanceId ();
143   
144     /**
145      * Returns the thread id of the thread that created this
146      * <code>Loggable</code>.
147      * @return the thread id of the thread that created this
148      * <code>Loggable</Code>.
149      */
150     long getThreadId ();
151   
152     /**
153      * Returns the cause of this throwable or <code>null</code> if the
154      * cause is nonexistent or unknown.  (The cause is the throwable
155      * that caused this throwable to get thrown.)
156      * The returned object might be a <code>Loggable</code>.
157      * @return  the cause of this throwable or <code>null</code> if the
158      *          cause is nonexistent or unknown.
159      */
160     Throwable getCause ();
161   
162     /**
163      * The toString method of <code>Loggable</code> must dump out all
164      * information stored within this loggable in a readable way. This
165      * includes the information of possible nested data.
166      * @return a exhaustive dump of the data stored within this
167      *       <code>Loggable</code>.
168      */
169     String toString ();
170   
171     /**
172      * Logs this <code>Loggable</code> into the appropriate log
173      * sink.
174      */
175     void log ();
176   
177     /**
178      * Tries to find the source method where this log event was fired.
179      * @return the name of the method including the line number if available
180      * @see StackTraceElement#getMethodName()
181      * @see StackTraceElement#getLineNumber()
182      */
183     String getSourceMethod ();
184   
185     /**
186      * Tries to find the source class name where this log event was fired.
187      * @return the name of the class
188      * @see StackTraceElement#getClassName()
189      */
190     String getSourceClass ();
191   
192  }
193   

Findings in this File