Package com.gurock.smartinspect

Class SmartInspect

  • public class SmartInspect
extends Object
    SmartInspect is the most important class in the SmartInspect Java library. It is an interface for the protocols, packets and sessions and is responsible for the error handling.

    The SmartInspect class is the most important class in the SmartInspect Java library. An instance of this class is able to write log messages to a file or to send them directly to the SmartInspect Console using TCP. You can control these connections by passing a connections string to the setConnections method.

    The SmartInspect class offers several properties for controlling the logging behavior. Besides the setConnections method there is the setEnabled method which controls if log messages should be sent or not. Furthermore, the setAppName method specifies the application name displayed in the SmartInspect Console. And last but not least, we have the setLevel and setDefaultLevel methods which let you specify the log level of an SmartInspect object and its related sessions.

    Additionally, the SmartInspect class acts as parent for sessions, which contain the actual logging methods, like, for example, Session.logMessage or Session.logObject. It is possible and common that several different sessions have the same parent and thus share the same connections. The Session class contains dozens of useful methods for logging any kind of data. Sessions can even log variable watches, generate illustrated process and thread information or control the behavior of the SmartInspect Console. It is possible, for example, to clear the entire log in the Console by calling the Session.clearLog method.

    To accomplish these different tasks the SmartInspect concept uses several different packets. The SmartInspect class manages these packets and logs them to its connections. It is possibility to register event handlers for every packet type which are called after a corresponding packet has been sent.

    The error handling in the SmartInspect Java library is a little bit different from other libraries. This library uses an event, the SmartInspectListener.onError(com.gurock.smartinspect.ErrorEvent), for reporting errors. We've chosen this way because a logging framework should not alter the behavior of an application by firing exceptions. The only exception you need to handle can be thrown by the setConnections method if the setConnections(java.lang.String) contains errors.

    This class is fully threadsafe.

    • Constructor Detail

      • SmartInspect

        public SmartInspect​(String appName)
        Initializes a new instance of the SmartInspect class.
        Parameters:
        appName - The application name used for Log Entries

    • Method Detail

      • now

        public long now()
        Returns the current date and time, optionally with a high resolution.

        If the getResolution method specifies using a high resolution for timestamps, this method tries to return a timestamp with a microsecond resolution.

        The SmartInspect Java library needs an external DLL to be able to use high-resolution timestamps. This DLL is called SmartInspect.Java.dll. If this DLL cannot be found during application startup, high-resolution support is not available. Additionally, even if this DLL is found and loaded correctly, high-resolution timestamps are only available if the QueryPerformanceCounter and QueryPerformanceFrequency Windows functions indicate a successfully working high-resolution performance counter.

        If high-resolution support is not available, this method simply returns the local date and time with the help of the System.currentTimeMillis() function and the default time zone.

        Returns:
        The current local date and time in microseconds since January 1, 1970

      • getResolution

        public ClockResolution getResolution()
        Returns the timestamp resolution mode for this SmartInspect object. This method returns ClockResolution.Standard by default. Please see the setResolution method for detailed information about timestamp resolutions.
        Returns:
        The timestamp resolution mode for this SmartInspect object
        See Also:
        ClockResolution

      • setResolution

        public void setResolution​(ClockResolution resolution)
        Specifies the timestamp resolution mode for this SmartInspect object. By changing this setting, you can specify if this object should try to use high-resolution timestamps for LogEntry, Watch and ProcessFlow packets. High-resolution timestamps provide a microsecond resolution. Conversely, standard timestamps have a maximum resolution of 10-55 milliseconds.

        The SmartInspect Java library needs an external DLL to be able to use high-resolution timestamps. This DLL is called SmartInspect.Java.dll. If this DLL cannot be found during application startup, high-resolution support is not available. Additionally, even if this DLL is found and loaded correctly, high-resolution timestamps are only available if the QueryPerformanceCounter and QueryPerformanceFrequency Windows functions indicate a successfully working high-resolution performance counter.

        Please note that high-resolution timestamps are not intended to be used on production systems. It is recommended to use them only during development and debugging. High-resolution timestamps can introduce several problems that are acceptable on development machines but normally not tolerable on production systems:

        High-resolution timestamp problems
        Problem Description
        Performance High-resolution timestamps can be a lot slower than standard timestamps. This actually depends on the concrete implementation of QueryPerformanceCounter (i.e. which timer is used for the high-resolution performance counter [PIT, PMT, TSC, HPET]), but in general one can say that standard timestamps are a lot faster to read.
        Accuracy High-resolution timestamps tend to deviate from the system timer when seen over a longer period of time. Depending on the particular QueryPerformanceCounter implementation, it can happen that high-resolution timestamps induce an error of milliseconds within a few minutes only.
        Reliability Depending on the used timer, QueryPerformanceCounter provides unreliable results under certain, not so uncommon, circumstances. When the TSC timer is used, multi-processor/multi-core systems or processors with varying frequencies (like found in most modern notebooks or desktop machines) are known to cause several problems which make high-resolution timestamps unsuitable for production usage.

        Due to the mentioned problems, this setting defaults to using the standard timestamp resolution. If null is passed as argument, the timestamp resolution is not changed.

        Parameters:
        resolution - The new timestamp resolution mode for this SmartInspect object
        See Also:
        ClockResolution

      • getVersion

        public static String getVersion()
        Returns the version number of the SmartInspect Java library. This static function returns the current version number of the SmartInspect Java library. The returned string always has the form "MAJOR.MINOR.RELEASE.BUILD"
        Returns:
        The current version number

      • getHostName

        public String getHostName()
        Returns the hostname of the sending machine.

        This method returns the hostname of the current machine. The hostname helps you to identify Log Entries from different machines in the SmartInspect Console.

        Returns:
        The hostname used for the Log Entries

      • getAppName

        public String getAppName()
        The application name helps you to identify Log Entries from different applications in the SmartInspect Console.
        Returns:
        The application name used for the Log Entries

      • setAppName

        public void setAppName​(String appName)
        Sets the application name used for the Log Entries.

        The application name helps you to identify Log Entries from different applications in the SmartInspect Console. If you set this property to null, the application name will be empty when sending Log Entries

        Parameters:
        appName - application name

      • getLevel

        public Level getLevel()
        Returns the log level of this SmartInspect instance and its related sessions.

        The getLevel and setLevel methods of this SmartInspect instance represent the log level used by its corresponding sessions to determine if information should be logged or not. The default return value of this method is Level.Debug.

        Please see the corresponding setLevel method for more information on how to use the log level.

        Returns:
        The log level of this SmartInspect instance and its related sessions

      • setLevel

        public void setLevel​(Level level)
        Sets the log level of this SmartInspect instance and its related sessions.

        The getLevel and setLevel methods of this SmartInspect instance represent the log level used by its corresponding sessions to determine if information should be logged or not. The default log level is Level.Debug.

        Every method (except the clear method family) in the Session class tests if its log level equals or is greater than the log level of its parent. If this is not the case, the methods return immediately and won't log anything.

        The log level for a method in the Session class can either be specified explicitly by passing a Level argument or implicitly by using the setDefaultLevel method. Every method in the Session class which makes use of the parent's log level and does not take a Level argument, uses the setDefaultLevel method of its parent to get the log level.

        Please note that this method does nothing if the supplied level argument is null. For more information about the default level, please refer to the documentation of the setDefaultLevel method.

           import com.gurock.smartinspect.*;
   public class Program {
       static void method() {
           SiAuto.main.enterMethod(Level.Debug, "Method");
           try {
               // ...
           } finally {
               SiAuto.main.leaveMethod(Level.Debug, "Method");
           }
       }
       public static void main(String[] args) {
           SiAuto.si.setEnabled(true);
           SiAuto.si.setLevel(Level.Debug);
           method(); // Logs enterMethod and leaveMethod calls.
           SiAuto.si.setLevel(Level.Message);
           method(); // Ignores enterMethod and leaveMethod calls.
       }
   }
        Parameters:
        level - The new log level

      • getDefaultLevel

        public Level getDefaultLevel()
        Returns the default log level of this SmartInspect instance and its related sessions.

        The getDefaultLevel and setDefaultLevel methods of this SmartInspect instance represent the default log level used by its corresponding sessions. The default return value of this method is Level.Message.

        Please see the corresponding setDefaultLevel method for more information on how to use the default log level.

        Returns:
        The default log level of this SmartInspect instance and its related sessions

      • setDefaultLevel

        public void setDefaultLevel​(Level level)
        Returns the default log level of this SmartInspect instance and its related sessions.

        The getDefaultLevel and setDefaultLevel methods of this SmartInspect instance represent the default log level used by its corresponding sessions. The default value for the default log level is Level.Message.

        Every method in the Session class which makes use of the parent's log level and does not take a Level argument, uses the default level of its parent as log level.

        Please note that this method does nothing if the supplied level argument is null. For more information on how to use this method, please have a look at the following examples.

        Example: 

         import com.gurock.smartinspect.*;

 public class Program {
     static void method() {
         SiAuto.main.enterMethod("Method");
         try {
             // ...
         } finally {
             SiAuto.main.leaveMethod("Method");
         }
     }

     public static void main(String[] args) {
         SiAuto.si.setEnabled(true);

         SiAuto.si.setLevel(Level.Debug);
         SiAuto.si.setDefaultLevel(Level.Verbose);

         // Since the enterMethod and leaveMethod calls do not
         // specify their log level explicitly (by passing a Level
         // argument), they use the default log level which has
         // just been set to Level.Verbose (see above). And since
         // the log level of the SiAuto.si object is set to
         // Level.Debug, the enterMethod and leaveMethod calls will
         // be logged.
         method(); // Logs enterMethod and leaveMethod calls.

         SiAuto.si.setLevel(Level.Message);

         // Since enterMethod and leaveMethod still use Level.Verbose
         // as their log level and the log level of the SiAuto.si
         // object is now set to Level.Message, the enterMethod and
         // leaveMethod calls will be ignored and not be logged.
         method(); // Ignores enterMethod and leaveMethod calls.
     }
 }
        Parameters:
        level - The new default log level

      • isEnabled

        public boolean isEnabled()
        Returns a boolean value which indicates if this instance is enabled or not.
        Returns:
        True if this instance is enabled and false otherwise. See setEnabled for more information

      • setEnabled

        public void setEnabled​(boolean enabled)
        This method allows you to control if anything should be logged at all.

        If you pass true to this method, all internal connections try to connect to their destination. For example, if the connections string is set to "file(filename=c:\\log.sil)", the file "c:\\log.sil" will be opened to write all following packets to it. By passing false, all internal connections will disconnect.

        Additionally, every Session method evaluates if its parent is enabled and returns immediately if this is not the case. This guarantees that the performance loss is minimal when logging is disabled. A SmartInspect instance is disabled by default, so you need to enable it, before you can make use of the SmartInspect instance and its related sessions.

        Please note: If one or more connections of this SmartInspect object operate in asynchronous protocol mode, you must disable this object by setting this property to false before exiting your application to properly exit and cleanup the protocol related threads. Disabling this instance may block until the related protocol threads are finished.

        Parameters:
        enabled - A boolean value to enable or disable this instance

      • loadConnections

        public void loadConnections​(String fileName)
        Overloaded. Loads the connections string from a file and enables this SmartInspect instance.

        This method loads the connections string from a file. This file should be a plain text file containing a line like in the following example:

        connections=file(filename=c:\\log.sil)

        Empty, unrecognized lines and lines beginning with a ';' character are ignored. This version of the method enables logging automatically.

        The Error event is used to notify the application if the specified file cannot be opened or does not contain a connections string. The connections string and the enabled status of this instance are not changed if such an error occurs.

        The Error event is also used if a connections string could be read but is found to be invalid. In this case, an instance of the InvalidConnectionsException exception type is passed to the Error event. Calling this method with the fileName parameter set to null has no effect.

        This method is useful for customizing the connections string after the deployment of an application. A typical use case for this method is the following scenario: imagine a customer who needs to send a log file to customer service to analyse a software problem. If the software in question uses this loadConnections method, the customer service just needs to send a prepared connections file to the customer. To enable the logging, the customer now just needs to drop this file to the application's installation directory or any other predefined location.

        See loadConfiguration for a method which is not limited to loading the connections string, but is also capable of loading any other property of this object from a file.

        The loadConnections and loadConfiguration methods are both capable of detecting the string encoding of the connections and configuration files. Please see the loadConfiguration method for details.

        To automatically replace placeholders in a loaded connections string, you can use so-called connection variables. Please have a look at the setVariable method for more information.

        Parameters:
        fileName - The file to load the connections string from

      • loadConnections

        public void loadConnections​(String fileName,
                            boolean doNotEnable)
        Overloaded. Loads the connections string from a file.

        This method loads the setConnections(java.lang.String) connections string from a file. This file should be a plain text file containing a line like in the following example:

        connections=file(filename=c:\\log.sil)

        Empty, unrecognized lines and lines beginning with a ';' character are ignored. This version of the method enables logging automatically unless the doNotEnable parameter is true. Please note that the doNotEnable parameter has no effect if this SmartInspect instance is already enabled.

        The SmartInspectListener.onError(com.gurock.smartinspect.ErrorEvent) Error event is used to notify the application if the specified file cannot be opened or does not contain a setConnections(java.lang.String) connections string. The setConnections(java.lang.String) connections string and the setEnabled(boolean) enabled status of this instance are not changed if such an error occurs.

        The SmartInspectListener.onError(com.gurock.smartinspect.ErrorEvent) Error event is also used if a connections string could be read but is found to be invalid. In this case, an instance of the InvalidConnectionsException exception type is passed to the SmartInspectListener.onError(com.gurock.smartinspect.ErrorEvent) Error event. Calling this method with the fileName parameter set to null has no effect.

        This version of the method accepts the doNotEnable parameter. If this parameter is set to true, the setEnabled(boolean) enabled status is not changed. Otherwise this SmartInspect instance will be enabled. Calling this method with the fileName parameter set to null has no effect.

        This method is useful for customizing the connections string after the deployment of an application. A typical use case for this method is the following scenario: imagine a customer who needs to send a log file to customer service to analyse a software problem. If the software in question uses this loadConnections method, the customer service just needs to send a prepared connections file to the customer. To enable the logging, the customer now just needs to drop this file to the application's installation directory or any other predefined location.

        See loadConfiguration for a method which is not limited to loading the connections string, but is also capable of loading any other property of this object from a file.

        The loadConnections and loadConfiguration methods are both capable of detecting the string encoding of the connections and configuration files. Please see the loadConfiguration method for details.

        To automatically replace placeholders in a loaded connections string, you can use so called connection variables. Please have a look at the setVariable method for more information.

        Parameters:
        fileName - The file to load the connections string from
        doNotEnable - Specifies if this instance shouldn't be enabled automatically

      • getConnections

        public String getConnections()
        Please see the setConnections method for a detailed description of the connections string and its function.
        Returns:
        The connections string of this instance

      • setConnections

        public void setConnections​(String connections)
                    throws InvalidConnectionsException
        Sets all connections used by a SmartInspect instance.

        You can set multiple connections by separating the connections with commas. A connection consists of a protocol identifier like "file" plus optional protocol parameters in parentheses. If you, for example, want to log to a file, the connections string must be set to "file()". You can specify the filename in the parentheses after the protocol identifier like this: "file(filename=\"c:\\mylogfile.sil\")". Note that only if this instance is enabled, the connections try to connect to their destinations immediately. By default, no connections are used.

        See the Protocol class for a list of available protocols and ProtocolFactory for a way to add your own custom protocols. Furthermore have a look at the loadConnections and loadConfiguration methods, which can load a connections string from a file. Also, for a class which assists in building connections strings, please refer to the documentation of the ConnectionsBuilder class. To automatically replace placeholders in the given connections string, you can use so called connection variables. Please have a look at the setVariable method for more information.

        Please note that an InvalidConnectionsException exception is thrown if an invalid connections string is supplied. 

         SiAuto.si.setConnections("");
 SiAuto.si.setConnections("file()");
 SiAuto.si.setConnections("file(filename=\"log.sil\", append=true)");
 SiAuto.si.setConnections("file(append=true), tcp(host=\"localhost\")");
 SiAuto.si.setConnections("file(), file(filename=\"anotherlog.sil\")");
        Parameters:
        connections - connection string
        Throws:
        InvalidConnectionsException - if invalid syntax, unknown protocols or inexistent options are found

      • loadConfiguration

        public void loadConfiguration​(String fileName)
        Loads the properties and sessions of this SmartInspect instance from a file. The given file should be a plain text file containing key/value pairs. Each key/value pair is expected to be on its own line. Empty, unrecognized lines and lines beginning with a ';' character are ignored. The SmartInspectListener.onError event is used to notify the application if an error occurs while trying to load the configuration from the specified file. Such errors include I/O errors like trying to open a file which does not exist, for example. The SmartInspectListener.onError event is also used if the specified configuration file contains an invalid connections string. In this case, an instance of the InvalidConnectionsException exception type is passed to the Error event.

        Note:

        • Calling this method with the fileName parameter set to null has no effect.
        • To monitor a SmartInspect configuration file for changes, please have a look at the ConfigurationTimer class.
        • The case of the configuration properties doesn't matter. This means, it makes no difference if you specify 'defaultlevel' or 'DefaultLevel' as key, for example.
        • This method is particularly useful for loading the properties of this SmartInspect instance after the deployment of an application. A typical use case for this method is the following scenario: imagine a customer who needs to send a log file to customer service to analyse a software problem. If the software in question uses this loadConfiguration method, the customer service just needs to send a prepared configuration file to the customer.

        Refer to @example for a typical configuration file format.

        Parameters:
        fileName - The name of the file to load the configuration from.
        See Also:
        ConfigurationTimer, LoadConfigurationException, InvalidConnectionsException

      • dispatch

        public void dispatch​(String caption,
                     int action,
                     Object state)
        Executes a custom protocol action of a connection.

        This method dispatches the action and state parameters to the connection identified by the caption argument. If no suitable connection can be found, the Error event is used. The Error event is also used if an exception is thrown in the custom protocol action.

        The SmartInspect Java library currently implements one custom protocol action in MemoryProtocol. The MemoryProtocol class is used for writing log packets to memory. On request, it can write its internal queue of packets to a user-supplied stream or Protocol object with a custom protocol action.

        The request for executing the custom action and writing the queue can be initiated with this dispatch method. Please see the example section below for details.

        For more information about custom protocol actions, please refer to the Protocol.dispatch(com.gurock.smartinspect.protocols.ProtocolCommand) method. Also have a look at Protocol.isValidOption() method which explains how to set the caption of a connection.

        Please note that the custom protocol action is executed asynchronously if the requested connection operates in asynchronous protocol mode.

        If the supplied caption argument is null, this method does nothing and returns immediately. 

         // Set the connections string and enable logging. We do not
 // specify a caption for the memory connection and stick with
 // the default. By default, the caption of a connection is set
 // to the name of the protocol, in our case 'mem'.
 SiAuto.si.setConnections("mem()");
 SiAuto.si.setEnabled(true);

 // Instrument your application with log statements as usual.
 SiAuto.main.logMessage("This is a message");
 SiAuto.main.logMessage("This is a message");

 // Then, in case of an unexpected event, for example, in a
 // global exception handler, you can write the entire queue
 // of packets of your memory protocol connection to a file
 // by using the dispatch method.
 OutputStream os = new FileOutputStream("log.sil");
 try
 {
        SiAuto.si.dispatch("mem", 0, os);
 }
 finally
 {
        os.close();
 }
 
         ...

 // Alternative dispatch call with a Protocol object which
 // sends the queue content to a local Console via a named
 // pipe.
 Protocol p = new PipeProtocol();
 try
 {
        // Optionally set some protocol options
        // p.initialize("");
        p.connect();
        try
        {
                SiAuto.si.dispatch("mem", 0, p);
        }
        finally
        {
                p.disconnect();
        }
 }
 finally
 {
        p.dispose();
 }
        Parameters:
        caption - The identifier of the connection. Not allowed to be null
        action - The action to execute by the requested connection
        state - An optional object which encapsulates additional protocol specific information about the custom action. Can be null
        See Also:
        Protocol.dispatch(com.gurock.smartinspect.protocols.ProtocolCommand)

      • getSessionDefaults

        public SessionDefaults getSessionDefaults()
        Returns the default property values for new sessions. This method lets you specify the default property values for new sessions which will be created by or passed to the addSession method. Please see the addSession method for details. For information about the available session properties, please refer to the documentation of the Session class.
        Returns:
        The default property values for new sessions

      • setVariable

        public void setVariable​(String key,
                        String value)
        Adds a new or updates an existing connection variable. This method sets the value of a given connection variable. A connection variable is a placeholder for strings in the connections string. When setting a connections string (or loading it from a file with loadConfiguration), any variables which have previously been defined with setVariable are automatically replaced with their respective values. The variables in the connections string are expected to have the following form: $variable$. If a connection variable with the given key already exists, its value is overridden. To delete a connection variable, use unsetVariable. This method does nothing if the key or value argument is null. Connection variables are especially useful if you load a connections string from a file and would like to handle some protocol options in your application instead of the configuration file. For example, if you encrypt log files, you probably do not want to specify the encryption key directly in your configuration file for security reasons. With connection variables, you can define a variable for the encryption key with setVariable and then reference this variable in your configuration file. The variable is then automatically replaced with the defined value when loading the configuration file. Another example deals with the directory or path of a log file. If you include a variable in the path of your log file, you can later replace it in your application with the real value. This might come in handy if you want to write a log file to an environment specific value, such as an application data directory, for example.

        Example: 

           // Define the variable "key" with the value "secret"
   SiAuto.si.setVariable("key", "secret");
   ...
   // And include the variable $key$ in the related connections
   // string (the connections string can either be set directly
   // or loaded from a file).
   file(encrypt="true", key="$key$")
        Parameters:
        key - The key of the connection variable
        value - The value of the connection variable

      • getVariable

        public String getVariable​(String key)
        Returns the value of a connection variable. Please see the setVariable method for more information about connection variables.
        Parameters:
        key - The key of the connection variable
        Returns:
        The value for the given connection variable or null if the connection variable is unknown

      • unsetVariable

        public void unsetVariable​(String key)
        Unsets an existing connection variable

        This method deletes the connection variable specified by the given key. Nothing happens if the connection variable doesn't exist or if the passed key is null.

        Parameters:
        key - The key of the connection variable to delete

      • addSession

        public Session addSession​(String sessionName)
        Adds and returns a new Session instance with this SmartInspect object set as parent. This method allocates a new session with this SmartInspect instance set as parent and the supplied sessionName parameter set as session name. The returned session will be configured with the default session properties as specified by the getSessionDefaults method. This default configuration can be overridden on a per-session basis by loading the session configuration with the loadConfiguration method. Please see the loadConfiguration documentation for details. This version of the method does not save the returned session for later access.
        Parameters:
        sessionName - The name for the new session. Not allowed to be null
        Returns:
        The new Session instance or null if the supplied sessionName parameter is null

      • addSession

        public Session addSession​(String sessionName,
                          boolean store)
        Overloaded. Adds and returns a new Session instance with this SmartInspect object set as parent and optionally saves it for later access.

        This method allocates a new session with this SmartInspect instance set as parent and the supplied sessionName parameter set as session name. The returned session will be configured with the default session properties as specified by the getSessionDefaults method. This default configuration can be overridden on a per-session basis by loading the session configuration with the loadConfiguration method. Please see the loadConfiguration documentation for details.

        If the 'store' parameter is true, the created and returned session is stored for later access and can be retrieved with the getSession method. To remove a created session from the internal list, call the deleteSession method.

        If this method is called multiple times with the same session name, then the getSession method operates on the session which got added last. If the sessionName parameter is null, this method does nothing and returns null as well

        Parameters:
        sessionName - The name for the new session. Not allowed to be null
        store - Indicates if the newly created session should be stored for later access
        Returns:
        The new Session instance or null if the supplied sessionName parameter is null

      • addSession

        public void addSession​(Session session)
        Overloaded. Adds an existing Session instance to the internal list of sessions and saves it for later access.

        This method adds the passed session to the internal list of sessions and saves it for later access. The passed session will be configured with the default session properties as specified by the getSessionDefaults method. This default configuration can be overridden on a per-session basis by loading the session configuration with the loadConfiguration method. Please see the loadConfiguration documentation for details.

        The passed session can later be retrieved with the getSession method. To remove an added session from the internal list, call the deleteSession method.

        Parameters:
        session - The session to store

      • deleteSession

        public void deleteSession​(Session session)
        Removes a session from the internal list of sessions. This method removes a session which has previously been added with and returned by the addSession method. After this method returns, the getSession method returns null when called with the same session name unless a different session with the same name has been added. This method does nothing if the supplied session argument is null.
        Parameters:
        session - The session to remove from the lookup table of sessions. Not allowed to be null.

      • getSession

        public Session getSession​(String sessionName)
        Returns a previously added session.

        This method returns a session which has previously been added with the addSession method and can be identified by the supplied sessionName argument. If the requested session is unknown or if the sessionName argument is null, this method returns null.

        Note that the behavior of this method can be unexpected in terms of the result value if multiple sessions with the same name have been added. In this case, this method returns the session which got added last and not necessarily the session which you expect.

        Adding multiple sessions with the same name should therefore be avoided.

        Parameters:
        sessionName - The name of the session to lookup and return. Not allowed to be null
        Returns:
        The requested session or null if the supplied sessionName is null or if the session is unknown

      • updateSession

        public void updateSession​(Session session,
                          String to,
                          String from)
        Updates an entry in the internal lookup table of sessions.

        Once the name of a session has changed, this method is called to update the internal session lookup table. The to parameter specifies the new name and the from name the old name of the session. After this method returns, the new name can be passed to the getSession method to lookup the supplied session.

        Parameters:
        session - The session whose name has changed and whose entry should be updated
        to - The new name of the session
        from - The old name of the session

      • addListener

        public void addListener​(SmartInspectListener listener)
        Adds a new listener for the events of this object.

        This methods adds a new listener for the events of this SmartInspect object. This can be useful to customize the logging behavior or get informed about errors. Please see the SmartInspectListener interface for event examples and details. Also see the documentation of the SmartInspectAdapter class which simplifies the event handling.

        Parameters:
        listener - The listener to add

      • removeListener

        public void removeListener​(SmartInspectListener listener)
        Removes an existing listener for the events of this object.

        This method removes the supplied listener from the event system of this object. After the listener has been removed, it will no longer be notified about any events of this object.

        Parameters:
        listener - The listener to remove

      • clearListeners

        public void clearListeners()
        Removes all registered listeners for the events of this object.

        This method removes all registered event listeners. After calling this method, the previously registered listeners will no longer be notified about any events of this object.

      • doFilter

        protected boolean doFilter​(Packet packet)
        Invokes the Filter event handlers and determines if the supplied packet should be sent or not. Derived classes can override this method to intercept the Filter event.
        Parameters:
        packet - The packet which is about to be processed
        Returns:
        True if the supplied packet shall be filtered and thus not be sent and false otherwise

      • doWatch

        protected void doWatch​(Watch watch)
        Invokes the Watch event handlers.

        Derived classes can override this method to intercept the Watch event.

        Parameters:
        watch - The Watch which has just been processed

      • doProcessFlow

        protected void doProcessFlow​(ProcessFlow processFlow)
        Invokes the Process Flow event handlers.

        Derived classes can override this method to intercept the Process Flow event.

        Parameters:
        processFlow - The Process Flow entry which has just been processed

      • sendLogEntry

        public final void sendLogEntry​(LogEntry logEntry)
        Logs a Log Entry. After setting the application name and hostname of the supplied Log Entry, this method determines if the Log Entry should really be sent by invoking the doFilter method. If the Log Entry passes the filter test, it will be logged and the SmartInspectListener.onLogEntry event is fired.
        Parameters:
        logEntry - The Log Entry to log

      • sendControlCommand

        public final void sendControlCommand​(ControlCommand controlCommand)
        Logs a Control Command.

        At first, this method determines if the Control Command should really be sent by invoking the doFilter method. If the Control Command passes the filter test, it will be logged and the SmartInspectListener.onControlCommand event is fired

        Parameters:
        controlCommand - The Control Command to log

      • sendWatch

        public final void sendWatch​(Watch watch)
        Logs a Watch.

        At first, this method determines if the Watch should really be sent by invoking the doFilter method. If the Watch passes the filter test, it will be logged and the SmartInspectListener.onWatch event is fired.

        Parameters:
        watch - The Watch to log

      • sendProcessFlow

        public final void sendProcessFlow​(ProcessFlow processFlow)
        Logs a Process Flow entry. After setting the hostname of the supplied Process Flow entry, this method determines if the Process Flow entry should really be sent by invoking the doFilter method. If the Process Flow entry passes the filter test, it will be logged and the SmartInspectListener.onProcessFlow event is fired.
        Parameters:
        processFlow - The Process Flow entry to log

      • dispose

        public void dispose()
        Releases all resources of this SmartInspect object.

        This method disconnects and removes all internal connections and disables this instance. Moreover, all previously stored sessions will be removed.