Package com.gurock.smartinspect.protocols

Class 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.

    • 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.