alma.acs.logging.engine.io

Class IOHelper

java.lang.Object

com.cosylab.logging.engine.LogMatcher

alma.acs.logging.engine.io.IOHelper

public class IOHelper
extends LogMatcher

An helper class to perform synchronous I/O operations like load and save.

Load and save methods are executed in a synchronous way i.e. they do not return until the I/O is terminated (or an exception occurs).
Intermediate results useful to monitor the progress of the I/O are communicated to the listeners implementing the IOProgressListener interface.

The load and save methods of this class are synchronized but I would not say that this class is thread safe because it does not hold and lock the objects it receives as parameters like for example the BufferReader and the BufferWriter. So thread safety must be ensured by the owner of such objects.

Loading
The loading is performed through one of the overloaded loadLogs methods. The bytes read and the number of the logs successfully read are sent to the listeners implementing the IOProgressListener interface. If there are filters, an audience or a discard level defined, then each log is checked before being sent to the listener.

Saving
The saving of logs can be done by passing a Collection of logs or an Iteratorto one of the overloaded saveLogs methods. Such methods communicates the progress to the listener implementing the IOProgressListener interface.

Saving logs by passing the name of the file does not require any extra steps.
Saving logs by passing a BufferedWriter is always a three steps procedure:

1. call the prepareSaveFile to write XML header
2. save the logs by calling one of the saveLogs or the saveLog
3. execute Save to add the closing XML tags, flush and close the buffer

Load and save can be very long operations. To stop an I/O, the stopIO() must be executed.

Author:

acaproni

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	IOHelper.GZipLogOutStream GZipLogOutStream subclass GZIPOutputStream to set the compression level.

Field Summary

Fields

Modifier and Type	Field and Description
static int	DEFAULT_COMPRESSION_LEVEL The default compression level while saving files
protected boolean	stopped Signal that a load or a save must be stopped

Fields inherited from class com.cosylab.logging.engine.LogMatcher

actualDiscardLevel

Constructor Summary

Constructors

Constructor and Description
IOHelper() Constructor

Method Summary

Modifier and Type	Method and Description
java.io.BufferedReader	getBufferedReader(java.lang.String fileName) Return the reader to get logs from
java.io.BufferedWriter	getBufferedWriter(java.lang.String fileName, boolean append, boolean gzip) Create a BufferedWriter to save logs into.
java.io.BufferedWriter	getBufferedWriter(java.lang.String fileName, boolean append, boolean gzip, int compressionLevel) Create a BufferedWriter to save logs into
void	loadLogs(java.io.BufferedReader reader, ACSRemoteLogListener logListener, ACSRemoteRawLogListener rawLogListener, ACSRemoteErrorListener errorListener, IOPorgressListener progressListener) Load the logs from the given BufferedReader.
long	loadLogs(java.lang.String fileName, ACSRemoteLogListener logListener, ACSRemoteRawLogListener rawLogListener, ACSRemoteErrorListener errorListener, IOPorgressListener progressListener) Load the logs from the file with the given name.
long	loadLogs(java.lang.String fileName, ACSRemoteLogListener logListener, ACSRemoteRawLogListener rawLogListener, ACSRemoteErrorListener errorListener, IOPorgressListener progressListener, boolean gzip) Load the logs from the file with the given name.
int	saveLog(java.io.BufferedWriter outBuf, ILogEntry log) Save a log in the passed file
void	saveLogs(java.io.BufferedWriter outBuffer, java.util.Collection<ILogEntry> logs, IOPorgressListener progressListener) Save a collection of logs on a BufferedWriter.
void	saveLogs(java.io.BufferedWriter outBuf, java.util.Iterator<ILogEntry> iterator, IOPorgressListener progressListener) Save a collection of logs on a BufferedWriter.
void	saveLogs(java.lang.String fileName, java.util.Collection<ILogEntry> logs, IOPorgressListener progressListener, boolean append, boolean gzip) Save a collection of logs on disk
void	saveLogs(java.lang.String fileName, java.util.Collection<ILogEntry> logs, IOPorgressListener progressListener, boolean append, boolean gzip, int compressionLevel) Save a collection of logs on disk
void	saveLogs(java.lang.String fileName, java.util.Iterator<ILogEntry> iterator, IOPorgressListener progressListener, boolean append, boolean gzip) Save the logs available through an Iterator.
void	saveLogs(java.lang.String fileName, java.util.Iterator<ILogEntry> iterator, IOPorgressListener progressListener, boolean append, boolean gzip, int compressionLevel) Save the logs available through an Iterator.
void	stopIO() Call this method if you wish to interrupt a load or a save.
void	terminateSave(java.io.BufferedWriter outBuffer, boolean close) Terminate the saving.
void	writeHeader(java.io.BufferedWriter wBuffer) Write the XML header in the buffered writer

Methods inherited from class com.cosylab.logging.engine.LogMatcher

getActualDiscardLevel, getAudience, getFilters, match, setAudience, setDiscardLevel, setFilters

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_COMPRESSION_LEVEL

