X-Git-Url: http://source.jalview.org/gitweb/?a=blobdiff_plain;f=srcjar_unused%2Forg%2Fapache%2Flog4j%2FEnhancedPatternLayout.java;fp=srcjar_unused%2Forg%2Fapache%2Flog4j%2FEnhancedPatternLayout.java;h=a8158dad859207cdc178837afe6758baeb714471;hb=2639d90e2b52d49cf586c0b602bc606033c9b8ae;hp=0000000000000000000000000000000000000000;hpb=aaead18c6acb21da4d63f3ad9f454d9eb410152f;p=jalview.git diff --git a/srcjar_unused/org/apache/log4j/EnhancedPatternLayout.java b/srcjar_unused/org/apache/log4j/EnhancedPatternLayout.java new file mode 100644 index 0000000..a8158da --- /dev/null +++ b/srcjar_unused/org/apache/log4j/EnhancedPatternLayout.java @@ -0,0 +1,571 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.log4j; + +import org.apache.log4j.helpers.OptionConverter; +import org.apache.log4j.helpers.PatternConverter; +import org.apache.log4j.pattern.BridgePatternConverter; +import org.apache.log4j.spi.LoggingEvent; + + +// Contributors: Nelson Minar +// Anders Kristensen + +/** + * This class is an enhanced version of org.apache.log4j.PatternLayout + * which was originally developed as part of the abandoned log4j 1.3 + * effort and has been available in the extras companion. + * This pattern layout should be used in preference to + * org.apache.log4j.PatternLayout except when compatibility + * where PatternLayout has been extended either through subclassing + * or alternative pattern parsers. + * + * + *

