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

191 192 APPENDIX B ■ THE LOG4J DTD

APPENDIX B ■ THE LOG4J DTD 193

194 APPENDIX B ■ THE LOG4J DTD

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 class, 135–36 C language, 4 creating custom logger, 137 category attribute, 167–69 generating custom logger factory object, Category class, 10, 26 137–38 categoryPrefixing property, TTCCLayout overview, 135 class, 83 simpler approach to using custom level close( ) method class, 140–44 Appender class, 89 using custom logging components, JDBCAppender class, 54 138–40 JMSAppender class, 71 overview, 115 SocketAppender class, 61 why custom logging components needed, closeWriter( ) method, WriterAppender class, 115 40 writing custom layout, 144–47 Commons logging API, 6–7 customappender.properties file, 122 configuration issues, 181–82 CustomLogger class, 138–39 Configurator class, 20, 131 CustomLoggerFactory class, 139 Configurator interface, 16, 131, 133 customlogger.properties file, 139 configureAndWatch( ) method, 20, 23, 185 configureAndWatch property, 182 ■D configuring log4j d conversion character, 92 naming and placing configuration file, DAILY appender, 50 12–13 daily.log file, 50 overview, 12 DailyRollingFileAppender, 90 what can be configured, 13–15 DailyRollingFileAppender class, 46–48, 50, 74, XML-style configuration, 15 123 Connection object, 58 dateFormat property, DateLayout class, CONSOLE appender, 15 83–84 ■INDEX 197

DateLayout class, 80, 83 FATAL level, 10, 24 DateLayout Class, 85 fatal log tag, 169 DateLayout class, 179 FILE appender, 15, 50 DatePattern configuration parameter, 46 file_logging.properties file, 48–49 DBConfigLoader class, 132–33 fileAppend property, FileAppender class, 42 dbConfig.properties file, 134 FileAppender, 15, 40, 74, 86, 91, 160–61, 188 debug( ) method, Logger class, 30 overview, 41 DEBUG level, 10, 14–15, 17, 19, 23, 31, 56, properties of, 41–42 135–36, 166, 168, 172, 178 sample configuration of, 42–43 debug log tag, 168 Filename property, FileAppender class, 42 element, 165 FileWatchDog class, 20, 186 debugging, 3 Filter class, 11, 28, 35, 38–39, 115, 122–23, 155 decide( ) method, Filter class, 151, 180 Filter component, 15, 187 DefaultCategoryFactory class, 139 Filter control, 16 DefaultEvaluator class, 64 filter objects destroy( ) method, 89 comparing log4j with JDK logging API, 184 doAppend( ) method, Appender class, 38, 51 using, 180–81 doConfigure( ) method, Configurator class, filter property, Appender class, 37 131 filtering doLocalizedLogging( ) method, Logger class, filter chaining, 102–3 30 level-based filtering doLogging( ) method, Logger class, 30 overview, 96 DOMConfigurator class, 16, 19, 51, 130, 153, using LevelRangeFilter, 97–99 185 LevelMatchFilter, 99 doRender( ) method, 152 overview, 95–96 driver property, JDBCAppender class, 55 SelectedLevelFilter, 99–102 dump log tag, 169 StringMatchFilter, 99 format( ) method ■E Layout class, 78, 85, 92 EJB (Enterprise Java Beans), 158–60 MessageFormat class, 27 encoding property Formatter class, 182–84 ConsoleAppender class, 40 fqcn argument, 27 FileAppender class, 41 WriterAppender class, 39 ■G Enterprise Java Beans (EJB), 158–60 getContentType( ) method, Layout class, 79 error handling getFooter( ) method comparing log4j with JDK logging API, HTMLLayout class, 89 184–85 Layout class, 79 configuring ErrorHandler, 108–9 getHeader( ) method, Layout class, 79 ErrorCode interface, 106 getLogger(String) method, CustomLogger overview, 103, 105 class, 138 running the example, 109 getPriority( ) method, BodyTagSupport class, writing custom ErrorHandler, 106–7 170–71 ERROR level, 10, 24, 64–65, 133–35 getWindowInstance( ) method, 120 error log tag, 169 ErrorHandler class, 42, 184–85 ErrorHandler component, 187 ■H ErrorTag class, 170 Handler class, 182–84 evaluatorClass property, 63, 64 height property, 116 executeUpdate( ) method, Statement class, hierarchy, logger, 176–77 54 Hierarchy class, 31 HTMLLayout, 85–90, 189 ■F html.properties file, 86 F conversion character, 93 HTTP, 23 Factory class, 137, 139, 144 HttpWatchDog class, 186 198 ■INDEX

