com.gurock.smartinspect.protocols

Class FileProtocol

java.lang.Object

com.gurock.smartinspect.protocols.Protocol

com.gurock.smartinspect.protocols.FileProtocol

Direct Known Subclasses:

TextProtocol

public class FileProtocol
extends Protocol

The FileProtocol serves as a standard SmartInspect protocol for writing log packets to a log file. This class serves as the base for all protocol classes that deal with log files. The default behavior of using the binary log file format is compatible with the Console. This behavior can be modified in classes that derive from this base class. For instance, creating plain text files can be done by TextProtocol class. A number of options are provided by file protocol which includes log rotation (by size and date), encryption and I/O buffers. For the complete list of available protocol options, one can refer to the isValidOption method.

Thread safety: The public members of this class are threadsafe.

Field Summary

Fields inherited from class com.gurock.smartinspect.protocols.Protocol

fConnected

Constructor Summary

Constructors

Constructor and Description
FileProtocol() Creates and initializes a new FileProtocol instance.

Method Summary

Modifier and Type	Method and Description
protected void	buildOptions(ConnectionsBuilder builder) Overridden.
protected String	getDefaultFileName() Returns the default filename for this log file protocol.
protected Formatter	getFormatter() Returns the formatter for this log file protocol.
protected String	getName() Overridden.
protected OutputStream	getStream(OutputStream stream) Intended to provide a wrapper stream for the underlying file stream.
protected void	internalConnect() Overridden.
protected void	internalDisconnect() Overridden.
protected void	internalWritePacket(Packet packet) Overridden.
protected boolean	isValidOption(String name) Overridden.
protected void	loadOptions() Overridden.
protected void	writeFooter(OutputStream stream) Overridden.
protected long	writeHeader(OutputStream stream, long size) Overridden.

Methods inherited from class com.gurock.smartinspect.protocols.Protocol

addListener, composeLogHeaderPacket, connect, disconnect, dispatch, dispose, doError, failed, getAppName, getAsyncEnabledDefaultValue, getAsyncQueueDefaultValue, getBooleanOption, getBytesOption, getCaption, getHostName, getIntegerOption, getLevelOption, getReconnectDefaultValue, getRotateOption, getSizeOption, getStringOption, getTimespanOption, handleException, implConnect, implDisconnect, implDispatch, implWritePacket, initialize, internalDispatch, internalReconnect, internalWriteLogHeader, isAsynchronous, removeListener, reset, scheduleWritePacket, setAppName, setHostName, writePacket

Methods inherited from class java.lang.Object

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

Constructor Detail

FileProtocol

public FileProtocol()

Creates and initializes a new FileProtocol instance. For a list of available file protocol options, please refer to the isValidOption method.

Method Detail

getName

protected String getName()

Overridden. Returns "file".

Specified by:

getName in class Protocol

Returns:

Just "file". Derived classes can change this behavior by overriding this method.

getFormatter

protected Formatter getFormatter()

Returns the formatter for this log file protocol. The standard implementation of this method returns an instance of the BinaryFormatter class. Derived classes can change this behavior by overriding this method.

Returns:

The formatter for this log file protocol.

getDefaultFileName

protected String getDefaultFileName()

Returns the default filename for this log file protocol.

The standard implementation of this method returns the string "log.sil" here. Derived classes can change this behavior by overriding this method.

Returns:

The default filename for this log file protocol.

getStream

protected OutputStream getStream(OutputStream stream)

Intended to provide a wrapper stream for the underlying file stream. This method can be used by custom protocol implementers to wrap the underlying file stream into a filter stream. Such filter streams could include streams for encrypting or compressing log files, for example. By default, this method simply returns the passed stream argument.

Parameters:

stream - The underlying file stream.

Returns:

The wrapper stream.

isValidOption

protected boolean isValidOption(String name)

Overridden. Validates if a protocol option is supported.

The following table lists all valid options, their default values and descriptions for the file protocol.

File protocol options

