com.gurock.smartinspect.protocols

Class Protocol

java.lang.Object

com.gurock.smartinspect.protocols.Protocol

Direct Known Subclasses:

FileProtocol, MemoryProtocol, PipeProtocol, TcpProtocol

public abstract class Protocol
extends Object

This is the abstract base class for a protocol. A protocol is responsible for transporting packets.

A protocol is responsible for the transport of packets. This base class offers all necessary methods to handle the protocol options, and it declares several abstract protocol specific methods for handling protocol destinations like connecting or writing packets.

The following table lists the available protocols together with their identifier in the connections string and a short description.

Available protocols

Protocol	Identifier	Description
FileProtocol	"file"	Used for writing log files in the standard SmartInspect binary log file format which can be loaded into the Console.
MemoryProtocol	"mem"	Used for writing log data to memory and saving it to a stream on request.
PipeProtocol	"pipe"	Used for sending log data over a named pipe directly to a local Console.
TcpProtocol	"tcp"	Used for sending packets over a TCP connection directly to the Console.
TextProtocol	"text"	Used for writing log files in a customizable text format. Best suited for end-user notification purposes.

There are several options which are common to all protocols and beyond that each protocol has its own set of additional options. For those protocol specific options, please refer to the documentation of the corresponding protocol class. Protocol options can be set with Initialize and derived classes can query option values using the Get methods.

The public members of this class are threadsafe.

Field Summary

Fields

Modifier and Type	Field and Description
protected boolean	fConnected

Constructor Summary

Constructors

Constructor and Description
Protocol() Creates and initializes a Protocol subclass instance.

Method Summary

Modifier and Type	Method and Description
void	addListener(ProtocolListener listener) Adds a new listener for the events of this object.
protected void	buildOptions(ConnectionsBuilder builder) Fills a ConnectionsBuilder instance with the options currently used by this protocol.
protected LogHeader	composeLogHeaderPacket()
void	connect() Connects to the protocol destination.
void	disconnect() Disconnects from the protocol destination.
void	dispatch(ProtocolCommand command) Dispatches a custom action to a concrete implementation of a protocol.
void	dispose() Disconnects from the protocol destination.
protected void	doError(Exception ex) Invokes the ProtocolListener.onError event handlers.
boolean	failed() Returns if the last executed connection-related operation of this protocol has failed.
String	getAppName() Returns the application name of this protocol.
protected boolean	getAsyncEnabledDefaultValue() Defines the default value for `async.enabled` option as `false`.
protected int	getAsyncQueueDefaultValue() Defines the default value for `async.queue` option as 2 megabytes.
protected boolean	getAsyncThrottleDefaultValue() Defines the default value for `async.throttle` option as `false`.
protected boolean	getBooleanOption(String key, boolean defaultValue) A Boolean value will be treated as true if the value of the key matches either "true", "yes" or "1" and as false otherwise.
byte[]	getBytesOption(String key, int size, byte[] defaultValue) Gets the byte array value of a key.
String	getCaption() Returns the caption of this protocol.
String	getHostName() Returns the hostname of this protocol.
protected int	getIntegerOption(String key, int defaultValue) Gets the integer value of a key.
protected Level	getLevelOption(String key, Level defaultValue) This method returns the defaultValue argument if either the supplied key is unknown or the found value is not a valid Level value.
protected abstract String	getName() Specifies the name of a real protocol implementation.
protected boolean	getReconnectDefaultValue() Defines the default value for `reconnect` option as `true`.
protected FileRotate	getRotateOption(String key, FileRotate defaultValue) Gets a FileRotate value of a key.
protected long	getSizeOption(String key, long defaultValue) Gets an integer value of a key.
protected String	getStringOption(String key, String defaultValue) Gets the string of a key.
protected long	getTimespanOption(String key, long defaultValue) Gets an integer value of a key.
protected void	handleException(String message) Handles a protocol exception.
void	implConnect()
void	implDisconnect()
void	implDispatch(ProtocolCommand command)
void	implWritePacket(Packet packet)
void	initialize(String options) Sets and initializes the options of this protocol.
protected abstract void	internalConnect() Connects to the protocol destination.
protected abstract void	internalDisconnect() Disconnects from the protocol destination.
protected void	internalDispatch(ProtocolCommand command) Executes a protocol specific custom action.
protected boolean	internalReconnect() Reconnects to the protocol specific destination.
protected void	internalWriteLogHeader()
protected abstract void	internalWritePacket(Packet packet) Writes a packet to the protocol destination.
boolean	isAsynchronous() Indicates if this protocol is operating in asynchronous protocol mode.
protected boolean	isValidOption(String name) Validates if an option is supported by this protocol.
protected void	loadOptions() Loads and inspects protocol specific options.
void	removeListener(ProtocolListener listener) Removes a new listener for the events of this object.
protected void	reset() Resets the protocol and brings it into a consistent state.
void	scheduleWritePacket(Packet packet, SchedulerQueue.QueueEnd insertTo)
void	setAppName(String appName) Sets the application name of this protocol.
void	setHostName(String hostName) Sets the hostname of this protocol.
void	writePacket(Packet packet) Writes a packet to the protocol specific destination.

