org.osgi.service.coordinator
Interface Coordination

public interface Coordination

A Coordination object is used to coordinate a number of independent Participants.

Once a Coordination is created, it can be used to add Participant objects. When the Coordination is ended, the participants are notified. A Coordination can also fail for various reasons. When this occurs, the participants are notified of the failure.

A Coordination must be in one of two states, either ACTIVE or TERMINATED. The transition between ACTIVE and TERMINATED must be atomic, ensuring that a Participant can be guaranteed of either receiving an exception when adding itself to a Coordination or of receiving notification the Coordination has terminated.

A Coordination object is thread safe and can be passed as a parameter to other parties regardless of the threads these parties use.

The following example code shows how a Coordination should be used.

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

ThreadSafe

Consumers of this API must not implement this interface

Field Summary

static java.lang.Exception	ORPHANED A singleton exception that will be the failure cause when a Coordination has been orphaned.
static java.lang.Exception	RELEASED A singleton exception that will be the failure cause when the Coordinations created by a bundle are terminated because the bundle released the Coordinator service.
static java.lang.Exception	TIMEOUT A singleton exception that will be the failure cause when a Coordination times out.

Method Summary

void	addParticipant(Participant participant) Register a Participant with this Coordination.
void	end() Terminate this Coordination normally.
long	extendTimeout(long timeMillis) Extend the time out of this Coordination.
boolean	fail(java.lang.Throwable cause) Terminate this Coordination as a failure with the specified failure cause.
Bundle	getBundle() Returns the bundle that created this Coordination.
Coordination	getEnclosingCoordination() Returns the Coordination enclosing this Coordination if this Coordination is on the thread local Coordination stack.
java.lang.Throwable	getFailure() Returns the failure cause of this Coordination.
long	getId() Returns the id assigned to this Coordination.
java.lang.String	getName() Returns the name of this Coordination.
java.util.List<Participant>	getParticipants() Returns a snapshot of the Participants registered with this Coordination.
java.lang.Thread	getThread() Returns the thread in whose thread local Coordination stack this Coordination has been pushed.
java.util.Map<java.lang.Class<?>,java.lang.Object>	getVariables() Returns the variable map associated with this Coordination.
boolean	isTerminated() Returns whether this Coordination is terminated.
void	join(long timeMillis) Wait until this Coordination is terminated and all registered Participants have been notified.
Coordination	push() Push this Coordination object onto the thread local Coordination stack to make it the current Coordination.

Field Detail

TIMEOUT

static final java.lang.Exception TIMEOUT

A singleton exception that will be the failure cause when a Coordination times out.

RELEASED

static final java.lang.Exception RELEASED

A singleton exception that will be the failure cause when the Coordinations created by a bundle are terminated because the bundle released the Coordinator service.

ORPHANED

static final java.lang.Exception ORPHANED

A singleton exception that will be the failure cause when a Coordination has been orphaned.

Method Detail

getId

long getId()

Returns the id assigned to this Coordination. The id is assigned by the Coordinator service which created this Coordination and is unique among all the Coordinations created by the Coordinator service and must not be reused as long as the Coordinator service remains registered. The id must be positive and monotonically increases for each Coordination created by the Coordinator service.

Returns:

The id assigned to this Coordination.

getName

java.lang.String getName()

Returns the name of this Coordination. The name is specified when this Coordination was created.

Returns:

The name of this Coordination.

end

void end()

Terminate this Coordination normally.

If this Coordination has been pushed on the thread local Coordination stack of another thread, this method does nothing except throw a CoordinationException of type CoordinationException.WRONG_THREAD.

If this Coordination has been pushed on the thread local Coordination stack of this thread but is not the current Coordination, then the Coordinations on the thread local Coordination stack above this Coordination must be terminated and removed from the thread local Coordination stack before this Coordination is terminated. Each of these Coordinations, starting with the current Coordination, will be terminated normally . If the termination throws a CoordinationException, then the next Coordination on the thread local Coordination stack will be terminated as a failure with a failure cause of the thrown CoordinationException. At the end of this process, this Coordination will be the current Coordination and will have been terminated as a failure if any of the terminated Coordinations threw a CoordinationException

If this Coordination is the current Coordination, then it will be removed from the thread local Coordination stack.

If this Coordination is already terminated, a CoordinationException is thrown. If this Coordination was terminated as a failure, the failure cause will be the cause of the thrown CoordinationException.

Otherwise, this Coordination is terminated normally and then all registered Participants are notified. Participants should finalize any work associated with this Coordination. The successful return of this method indicates that the Coordination has terminated normally and all registered Participants have been notified of the normal termination.

It is possible that one of the Participants throws an exception during notification. If this happens, this Coordination is considered to have partially failed and this method must throw a CoordinationException of type CoordinationException.PARTIALLY_ENDED after all the registered Participants have been notified.

Throws:

CoordinationException - If this Coordination has failed, including timed out, or partially failed or this Coordination is on the thread local Coordination stack of another thread.

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

fail

boolean fail(java.lang.Throwable cause)

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

If this Coordination is already terminated, this method does nothing and returns false.

Otherwise, this Coordination is terminated as a failure with the specified failure cause and then all registered Participants are notified. Participants should discard any work associated with this Coordination. This method will return true.

