The Coordinator service provides a mechanism for multiple parties to collaborate on a common task without a priori knowledge of who will collaborate in that task. A collaborator can participate by adding a Participant to the Coordination. The Coordination will notify the Participants when the coordination is ended or when it is failed.

Each Coordination has an initiator that creates the Coordination object through the Coordinator service. The initiator can then push this object on a thread-local stack to make it an implicit Coordination or it can pass this object around as a parameter for explicit Coordinations. Collaborators can then use the current Coordination on the stack or get it from a parameter. Whenever a bundle wants to participate in the Coordination it adds itself to the Coordination as a participant. If necessary, a collaborator can initiate a new Coordination, which could be a nested Coordination for implicit Coordinations.

A Coordination must be terminated. Termination is either a normal end when the initiator calls the end method or it is failed when the fail method is called. A Coordination can be failed by any of the collaborators. A Coordination can also fail independently due to a time-out or when the initiator releases its Coordinator service. All participants in the Coordination are informed in reverse participation order about the outcome in a callback for ended or failed Coordinations.

A typical action diagram with a successful outcome is depicted in Figure 130.2.

Figure 130.2 Action Diagram Implicit Coordination

The general pattern for an initiator is to create a Coordination through the Coordinator service, perform the work in a try block, catch any exceptions and fail the Coordination in the catch block, and then ensure ending the Coordination in the finally block. The finally block can cause an exception. This is demonstrated in the following example:

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

This deceptively small template is quite robust:

The different failure paths and their handling is pictured in Figure 130.3.

Figure 130.3 Flow through the Coordination template

The example shows an explicit Coordination because the create method is used, implicit Coordinations are used in Implicit Coordinations. The parameters of the create method are the name of the Coordination and its time-out. The name is used for informational purposes as well as security. For security reasons, the name must follow the same syntax as the Bundle Symbolic Name. In a secure environment the name can be used to limit Coordinations to a limited set of bundles. For example, a set of bundles signed by a specific signer can use names like com.acme.* that are denied to all other bundles.

The zero time-out specifies that the Coordination will not have a time-out. Otherwise it must be a positive long, indicating the number of milliseconds the Coordination may take. However, implementations should have a configurable time-out to ensure that the system remains alive.

In the doWork method the real work is done in conjunction with the collaborators. Explicit Coordinations can be passed to other threads if needed. Collaborators can decide to add participants whenever they require a notification when the Coordination has been terminated. For example, the following code could be called from the doWork method:

void foo(Coordination c) {
  doPrepare();
  c.addParticipant(this);
}

This method does the preparation work but does not finalize it so that next time it can use some intermediate results. For example, the prepare method could cache a connection to a database that should be reused during the Coordination. The collaborator can assume that it will be called back on either the failed or ended method. These methods could look like:

public void ended(Coordination c)  { doFinish(); }
public void failed(Coordination c) { doFailed(); }

The Coordinator provides the guarantee that this code will always call the doFinish method when the Coordination succeeds and doFailed method when it failed.

The Participant must be aware that the ended(Coordination) and failed(Coordination) methods can be called on any thread.

If the doWork method throws an exception it will end up in the catch block of the initiator. The catch block will then fail the Coordination by calling the fail method with the given exception. If the Coordination was already terminated because something else already had failed it then the method call is ignored, only the first fail is used, later fails are ignored.

In all cases, the finally block is executed last. The finally block ends the Coordination. If this coordination was failed then it will throw a Coordination Exception detailing the reason of the failure. Otherwise it will terminate it and notify all the participants.

The Coordination Exception is a Runtime Exception making it unnecessary to declare it.

Explicit Coordinations allow the Coordination objects to be passed to many different collaborators who can perform the work on different threads. Each collaborator can fail the Coordination at any moment in time or the time-out can occur on yet another thread. Participants must therefore be aware that the callbacks ended and failed can happen on any thread. The following example shows a typical case where a task is parallelized. If any thread fails the Coordination, all other threads could be notified before they're finished.

