com.sun.xml.ws.tx.coordinator
Class Coordinator

java.lang.Object
  extended by com.sun.xml.ws.tx.coordinator.Coordinator
Direct Known Subclasses:
ATCoordinator

public abstract class Coordinator
extends java.lang.Object

This class encapsulates a coordinated activity.

Whenever a client (participant) registers for the activity, a Registrant is constructed and managed by this class.

Since:
1.0

Constructor Summary
Coordinator(CoordinationContextInterface context)
          Construct a new Coordinator object from the specified context.
Coordinator(CoordinationContextInterface context, CreateCoordinationContextType request)
          Construct a new Coordinator object from the specified context and soap request.
 
Method Summary
abstract  void addRegistrant(Registrant registrant, javax.xml.ws.WebServiceContext wsContext)
          Add the specified Registrant to the list of registrants for this coordinated activity.
abstract  boolean expirationGuard()
          Sub classes will implement this method to indicate whether or not they are subject to expiration.
 void expire()
          Release resources held by this coordinator.
 void forget()
          Release all resources associated with this coordinator
 CoordinationContextInterface getContext()
          Get the coordination context associated with this coordinated activity
abstract  javax.xml.ws.EndpointReference getCoordinatorProtocolServiceForRegistrant(Registrant r)
          Return the Coordinator Protocol Service EPR for registrant r.
 long getExpires()
          Get the expiration value
 Identifier getId()
          Get the ActivityIdentifier object.
 java.lang.String getIdValue()
          Get the activity id value
abstract  Registrant getRegistrant(java.lang.String id)
          Get the registrant with the specified id or null if it does not exist.
abstract  java.util.List<Registrant> getRegistrants()
          Get the list of Registrants for this coordinated activity.
 CreateCoordinationContextType getRequest()
          Get the SOAP request associated with this coordinated activity, if it exists.
 boolean isExpired()
           
 boolean isSubordinate()
          Return true iff this coordinator is delegating to a root coordinator
 boolean registerWithRootRegistrationService(Registrant r)
          Return true iff registrant should register with its root registration service.
abstract  void removeRegistrant(java.lang.String id)
          Remove the registrant with the specified id
 void setExpired(boolean expired)
           
 void setExpires(long i)
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Coordinator

public Coordinator(@NotNull
                   CoordinationContextInterface context,
                   @Nullable
                   CreateCoordinationContextType request)
Construct a new Coordinator object from the specified context and soap request.

Parameters:
context - The coordination context
request - The soap request

Coordinator

public Coordinator(@NotNull
                   CoordinationContextInterface context)
Construct a new Coordinator object from the specified context.

This constructor will be the main entry point for activity within the AppServer.

Parameters:
context - The coordination context
Method Detail

getContext

@NotNull
public CoordinationContextInterface getContext()
Get the coordination context associated with this coordinated activity

Returns:
The coordination context

getRequest

@Nullable
public CreateCoordinationContextType getRequest()
Get the SOAP request associated with this coordinated activity, if it exists.

Returns:
The original SOAP request (createCoordinationContext) or null if it doesn't exist.

getIdValue

@NotNull
public java.lang.String getIdValue()
Get the activity id value

Returns:
The activity id value

getId

@NotNull
public Identifier getId()
Get the ActivityIdentifier object.

This object can be used when it is necessary to insert the id as a ReferenceParameter in a soap message

Returns:
The activity id object

getExpires

public long getExpires()
Get the expiration value

Returns:
The expiration value

setExpires

public void setExpires(long i)

getRegistrants

@NotNull
public abstract java.util.List<Registrant> getRegistrants()
Get the list of Registrants for this coordinated activity.

The returned list is unmodifiable (read-only). Add new Registrants with the addRegistrant(Registrant,WebServiceContext) api instead.

Returns:
the list of Registrant objects

addRegistrant

public abstract void addRegistrant(Registrant registrant,
                                   javax.xml.ws.WebServiceContext wsContext)
Add the specified Registrant to the list of registrants for this coordinated activity.

Parameters:
registrant - The Registrant
wsContext - the web service context of the incoming message or null if it isn't available

getRegistrant

@Nullable
public abstract Registrant getRegistrant(java.lang.String id)
Get the registrant with the specified id or null if it does not exist.

Parameters:
id - the registrant id
Returns:
the Registrant object or null if the id does not exist

removeRegistrant

public abstract void removeRegistrant(java.lang.String id)
Remove the registrant with the specified id

Parameters:
id - the registrant id

isSubordinate

public boolean isSubordinate()
Return true iff this coordinator is delegating to a root coordinator

Returns:
true iff this coordinator is delegating to a root coordinator

getCoordinatorProtocolServiceForRegistrant

@NotNull
public abstract javax.xml.ws.EndpointReference getCoordinatorProtocolServiceForRegistrant(@NotNull
                                                                                                  Registrant r)
Return the Coordinator Protocol Service EPR for registrant r.

Parameters:
r - registrant
Returns:
the CPS EPT for the specified registrant

registerWithRootRegistrationService

public boolean registerWithRootRegistrationService(@NotNull
                                                   Registrant r)
Return true iff registrant should register with its root registration service.

Enables local participants to be cached with coordinator locally when this method returns true.

Parameters:
r - restistrant
Returns:
Return true iff registrant should register with its root registration service

expirationGuard

public abstract boolean expirationGuard()
Sub classes will implement this method to indicate whether or not they are subject to expiration.

Returns:
true if the coordinator should NOT expire, false otherwise.

expire

public void expire()
Release resources held by this coordinator.

This method will be automatically invoked once if the activity has a non-zero expiration.

During expiration, the coordinator will iterate over all of its registrants and tell them to expire. Depending on their state, registrants will either expire or not. A coordinator will not completely expire until all of its registrants have expired.


isExpired

public boolean isExpired()

setExpired

public void setExpired(boolean expired)

forget

public void forget()
Release all resources associated with this coordinator