Top Description Fields Methods
org.osgi.service.coordinator

public Interface Coordination

Annotations
@ProviderType
Imports
java.util.List, .Map, org.osgi.annotation.versioning.ProviderType, org.osgi.framework.Bundle
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();
  }
}
Author
$Id: 9b7da14f4dac30c9a1cb8b2f411887b0f58de94b $

Field Summary

Modifier and TypeField and Description
public static final Exception
ORPHANED

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

public static final 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.

public static final Exception
TIMEOUT

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

Method Summary

Modifier and TypeMethod and Description
public void
addParticipant(Participant
The Participant to register with this Coordination. The participant must not be null.
participant)

Register a Participant with this Coordination.

public void
end()

Terminate this Coordination normally.

public long

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.
extendTimeout(long
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.
timeMillis)

Extend the time out of this Coordination.

public boolean

Returns:

true if this Coordination was active and was terminated by this method, otherwise false.
fail(Throwable
The failure cause. The failure cause must not be null.
cause)

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

public Bundle

Returns:

The bundle that created this Coordination.
getBundle()

Returns the bundle that created this Coordination.

public 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.
getEnclosingCoordination()

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

public Throwable

Returns:

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

Returns the failure cause of this Coordination.

public long

Returns:

The id assigned to this Coordination.
getId()

Returns the id assigned to this Coordination.

public String

Returns:

The name of this Coordination.
getName()

Returns the name of this Coordination.

public List<Participant>

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.
getParticipants()

Returns a snapshot of the Participants registered with this Coordination.

public Thread

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.
getThread()

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

public Map<Class<?>, Object>

Returns:

The variable map associated with this Coordination.
getVariables()

Returns the variable map associated with this Coordination.

public boolean

Returns:

true if this Coordination is terminated, otherwise false if this Coordination is active.
isTerminated()

Returns whether this Coordination is terminated.

public void
join(long
Maximum time in milliseconds to wait. Specifying a time of 0 will wait until this Coordination is terminated.
timeMillis)

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

public Coordination

Returns:

This Coordination.
push()

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

Field Detail

ORPHANEDback to summary
public static final Exception ORPHANED

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

RELEASEDback to summary
public static final 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.

TIMEOUTback to summary
public static final Exception TIMEOUT

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

Method Detail

addParticipantback to summary
public 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:Participant

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

Exceptions
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.
SecurityException:
If the caller does not have CoordinationPermission[PARTICIPATE] for this Coordination.
endback to summary
public 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.

Exceptions
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.
SecurityException:
If the caller does not have CoordinationPermission[INITIATE] for this Coordination.
extendTimeoutback to summary
public 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 will return the new deadline if an extension took place or the current deadline if, for whatever reason, no extension takes place. Note that if a maximum timeout is in effect, the deadline may not be extended by as much as was requested, if at all. If there is no deadline, zero is returned. Specifying a timeout extension of 0 will return the existing deadline.

Parameters
timeMillis:long

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:long

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.

Exceptions
CoordinationException:
If this Coordination is terminated.
IllegalArgumentException:
If the specified time is negative.
SecurityException:
If the caller does not have CoordinationPermission[PARTICIPATE] for this Coordination.
failback to summary
public boolean fail(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:Throwable

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

Returns:boolean

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

Exceptions
SecurityException:
If the caller does not have CoordinationPermission[PARTICIPATE] for this Coordination.
getBundleback to summary
public 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:Bundle

The bundle that created this Coordination.

Exceptions
SecurityException:
If the caller does not have CoordinationPermission[ADMIN] for this Coordination.
getEnclosingCoordinationback to summary
public 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:Coordination

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.

Exceptions
SecurityException:
If the caller does not have CoordinationPermission[ADMIN] for this Coordination.
getFailureback to summary
public 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:Throwable

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

Exceptions
SecurityException:
If the caller does not have CoordinationPermission[INITIATE] for this Coordination.
getIdback to summary
public 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:long

The id assigned to this Coordination.

getNameback to summary
public String getName()

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

Returns:String

The name of this Coordination.

getParticipantsback to summary
public List<Participant> getParticipants()

Returns a snapshot of the Participants registered with this Coordination.

Returns:List<Participant>

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.

Exceptions
SecurityException:
If the caller does not have CoordinationPermission[INITIATE] for this Coordination.
getThreadback to summary
public Thread getThread()

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

Returns:Thread

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.

Exceptions
SecurityException:
If the caller does not have CoordinationPermission[ADMIN] for this Coordination.
getVariablesback to summary
public Map<Class<?>, 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:Map<Class<?>, Object>

The variable map associated with this Coordination.

Exceptions
SecurityException:
If the caller does not have CoordinationPermission[PARTICIPANT] for this Coordination.
isTerminatedback to summary
public boolean isTerminated()

Returns whether this Coordination is terminated.

Returns:boolean

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

joinback to summary
public void join(long timeMillis) throws InterruptedException

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

Parameters
timeMillis:long

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

Exceptions
InterruptedException:
If the wait is interrupted.
IllegalArgumentException:
If the specified time is negative.
SecurityException:
If the caller does not have CoordinationPermission[PARTICIPATE] for this Coordination.
pushback to summary
public Coordination push()

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

Returns:Coordination

This Coordination.

Exceptions
CoordinationException:
If this Coordination is already on the any thread's thread local Coordination stack or this Coordination is terminated.
SecurityException:
If the caller does not have CoordinationPermission[INITIATE] for this Coordination.