Package org.apache.taverna.reference

Interfaces for the Taverna 2 reference manager.

See: Description

Interface Summary

Interface	Description
ContextualizedT2Reference	Used by the ReferenceService.traverseFrom(T2Reference, int) when traversing a collection structure.
ErrorDocument	Contains the definition of an error token within the workflow system.
ErrorDocumentDao	Data access object handling ErrorDocument instances.
ErrorDocumentService	Provides facilities to register list of T2References, register empty lists at any given depth and to resolve appropriate T2Reference instances back to these lists.
ErrorDocumentServiceCallback	Callback interface used by asynchronous methods in the ErrorDocumentService interface
ExternalReferenceBuilderSPI<TargetType extends ExternalReferenceSPI>	Constructs an ExternalReferenceSPI instance from a byte stream.
ExternalReferenceSPI	A reference to a single piece of data.
ExternalReferenceTranslatorSPI<SourceType extends ExternalReferenceSPI,TargetType extends ExternalReferenceSPI>	Constructs an ExternalReference instance from an existing ExternalReference, most usually of a different type.
Identified	Interface for any object that has an associated T2Reference
IdentifiedList<T>	An identified list is a list which is identified by a T2Reference.
ListDao	Data access object handling NamedLists of T2Reference instances.
ListService	Provides facilities to register list of T2References, register empty lists at any given depth and to resolve appropriate T2Reference instances back to these lists.
ListServiceCallback	Callback interface used by asynchronous methods in the ListService interface
ReferenceContext	Many operations over the reference manager require access to an appropriate context.
ReferenceService	Top level access point to the reference manager for client code which is aware of references and error documents.
ReferenceServiceCacheProvider	A simple interface to be implemented by data access object cache providers, intended to be used to inject cache implementations through AoP
ReferenceServiceResolutionCallback	Used by the asynchronous form of the resolveIdentifier method in ReferenceService
ReferenceSet	A set of ExternalReferenceSPI instances, all of which point to the same (byte equivalent) data.
ReferenceSetAugmentor	Provides a framework to find and engage appropriate instances of ExternalReferenceTranslatorSPI and ExternalReferenceBuilderSPI to build external references from, respectively, other external references and from streams.
ReferenceSetAugmentorCallback	Callback interface used when augmenting a ReferenceSet in an asynchronous fashion through augmentReferenceSetAsynch in ReferenceSetAugmentor.
ReferenceSetDao	Data Access Object interface for ReferenceSet.
ReferenceSetService	Provides facilities to register sets of ExternalReferenceSPI implementations within the reference manager and to retrieve these sets by T2Reference either as stored or with translation support.
ReferenceSetServiceCallback	Callback interface used by asynchronous methods in the ReferenceSetService interface
StackTraceElementBean	Used by the ErrorDocument interface to represent a frame within a stack trace
StreamToValueConverterSPI<T>	SPI for objects that can render a POJO from an InputStream
T2Reference	The T2Reference is used within the workflow system to refer to any entity within the reference management system, whether reference set, list or error document.
T2ReferenceGenerator	Provides new unique T2Reference instances.
ValueCarryingExternalReference<T>	Specialization of ExternalReferenceSPI for reference types which carry a value type internally.
ValueToReferenceConverterSPI	SPI for components that can convert an arbitrary object to an ExternalReferenceSPI representing the value of that object.

Class Summary

Class	Description
AbstractExternalReference	A trivial implementation of ExternalReference.
WorkflowRunIdEntity	Entity that wraps workflow run id and can be passed through ( ReferenceContext to be used by T2ReferenceGenerator to generate references that are specific for a workflow run.

Enum Summary

Enum	Description
ReferencedDataNature	Where possible ExternalReferenceSPI implementations should be able to determine whether the data they refer to is textual or binary in nature.
T2ReferenceType	The T2Reference interface is used to identify several different kinds of information, namely ReferenceSet, IdentifiedList and ErrorDocument.

Exception Summary

Exception	Description
DaoException	Thrown by the Data Access Object interface methods, wrapping any underlying exception.
DereferenceException	Thrown when a problem occurs during de-reference of an ExternalReferenceSPI implementation.
ErrorDocumentServiceException	RuntimeException subclass thrown by the error document service layer interfaces.
ExternalReferenceConstructionException	Thrown when an exception occurs during construction of an ExternalReferenceSPI instance.
ExternalReferenceValidationException	Thrown by setter methods and constructors of ExternalReferenceSPI implementations when fed parameters which cause some kind of format or validation error.
ListServiceException	Thrown by methods in the ListService interface if anything goes wrong with list registration or retrieval.
ReferenceServiceException	Thrown by methods in the ReferenceService, used to wrap any underlying exceptions from lower layers.
ReferenceSetAugmentationException	Thrown when the reference set augmentor is unable to provide at least one of the desired types for any reason.
ReferenceSetServiceException	RuntimeException subclass thrown by the reference set service layer interfaces.
ValueToReferenceConversionException	Thrown by instances of ValueToReferenceConvertor when trying to convert an object to an instance of ExternalReferenceSPI if the conversion process fails for some reason.

Package org.apache.taverna.reference Description

Interfaces for the Taverna 2 reference manager. This replaces the (badly named) DataManager and is, in effect, a version 2 of that system. While these APIs are implementation neutral the intent is heavily towards the use of an object relational mapping (ORM) tool such as Hibernate backed by a relational database to hold the various collection, external reference and error documents managed by the reference manager.

For those familiar with the previous DataManager code the table below shows the old class names and the equivalent (where appropriate) in the new code:

DataDocument	net.sf.taverna.t2.reference.ReferenceSet
ReferenceScheme	net.sf.taverna.t2.reference.ExternalReferenceSPI
EntityIdentifier	net.sf.taverna.t2.reference.T2Reference
...

One fundamental change is a move to runtime exceptions rather than checked exceptions. This follows the pattern used by Spring and Hibernate. The rationale is the same as in those systems - in general checked exceptions are not handled properly by client code. The loss of compiler level functionality from moving to runtime exceptions is countered by much higher readability of code which in itself leads to more robust and reliable systems.

A second change is the availability of asynchronous versions of all the critical APIs. Reference construction or translation in particular can be a costly process taking substantial time to complete. Synchronous versions of the get methods still exist but in general the simple callback based asynchronous ones are recommended over them for most applications.