Methods inherited from class java.lang.Object

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

Field Detail

fConnected

protected boolean fConnected

Constructor Detail

Protocol

public Protocol()

Creates and initializes a Protocol subclass instance. For a list of protocol options common to all protocols, please refer to the isValidOption method.

Method Detail

handleException

protected void handleException(String message)
                        throws ProtocolException

Handles a protocol exception.

This method handles an occurred protocol exception. It first sets the Failed flag and creates a ProtocolException object with the name and options of this protocol. In normal blocking mode (see IsValidOption), it then throws this exception. When operating in asynchronous mode, it invokes the Error event handlers instead and does not throw an exception.

Parameters:

message - The exception message

Throws:

ProtocolException - Always in normal blocking mode, never in asynchronous mode

buildOptions

protected void buildOptions(ConnectionsBuilder builder)

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

The filled options string consists of key, value option pairs separated by commas.

This function takes care of the options common to all protocols. To include protocol specific options, override this function.

Parameters:

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

initialize

public void initialize(String options)
                throws SmartInspectException

Sets and initializes the options of this protocol.

This method expects an options string which consists of key, value pairs separated by commas like this: "filename=log.sil, append=true". To use a comma in a value, you can use quotation marks like in the following example: "filename=\"log.sil\", append=true".

Please note that a SmartInspectException exception is thrown if a wrong options string is assigned. A wrong options string could use an invalid syntax or contain one or more unknown option keys. This method can be called only once. Further calls have no effect. Pass null or an empty string to use the default options of a particular protocol.

Parameters:

options - The new protocol options

Throws:

SmartInspectException - If invalid options syntax, an unknown option key

getStringOption

protected String getStringOption(String key,
                                 String defaultValue)

Gets the string of a key.

Parameters:

key - The key to search for

defaultValue - The value to return if the key does not exist. Note that this method can throw an exception of type NullPointerException if you pass a null reference as key

Returns:

Either the value if the key exists or defaultValue otherwise

Throws:

NullPointerException - If the key argument is null

getIntegerOption

protected int getIntegerOption(String key,
                               int defaultValue)

Gets the integer value of a key.

Please note that if a related value could be found but is not a valid integer, the supplied default value will be returned. Only non-negative integers will be recognized as valid values. Note that this method can throw an exception of type NullPointerException if you pass a null reference as key.

Parameters:

key - The key to search for

defaultValue - The value to return if the key does not exist

Returns:

Either the value if the key exists and is a valid integer or defaultValue otherwise

Throws:

NullPointerException - If the key argument is null

getBooleanOption

protected boolean getBooleanOption(String key,
                                   boolean defaultValue)

A Boolean value will be treated as true if the value of the key matches either "true", "yes" or "1" and as false otherwise. Note that this method can throw an exception of type NullPointerException if you pass a null reference as key.

Parameters:

key - The key to search for

defaultValue - The value to return if the key does not exist

Returns:

Either the value if the key exists or defaultValue otherwise

Throws:

NullPointerException - If the key argument is null

