Package net.shibboleth.metadata

Interface Item<T>

Type Parameters:
T - type of item data
All Known Implementing Classes:
AbstractItem, DOMElementItem
public interface Item<T>
A wrapper around a piece of information processed by pipeline stages.

Implementations of Item are not expected to be thread-safe.

In multi-threaded applications, use of Item objects should be confined to a single thread at a time. When responsibility for an Item passes from one thread to another, actions in the sending and receiving threads must be synchronized such that the last use of the Item in the sending thread happens-before the first use of the Item in the receiving thread. The same must be true in reverse if responsibility for the Item is later transferred back to the original thread.

Many constructs in the Java API, such as ExecutorService, provide such happens-before guarantees. Similarly, classes within the MDA framework such as PipelineDemultiplexerStage provide the same guarantees and can be used without concern for synchronization.

If you pass Items between threads in some other way, however, you must make sure that no data races can occur.

Note that if you call copy() to duplicate an item, the copy is entirely independent of the original except that they will share any attached immutable ItemMetadata objects. The two 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 happens-before relationship is still required to guarantee that the receiving thread sees a consistent state for the object transferred.

See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    Item<T>
    copy()
    Performs a copy of this Item.
    net.shibboleth.shared.collection.ClassToInstanceMultiMap<ItemMetadata>
    getItemMetadata()
    Gets all of the metadata attached to this Item.
    T
    unwrap()
    Gets the wrapped item data.

  • Method Details

    • unwrap

      @Nonnull T unwrap()
      Gets the wrapped item data.
      Returns:
      the wrapped item data

    • getItemMetadata

      @Nonnull @NonnullElements net.shibboleth.shared.collection.ClassToInstanceMultiMap<ItemMetadata> getItemMetadata()
      Gets all of the metadata attached to this Item.
      Returns:
      metadata attached to this Item

    • copy

      @Nonnull Item<T> copy()
      Performs a copy of this Item. All member fields, except ItemMetadata, should be deep cloned. ItemMetadata objects must be shared between the clone and the original.
      Returns:
      the clone of this Item