■I jdbc.properties file, 74 ignoresThrowable( ) method, Layout class, JDK (Java Development Kit), 6–7, 9, 175 78–79 JDK logging API, 6, 183–84, 186 immediateFlush property comparing with log4j ConsoleAppender class, 40 configuration options, 183 FileAppender class, 41 error handling, 184–85 WriterAppender class, 39 filter objects, 184 info( ) method, Logger class, 18, 23, 28, 30 formatting logging information, 183–84 INFO level, 10, 24, 31, 133, 135, 183 location information options, 184 info log tag, 168 overview, 182 element, 165 JMS (Java Message Service), 6, 9–10, 35, 57, InfoTag class, 170 59–61, 65, 67, 69–71, 75, 161, 182, 184 initialContextFactoryName property, jms_client.properties file, 71 JMSAppender class, 59 JMSAppender class, 60, 65, 75, 161, 188 initializing log4j example, 67–71 overview, 16 and log4j, 58–60 through VM parameters, 16–17 overview, 57 installing log4j, 9–10 Point-to-Point messaging, 57 isTraceEnabled( ) method, 143 Publish-Subscribe messaging, 58 jms.properties file, 71 ■J JMSReceiver class, 185 J2EE (Java 2 Platform, Enterprise Edition), 58, JNDI, 67 67, 71, 155 JNDI (Java Naming and Directory Interface), Jakarta Taglibs project, 163 10 Java 2 Platform, Enterprise Edition (J2EE), 58, JNDIContext class, 58, 67 67, 71, 155 jndi.properties file, 58 Java Activation API, 65 JNI (Java Native Interface), 62 Java Database Connectivity (JDBC), 9 Joran configurator, 185 Java Development Kit. See JDK JScrollPane class, 120 Java Development Kit (JDK), 6–7, 9, 175 JSP (Java Server Pages), 163–69, 171–73 Java Mail API, 10 JTextArea class, 120 Java Message Service (JMS), 6, 9–10, 35, 57, JVM (Java Virtual Machine), 61, 158, 161 59–61, 65, 67, 69–71, 75 ■ Java Naming and Directory Interface (JNDI), L 10 l conversion character, 93 Java Native Interface (JNI), 62 Layout class, 10–13, 24, 28, 32, 61, 77, 79–80, Java Servlet, 181 83, 85, 89, 91–92, 94, 115, 120, 122, Java Virtual Machine (JVM), 61, 158, 161 144, 152, 179, 182–83 Java-based logging APIs, 6–7 Layout component, 187 JavaBeans Activation Framework, 10 layout property JavaMail API, 65 Appender class, 37 JavaServer Pages (JSP), 163–69, 171–73 JDBCAppender class, 55 java.sql package, 54 Level class, 10–12, 23–24, 25–28, 122, 182 java.util.logging package, 6 Level component, 187 JAXP, 9 level property, Appender class, 37 JBoss Server, 59 level-based filtering JDBC, 53, 74 overview, 96 JDBC (Java Database Connectivity), 9 using LevelRangeFilter, 97–99 JDBCAppender class, 56–57, 74, 75, 123, 134, LevelMatchFilter, 99 188 LevelRangeFilter, 97–99 configuring, 54–55 localization issues, 179 creating table for storing logging location information information, 55 options, comparing log4j with JDK logging overview, 53–54 API, 184 sample configuration for, 55–56 using, 179 ■INDEX 199 locationInfo property overview, 157 HTMLLayout class, 86 thread-safety in, 38 JMSAppender class, 59 WebLogic class loaders, 158–59 SocketAppender class, 62 when does not work, 159–60 log messages, rendering of why logging is difficult in J2EE, 157–58 difference from formatting, 114 working on its own, 161 ObjectRenderer class, 113 log4j component, 187 configuring ObjectRenderer, 112 log4j.configuration property, 16 custom Renderer example, 109–12 log4j.dtd file, 90 overview, 109 log4j.jar file, 159 LOG_DEBUG level, 135–36 log4j.properties configuration file, 12, 14, log4j 20–23, 30–31, 33 architecture of, 10, 12 log4j.properties file, 131, 165–67, 172, 182 comparing with JDK logging API log4j.xml file, 12, 131, 167, 182 configuration options, 183 logger, obtaining, 175–76 error handling, 184–85 Logger class, 10–11, 13, 17–19, 23, 26–28, filter objects, 184 30–31, 35, 37, 51, 65, 77, 81, 92, formatting logging information, 183–84 115–16, 120, 122, 131, 134, 138–40, location information options, 184 143–44, 149, 159, 161, 166, 182–84, overview, 182 187 configuring conditions of successful logging, 28 dynamic loading of configuration, 19–20 configuration methods, 28 naming and placing configuration file, example, 29–31 12–13 how to obtain loggers, 25–26 overview, 12 logging information, 26–28 programmatically, 19 overview, 24–25 in Web applications, 20–23 LOGGER_REPOSITORY table, 123, 134 what can be configured, 13–15 LoggerFactory class, 140, 144 XML-style configuration, 15 LoggerFactory interface, 138 creating configuration file logger.info( ) method, 81 overview, 17–18 LoggerTag class, 170–71 running the program, 18 loggerWrapper.properties file, 144 DTD, 191–94 logging. See also custom logging formatting logging information in advantages of, 3 date-DateLayout, 85 disadvantages of, 3–4 HTMLLayout, 85–90 formatting logging information, 179 layout hierarchy, 77–78 how works, 4–5 layout objects, 78–79 what it is, 1–2 overview, 77 logging packages, evaluating, 6 PatternLayout, 92–94 LoggingEvent class, 38, 51, 61, 69–70, 72, SimpleLayout, 79 78–80, 82, 85, 90, 92 XMLLayout, 90–91 LoggingRepository class, 185 JMSAppender class, 58–60 LoggingServlet class, 22 Level class, 23–24 LogManager class, 11–12, 16, 26, 31–32, 54, Logger class 61, 71, 89, 131, 133 conditions of successful logging, 28 LogMessageListener class, 68, 69–70 configuration methods, 28 log.out file, 46 example, 29–31 logtags.log file, 168 how to obtain loggers, 25–26 logging information, 26–28 ■M overview, 24–25 m conversion character, 93 LogManager class, 31–32 maxBackupIndex property, making work in J2EE, 160–61 RollingFileAppender class, 44 Message Diagnostic Context (MDC), 32–33 maxFileSize property, RollingFileAppender Nested Diagnostic Context (NDC), 32 class, 44 200 ■INDEX

