[java-metadata-aggregator] 04/04: MDA-242 - Item implementations are NOT thread-safe
Ian Young
ian at iay.org.uk
Thu Jul 9 14:51:35 UTC 2020
This is an automated email from the git hooks/post-receive script.
iay pushed a commit to branch master
in repository java-metadata-aggregator.
View the commit online:
http://git.shibboleth.net/view/?p=java-metadata-aggregator.git;a=commit;h=e6c9f48de36f68835b91c034b96706c75577ff9c
commit e6c9f48de36f68835b91c034b96706c75577ff9c
Author: Ian Young <ian at iay.org.uk>
AuthorDate: Thu Jul 9 15:43:38 2020 +0100
MDA-242 - Item implementations are NOT thread-safe
https://issues.shibboleth.net/jira/browse/MDA-242
---
.../java/net/shibboleth/metadata/AbstractItem.java | 6 ++--
.../main/java/net/shibboleth/metadata/Item.java | 42 +++++++++++++++++++++-
.../shibboleth/metadata/dom/DOMElementItem.java | 4 +--
.../java/net/shibboleth/metadata/MockItem.java | 11 +++---
4 files changed, 53 insertions(+), 10 deletions(-)
diff --git a/aggregator-pipeline/src/main/java/net/shibboleth/metadata/AbstractItem.java b/aggregator-pipeline/src/main/java/net/shibboleth/metadata/AbstractItem.java
index 863a6b2..55329f9 100644
--- a/aggregator-pipeline/src/main/java/net/shibboleth/metadata/AbstractItem.java
+++ b/aggregator-pipeline/src/main/java/net/shibboleth/metadata/AbstractItem.java
@@ -19,7 +19,7 @@ package net.shibboleth.metadata;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;
-import javax.annotation.concurrent.ThreadSafe;
+import javax.annotation.concurrent.NotThreadSafe;
import net.shibboleth.utilities.java.support.annotation.constraint.NonnullElements;
import net.shibboleth.utilities.java.support.collection.ClassToInstanceMultiMap;
@@ -29,7 +29,7 @@ import net.shibboleth.utilities.java.support.collection.ClassToInstanceMultiMap;
*
* @param <T> type of data contained in the item
*/
- at ThreadSafe
+ at NotThreadSafe
public abstract class AbstractItem<T> implements Item<T> {
/** The actual data held by the item. */
@@ -53,7 +53,7 @@ public abstract class AbstractItem<T> implements Item<T> {
*
* @param newData the data
*/
- protected synchronized void setData(@Nullable final T newData) {
+ protected void setData(@Nullable final T newData) {
data = newData;
}
diff --git a/aggregator-pipeline/src/main/java/net/shibboleth/metadata/Item.java b/aggregator-pipeline/src/main/java/net/shibboleth/metadata/Item.java
index f1e8df5..f57db32 100644
--- a/aggregator-pipeline/src/main/java/net/shibboleth/metadata/Item.java
+++ b/aggregator-pipeline/src/main/java/net/shibboleth/metadata/Item.java
@@ -23,11 +23,51 @@ import javax.annotation.Nullable;
import net.shibboleth.utilities.java.support.annotation.constraint.NonnullElements;
import net.shibboleth.utilities.java.support.collection.ClassToInstanceMultiMap;
+// Checkstyle: LineLength OFF
/**
* A wrapper around a piece of information processed by pipeline stages.
*
- * @param <T> type of metadata element
+ * <p>
+ * Implementations of {@code Item} are <strong>not</strong> expected to be thread-safe.
+ * </p>
+ *
+ * <p>
+ * In multi-threaded applications, use of {@code Item} objects should be
+ * confined to a single thread at a time. When responsibility for an {@code Item}
+ * passes from one thread to another, actions in the sending and receiving threads
+ * must be synchronized such that the last use of the {@code Item} in the sending
+ * thread <em>happens-before</em> the first use of the {@code Item} in the receiving
+ * thread. The same must be true in reverse if responsibility for the {@code Item}
+ * is later transferred back to the original thread.
+ * </p>
+ *
+ * <p>
+ * Many constructs in the Java API, such as {@link java.util.concurrent.ExecutorService},
+ * provide such <em>happens-before</em> guarantees. Similarly, classes within the MDA
+ * framework such as {@link net.shibboleth.metadata.pipeline.PipelineDemultiplexerStage}
+ * provide the same guarantees and can be used without concern for synchronization.
+ * </p>
+ *
+ * <p>
+ * If you pass {@code Item}s between threads in some other way, however, you <strong>must</strong>
+ * make sure that no data races can occur.
+ * </p>
+ *
+ * <p>
+ * Note that if you call {@link Item#copy} to duplicate an item, the copy is entirely independent
+ * of the original except that they will share any attached immutable {@link ItemMetadata} objects.
+ * The two {@code Item} objects can then be used without additional synchronization, except for
+ * that involved in publishing the copy to the thread in which it will be used: a <em>happens-before</em>
+ * relationship is still required to guarantee that the receiving thread sees a consistent state
+ * for the object transferred.
+ * </p>
+ *
+ * @see <a href="https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/concurrent/package-summary.html#MemoryVisibility"
+ * >Memory Consistency Properties; <code>java.util.concurrent</code> package documentation</a>
+ *
+ * @param <T> type of item data
*/
+// Checkstyle: LineLength ON
public interface Item<T> {
/**
diff --git a/aggregator-pipeline/src/main/java/net/shibboleth/metadata/dom/DOMElementItem.java b/aggregator-pipeline/src/main/java/net/shibboleth/metadata/dom/DOMElementItem.java
index cf61929..623b6c1 100644
--- a/aggregator-pipeline/src/main/java/net/shibboleth/metadata/dom/DOMElementItem.java
+++ b/aggregator-pipeline/src/main/java/net/shibboleth/metadata/dom/DOMElementItem.java
@@ -18,7 +18,7 @@
package net.shibboleth.metadata.dom;
import javax.annotation.Nonnull;
-import javax.annotation.concurrent.ThreadSafe;
+import javax.annotation.concurrent.NotThreadSafe;
import org.w3c.dom.DOMImplementation;
import org.w3c.dom.Document;
@@ -35,7 +35,7 @@ import net.shibboleth.utilities.java.support.xml.ElementSupport;
* The {@link Element} wrapped by this {@link Item} is always the document element of the document that owns the
* {@link Element}.
*/
- at ThreadSafe
+ at NotThreadSafe
public class DOMElementItem extends AbstractItem<Element> {
/**
diff --git a/aggregator-pipeline/src/test/java/net/shibboleth/metadata/MockItem.java b/aggregator-pipeline/src/test/java/net/shibboleth/metadata/MockItem.java
index 2d2db4f..d59bc21 100644
--- a/aggregator-pipeline/src/test/java/net/shibboleth/metadata/MockItem.java
+++ b/aggregator-pipeline/src/test/java/net/shibboleth/metadata/MockItem.java
@@ -19,7 +19,10 @@ package net.shibboleth.metadata;
import java.util.Objects;
+import javax.annotation.concurrent.NotThreadSafe;
+
/** A mock implementation of {@link Item}. */
+ at NotThreadSafe
public class MockItem extends AbstractItem<String> {
/**
@@ -38,13 +41,13 @@ public class MockItem extends AbstractItem<String> {
return clone;
}
- /** {@inheritDoc} */
- @Override public int hashCode() {
+ @Override
+ public int hashCode() {
return unwrap().hashCode();
}
- /** {@inheritDoc} */
- @Override public boolean equals(Object obj) {
+ @Override
+ public boolean equals(Object obj) {
if (obj == null) {
return false;
}
--
To stop receiving notification emails like this one, please contact
the administrator of this repository.
More information about the commits
mailing list