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