Executor executor = ...
final CountDownLatch latch = new CountdownLatch(10);
final Coordination c = coordinator.create("parallel", 0); 
for ( int i=0; i<10; i++) {
  executor.execute(
    new Runnable() {
        public void run() { baz(c); latch.countDown(); }
      });
  }
  latch.await();
  c.end();

The Coordination object is thread safe so it can be freely passed around.

An explicit Coordination requires that the Coordination is passed as a parameter to the doWork method. The Coordinator also supports implicit Coordinations. With implicit Coordinations the Coordinator maintains a thread local stack of Coordinations where the top of this stack is the current Coordination for that thread. The usage of the implicit Coordination is almost identical to the explicit Coordinations except that all the work occurs on a single thread. The control flow is almost identical to explicit Coordinations:

Coordination c = coordinator.begin("com.example.work",0);
try {
    doWork();
} catch( Exception e ) { 
    c.fail(e); 
} finally { 
    c.end();   
}

See also Figure 130.3. However, in this case the finally block with the call to the end method is even more important. With an implicit Coordination the Coordination is put on a thread local stack in the begin method and must therefore be popped when the Coordination is finished. The finally block ensures therefore the proper cleanup of this thread local stack.

The difference between implicit and explicit Coordinations is that the implicit Coordination is not passed as a parameter, instead, collaborators use the current Coordination. With implicit Coordinations all method invocations in a thread can always access the current Coordination, even if they have many intermediates on the stack. The implicit model allows a collaborator many levels down the stack to detect a current Coordination and register itself without the need to modify all intermediate methods to contain a Coordination parameter. The explicit model has the advantage of explicitness but requires all APIs to be modified to hold the parameter. This model does not support passing the parameter through layers that are not aware of the Coordination. For example, OSGi services in general do not have a Coordination parameter in their methods making the use of explicit Coordinations impossible.

Collaborators can act differently in the presence of a current Coordination. For example, a collaborator can optimize its work flow depending on the presence of a current Coordination.

Coordinator coordinator = ...
void foo() {
  doPrepare();
  if ( !coordinator.addParticipant(this))
      doFinish();
}

The Coordinator service has an addParticipant method that makes working with the current Coordination simple. If there is a current Coordination then the Coordinator service will add the participant and return true, otherwise it returns false. It is therefore easy to react differently in the presence of a current Coordination. In the previous example, the doFinish method will be called immediately if there was no current Coordination, otherwise it is delayed until the Coordination fails or succeeds. The participant callbacks look the same as in the previous section:

public void ended(Coordination c)  { doFinish(); }
public void failed(Coordination c) { doFailed(); }

Though the code looks very similar for the implicit and explicit Coordinations there are some additional rules for implicit Coordinations.

The end method must be called on the same thread as the begin method, trying to end it on another thread results in a WRONG_THREAD Coordination Exception being thrown.

Even though the end method must be called on the initiating thread, the callbacks to the Participants can be done on any thread as the specification allows the Coordinator to use multiple threads for all callbacks.

The Coordination is a best effort mechanism to coordinate, not a transaction model with integrity guarantees. This means that users of the Coordinator service must understand that there are cases where a Coordination ends in limbo. This happens when one of the Participants throws an Exception in the ended callback. This is similar to a transactional resource manager failing to commit in a 2-phase commit after it has voted yes in the prepare phase; a problem that is the cause of much of the complexity of a transaction manager. The Coordinator is limited to use cases that do not require full ACID properties and can therefore be much simpler. However, users of the Coordinator service must be aware of this limitation.

If a Participant throws an exception in the ended method, the end method that terminated the Coordination must throw a PARTIALLY_ENDED Coordination Exception. It is then up to the initiator to correct the situations. In most cases, this means allowing the exception to be re-thrown and handle the failure at the top level. Handling in those cases usually implies logging and continuing.

The following code shows how the PARTIALLY_ENDED case can be handled more explicitly.

Coordination c = coordinator.begin("work",0);
try {
  doWork();
} catch( Excption e ) {
  c.fail(e);
} finally {
  try {
    c.end();
  } catch( CoordinationException e ) {
    if ( e.getType() == CoordinationException.PARTIALLY_ENDED) {
      // limbo!
      ...
    }
  }
}

