Package com.opencloud.rhino.facilities.sas

Interface SasFacility

  • All Superinterfaces:
    Referenceable
    All Known Implementing Classes:
    NullSasFacilityImpl
    public interface SasFacility
extends Referenceable

    Entry point to the SAS event reporting facility.

    Users of this facility create a Trail, then use that to create and report events The Trail interface provides two ways to create then report Events and Markers:

    1. create a message, add parameters, then report the message

    2. convenience methods that create a Marker or Event, with various combinations of parameters, then report it, in one call.

    The SAS Facility supports communication with a federation of SAS servers. As such, trails created with startTrail() are distributed between servers by simple round-robin. When starting a new trail that will be associated with an existing one, use startColocatedTrail(Trail) or startAndAssociateTrail(Trail, Scope) to start a new trail on the same server as the given trail.

    Since:
    Rhino 2.6.0

    • Method Detail

      • isEnabled

        boolean isEnabled()

        Return the current state of the global SAS enabled flag.

      • startTrail

        Trail startTrail()

        Send a start marker on the next trail ID, and return a trail to create and send messages on. Trails are distributed between available servers randomly.

        Service code (SBBs, SBB Parts) should use getOrCreateTrail(ActivityContextInterface) in preference to this method.

      • startTrail

        Trail startTrail​(UUID steeringId)

        Send a start marker on the next trail ID, and return a trail to create and send messages on. Trails are sent to the server mapped from UUID. Uses a UUID steering ID provided by another network element to associate with a trail reported by that element.

        Service code (SBBs, SBB Parts) should use getOrCreateTrail(ActivityContextInterface) in preference to this method.

      • startColocatedTrail

        Trail startColocatedTrail​(Trail trail)

        Start a new SAS trail on the same server as an existing SAS trail.

        To facilitate associating trails when using a federation of SAS servers this method starts the new trail on the same server as the provided trail.

        Parameters:
        trail - a Trail associated with the desired SAS server
        Returns:
        a new Trail on the same server as trail, or the NullTrail if this server is unavailable permanently.

      • startAndAssociateTrail

        Trail startAndAssociateTrail​(Trail trail,
                             Scope scope)

        Start a new colocated SAS trail, and associate it with the original trail.

        Parameters:
        trail - to associate with
        scope - association scope
        Returns:

      • copyOrCreateTrail

        Trail copyOrCreateTrail​(ActivityContextInterface fromActivity,
                        ActivityContextInterface toActivity)

        Attach the Trail from fromActivity to toActivity. If no Trail is attached to fromActivity, start a Trail, and attach it to both Activities. This blindly overwrites any existing trail attachment in toActivity.

        Parameters:
        fromActivity - Activity to copy trail from
        toActivity - Activity to copy trail to
        Returns:
        The trail attached to both activities.

      • setActivityTrail

        void setActivityTrail​(ActivityHandle handle,
                      Trail trail)

        Set the trail for an Activity. This association is one-way, a trail may be attached to multiple activities.

        This method is only usable from SasFacility instances owned by a Resource Adaptor.

        Parameters:
        handle - The handle for the Activity to attach the trail to
        trail - The trail to attach
        Throws:
        UnrecognizedActivityHandleException - if the handle is null, or does not point to a live activity

      • setActivityTrail

        void setActivityTrail​(EventContext event,
                      Trail trail)

        Attach a given Trail to the Activity owning an EventContext.

        Parameters:
        event - EventContext owned by the Activity to attach the Trail to
        trail - to attach to Activity owning event

      • setActivityTrail

        void setActivityTrail​(ActivityContextInterface aci,
                      Trail trail)

        Set the trail for an Activity. This association is one-way, a trail may be attached to multiple activities.

        This method is only usable from SasFacility instances obtained from an SBB context.

        Parameters:
        aci - The ACI for the Activity to attach the trail to
        trail - The trail to attach
        Throws:
        NullPointerException - if the ACI is null

      • getTrail

        Trail getTrail​(ActivityHandle handle)

        Get the trail attached to an activity. Returns null if no activity is bound.

        This method is only usable from SasFacility instances owned by a Resource Adaptor. RAs should create the trail and attach it with setActivityTrail(ActivityHandle, Trail) before calling this method.

        Parameters:
        handle - The handle for the Activity to get the trail from
        Returns:
        The trail or null if no trail is attached
        Throws:
        UnrecognizedActivityHandleException - if the handle is null, or does not point to a live activity

      • getOrCreateTrail

        Trail getOrCreateTrail​(ActivityHandle handle)

        Get the trail attached to an activity or a new trail if one is not bound. The new trail will be bound to the activity.

        This method is only usable from SasFacility instances obtained from a Resource Adaptor context.

        Parameters:
        handle - An ActivityHandle referencing the Activity to get the trail from
        Returns:
        The trail attached to the referenced activity.
        Throws:
        UnrecognizedActivityHandleException - if the handle is null, or does not point to a live activity

      • getOrCreateTrail

        Trail getOrCreateTrail​(EventContext event)

        Get the trail attached to the activity owning an event, or a new trail if one is not bound. The new trail will be bound to the owning activity.

        Parameters:
        event - An event on the Activity to fetch the trail from
        Returns:
        The trail attached to the referenced activity.

      • getOrCreateTrail

        Trail getOrCreateTrail​(ActivityContextInterface aci)

        Get the trail attached to an activity or a new trail if one is not bound. The new trail will be bound to the activity.

        This method is only usable from SasFacility instances obtained from an SBB context.

        Parameters:
        aci - An ACI referencing the Activity to get the trail from
        Returns:
        The trail attached to the referenced activity.
        Throws:
        NullPointerException - if the ACI is null