getLevelOption

protected Level getLevelOption(String key,
                               Level defaultValue)

This method returns the defaultValue argument if either the supplied key is unknown or the found value is not a valid Level value. Please see the Level enum for more information on the available values. Note that this method can throw an exception of type NullPointerException if you pass a null reference as key.

Parameters:

key - The key whose value to return

defaultValue - The value to return if the given key is unknown

Returns:

Either the value converted to the corresponding Level value for the given key if an element with the given key exists and the found value is a valid Level value or defaultValue otherwise

Throws:

NullPointerException - if the key argument is null

getSizeOption

protected long getSizeOption(String key,
                             long defaultValue)

Gets an integer value of a key. The integer value is interpreted as a byte size, and it is supported to specify byte units. This method returns the defaultValue argument if either the supplied key is unknown or the found value is not a valid integer or ends with an unknown byte unit. Only non-negative integer values are recognized as valid.

It is possible to specify a size unit at the end of the value. If a known unit is found, this function multiplies the resulting value with the corresponding factor. For example, if the value of the element is "1KB", the return value of this function would be 1024.

The following table lists the available units together with a short description and the corresponding factor:

Size units

Unit Name	Description	Factor
KB	Kilo Byte	1024
MB	Mega Byte	(1024)^2
GB	Giga Byte	(1024)^3

If no unit is specified, this function defaults to the KB unit.

Note: This method can throw a NullPointerException if you pass a null reference as key.

Parameters:

key - The key whose value to return

defaultValue - The value to return if the given key is unknown

Returns:

Either the value converted to an integer for the given key if an element with the given key exists and the found value is a valid integer, or defaultValue otherwise.

Throws:

NullPointerException - if the key argument is null

getTimespanOption

protected long getTimespanOption(String key,
                                 long defaultValue)

Gets an integer value of a key. The integer value is interpreted as a time span and it is supported to specify time span units.

This method returns the defaultValue argument if either the supplied key is unknown or the found value is not a valid integer or ends with an unknown time span unit. It is possible to specify a time span unit at the end of the value. If a known unit is found, this function multiplies the resulting value with the corresponding factor. For example, if the value of the element is "1s", the return value of this function would be 1000. The following table lists the available units together with a short description and the corresponding factor.

Time nits

Unit Name	Description	Factor
s	Seconds	1000
m	Minutes	60*s
h	Hours	60*m
d	Days	24*h

If no unit is specified, this function defaults to the Seconds unit. Please note that the value is always returned in milliseconds.

Parameters:

key - The key whose value to return

defaultValue - The value to return if the given key is unknown

Returns:

Either the value converted to an integer for the given key if an element with the given key exists and the found value is a valid integer or defaultValue otherwise. The value is returned in milliseconds

Throws:

NullPointerException - if The key argument is null

getRotateOption

protected FileRotate getRotateOption(String key,
                                     FileRotate defaultValue)

Gets a FileRotate value of a key.

Parameters:

key - The key whose value to return

defaultValue - The value to return if the given key is unknown

Returns:

Either the value converted to a FileRotate value for the given key if an element with the given key exists and the found value is a valid FileRotate or defaultValue otherwise. Note that this method can throw a NullPointerException if you pass a null reference as key

Throws:

NullPointerException - if the key argument is null

getBytesOption

public byte[] getBytesOption(String key,
                             int size,
                             byte[] defaultValue)

Gets the byte array value of a key.

The returned byte array always has the desired length as specified by the size argument. If the element value does not have the required size after conversion, it is shortened or padded (with zeros) automatically. This method returns the defaultValue argument if either the supplied key is unknown or the found value does not have a valid format (e.g. invalid characters when using hexadecimal strings).

Note that this method can throw an exception of type NullPointerException if you pass a null reference as key.

Parameters:

key - The key whose value to return

size - The desired size in bytes of the returned byte array. If the element value does not have the expected size, it is shortened or padded automatically

defaultValue - The value to return if the given key is unknown or if the found value has an invalid format

Returns:

Either the value converted to a byte array for the given key if an element with the given key exists and the found value has a valid format or defaultValue otherwise

