com.gurock.smartinspect

Class SmartInspect

java.lang.Object

com.gurock.smartinspect.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 Summary

Constructors

Constructor and Description
SmartInspect(String appName) Initializes a new instance of the SmartInspect class.

Method Summary

Modifier and Type	Method and Description
void	addListener(SmartInspectListener listener) Adds a new listener for the events of this object.
void	addSession(Session session) Overloaded.
Session	addSession(String sessionName) Adds and returns a new Session instance with this SmartInspect object set as parent.
Session	addSession(String sessionName, boolean store) Overloaded.
void	clearListeners() Removes all registered listeners for the events of this object.
void	deleteSession(Session session) Removes a session from the internal list of sessions.
void	dispatch(String caption, int action, Object state) Executes a custom protocol action of a connection.
void	dispose() Releases all resources of this SmartInspect object.
protected void	doControlCommand(ControlCommand controlCommand) Invokes the Control Command event handlers.
protected void	doError(Exception ex) Invokes the Error event handlers.
protected boolean	doFilter(Packet packet) Invokes the Filter event handlers and determines if the supplied packet should be sent or not.
protected void	doLogEntry(LogEntry logEntry) Invokes the Log Entry event handlers.
protected void	doProcessFlow(ProcessFlow processFlow) Invokes the Process Flow event handlers.
protected void	doWatch(Watch watch) Invokes the Watch event handlers.
String	getAppName() The application name helps you to identify Log Entries from different applications in the SmartInspect Console.
String	getConnections() Please see the setConnections method for a detailed description of the connections string and its function.
Level	getDefaultLevel() Returns the default log level of this SmartInspect instance and its related sessions.
String	getHostName() Returns the hostname of the sending machine.
Level	getLevel() Returns the log level of this SmartInspect instance and its related sessions.
ClockResolution	getResolution() Returns the timestamp resolution mode for this SmartInspect object.
Session	getSession(String sessionName) Returns a previously added session.
SessionDefaults	getSessionDefaults() Returns the default property values for new sessions.
String	getVariable(String key) Returns the value of a connection variable.
static String	getVersion() Returns the version number of the SmartInspect Java library.
boolean	isEnabled() Returns a boolean value which indicates if this instance is enabled or not.
void	loadConfiguration(String fileName) Loads the properties and sessions of this SmartInspect instance from a file.
void	loadConnections(String fileName) Overloaded.
void	loadConnections(String fileName, boolean doNotEnable) Overloaded.
long	now() Returns the current date and time, optionally with a high resolution.
void	removeListener(SmartInspectListener listener) Removes an existing listener for the events of this object.
void	sendControlCommand(ControlCommand controlCommand) Logs a Control Command.
void	sendLogEntry(LogEntry logEntry) Logs a Log Entry.
void	sendProcessFlow(ProcessFlow processFlow) Logs a Process Flow entry.
void	sendWatch(Watch watch) Logs a Watch.
void	setAppName(String appName) Sets the application name used for the Log Entries.
void	setConnections(String connections) Sets all connections used by a SmartInspect instance.
void	setDefaultLevel(Level level) Returns the default log level of this SmartInspect instance and its related sessions.
void	setEnabled(boolean enabled) This method allows you to control if anything should be logged at all.
void	setLevel(Level level) Sets the log level of this SmartInspect instance and its related sessions.
void	setResolution(ClockResolution resolution) Specifies the timestamp resolution mode for this SmartInspect object.
void	setVariable(String key, String value) Adds a new or updates an existing connection variable.
void	unsetVariable(String key) Unsets an existing connection variable This method deletes the connection variable specified by the given key.
void	updateSession(Session session, String to, String from) Updates an entry in the internal lookup table of sessions.

Methods inherited from class java.lang.Object

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

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

doLogEntry

protected void doLogEntry(LogEntry logEntry)

Invokes the Log Entry event handlers.

Derived classes can override this method to intercept the SmartInspectListener.onLogEntry(com.gurock.smartinspect.packets.logentry.LogEntryEvent).

Parameters:

logEntry - The Log Entry which has just been processed

doControlCommand

protected void doControlCommand(ControlCommand controlCommand)

Invokes the Control Command event handlers.

Derived classes can override this method to intercept the Control Command event. SmartInspectListener.onControlCommand(com.gurock.smartinspect.packets.controlcommand.ControlCommandEvent)

Parameters:

controlCommand - The Control Command which has just been processed

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

doError

protected void doError(Exception ex)

Invokes the Error event handlers. Derived classes can override this method to intercept the SmartInspectListener.onError(com.gurock.smartinspect.ErrorEvent)

Parameters:

ex - The occurred exception

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.