Valid Options	Default Value	Description
append	false	Specifies if new packets should be appended to the destination file instead of overwriting the file first.
buffer	0	Specifies the I/O buffer size in kilobytes. It is possible to specify size units like this: "1 MB". Supported units are "KB", "MB" and "GB". A value of 0 disables this feature. Enabling the I/O buffering greatly improves the logging performance but has the disadvantage that log packets are temporarily stored in memory and are not immediately written to disk.
encrypt	false	Specifies if the resulting log file should be encrypted. Note that the 'append' option cannot be used with encryption enabled. If encryption is enabled the 'append' option has no effect.
filename	[varies]	Specifies the filename of the log.
key	[empty]	Specifies the secret encryption key as string if the 'encrypt' option is enabled.
maxparts	[varies]	Specifies the maximum amount of log files at any given time when log rotating is enabled or the maxsize option is set. Specify 0 for no limit. See below for information on the default value for this option.
maxsize	0	Specifies the maximum size of a log file in kilobytes. When this size is reached, the current log file is closed and a new file is opened. The maximum amount of log files can be set with the maxparts option. It is possible to specify size units like this: "1 MB". Supported units are "KB", "MB" and "GB". A value of 0 disables this feature.
rotate	none	Specifies the rotate mode for log files. Please see below for a list of available values. A value of "none" disables this feature. The maximum amount of log files can be set with the maxparts option.

When using the standard binary log file protocol ("file" in the SmartInspect.setConnections), the default filename is set to "log.sil". When using text log files ("text" in the SmartInspect.setConnections), the default filename is "log.txt".

Example usage:

 SiAuto.si.setConnections("file()");
 SiAuto.si.setConnections("file(filename=\"log.sil\", append=true)");
 SiAuto.si.setConnections("file(filename=\"log.sil\")");
 SiAuto.si.setConnections("file(maxsize=\"16MB\", maxparts=5)");
 SiAuto.si.setConnections("file(rotate=weekly)");
 SiAuto.si.setConnections("file(encrypt=true, key=\"secret\")");
 

Overrides:

isValidOption in class Protocol

Parameters:

name - The option name to validate.

Returns:

True if the option is supported and false otherwise.

buildOptions

protected void buildOptions(ConnectionsBuilder builder)

Overridden. Fills a ConnectionsBuilder instance with the options currently used by this file protocol.

Overrides:

buildOptions in class Protocol

Parameters:

builder - The ConnectionsBuilder object to fill with the current options of this protocol.

loadOptions

protected void loadOptions()

Overridden. Loads and inspects file specific options.

This method loads all relevant options and ensures their correctness. See isValidOption for a list of options which are recognized by the file protocol.

Overrides:

loadOptions in class Protocol

internalConnect

protected void internalConnect()
                        throws Exception

Overridden. Opens the destination file.

This method tries to open the destination file, which can be specified by passing the "filename" option to the initialize method. For other valid options which might affect the behavior of this method, please see the isValidOption method.

Specified by:

internalConnect in class Protocol

Throws:

Exception - if opening the destination file failed.

writeHeader

protected long writeHeader(OutputStream stream,
                           long size)
                    throws IOException

Overridden. Intended to write the header of a log file. This default implementation of this method writes the standard binary protocol header to the supplied OutputStream instance. Derived classes may change this behavior by overriding this method.

Parameters:

stream - The stream to which the header should be written to.

size - Specifies the current size of the supplied stream.

Returns:

The new size of the stream after writing the header. If no header is written, the supplied size argument is returned.

Throws:

IOException - io exception

writeFooter

protected void writeFooter(OutputStream stream)

Overridden. Intended to write the footer of a log file.

The implementation of this method does nothing. Derived class may change this behavior by overriding this method.

Parameters:

stream - The stream to which the footer should be written to.

internalWritePacket

protected void internalWritePacket(Packet packet)
                            throws Exception

Overridden. Writes a packet to the destination file.

If the "maxsize" option is set and the supplied packet would exceed the maximum size of the destination file, then the current log file is closed and a new file is opened. Additionally, if the "rotate" option is active, the log file is rotated if necessary. Please see the documentation of the isValidOption method for more information.

Specified by:

internalWritePacket in class Protocol

Parameters:

packet - The packet to write.

Throws:

Exception - If writing the packet to the destination file fails.

internalDisconnect

protected void internalDisconnect()
                           throws Exception

Overridden. Closes the destination file.

This method closes the underlying file handle if previously created and disposes any supplemental objects.

Specified by:

internalDisconnect in class Protocol

Throws:

Exception - if closing the destination file fails.