Throws:

NullPointerException - if the key argument is null

isValidOption

protected boolean isValidOption(String name)

Validates if an option is supported by this protocol.

The following table lists all valid options, their default values and descriptions common to all protocols. See below for explanations:

Protocol options

Option Name	Default	Description
-	-	-
level	debug	Specifies the log level of this protocol.
reconnect	false	Specifies if a reconnect should be initiated when a connection gets dropped.
reconnect.interval	0	If reconnecting is enabled, specifies the minimum time in seconds between two successive reconnect attempts. If 0 is specified, a reconnect attempt is initiated for each packet if needed. It is possible to specify time span units like this: "1s". Supported units are "s" (seconds), "m" (minutes), "h" (hours) and "d" (days).
caption	[name]	Specifies the caption of this protocol as used by SmartInspect.Dispatch. By default, it is set to the protocol identifier (e.g., "file" or "mem").
async.enabled	false	Specifies if this protocol should operate in asynchronous instead of the default blocking mode.
async.queue	2048	Specifies the maximum size of the asynchronous queue in kilobytes. It is possible to specify size units like this: "1 MB". Supported units are "KB", "MB" and "GB".
async.throttle	true	Specifies if the application should be automatically throttled in asynchronous mode when more data is logged than the queue can handle.
async.clearondisconnect	false	Specifies if the current content of the asynchronous queue should be discarded before disconnecting. Useful if an application must not wait for the logging to complete before exiting.
backlog.enabled	false	Enables the backlog feature (see below).
backlog.queue	2048	Specifies the maximum size of the backlog queue in kilobytes. It is possible to specify size units like this: "1 MB". Supported units are "KB", "MB" and "GB".
backlog.flushon	error	Specifies the flush level for the backlog functionality.
backlog.keepopen	false	Specifies if the connection should be kept open between two successive writes when the backlog feature is used.

With the log level of a protocol you can limit the amount of data being logged by excluding packets which don't have a certain minimum log level. For example, if you set the level to "message", all packets with a log level of "debug" or "verbose" are ignored. For a complete list of available log level values, please see the documentation of the Level enum.

The caption option specifies the caption for this protocol as used by the SmartInspect.Dispatch method. This method can send and initiate custom protocol actions and the caption is used to lookup the requested connection. By default, the caption is set to the identifier of a protocol (e.g., "file" or "mem"). For more information about the dispatching of custom protocol actions, please refer to the documentation of the Dispatch and SmartInspect.Dispatch methods.

If the backlog option is enabled, all packets whose log level is less than the flushon level and equal to or higher than the general log level of a protocol, will be written to a queue rather than directly to the protocol specific destination. When a packet arrives with a log level of at least the same value as the flushon option, the current content of the queue is written. The total amount of memory occupied by this queue can be set with the queue option. If the packet queue has been filled up with packets and a new packet is about to be stored, old packets are discarded.

As an example, if the backlog queue is set to "2 MB" and the flushon level to "error", all packets with a log level less than error are written to a queue first. By specifying a queue option of "2 MB", the baclog queue is set to a maximum memory size of 2 megabyte. Now, when a packet with a log level of error arrives, the current content of the queue and then the error itself is written.

With the keepopen option of the backlog feature you can specify if a connection should be kept open between two successive writes. When keepopen is set to false, a connection is only available during the actual write / flush. A connection is thus only created when absolutely necessary.

A protocol can either operate in normal blocking (the default) or in asynchronous mode. In blocking mode, the operations of this protocol (Connect, Disconnect, Dispatch and WritePacket) are executed synchronously and block the caller until they are done. In asynchronous mode, these operations are not executed directly but scheduled for execution in a different thread and return immediately. Asynchronous logging can increase the logging performance and reduce the blocking of applications.

When operating in asynchronous mode, this protocol uses a queue to buffer the logging data. The total amount of memory occupied by this queue can be set with the queue option. The throttle option specifies if an application should be automatically throttled in asynchronous mode when more data is logged / generated than the queue can handle. If this option is disabled and the queue is currently full, old packets are discarded when new data is logged. The throttle option ensures that no logging data is lost but can be disabled if logging performance is critical.

