Coordinator
Date: 2016-06-25

org.osgi.service.coordinator

## Interface Coordinator

-     @ProviderType
      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();
       }

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `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.