org.osgi.service.coordinator
Interface Coordinator

public interface Coordinator

A Coordinator service coordinates activities between different parties.

A bundle can use the Coordinator service to create Coordination objects. Once a Coordination object is created, it can be pushed on the thread local Coordination stack to be an implicit parameter as the current Coordination for calls to other parties, or it can be passed directly to other parties as an argument. The current Coordination, which is on the top of the current thread's thread local Coordination stack, can be obtained with peek().

Any active Coordinations created by a bundle must be terminated when the bundle releases the Coordinator service. The Coordinator service must fail these Coordinations with the RELEASED exception.

A Participant can register to participate in a Coordination and receive notification of the termination of the Coordination.

The following example code shows a example usage of the Coordinator service.

 void foo() {
   Coordination c = coordinator.begin("work", 0);
   try {
     doWork();
   } catch (Exception e) {
     c.fail(e);
   } finally {
     c.end();
   }
 }
 

In the doWork method, code can be called that requires notification of the termination of the Coordination. The doWork method can then register a Participant with the Coordination.

 void doWork() {
   if (coordinator.addParticipant(this)) {
     beginWork();
   } else {
     beginWork();
     finishWork();
   }
 }
 
 void ended(Coordination c) {
   finishWork();
 }
 
 void failed(Coordination c) {
   undoWork();
 }
 

ThreadSafe

Consumers of this API must not implement this interface

Method Summary

boolean	addParticipant(Participant participant) Register a Participant with the current Coordination.
Coordination	begin(java.lang.String name, long timeMillis) Create a new Coordination and make it the current Coordination.
Coordination	create(java.lang.String name, long timeMillis) Create a new Coordination.
boolean	fail(java.lang.Throwable cause) Terminate the current Coordination as a failure with the specified failure cause.
Coordination	getCoordination(long id) Returns the Coordination with the specified id.
java.util.Collection<Coordination>	getCoordinations() Returns a snapshot of all active Coordinations.
Coordination	peek() Returns the current Coordination.
Coordination	pop() Remove the current Coordination from the thread local Coordination stack.

Method Detail

create

Coordination create(java.lang.String name,
                    long timeMillis)

Create a new Coordination.

Parameters:

name - The name of this coordination. The name does not have to be unique but must follow the symbolic-name syntax from the Core specification.

timeMillis - Timeout in milliseconds. A value of 0 means no timeout is required. If the Coordination is not terminated within the timeout, the Coordinator service will fail the Coordination with a TIMEOUT exception.

Returns:

The new Coordination object.

Throws:

java.lang.IllegalArgumentException - If the specified name does not follow the symbolic-name syntax or the specified time is negative.

java.lang.SecurityException - If the caller does not have CoordinationPermission[INITIATE] for the specified name and creating bundle.

begin

Coordination begin(java.lang.String name,
                   long timeMillis)

Create a new Coordination and make it the current Coordination.

This method does that same thing as calling create(name, timeMillis).push()

Parameters:

name - The name of this coordination. The name does not have to be unique but must follow the symbolic-name syntax from the Core specification.

timeMillis - Timeout in milliseconds. A value of 0 means no timeout is required. If the Coordination is not terminated within the timeout, the Coordinator service will fail the Coordination with a TIMEOUT exception.

Returns:

A new Coordination object

Throws:

java.lang.IllegalArgumentException - If the specified name does not follow the symbolic-name syntax or the specified time is negative.

java.lang.SecurityException - If the caller does not have CoordinationPermission[INITIATE] for the specified name and creating bundle.

peek

Coordination peek()

Returns the current Coordination.

The current Coordination is the Coordination at the top of the thread local Coordination stack. If the thread local Coordination stack is empty, there is no current Coordination. Each Coordinator service maintains thread local Coordination stacks.

This method does not alter the thread local Coordination stack.

Returns:

The current Coordination or null if the thread local Coordination stack is empty.

pop

Coordination pop()

Remove the current Coordination from the thread local Coordination stack.

The current Coordination is the Coordination at the top of the thread local Coordination stack. If the thread local Coordination stack is empty, there is no current Coordination. Each Coordinator service maintains its own thread local Coordination stacks.

This method alters the thread local Coordination stack, if it is not empty, by removing the Coordination at the top of the thread local Coordination stack.

Returns:

The Coordination that was the current Coordination or null if the thread local Coordination stack is empty.

Throws:

java.lang.SecurityException - If the caller does not have CoordinationPermission[INITIATE] for the current Coordination.

fail

boolean fail(java.lang.Throwable cause)

Terminate the current Coordination as a failure with the specified failure cause.

If there is no current Coordination, this method does nothing and returns false.

Otherwise, this method returns the result from calling Coordination.fail(Throwable) with the specified failure cause on the current Coordination.

Parameters:

cause - The failure cause. The failure cause must not be null .

Returns:

false if there was no current Coordination, otherwise returns the result from calling Coordination.fail(Throwable) on the current Coordination.

Throws:

java.lang.SecurityException - If the caller does not have CoordinationPermission[PARTICIPATE] for the current Coordination.

See Also:

Coordination.fail(Throwable)

addParticipant

boolean addParticipant(Participant participant)

Register a Participant with the current Coordination.

If there is no current Coordination, this method does nothing and returns false.

Otherwise, this method calls Coordination.addParticipant(Participant) with the specified Participant on the current Coordination and returns true.

Parameters:

participant - The Participant to register with the current Coordination. The participant must not be null.

Returns:

false if there was no current Coordination, otherwise returns true.

Throws:

CoordinationException - If the Participant could not be registered with the current Coordination. This exception should normally not be caught by the caller but allowed to be caught by the initiator of this Coordination.

java.lang.SecurityException - If the caller does not have CoordinationPermission[PARTICIPATE] for the current Coordination.

See Also:

Coordination.addParticipant(Participant)

getCoordinations

java.util.Collection<Coordination> getCoordinations()

Returns a snapshot of all active Coordinations.

Since Coordinations can be terminated at any time, Coordinations in the returned collection can be terminated before the caller examines the returned collection.

The returned collection must only contain the Coordinations for which the caller has CoordinationPermission[ADMIN].

Returns:

A snapshot of all active Coordinations. If there are no active Coordinations, the returned list will be empty. The returned collection is the property of the caller and can be modified by the caller.

getCoordination

Coordination getCoordination(long id)

Returns the Coordination with the specified id.

Parameters:

id - The id of the requested Coordination.

Returns:

A Coordination having with specified id or null if no Coordination with the specified id exists, the Coordination with the specified id is terminated or the caller does not have CoordinationPermission[ADMIN] for the Coordination with the specified id.