With the clearondisconnect option, you can specify if the current content of the asynchronous queue should be discarded before disconnecting. This can be useful if an application must not wait for the logging to complete before exiting.

The reconnect option allows a protocol to reconnect automatically before a packet is being written. A reconnect might be necessary if a working connection has been unexpectedly disconnected or could not be established in the first place. Possible errors during a reconnect attempt will silently be ignored and not reported.

Please note that the reconnect functionality causes a protocol by default to initiate a connection attempt for every packet until a connection has been successfully (re-) established. This can be a very time-consuming process, especially when using a protocol which requires a complex connection process like TCP, for example. This can slow down the logging performance. When using the reconnect option, it is thus recommended to also enable asynchronous logging to not block the application or to specify a reconnect interval to minimize the reconnect attempts.

Parameters:

name - The option name to validate

Returns:

True if the option is supported and false otherwise

loadOptions

protected void loadOptions()

Loads and inspects protocol specific options.

This method is intended to give real protocol implementations the opportunity to load and inspect options. This method will be called automatically when the options have been changed. The default implementation of this method takes care of the options isValidOption(java.lang.String) common to all protocols and should thus always be called by derived classes which override this method.

getReconnectDefaultValue

protected boolean getReconnectDefaultValue()

Defines the default value for `reconnect` option as `true`.

Returns:

false

getAsyncEnabledDefaultValue

protected boolean getAsyncEnabledDefaultValue()

Defines the default value for `async.enabled` option as `false`.

Returns:

false

getAsyncThrottleDefaultValue

protected boolean getAsyncThrottleDefaultValue()

Defines the default value for `async.throttle` option as `false`.

Returns:

true

getAsyncQueueDefaultValue

protected int getAsyncQueueDefaultValue()

Defines the default value for `async.queue` option as 2 megabytes.

Returns:

2048

reset

protected void reset()
              throws Exception

Resets the protocol and brings it into a consistent state.

This method resets the current protocol state by clearing the internal queue of packets, setting the connected status to false and calling the abstract internalDisconnect method of a real protocol implementation to clean up any protocol specific resources.

Throws:

Exception - exception

internalConnect

protected abstract void internalConnect()
                                 throws Exception

Connects to the protocol destination.

This method initiates a protocol specific connection attempt. The behavior of real implementations of this method can often be changed by setting protocol options with the initialize method. This method is always called in a threadsafe and exception-safe context.

Throws:

Exception - If connecting to the destination failed.

implConnect

public void implConnect()
                 throws ProtocolException

Throws:

ProtocolException

connect

public void connect()
             throws ProtocolException

Connects to the protocol destination.

In normal blocking mode (see isValidOption), this method does nothing more than to verify that the protocol is not already connected and does not use the keep-open backlog feature, and then calls the abstract protocol specific internalConnect method in a threadsafe and exception-safe context.
When operating in asynchronous mode instead, this method schedules a connect operation for asynchronous execution and returns immediately. Please note that possible exceptions which occur during the eventually executed connect are not thrown directly but reported with the error event.

Throws:

ProtocolException - If connecting to the destination fails. Can only occur when operating in normal blocking mode. In asynchronous mode, the error event is used for reporting exceptions instead

internalReconnect

protected boolean internalReconnect()
                             throws Exception

Reconnects to the protocol specific destination.

This method initiates a protocol specific reconnect attempt. The behavior of real method implementations can often be changed by setting protocol options with initialize. This method is always called in a threadsafe and exception-safe context.

The default implementation simply calls the protocol specific internalConnect method. Derived classes can change this behavior by overriding this method.

Returns:

True if the reconnect attempt has been successful and false otherwise

Throws:

Exception - if reconnecting to the destination failed

internalDisconnect

protected abstract void internalDisconnect()
                                    throws Exception

Disconnects from the protocol destination.

This method is intended for real protocol implementations to disconnect from the protocol specific source. This could be closing a file or disconnecting a TCP socket, for example. This method is always called in a threadsafe and exception-safe context.

Throws:

Exception - If disconnecting from the destination failed