To participate in a Coordination and receive callbacks a collaborator must add a Participant object to the Coordination. The addParticipant(Participant) method blocks if the given Participant object is already used in another Coordination. This blocking facility can be used to implement a number of simple locking schemes that can simplify maintaining state in a concurrent environment.

Using the Participant object as the key for the lock makes it simple to do course grained locking. For example, a service implementation could use the service object as a lock, effectively serializing access to this service when it is used in a Coordination. Coarse grained locking allows all the state to be maintained in the coarse object and not having to worry about multiplexing simultaneous requests. The following code uses the coarse locking pattern because the collaborator implements the Participant interface itself:

public class Collaborator implements Participant{
  public void doWork(Coordination coordination ) {
    ...
    coordination.addParticipant(this);
  }

  public void ended(Coordination c) { ... }
  public void failed(Coordination c) { ... }
}

The simplicity of the coarse grained locking is at the expense of lower performance because tasks are serialized even if it would have no contention. Locks can therefore also be made more fine grained, allowing more concurrency. In the extreme case, creating a new object for each participation makes it possible to never lock. For example, the following code never locks because it always creates a new object for the Participant:

    public void doWork(Coordination coordination){
      final State state = ...
      coordination.addParticipant(
         new Participant() {
           public void ended(Coordination c) { state ... }
           public void failed(Coordination c) { state ...}
    } ); }

Any collaborator can fail an ongoing Coordination by calling the fail(Throwable) method, the Throwable parameter must not be null. When the Coordination has already terminated then this is a no-op. The Coordinator service has a convenience method that fails the current Coordination if present. The fail methods return a boolean that is true when the method call causes the termination of the Coordination, in all other cases it is false.

Failing a Coordination will immediately perform the callbacks and reject any additional Participants by throwing an ALREADY_ENDED Coordination Exception. The asynchronous nature of the fail method implies that it is possible to have been called even before the addParticipant(Participant) method has returned. Anybody that has the Coordination object can check the failed state with the getFailure() method.

In general, the best and most robust strategy to handle failures is to throw an Exception from the collaborator, allowing the initiator to catch the exception and properly fail the Coordination.

The time-out is specified in the Coordinator create(String,long) or begin(String,long) methods. A time-out of zero is indefinite, otherwise the time-out specifies the number of milliseconds the Coordination can take to terminate. A given time-out can be extended with the extendTimeout(long) method. This method will add an additional time-out to the existing deadline if a prior deadline was set. For example, the following code extends the time-out with 5 seconds whenever a message must be sent to a remote address:

Object sendMessage(Message m) {
  Coordination c = coordinator.peek();
  Address a = m.getDestination();
  if ( c != null && a.isRemote() ) {
    c.extendTimeout(5000);
  }
  return sendMessage0(m);
}

Applications should not rely on the exact time-out of the Coordination and only use it as a safety function against deadlocks and hanging collaborators.

When a Coordination is terminated it is not yet completely finished, the callback to the Participants happens after the atomic termination. In certain cases it is necessary to ensure that a method does not progress until all the participants have been notified. It is therefore possible to wait for the Coordination to completely finish with the join(long) method. This method can have a time-out. For example:

void collaborate( final Coordination c ) {
  doWork();
  Thread t = new Thread() {
    public void run(){
      try {
          c.join(0);
          ... // really terminated here, all participantscalled back
      } catch( Exception e) { ... }
    }
  };
  t.start();
}

A Participant is likely to have to maintain state that is particular for the collaboration. This state is usually needed in the ended method to properly finalize the work. In general, the best place to store this state is in the Participant object itself, inner classes and final variables are a good technique for storing the state. However, the state can also be stored in a Coordination variable. Each Coordination has a private set of variables that can be obtained with the getVariables() method. The resulting map takes a class as the key and returns an Object. The map is not synchronized, any changes to the map must be synchronized on the returned Map object to ensure the visibility of the changes to other threads. The class used for the key is not related to the returned type, it is a Class object to provide a convenient namespace.

The following example shows how the state can be stored with variables.

