Start line:  
End line:  

Snippet Preview

Snippet HTML Code

Stack Overflow Questions
  /*
   * Copyright (c) OSGi Alliance (2010, 2013). All Rights Reserved.
   *
   * Licensed under the Apache License, Version 2.0 (the "License");
   * you may not use this file except in compliance with the License.
   * You may obtain a copy of the License at
   *
   *      http://www.apache.org/licenses/LICENSE-2.0
   *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
 
 package org.osgi.service.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();
 }
 

Author(s):
$Id: e2e1850c645234dd7a546a2f6a77ba6fc8d3c73b $
ThreadSafe:
Noimplement:
 
 public interface Coordinator {

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.
	Coordination create(String namelong 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.
	Coordination begin(String namelong timeMillis);

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.
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.
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(java.lang.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(java.lang.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(java.lang.Throwable)
	boolean fail(Throwable cause);

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(org.osgi.service.coordinator.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(org.osgi.service.coordinator.Participant)
	boolean addParticipant(Participant participant);

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.
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.
New to GrepCode? Check out our FAQ X