Package com.opencloud.rhino.facilities.sas

Interface Message<T>

All Known Subinterfaces:

EventMessage, MarkerMessage

All Known Implementing Classes:

NullEventMessageImpl, NullMarkerMessageImpl

public interface Message<T>

Superinterface of EventMessage and MarkerMessage with functionality common to both.

A Message sent to SAS may contain parameters to be used when decoding the message on the SAS server for display or correlation.

Variable-length parameters

Thread-safety

There are some critical thread-safety issues to consider for parameters added to messages.

Parameters are not copied or marshalled into the message until report() is called, and then only if SAS tracing is enabled.

This means two things:

1. Parameters must not be modified until the report() method is called.

2. Large or complex objects can be passed to this method, and if tracing is disabled or the event is discarded and not reported, it will have negligible memory or CPU cost

The threadSafeParam(byte[]) method allows callers to add a parameter that will not be copied, even after report() is called. This should be used for parameters which the caller plans to modify and has therefore defensively copied or marshalled into a new byte array.

Object parameter handling

Parameters passed to varParam(Object) and the multi-parameter equivalents will be handled differently depending on their type:

• null — Encoded as zero length byte array.

• byte[] — copied directly into the message

• ByteBuffer — Warning: Unsupported. Will be coerced to zero length byte array. Use threadSafeParam(byte[]) instead.

• String — encoded as UTF-8 and copied into the message

• implements EncodeableParameter — call EncodeableParameter.encode(ByteBuffer) copy bytes written to stream into the message

• implements MarshalableParameter — call MarshalableParameter.marshal() and copy the returned byte[] into the message

• any other type — call Object.toString() and proceed as for String

The varParam method should not be used for parameters that implement EnumParameter). It will still add the parameter but will log an error message. staticParam(EnumParameter) should be used for enum parameters.

As noted above, this marshalling/copying happens when the report() method is called, not when the parameters are added to the message. There are exceptions to this. These conversions happen when the parameter is added:

1. null parameter to empty byte array

2. ByteBuffer to empty byte array

3. EnumParameter to its integer value

Since:

Rhino 2.6.0

Method Summary

Modifier and Type	Method	Description
T	instance(int instanceId)
boolean	isEnabled()	Allows a caller to guard against performing expensive marshalling of message parameters, in cases where it doesn’t have access to the SasFacility.
void	report()	Enqueue this message for reporting to SAS.
T	staticParam(int param0)	Add a 32-bit fixed-length parameter to the message.
T	staticParam(EnumParameter param0)	Add a 32-bit fixed-length parameter to the message, specified as an enumerated type.
T	staticParam(Integer param0)	Add a 32-bit fixed-length parameter to the message, specified as an Integer.
T	threadSafeParam(byte[] param)	Add a parameter that will not be copied, even after report() is called and therefore must not be modified by calling code.
T	varParam(Object param0)	Add one variable length parameter.
T	varParams(Object param0, Object param1)	Add two variable-length parameters.
T	varParams(Object param0, Object param1, Object param2)	Add three variable-length parameters.

Method Detail

instance

T instance(int instanceId)

isEnabled

boolean isEnabled()

Allows a caller to guard against performing expensive marshalling of message parameters, in cases where it doesn’t have access to the SasFacility.

Returns:

true if SAS tracing is enabled on the SAS facility this message was created from

threadSafeParam

T threadSafeParam(byte[] param)

Add a parameter that will not be copied, even after report() is called and therefore must not be modified by calling code.

Callers should use this for parameters which it plans to modify and has therefore defensively copied or marshalled into a new byte array.

Use of isEnabled() is recommended before marshalling to avoid unnecessary memory and CPU use.

Parameters:

param - a message parameter that the caller guarantees will not be subsequently modified

Returns:

this, to allow method chaining

varParam

T varParam(Object param0)

Add one variable length parameter.

Warning: Parameters passed to this and other variable-length parameter methods must not be modified until the report() method is called. See discussion in the Javadoc for this interface (Message).

Parameters:

param0 - an parameter to be added to this message

Returns:

this, to allow method chaining

varParams

T varParams(Object param0,
            Object param1)

Add two variable-length parameters. Parameters will be handled as for #param(Object).

See warning on interface Javadoc about when parameters are marshalled.

Parameters:

param0 -

param1 -

Returns:

this, to allow method chaining

varParams

T varParams(Object param0,
            Object param1,
            Object param2)

Add three variable-length parameters. Parameters will be handled as for #param(Object).

See warning on interface Javadoc about when parameters are marshalled.

Parameters:

param0 -

param1 -

param2 -

Returns:

this, to allow method chaining

staticParam

T staticParam(int param0)

Add a 32-bit fixed-length parameter to the message.

Parameters:

param0 - a 32-bit integer containing the parameter

Returns:

this, to allow method chaining

staticParam

T staticParam(EnumParameter param0)

Add a 32-bit fixed-length parameter to the message, specified as an enumerated type.

The implementation adds the parameter using EnumParameter.value().

Parameters:

param0 - an enum parameter from a generated enum type

Returns:

this, to allow method chaining

staticParam

T staticParam(Integer param0)

Add a 32-bit fixed-length parameter to the message, specified as an Integer.

Parameters:

param0 - an enum parameter from a generated enum type

Returns:

this, to allow method chaining

report

void report()

Enqueue this message for reporting to SAS.

Variable-length parameters added with #param(Object) and the multi-parameter methods are marshalled into the message when this method is called so they can be freely modified from this call on.

Parameters added with threadSafeParam(byte[]) are not copied therefore must not be modified even after this method is called because the actual reporting to SAS will be done asynchronously.