public void doWork(Coordination coordination){
  Map<Class<?>,Object> map = coordination.getVariables();
  synchronized(map) {
    State state = (State) map.get( SharedWorker.class );
    if ( state == null ) {
      state = new State(this);
      map.put( state );
      ... do initial work
    }
  }
  ... do other work
  coordination.addParticipant( this );
}
public void ended(Coordination c) {
  Map<Class<?>,Object> map = coordination.getVariables();
  synchronized(map) {
    State state = (State) map.get( SharedWorker.class );
    .. finalize
  }  
}
public void failed(Coordination c) {
  Map<Class<?>,Object> map = coordination.getVariables();
  synchronized(map) {
    State state = (State) map.get( SharedWorker.class );
    .. finalize
  }
}

For example, a web based system has a charge service:

public interface Charge {
  void charge( String reason, int amount );
}

This service is used throughout the system for charging the tasks the system performs. Each servlet request can actually create multiple Charge Data Records (CDR). For this reason, a Coordination is started before the page is constructed. Each part of the page that has an associated cost must create a CDR. There are the following issues at stake:

To begin with the request code:

public void doGet(HttpServletRequest rq, HttpServletResponsersp) {
  Coordination c = coordinator.begin("com.acme.request", 30000);
  try {
    Principal p = rq.getUserPrincipal();
    Map<Class<?>,Object> map = c.getVariables();
    map.put( Principal.class, p );
    buildPage(rq,rsp);
  } catch( Exception e  ) { c.fail(e); } 
    finally               { c.end(); }
}

Each method that has a charge will call the Charge service. The following code shows an implementation of this Charge service.

public class ChargeImpl implements Charge,Participant {
  final List<CDR> records = new ArrayList<CDR>();

  public void charge( String reason, int amount ) {
    Coordination c = coordinator.peek();
    if ( c == null ) {
       save( Arrays.asList( new CDR(null, reason, amount)));
    } else {
      Principal p = getPrincipal(c);
      records.add( new CDR(p, reason, amount ) );
      c.addParticipant( this );
    }
  }

  Principal getPrincipal(Coordination c) {
    if ( c == null )
      return null;

    Map<Class<?>,Object> map = c.getVariables();
    synchronized(map) {
      Principal p = (Principal) map.get( Principal.class );
      return p != null ? p : getPrincipal(c.getEnclosingCoordination());
    }
  }

  public void ended(Coordination c) {
    save(records);
    records.clear();
  }
  public void failed(Coordination c) {
    records.clear();
  }

  void save(List<CDR> records) { ... }
}

The Coordination Permission is a filter based permission that is asserted for many of the methods in the API, the bundle that is checked is always the bundle that created the corresponding Coordination. For example:

ALLOW {
     [ BundleSignerCondition "cn=ACME" ]
    ( CoordinationPermission "(signer=cn=ACME)" "*" )
}

This example allows bundles signed by ACME to perform all Coordination actions on Coordinations created by bundles signed by ACME.

The filter can also assert the name of the Coordination:

coordination.name

It is therefore possible to create a name based protection scheme. By denying all bundles except a select group through the use of a name prefix, the use of Coordinations can be restricted to this select group:

DENY {
     [ BundleSignerCondition "cn=ACME" "!" ]
    ( CoordinationPermission "(coordination.name=com.acme.*)""*" )
}
ALLOW {
    ( CoordinationPermission "(coordination.name=*)" "*" )
}

If a bundle is not signed by ACME it will be denied the use of Coordination names starting with com.acme. though it will be allowed to use any other name. This effectively enables only bundles signed by ACME to create Coordinations with this name prefix.

A Coordination object is created by an initiator. An initiator can create a Coordination object with the Coordinator create(String,long) or begin(String,long) method. Each Coordination when created gets a positive long identity that is available with getId(). Ids are a unique identifier for a specific Coordinator service. The id is always increasing, that is, a Coordination with a higher id is created later.

The create methods specify the name of the Coordination. This name is a security concept, see Security, as well as used for debugging. The coordination name must therefore conform to the same syntax as a bundle symbolic name:

coordination-name ::= symbolic-name   // see OSGi Core Release 8

