001    package com.softnetConsult.utils.log;
002    
003    import java.io.File;
004    import java.io.FileNotFoundException;
005    
006    import com.softnetConsult.utils.exceptions.Bug;
007    import com.softnetConsult.utils.files.FileTools;
008    
009    /**
010     * This class provides a number of convenience methods for creating {@code ScreenFileLogger} objects.
011     * 
012     * <p style="font-size:smaller;">This product includes software developed by the
013     *    <strong>SoftNet-Consult Java Utility Library</strong> project and its contributors.<br />
014     *    (<a href="http://java-tools.sourceforge.net" target="_blank">http://java-tools.sourceforge.net</a>)<br />
015     *    Copyright (c) 2007-2008 SoftNet-Consult.<br />
016     *    Copyright (c) 2007-2008 G. Paperin.<br />
017     *    All rights reserved.
018     * </p>
019     * <p style="font-size:smaller;">File: ScreenFileLoggerFactory.java<br />
020     *    Library API version: {@value com.softnetConsult.utils.APIProperties#apiVersion}<br />
021     *    Java compliance version: {@value com.softnetConsult.utils.APIProperties#javaComplianceVersion}
022     * </p>
023     * <p style="font-size:smaller;">Redistribution and use in source and binary forms, with or
024     *    without modification, are permitted provided that the following terms and conditions are met:
025     * </p>
026     * <p style="font-size:smaller;">1. Redistributions of source code must retain the above
027     *    acknowledgement of the SoftNet-Consult Java Utility Library project, the above copyright
028     *    notice, this list of conditions and the following disclaimer.<br />
029     *    2. Redistributions in binary form must reproduce the above acknowledgement of the
030     *    SoftNet-Consult Java Utility Library project, the above copyright notice, this list of
031     *    conditions and the following disclaimer in the documentation and/or other materials
032     *    provided with the distribution.<br />
033     *    3. All advertising materials mentioning features or use of this software or any derived
034     *    software must display the following acknowledgement:<br />
035     *    <em>This product includes software developed by the SoftNet-Consult Java Utility Library
036     *    project and its contributors.</em>
037     * </p>
038     * <p style="font-size:smaller;">THIS SOFTWARE IS PROVIDED &quot;AS IS&quot;, WITHOUT WARRANTY
039     *    OF ANY KIND, EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
040     *    MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND  NONINFRINGEMENT. IN NO EVENT SHALL
041     *    THE AUTHORS, CONTRIBUTORS OR COPYRIGHT  HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
042     *    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING  FROM, OUT OF OR
043     *    IN CONNECTION WITH THE SOFTWARE OR THE USE OR  OTHER DEALINGS IN THE SOFTWARE.
044     * </p> 
045     * @author Greg Paperin (<a href="http://www.paperin.org" target="_blank">http://www.paperin.org</a>)
046     * @version {@value com.softnetConsult.utils.APIProperties#apiVersion}
047     */
048    public final class ScreenFileLoggerFactory {
049    
050    /**
051     * Default indentation length in characters. 
052     */
053    private static final int defaultIndentationLen = 4;
054    
055    /**
056     * Default base name for log files.
057     */
058    private static final String defaultLogfileName = "LogFile";
059    
060    /**
061     * Default file extension for log files.
062     */
063    private static final String defaultLogfileExt = "txt";
064    
065    
066    /**
067     * Prevents instances of this class from being created
068     * as this class contains only static utility methods.
069     */
070    private ScreenFileLoggerFactory() {}
071    
072    
073    /**
074     * Constructs an indentation string of the required length.
075     * 
076     * @param len Length of the indentation string.
077     * @return A string consisting of {@code len} white spaces.
078     */
079    public static String getIndentStr(int len) {
080            if (len < 0 || 250 < len)
081                    throw new IllegalArgumentException("Indentation len must be between 0 and 250");
082            StringBuffer s = new StringBuffer(len);
083            for (int i = 0; i < len; i++)
084                    s.append(' ');
085            return s.toString();
086    }
087    
088    /**
089     * Creates a new logger that logs to screen only.
090     * The logger created by this method has the following properties:<br />
091     * {@code logToScreen}: on.<br />
092     * {@code logToFile}:   off.<br />
093     * {@code logFile}:     null.<br />
094     * {@code append}:      no, overwrite.<br />
095     * {@code indentation}: a string consisting of {@code defaultIndentationLen} white spaces.<br />
096     * 
097     * @return A new logger.
098     */
099    public static ScreenFileLogger createLogger() {
100            try {
101                    return new ScreenFileLogger(true, false, (File) null, false, getIndentStr(defaultIndentationLen));
102            } catch (FileNotFoundException e) {
103                    throw new Bug("An IO exception is not expected as logger is not logging to a file", e);
104            }
105    }
106    
107    /**
108     * Creates a new logger that logs to screen only.
109     * The logger created by this method has the following properties:<br />
110     * {@code logToScreen}: on.<br />
111     * {@code logToFile}:   off.<br />
112     * {@code logFile}:     null.<br />
113     * {@code append}:      no, overwrite.<br />
114     * {@code indentation}: a string consisting of {@code defaultIndentationLen} white spaces.<br />
115     * 
116     * @param indentationStr A string to use for indentation (one copy per indent-level), it does
117     * not necessarily need to consist of white spaces.
118     * @return A new logger.
119     */
120    public static ScreenFileLogger createLogger(char[] indentationStr) {
121            
122            if (null == indentationStr)
123                    return createLogger();
124            
125            try {
126                    return new ScreenFileLogger(true, false, (File) null, false, String.valueOf(indentationStr));
127            } catch (FileNotFoundException e) {
128                    throw new Bug("An IO exception is not expected as logger is not logging to a file", e);
129            }
130    }
131    
132    /**
133     * Creates a new logger that logs to screen only.
134     * The logger created by this method has the following properties:<br />
135     * {@code logToScreen}: on.<br />
136     * {@code logToFile}:   on.<br />
137     * {@code logFile}:     as specified.<br />
138     * {@code append}:      as specified.<br />
139     * {@code indentation}: a string consisting of the specified number of white spaces.<br />
140     * 
141     * @param logPath The file for logging. If {@code null}, a unique default file will be
142     * created in the program start directory.
143     * @param append Whether to append (or overwrite) the log file.
144     * @param indentLen The length of the indentation string.
145     * @return A new logger.
146     */
147    public static ScreenFileLogger createLogger(String logPath, boolean append, int indentLen) {
148            
149            if (null == logPath || 0 == logPath.trim().length())            
150                    return createLogger(FileTools.findUniqueFile(defaultLogfileName, defaultLogfileExt, true));
151                    
152            try {
153                    return new ScreenFileLogger(true, true, logPath, append, getIndentStr(indentLen));
154            } catch (FileNotFoundException e) {
155                    return null;
156            }
157    }
158    
159    /**
160     * Creates a new logger that logs to screen only.
161     * The logger created by this method has the following properties:<br />
162     * {@code logToScreen}: on.<br />
163     * {@code logToFile}:   on.<br />
164     * {@code logFile}:     as specified.<br />
165     * {@code append}:      as specified.<br />
166     * {@code indentation}: a string consisting of the specified number of white spaces.<br />
167     * 
168     * @param logDir The directory for for log file. If {@code null}, the program start
169     * directory will be used.
170     * @param logName The file for logging (relative to the specified directory). If {@code null},
171     * a unique default file will be created in the specified directory.
172     * @param append Whether to append (or overwrite) the log file.
173     * @param indentLen The length of the indentation string.
174     * @return A new logger.
175     */
176    public static ScreenFileLogger createLogger(String logDir, String logName, boolean append, int indentLen) {
177            
178            if (null == logDir || 0 == logDir.trim().length())
179                    return createLogger(logName);
180            
181            if (null == logName || 0 == logName.trim().length())            
182                    return createLogger(FileTools.findUniqueFile(logDir, defaultLogfileName, defaultLogfileExt, true));
183                            
184            try {
185                    return new ScreenFileLogger(true, true, FileTools.concatDirFile(logDir, logName),
186                                                                            append, getIndentStr(indentLen));
187            } catch (FileNotFoundException e) {
188                    return null;
189            }
190    }
191    
192    /**
193     * Creates a new logger that logs to screen only.
194     * The logger created by this method has the following properties:<br />
195     * {@code logToScreen}: on.<br />
196     * {@code logToFile}:   on.<br />
197     * {@code logFile}:     as specified.<br />
198     * {@code append}:      as specified.<br />
199     * {@code indentation}: a string consisting of the specified number of white spaces.<br />
200     * 
201     * @param logFile The file for logging. If {@code null}, a unique default file will be
202     * created in the program start directory. If the file specified a directory, a unique
203     * default file will be created within that directory.
204     * @param append Whether to append (or overwrite) the log file.
205     * @param indentLen The length of the indentation string.
206     * @return A new logger.
207     */
208    public static ScreenFileLogger createLogger(File logFile, boolean append, int indentLen) {
209            
210            if (null == logFile)
211                    logFile = FileTools.findUniqueFile(defaultLogfileName, defaultLogfileExt, true);
212            
213            if (logFile.isDirectory())
214                    logFile = FileTools.findUniqueFile(logFile.getAbsolutePath(),
215                                                                                       defaultLogfileName, defaultLogfileExt, true);                
216                    
217            try {
218                    return new ScreenFileLogger(true, true, logFile, append, getIndentStr(indentLen));
219            } catch (FileNotFoundException e) {
220                    return null;
221            }
222    }
223    
224    /**
225     * Creates a new logger that logs to screen only.
226     * The logger created by this method has the following properties:<br />
227     * {@code logToScreen}: on.<br />
228     * {@code logToFile}:   on.<br />
229     * {@code logFile}:     as specified.<br />
230     * {@code append}:      yes.<br />
231     * {@code indentation}: a string consisting of {@code defaultIndentationLen} white spaces.<br />
232     * 
233     * @param logPath The file for logging. If {@code null}, a unique default file will be
234     * created in the program start directory.
235     * @return A new logger.
236     */
237    public static ScreenFileLogger createLogger(String logPath) {
238            return createLogger(logPath, true, defaultIndentationLen);
239    }
240    
241    /**
242     * Creates a new logger that logs to screen only.
243     * The logger created by this method has the following properties:<br />
244     * {@code logToScreen}: on.<br />
245     * {@code logToFile}:   on.<br />
246     * {@code logFile}:     as specified.<br />
247     * {@code append}:      yes.<br />
248     * {@code indentation}: a string consisting of {@code defaultIndentationLen} white spaces.<br />
249     * 
250     * @param logDir The directory for for log file. If {@code null}, the program start
251     * directory will be used.
252     * @param logName The file for logging (relative to the specified directory). If {@code null},
253     * a unique default file will be created in the specified directory.
254     * @return A new logger.
255     */
256    public static ScreenFileLogger createLogger(String logDir, String logName) {
257            return createLogger(logDir, logName, true, defaultIndentationLen);
258    }
259    
260    /**
261     * Creates a new logger that logs to screen only.
262     * The logger created by this method has the following properties:<br />
263     * {@code logToScreen}: on.<br />
264     * {@code logToFile}:   on.<br />
265     * {@code logFile}:     as specified.<br />
266     * {@code append}:      yes.<br />
267     * {@code indentation}: a string consisting of {@code defaultIndentationLen} white spaces.<br />
268     * 
269     * @param logFile The file for logging. If {@code null}, a unique default file will be
270     * created in the program start directory. If the file specified a directory, a unique
271     * default file will be created within that directory.
272     * @return A new logger.
273     */
274    public static ScreenFileLogger createLogger(File logFile) {
275            return createLogger(logFile, true, defaultIndentationLen);
276    }
277    
278    /**
279     * Creates a new logger that logs to screen only.
280     * The logger created by this method has the following properties:<br />
281     * {@code logToScreen}: on.<br />
282     * {@code logToFile}:   on.<br />
283     * {@code logFile}:     as specified.<br />
284     * {@code append}:      as specified.<br />
285     * {@code indentation}: a string consisting of {@code defaultIndentationLen} white spaces.<br />
286     * 
287     * @param logPath The file for logging. If {@code null}, a unique default file will be
288     * created in the program start directory.
289     * @param append Whether to append (or overwrite) the log file.
290     * @return A new logger.
291     */
292    public static ScreenFileLogger createLogger(String logPath, boolean append) {
293            return createLogger(logPath, append, defaultIndentationLen);
294    }
295    
296    /**
297     * Creates a new logger that logs to screen only.
298     * The logger created by this method has the following properties:<br />
299     * {@code logToScreen}: on.<br />
300     * {@code logToFile}:   on.<br />
301     * {@code logFile}:     as specified.<br />
302     * {@code append}:      as specified.<br />
303     * {@code indentation}: a string consisting of {@code defaultIndentationLen} white spaces.<br />
304     * 
305     * @param logDir The directory for for log file. If {@code null}, the program start
306     * directory will be used.
307     * @param logName The file for logging (relative to the specified directory). If {@code null},
308     * a unique default file will be created in the specified directory.
309     * @param append Whether to append (or overwrite) the log file.
310     * @return A new logger.
311     */
312    public static ScreenFileLogger createLogger(String logDir, String logName, boolean append) {
313            return createLogger(logDir, logName, append, defaultIndentationLen);
314    }
315    
316    /**
317     * Creates a new logger that logs to screen only.
318     * The logger created by this method has the following properties:<br />
319     * {@code logToScreen}: on.<br />
320     * {@code logToFile}:   on.<br />
321     * {@code logFile}:     as specified.<br />
322     * {@code append}:      as specified.<br />
323     * {@code indentation}: a string consisting of {@code defaultIndentationLen} white spaces.<br />
324     * 
325     * @param logFile The file for logging. If {@code null}, a unique default file will be
326     * created in the program start directory. If the file specified a directory, a unique
327     * default file will be created within that directory.
328     * @param append Whether to append (or overwrite) the log file.
329     * @return A new logger.
330     */
331    public static ScreenFileLogger createLogger(File logFile, boolean append) {
332            return createLogger(logFile, append, defaultIndentationLen);
333    }
334    
335    /**
336     * Creates a new logger that logs to screen only.
337     * The logger created by this method has the following properties:<br />
338     * {@code logToScreen}: on.<br />
339     * {@code logToFile}:   on.<br />
340     * {@code logFile}:     as specified.<br />
341     * {@code append}:      yes.<br />
342     * {@code indentation}: a string consisting of the specified number of white spaces.<br />
343     * 
344     * @param logPath The file for logging. If {@code null}, a unique default file will be
345     * created in the program start directory.
346     * @param indentLen The length of the indentation string.
347     * @return A new logger.
348     */
349    public static ScreenFileLogger createLogger(String logPath, int indentLen) {
350            return createLogger(logPath, true, indentLen);
351    }
352    
353    /**
354     * Creates a new logger that logs to screen only.
355     * The logger created by this method has the following properties:<br />
356     * {@code logToScreen}: on.<br />
357     * {@code logToFile}:   on.<br />
358     * {@code logFile}:     as specified.<br />
359     * {@code append}:      yes.<br />
360     * {@code indentation}: a string consisting of the specified number of white spaces.<br />
361     * 
362     * @param logDir The directory for for log file. If {@code null}, the program start
363     * directory will be used.
364     * @param logName The file for logging (relative to the specified directory). If {@code null},
365     * a unique default file will be created in the specified directory.
366     * @param indentLen The length of the indentation string.
367     * @return A new logger.
368     */
369    public static ScreenFileLogger createLogger(String logDir, String logName, int indentLen) {
370            return createLogger(logDir, logName, true, indentLen);
371    }
372    
373    /**
374     * Creates a new logger that logs to screen only.
375     * The logger created by this method has the following properties:<br />
376     * {@code logToScreen}: on.<br />
377     * {@code logToFile}:   on.<br />
378     * {@code logFile}:     as specified.<br />
379     * {@code append}:      yes.<br />
380     * {@code indentation}: a string consisting of the specified number of white spaces.<br />
381     * 
382     * @param logFile The file for logging. If {@code null}, a unique default file will be
383     * created in the program start directory. If the file specified a directory, a unique
384     * default file will be created within that directory.
385     * @param indentLen The length of the indentation string.
386     * @return A new logger.
387     */
388    public static ScreenFileLogger createLogger(File logFile, int indentLen) {
389            return createLogger(logFile, true, indentLen);
390    }
391    
392    } // public final class ScreenFileLoggerFactory