001 /*
002 * Copyright 2000-2004 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package java.util.logging;
027
028 /**
029 * <tt>Handler</tt> that buffers requests in a circular buffer in memory.
030 * <p>
031 * Normally this <tt>Handler</tt> simply stores incoming <tt>LogRecords</tt>
032 * into its memory buffer and discards earlier records. This buffering
033 * is very cheap and avoids formatting costs. On certain trigger
034 * conditions, the <tt>MemoryHandler</tt> will push out its current buffer
035 * contents to a target <tt>Handler</tt>, which will typically publish
036 * them to the outside world.
037 * <p>
038 * There are three main models for triggering a push of the buffer:
039 * <ul>
040 * <li>
041 * An incoming <tt>LogRecord</tt> has a type that is greater than
042 * a pre-defined level, the <tt>pushLevel</tt>.
043 * <li>
044 * An external class calls the <tt>push</tt> method explicitly.
045 * <li>
046 * A subclass overrides the <tt>log</tt> method and scans each incoming
047 * <tt>LogRecord</tt> and calls <tt>push</tt> if a record matches some
048 * desired criteria.
049 * </ul>
050 * <p>
051 * <b>Configuration:</b>
052 * By default each <tt>MemoryHandler</tt> is initialized using the following
053 * LogManager configuration properties. If properties are not defined
054 * (or have invalid values) then the specified default values are used.
055 * If no default value is defined then a RuntimeException is thrown.
056 * <ul>
057 * <li> java.util.logging.MemoryHandler.level
058 * specifies the level for the <tt>Handler</tt>
059 * (defaults to <tt>Level.ALL</tt>).
060 * <li> java.util.logging.MemoryHandler.filter
061 * specifies the name of a <tt>Filter</tt> class to use
062 * (defaults to no <tt>Filter</tt>).
063 * <li> java.util.logging.MemoryHandler.size
064 * defines the buffer size (defaults to 1000).
065 * <li> java.util.logging.MemoryHandler.push
066 * defines the <tt>pushLevel</tt> (defaults to <tt>level.SEVERE</tt>).
067 * <li> java.util.logging.MemoryHandler.target
068 * specifies the name of the target <tt>Handler </tt> class.
069 * (no default).
070 * </ul>
071 *
072 * @version 1.32, 05/05/07
073 * @since 1.4
074 */
075
076 public class MemoryHandler extends Handler {
077 private final static int DEFAULT_SIZE = 1000;
078 private Level pushLevel;
079 private int size;
080 private Handler target;
081 private LogRecord buffer[];
082 int start, count;
083
084 // Private method to configure a ConsoleHandler from LogManager
085 // properties and/or default values as specified in the class
086 // javadoc.
087 private void configure() {
088 LogManager manager = LogManager.getLogManager();
089 String cname = getClass().getName();
090
091 pushLevel = manager.getLevelProperty(cname + ".push",
092 Level.SEVERE);
093 size = manager.getIntProperty(cname + ".size", DEFAULT_SIZE);
094 if (size <= 0) {
095 size = DEFAULT_SIZE;
096 }
097 setLevel(manager.getLevelProperty(cname + ".level", Level.ALL));
098 setFilter(manager.getFilterProperty(cname + ".filter", null));
099 setFormatter(manager.getFormatterProperty(cname + ".formatter",
100 new SimpleFormatter()));
101 }
102
103 /**
104 * Create a <tt>MemoryHandler</tt> and configure it based on
105 * <tt>LogManager</tt> configuration properties.
106 */
107 public MemoryHandler() {
108 sealed = false;
109 configure();
110 sealed = true;
111
112 String name = "???";
113 try {
114 LogManager manager = LogManager.getLogManager();
115 name = manager
116 .getProperty("java.util.logging.MemoryHandler.target");
117 Class clz = ClassLoader.getSystemClassLoader().loadClass(
118 name);
119 target = (Handler) clz.newInstance();
120 } catch (Exception ex) {
121 throw new RuntimeException(
122 "MemoryHandler can't load handler \"" + name + "\"",
123 ex);
124 }
125 init();
126 }
127
128 // Initialize. Size is a count of LogRecords.
129 private void init() {
130 buffer = new LogRecord[size];
131 start = 0;
132 count = 0;
133 }
134
135 /**
136 * Create a <tt>MemoryHandler</tt>.
137 * <p>
138 * The <tt>MemoryHandler</tt> is configured based on <tt>LogManager</tt>
139 * properties (or their default values) except that the given <tt>pushLevel</tt>
140 * argument and buffer size argument are used.
141 *
142 * @param target the Handler to which to publish output.
143 * @param size the number of log records to buffer (must be greater than zero)
144 * @param pushLevel message level to push on
145 *
146 * @throws IllegalArgumentException is size is <= 0
147 */
148 public MemoryHandler(Handler target, int size, Level pushLevel) {
149 if (target == null || pushLevel == null) {
150 throw new NullPointerException();
151 }
152 if (size <= 0) {
153 throw new IllegalArgumentException();
154 }
155 sealed = false;
156 configure();
157 sealed = true;
158 this .target = target;
159 this .pushLevel = pushLevel;
160 this .size = size;
161 init();
162 }
163
164 /**
165 * Store a <tt>LogRecord</tt> in an internal buffer.
166 * <p>
167 * If there is a <tt>Filter</tt>, its <tt>isLoggable</tt>
168 * method is called to check if the given log record is loggable.
169 * If not we return. Otherwise the given record is copied into
170 * an internal circular buffer. Then the record's level property is
171 * compared with the <tt>pushLevel</tt>. If the given level is
172 * greater than or equal to the <tt>pushLevel</tt> then <tt>push</tt>
173 * is called to write all buffered records to the target output
174 * <tt>Handler</tt>.
175 *
176 * @param record description of the log event. A null record is
177 * silently ignored and is not published
178 */
179 public synchronized void publish(LogRecord record) {
180 if (!isLoggable(record)) {
181 return;
182 }
183 int ix = (start + count) % buffer.length;
184 buffer[ix] = record;
185 if (count < buffer.length) {
186 count++;
187 } else {
188 start++;
189 start %= buffer.length;
190 }
191 if (record.getLevel().intValue() >= pushLevel.intValue()) {
192 push();
193 }
194 }
195
196 /**
197 * Push any buffered output to the target <tt>Handler</tt>.
198 * <p>
199 * The buffer is then cleared.
200 */
201 public synchronized void push() {
202 for (int i = 0; i < count; i++) {
203 int ix = (start + i) % buffer.length;
204 LogRecord record = buffer[ix];
205 target.publish(record);
206 }
207 // Empty the buffer.
208 start = 0;
209 count = 0;
210 }
211
212 /**
213 * Causes a flush on the target <tt>Handler</tt>.
214 * <p>
215 * Note that the current contents of the <tt>MemoryHandler</tt>
216 * buffer are <b>not</b> written out. That requires a "push".
217 */
218 public void flush() {
219 target.flush();
220 }
221
222 /**
223 * Close the <tt>Handler</tt> and free all associated resources.
224 * This will also close the target <tt>Handler</tt>.
225 *
226 * @exception SecurityException if a security manager exists and if
227 * the caller does not have <tt>LoggingPermission("control")</tt>.
228 */
229 public void close() throws SecurityException {
230 target.close();
231 setLevel(Level.OFF);
232 }
233
234 /**
235 * Set the <tt>pushLevel</tt>. After a <tt>LogRecord</tt> is copied
236 * into our internal buffer, if its level is greater than or equal to
237 * the <tt>pushLevel</tt>, then <tt>push</tt> will be called.
238 *
239 * @param newLevel the new value of the <tt>pushLevel</tt>
240 * @exception SecurityException if a security manager exists and if
241 * the caller does not have <tt>LoggingPermission("control")</tt>.
242 */
243 public void setPushLevel(Level newLevel) throws SecurityException {
244 if (newLevel == null) {
245 throw new NullPointerException();
246 }
247 LogManager manager = LogManager.getLogManager();
248 checkAccess();
249 pushLevel = newLevel;
250 }
251
252 /**
253 * Get the <tt>pushLevel</tt>.
254 *
255 * @return the value of the <tt>pushLevel</tt>
256 */
257 public synchronized Level getPushLevel() {
258 return pushLevel;
259 }
260
261 /**
262 * Check if this <tt>Handler</tt> would actually log a given
263 * <tt>LogRecord</tt> into its internal buffer.
264 * <p>
265 * This method checks if the <tt>LogRecord</tt> has an appropriate level and
266 * whether it satisfies any <tt>Filter</tt>. However it does <b>not</b>
267 * check whether the <tt>LogRecord</tt> would result in a "push" of the
268 * buffer contents. It will return false if the <tt>LogRecord</tt> is Null.
269 * <p>
270 * @param record a <tt>LogRecord</tt>
271 * @return true if the <tt>LogRecord</tt> would be logged.
272 *
273 */
274 public boolean isLoggable(LogRecord record) {
275 return super.isLoggable(record);
276 }
277 }
|