Passing a name that does not conform to this syntax must throw an Illegal Argument Exception. There are no constraints on duplicates, multiple different Coordinations can use the same name. The name of the Coordination is available with the getName() method.

The Coordination object can be passed to collaborators as a parameter in a method call. Some of these collaborators might be interested in participating in the given Coordination, they can achieve this by adding a Participant object to the Coordination.

A Participant is a collaborator that requires a callback after the Coordination has been terminated, either when it ended or when it failed. To participate, it must add a Participant object to a Coordination with the addParticipant(Participant) method on Coordination. This method throws an ALREADY_ENDED or FAILED Coordination Exception when the Coordination has been terminated.

When a Participant is:

Verifying if a Participant object is already in another Coordination must use identity and not equality.

A Coordination is active until it is terminated. A Coordination can terminate because it is ended, or it is failed. The following methods cause a termination:

The state diagram for the Coordination is pictured in Figure 130.4.

Figure 130.4 Coordination state diagram

The Coordinator supports two very different models of usage: explicit and implicit. The explicit model is when a Coordination is created and passed around as a parameter. The second model is the implicit model where the Coordinator maintains a thread local stack of Coordinations. Any collaborator can then decide to use the top of the stack as the current Coordination. The peek() method provides access to the current Coordination.

The begin(String,long) method creates a new Coordination and pushes this on the stack, beginning an implicit Coordination. This is identical to:

coordinator.create("work",0).push();

Once a Coordination is pushed on a stack it is from that moment on associated with the current thread. A Coordination can only be pushed once, the ALREADY_PUSHED Coordination Exception must be thrown when the Coordination is already associated with one of the thread local stacks maintained by the Coordinator service.

The Coordination is removed from the stack in the end() method. The end() method must not only terminate itself but it must also terminate all nested Coordinations.

The current Coordination can also be explicitly removed with the Coordinator pop() method.

A Coordination that is pushed on a thread local stack returns the associated thread on the getThread() method. This method returns null for Coordinations not on any stack, that is, explicit Coordinations.

Both the end() and fail(Throwable) methods terminate the Coordination if it was not already terminated. Termination is atomic, only the end or the fail method can terminate the Coordination. Though this happens on different threads, a Coordination can never both end and fail from any perspective. That is, if a fail races with end then only one of them can win and the other provides the feedback that the Coordination was already terminated.

Terminating a Coordination has the following effects:

The end() method should always be called at the end of a Coordination to ensure proper termination, notification, and cleanup. The end method throws a FAILED or PARTIALLY_ENDED Coordination Exception if the Coordination was failed before.

If the Coordination had already been ended before then this is a programming error and an ALREADY_ENDED Configuration Exception is thrown. The end() method should never be called twice on the same Coordination.

If the termination succeeds then the participants must be notified by calling the ended(Coordination) method on each Participant that had been successfully added to the Coordination. This callback can take place on any thread but must be in reverse order of adding. That is, the last added Participant is called back first.

Participants must never make any assumptions about the current Coordination in the callback. The Coordination it was added to is therefore given as an explicit parameter in the ended(Coordination) method.

If a Participant throws an Exception then this must not prevent the calling of the remaining participants. The Exception should be logged. If a Participant has thrown an Exception then the end() method must throw a PARTIALLY_ENDED Coordination Exception after the last Participant has returned from its callback, otherwise the method returns normally. Participants should normally not throw Exceptions in their callbacks.

If the Coordination is implicit (it is pushed on a stack) then the Coordination must be removed from its stack after the participants have been called back. This requires that the ending thread is the same as the thread of the Coordination. The end thread is the thread of the end() method call. If the Coordination's thread is not the same as the ending thread then a WRONG_THREAD Coordination Exception is thrown.

If the ending Coordination is on the stack but it is not the current Coordination then each nested Coordination must be ended before the current Coordination, see Nesting Implicit Coordinations for more information.

The fail(Throwable) method must not remove the current Coordination, it must remain on the stack. The initiator must always call the end() method. Always calling end() in a finally block is therefore paramount.

Failing can happen asynchronously during the time a Coordination is active. A Coordination is failed by calling fail(Throwable). The Throwable argument must not be null, it is the cause of the failure.