public static final int DEFAULT_COMPRESSION_LEVEL

The default compression level while saving files

See Also:

Constant Field Values

stopped

protected volatile boolean stopped

Signal that a load or a save must be stopped

Constructor Detail

IOHelper

public IOHelper()
         throws java.lang.Exception

Constructor

Throws:

java.lang.Exception - In case of errors building the parser

Method Detail

loadLogs

public long loadLogs(java.lang.String fileName,
                     ACSRemoteLogListener logListener,
                     ACSRemoteRawLogListener rawLogListener,
                     ACSRemoteErrorListener errorListener,
                     IOPorgressListener progressListener,
                     boolean gzip)
              throws java.io.IOException,
                     java.lang.Exception

Load the logs from the file with the given name.

The logs are sent to the ACSRemoteLogListener and /or to the ACSRemoteRawLogListener.

Parameters:

fileName - The name of the file to read logs from

logListener - The callback for each new log read from the IO

rawLogListener - The callback for each new XML log read from the IO

errorListener - The listener for errors

progressListener - The listener to be notified about the bytes read

gzip - If true the file to read is compressed in GZIP format

Returns:

The length of the file to read

Throws:

java.io.IOException - In case of an IO error while reading the file

java.lang.Exception - In case of error building the parser

loadLogs

public long loadLogs(java.lang.String fileName,
                     ACSRemoteLogListener logListener,
                     ACSRemoteRawLogListener rawLogListener,
                     ACSRemoteErrorListener errorListener,
                     IOPorgressListener progressListener)
              throws java.io.IOException,
                     java.lang.Exception

Load the logs from the file with the given name.

The logs are sent to the ACSRemoteLogListener and /or to the ACSRemoteRawLogListener.

The file can be compressed (GZIP) or plain. Compressed file names must terminate with .gz while plain XML file names must end with .xml.

Parameters:

fileName - The name of the file to read logs from. fileName must terminate with .gz or .xml (case insensitive)

logListener - The callback for each new log read from the IO

rawLogListener - The callback for each new XML log read from the IO

errorListener - The listener for errors

progressListener - The listener to be notified about the bytes read

Returns:

The length of the file to read

Throws:

java.io.IOException - In case of an IO error while reading the file

java.lang.Exception - In case of error building the parser

loadLogs

public void loadLogs(java.io.BufferedReader reader,
                     ACSRemoteLogListener logListener,
                     ACSRemoteRawLogListener rawLogListener,
                     ACSRemoteErrorListener errorListener,
                     IOPorgressListener progressListener)
              throws java.io.IOException

Load the logs from the given BufferedReader.

The logs are sent to the ACSRemoteLogListener and /or to the ACSRemoteRawLogListener.

Parameters:

reader - The reader to read logs from

logListener - The callback for each new log read from the IO

rawLogListener - The callback for each new XML log read from the IO

errorListener - The listener for errors

progressListener - The listener to be notified about the bytes read

Throws:

java.io.IOException - In case of an IO error while reading the file

writeHeader

public void writeHeader(java.io.BufferedWriter wBuffer)
                 throws java.io.IOException

Write the XML header in the buffered writer

Parameters:

bw -

Throws:

java.io.IOException

terminateSave

public void terminateSave(java.io.BufferedWriter outBuffer,
                          boolean close)
                   throws java.io.IOException

Terminate the saving.

This method must executed when the save terminates. It does the following:

• write the closing XML tags
• flush the output file
• close the file

Parameters:

outBuffer - The file to close

close - If true the BufferedWriter is closed

Throws:

java.io.IOException - In case of an IO error

saveLog

public int saveLog(java.io.BufferedWriter outBuf,
                   ILogEntry log)
            throws java.io.IOException

Save a log in the passed file

Parameters:

outbuf - The buffered writer where the logs have to be stored

log - The log to save

progressListener - The listener to be notified about the bytes written

Throws:

java.io.IOException - In case of an IO error while writing logs into the file

saveLogs

public void saveLogs(java.lang.String fileName,
                     java.util.Collection<ILogEntry> logs,
                     IOPorgressListener progressListener,
                     boolean append,
                     boolean gzip)
              throws java.io.IOException

Save a collection of logs on disk

Parameters:

fileName - The name of the file to store logs into

logs - The non empty collection of logs to save

progressListener - The listener to be notified about the number of bytes written

append -

• if true if the logs in the collection must be appended to an existing file
• if false and the file aredy exists, it is deleted before writing

gzip - If true the file is compressed (GZIP) with the default compression level

Throws:

java.io.IOException - In case of error writing

saveLogs

public void saveLogs(java.lang.String fileName,
                     java.util.Collection<ILogEntry> logs,
                     IOPorgressListener progressListener,
                     boolean append,
                     boolean gzip,
                     int compressionLevel)
              throws java.io.IOException

Save a collection of logs on disk

Parameters:

fileName - The name of the file to store logs into

logs - The non empty collection of logs to save