implDisconnect

public void implDisconnect()
                    throws ProtocolException

Throws:

ProtocolException

disconnect

public void disconnect()
                throws ProtocolException

Disconnects from the protocol destination.

In normal blocking mode (see isValidOption), this method checks if this protocol has a working connection and then calls the protocol specific internalDisconnect method in a threadsafe and exception-safe context.

When operating in asynchronous mode instead, this method schedules a disconnect operation for asynchronous execution and then blocks until the internal protocol thread is done. Please note that possible exceptions which occur during the eventually executed disconnect are not thrown directly but reported with the ProtocolListener.onError, error event.

Throws:

ProtocolException - Disconnecting from the destination failed. Can only occur when operating in normal blocking mode. In asynchronous mode, the error event is used for reporting exceptions instead

composeLogHeaderPacket

protected LogHeader composeLogHeaderPacket()

internalWriteLogHeader

protected void internalWriteLogHeader()
                               throws Exception

Throws:

Exception

internalWritePacket

protected abstract void internalWritePacket(Packet packet)
                                     throws Exception

Writes a packet to the protocol destination.

This method is intended for real protocol implementations to write the supplied packet to the protocol specific destination. This method is always called in a threadsafe and exception-safe context.

Parameters:

packet - The packet to write

Throws:

Exception - if writing the packet to the destination failed

implWritePacket

public void implWritePacket(Packet packet)
                     throws ProtocolException

Throws:

ProtocolException

scheduleWritePacket

public void scheduleWritePacket(Packet packet,
                                SchedulerQueue.QueueEnd insertTo)

writePacket

public void writePacket(Packet packet)
                 throws ProtocolException

Writes a packet to the protocol specific destination.

This method first checks if the log level of the supplied packet is sufficient to be logged. If this is not the case, this method returns immediately.

Otherwise, in normal blocking mode (see isValidOption(java.lang.String)), this method verifies that this protocol is successfully connected and then writes the supplied packet to the backlog queue or passes it directly to the protocol specific destination by calling the InternalWritePacket method. Calling InternalWritePacket is always done in a threadsafe and exception-safe way.

When operating in asynchronous mode instead, this method schedules a write operation for asynchronous execution and returns immediately. Please note that possible exceptions which occur during the eventually executed write are not thrown directly but reported with the error event.

Parameters:

packet - The packet to write

Throws:

ProtocolException - Writing the packet to the destination failed. Can only occur when operating in normal blocking mode. In asynchronous mode, the error event is used for reporting exceptions instead

getName

protected abstract String getName()

Specifies the name of a real protocol implementation.

Real implementations should return a meaningful name which represents the protocol. For example, the FileProtocol returns "file", the TcpProtocol "tcp" and the TextProtocol "text".

Returns:

The name of a real protocol implementation

internalDispatch

protected void internalDispatch(ProtocolCommand command)
                         throws Exception

Executes a protocol specific custom action. The default implementation does nothing. Derived protocol implementations can override this method to add custom actions. Please see the MemoryProtocol.internalDispatch method for an example. This method is always called in a threadsafe and exception-safe way.

Parameters:

command - The protocol command which provides protocol specific information about the custom action.

Throws:

Exception - if executing the custom action failed.

See Also:

SmartInspect.dispatch(java.lang.String, int, java.lang.Object)

implDispatch

public void implDispatch(ProtocolCommand command)
                  throws ProtocolException

Throws:

ProtocolException

dispatch

public void dispatch(ProtocolCommand command)
              throws ProtocolException

Dispatches a custom action to a concrete implementation of a protocol.

In normal blocking mode (see isValidOption), this method does nothing more than to call the protocol-specific internalDispatch method with the supplied command argument in a threadsafe and exception-safe way. Please note that this method dispatches the custom action only if the protocol is currently connected.

When operating in asynchronous mode instead, this method schedules a dispatch operation for asynchronous execution and returns immediately. Please note that possible exceptions which occur during the eventually executed dispatch are not thrown directly but reported with the error event.

Parameters:

command - The protocol command object which provides protocol-specific information about the custom action. Can be null