If this Coordination has been pushed onto a thread local Coordination stack, this Coordination is not removed from the stack. The creator of this Coordination must still call end() on this Coordination to cause it to be removed from the thread local Coordination stack.

Parameters:

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

Returns:

true if this Coordination was active and was terminated by this method, otherwise false.

Throws:

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

getFailure

java.lang.Throwable getFailure()

Returns the failure cause of this Coordination.

If this Coordination has failed, then this method will return the failure cause.

If this Coordination timed out, this method will return TIMEOUT as the failure cause. If this Coordination was active when the bundle that created it released the Coordinator service, this method will return RELEASED as the failure cause. If the Coordination was orphaned, this method will return ORPHANED as the failure cause.

Returns:

The failure cause of this Coordination or null if this Coordination has not terminated as a failure.

Throws:

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

isTerminated

boolean isTerminated()

Returns whether this Coordination is terminated.

Returns:

true if this Coordination is terminated, otherwise false if this Coordination is active.

addParticipant

void addParticipant(Participant participant)

Register a Participant with this Coordination.

Once a Participant is registered with this Coordination, it is guaranteed to receive a notification for either normal or failure termination when this Coordination is terminated.

Participants are registered using their object identity. Once a Participant is registered with this Coordination, subsequent attempts to register the Participant again with this Coordination are ignored and the Participant is only notified once when this Coordination is terminated.

A Participant can only be registered with a single active Coordination at a time. If a Participant is already registered with an active Coordination, attempts to register the Participation with another active Coordination will block until the Coordination the Participant is registered with terminates. Notice that in edge cases the notification to the Participant that this Coordination has terminated can happen before this method returns.

Attempting to register a Participant with a terminated Coordination will result in a CoordinationException being thrown.

The ordering of notifying Participants must follow the reverse order in which the Participants were registered.

Parameters:

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

Throws:

CoordinationException - If the Participant could not be registered with this 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 this Coordination.

getParticipants

java.util.List<Participant> getParticipants()

Returns a snapshot of the Participants registered with this Coordination.

Returns:

A snapshot of the Participants registered with this Coordination. If no Participants are registered with this Coordination, the returned list will be empty. The list is ordered in the order the Participants were registered. The returned list is the property of the caller and can be modified by the caller.

Throws:

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

getVariables

java.util.Map<java.lang.Class<?>,java.lang.Object> getVariables()

Returns the variable map associated with this Coordination. Each Coordination has a map that can be used for communicating between different Participants. The key of the map is a class, allowing for private data to be stored in the map by using implementation classes or shared data by using shared interfaces. The returned map is not synchronized. Users of the map must synchronize on the Map object while making changes.

Returns:

The variable map associated with this Coordination.

Throws:

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

extendTimeout

long extendTimeout(long timeMillis)

Extend the time out of this Coordination.

Participants can call this method to extend the timeout of this Coordination with at least the specified time. This can be done by Participants when they know a task will take more than normal time. This method returns the new deadline. Specifying a timeout extension of 0 will return the existing deadline.

Parameters:

timeMillis - The time in milliseconds to extend the current timeout. If the initial timeout was specified as 0, no extension must take place. A zero must have no effect.

Returns:

The new deadline in milliseconds. If the specified time is 0, the existing deadline is returned. If this Coordination was created with an initial timeout of 0, no timeout is set and 0 is returned.

Throws:

CoordinationException - If this Coordination is terminated.

java.lang.IllegalArgumentException - If the specified time is negative.

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

join

void join(long timeMillis)
          throws java.lang.InterruptedException

Wait until this Coordination is terminated and all registered Participants have been notified.

Parameters:

timeMillis - Maximum time in milliseconds to wait. Specifying a time of 0 will wait until this Coordination is terminated.

Throws:

java.lang.InterruptedException - If the wait is interrupted.

java.lang.IllegalArgumentException - If the specified time is negative.

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

push

Coordination push()

Push this Coordination object onto the thread local Coordination stack to make it the current Coordination.

Returns:

This Coordination.

Throws:

CoordinationException - If this Coordination is already on the any thread's thread local Coordination stack or this Coordination is terminated.

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

getThread

java.lang.Thread getThread()

Returns the thread in whose thread local Coordination stack this Coordination has been pushed.

Returns:

The thread in whose thread local Coordination stack this Coordination has been pushed or null if this Coordination is not in any thread local Coordination stack.

Throws:

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

getBundle

Bundle getBundle()

Returns the bundle that created this Coordination. This is the bundle that obtained the Coordinator service that was used to create this Coordination.

Returns:

The bundle that created this Coordination.

Throws:

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

getEnclosingCoordination

Coordination getEnclosingCoordination()

Returns the Coordination enclosing this Coordination if this Coordination is on the thread local Coordination stack.

When a Coordination is pushed onto the thread local Coordination stack, the former current Coordination, if any, is the enclosing Coordination of this Coordination. When this Coordination is removed from the thread local Coordination stack, this Coordination no longer has an enclosing Coordination.

Returns:

The Coordination enclosing this Coordination if this Coordination is on the thread local Coordination stack or null if this Coordination is not on the thread local Coordination stack or has no enclosing Coordination.

Throws:

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