progressListener - The listener to be notified about the number of bytes written

append -

• if true if the logs in the collection must be appended to an existing file
• if false and the file aredy exists, it is deleted before writing

gzip - If true the file is compressed (GZIP)

compressionLevel - The compressionLevel for GZIP compression (0..9); ignored if gzip is is false>/code>

Throws:

java.io.IOException - In case of error writing

saveLogs

public void saveLogs(java.io.BufferedWriter outBuffer,
                     java.util.Collection<ILogEntry> logs,
                     IOPorgressListener progressListener)
              throws java.io.IOException

Save a collection of logs on a BufferedWriter.

The buffer must be initialized and terminated i.e. the prepareSaveFile and the terminateSave are not executed by this method.

Parameters:

outBuffer - The writer to write logs into

logs - The non empty collection of logs to save

progressListener - The listener to be notified about the number of bytes written

gzip - If true the file is compressed (GZIP)

Throws:

java.io.IOException - In case of error writing

saveLogs

public void saveLogs(java.lang.String fileName,
                     java.util.Iterator<ILogEntry> iterator,
                     IOPorgressListener progressListener,
                     boolean append,
                     boolean gzip)
              throws java.io.IOException

Save the logs available through an Iterator.

Parameters:

filename - The name of the file to write logs into

logs - The non empty collection of logs to save

progressListener - The listener to be notified about the number of bytes written

append -

• if true if the logs in the collection must be appended to an existing file
• if false and the file already exists, it is deleted before writing

gzip - If true the file is compressed (GZIP) with the default compression level

Throws:

java.io.IOException - In case of error writing

saveLogs

public void saveLogs(java.lang.String fileName,
                     java.util.Iterator<ILogEntry> iterator,
                     IOPorgressListener progressListener,
                     boolean append,
                     boolean gzip,
                     int compressionLevel)
              throws java.io.IOException

Save the logs available through an Iterator.

Parameters:

filename - The name of the file to write logs into

logs - The non empty collection of logs to save

progressListener - The listener to be notified about the number of bytes written

append -

• if true if the logs in the collection must be appended to an existing file
• if false and the file already exists, it is deleted before writing

gzip - If true the file is compressed (GZIP)

compressionLevel - The compressionLevel for GZIP compression (0..9); ignored if gzip is false>/code>

Throws:

java.io.IOException - In case of error writing

getBufferedWriter

public java.io.BufferedWriter getBufferedWriter(java.lang.String fileName,
                                                boolean append,
                                                boolean gzip,
                                                int compressionLevel)
                                         throws java.io.FileNotFoundException,
                                                java.io.IOException

Create a BufferedWriter to save logs into

Parameters:

fileName - The name of the file to write logs into

append -

• if true if the logs in the collection must be appended to an existing file
• if false and the file already exists, it is deleted before writing

gzip - If true the file is compressed (GZIP)

compressionLevel - The compressionLevel for GZIP compression (0..9); ignored if gzip is false>/code>

Returns:

the BufferedWriter to save logs into the file of the given name

Throws:

java.io.FileNotFoundException

java.io.IOException

getBufferedWriter

public java.io.BufferedWriter getBufferedWriter(java.lang.String fileName,
                                                boolean append,
                                                boolean gzip)
                                         throws java.io.FileNotFoundException,
                                                java.io.IOException

Create a BufferedWriter to save logs into.

In case of compressed files, the default compression level is used

Parameters:

fileName - The name of the file to write logs into

append -

• if true if the logs in the collection must be appended to an existing file
• if false and the file already exists, it is deleted before writing

gzip - If true the file is compressed (GZIP) with the default level

Returns:

the BufferedWriter to save logs into the file of the given name

Throws:

java.io.FileNotFoundException

java.io.IOException

getBufferedReader

public java.io.BufferedReader getBufferedReader(java.lang.String fileName)
                                         throws java.io.FileNotFoundException,
                                                java.io.IOException

Return the reader to get logs from

The reader can be compressed (GZIP) or not depending on the extension of the file name (i.e. ".gz" or ".xml").

Parameters:

fileName - The name of the file to read

Returns:

the reader to get logs from

Throws:

java.io.FileNotFoundException

java.io.IOException

saveLogs

public void saveLogs(java.io.BufferedWriter outBuf,
                     java.util.Iterator<ILogEntry> iterator,
                     IOPorgressListener progressListener)
              throws java.io.IOException

Save a collection of logs on a BufferedWriter.

The buffer must be initialized and terminated i.e. the prepareSaveFile and the terminateSave are not executed by this method.

Parameters:

outBuf - The buffer to write logs into

logs - The non empty collection of logs to save

progressListener - The listener to be notified about the number of bytes written

Throws:

java.io.IOException - In case of error writing

stopIO

public void stopIO()

Call this method if you wish to interrupt a load or a save.

Load and save are executed synchronously so this method has to be called by a separate thread. A typical example is the "Abort" button of a dialog: when the user presses such a button, this method is invoked by the swing thread.