dev/logging.html - tomee-site-pub - Git at Google

 <!DOCTYPE html>
 <html lang="en">

 <head>
 	<meta charset="UTF-8">
 	<meta http-equiv="X-UA-Compatible" content="IE=edge">
 	<meta name="viewport" content="width=device-width, initial-scale=1">
 	<title>Apache TomEE</title>
 	<meta name="description"
 		  content="Apache TomEE is a lightweight, yet powerful, JavaEE Application server with feature rich tooling." />
 	<meta name="keywords" content="tomee,asf,apache,javaee,jee,shade,embedded,test,junit,applicationcomposer,maven,arquillian" />
 	<meta name="author" content="Luka Cvetinovic for Codrops" />
 	<link rel="icon" href="../favicon.ico">
 	<link rel="icon"  type="image/png" href="../favicon.png">
 	<meta name="msapplication-TileColor" content="#80287a">
 	<meta name="theme-color" content="#80287a">
 	<link rel="stylesheet" type="text/css" href="../css/normalize.css">
 	<link rel="stylesheet" type="text/css" href="../css/bootstrap.css">
 	<link rel="stylesheet" type="text/css" href="../css/owl.css">
 	<link rel="stylesheet" type="text/css" href="../css/animate.css">
 	<link rel="stylesheet" type="text/css" href="../fonts/font-awesome-4.1.0/css/font-awesome.min.css">
 	<link rel="stylesheet" type="text/css" href="../fonts/eleganticons/et-icons.css">
 	<link rel="stylesheet" type="text/css" href="../css/jqtree.css">
 	<link rel="stylesheet" type="text/css" href="../css/idea.css">
 	<link rel="stylesheet" type="text/css" href="../css/cardio.css">

 	<script type="text/javascript">
 		<!-- Matomo -->
 		var _paq = window._paq = window._paq || [];
 		/* tracker methods like "setCustomDimension" should be called before "trackPageView" */
 		/* We explicitly disable cookie tracking to avoid privacy issues */
 		_paq.push(['disableCookies']);
 		_paq.push(['trackPageView']);
 		_paq.push(['enableLinkTracking']);
 		(function () {
 			var u = "//matomo.privacy.apache.org/";
 			_paq.push(['setTrackerUrl', u + 'matomo.php']);
 			_paq.push(['setSiteId', '5']);
 			var d = document, g = d.createElement('script'), s = d.getElementsByTagName('script')[0];
 			g.async = true;
 			g.src = u + 'matomo.js';
 			s.parentNode.insertBefore(g, s);
 		})();
 		<!-- End Matomo Code -->
     </script>
 </head>

 <body>
     <div class="preloader">
 		<img src="../img/loader.gif" alt="Preloader image">
 	</div>
 	    <nav class="navbar">
 		<div class="container">
 		  <div class="row">          <div class="col-md-12">

 			<!-- Brand and toggle get grouped for better mobile display -->
 			<div class="navbar-header">
 				<button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#bs-example-navbar-collapse-1">
 					<span class="sr-only">Toggle navigation</span>
 					<span class="icon-bar"></span>
 					<span class="icon-bar"></span>
 					<span class="icon-bar"></span>
 				</button>
 				<a class="navbar-brand" href="/" title="Apache TomEE">
 				    <span>


                         <img
 							src="../img/apache_tomee-logo.svg"
 							onerror="this.src='../img/apache_tomee-logo.jpg'"
 							height="50"
 							>


                     </span>
                 </a>
 			</div>
 			<!-- Collect the nav links, forms, and other content for toggling -->
 			<div class="collapse navbar-collapse" id="bs-example-navbar-collapse-1">
 				<ul class="nav navbar-nav navbar-right main-nav">
 					<li><a href="../docs.html">Documentation</a></li>
 					<li><a href="../community/index.html">Community</a></li>
 					<li><a href="../security/security.html">Security</a></li>
 					<li><a class="btn btn-accent accent-orange no-shadow" href="../download.html">Downloads</a></li>
 				</ul>
 			</div>
 			<!-- /.navbar-collapse -->
 		   </div></div>
 		</div>
 		<!-- /.container-fluid -->
 	</nav>


     <div id="main-block" class="container main-block">
         <div class="row title">
           <div class="col-md-12">
             <div class='page-header'>

               <h1>Logging</h1>
             </div>
           </div>
         </div>
         <div class="row">

             <div class="col-md-12">
                 <div class="sect1">
 <h2 id="_logging_for_users">Logging for Users</h2>
 <div class="sectionbody">
 <div class="paragraph">
 <p>All logging in OpenEJB is done using the openejb.base/conf/logging.properties file.
 When you download and extract OpenEJB, you will not find this file under the openejb.base/conf directory.
 However, when you start the server, this file magically appears.
 So what does this give you as a user of OpenEJB?
 Here are some of the benefits:</p>
 </div>
 <div class="olist arabic">
 <ol class="arabic">
 <li>
 <p>You do not have to author a logging.properties from scratch.
 You get one with sensible defaults.</p>
 </li>
 <li>
 <p>If you did modify the default file, and you wanted to revert back to the default file generated by OpenEJB, all you have to do is</p>
 </li>
 <li>
 <p></p>
 <div class="paragraph">
 <p>= Delete or rename the file e.g. rename it to logging.properties.BAK .</p>
 </div>
 </li>
 <li>
 <p></p>
 <div class="paragraph">
 <p>= Restart the server</p>
 </div>
 </li>
 </ol>
 </div>
 <div class="paragraph">
 <p>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
 OpenEJB will find that the logging.properties file is missing from the openejb.base/conf directory and it will automatically create a new one with the default configuration.
 The good thing is that if you modify the logging.properties file, OpenEJB will <strong>NOT</strong> over-write it.</p>
 </div>
 <div class="paragraph">
 <p>The default logging configuration created by OpenEJB uses RollingFileAppender&#8217;s.
 The log files are located under the openejb.base/logs directory.
 By default it writes to just two files , openejb.log and transaction.log&nbsp;
 {info:title=Embedded Testing} When running tests using embedded OpenEJB, the logging.properties will be ignored.
 You need to use a file named embedded.logging.properties instead.
 Place this file under src/test/resources {info}  <a name="Logging-Loggingforcontributors/committers"></a></p>
 </div>
 </div>
 </div>
 <div class="sect1">
 <h2 id="_logging_for_contributorscommitters">Logging for contributors/committers</h2>
 <div class="sectionbody">
 <div class="paragraph">
 <p>The org.apache.openejb.util.Logger class is the one which is used for logging.
 This class is a wrapper around log4.&nbsp;</p>
 </div>
 <div class="paragraph">
 <p><a name="Logging-LogCategory"></a></p>
 </div>
 <div class="sect2">
 <h3 id="_logcategory">LogCategory</h3>
 <div class="paragraph">
 <p>Each Logger instance belongs to a category represented by a org.apache.openejb.util.LogCategory instance.
 Here is what the LogCategory class looks like</p>
 </div>
 <div class="literalblock">
 <div class="content">
 <pre>public final class LogCategory {
   private final String name;
   public static final LogCategory OPENEJB = new LogCategory( "OpenEJB");
   public static final LogCategory OPENEJB_ADMIN = OPENEJB.createChild("admin");
   public static final LogCategory OPENEJB_STARTUP = OPENEJB.createChild("startup");
   public static final LogCategory OPENEJB_STARTUP_CONFIG = OPENEJB_STARTUP.createChild("config");
   public static final LogCategory OPENEJB_STARTUP_VALIDATION = OPENEJB_STARTUP.createChild("validation");
        // other categories removed for code brevity
   private LogCategory(String name){
     this.name = name;
   }
   public String getName() {
     return name;
   }
   /**
    * Creates a child category of this category. &lt;B&gt;Use this method sparingly&lt;/B&gt;. This method is to be used in only those circumstances where the name of the
    * category is not known upfront and is a derived name. If you know the name of the category, it is highly recommended to add a static final field
    * of type LogCategory in this class
    * @param child
    * @return - LogCategory
    */
   public LogCategory createChild(String child){
     return new LogCategory(this.name+"."+child);
   }

 }</pre>
 </div>
 </div>
 <div class="paragraph">
 <p>Notice carefully how each LogCategory instance is created.&nbsp;
 The objective here is that each LogCategory should be a child of the OPENEJB category.
 If you need to add a new category and you know the name of the category upfront, simply open the LogCategory class and add another category.
 For example, if you needed to add a category named SHUTDOWN, here is the recommended way to add it</p>
 </div>
 <div class="literalblock">
 <div class="content">
 <pre>public static final LogCategory OPENEJB_SHUTDOWN = LogCategory.OPENEJB.createChild("shutdown");</pre>
 </div>
 </div>
 <div class="paragraph">
 <p>Sometimes you may want to create a category whose name is "generated" at runtime.
 In that case you can use the "createChild" method of the LogCategory class to create this new category.&nbsp;
 For example, if you wanted to create a category of Logger for every deployed module, then assuming you have the moduleId information you could do something as follows to create a category:</p>
 </div>
 <div class="literalblock">
 <div class="content">
 <pre>String moduleId = "mymodule";
 LogCategory generatedCategory = LogCategory.OPENEJB.createChild(moduleId);</pre>
 </div>
 </div>
 <div class="paragraph">
 <p><a name="Logging-&nbsp;Logger"></a></p>
 </div>
 </div>
 <div class="sect2">
 <h3 id="_logger">&nbsp;Logger</h3>
 <div class="paragraph">
 <p>The preference is to externalize all logging messages in properties file.
 Typically each package should have a file called Messages.properties.&nbsp;
 This file should have all the keys and the corresponding messages.&nbsp;
 Here are the steps you would follow to log a message:</p>
 </div>
 <div class="ulist">
 <ul>
 <li>
 <p>For each message you need to log, you would open the Messages.properties file in the corresponding package and add a key-value pair for the message.&nbsp;
 For example, if you were authoring a class called org.apache.openejb.util.Connect, then you would add a key-value pair to the Messages.properties file located in the org.apache.openejb.util package.</p>
 </li>
 <li>
 <p>Obtain a Logger instance in one of the following ways:</p>
 </li>
 </ul>
 </div>
 <div class="paragraph">
 <p>&nbsp;&nbsp;&nbsp;
 &nbsp;&nbsp;&nbsp;
 &nbsp;&nbsp;&nbsp;
 &nbsp;&nbsp;&nbsp;
 <em>Using the package name</em></p>
 </div>
 <div class="literalblock">
 <div class="content">
 <pre>Logger logger = Logger.getInstance (LogCategory.OPENEJB, "org.apache.openejb.util");</pre>
 </div>
 </div>
 <div class="paragraph">
 <p>&nbsp;&nbsp;&nbsp;
 &nbsp;&nbsp;&nbsp;
 &nbsp;&nbsp;
 &nbsp;&nbsp;<em>&nbsp;
 Using the Class</em></p>
 </div>
 <div class="literalblock">
 <div class="content">
 <pre>Logger logger = Logger.getInsance(LogCategory.OPENEJB, Connect.class);</pre>
 </div>
 </div>
 <div class="paragraph">
 <p>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
 <em>Get a child Logger for an existing Logger instance</em></p>
 </div>
 <div class="literalblock">
 <div class="content">
 <pre>Logger logger = Logger.getInsance(LogCategory.OPENEJB, Connect.class);
 Logger child = logger.getChildLogger("shutdown");</pre>
 </div>
 </div>
 <div class="paragraph">
 <p>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
 <em>Get a child Logger of an existing Logger using a LogCategory</em></p>
 </div>
 <div class="literalblock">
 <div class="content">
 <pre>LogCategory childCategory = LogCategory.OPENEJB.createChild("shutdown");
 Logger logger = Logger.getInstance(childCategory,Connect.class);</pre>
 </div>
 </div>
 <div class="ulist">
 <ul>
 <li>
 <p>&nbsp;Call one of the following methods passing in the key as an argument <strong> debug </strong> error <strong> fatal </strong> info ** warning</p>
 <div class="paragraph">
 <p>Logger logger = Logger.getInstance(LogCategory.OPENEJB,Connect.class);
 logger.info("error.file");</p>
 </div>
 </li>
 </ul>
 </div>
 <div class="paragraph">
 <p>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
 The Messages.properties file under org.apache.openejb.util must have the "error.file" key in it with the corresponding message.</p>
 </div>
 <div class="paragraph">
 <p><a name="Logging-LoggerInheritance&nbsp;"></a></p>
 </div>
 </div>
 <div class="sect2">
 <h3 id="_logger_inheritance">Logger Inheritance&nbsp;</h3>
 <div class="paragraph">
 <p>&nbsp;Another interesting feature of the Logging framework is inheritance.
 Here is how it works:</p>
 </div>
 <div class="paragraph">
 <p>Say you have the following Messages.properties files in the classpath.</p>
 </div>
 <div class="olist arabic">
 <ol class="arabic">
 <li>
 <p>&nbsp;
 org/apache/openejb/Messages.properties</p>
 </li>
 <li>
 <p>&nbsp;
 org/apache/openejb/core/Messages.properties</p>
 </li>
 <li>
 <p>&nbsp;
 org/apache/openejb/core/stateless/Messages.properties</p>
 </li>
 </ol>
 </div>
 <div class="paragraph">
 <p>&nbsp;
 &nbsp;
 Then you have a class such as org.apache.openejb.core.stateless.StatelessContainer (note the package) If that class referenced a message key "classNotFound" for example, the Logger would look for the message first in Messages.properties 3, then 2, then 1 and so on until it found the required message.
 This would allow better reuse of messages, more flexibility in where we put the Message.properties&nbsp;
 files, as well as the added bonus in that we no longer need to pass in the location of where our Message.properties file is</p>
 </div>
 <div class="paragraph">
 <p><a name="Logging-Loggingforintegrators"></a></p>
 </div>
 </div>
 <div class="sect2">
 <h3 id="_logging_for_integrators">Logging for integrators</h3>
 <div class="paragraph">
 <p>If you want to embed OpenEJB in your application and need to control the logging configuration of OpenEJB, simple set the openejb.logger.external system property to true.
 Now, its your applications' responsibility to configure logging, OpenEJB will simply use your configuration.</p>
 </div>
 <div class="paragraph">
 <p><a name="Logging-&nbsp;OriginationoftheLoggingIdea"></a></p>
 </div>
 </div>
 <div class="sect2">
 <h3 id="_origination_of_the_logging_idea">&nbsp;Origination of the Logging Idea</h3>
 <div class="paragraph">
 <p>There has been a long discussion for this logging idea.
 Its going to be worth it to read the discussion at <a href="http://www.nabble.com/i18n-and-logging-tf3962134s2756.html">i18n and logging</a></p>
 </div>
 <div class="paragraph">
 <p>Here is a extract from an email from David Blevins which talks about the existing logging framework.
 The current framework is more or less the same as this one, just some added features and a rewrite of the API</p>
 </div>
 <div class="paragraph">
 <p>Each module has a file called default.logging.conf.
 This file contains the definition of all Loggers, their appenders and warning levels.
 However, we do not use default.logging.conf first.
 The basic idea is that first we look for say conf/logging.conf in the openejb.base directory.
 &nbsp;If we don&#8217;t find it there, we look for default.logging.conf in the classpath.
 &nbsp;If we did find default.logging.conf (which we should) and there is an openejb.base/conf/ directory then expand the default.logging.conf to openejb.base/conf/logging.conf where we expected to find the file in the first place.
 &nbsp;If there was no openejb.base/conf/ directory, then it&#8217;s safe to assume we&#8217;re running embedded (in a test case perhaps) and just use the default.logging.conf and do no extra work.</p>
 </div>
 <div class="paragraph">
 <p>We have default.logging.conf which we use this way as well as default.openejb.conf and now more recently users.properties and groups.properties.
 &nbsp;We search on disk for the resource in openejb.base/conf/ if we don&#8217;t find them we unpack the default one we stuffed in openejb-core jar and extract it to disk in the openejb.base/conf directory if there is one&#8201;&#8212;&#8201;if there isn&#8217;t one we just use the default file.</p>
 </div>
 <div class="paragraph">
 <p>The basic ideas behind the pattern are that:  &nbsp;1.
 If you&#8217;ve messed up your configuration, just delete or rename the respective files in your conf/ directory and new (working) ones will magically appear.
 &nbsp;2.
 When upgrading its nice that our zip file won&#8217;t overwrite any existing files in conf/  &nbsp;3.
 If you&#8217;re running embedded you don&#8217;t have to setup any directories or have any config files, we can run on defaults.</p>
 </div>
 <div class="paragraph">
 <p>The <em>ConfUtils.getConfResource</em> utility to do that pattern generically , but so far we&#8217;re only using it for the users.properties and groups.properties files.
 &nbsp;We should be using it everywhere.
 &nbsp;Having the code in multiple places has lead to some inconsistencies such as we expand the default.openejb.conf file to conf/openejb.xml (not even the same file extension).
 &nbsp;We really don&#8217;t need the "default" part in our file names and the lingering usage of the "conf" file extension is something that needs to go bye-bye&#8201;&#8212;&#8201;we should use properties for properties files and xml for xml files, etc.</p>
 </div>
 </div>
 </div>
 </div>
             </div>

         </div>
     </div>
 <div style="margin-bottom: 30px;"></div>
 <footer>
 		<div class="container">
 			<div class="row">
 				<div class="col-sm-6 text-center-mobile">
 					<h3 class="white">Be simple.  Be certified. Be Tomcat.</h3>
 					<h5 class="light regular light-white">"A good application in a good server"</h5>
 					<ul class="social-footer">
 						<li><a href="https://www.facebook.com/ApacheTomEE/"><i class="fa fa-facebook"></i></a></li>
 						<li><a href="https://twitter.com/apachetomee"><i class="fa fa-twitter"></i></a></li>
 					</ul>
 					<h5 class="light regular light-white">
 						<a href="../privacy-policy.html" class="white">Privacy Policy</a>
 					</h5>
 				</div>
 				<div class="col-sm-6 text-center-mobile">
 					<div class="row opening-hours">
 						<div class="col-sm-3 text-center-mobile">
 							<h5><a href="../latest/docs/" class="white">Documentation</a></h5>
 							<ul class="list-unstyled">
 								<li><a href="../latest/docs/admin/configuration/index.html" class="regular light-white">How to configure</a></li>
 								<li><a href="../latest/docs/admin/file-layout.html" class="regular light-white">Dir. Structure</a></li>
 								<li><a href="../latest/docs/developer/testing/index.html" class="regular light-white">Testing</a></li>
 								<li><a href="../latest/docs/admin/cluster/index.html" class="regular light-white">Clustering</a></li>
 							</ul>
 						</div>
 						<div class="col-sm-3 text-center-mobile">
 							<h5><a href="../latest/examples/" class="white">Examples</a></h5>
 							<ul class="list-unstyled">
 								<li><a href="../latest/examples/simple-cdi-interceptor.html" class="regular light-white">CDI Interceptor</a></li>
 								<li><a href="../latest/examples/rest-cdi.html" class="regular light-white">REST with CDI</a></li>
 								<li><a href="../latest/examples/ejb-examples.html" class="regular light-white">EJB</a></li>
 								<li><a href="../latest/examples/jsf-managedBean-and-ejb.html" class="regular light-white">JSF</a></li>
 							</ul>
 						</div>
 						<div class="col-sm-3 text-center-mobile">
 							<h5><a href="../community/index.html" class="white">Community</a></h5>
 							<ul class="list-unstyled">
 								<li><a href="../community/contributors.html" class="regular light-white">Contributors</a></li>
 								<li><a href="../community/social.html" class="regular light-white">Social</a></li>
 								<li><a href="../community/sources.html" class="regular light-white">Sources</a></li>
 							</ul>
 						</div>
 						<div class="col-sm-3 text-center-mobile">
 							<h5><a href="../security/index.html" class="white">Security</a></h5>
 							<ul class="list-unstyled">
 								<li><a href="https://apache.org/security" target="_blank" class="regular light-white">Apache Security</a></li>
 								<li><a href="https://apache.org/security/projects.html" target="_blank" class="regular light-white">Security Projects</a></li>
 								<li><a href="https://cve.mitre.org" target="_blank" class="regular light-white">CVE</a></li>
 							</ul>
 						</div>
 					</div>
 				</div>
 			</div>
 			<div class="row bottom-footer text-center-mobile">
 				<div class="col-sm-12 light-white">
 					<p>Copyright &copy; 1999-2022 The Apache Software Foundation, Licensed under the Apache License, Version 2.0. Apache TomEE, TomEE, Apache, the Apache feather logo, and the Apache TomEE project logo are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners.</p>
 				</div>
 			</div>
 		</div>
 	</footer>
 	<!-- Holder for mobile navigation -->
 	<div class="mobile-nav">
         <ul>
           <li><a hef="../latest/docs/admin/index.html">Administrators</a>
           <li><a hef="../latest/docs/developer/index.html">Developers</a>
           <li><a hef="../latest/docs/advanced/index.html">Advanced</a>
           <li><a hef="../community/index.html">Community</a>
         </ul>
 		<a href="#" class="close-link"><i class="arrow_up"></i></a>
 	</div>
 	<!-- Scripts -->
 	<script src="../js/jquery-1.11.1.min.js"></script>
 	<script src="../js/owl.carousel.min.js"></script>
 	<script src="../js/bootstrap.min.js"></script>
 	<script src="../js/wow.min.js"></script>
 	<script src="../js/typewriter.js"></script>
 	<script src="../js/jquery.onepagenav.js"></script>
 	<script src="../js/tree.jquery.js"></script>
 	<script src="../js/highlight.pack.js"></script>
     <script src="../js/main.js"></script>
 		</body>

 </html>
	<!DOCTYPE html>
	<html lang="en">

	<head>
	<meta charset="UTF-8">
	<meta http-equiv="X-UA-Compatible" content="IE=edge">
	<meta name="viewport" content="width=device-width, initial-scale=1">
	<title>Apache TomEE</title>
	<meta name="description"
	content="Apache TomEE is a lightweight, yet powerful, JavaEE Application server with feature rich tooling." />
	<meta name="keywords" content="tomee,asf,apache,javaee,jee,shade,embedded,test,junit,applicationcomposer,maven,arquillian" />
	<meta name="author" content="Luka Cvetinovic for Codrops" />
	<link rel="icon" href="../favicon.ico">
	<link rel="icon" type="image/png" href="../favicon.png">
	<meta name="msapplication-TileColor" content="#80287a">
	<meta name="theme-color" content="#80287a">
	<link rel="stylesheet" type="text/css" href="../css/normalize.css">
	<link rel="stylesheet" type="text/css" href="../css/bootstrap.css">
	<link rel="stylesheet" type="text/css" href="../css/owl.css">
	<link rel="stylesheet" type="text/css" href="../css/animate.css">
	<link rel="stylesheet" type="text/css" href="../fonts/font-awesome-4.1.0/css/font-awesome.min.css">
	<link rel="stylesheet" type="text/css" href="../fonts/eleganticons/et-icons.css">
	<link rel="stylesheet" type="text/css" href="../css/jqtree.css">
	<link rel="stylesheet" type="text/css" href="../css/idea.css">
	<link rel="stylesheet" type="text/css" href="../css/cardio.css">

	<script type="text/javascript">
	<!-- Matomo -->
	var _paq = window._paq = window._paq \|\| [];
	/* tracker methods like "setCustomDimension" should be called before "trackPageView" */
	/* We explicitly disable cookie tracking to avoid privacy issues */
	_paq.push(['disableCookies']);
	_paq.push(['trackPageView']);
	_paq.push(['enableLinkTracking']);
	(function () {
	var u = "//matomo.privacy.apache.org/";
	_paq.push(['setTrackerUrl', u + 'matomo.php']);
	_paq.push(['setSiteId', '5']);
	var d = document, g = d.createElement('script'), s = d.getElementsByTagName('script')[0];
	g.async = true;
	g.src = u + 'matomo.js';
	s.parentNode.insertBefore(g, s);
	})();
	<!-- End Matomo Code -->
	</script>
	</head>

	<body>
	<div class="preloader">
	<img src="../img/loader.gif" alt="Preloader image">
	</div>
	<nav class="navbar">
	<div class="container">
	<div class="row"> <div class="col-md-12">

	<!-- Brand and toggle get grouped for better mobile display -->
	<div class="navbar-header">
	<button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#bs-example-navbar-collapse-1">
	<span class="sr-only">Toggle navigation</span>
	<span class="icon-bar"></span>
	<span class="icon-bar"></span>
	<span class="icon-bar"></span>
	</button>
	<a class="navbar-brand" href="/" title="Apache TomEE">
	<span>


	<img
	src="../img/apache_tomee-logo.svg"
	onerror="this.src='../img/apache_tomee-logo.jpg'"
	height="50"
	>


	</span>
	</a>
	</div>
	<!-- Collect the nav links, forms, and other content for toggling -->
	<div class="collapse navbar-collapse" id="bs-example-navbar-collapse-1">
	<ul class="nav navbar-nav navbar-right main-nav">
	<li><a href="../docs.html">Documentation</a></li>
	<li><a href="../community/index.html">Community</a></li>
	<li><a href="../security/security.html">Security</a></li>
	<li><a class="btn btn-accent accent-orange no-shadow" href="../download.html">Downloads</a></li>
	</ul>
	</div>
	<!-- /.navbar-collapse -->
	</div></div>
	</div>
	<!-- /.container-fluid -->
	</nav>


	<div id="main-block" class="container main-block">
	<div class="row title">
	<div class="col-md-12">
	<div class='page-header'>

	<h1>Logging</h1>
	</div>
	</div>
	</div>
	<div class="row">

	<div class="col-md-12">
	<div class="sect1">
	<h2 id="_logging_for_users">Logging for Users</h2>
	<div class="sectionbody">
	<div class="paragraph">
	<p>All logging in OpenEJB is done using the openejb.base/conf/logging.properties file.
	When you download and extract OpenEJB, you will not find this file under the openejb.base/conf directory.
	However, when you start the server, this file magically appears.
	So what does this give you as a user of OpenEJB?
	Here are some of the benefits:</p>
	</div>
	<div class="olist arabic">
	<ol class="arabic">
	<li>
	<p>You do not have to author a logging.properties from scratch.
	You get one with sensible defaults.</p>
	</li>
	<li>
	<p>If you did modify the default file, and you wanted to revert back to the default file generated by OpenEJB, all you have to do is</p>
	</li>
	<li>
	<p></p>
	<div class="paragraph">
	<p>= Delete or rename the file e.g. rename it to logging.properties.BAK .</p>
	</div>
	</li>
	<li>
	<p></p>
	<div class="paragraph">
	<p>= Restart the server</p>
	</div>
	</li>
	</ol>
	</div>
	<div class="paragraph">
	<p>
	OpenEJB will find that the logging.properties file is missing from the openejb.base/conf directory and it will automatically create a new one with the default configuration.
	The good thing is that if you modify the logging.properties file, OpenEJB will <strong>NOT</strong> over-write it.</p>
	</div>
	<div class="paragraph">
	<p>The default logging configuration created by OpenEJB uses RollingFileAppender’s.
	The log files are located under the openejb.base/logs directory.
	By default it writes to just two files , openejb.log and transaction.log
	{info:title=Embedded Testing} When running tests using embedded OpenEJB, the logging.properties will be ignored.
	You need to use a file named embedded.logging.properties instead.
	Place this file under src/test/resources {info} <a name="Logging-Loggingforcontributors/committers"></a></p>
	</div>
	</div>
	</div>
	<div class="sect1">
	<h2 id="_logging_for_contributorscommitters">Logging for contributors/committers</h2>
	<div class="sectionbody">
	<div class="paragraph">
	<p>The org.apache.openejb.util.Logger class is the one which is used for logging.
	This class is a wrapper around log4. </p>
	</div>
	<div class="paragraph">
	<p><a name="Logging-LogCategory"></a></p>
	</div>
	<div class="sect2">
	<h3 id="_logcategory">LogCategory</h3>
	<div class="paragraph">
	<p>Each Logger instance belongs to a category represented by a org.apache.openejb.util.LogCategory instance.
	Here is what the LogCategory class looks like</p>
	</div>
	<div class="literalblock">
	<div class="content">
	<pre>public final class LogCategory {
	private final String name;
	public static final LogCategory OPENEJB = new LogCategory( "OpenEJB");
	public static final LogCategory OPENEJB_ADMIN = OPENEJB.createChild("admin");
	public static final LogCategory OPENEJB_STARTUP = OPENEJB.createChild("startup");
	public static final LogCategory OPENEJB_STARTUP_CONFIG = OPENEJB_STARTUP.createChild("config");
	public static final LogCategory OPENEJB_STARTUP_VALIDATION = OPENEJB_STARTUP.createChild("validation");
	// other categories removed for code brevity
	private LogCategory(String name){
	this.name = name;
	}
	public String getName() {
	return name;
	}
	/**
	* Creates a child category of this category. <B>Use this method sparingly</B>. This method is to be used in only those circumstances where the name of the
	* category is not known upfront and is a derived name. If you know the name of the category, it is highly recommended to add a static final field
	* of type LogCategory in this class
	* @param child
	* @return - LogCategory
	*/
	public LogCategory createChild(String child){
	return new LogCategory(this.name+"."+child);
	}

	}</pre>
	</div>
	</div>
	<div class="paragraph">
	<p>Notice carefully how each LogCategory instance is created.
	The objective here is that each LogCategory should be a child of the OPENEJB category.
	If you need to add a new category and you know the name of the category upfront, simply open the LogCategory class and add another category.
	For example, if you needed to add a category named SHUTDOWN, here is the recommended way to add it</p>
	</div>
	<div class="literalblock">
	<div class="content">
	<pre>public static final LogCategory OPENEJB_SHUTDOWN = LogCategory.OPENEJB.createChild("shutdown");</pre>
	</div>
	</div>
	<div class="paragraph">
	<p>Sometimes you may want to create a category whose name is "generated" at runtime.
	In that case you can use the "createChild" method of the LogCategory class to create this new category.
	For example, if you wanted to create a category of Logger for every deployed module, then assuming you have the moduleId information you could do something as follows to create a category:</p>
	</div>
	<div class="literalblock">
	<div class="content">
	<pre>String moduleId = "mymodule";
	LogCategory generatedCategory = LogCategory.OPENEJB.createChild(moduleId);</pre>
	</div>
	</div>
	<div class="paragraph">
	<p><a name="Logging- Logger"></a></p>
	</div>
	</div>
	<div class="sect2">
	<h3 id="_logger"> Logger</h3>
	<div class="paragraph">
	<p>The preference is to externalize all logging messages in properties file.
	Typically each package should have a file called Messages.properties.
	This file should have all the keys and the corresponding messages.
	Here are the steps you would follow to log a message:</p>
	</div>
	<div class="ulist">
	<ul>
	<li>
	<p>For each message you need to log, you would open the Messages.properties file in the corresponding package and add a key-value pair for the message.
	For example, if you were authoring a class called org.apache.openejb.util.Connect, then you would add a key-value pair to the Messages.properties file located in the org.apache.openejb.util package.</p>
	</li>
	<li>
	<p>Obtain a Logger instance in one of the following ways:</p>
	</li>
	</ul>
	</div>
	<div class="paragraph">
	<p>



	<em>Using the package name</em></p>
	</div>
	<div class="literalblock">
	<div class="content">
	<pre>Logger logger = Logger.getInstance (LogCategory.OPENEJB, "org.apache.openejb.util");</pre>
	</div>
	</div>
	<div class="paragraph">
	<p>


	<em>
	Using the Class</em></p>
	</div>
	<div class="literalblock">
	<div class="content">
	<pre>Logger logger = Logger.getInsance(LogCategory.OPENEJB, Connect.class);</pre>
	</div>
	</div>
	<div class="paragraph">
	<p>
	<em>Get a child Logger for an existing Logger instance</em></p>
	</div>
	<div class="literalblock">
	<div class="content">
	<pre>Logger logger = Logger.getInsance(LogCategory.OPENEJB, Connect.class);
	Logger child = logger.getChildLogger("shutdown");</pre>
	</div>
	</div>
	<div class="paragraph">
	<p>
	<em>Get a child Logger of an existing Logger using a LogCategory</em></p>
	</div>
	<div class="literalblock">
	<div class="content">
	<pre>LogCategory childCategory = LogCategory.OPENEJB.createChild("shutdown");
	Logger logger = Logger.getInstance(childCategory,Connect.class);</pre>
	</div>
	</div>
	<div class="ulist">
	<ul>
	<li>
	<p> Call one of the following methods passing in the key as an argument <strong> debug </strong> error <strong> fatal </strong> info ** warning</p>
	<div class="paragraph">
	<p>Logger logger = Logger.getInstance(LogCategory.OPENEJB,Connect.class);
	logger.info("error.file");</p>
	</div>
	</li>
	</ul>
	</div>
	<div class="paragraph">
	<p>
	The Messages.properties file under org.apache.openejb.util must have the "error.file" key in it with the corresponding message.</p>
	</div>
	<div class="paragraph">
	<p><a name="Logging-LoggerInheritance "></a></p>
	</div>
	</div>
	<div class="sect2">
	<h3 id="_logger_inheritance">Logger Inheritance </h3>
	<div class="paragraph">
	<p> Another interesting feature of the Logging framework is inheritance.
	Here is how it works:</p>
	</div>
	<div class="paragraph">
	<p>Say you have the following Messages.properties files in the classpath.</p>
	</div>
	<div class="olist arabic">
	<ol class="arabic">
	<li>
	<p>
	org/apache/openejb/Messages.properties</p>
	</li>
	<li>
	<p>
	org/apache/openejb/core/Messages.properties</p>
	</li>
	<li>
	<p>
	org/apache/openejb/core/stateless/Messages.properties</p>
	</li>
	</ol>
	</div>
	<div class="paragraph">
	<p>

	Then you have a class such as org.apache.openejb.core.stateless.StatelessContainer (note the package) If that class referenced a message key "classNotFound" for example, the Logger would look for the message first in Messages.properties 3, then 2, then 1 and so on until it found the required message.
	This would allow better reuse of messages, more flexibility in where we put the Message.properties
	files, as well as the added bonus in that we no longer need to pass in the location of where our Message.properties file is</p>
	</div>
	<div class="paragraph">
	<p><a name="Logging-Loggingforintegrators"></a></p>
	</div>
	</div>
	<div class="sect2">
	<h3 id="_logging_for_integrators">Logging for integrators</h3>
	<div class="paragraph">
	<p>If you want to embed OpenEJB in your application and need to control the logging configuration of OpenEJB, simple set the openejb.logger.external system property to true.
	Now, its your applications' responsibility to configure logging, OpenEJB will simply use your configuration.</p>
	</div>
	<div class="paragraph">
	<p><a name="Logging- OriginationoftheLoggingIdea"></a></p>
	</div>
	</div>
	<div class="sect2">
	<h3 id="_origination_of_the_logging_idea"> Origination of the Logging Idea</h3>
	<div class="paragraph">
	<p>There has been a long discussion for this logging idea.
	Its going to be worth it to read the discussion at <a href="http://www.nabble.com/i18n-and-logging-tf3962134s2756.html">i18n and logging</a></p>
	</div>
	<div class="paragraph">
	<p>Here is a extract from an email from David Blevins which talks about the existing logging framework.
	The current framework is more or less the same as this one, just some added features and a rewrite of the API</p>
	</div>
	<div class="paragraph">
	<p>Each module has a file called default.logging.conf.
	This file contains the definition of all Loggers, their appenders and warning levels.
	However, we do not use default.logging.conf first.
	The basic idea is that first we look for say conf/logging.conf in the openejb.base directory.
	If we don’t find it there, we look for default.logging.conf in the classpath.
	If we did find default.logging.conf (which we should) and there is an openejb.base/conf/ directory then expand the default.logging.conf to openejb.base/conf/logging.conf where we expected to find the file in the first place.
	If there was no openejb.base/conf/ directory, then it’s safe to assume we’re running embedded (in a test case perhaps) and just use the default.logging.conf and do no extra work.</p>
	</div>
	<div class="paragraph">
	<p>We have default.logging.conf which we use this way as well as default.openejb.conf and now more recently users.properties and groups.properties.
	We search on disk for the resource in openejb.base/conf/ if we don’t find them we unpack the default one we stuffed in openejb-core jar and extract it to disk in the openejb.base/conf directory if there is one — if there isn’t one we just use the default file.</p>
	</div>
	<div class="paragraph">
	<p>The basic ideas behind the pattern are that:  1.
	If you’ve messed up your configuration, just delete or rename the respective files in your conf/ directory and new (working) ones will magically appear.
	2.
	When upgrading its nice that our zip file won’t overwrite any existing files in conf/  3.
	If you’re running embedded you don’t have to setup any directories or have any config files, we can run on defaults.</p>
	</div>
	<div class="paragraph">
	<p>The <em>ConfUtils.getConfResource</em> utility to do that pattern generically , but so far we’re only using it for the users.properties and groups.properties files.
	We should be using it everywhere.
	Having the code in multiple places has lead to some inconsistencies such as we expand the default.openejb.conf file to conf/openejb.xml (not even the same file extension).
	We really don’t need the "default" part in our file names and the lingering usage of the "conf" file extension is something that needs to go bye-bye — we should use properties for properties files and xml for xml files, etc.</p>
	</div>
	</div>
	</div>
	</div>
	</div>

	</div>
	</div>
	<div style="margin-bottom: 30px;"></div>
	<footer>
	<div class="container">
	<div class="row">
	<div class="col-sm-6 text-center-mobile">
	<h3 class="white">Be simple. Be certified. Be Tomcat.</h3>
	<h5 class="light regular light-white">"A good application in a good server"</h5>
	<ul class="social-footer">
	<li><a href="https://www.facebook.com/ApacheTomEE/"><i class="fa fa-facebook"></i></a></li>
	<li><a href="https://twitter.com/apachetomee"><i class="fa fa-twitter"></i></a></li>
	</ul>
	<h5 class="light regular light-white">
	<a href="../privacy-policy.html" class="white">Privacy Policy</a>
	</h5>
	</div>
	<div class="col-sm-6 text-center-mobile">
	<div class="row opening-hours">
	<div class="col-sm-3 text-center-mobile">
	<h5><a href="../latest/docs/" class="white">Documentation</a></h5>
	<ul class="list-unstyled">
	<li><a href="../latest/docs/admin/configuration/index.html" class="regular light-white">How to configure</a></li>
	<li><a href="../latest/docs/admin/file-layout.html" class="regular light-white">Dir. Structure</a></li>
	<li><a href="../latest/docs/developer/testing/index.html" class="regular light-white">Testing</a></li>
	<li><a href="../latest/docs/admin/cluster/index.html" class="regular light-white">Clustering</a></li>
	</ul>
	</div>
	<div class="col-sm-3 text-center-mobile">
	<h5><a href="../latest/examples/" class="white">Examples</a></h5>
	<ul class="list-unstyled">
	<li><a href="../latest/examples/simple-cdi-interceptor.html" class="regular light-white">CDI Interceptor</a></li>
	<li><a href="../latest/examples/rest-cdi.html" class="regular light-white">REST with CDI</a></li>
	<li><a href="../latest/examples/ejb-examples.html" class="regular light-white">EJB</a></li>
	<li><a href="../latest/examples/jsf-managedBean-and-ejb.html" class="regular light-white">JSF</a></li>
	</ul>
	</div>
	<div class="col-sm-3 text-center-mobile">
	<h5><a href="../community/index.html" class="white">Community</a></h5>
	<ul class="list-unstyled">
	<li><a href="../community/contributors.html" class="regular light-white">Contributors</a></li>
	<li><a href="../community/social.html" class="regular light-white">Social</a></li>
	<li><a href="../community/sources.html" class="regular light-white">Sources</a></li>
	</ul>
	</div>
	<div class="col-sm-3 text-center-mobile">
	<h5><a href="../security/index.html" class="white">Security</a></h5>
	<ul class="list-unstyled">
	<li><a href="https://apache.org/security" target="_blank" class="regular light-white">Apache Security</a></li>
	<li><a href="https://apache.org/security/projects.html" target="_blank" class="regular light-white">Security Projects</a></li>
	<li><a href="https://cve.mitre.org" target="_blank" class="regular light-white">CVE</a></li>
	</ul>
	</div>
	</div>
	</div>
	</div>
	<div class="row bottom-footer text-center-mobile">
	<div class="col-sm-12 light-white">
	<p>Copyright © 1999-2022 The Apache Software Foundation, Licensed under the Apache License, Version 2.0. Apache TomEE, TomEE, Apache, the Apache feather logo, and the Apache TomEE project logo are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners.</p>
	</div>
	</div>
	</div>
	</footer>
	<!-- Holder for mobile navigation -->
	<div class="mobile-nav">
	<ul>
	<li><a hef="../latest/docs/admin/index.html">Administrators</a>
	<li><a hef="../latest/docs/developer/index.html">Developers</a>
	<li><a hef="../latest/docs/advanced/index.html">Advanced</a>
	<li><a hef="../community/index.html">Community</a>
	</ul>
	<a href="#" class="close-link"><i class="arrow_up"></i></a>
	</div>
	<!-- Scripts -->
	<script src="../js/jquery-1.11.1.min.js"></script>
	<script src="../js/owl.carousel.min.js"></script>
	<script src="../js/bootstrap.min.js"></script>
	<script src="../js/wow.min.js"></script>
	<script src="../js/typewriter.js"></script>
	<script src="../js/jquery.onepagenav.js"></script>
	<script src="../js/tree.jquery.js"></script>
	<script src="../js/highlight.pack.js"></script>
	<script src="../js/main.js"></script>
	</body>

	</html>