OSGi 8.1.0 · org.osgi.service.coordinator.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();
}

Method Summary

Modifier and Type	Method and Description
public boolean	Returns: `false` if there was no current Coordination, otherwise returns `true`. addParticipant(Participant The Participant to register with the current Coordination. The participant must not be `null`. participant) Register a Participant with the `current Coordination`.
public Coordination	Returns: A new Coordination object begin(String The name of this coordination. The name does not have to be unique but must follow the `symbolic-name` syntax from the Core specification. name, long 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. timeMillis) Create a new Coordination and make it the `current Coordination`.
public Coordination	Returns: The new Coordination object. create(String The name of this coordination. The name does not have to be unique but must follow the `symbolic-name` syntax from the Core specification. name, long 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. timeMillis) Create a new Coordination.
public boolean	Returns: `false` if there was no current Coordination, otherwise returns the result from calling `Coordination#fail(Throwable)` on the current Coordination. fail(Throwable The failure cause. The failure cause must not be `null` . cause) Terminate the `current Coordination` as a failure with the specified failure cause.
public 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. getCoordination(long The id of the requested Coordination. id) Returns the Coordination with the specified id.
public Collection<Coordination>	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. getCoordinations() Returns a snapshot of all active Coordinations.
public Coordination	Returns: The current Coordination or `null` if the thread local Coordination stack is empty. peek() Returns the current Coordination.
public Coordination	Returns: The Coordination that was the current Coordination or `null` if the thread local Coordination stack is empty. pop() Remove the current Coordination from the thread local Coordination stack.

Method Detail

addParticipant back to summary

addParticipant	back to summary
public 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:Participant The Participant to register with the current Coordination. The participant must not be `null`. Returns:boolean `false` if there was no current Coordination, otherwise returns `true`. Exceptions 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. SecurityException: If the caller does not have `CoordinationPermission[PARTICIPATE]` for the current Coordination. See Also `Coordination#addParticipant(Participant)`

public boolean addParticipant(Participant participant)

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:Participant: The Participant to register with the current Coordination. The participant must not be null.

Returns:boolean

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

Exceptions

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.
SecurityException:: If the caller does not have CoordinationPermission[PARTICIPATE] for the current Coordination.

begin back to summary

begin	back to summary
public Coordination begin(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:String 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:long 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:Coordination A new Coordination object Exceptions IllegalArgumentException: If the specified name does not follow the `symbolic-name` syntax or the specified time is negative. SecurityException: If the caller does not have `CoordinationPermission[INITIATE]` for the specified name and creating bundle.

public Coordination begin(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:String: 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:long: 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:Coordination

A new Coordination object

Exceptions

IllegalArgumentException:: If the specified name does not follow the symbolic-name syntax or the specified time is negative.
SecurityException:: If the caller does not have CoordinationPermission[INITIATE] for the specified name and creating bundle.

create back to summary

create	back to summary
public Coordination create(String name, long timeMillis) Create a new Coordination. Parameters name:String 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:long 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:Coordination The new Coordination object. Exceptions IllegalArgumentException: If the specified name does not follow the `symbolic-name` syntax or the specified time is negative. SecurityException: If the caller does not have `CoordinationPermission[INITIATE]` for the specified name and creating bundle.

public Coordination create(String name, long timeMillis)

Create a new Coordination.

Parameters

name:String: 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:long: 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:Coordination

The new Coordination object.

Exceptions

IllegalArgumentException:: If the specified name does not follow the symbolic-name syntax or the specified time is negative.
SecurityException:: If the caller does not have CoordinationPermission[INITIATE] for the specified name and creating bundle.

fail back to summary

fail	back to summary
public boolean fail(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:Throwable The failure cause. The failure cause must not be `null` . Returns:boolean `false` if there was no current Coordination, otherwise returns the result from calling `Coordination#fail(Throwable)` on the current Coordination. Exceptions SecurityException: If the caller does not have `CoordinationPermission[PARTICIPATE]` for the current Coordination. See Also `Coordination#fail(Throwable)`

public boolean fail(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:Throwable: The failure cause. The failure cause must not be null .

Returns:boolean

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

Exceptions

SecurityException:: If the caller does not have CoordinationPermission[PARTICIPATE] for the current Coordination.

See Also

Coordination#fail(Throwable)

getCoordination back to summary

getCoordination	back to summary
public Coordination getCoordination(long id) Returns the Coordination with the specified id. Parameters id:long The id of the requested Coordination. Returns:Coordination 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.

public Coordination getCoordination(long id)

Returns the Coordination with the specified id.

Parameters

id:long: The id of the requested Coordination.

Returns:Coordination

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.

getCoordinations back to summary

getCoordinations	back to summary
public 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:Collection<Coordination> 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.

public 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:Collection<Coordination>: 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.

peek back to summary

peek	back to summary
public 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:Coordination The current Coordination or `null` if the thread local Coordination stack is empty.

public 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:Coordination: The current Coordination or null if the thread local Coordination stack is empty.

pop back to summary

pop	back to summary
public 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:Coordination The Coordination that was the current Coordination or `null` if the thread local Coordination stack is empty. Exceptions SecurityException: If the caller does not have `CoordinationPermission[INITIATE]` for the current Coordination.

public Coordination pop()

Remove the current Coordination from the thread local Coordination stack.

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

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

Exceptions

SecurityException:: If the caller does not have CoordinationPermission[INITIATE] for the current Coordination.

public Interface Coordinator

Method Summary

Method Detail