001    package hirondelle.web4j.webmaster;
002    
003    import javax.servlet.ServletConfig;
004    import hirondelle.web4j.model.AppException;
005    
006    /**
007     Configure the logging system used in your application.
008    
009     <P>See {@link hirondelle.web4j.BuildImpl} for important information on how this item is configured. 
010     {@link hirondelle.web4j.BuildImpl#forLoggingConfig()} 
011     returns the configured implementation of this interface.
012     
013     <P>Here, implementations configure the logging system using <em>code</em>, not a configuration file. 
014     WEB4J itself uses JDK logging. Your application may also use JDK logging, or any other logging system.
015     
016     <P>If your application does not require any logging config performed in code, 
017     then just set the <tt>LoggingDirectory</tt> in <tt>web.xml</tt> set to <tt>'NONE'</tt>.  
018     
019     <P>Implementations of this interface are called by the framework only <em>once</em>, upon startup.
020     
021     <P><b>Independent Logging On Servers</b><br>
022     In the JDK <tt>logging.properties</tt> config file, it is important to remember that  
023     the <tt>handlers</tt> setting creates Handlers and <em>attaches them to the root logger</em>. 
024     In general, those default handlers will be <em>shared</em> by all applications running 
025     in that JRE. This is not appropriate for most server environments. 
026     In a servlet environment, however, each application uses a <em>private class loader</em>. 
027     This means that each application can perform its own custom logging 
028     config in <em>code</em>, instead of in <tt>logging.properties</tt>, and <em>retain independence</em> 
029     from other applications running in the same JRE. 
030    */
031    public interface LoggingConfig {
032      
033      /** Configure application logging.  */
034      void setup(ServletConfig aConfig) throws AppException;
035    
036    }