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

Field Summary

Fields

Modifier and Type	Field and Description
static String	CONFIG_PROPERTY_NAME
static String	JNDI_NAME

Method Summary

Modifier and Type	Method and Description
Trail	copyOrCreateTrail(ActivityContextInterface fromActivity, ActivityContextInterface toActivity) Attach the Trail from fromActivity to toActivity.
Trail	getOrCreateTrail(ActivityContextInterface aci) Get the trail attached to an activity or a new trail if one is not bound.
Trail	getOrCreateTrail(ActivityHandle handle) Get the trail attached to an activity or a new trail if one is not bound.
Trail	getOrCreateTrail(EventContext event) Get the trail attached to the activity owning an event, or a new trail if one is not bound.
Trail	getTrail(ActivityHandle handle) Get the trail attached to an activity.
boolean	isEnabled() Return the current state of the global SAS enabled flag.
void	setActivityTrail(ActivityContextInterface aci, Trail trail) Set the trail for an Activity.
void	setActivityTrail(ActivityHandle handle, Trail trail) Set the trail for an Activity.
void	setActivityTrail(EventContext event, Trail trail) Attach a given Trail to the Activity owning an EventContext.
Trail	startAndAssociateTrail(Trail trail, Scope scope) Start a new colocated SAS trail, and associate it with the original trail.
Trail	startColocatedTrail(Trail trail) Start a new SAS trail on the same server as an existing SAS trail.
Trail	startTrail() Send a start marker on the next trail ID, and return a trail to create and send messages on.
Trail	startTrail(UUID steeringId) Send a start marker on the next trail ID, and return a trail to create and send messages on.

Methods inherited from interface javax.naming.Referenceable

getReference

Field Detail

JNDI_NAME

static final String JNDI_NAME

See Also:

Constant Field Values

CONFIG_PROPERTY_NAME

static final String CONFIG_PROPERTY_NAME

See Also:

Constant Field Values

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