A flexible layout configurable with pattern string. The goal of this class + * is to {@link #format format} a {@link LoggingEvent} and return the results + * in a {@link StringBuffer}. The format of the result depends on the + * conversion pattern. + *

+ * + *

The conversion pattern is closely related to the conversion + * pattern of the printf function in C. A conversion pattern is + * composed of literal text and format control expressions called + * conversion specifiers. + * + *

Note that you are free to insert any literal text within the + * conversion pattern. + *

+ +

Each conversion specifier starts with a percent sign (%) and is + followed by optional format modifiers and a conversion + character. The conversion character specifies the type of + data, e.g. category, priority, date, thread name. The format + modifiers control such things as field width, padding, left and + right justification. The following is a simple example. + +

Let the conversion pattern be "%-5p [%t]: %m%n" and assume + that the log4j environment was set to use a EnhancedPatternLayout. Then the + statements + 

+   Category root = Category.getRoot();
+   root.debug("Message 1");
+   root.warn("Message 2");
+
+ would yield the output + 
+   DEBUG [main]: Message 1
+   WARN  [main]: Message 2
+
+ +

Note that there is no explicit separator between text and + conversion specifiers. The pattern parser knows when it has reached + the end of a conversion specifier when it reads a conversion + character. In the example above the conversion specifier + %-5p means the priority of the logging event should be left + justified to a width of five characters. + + The recognized conversion characters are + +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Conversion CharacterEffect
cUsed to output the category of the logging event. The + category conversion specifier can be optionally followed by + NameAbbreviator pattern. + +

For example, for the category name "alpha.beta.gamma" the pattern + %c{2} will output the last two elements ("beta.gamma"), + %c{-2} will remove two elements leaving "gamma", + %c{1.} will output "a.b.gamma". + +

CUsed to output the fully qualified class name of the caller + issuing the logging request. This conversion specifier + can be optionally followed by precision specifier, that + is a decimal constant in brackets. + + Used to output the category of the logging event. The + category conversion specifier can be optionally followed by + NameAbbreviator pattern. + +

For example, for the category name "alpha.beta.gamma" the pattern + %c{2} will output the last two elements ("beta.gamma"), + %c{-2} will remove two elements leaving "gamma", + %c{1.} will output "a.b.gamma". + +

WARNING Generating the caller class information is + slow. Thus, its use should be avoided unless execution speed is + not an issue. + +

d Used to output the date of + the logging event. The date conversion specifier may be + followed by a set of braces containing a + date and time pattern strings {@link java.text.SimpleDateFormat}, + ABSOLUTE, DATE or ISO8601 + and a set of braces containing a time zone id per + {@link java.util.TimeZone#getTimeZone(String)}. + For example, %d{HH:mm:ss,SSS}, + %d{dd MMM yyyy HH:mm:ss,SSS}, + %d{DATE} or %d{HH:mm:ss}{GMT+0}. If no date format specifier is given then + ISO8601 format is assumed. +
FUsed to output the file name where the logging request was + issued. + +

WARNING Generating caller location information is + extremely slow and should be avoided unless execution speed + is not an issue. + +

lUsed to output location information of the caller which generated + the logging event. + +

The location information depends on the JVM implementation but + usually consists of the fully qualified name of the calling + method followed by the callers source the file name and line + number between parentheses. + +

The location information can be very useful. However, its + generation is extremely slow and should be avoided + unless execution speed is not an issue. + +

LUsed to output the line number from where the logging request + was issued. + +

WARNING Generating caller location information is + extremely slow and should be avoided unless execution speed + is not an issue. + +

mUsed to output the application supplied message associated with + the logging event.
MUsed to output the method name where the logging request was + issued. + +

WARNING Generating caller location information is + extremely slow and should be avoided unless execution speed + is not an issue. + +

nOutputs the platform dependent line separator character or + characters. + +

This conversion character offers practically the same + performance as using non-portable line separator strings such as + "\n", or "\r\n". Thus, it is the preferred way of specifying a + line separator. + + +

pUsed to output the priority of the logging event.
rUsed to output the number of milliseconds elapsed since the construction + of the layout until the creation of the logging event.
tUsed to output the name of the thread that generated the + logging event.
xUsed to output the NDC (nested diagnostic context) associated + with the thread that generated the logging event. +
X + +

Used to output the MDC (mapped diagnostic context) associated + with the thread that generated the logging event. The X + conversion character can be followed by the key for the + map placed between braces, as in %X{clientNumber} where + clientNumber is the key. The value in the MDC + corresponding to the key will be output. If no additional sub-option + is specified, then the entire contents of the MDC key value pair set + is output using a format {{key1,val1},{key2,val2}}

+ +

See {@link MDC} class for more details. +

+ +
properties +

Used to output the Properties associated + with the logging event. The properties + conversion word can be followed by the key for the + map placed between braces, as in %properties{application} where + application is the key. The value in the Properties bundle + corresponding to the key will be output. If no additional sub-option + is specified, then the entire contents of the Properties key value pair set + is output using a format {{key1,val1},{key2,val2}}

+
throwable +

Used to output the Throwable trace that has been bound to the LoggingEvent, by + default this will output the full trace as one would normally + find by a call to Throwable.printStackTrace(). + %throwable{short} or %throwable{1} will output the first line of + stack trace. throwable{none} or throwable{0} will suppress + the stack trace. %throwable{n} will output n lines of stack trace + if a positive integer or omit the last -n lines if a negative integer. + If no %throwable pattern is specified, the appender will take + responsibility to output the stack trace as it sees fit.

+
%The sequence %% outputs a single percent sign. +
+ +

By default the relevant information is output as is. However, + with the aid of format modifiers it is possible to change the + minimum field width, the maximum field width, justification + and truncation. + +

The optional format modifier are placed between the percent sign + and the conversion character. + +

The left justification flag, the minus sign (-), + the right truncation flag, the exclamation mark (!), + or any combination appear first. Followed by the + optional minimum field width modifier. This is a decimal + constant that represents the minimum number of characters to + output. If the data item requires fewer characters, it is padded on + either the left or the right until the minimum width is + reached. The default is to pad on the left (right justify) but you + can specify right padding with the left justification flag. The + padding character is space. If the data item is larger than the + minimum field width, the field is expanded to accommodate the + data. The value is never truncated. + +

This behavior can be changed using the maximum field + width modifier which is designated by a period followed by a + decimal constant. If the data item is longer than the maximum + field, then the extra characters are removed from the + beginning of the data item and not from the end. For + example, it the maximum field width is eight and the data item is + ten characters long, then the first two characters of the data item + are dropped. This behavior deviates from the printf function in C + where truncation is done from the end. The right truncation flag, + described previously, will override this behavior. + +

Below are various format modifier examples for the category + conversion specifier. + +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Format modifier + left justify + minimum width + maximum width + comment + +
%20cfalse20noneLeft pad with spaces if the category name is less than 20 + characters long. + +
%-20c true 20 none Right pad with + spaces if the category name is less than 20 characters long. + +
%.30cNAnone30Truncate from the beginning if the category name is longer than 30 + characters. + +
%!.30cNAnone30Truncate from the end if the category name is longer than 30 + characters. + +
%20.30cfalse2030Left pad with spaces if the category name is shorter than 20 + characters. However, if category name is longer than 30 characters, + then truncate from the beginning. + +
%-20.30ctrue2030Right pad with spaces if the category name is shorter than 20 + characters. However, if category name is longer than 30 characters, + then truncate from the beginning. + +
+ +

Below are some examples of conversion patterns. + +

+ +

%r [%t] %-5p %c %x - %m%n +

This is essentially the TTCC layout. + +

%-6r [%15.15t] %-5p %30.30c %x - %m%n + +

Similar to the TTCC layout except that the relative time is + right padded if less than 6 digits, thread name is right padded if + less than 15 characters and truncated if longer and the category + name is left padded if shorter than 30 characters and truncated if + longer. + +
+ +

The above text is largely inspired from Peter A. Darnell and + Philip E. Margolis' highly recommended book "C -- a Software + Engineering Approach", ISBN 0-387-97389-3. + + @author James P. Cakalic + @author Ceki Gülcü + + + @since 1.2.16 */ +public class EnhancedPatternLayout extends Layout { + /** Default pattern string for log output. Currently set to the + string "%m%n" which just prints the application supplied + message. */ + public static final String DEFAULT_CONVERSION_PATTERN = "%m%n"; + + /** A conversion pattern equivalent to the TTCCCLayout. + Current value is %r [%t] %p %c %x - %m%n. */ + public static final String TTCC_CONVERSION_PATTERN = + "%r [%t] %p %c %x - %m%n"; + + /** + * Initial size of internal buffer, no longer used. + * @deprecated since 1.3 + */ + protected final int BUF_SIZE = 256; + + /** + * Maximum capacity of internal buffer, no longer used. + * @deprecated since 1.3 + */ + protected final int MAX_CAPACITY = 1024; + + /** + * Customized pattern conversion rules are stored under this key in the + * {@link org.apache.log4j.spi.LoggerRepository LoggerRepository} object store. + */ + public static final String PATTERN_RULE_REGISTRY = "PATTERN_RULE_REGISTRY"; + + + /** + * Initial converter for pattern. + */ + private PatternConverter head; + + /** + * Conversion pattern. + */ + private String conversionPattern; + + /** + * True if any element in pattern formats information from exceptions. + */ + private boolean handlesExceptions; + + /** + Constructs a EnhancedPatternLayout using the DEFAULT_LAYOUT_PATTERN. + + The default pattern just produces the application supplied message. + */ + public EnhancedPatternLayout() { + this(DEFAULT_CONVERSION_PATTERN); + } + + /** + * Constructs a EnhancedPatternLayout using the supplied conversion pattern. + * @param pattern conversion pattern. + */ + public EnhancedPatternLayout(final String pattern) { + this.conversionPattern = pattern; + head = createPatternParser( + (pattern == null) ? DEFAULT_CONVERSION_PATTERN : pattern).parse(); + if (head instanceof BridgePatternConverter) { + handlesExceptions = !((BridgePatternConverter) head).ignoresThrowable(); + } else { + handlesExceptions = false; + } + } + + /** + * Set the ConversionPattern option. This is the string which + * controls formatting and consists of a mix of literal content and + * conversion specifiers. + * + * @param conversionPattern conversion pattern. + */ + public void setConversionPattern(final String conversionPattern) { + this.conversionPattern = + OptionConverter.convertSpecialChars(conversionPattern); + head = createPatternParser(this.conversionPattern).parse(); + if (head instanceof BridgePatternConverter) { + handlesExceptions = !((BridgePatternConverter) head).ignoresThrowable(); + } else { + handlesExceptions = false; + } + } + + /** + * Returns the value of the ConversionPattern option. + * @return conversion pattern. + */ + public String getConversionPattern() { + return conversionPattern; + } + + + /** + Returns PatternParser used to parse the conversion string. Subclasses + may override this to return a subclass of PatternParser which recognize + custom conversion characters. + + @since 0.9.0 + */ + protected org.apache.log4j.helpers.PatternParser createPatternParser(String pattern) { + return new org.apache.log4j.pattern.BridgePatternParser(pattern); + } + + + /** + Activates the conversion pattern. Do not forget to call this method after + you change the parameters of the EnhancedPatternLayout instance. + */ + public void activateOptions() { + // nothing to do. + } + + + /** + * Formats a logging event to a writer. + * @param event logging event to be formatted. + */ + public String format(final LoggingEvent event) { + StringBuffer buf = new StringBuffer(); + for(PatternConverter c = head; + c != null; + c = c.next) { + c.format(buf, event); + } + return buf.toString(); + } + + /** + * Will return false if any of the conversion specifiers in the pattern + * handles {@link Exception Exceptions}. + * @return true if the pattern formats any information from exceptions. + */ + public boolean ignoresThrowable() { + return !handlesExceptions; + } +}