Failing a Coordination must first terminate it. If the Coordination was already terminated the fail(Throwable) method has no effect. Otherwise, it must callback all its added Participants on the failed(Coordination) callback method. Exceptions thrown from this method should be logged and further ignored. The callback can occur on any thread, including the caller's.

Implicit Coordinations must not be popped from its stack in a fail nor is it necessary to call the fail method from any particular thread. The removal of the Coordination from the stack must happen in the end method.

There are two asynchronous events that can also fail the Coordination. If the Coordination times out, it will be treated as a fail( TIMEOUT ) and if the Coordinator is ungotten with active Coordinations then each of those Coordinations must fail as if fail( RELEASED ) is called.

A Coordination can also be orphaned. An orphaned Coordination has no longer any outside references. This means that the Coordination can no longer be ended or failed. Such Coordinations must fail with an ORPHANED Exception.

Implicit Coordinations can be nested. For this reason, the Coordinator maintains a thread local stack of Coordinations where the top, accessible with the peek() method, is the current Coordination. Each time a new Coordination is begun with the begin(String,long) method, the current Coordination is replaced with the newly created Coordination. When that Coordination is ended, the previous current Coordination is restored. Nesting is always on the same thread, implicit Coordinations are always associated with a single thread, available through its getThread() method. The end method must be called on the same thread as the begin(String,long) or last push() method.

Using the standard model for implicit Coordinations, where the initiator always ends the Coordination on the same thread as it begun, ensures that nesting is properly handled. However, in certain cases it is necessary to manipulate the stack or make implicit Coordinations explicit or vice versa. For this reason, it is possible to pop Coordinations from the stack with the pop() method. This method disassociates the Coordination from the current thread and restores the previous (if any) Coordination as the current Thread. A Coordination can then be made the current Coordination for a thread by calling the push() method. However, a Coordination can be pushed on the stack at most once. If a Coordination is pushed a second time, in any thread, the ALREADY_PUSHED Coordination Exception must be thrown.

The Coordination is removed from its stack when the end() method is called. It is therefore highly recommended to always end a Coordination in the nesting order. However, it is possible that a Coordination is ended that is not the current Coordination, it has nested Coordinations that were not properly ended. In that case all nested Coordinations must be ended in reverse creation order, that is, the current Coordination first, by calling the end method on it.

If any Coordination fails to end properly (including PARTIALLY_ENDED ) then the remaining Coordinations on the stack must fail and chain the exceptions. In pseudo code:

while (coordinator.peek() != this) {
 try {
     coordinator.peek().end();
 } catch (CoordinationException e) {
      coordinator.peek().fail(e);
 }
}

When a Coordination is created it will receive a time-out. A time-out is a positive value or zero. A zero value indicates that the Coordination should have no time-out. This does not imply that a Coordination will never time-out, implementations are allowed to be configured with a limit to the maximum active time for a Coordination.

Collaborators can extend the time out with the extendTimeout(long) method. If no time-out was set (0), this method will be ignored. Otherwise the given amount (which must be positive) is added to the existing deadline. A Coordinator implementation can fail the Coordination earlier, however, when configured to do so.

If a Coordination is timed out, the Coordination is failed with a fail(TIMEOUT) method call from an unspecified thread, see Failing, TIMEOUT, ORPHANED, and RELEASED.

The Coordination's life cycle is bound to the Coordinator service that created it. If the initiator's bundle ungets this service then the Coordinator must fail all the Coordinations created by this Coordinator by calling the fail(RELEASED) method.

Participants from bundles that are stopped are not taken into account. This means that it is possible that a participant is called while its bundle is stopped. Stopped Participants should fail any Coordinations that they participate in.

The Coordinator contains a number of convenience methods that can be used by collaborators to interact with the current Coordination.

The Coordination objects provide a number of methods that are used for administrating the Coordinations and the Coordinator.

And for the Coordinator:

A Coordination can exist in three different states ACTIVE, END, and FAIL. During its life it will transition from ACTIVE to either END or FAIL. The entry (when the state is entered) and exit (when the state is left) actions when this transition takes place and the effect on the different methods are summarized in the following table.