APPENDIX A ■ ■ ■ The log4j Configuration Parameters Table A-1 presents all the configurable components in log4j and the configurable parameters associated with each component. Table A-1. Log4j Framework Configuration Component Configuration Parameters log4j Renderer Appender Logger Root LoggerFactory (CategoryFactory) Renderer RenderedClass RenderingClass Appender ErrorHandler Param Layout Filter Appender-ref Name Class Layout Param Class Filter Param Class ErrorHandler Param Root-ref Logger-ref Appender-ref Class Level Param Class Value Logger Name Class Additivity (true|false); default true 187 188 APPENDIX A ■ THE LOG4J CONFIGURATION PARAMETERS Table A-2 presents all the Appender objects and their configurable parameters. Table A-2. Log4j Appenders and Their Configuration Parameters Appender Configuration Parameters ConsoleAppender ImmediateFlush Encoding Threshold Target Name Layout ErrorHandler FileAppender ImmediateFlush Encoding Threshold Filename FileAppend BufferedIO BufferSize Name Layout ErrorHandler RollingFileAppender All properties of FileAppender MaxFileSize MaxBackupIndex JDBCAppender BufferSize Driver Layout User Password URL SQL Name ErrorHandler JMSAppender InitialContextFactoryName LocationInfo Username Password ProviderURL SecurityCredentials SecurityPrincipalName TopicBindingName TopicConnectionFactoryBindingName URLPkgPrefixes Name Layout ErrorHandler SocketAppender LocationInfo Port ReconnectionDelay RemoteHost Name ErrorHandler Layout APPENDIX A ■ THE LOG4J CONFIGURATION PARAMETERS 189 Appender Configuration Parameters NTEventLogAppender Source Name Layout ErrorHandler SMTPAppender BufferSize EvaluatorClass From To LocationInfo SMTPHost Subject Name Layout ErrorHandler TelnetAppender Port Name Layout ErrorHandler Table A-3 presents all the Layout objects and their configurable parameters. Table A-3. Log4j Layouts and Their Configuration Parameters Layout Configuration Parameters TTCCLayout CategoryPrefixing ContextPrinting ThreadPrinting HTMLLayout LocationInfo Title PatternLayout ConversionPattern APPENDIX B ■ ■ ■ The log4j DTD Listing B-1 presents the complete Document Type Definition (DTD) for the log4j configuration. Listing B-1. The log4j DTD <?xml version="1.0" encoding="UTF-8" ?> <!-- Version: 1.2 --> <!-- A configuration element consists of optional renderer elements,appender elements, categories and an optional root element. --> <!ELEMENT log4j:configuration (renderer*, appender*,(category|logger)*,root?, categoryFactory?)> <!ATTLIST log4j:configuration xmlns:log4j CDATA #FIXED "http://jakarta.apache.org/log4j/" threshold (all|debug|info|warn|error|fatal|off|null) "null" debug (true|false|null) "null"> <!-- renderer elements allow the user to customize the conversion of --> <!-- message objects to String. --> <!ELEMENT renderer EMPTY> <!ATTLIST renderer renderedClass CDATA #REQUIRED renderingClass CDATA #REQUIRED> <!-- Appenders must have a name and a class. --> <!-- Appenders may contain an error handler, a layout, optional parameters --> <!-- and filters. They may also reference (or include) other appenders. --> 191 192 APPENDIX B ■ THE LOG4J DTD <!ELEMENT appender (errorHandler?, param*, layout?, filter*, appender-ref*)> <!ATTLIST appender name ID #REQUIRED class CDATA #REQUIRED> <!ELEMENT layout (param*)> <!ATTLIST layout class CDATA #REQUIRED> <!ELEMENT filter (param*)> <!ATTLIST filter class CDATA #REQUIRED> <!-- ErrorHandlers can be of any class. They can admit any number of --> <!-- parameters. --> <!ELEMENT errorHandler (param*, root-ref?, logger-ref*, appender-ref?)> <!ATTLIST errorHandler class CDATA #REQUIRED > <!ELEMENT root-ref EMPTY> <!ELEMENT logger-ref EMPTY> <!ATTLIST logger-ref ref IDREF #REQUIRED> <!ELEMENT param EMPTY> <!ATTLIST param name CDATA #REQUIRED value CDATA #REQUIRED> <!-- The priority class is org.apache.log4j.Level by default --> <!ELEMENT priority (param*)> <!ATTLIST priority class CDATA #IMPLIED value CDATA #REQUIRED> <!-- The level class is org.apache.log4j.Level by default --> <!ELEMENT level (param*)> <!ATTLIST level class CDATA #IMPLIED value CDATA #REQUIRED> APPENDIX B ■ THE LOG4J DTD 193 <!-- If no level element is specified, then the configurator MUST not --> <!-- touch the level of the named category. --> <!ELEMENT category (param*,(priority|level)?,appender-ref*)> <!ATTLIST category class CDATA #IMPLIED name CDATA #REQUIRED additivity (true|false) "true" > <!-- If no level element is specified, then the configurator MUST not --> <!-- touch the level of the named logger. --> <!ELEMENT logger (level?,appender-ref*)> <!ATTLIST logger name ID #REQUIRED additivity (true|false) "true" > <!ELEMENT categoryFactory (param*)> <!ATTLIST categoryFactory class CDATA #REQUIRED> <!ELEMENT appender-ref EMPTY> <!ATTLIST appender-ref ref IDREF #REQUIRED> <!-- If no priority element is specified, then the configurator MUST not --> <!-- touch the priority of root. --> <!-- The root category always exists and cannot be subclassed. --> <!ELEMENT root (param*, (priority|level)?, appender-ref*)> <!-- ==================================================================== --> <!-- A logging event --> <!-- ==================================================================== --> <!ELEMENT log4j:eventSet (log4j:event*)> <!ATTLIST log4j:eventSet xmlns:log4j CDATA #FIXED "http://jakarta.apache.org/log4j/" version (1.1|1.2) "1.2" includesLocationInfo (true|false) "true"> <!ELEMENT log4j:event (log4j:message, log4j:NDC?, log4j:throwable?, log4j:locationInfo?) > 194 APPENDIX B ■ THE LOG4J DTD <!-- The timestamp format is application dependent. --> <!ATTLIST log4j:event logger CDATA #REQUIRED level CDATA #REQUIRED thread CDATA #REQUIRED timestamp CDATA #REQUIRED> <!ELEMENT log4j:message (#PCDATA)> <!ELEMENT log4j:NDC (#PCDATA)> <!ELEMENT log4j:throwable (#PCDATA)> <!ELEMENT log4j:locationInfo EMPTY> <!ATTLIST log4j:locationInfo class CDATA #REQUIRED method CDATA #REQUIRED file CDATA #REQUIRED line CDATA #REQUIRED > Index ■Special Characters Appender objects % conversion character, 93 AsyncAppender class %-10c format modifier, Pattern Layout class, overview, 51–52 93 sample use of, 52–53 %-20.30c format modifier, Pattern Layout ConsoleAppender class class, 93 example, 40–41 %.20c format modifier, Pattern Layout class, overview, 40 93 properties of, 40 %c format, 168 DailyRollingFileAppender class, 46–48 %m%n conversion pattern, 14–15, 17, 19 FileAppender class %p sign, 17 overview, 41 %x conversion pattern, 33 properties of, 41–42 ‰CE level, 135–40, 143–44, 170–73 sample configuration of, 42–43 file-based logging example, 48–50 ■A JDBCAppender class ABSOLUTE format, DateLayout Class, 85 configuring, 54–55 abstract keyword, 77, 79, 85, 92, 170 creating table for storing logging activateOptions( ) method, Appender class, information, 55 116–17, 120 overview, 53–54 activation.jar file, 10, 65 sample configuration for, 55–56 addAppender( ) method, Appender class, 37 JMSAppender class additivity property, 18, 25, 30, 37 example, 67–71 ALL level, 10, 23 and log4j, 58–60 Apache log tag library, 163 overview, 57 creating custom tags with, 170–73 Point-to-Point messaging, 57 description of log tags, 168–69 Publish-Subscribe messaging, 58 example using NTEventLogAppender class, 62–63 configuration file for log tag library, overview, 35 165–66 properties of log example in action, 167 adding appenders to loggers, 37 overview, 164–65 logger-to-appender collaboration, setting environment, 166–67 38 installing, 164 overview, 36–37 using custom logger with log tag library, RollingFileAppender class 167–68 overview, 43 what a tag is, 163 properties of, 43–44 Apache log4j, 4, 6–7, 175, 186 sample configuration of, 45–46 API (Application Programming Interface), 1, useful operations in, 44 4, 6–7, 9–10, 57, 78, 89, 130, 175 sending log messages to database, 74 append( ) method, 38, 39, 120 sending logging information to remote append property, 50 destinations, 53 Appender class, 10–13, 23–25, 28, 34, 37–39, SMTPAppender class, 63–65 48, 51, 53, 57, 63, 74–75, 77–78, 85, 89, SocketAppender class 91, 115–17, 122–23, 134, 137, 152, configuring, 61–62 182–85 example, 71–73 Appender component, 187 fault tolerance, 61 overview, 60–61 195 196 ■INDEX TelnetAppender class, 65 ConsoleAppender class, 10, 15, 17–19, 51, 74, thread-safety in log4j, 38 81, 94, 123, 134, 166, 188 WriterAppender class example, 40–41 overview, 38–39 overview, 40 properties of, 39 properties of, 40 variations of, 40 contentType property, HTMLLayout class, 86 APPENDER_DEF table, 123, 134 contextPrinting property, TTTCLayout class, AppenderAttachable class, 51 83–84 AppenderSkeleton class, 38–39, 42, 51, conversionPattern property, PatternLayout 116 class, 92 Application Programming Interface (API), custom logging 1, 4, 6–7, 9–10, 57, 78, 89, 130, 175 configuring log4j from database ASYNC appender, 51 database table design for storing logging AsyncAppender class, 15–16, 180 information, 123 overview, 51–52 database-based configuration example, sample use of, 52–53 133–35 asynchronous logging, 180 overview, 122 async.xml file, 52 reading configuration information from database via configuration loader, ■B 123–30 BasicConfigurator class, 19 writing configuration class, 130–33 BEA WebLogic application server, 58 custom WindowAppender class BodyTagSupport class, 170 architecture, 116–17 bufferedIO property, FileAppender class, 42 bottlenecks, 116 bufferSize property features of, 116 FileAppender class, 42 implementing, 117–20 JDBCAppender class, 55 overview, 115 testing, 120–22 ■C framework C conversion character, 92 creating custom level