MDC (Message Diagnostic Context), 32–33, PropertyConfigurator class, 16, 19, 23, 124, 93 132–33 MDCMatchFilter filter, 186 providerURL property, JMSAppender class, 59 message attribute, 169 Publish-Subscribe messaging, 58 Message Diagnostic Context (MDC), 32–33, 93 ■Q MessageFormat class, 27 QuietWriter class, 42 MessageListener class, 69 MessageMatchFilter filter, 186 ■R Model-View-Controller (MVC), 163 r conversion character, 93 MVC (Model-View-Controller), 163 reconnectionDelay property, SocketAppender class, 62 ■N RELATIVE format n conversion character, 93 DateFormat class, 84, 93 NDC (Nested Diagnostic Context), 32–33, 56, DateLayout class, 85 61, 66, 80–81, 84, 86, 90, 93, 181 remoteHost property, SocketAppender class, NDCMatchFilter filter, 186 62 NTEventLogAppender class, 62–63, 189 remove( ) method, NDC class, 32 NTEventLogAppender.dll file, 62 Renderer class, 123, 155, 180 NULL format, DateLayout Class, 85 Renderer component, 187 rendering of log messages ■O difference from formatting, 114 ObjectMessage class, 69 ObjectRenderer, 113 ObjectRenderer class, 11, 16, 28, 78, 113 configuring ObjectRenderer, 112 configuring, 112 custom Renderer example, 109–12 custom Renderer example, 109–12 overview, 109 overview, 109 requiresLayout( ) method, WindowAppender OFF level, 10, 24 class, 120 OnlyOnceErrorHandler class, 184 Resource Adapter, 158 OnlyOnceErrorHandler interface, 42 ResourceBundle class, 25, 27, 30, 179 onMessage( ) method, MessageListener class, ROLLING appender, 50 69 RollingFileAppender class, 74, 166, 168, 188 OptionConverter class, 131, 133 overview, 43 org.apache.log4j.helpers package, 20, 42, 80 properties of, 43–44 org.apache.log4j.net package, 58, 61–63, 65 sample configuration of, 45–46 org.apache.log4j.spi package, 16, 38, 42, 51 useful operations in, 44 out.log file, 50 rolling.log file, 50 OutputStream class, 38–39 rollOver( ) method, RollingFileAppender class, 44 ■P run( ) method, 32, 73 p conversion character, 93 RunTimeException class, 184 password property JDBCAppender class, 55 ■S JMSAppender class, 59 SAX (Simple API for XML), 185 PatternLayout, 14, 51, 56, 92–94, 144, 166, scope attribute, 169 179, 183–84, 189 securityCredentials property, JMSAppender plug-ins, log4j 1.3 class, 59 overview, 185 securityPrincipalName property, receivers, 185 JMSAppender class, 59 watchdogs, 185–86 SelectedLevelFilter, 99–102 Point-to-Point messaging, 57 set( ) method, 116 port property, SocketAppender class, 62 setAdditivity( ) method, 37 printf( ) command, 4 setMaxBackupIndex ( ) method, println( ) method, System class, 4 RollingFileAppender class, 44 Priority class, 10, 23, 26–27 setMaxFileSize( ) method, Properties class, 124, 132 RollingFileAppender class, 44 ■INDEX 201 setWriter( ) method, HTMLLayout class, FileAppender class, 41 89 WriterAppender class, 39 shutdown( ) method, LogManager class, timeZone property, DateLayout class, 83 54, 61, 71, 89 title property, HTMLLayout class, 86 Simple API for XML (SAX), 185 to attribute, 64 Simple Mail Transfer Protocol (SMTP), 63, 64, to property, 64 75, 182 TOMCAT classpath, 167 SimpleDateFormat class, 46, 92 Tomcat server, 20–22, 164, 167 SimpleFormatter class, 183 tomcat.bat file, 21, 166, 172 SimpleLayout, 63–64, 79, 80 topicBindingName configuration item, 67 SMTPAppender class, 63–65, 75, 189 topicBindingName property, JMSAppender SMTPHost property, 64 class, 59 SocketAppender class, 65, 75, 161, 188 topicConnectionFactoryBindingName configuring, 61–62 configuration item, 67 example, 71–73 topicConnectionFactoryBindingName fault tolerance, 61 property, JMSAppender class, 60 overview, 60–61 trace( ) method, CustomLogger class, 138 SocketReceiver class, 185 trace tag, 172 SQL, 53–56, 124, 134 TTCCLayout class, 85, 189 static keyword, 117, 131 configuring programmatically, 81–83 String class, 11, 78, 81, 149, 152, 178, 180 configuring via configuration file, 83–84 StringBuffer class, 178 mandatory information, 80 StringMatchFilter, 99 overview, 80 subAppend( ) method, RollingFileAppender ttcc.properties file, 83 class, 44 subject attribute, 64 ■U subject property, 64 UNIX operating system, 15, 20, 43, 115 synchronized keyword, 31, 51, 117, 120 UNIX Syslog, 6, 135 SysLogAppender class, 135 UNIX Syslogs, 184 syslog.h file, 135 UnsatisfiedLinkError class, 62 System class, 4 UPDATE statement, 54 system classpath, 161 URL (Uniform Resource Locator), 122, 131 System.err stream, 40, 42 URL property, JDBCAppender class, 55 System.out stream, 17, 40, 82 URLPkgPrefixes property, JMSAppender class, 60 ■T user property, JDBCAppender class, 55 t conversion character, 93 user.home path, 15, 49–50 element, 164 username property, JMSAppender class, taglib-descriptor file, 170 60 taglibs-log.jar file, 164, 172 taglibs-log.tld file, 164, 171–72 ■V tail utility, 115 VM parameters, log4j initialization through, target property 16–17 Appender class, 37 ConsoleAppender class, 40 ■W WriterAppender class, 39 warn( ) method, Logger class, 30 TCP/IP, 60–61, 176 WARN level, 10, 24, 28 Telnet, 182 warn log tag, 169 TelnetAppender class, 65, 75, 189 Web applications, configuring log4j in, testing WindowAppender, custom, 120–22 20–23 threadPrinting property, TTTCLayout class, webapps directory, 166 83–84 WEB-INF directory, 166 thread-safety in log4j, 38 WebLogic application server, 158–59, 161 threshold property WebLogic class loaders, 158–59 Appender class, 37 web.xml file, 21, 164 ConsoleAppender class, 40 width property, 116 202 ■INDEX

WindowAppender class, custom ■X architecture, 116–17 x conversion character, 93 bottlenecks, 116 XML, 2, 6, 9, 12, 16, 37, 45, 51, 56, 75, 84, features of, 116 87–88, 90–91, 94, 122, 131, 139, 153, implementing, 115, 117–20 155, 179, 181–83, 185 testing, 120–22 XMLFormatter class, 183 Windows operating system, 20 XMLLayout class, 90–91, 92 Writer class, 38–39, 42 xmlLayout.xml file, 91 WriterAppender class, 42 overview, 38–39 properties of, 39 variations of, 40