public interface Message<T extends Message>
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.
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:
Parameters must not be modified until the report() method is called.
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.
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:
null parameter to empty byte array
ByteBuffer to empty byte array
EnumParameter to its integer value
| Modifier and Type | Method and 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(EnumParameter param0)
Add a 32-bit fixed-length parameter to the message, specified as an enumerated type.
|
T |
staticParam(int param0)
Add a 32-bit fixed-length parameter to the message.
|
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.
|
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.
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.
param - a message parameter that the caller guarantees will not be subsequently modifiedT 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).
param0 - an parameter to be added to this messageT 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.
param0 - param1 - 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.
param0 - param1 - param2 - T staticParam(int param0)
Add a 32-bit fixed-length parameter to the message.
param0 - a 32-bit integer containing the parameterT 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().
param0 - an enum parameter from a generated enum typeT staticParam(Integer param0)
Add a 32-bit fixed-length parameter to the message, specified as an Integer.
param0 - an enum parameter from a generated enum typevoid 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.