Start line:  
End line:  

Snippet Preview

Snippet HTML Code

Stack Overflow Questions
  /*
   * Copyright (c) OSGi Alliance (2010, 2011). 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;
 
 import java.util.List;
 import java.util.Map;
 
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();
   }
 }
 

Version:
$Id: 6547f729fc34bc31639a1ac73048f5c8258c337f $
ThreadSafe:
Noimplement:
 
 
 public interface Coordination {

A singleton exception that will be the failure cause when a Coordination times out.
 
 	Exception	TIMEOUTnew Exception("TIMEOUT");

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.
 
 	Exception	RELEASEDnew Exception("RELEASED");

A singleton exception that will be the failure cause when a Coordination has been orphaned.
 
 	Exception	ORPHANEDnew Exception("ORPHANED");

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.
	long getId();

Returns the name of this Coordination. The name is specified when this Coordination was created.

Returns:
The name of this Coordination.
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.
	void end();

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

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.
Returns whether this Coordination is terminated.

Returns:
true if this Coordination is terminated, otherwise false if this Coordination is active.
	boolean isTerminated();

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.
	void addParticipant(Participant participant);

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.
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.
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 returns the new deadline. 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.
	long extendTimeout(long timeMillis);

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.
	void join(long timeMillisthrows InterruptedException;

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