Throws:

ProtocolException - An exception occurred in the custom action. Can only occur when operating in normal blocking mode. In asynchronous mode, the error event is used for reporting exceptions instead

See Also:

SmartInspect.dispatch(java.lang.String, int, java.lang.Object)

getCaption

public String getCaption()

Returns the caption of this protocol.

The caption is used in the SmartInspect.dispatch method to lookup the requested connection. The caption can be set with initialize. If you use only one connection at once or does not use the SmartInspect.dispatch method, the caption option can safely be ignored. For more information, please refer to the documentation of the dispatch and SmartInspect.dispatch methods.

Returns:

The caption of this protocol as used by the SmartInspect.dispatch method

See Also:

SmartInspect.dispatch(java.lang.String, int, java.lang.Object)

dispose

public void dispose()
             throws ProtocolException

Disconnects from the protocol destination.

In normal blocking mode (see isValidOption), this method checks if this protocol has a working connection and then calls the protocol specific internalDisconnect method in a threadsafe and exception-safe context.

When operating in asynchronous mode instead, this method schedules a disconnect operation for asynchronous execution and then blocks until the internal protocol thread is done. Please note that possible exceptions which occur during the eventually executed disconnect are not thrown directly but reported with the ProtocolListener.onError, error event.

Throws:

ProtocolException - Disconnecting from the destination failed. Can only occur when operating in normal blocking mode. In asynchronous mode, the error event is used for reporting exceptions instead

failed

public boolean failed()

Returns if the last executed connection-related operation of this protocol has failed. Indicates if the next operation is likely to block.

Returns:

True if the last executed connection-related operation of this protocol has failed and false otherwise

addListener

public void addListener(ProtocolListener listener)

Adds a new listener for the events of this object. This method adds a new listener for the events of this Protocol object. This can be useful to get informed about possible protocol errors. Please see the ProtocolListener interface for details. Also see the documentation of the ProtocolAdapter class which simplifies the event handling. Note that the error event is only used in combination with asynchronous logging (please see isValidOption for more information). In normal blocking mode, exceptions are reported by throwing.

Parameters:

listener - The listener to add

removeListener

public void removeListener(ProtocolListener listener)

Removes a new 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. Note that the error event is only used in combination with asynchronous logging (please see isValidOption for more information). In normal blocking mode, exceptions are reported by throwing.

Parameters:

listener - The listener to add

doError

protected void doError(Exception ex)

Invokes the ProtocolListener.onError event handlers. Derived classes can override this method to intercept the ProtocolListener.onError event. Note that the error event is only used in combination with asynchronous logging (please see isValidOption for more information). In normal blocking mode, exceptions are reported by throwing.

Parameters:

ex - The occurred exception

isAsynchronous

public boolean isAsynchronous()

Indicates if this protocol is operating in asynchronous protocol mode. If this method returns true, this protocol is operating in asynchronous protocol mode. Otherwise, it returns false. Asynchronous protocol mode can be enabled with the initialize method. Also see isValidOption for information on asynchronous logging and how to enable it.

Returns:

True if this protocol is operating in asynchronous protocol mode and false otherwise

getHostName

public String getHostName()

Returns the hostname of this protocol.

The hostname of a protocol is usually set to the name of the machine this protocol is created in. The hostname can be used to write LogHeader packets after a successful protocol connect.

Returns:

The hostname of this protocol

setHostName

public void setHostName(String hostName)

Sets the hostname of this protocol.

The hostname of a protocol is usually set to the name of the machine this protocol is created in. The hostname can be used to write LogHeader packets after a successful protocol connect.

Parameters:

hostName - The new hostname

getAppName

public String getAppName()

Returns the application name of this protocol.

The application name of a protocol is usually set to the name of the application this protocol is created in. The application name can be used to write LogHeader packets after a successful protocol connect.

Returns:

The application name of this protocol

setAppName

public void setAppName(String appName)

Sets the application name of this protocol.

The application name of a protocol is usually set to the name of the application this protocol is created in. The application name can be used to write LogHeader packets after a successful protocol connect.

Parameters:

appName - The new application name