aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorJohn Ross2011-11-03 19:43:56 (EDT)
committerJohn Ross2011-11-04 10:11:00 (EDT)
commitdbcdf393841ec34ab894d2551cdb5a5d8922e9b4 (patch)
treea11b95209c067b26690abe3c0fa6b5f9758d5e46
parent1f0b0459bd27cbaeb57c55d6bd7552a14ee5409c (diff)
downloadrt.equinox.bundles-dbcdf393841ec34ab894d2551cdb5a5d8922e9b4.zip
rt.equinox.bundles-dbcdf393841ec34ab894d2551cdb5a5d8922e9b4.tar.gz
rt.equinox.bundles-dbcdf393841ec34ab894d2551cdb5a5d8922e9b4.tar.bz2
Bug 362232 - [coordinator] Add support for the new, mandatory orphaned coordination requirement.
Updated OSGi Coordinator API.
-rw-r--r--bundles/org.eclipse.equinox.coordinator/src/org/osgi/service/coordinator/Coordination.java107
-rw-r--r--bundles/org.eclipse.equinox.coordinator/src/org/osgi/service/coordinator/package-info.java38
-rw-r--r--bundles/org.eclipse.equinox.coordinator/src/org/osgi/service/coordinator/packageinfo1
3 files changed, 97 insertions, 49 deletions
diff --git a/bundles/org.eclipse.equinox.coordinator/src/org/osgi/service/coordinator/Coordination.java b/bundles/org.eclipse.equinox.coordinator/src/org/osgi/service/coordinator/Coordination.java
index 3094850..6547f72 100644
--- a/bundles/org.eclipse.equinox.coordinator/src/org/osgi/service/coordinator/Coordination.java
+++ b/bundles/org.eclipse.equinox.coordinator/src/org/osgi/service/coordinator/Coordination.java
@@ -23,7 +23,7 @@ import org.osgi.framework.Bundle;
/**
* A Coordination object is used to coordinate a number of independent
* Participants.
- *
+ *
* <p>
* Once a Coordination is {@link Coordinator#create(String, long) created}, it
* can be used to add {@link Participant} objects. When the Coordination is
@@ -31,21 +31,21 @@ import org.osgi.framework.Bundle;
* A Coordination can also fail for various reasons. When this occurs, the
* participants are {@link Participant#failed(Coordination) notified} of the
* failure.
- *
+ *
* <p>
* 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.
- *
+ *
* <p>
* A Coordination object is thread safe and can be passed as a parameter to
* other parties regardless of the threads these parties use.
- *
+ *
* <p>
* The following example code shows how a Coordination should be used.
- *
+ *
* <pre>
* void foo() {
* Coordination c = coordinator.create(&quot;work&quot;, 0);
@@ -60,7 +60,7 @@ import org.osgi.framework.Bundle;
* }
* }
* </pre>
- *
+ *
* @ThreadSafe
* @noimplement
* @version $Id$
@@ -82,37 +82,43 @@ public interface Coordination {
Exception RELEASED = new Exception("RELEASED");
/**
+ * A singleton exception that will be the failure cause when a Coordination
+ * has been orphaned.
+ */
+ Exception ORPHANED = new Exception("ORPHANED");
+
+ /**
* Returns the id assigned to this Coordination.
- *
+ *
* The id is assigned by the {@link 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.
- *
+ *
* @return The id assigned to this Coordination.
*/
long getId();
/**
* Returns the name of this Coordination.
- *
+ *
* The name is specified when this Coordination was created.
- *
+ *
* @return The name of this Coordination.
- *
+ *
*/
String getName();
/**
* Terminate this Coordination normally.
- *
+ *
* <p>
* If this Coordination has been {@link #push() pushed} on the thread local
* Coordination stack of another thread, this method does nothing except
* throw a CoordinationException of type
* {@link CoordinationException#WRONG_THREAD}.
- *
+ *
* <p>
* If this Coordination has been {@link #push() pushed} on the thread local
* Coordination stack of this thread but is not the
@@ -128,18 +134,18 @@ public interface Coordination {
* Coordination will be the current Coordination and will have been
* terminated as a failure if any of the terminated Coordinations threw a
* CoordinationException
- *
+ *
* <p>
* If this Coordination is the {@link Coordinator#peek() current
* Coordination}, then it will be {@link Coordinator#pop() removed} from the
* thread local Coordination stack.
- *
+ *
* <p>
* If this Coordination is already terminated, a CoordinationException is
* thrown. If this Coordination was terminated as a failure, the
* {@link #getFailure() failure cause} will be the cause of the thrown
* CoordinationException.
- *
+ *
* <p>
* Otherwise, this Coordination is terminated normally and then all
* registered {@link #getParticipants() Participants} are
@@ -148,14 +154,14 @@ public interface Coordination {
* return of this method indicates that the Coordination has terminated
* normally and all registered Participants have been notified of the normal
* termination.
- *
+ *
* <p>
* 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 {@link 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.
@@ -167,11 +173,11 @@ public interface Coordination {
/**
* Terminate this Coordination as a failure with the specified failure
* cause.
- *
+ *
* <p>
* If this Coordination is already {@link #isTerminated() terminated}, this
* method does nothing and returns {@code false}.
- *
+ *
* <p>
* Otherwise, this Coordination is terminated as a failure with the
* specified failure cause and then all registered
@@ -179,14 +185,14 @@ public interface Coordination {
* {@link Participant#failed(Coordination) notified}. Participants should
* discard any work associated with this Coordination. This method will
* return {@code true}.
- *
+ *
* <p>
* If this Coordination has been {@link #push() pushed} onto a thread local
* Coordination stack, this Coordination is not removed from the stack. The
* creator of this Coordination must still call {@link #end()} on this
* Coordination to cause it to be removed from the thread local Coordination
* stack.
- *
+ *
* @param cause The failure cause. The failure cause must not be
* {@code null}.
* @return {@code true} if this Coordination was active and was terminated
@@ -207,18 +213,20 @@ public interface Coordination {
* If this Coordination timed out, this method will return {@link #TIMEOUT}
* as the failure cause. If this Coordination was active when the bundle
* that created it released the {@link Coordinator} service, this method
- * will return {@link #RELEASED} as the failure cause.
+ * will return {@link #RELEASED} as the failure cause. If the Coordination
+ * was orphaned, this method will return {@link #ORPHANED} as the failure
+ * cause.
*
* @return The failure cause of this Coordination or {@code null} if this
* Coordination has not terminated as a failure.
- * @throws SecurityException If the caller does not have {@code
- * CoordinationPermission[INITIATE]} for this Coordination.
+ * @throws SecurityException If the caller does not have
+ * {@code CoordinationPermission[INITIATE]} for this Coordination.
*/
Throwable getFailure();
/**
* Returns whether this Coordination is terminated.
- *
+ *
* @return {@code true} if this Coordination is terminated, otherwise
* {@code false} if this Coordination is active.
*/
@@ -226,20 +234,20 @@ public interface Coordination {
/**
* Register a Participant with this Coordination.
- *
+ *
* <p>
* Once a Participant is registered with this Coordination, it is guaranteed
* to receive a notification for either
* {@link Participant#ended(Coordination) normal} or
* {@link Participant#failed(Coordination) failure} termination when this
* Coordination is terminated.
- *
+ *
* <p>
* 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.
- *
+ *
* <p>
* A Participant can only be registered with a single active Coordination at
* a time. If a Participant is already registered with an active
@@ -248,30 +256,31 @@ public interface Coordination {
* registered with terminates. Notice that in edge cases the notification to
* the Participant that this Coordination has terminated can happen before
* this method returns.
- *
+ *
* <p>
* Attempting to register a Participant with a {@link #isTerminated()
* terminated} Coordination will result in a CoordinationException being
* thrown.
- *
+ *
* <p>
- * The ordering of notifying Participants must follow the order in which the
- * Participants were registered.
- *
+ * The ordering of notifying Participants must follow the reverse order in
+ * which the Participants were registered.
+ *
* @param participant The Participant to register with this Coordination.
* The participant must not be {@code 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.
- * @throws SecurityException If the caller does not have {@code
- * CoordinationPermission[PARTICIPATE]} for this Coordination.
+ * @throws SecurityException If the caller does not have
+ * {@code CoordinationPermission[PARTICIPATE]} for this
+ * Coordination.
*/
void addParticipant(Participant participant);
/**
* Returns a snapshot of the Participants registered with this Coordination.
- *
+ *
* @return 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
@@ -284,15 +293,15 @@ public interface 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.
- *
+ *
* @return The variable map associated with this Coordination.
* @throws SecurityException If the caller does not have {@code
* CoordinationPermission[PARTICIPANT]} for this Coordination.
@@ -301,15 +310,15 @@ public interface Coordination {
/**
* Extend the time out of this Coordination.
- *
+ *
* <p>
* 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.
- *
+ *
* @param 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.
@@ -328,7 +337,7 @@ public interface Coordination {
/**
* Wait until this Coordination is terminated and all registered
* Participants have been notified.
- *
+ *
* @param timeMillis Maximum time in milliseconds to wait. Specifying a time
* of 0 will wait until this Coordination is terminated.
* @throws InterruptedException If the wait is interrupted.
@@ -342,7 +351,7 @@ public interface Coordination {
/**
* Push this Coordination object onto the thread local Coordination stack to
* make it the {@link Coordinator#peek() current Coordination}.
- *
+ *
* @return This Coordination.
* @throws CoordinationException If this Coordination is already on the any
* thread's thread local Coordination stack or this Coordination
@@ -355,7 +364,7 @@ public interface Coordination {
/**
* Returns the thread in whose thread local Coordination stack this
* Coordination has been {@link #push() pushed}.
- *
+ *
* @return The thread in whose thread local Coordination stack this
* Coordination has been pushed or {@code null} if this Coordination
* is not in any thread local Coordination stack.
@@ -368,7 +377,7 @@ public interface Coordination {
* Returns the bundle that created this Coordination. This is the bundle
* that obtained the {@link Coordinator} service that was used to create
* this Coordination.
- *
+ *
* @return The bundle that created this Coordination.
* @throws SecurityException If the caller does not have {@code
* CoordinationPermission[ADMIN]} for this Coordination.
@@ -378,7 +387,7 @@ public interface Coordination {
/**
* Returns the Coordination enclosing this Coordination if this Coordination
* is on the thread local Coordination stack.
- *
+ *
* <p>
* When a Coordination is {@link #push() pushed} onto the thread local
* Coordination stack, the former {@link Coordinator#peek() current
@@ -386,7 +395,7 @@ public interface Coordination {
* Coordination. When this Coordination is {@link Coordinator#pop() removed}
* from the thread local Coordination stack, this Coordination no longer has
* an enclosing Coordination.
- *
+ *
* @return The Coordination enclosing this Coordination if this Coordination
* is on the thread local Coordination stack or {@code null} if this
* Coordination is not on the thread local Coordination stack or has
diff --git a/bundles/org.eclipse.equinox.coordinator/src/org/osgi/service/coordinator/package-info.java b/bundles/org.eclipse.equinox.coordinator/src/org/osgi/service/coordinator/package-info.java
new file mode 100644
index 0000000..a48f965
--- /dev/null
+++ b/bundles/org.eclipse.equinox.coordinator/src/org/osgi/service/coordinator/package-info.java
@@ -0,0 +1,38 @@
+/*
+ * Copyright (c) OSGi Alliance (2010). 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.
+ */
+
+/**
+ * Coordinator Package Version 1.0.
+ *
+ * <p>
+ * Bundles wishing to use this package must list the package in the
+ * Import-Package header of the bundle's manifest. This package has two types of
+ * users: the consumers that use the API in this package and the providers that
+ * implement the API in this package.
+ *
+ * <p>
+ * Example import for consumers using the API in this package:
+ * <p>
+ * {@code Import-Package: org.osgi.service.coordinator; version="[1.0,2.0)"}
+ * <p>
+ * Example import for providers implementing the API in this package:
+ * <p>
+ * {@code Import-Package: org.osgi.service.coordinator; version="[1.0,1.1)"}
+ *
+ * @version $Id$
+ */
+
+package org.osgi.service.coordinator;
diff --git a/bundles/org.eclipse.equinox.coordinator/src/org/osgi/service/coordinator/packageinfo b/bundles/org.eclipse.equinox.coordinator/src/org/osgi/service/coordinator/packageinfo
new file mode 100644
index 0000000..7c8de03
--- /dev/null
+++ b/bundles/org.eclipse.equinox.coordinator/src/org/osgi/service/coordinator/packageinfo
@@ -0,0 +1 @@
+version 1.0