Coordination
Date: 2016-06-25

org.osgi.service.coordinator

## Interface Coordination

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

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `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

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

          org.osgi.framework.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.