Project Report: fawkez

Packagesummary org.jcoderz.commons

org.jcoderz.commons.Loggable

LineHitsNoteSource
1  /*
2   * $Id: Loggable.java 1492 2009-06-06 13:36:19Z 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 thread name as it was valid at the time of
154      * creation of this <code>Loggable</code>.
155      * @return the thread name as it was valid at the time of
156      * creation of this <code>Loggable</code>.
157      * @see Thread#getName()
158      */
159     String getThreadName ();
160  
161     /**
162      * Returns the cause of this throwable or <code>null</code> if the
163      * cause is nonexistent or unknown.  (The cause is the throwable
164      * that caused this throwable to get thrown.)
165      * The returned object might be a <code>Loggable</code>.
166      * @return the cause of this throwable or <code>null</code> if the
167      *          cause is nonexistent or unknown.
168      */
169     Throwable getCause ();
170  
171     /**
172      * The toString method of <code>Loggable</code> dumps the
173      * String representation of the class name of the loggable
174      * and the contained message.
175      * @return one line information about this <code>Loggable</code>.
176      */
177     String toString ();
178  
179     /**
180      * The toString method of <code>Loggable</code> must dump out all
181      * information stored within this loggable in a readable way. This
182      * includes the information of possible nested data.
183      * @return a exhaustive dump of the data stored within this
184      *       <code>Loggable</code>.
185      */
186     String toDetailedString ();
187  
188     /**
189      * Logs this <code>Loggable</code> into the appropriate log
190      * sink.
191      */
192     void log ();
193  
194     /**
195      * Tries to find the source method where this log event was fired.
196      * @return the name of the method including the line number if available
197      * @see StackTraceElement#getMethodName()
198      * @see StackTraceElement#getLineNumber()
199      */
200     String getSourceMethod ();
201  
202     /**
203      * Tries to find the source class name where this log event was fired.
204      * @return the name of the class
205      * @see StackTraceElement#getClassName()
206      */
207     String getSourceClass ();
208  
209  }

Findings in this File