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:

    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

      All Methods Instance Methods Abstract Methods 
      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.