You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@taverna.apache.org by re...@apache.org on 2015/03/23 17:38:24 UTC
[40/51] [partial] incubator-taverna-engine git commit:
http://git-wip-us.apache.org/repos/asf/incubator-taverna-engine/blob/5f1ddb71/taverna-reference-api/src/main/java/org/apache/taverna/reference/ListService.java
----------------------------------------------------------------------
diff --git a/taverna-reference-api/src/main/java/org/apache/taverna/reference/ListService.java b/taverna-reference-api/src/main/java/org/apache/taverna/reference/ListService.java
new file mode 100644
index 0000000..3df2b5b
--- /dev/null
+++ b/taverna-reference-api/src/main/java/org/apache/taverna/reference/ListService.java
@@ -0,0 +1,143 @@
+/*
+* Licensed to the Apache Software Foundation (ASF) under one
+* or more contributor license agreements. See the NOTICE file
+* distributed with this work for additional information
+* regarding copyright ownership. The ASF licenses this file
+* to you 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.apache.taverna.reference;
+
+import static org.springframework.transaction.annotation.Propagation.REQUIRED;
+import static org.springframework.transaction.annotation.Propagation.SUPPORTS;
+
+import java.util.List;
+
+import org.springframework.transaction.annotation.Transactional;
+
+/**
+ * Provides facilities to register list of T2References, register empty lists at
+ * any given depth and to resolve appropriate T2Reference instances back to
+ * these lists. Registration operations assign names and lock the list contents
+ * as a result. This service operates strictly on T2References, it neither tries
+ * to nor is capable of any form of reference resolution, so aspects such as
+ * collection traversal are not handled here (these are performed by the top
+ * level reference service)
+ *
+ * @author Tom Oinn
+ */
+@Transactional(propagation = SUPPORTS, readOnly = true)
+public interface ListService {
+ /**
+ * Register a new list of T2References. The depth of the list will be
+ * calculated based on the depth of the references within it - if these are
+ * not uniform the list won't be created (all children of a list in T2 must
+ * have the same depth as their siblings). Provided this constraint is
+ * satisfied the list is named and stored in the backing store. The returned
+ * list is at this point immutable, operations modifying it either directly
+ * or through the ListIterator will fail with an IllegalStateException.
+ * Implementations should copy the input list rather than keeping a
+ * reference to it to preserve this property.
+ * <p>
+ * The created references will be related with a workflow run id passed
+ * through ReferenceContext so we can track all data referenced by a
+ * specific run.
+ *
+ * @param items
+ * the T2Reference instances to store as a list.
+ * @return a new IdentifiedList of T2Reference instances allocated with a
+ * T2Reference itself as the unique name and cached by the backing
+ * store.
+ * @throws ListServiceException
+ * if there is a problem either with the specified list of
+ * references or with the storage subsystem.
+ */
+ @Transactional(propagation = REQUIRED, readOnly = false)
+ IdentifiedList<T2Reference> registerList(List<T2Reference> items,
+ ReferenceContext context) throws ListServiceException;
+
+ /**
+ * Register a new empty list with the specified depth. This is needed
+ * because in the case of empty lists we can't calculate the depth from the
+ * list items (what with there not being any!), but the depth property is
+ * critical for the T2 iteration and collection management system in the
+ * enactor - we need to know that this is an empty list that
+ * <em>would have</em> contained lists, for example.
+ * <p>
+ * The created references will be related with a workflow run id passed
+ * through ReferenceContext so we can track all data referenced by a
+ * specific run.
+ *
+ * @param depth
+ * the depth of the empty list, must be >=1
+ * @return a new empty IdentifiedList allocated with a T2Reference itself as
+ * the unique name and cached by the backing store.
+ * @throws ListServiceException
+ * if there is a problem with the storage subsystem or if called
+ * with an invalid depth argument
+ */
+ @Transactional(propagation = REQUIRED, readOnly = false)
+ IdentifiedList<T2Reference> registerEmptyList(int depth,
+ ReferenceContext context) throws ListServiceException;
+
+ /**
+ * Retrieve a previously named and registered list of T2Reference instances
+ * identified by the specified T2Reference (which must be of type
+ * T2ReferenceType.IdentifiedList)
+ *
+ * @param id
+ * identifier of the list of reference to retrieve
+ * @return an IdentifiedList of T2References. Note that because this list is
+ * named it is effectively immutable, if you want to modify the list
+ * you have to create and register a new list, you cannot modify the
+ * returned value of this directly. This is why there is no update
+ * method in the service or dao for reference lists.
+ * @throws ListServiceException
+ * if anything goes wrong with the retrieval process or if there
+ * is something wrong with the reference (such as it being of
+ * the wrong reference type).
+ */
+ IdentifiedList<T2Reference> getList(T2Reference id)
+ throws ListServiceException;
+
+ /**
+ * Functionality the same as {@link #getList(T2Reference) getList} but in
+ * asynchronous mode, returning immediately and using the supplied callback
+ * to communicate its results.
+ *
+ * @param id
+ * a {@link T2Reference} identifying an {@link IdentifiedList} to
+ * retrieve
+ * @param callback
+ * a {@link ListServiceCallback} used to convey the results of
+ * the asynchronous call
+ * @throws ListServiceException
+ * if the reference set service is not correctly configured.
+ * Exceptions encountered when performing the asynchronous call
+ * are not returned here, for obvious reasons, and are instead
+ * messaged through the callback interface.
+ */
+ void getListAsynch(T2Reference id, ListServiceCallback callback)
+ throws ListServiceException;
+
+ @Transactional(propagation = SUPPORTS, readOnly = false)
+ boolean delete(T2Reference reference) throws ReferenceServiceException;
+
+ /**
+ * Delete all {@link IdentifiedList}S used by the specific workflow run.
+ */
+ @Transactional(propagation = SUPPORTS, readOnly = false)
+ void deleteIdentifiedListsForWorkflowRun(String workflowRunId)
+ throws ReferenceServiceException;
+}
http://git-wip-us.apache.org/repos/asf/incubator-taverna-engine/blob/5f1ddb71/taverna-reference-api/src/main/java/org/apache/taverna/reference/ListServiceCallback.java
----------------------------------------------------------------------
diff --git a/taverna-reference-api/src/main/java/org/apache/taverna/reference/ListServiceCallback.java b/taverna-reference-api/src/main/java/org/apache/taverna/reference/ListServiceCallback.java
new file mode 100644
index 0000000..4915d39
--- /dev/null
+++ b/taverna-reference-api/src/main/java/org/apache/taverna/reference/ListServiceCallback.java
@@ -0,0 +1,46 @@
+/*
+* Licensed to the Apache Software Foundation (ASF) under one
+* or more contributor license agreements. See the NOTICE file
+* distributed with this work for additional information
+* regarding copyright ownership. The ASF licenses this file
+* to you 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.apache.taverna.reference;
+
+/**
+ * Callback interface used by asynchronous methods in the
+ * {@link ListService} interface
+ *
+ * @author Tom Oinn
+ */
+public interface ListServiceCallback {
+ /**
+ * Called when the requested {@link ReferenceSet} has been successfully
+ * retrieved.
+ *
+ * @param references
+ * the ReferenceSet requested
+ */
+ void listRetrieved(IdentifiedList<T2Reference> references);
+
+ /**
+ * Called if the retrieval failed for some reason
+ *
+ * @param cause
+ * a ListServiceException explaining the retrieval
+ * failure
+ */
+ void listRetrievalFailed(ListServiceException cause);
+}
http://git-wip-us.apache.org/repos/asf/incubator-taverna-engine/blob/5f1ddb71/taverna-reference-api/src/main/java/org/apache/taverna/reference/ListServiceException.java
----------------------------------------------------------------------
diff --git a/taverna-reference-api/src/main/java/org/apache/taverna/reference/ListServiceException.java b/taverna-reference-api/src/main/java/org/apache/taverna/reference/ListServiceException.java
new file mode 100644
index 0000000..6379596
--- /dev/null
+++ b/taverna-reference-api/src/main/java/org/apache/taverna/reference/ListServiceException.java
@@ -0,0 +1,47 @@
+/*
+* Licensed to the Apache Software Foundation (ASF) under one
+* or more contributor license agreements. See the NOTICE file
+* distributed with this work for additional information
+* regarding copyright ownership. The ASF licenses this file
+* to you 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.apache.taverna.reference;
+
+/**
+ * Thrown by methods in the ListService interface if anything goes wrong with
+ * list registration or retrieval. Any underlying exceptions that can't be
+ * handled in the service layer are wrapped in this and re-thrown.
+ *
+ * @author Tom Oinn
+ */
+public class ListServiceException extends RuntimeException {
+ private static final long serialVersionUID = 5049346991071587866L;
+
+ public ListServiceException() {
+ super();
+ }
+
+ public ListServiceException(String message) {
+ super(message);
+ }
+
+ public ListServiceException(Throwable cause) {
+ super(cause);
+ }
+
+ public ListServiceException(String message, Throwable cause) {
+ super(message, cause);
+ }
+}
http://git-wip-us.apache.org/repos/asf/incubator-taverna-engine/blob/5f1ddb71/taverna-reference-api/src/main/java/org/apache/taverna/reference/ReferenceContext.java
----------------------------------------------------------------------
diff --git a/taverna-reference-api/src/main/java/org/apache/taverna/reference/ReferenceContext.java b/taverna-reference-api/src/main/java/org/apache/taverna/reference/ReferenceContext.java
new file mode 100644
index 0000000..26b330b
--- /dev/null
+++ b/taverna-reference-api/src/main/java/org/apache/taverna/reference/ReferenceContext.java
@@ -0,0 +1,65 @@
+/*
+* Licensed to the Apache Software Foundation (ASF) under one
+* or more contributor license agreements. See the NOTICE file
+* distributed with this work for additional information
+* regarding copyright ownership. The ASF licenses this file
+* to you 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.apache.taverna.reference;
+
+import java.util.List;
+
+/**
+ * Many operations over the reference manager require access to an appropriate
+ * context. The context contains hooks out to platform level facilities such as
+ * the security agent framework (when used in conjunction with the enactor).
+ * <p>
+ * This interface is also used to pass in resources required by the external
+ * reference translation and construction SPIs. An example might be a translator
+ * from File to URL could work by copying the source file to a web share of some
+ * kind, but obviously this can't happen unless properties such as the location
+ * of the web share folder are known. These properties tend to be properties of
+ * the installation rather than of the code, referring as they do to resources
+ * on the machine hosting the reference manager (and elsewhere).
+ * <p>
+ * Where entities in the context represent properties of the platform rather
+ * than the 'session' they are likely to be configured in a central location
+ * such as a Spring context definition, this interface is neutral to those
+ * concerns.
+ *
+ * @author Tom Oinn
+ */
+public interface ReferenceContext {
+ /**
+ * Return a list of all entities in the resolution context which match the
+ * supplied entity type argument.
+ *
+ * @param <T>
+ * The generic type of the returned entity list. In general the
+ * compiler is smart enough that you don't need to specify this,
+ * it can pick it up from the entityType parameter.
+ * @param entityType
+ * Class of entity to return. Use Object.class to return all
+ * entities within the reference context
+ * @return a list of entities from the reference context which can be cast
+ * to the specified type.
+ */
+ <T extends Object> List<T> getEntities(Class<T> entityType);
+
+ /**
+ * Add an entity to the context.
+ */
+ void addEntity(Object entity);
+}
http://git-wip-us.apache.org/repos/asf/incubator-taverna-engine/blob/5f1ddb71/taverna-reference-api/src/main/java/org/apache/taverna/reference/ReferenceService.java
----------------------------------------------------------------------
diff --git a/taverna-reference-api/src/main/java/org/apache/taverna/reference/ReferenceService.java b/taverna-reference-api/src/main/java/org/apache/taverna/reference/ReferenceService.java
new file mode 100644
index 0000000..1cb0147
--- /dev/null
+++ b/taverna-reference-api/src/main/java/org/apache/taverna/reference/ReferenceService.java
@@ -0,0 +1,293 @@
+/*
+* Licensed to the Apache Software Foundation (ASF) under one
+* or more contributor license agreements. See the NOTICE file
+* distributed with this work for additional information
+* regarding copyright ownership. The ASF licenses this file
+* to you 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.apache.taverna.reference;
+
+import static org.springframework.transaction.annotation.Propagation.REQUIRED;
+import static org.springframework.transaction.annotation.Propagation.SUPPORTS;
+
+import java.util.Iterator;
+import java.util.List;
+import java.util.Set;
+
+import org.springframework.transaction.annotation.Transactional;
+
+/**
+ * Top level access point to the reference manager for client code which is
+ * aware of references and error documents. Provides methods to store and
+ * retrieve instances of ReferenceSet, IdentifiedList<T2Reference> and
+ * ErrorDocument. Acts as an integration layer for the three sub-component
+ * service, providing in addition collection traversal and retrieval of lists of
+ * identified entities (ReferenceSet, IdentifiedList<Identified> and
+ * ErrorDocument) from a T2Reference identifying a list.
+ * <p>
+ * Also provides registration and retrieval logic for POJOs where supported by
+ * appropriate plug-in instances, these methods can be used by code which is not
+ * 'reference aware' to store and retrieve value types transparently.
+ * <p>
+ * Resolution of collections can happen at three different levels:
+ * <ol>
+ * <li>The embedded {@link ListService} resolves the collection ID to a list of
+ * child IDs, and doesn't traverse these children if they are themselves lists.
+ * Use the {@link #getListService()}.{@link ListService#getList(T2Reference)
+ * getList()} to call this method directly on the list service if you need this
+ * functionality, returning a list of {@link T2Reference}</li>
+ * <li>The {@link #resolveIdentifier(T2Reference, Set, ReferenceContext)
+ * resolveIdentifier} method in this service instead resolves to a fully
+ * realized collection of the entities which those IDs reference, and does
+ * recursively apply this to child lists, resulting in a nested collection
+ * structure where the leaf nodes are ReferenceSet and ErrorDocument instances
+ * and non-leaf are IdentifiedList of Identified (the super-interface for
+ * IdentifiedList, ReferenceSet and ErrorDocument). Use this method if you want
+ * to access the ExternalReferenceSPI and ErrorDocument entities directly
+ * because your code can act on a particular reference type - in general in
+ * these cases you would also be using the augmentation system to ensure that
+ * the required reference type was actually present in the collection structure.
+ * </li>
+ * <li>The third level of resolution is to render the identifier through
+ * {@link #renderIdentifier(T2Reference, Class, ReferenceContext)
+ * renderIdentifier} to a nested structure as in
+ * {@link #resolveIdentifier(T2Reference, Set, ReferenceContext)
+ * resolveIdentifier} but where the structure consists of POJOs of the specified
+ * type and lists or either list or the leaf type. This is used when your code
+ * is reference agnostic and just requires the values in an easy to consume
+ * fashion. Note that because this involves pulling the entire structure into
+ * memory it may not be suitable for large data, use with caution. This method
+ * will, unlike {@link #resolveIdentifier(T2Reference, Set, ReferenceContext)
+ * resolveIdentifier}, fail if the reference contains or is an error.</li>
+ * </ol>
+ *
+ * @author Tom Oinn
+ */
+public interface ReferenceService {
+ /**
+ * Perform recursive identifier resolution, building a collection structure
+ * of Identified objects, any collection elements being IdentifiedLists of
+ * Identified subclasses. If the id has depth 0 this will just return the
+ * Identified to which that id refers.
+ *
+ * @param id
+ * the T2Reference to resolve
+ * @param ensureTypes
+ * a set of ExternalReferenceSPI classes, this is used to augment
+ * any resolved ReferenceSet instances to ensure that each one
+ * has at least one of the specified types. If augmentation is
+ * not required this can be set to null.
+ * @param context
+ * the ReferenceContext to use to resolve this and any
+ * recursively resolved identifiers <br/>
+ * If null the implementation should insert a new empty context
+ * and proceed.
+ * @return fully resolved Identified subclass - this is either a (recursive)
+ * IdentifiedList of Identified, a ReferenceSet or an ErrorDocument
+ * @throws ReferenceServiceException
+ * if any problems occur during resolution
+ */
+ @Transactional(propagation = REQUIRED, readOnly = false)
+ Identified resolveIdentifier(T2Reference id,
+ Set<Class<ExternalReferenceSPI>> ensureTypes,
+ ReferenceContext context) throws ReferenceServiceException;
+
+ /**
+ * As resolveIdentifier but using a callback object and returning
+ * immediately
+ *
+ * @throws ReferenceServiceException
+ * if anything goes wrong with the setup of the resolution job.
+ * Any exceptions during the resolution process itself are
+ * communicated through the callback object.
+ */
+ @Transactional(propagation = REQUIRED, readOnly = false)
+ void resolveIdentifierAsynch(T2Reference id,
+ Set<Class<ExternalReferenceSPI>> ensureTypes,
+ ReferenceContext context,
+ ReferenceServiceResolutionCallback callback)
+ throws ReferenceServiceException;
+
+ /**
+ * Resolve the given identifier, building a POJO structure where the
+ * non-list items are of the desired class. This makes of any external
+ * references that can directly expose the appropriate object type, then, if
+ * none are present in a given reference set, it attempts to locate a POJO
+ * builder and uses the cheapest available reference to get an InputStream
+ * and build the target object. If no appropriate builder or embedded value
+ * can be found the process throws ReferenceServiceException, it also does
+ * this if any error occurs during retrieval of a (potentially nested)
+ * identifier.
+ * <p>
+ * This method will return a collection structure mirroring that of the
+ * specified T2Reference, client code should use T2Reference.getDepth() to
+ * determine the depth of this structure; a reference with depth of 0 means
+ * that the object returned is of the specified class, one of depth 1 is a
+ * list of this class and so on.
+ * <p>
+ * If the T2Reference contains or is an error this method will not retrieve
+ * it, and instead throws ReferenceServiceException
+ *
+ * @see StreamToValueConverterSPI
+ * @see ValueCarryingExternalReference
+ * @param id
+ * the T2Reference to render to a POJO
+ * @param leafClass
+ * the java class for leaves in the resulting POJO structure
+ * @param context
+ * a reference context, potentially used if required by the
+ * openStream methods of ExternalReferenceSPI implementations
+ * used as sources for the POJO construction <br/>
+ * If null the implementation should insert a new empty context
+ * and proceed.
+ * @return a java structure as defined above
+ * @throws ReferenceServiceException
+ * if anything fails during this process
+ */
+ Object renderIdentifier(T2Reference id, Class<?> leafClass,
+ ReferenceContext context) throws ReferenceServiceException;
+
+ /**
+ * The top level registration method is used to register either as yet
+ * unregistered ErrorDocuments and ReferenceSets (if these are passed in and
+ * already have an identifier this call does nothing) and arbitrarily nested
+ * Lists of the same. In addition any ExternalReferenceSPI instances found
+ * will be wrapped in a single item ReferenceSet and registered, and any
+ * Throwables will be wrapped in an ErrorDocument and registered. Lists will
+ * be converted to IdentifiedList<T2Reference> and registered if all
+ * children can be (or were already) appropriately named.
+ * <p>
+ * This method is only valid on parameters of the following type :
+ * <ol>
+ * <li>{@link T2Reference} - returned immediately as itself, this is needed
+ * because it means we can register lists of existing T2Reference</li>
+ * <li>{@link ReferenceSet} - registered if not already registered,
+ * otherwise returns existing T2Reference</li>
+ * <li>{@link ErrorDocument} - same behaviour as ReferenceSet</li>
+ * <li>{@link ExternalReferenceSPI} - wrapped in ReferenceSet, registered
+ * and ID returned</li>
+ * <li>Throwable - wrapped in {@link ErrorDocument} with no message,
+ * registered and ID returned</li>
+ * <li>List - all children are first registered, if this succeeds the list
+ * is itself registered as an {@link IdentifiedList} of {@link T2Reference}
+ * and its reference returned.</li>
+ * </ol>
+ * The exception to this is if the useConvertorSPI parameter is set to true
+ * - in this case any objects which do not match the above allowed list will
+ * be run through any available ValueToReferenceConvertorSPI instances in
+ * turn until one succeeds or all fail, which may result in the creation of
+ * ExternalReferenceSPI instances. As these can be registered such objects
+ * will not cause an exception to be thrown.
+ *
+ * @see ValueToReferenceConverterSPI
+ * @param o
+ * the object to register with the reference system, must comply
+ * with and will be interpreted as shown in the type list above.
+ * @param targetDepth
+ * the depth of the top level object supplied. This is needed
+ * when registering empty collections and error documents,
+ * whether as top level types or as members of a collection
+ * within the top level type. If registering a collection this is
+ * the collection depth, so a List of ReferenceSchemeSPI would be
+ * depth 1. Failing to specify this correctly will result in
+ * serious problems downstream so be careful! We can't catch all
+ * potential problems in this method (although some errors will
+ * be trapped).
+ * @param useConverterSPI
+ * whether to attempt to use the ValueToReferenceConvertorSPI
+ * registry (if defined and available) to map arbitrary objects
+ * to ExternalReferenceSPI instances on the fly. The registry of
+ * converters is generally injected into the implementation of
+ * this service.
+ * @param context
+ * ReferenceContext to use if required by component services,
+ * this is most likely to be used by the object to reference
+ * converters if engaged. <br/>
+ * If null the implementation should insert a new empty context
+ * and proceed.
+ * @return a T2Reference to the registered object
+ * @throws ReferenceServiceException
+ * if the object type (or, for collections, the recursive type
+ * of its contents) is not in the allowed list or if a problem
+ * occurs during registration. Also thrown if attempting to use
+ * the converter SPI without an attached registry.
+ */
+ @Transactional(propagation = REQUIRED, readOnly = false)
+ T2Reference register(Object o, int targetDepth, boolean useConverterSPI,
+ ReferenceContext context) throws ReferenceServiceException;
+
+ /**
+ * Given a string representation of a T2Reference create a new T2Reference
+ * with the correct depth etc.
+ *
+ * @param reference
+ * @return a new T2Reference parsed from the original
+ */
+ T2Reference referenceFromString(String reference);
+
+ @Transactional(propagation = SUPPORTS, readOnly = false)
+ boolean delete(T2Reference reference) throws ReferenceServiceException;
+
+ @Transactional(propagation = SUPPORTS, readOnly = false)
+ boolean delete(List<T2Reference> references)
+ throws ReferenceServiceException;
+
+ @Transactional(propagation = SUPPORTS, readOnly = false)
+ void deleteReferencesForWorkflowRun(String workflowRunId)
+ throws ReferenceServiceException;
+
+ /**
+ * Returns the {@link ErrorDocumentService} this ReferenceService uses, use
+ * this when you need functionality from that service explicitly.
+ */
+ ErrorDocumentService getErrorDocumentService();
+
+ /**
+ * Returns the {@link ReferenceSetService} this ReferenceService uses, use
+ * this when you need functionality from that service explicitly.
+ */
+ ReferenceSetService getReferenceSetService();
+
+ /**
+ * Returns the {@link ListService} this ReferenceService uses, use this when
+ * you need functionality from that service explicitly.
+ */
+ ListService getListService();
+
+ /**
+ * Initiates a traversal of the specified t2reference, traversing to
+ * whatever level of depth is required such that all identifiers returned
+ * within the iterator have the specified depth. The context (i.e. the index
+ * path from the originally specified reference to each reference within the
+ * iteration) is included through use of the ContextualizedT2Reference
+ * wrapper class
+ *
+ * @param source
+ * the T2Reference from which to traverse. In general this is the
+ * root of a collection structure.
+ * @param desiredDepth
+ * the desired depth of all returned T2References, must be less
+ * than or equal to that of the source reference.
+ * @throws ReferenceServiceException
+ * if unable to create the iterator for some reason. Note that
+ * implementations are free to lazily perform the iteration so
+ * this method may succeed but the iterator produced can fail
+ * when used. If the iterator fails it will do so by throwing
+ * one of the underlying sub-service exceptions.
+ */
+ @Transactional(propagation = SUPPORTS, readOnly = true)
+ Iterator<ContextualizedT2Reference> traverseFrom(T2Reference source,
+ int desiredDepth);
+}
http://git-wip-us.apache.org/repos/asf/incubator-taverna-engine/blob/5f1ddb71/taverna-reference-api/src/main/java/org/apache/taverna/reference/ReferenceServiceCacheProvider.java
----------------------------------------------------------------------
diff --git a/taverna-reference-api/src/main/java/org/apache/taverna/reference/ReferenceServiceCacheProvider.java b/taverna-reference-api/src/main/java/org/apache/taverna/reference/ReferenceServiceCacheProvider.java
new file mode 100644
index 0000000..8602420
--- /dev/null
+++ b/taverna-reference-api/src/main/java/org/apache/taverna/reference/ReferenceServiceCacheProvider.java
@@ -0,0 +1,51 @@
+/*
+* Licensed to the Apache Software Foundation (ASF) under one
+* or more contributor license agreements. See the NOTICE file
+* distributed with this work for additional information
+* regarding copyright ownership. The ASF licenses this file
+* to you 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.apache.taverna.reference;
+
+/**
+ * A simple interface to be implemented by data access object cache providers,
+ * intended to be used to inject cache implementations through AoP
+ *
+ * @author Tom Oinn
+ */
+public interface ReferenceServiceCacheProvider {
+ /**
+ * Called after an {@link Identified} has been written to the backing store,
+ * either for the first time or after modification. In our model
+ * {@link ReferenceSet} is the only {@link Identified} that is modifiable,
+ * specifically only by the addition of {@link ExternalReferenceSPI}
+ * instances to its reference set.
+ *
+ * @param i
+ * the Identified written to the backing store
+ */
+ void put(Identified i);
+
+ /**
+ * Called before an attempt is made to retrieve an item from the backing
+ * store
+ *
+ * @param id
+ * the T2Reference of the item to retrieve
+ * @return a cached item with matching {@link T2Reference}, or <tt>null</tt>
+ * if the cache does not contain that item
+ */
+ Identified get(T2Reference id);
+}
http://git-wip-us.apache.org/repos/asf/incubator-taverna-engine/blob/5f1ddb71/taverna-reference-api/src/main/java/org/apache/taverna/reference/ReferenceServiceException.java
----------------------------------------------------------------------
diff --git a/taverna-reference-api/src/main/java/org/apache/taverna/reference/ReferenceServiceException.java b/taverna-reference-api/src/main/java/org/apache/taverna/reference/ReferenceServiceException.java
new file mode 100644
index 0000000..d7eb91d
--- /dev/null
+++ b/taverna-reference-api/src/main/java/org/apache/taverna/reference/ReferenceServiceException.java
@@ -0,0 +1,46 @@
+/*
+* Licensed to the Apache Software Foundation (ASF) under one
+* or more contributor license agreements. See the NOTICE file
+* distributed with this work for additional information
+* regarding copyright ownership. The ASF licenses this file
+* to you 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.apache.taverna.reference;
+
+/**
+ * Thrown by methods in the ReferenceService, used to wrap any underlying
+ * exceptions from lower layers.
+ *
+ * @author Tom Oinn
+ */
+public class ReferenceServiceException extends RuntimeException {
+ private static final long serialVersionUID = -2607675495513408333L;
+
+ public ReferenceServiceException() {
+ //
+ }
+
+ public ReferenceServiceException(String message) {
+ super(message);
+ }
+
+ public ReferenceServiceException(Throwable cause) {
+ super(cause);
+ }
+
+ public ReferenceServiceException(String message, Throwable cause) {
+ super(message, cause);
+ }
+}
http://git-wip-us.apache.org/repos/asf/incubator-taverna-engine/blob/5f1ddb71/taverna-reference-api/src/main/java/org/apache/taverna/reference/ReferenceServiceResolutionCallback.java
----------------------------------------------------------------------
diff --git a/taverna-reference-api/src/main/java/org/apache/taverna/reference/ReferenceServiceResolutionCallback.java b/taverna-reference-api/src/main/java/org/apache/taverna/reference/ReferenceServiceResolutionCallback.java
new file mode 100644
index 0000000..7a6ffb5
--- /dev/null
+++ b/taverna-reference-api/src/main/java/org/apache/taverna/reference/ReferenceServiceResolutionCallback.java
@@ -0,0 +1,46 @@
+/*
+* Licensed to the Apache Software Foundation (ASF) under one
+* or more contributor license agreements. See the NOTICE file
+* distributed with this work for additional information
+* regarding copyright ownership. The ASF licenses this file
+* to you 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.apache.taverna.reference;
+
+/**
+ * Used by the asynchronous form of the resolveIdentifier method in
+ * {@link ReferenceService}
+ *
+ * @author Tom Oinn
+ */
+public interface ReferenceServiceResolutionCallback {
+ /**
+ * Called when the resolution process has completed
+ *
+ * @param result
+ * the Identified that corresponds to the {@link T2Reference}
+ * specified in the call to
+ * {@link ReferenceService#resolveIdentifierAsynch}
+ */
+ void identifierResolved(Identified result);
+
+ /**
+ * Called when the resolution process has failed
+ *
+ * @param cause
+ * a ReferenceServiceException describing the failure
+ */
+ void resolutionFailed(ReferenceServiceException cause);
+}
http://git-wip-us.apache.org/repos/asf/incubator-taverna-engine/blob/5f1ddb71/taverna-reference-api/src/main/java/org/apache/taverna/reference/ReferenceSet.java
----------------------------------------------------------------------
diff --git a/taverna-reference-api/src/main/java/org/apache/taverna/reference/ReferenceSet.java b/taverna-reference-api/src/main/java/org/apache/taverna/reference/ReferenceSet.java
new file mode 100644
index 0000000..d2be6c8
--- /dev/null
+++ b/taverna-reference-api/src/main/java/org/apache/taverna/reference/ReferenceSet.java
@@ -0,0 +1,52 @@
+/*
+* Licensed to the Apache Software Foundation (ASF) under one
+* or more contributor license agreements. See the NOTICE file
+* distributed with this work for additional information
+* regarding copyright ownership. The ASF licenses this file
+* to you 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.apache.taverna.reference;
+
+import java.util.Set;
+
+/**
+ * A set of ExternalReferenceSPI instances, all of which point to the same (byte
+ * equivalent) data. The set is identified by a T2Reference. This interface is
+ * read-only, as are most of the interfaces in this package. Rather than
+ * modifying properties of the reference set directly the client code should use
+ * the reference manager functionality.
+ * <p>
+ * It is technically okay, but rather unhelpful, to have a ReferenceSet with no
+ * ExternalReferenceSPI implementations. In general this is a sign that
+ * something has gone wrong somewhere as the reference set will not be
+ * resolvable in any way, but it would still retain its unique identifier so
+ * there may be occasions where this is the desired behaviour.
+ *
+ * @author Tom Oinn
+ */
+public interface ReferenceSet extends Identified {
+ /**
+ * The reference set contains a set of ExternalReferenceSPI instances, all
+ * of which point to byte equivalent data.
+ *
+ * @return the set of references to external data
+ */
+ Set<ExternalReferenceSPI> getExternalReferences();
+
+ /**
+ * Get approximate size of the data pointed to by this ReferenceSet.
+ */
+ Long getApproximateSizeInBytes();
+}
http://git-wip-us.apache.org/repos/asf/incubator-taverna-engine/blob/5f1ddb71/taverna-reference-api/src/main/java/org/apache/taverna/reference/ReferenceSetAugmentationException.java
----------------------------------------------------------------------
diff --git a/taverna-reference-api/src/main/java/org/apache/taverna/reference/ReferenceSetAugmentationException.java b/taverna-reference-api/src/main/java/org/apache/taverna/reference/ReferenceSetAugmentationException.java
new file mode 100644
index 0000000..ff41f4d
--- /dev/null
+++ b/taverna-reference-api/src/main/java/org/apache/taverna/reference/ReferenceSetAugmentationException.java
@@ -0,0 +1,46 @@
+/*
+* Licensed to the Apache Software Foundation (ASF) under one
+* or more contributor license agreements. See the NOTICE file
+* distributed with this work for additional information
+* regarding copyright ownership. The ASF licenses this file
+* to you 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.apache.taverna.reference;
+
+/**
+ * Thrown when the reference set augmentor is unable to provide at least one of
+ * the desired types for any reason.
+ *
+ * @author Tom Oinn
+ */
+public class ReferenceSetAugmentationException extends RuntimeException {
+ private static final long serialVersionUID = -6156508424485682266L;
+
+ public ReferenceSetAugmentationException() {
+ //
+ }
+
+ public ReferenceSetAugmentationException(String message) {
+ super(message);
+ }
+
+ public ReferenceSetAugmentationException(Throwable cause) {
+ super(cause);
+ }
+
+ public ReferenceSetAugmentationException(String message, Throwable cause) {
+ super(message, cause);
+ }
+}
http://git-wip-us.apache.org/repos/asf/incubator-taverna-engine/blob/5f1ddb71/taverna-reference-api/src/main/java/org/apache/taverna/reference/ReferenceSetAugmentor.java
----------------------------------------------------------------------
diff --git a/taverna-reference-api/src/main/java/org/apache/taverna/reference/ReferenceSetAugmentor.java b/taverna-reference-api/src/main/java/org/apache/taverna/reference/ReferenceSetAugmentor.java
new file mode 100644
index 0000000..fcde110
--- /dev/null
+++ b/taverna-reference-api/src/main/java/org/apache/taverna/reference/ReferenceSetAugmentor.java
@@ -0,0 +1,91 @@
+/*
+* Licensed to the Apache Software Foundation (ASF) under one
+* or more contributor license agreements. See the NOTICE file
+* distributed with this work for additional information
+* regarding copyright ownership. The ASF licenses this file
+* to you 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.apache.taverna.reference;
+
+import java.util.Set;
+
+/**
+ * Provides a framework to find and engage appropriate instances of
+ * {@link ExternalReferenceTranslatorSPI} and
+ * {@link ExternalReferenceBuilderSPI} to build external references from,
+ * respectively, other external references and from streams. These are then used
+ * to augment the contents of implementations of {@link ReferenceSet} with
+ * additional {@link ExternalReferenceSPI} implementations.
+ * <p>
+ * Methods in this interface throw the runtime exception
+ * {@link ReferenceSetAugmentationException} for all problems, other exceptions
+ * are wrapped in this type and re-thrown.
+ *
+ * @author Tom Oinn
+ */
+public interface ReferenceSetAugmentor {
+ /**
+ * Attempts to modify the supplied ReferenceSet such that it contains an
+ * implementation of at least one of the ExternalReferenceSPI classes
+ * specified. Uses the supplied context if required to build or translate
+ * existing references within the reference set.
+ *
+ * @param references
+ * reference set object to augment
+ * @param targetReferenceTypes
+ * a set of Class objects, this method succeeds if it can create
+ * an instance of at least one of these pointing to the same data
+ * as the other external references in the supplied reference set
+ * @param context
+ * a reference resolution context, potentially required for
+ * access to the existing references or for creation of the
+ * augmentations
+ * @return a set of new ExternalReferenceSPI instances such that the union
+ * of this set with the pre-existing reference set satisfies the
+ * target reference constraint. It is the responsibility of the
+ * caller to re-integrate these references into the original
+ * ReferenceSet if so desired.
+ * @throws ReferenceSetAugmentationException
+ * if a problem occurs either in configuration of the
+ * ReferenceSetAugmentor or in the augmentation process itself.
+ * Any other exception types are wrapped in this and re-thrown.
+ */
+ Set<ExternalReferenceSPI> augmentReferenceSet(ReferenceSet references,
+ Set<Class<ExternalReferenceSPI>> targetReferenceTypes,
+ ReferenceContext context) throws ReferenceSetAugmentationException;
+
+ /**
+ * As with {@link #augmentReferenceSet(ReferenceSet, Set, ReferenceContext)}
+ * but called in an asynchronous fashion. Returns immediately and uses the
+ * supplied instance of {@link ReferenceSetAugmentorCallback} to provide
+ * either the augmented {@link ReferenceSet} or an exception indicating a
+ * failure in the augmentation process.
+ *
+ * @param callback
+ * callback object used to indicate failure or to return the
+ * modified reference set
+ * @throws ReferenceSetAugmentationException
+ * if the ReferenceSetAugmentor is missing critical
+ * configuration. Exceptions that happen during augmentation or
+ * as a result of a failure to find an appropriate augmentation
+ * path are signalled by calls to the callback object, this
+ * method only throws the exception if it can't even try to do
+ * the augmentation for some reason.
+ */
+ void augmentReferenceSetAsynch(ReferenceSet references,
+ Set<Class<ExternalReferenceSPI>> targetReferenceTypes,
+ ReferenceContext context, ReferenceSetAugmentorCallback callback)
+ throws ReferenceSetAugmentationException;
+}
http://git-wip-us.apache.org/repos/asf/incubator-taverna-engine/blob/5f1ddb71/taverna-reference-api/src/main/java/org/apache/taverna/reference/ReferenceSetAugmentorCallback.java
----------------------------------------------------------------------
diff --git a/taverna-reference-api/src/main/java/org/apache/taverna/reference/ReferenceSetAugmentorCallback.java b/taverna-reference-api/src/main/java/org/apache/taverna/reference/ReferenceSetAugmentorCallback.java
new file mode 100644
index 0000000..3f53dd0
--- /dev/null
+++ b/taverna-reference-api/src/main/java/org/apache/taverna/reference/ReferenceSetAugmentorCallback.java
@@ -0,0 +1,52 @@
+/*
+* Licensed to the Apache Software Foundation (ASF) under one
+* or more contributor license agreements. See the NOTICE file
+* distributed with this work for additional information
+* regarding copyright ownership. The ASF licenses this file
+* to you 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.apache.taverna.reference;
+
+import java.util.Set;
+
+/**
+ * Callback interface used when augmenting a ReferenceSet in an asynchronous
+ * fashion through
+ * {@link ReferenceSetAugmentor#augmentReferenceSetAsynch(ReferenceSet, Set, ReferenceContext, ReferenceSetAugmentorCallback)
+ * augmentReferenceSetAsynch} in {@link ReferenceSetAugmentor}.
+ *
+ * @author Tom Oinn
+ */
+public interface ReferenceSetAugmentorCallback {
+ /**
+ * Called when the augmentation has succeeded
+ *
+ * @param newReferences
+ * a set of ExternalReferenceSPI instances created during the
+ * augmentation process. It is the responsibility of the caller
+ * to re-integrate these back into the ReferenceSet used in the
+ * translation
+ */
+ void augmentationCompleted(Set<ExternalReferenceSPI> newReferences);
+
+ /**
+ * Called when the augmentation has failed for some reason
+ *
+ * @param cause
+ * a {@link ReferenceSetAugmentationException} object describing
+ * the failure.
+ */
+ void augmentationFailed(ReferenceSetAugmentationException cause);
+}
http://git-wip-us.apache.org/repos/asf/incubator-taverna-engine/blob/5f1ddb71/taverna-reference-api/src/main/java/org/apache/taverna/reference/ReferenceSetDao.java
----------------------------------------------------------------------
diff --git a/taverna-reference-api/src/main/java/org/apache/taverna/reference/ReferenceSetDao.java b/taverna-reference-api/src/main/java/org/apache/taverna/reference/ReferenceSetDao.java
new file mode 100644
index 0000000..6b6332e
--- /dev/null
+++ b/taverna-reference-api/src/main/java/org/apache/taverna/reference/ReferenceSetDao.java
@@ -0,0 +1,81 @@
+/*
+* Licensed to the Apache Software Foundation (ASF) under one
+* or more contributor license agreements. See the NOTICE file
+* distributed with this work for additional information
+* regarding copyright ownership. The ASF licenses this file
+* to you 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.apache.taverna.reference;
+
+import static org.springframework.transaction.annotation.Propagation.REQUIRED;
+import static org.springframework.transaction.annotation.Propagation.SUPPORTS;
+
+import org.springframework.transaction.annotation.Transactional;
+
+/**
+ * Data Access Object interface for {@link ReferenceSet}. Used by the
+ * {@link ReferenceSetService} to store and retrieve implementations of
+ * reference set to and from the database. Client code should use the reference
+ * set service rather than using this Dao directly.
+ * <p>
+ * All methods throw DaoException, and nothing else. Where a deeper error is
+ * propagated it is wrapped in a DaoException and passed on to the caller.
+ *
+ * @author Tom Oinn
+ */
+public interface ReferenceSetDao {
+ /**
+ * Store the specified new reference set
+ *
+ * @param rs
+ * a reference set, must not already exist in the database.
+ * @throws DaoException
+ * if the entry already exists in the database or some other
+ * database related problem occurs
+ */
+ @Transactional(propagation = REQUIRED, readOnly = false)
+ void store(ReferenceSet rs) throws DaoException;
+
+ /**
+ * Update a pre-existing entry in the database
+ *
+ * @param rs
+ * the reference set to update. This must already exist in the
+ * database
+ * @throws DaoException
+ */
+ @Transactional(propagation = REQUIRED, readOnly = false)
+ void update(ReferenceSet rs) throws DaoException;
+
+ /**
+ * Fetch a reference set by id
+ *
+ * @param ref
+ * the T2Reference to fetch
+ * @return a retrieved ReferenceSet
+ * @throws DaoException
+ * if the supplied reference is of the wrong type or if
+ * something goes wrong fetching the data or connecting to the
+ * database
+ */
+ @Transactional(propagation = SUPPORTS, readOnly = true)
+ ReferenceSet get(T2Reference ref) throws DaoException;
+
+ @Transactional(propagation = SUPPORTS, readOnly = false)
+ boolean delete(ReferenceSet rs) throws DaoException;
+
+ @Transactional(propagation = SUPPORTS, readOnly = false)
+ void deleteReferenceSetsForWFRun(String workflowRunId) throws DaoException;
+}
http://git-wip-us.apache.org/repos/asf/incubator-taverna-engine/blob/5f1ddb71/taverna-reference-api/src/main/java/org/apache/taverna/reference/ReferenceSetService.java
----------------------------------------------------------------------
diff --git a/taverna-reference-api/src/main/java/org/apache/taverna/reference/ReferenceSetService.java b/taverna-reference-api/src/main/java/org/apache/taverna/reference/ReferenceSetService.java
new file mode 100644
index 0000000..5a9327f
--- /dev/null
+++ b/taverna-reference-api/src/main/java/org/apache/taverna/reference/ReferenceSetService.java
@@ -0,0 +1,180 @@
+/*
+* Licensed to the Apache Software Foundation (ASF) under one
+* or more contributor license agreements. See the NOTICE file
+* distributed with this work for additional information
+* regarding copyright ownership. The ASF licenses this file
+* to you 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.apache.taverna.reference;
+
+import static org.springframework.transaction.annotation.Propagation.REQUIRED;
+import static org.springframework.transaction.annotation.Propagation.SUPPORTS;
+
+import java.util.Set;
+
+import org.springframework.transaction.annotation.Transactional;
+
+/**
+ * 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. In general applications should be
+ * using this interface (where only ReferenceSet functionality is required) or
+ * the support classes which in turn use this and the collection and error
+ * handling interfaces to present a unified view over the various components of
+ * the reference management system.
+ *
+ * @author Tom Oinn
+ */
+@Transactional(propagation = SUPPORTS, readOnly = true)
+public interface ReferenceSetService {
+ /**
+ * Register a set of {@link ExternalReferenceSPI} instances, all of which
+ * should point to byte equivalent data, and return the newly created
+ * {@link ReferenceSet}. This method blocks on the underlying store, but
+ * guarantees that the returned value has been persisted.
+ * <p>
+ * The created references will be related with a workflow run id passed
+ * through ReferenceContext so we can track all data referenced by a
+ * specific run.
+ *
+ * @param references
+ * a set of {@link ExternalReferenceSPI} implementations to
+ * register as a {@link ReferenceSet}
+ * @return the registered {@link ReferenceSet}
+ */
+ @Transactional(propagation = REQUIRED, readOnly = false)
+ ReferenceSet registerReferenceSet(Set<ExternalReferenceSPI> references,
+ ReferenceContext context) throws ReferenceSetServiceException;
+
+ /**
+ * Get a previously registered {@link ReferenceSet} by {@link T2Reference}.
+ * Note that this method blocks and may take some time to return in the case
+ * of distributed reference managers; if this is likely to be an issue then
+ * you should use the asynchronous form
+ * {@link #getReferenceSetAsynch(T2Reference, ReferenceSetServiceCallback)
+ * getReferenceSetAsynch} instead of this method.
+ *
+ * @param id
+ * a {@link T2Reference} identifying a {@link ReferenceSet} to
+ * retrieve
+ * @return the requested {@link ReferenceSet}
+ */
+ ReferenceSet getReferenceSet(T2Reference id)
+ throws ReferenceSetServiceException;
+
+ /**
+ * Functionality the same as {@link #getReferenceSet(T2Reference)
+ * getReferenceSet} but in asynchronous mode, returning immediately and
+ * using the supplied callback to communicate its results.
+ *
+ * @param id
+ * a {@link T2Reference} identifying a {@link ReferenceSet} to
+ * retrieve
+ * @param callback
+ * a {@link ReferenceSetServiceCallback} used to convey the
+ * results of the asynchronous call
+ * @throws ReferenceSetServiceException
+ * if the reference set service is not correctly configured.
+ * Exceptions encountered when performing the asynchronous call
+ * are not returned here, for obvious reasons, and are instead
+ * messaged through the callback interface.
+ */
+ void getReferenceSetAsynch(T2Reference id,
+ ReferenceSetServiceCallback callback)
+ throws ReferenceSetServiceException;
+
+ /**
+ * Functionality the same as {@link #getReferenceSet(T2Reference)
+ * getReferenceSet} but with the additional option to specify a set of
+ * {@link ExternalReferenceSPI} classes. The reference set manager will
+ * attempt to ensure that the returned {@link ReferenceSet} contains an
+ * instance of at least one of the specified classes. This method blocks,
+ * and may potentially incur both the remote lookup overhead of the simpler
+ * version of this call and any translation logic. It is <em>strongly</em>
+ * recommended that you do not use this version of the call and instead use
+ * the asynchronous form
+ * {@link #getReferenceSetWithAugmentationAsynch(T2Reference, Set, ReferenceContext, ReferenceSetServiceCallback)
+ * getReferenceSetWithAugmentationAsynch} instead.
+ * <p>
+ * If the translation logic cannot provide at least one of the required
+ * types this call will fail, even if the {@link ReferenceSet} requested is
+ * otherwise available.
+ *
+ * @param id
+ * a {@link T2Reference} identifying a {@link ReferenceSet} to
+ * retrieve
+ * @param ensureTypes
+ * a set of {@link ExternalReferenceSPI} classes. The framework
+ * will attempt to ensure there is an instance of at least one of
+ * these classes in the returned {@link ReferenceSet}
+ * @param context
+ * if translation of references is required the translation
+ * infrastructure will need information in this
+ * {@link ReferenceContext} parameter.
+ * <p>
+ * If null the implementation should insert a new empty context
+ * and proceed.
+ * @return the requested {@link ReferenceSet}
+ */
+ @Transactional(propagation = REQUIRED, readOnly = false)
+ ReferenceSet getReferenceSetWithAugmentation(T2Reference id,
+ Set<Class<ExternalReferenceSPI>> ensureTypes,
+ ReferenceContext context) throws ReferenceSetServiceException;
+
+ /**
+ * Functionality as
+ * {@link #getReferenceSetWithAugmentation(T2Reference, Set, ReferenceContext)
+ * getReferenceSetWithAugmentation} but with the addition of a callback
+ * interface to report the result or failure of the method.
+ *
+ * @param id
+ * a {@link T2Reference} identifying a {@link ReferenceSet} to
+ * retrieve
+ * @param ensureTypes
+ * a set of {@link ExternalReferenceSPI} classes. The framework
+ * will attempt to ensure there is an instance of at least one of
+ * these classes in the returned {@link ReferenceSet}
+ * @param context
+ * if translation of references is required the translation
+ * infrastructure will need information in this
+ * {@link ReferenceContext} parameter.
+ * <p>
+ * If null the implementation should insert a new empty context
+ * and proceed.
+ * @param callback
+ * a {@link ReferenceSetServiceCallback} used to convey the
+ * results of the asynchronous call *
+ * @throws ReferenceSetServiceException
+ * if the reference set service is not correctly configured.
+ * Exceptions encountered when performing the asynchronous call
+ * are not returned here, for obvious reasons, and are instead
+ * messaged through the callback interface.
+ */
+ @Transactional(propagation = REQUIRED, readOnly = false)
+ void getReferenceSetWithAugmentationAsynch(T2Reference id,
+ Set<Class<ExternalReferenceSPI>> ensureTypes,
+ ReferenceContext context, ReferenceSetServiceCallback callback)
+ throws ReferenceSetServiceException;
+
+ @Transactional(propagation = SUPPORTS, readOnly = false)
+ boolean delete(T2Reference reference) throws ReferenceServiceException;
+
+ /**
+ * Delete all {@link ReferenceSet}S used by the specific workflow run.
+ */
+ @Transactional(propagation = SUPPORTS, readOnly = false)
+ void deleteReferenceSetsForWorkflowRun(String workflowRunId)
+ throws ReferenceServiceException;
+}
http://git-wip-us.apache.org/repos/asf/incubator-taverna-engine/blob/5f1ddb71/taverna-reference-api/src/main/java/org/apache/taverna/reference/ReferenceSetServiceCallback.java
----------------------------------------------------------------------
diff --git a/taverna-reference-api/src/main/java/org/apache/taverna/reference/ReferenceSetServiceCallback.java b/taverna-reference-api/src/main/java/org/apache/taverna/reference/ReferenceSetServiceCallback.java
new file mode 100644
index 0000000..670fec2
--- /dev/null
+++ b/taverna-reference-api/src/main/java/org/apache/taverna/reference/ReferenceSetServiceCallback.java
@@ -0,0 +1,46 @@
+/*
+* Licensed to the Apache Software Foundation (ASF) under one
+* or more contributor license agreements. See the NOTICE file
+* distributed with this work for additional information
+* regarding copyright ownership. The ASF licenses this file
+* to you 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.apache.taverna.reference;
+
+/**
+ * Callback interface used by asynchronous methods in the
+ * {@link ReferenceSetService} interface
+ *
+ * @author Tom Oinn
+ */
+public interface ReferenceSetServiceCallback {
+ /**
+ * Called when the requested {@link ReferenceSet} has been successfully
+ * retrieved.
+ *
+ * @param references
+ * the ReferenceSet requested
+ */
+ void referenceSetRetrieved(ReferenceSet references);
+
+ /**
+ * Called if the retrieval failed for some reason
+ *
+ * @param cause
+ * a ReferenceSetServiceException explaining the retrieval
+ * failure
+ */
+ void referenceSetRetrievalFailed(ReferenceSetServiceException cause);
+}
http://git-wip-us.apache.org/repos/asf/incubator-taverna-engine/blob/5f1ddb71/taverna-reference-api/src/main/java/org/apache/taverna/reference/ReferenceSetServiceException.java
----------------------------------------------------------------------
diff --git a/taverna-reference-api/src/main/java/org/apache/taverna/reference/ReferenceSetServiceException.java b/taverna-reference-api/src/main/java/org/apache/taverna/reference/ReferenceSetServiceException.java
new file mode 100644
index 0000000..9381d7e
--- /dev/null
+++ b/taverna-reference-api/src/main/java/org/apache/taverna/reference/ReferenceSetServiceException.java
@@ -0,0 +1,47 @@
+/*
+* Licensed to the Apache Software Foundation (ASF) under one
+* or more contributor license agreements. See the NOTICE file
+* distributed with this work for additional information
+* regarding copyright ownership. The ASF licenses this file
+* to you 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.apache.taverna.reference;
+
+/**
+ * RuntimeException subclass thrown by the reference set service layer
+ * interfaces. All underlying exceptions are either handled by the service layer
+ * or wrapped in this exception (or a subclass) and rethrown.
+ *
+ * @author Tom Oinn
+ */
+public class ReferenceSetServiceException extends RuntimeException {
+ private static final long serialVersionUID = -2762995062729638168L;
+
+ public ReferenceSetServiceException() {
+ //
+ }
+
+ public ReferenceSetServiceException(String message) {
+ super(message);
+ }
+
+ public ReferenceSetServiceException(Throwable cause) {
+ super(cause);
+ }
+
+ public ReferenceSetServiceException(String message, Throwable cause) {
+ super(message, cause);
+ }
+}
http://git-wip-us.apache.org/repos/asf/incubator-taverna-engine/blob/5f1ddb71/taverna-reference-api/src/main/java/org/apache/taverna/reference/ReferencedDataNature.java
----------------------------------------------------------------------
diff --git a/taverna-reference-api/src/main/java/org/apache/taverna/reference/ReferencedDataNature.java b/taverna-reference-api/src/main/java/org/apache/taverna/reference/ReferencedDataNature.java
new file mode 100644
index 0000000..b1b7f2c
--- /dev/null
+++ b/taverna-reference-api/src/main/java/org/apache/taverna/reference/ReferencedDataNature.java
@@ -0,0 +1,44 @@
+/*
+* Licensed to the Apache Software Foundation (ASF) under one
+* or more contributor license agreements. See the NOTICE file
+* distributed with this work for additional information
+* regarding copyright ownership. The ASF licenses this file
+* to you 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.apache.taverna.reference;
+
+/**
+ * Where possible ExternalReferenceSPI implementations should be able to
+ * determine whether the data they refer to is textual or binary in nature. This
+ * enumeration contains values for textual, binary and unknown data natures.
+ *
+ * @author Tom Oinn
+ */
+public enum ReferencedDataNature {
+ /**
+ * The data is binary, no character encoding will be specified.
+ */
+ BINARY,
+
+ /**
+ * The data is textual, character encoding may be defined.
+ */
+ TEXT,
+
+ /**
+ * Unknown data nature.
+ */
+ UNKNOWN;
+}
http://git-wip-us.apache.org/repos/asf/incubator-taverna-engine/blob/5f1ddb71/taverna-reference-api/src/main/java/org/apache/taverna/reference/StackTraceElementBean.java
----------------------------------------------------------------------
diff --git a/taverna-reference-api/src/main/java/org/apache/taverna/reference/StackTraceElementBean.java b/taverna-reference-api/src/main/java/org/apache/taverna/reference/StackTraceElementBean.java
new file mode 100644
index 0000000..70ce0d2
--- /dev/null
+++ b/taverna-reference-api/src/main/java/org/apache/taverna/reference/StackTraceElementBean.java
@@ -0,0 +1,53 @@
+/*
+* Licensed to the Apache Software Foundation (ASF) under one
+* or more contributor license agreements. See the NOTICE file
+* distributed with this work for additional information
+* regarding copyright ownership. The ASF licenses this file
+* to you 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.apache.taverna.reference;
+
+/**
+ * Used by the {@link ErrorDocument} interface to represent a frame within a
+ * stack trace
+ *
+ * @author Tom Oinn
+ * @see StackTraceElement
+ */
+public interface StackTraceElementBean {
+ /**
+ * Returns the fully qualified name of the class containing the execution
+ * point represented by this stack trace element.
+ */
+ String getClassName();
+
+ /**
+ * Returns the name of the source file containing the execution point
+ * represented by this stack trace element.
+ */
+ String getFileName();
+
+ /**
+ * Returns the line number of the source line containing the execution point
+ * represented by this stack trace element.
+ */
+ int getLineNumber();
+
+ /**
+ * Returns the name of the method containing the execution point represented
+ * by this stack trace element.
+ */
+ String getMethodName();
+}
http://git-wip-us.apache.org/repos/asf/incubator-taverna-engine/blob/5f1ddb71/taverna-reference-api/src/main/java/org/apache/taverna/reference/StreamToValueConverterSPI.java
----------------------------------------------------------------------
diff --git a/taverna-reference-api/src/main/java/org/apache/taverna/reference/StreamToValueConverterSPI.java b/taverna-reference-api/src/main/java/org/apache/taverna/reference/StreamToValueConverterSPI.java
new file mode 100644
index 0000000..e618523
--- /dev/null
+++ b/taverna-reference-api/src/main/java/org/apache/taverna/reference/StreamToValueConverterSPI.java
@@ -0,0 +1,47 @@
+/*
+* Licensed to the Apache Software Foundation (ASF) under one
+* or more contributor license agreements. See the NOTICE file
+* distributed with this work for additional information
+* regarding copyright ownership. The ASF licenses this file
+* to you 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.apache.taverna.reference;
+
+import java.io.InputStream;
+
+/**
+ * SPI for objects that can render a POJO from an InputStream
+ *
+ * @author Tom Oinn
+ */
+public interface StreamToValueConverterSPI<T> {
+ /**
+ * The class of objects which this builder can construct from a stream
+ */
+ Class<T> getPojoClass();
+
+ /**
+ * Render the stream to the target object type
+ *
+ * @param stream
+ * input stream of data to render to the object; the caller will
+ * close it
+ * @param charset
+ * @param dataNature
+ * @return the newly created object
+ */
+ T renderFrom(InputStream stream, ReferencedDataNature dataNature,
+ String charset);
+}
http://git-wip-us.apache.org/repos/asf/incubator-taverna-engine/blob/5f1ddb71/taverna-reference-api/src/main/java/org/apache/taverna/reference/T2Reference.java
----------------------------------------------------------------------
diff --git a/taverna-reference-api/src/main/java/org/apache/taverna/reference/T2Reference.java b/taverna-reference-api/src/main/java/org/apache/taverna/reference/T2Reference.java
new file mode 100644
index 0000000..96f7330
--- /dev/null
+++ b/taverna-reference-api/src/main/java/org/apache/taverna/reference/T2Reference.java
@@ -0,0 +1,101 @@
+/*
+* Licensed to the Apache Software Foundation (ASF) under one
+* or more contributor license agreements. See the NOTICE file
+* distributed with this work for additional information
+* regarding copyright ownership. The ASF licenses this file
+* to you 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.apache.taverna.reference;
+
+import java.net.URI;
+
+/**
+ * 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. The reference carries certain properties which can be evaluated
+ * without resolution, these include a depth property and whether the reference
+ * either is or contains an error document at any point in its structure.
+ *
+ * @author Tom Oinn
+ */
+public interface T2Reference {
+ /**
+ * To determine the entity that this reference points to we use an
+ * enumeration of possible entity types
+ *
+ * @return the type of entity to which this reference refers.
+ */
+ T2ReferenceType getReferenceType();
+
+ /**
+ * All entities identified by a T2Reference have a conceptual depth. In the
+ * case of lists the depth is the (uniform) depth of any item in the list
+ * plus one, in the case of reference sets the depth is 0. Error documents
+ * and empty lists may also have non zero depth; error documents in
+ * particular have a depth corresponding to the depth of the list or
+ * reference set that would have been created if there was no error.
+ *
+ * @return the depth of the entity identified by this T2Reference
+ */
+ int getDepth();
+
+ /**
+ * Error documents always return true, as do any lists where at least one
+ * immediate child of the list returns true when this property is evaluated.
+ * As lists are immutable this property is actually set on list
+ * registration. This is used to determine whether to allow POJO resolution
+ * of the entity identified by this T2Reference - this is configurable by
+ * the caller but there will be some cases where an attempt to render a
+ * collection containing errors to a POJO should return an error and other
+ * occasions when it should return a collection containing error objects.
+ * <p>
+ * ReferenceSet implementations always return false.
+ *
+ * @return whether the entity identified by this T2Reference either is or
+ * contains an error document. Containment is transitive, so a list
+ * containing a list that contained an error would return true.
+ */
+ boolean containsErrors();
+
+ /**
+ * T2Reference instances retain a reference to the reference manager which
+ * created them in the form of a namespace. This is an opaque string
+ * matching the regular expression [a-zA-Z_0-9]+, and is immutable once
+ * assigned (as are the other properties of this interface). The reference
+ * manager infrastructure uses this namespace property primarily to
+ * differentiate between cases where a reference cannot be resolved because
+ * of a lack of connection to the appropriate remote reference manager and
+ * those where the reference simply does not exist anywhere.
+ *
+ * @return the namespace of this T2Reference as a string.
+ */
+ String getNamespacePart();
+
+ /**
+ * In addition to the namespace the T2Reference contains a local identifier.
+ * This identifier is unique in the context of the namespace and is also
+ * represented as a string matching the regular expression [a-z_A-Z0-9]+
+ *
+ * @return the local part of this T2Reference as a string.
+ */
+ String getLocalPart();
+
+ /**
+ * All T2Reference instances can be represented as a URI.
+ *
+ * @return representation of this T2Reference as a URI
+ */
+ URI toUri();
+}
http://git-wip-us.apache.org/repos/asf/incubator-taverna-engine/blob/5f1ddb71/taverna-reference-api/src/main/java/org/apache/taverna/reference/T2ReferenceGenerator.java
----------------------------------------------------------------------
diff --git a/taverna-reference-api/src/main/java/org/apache/taverna/reference/T2ReferenceGenerator.java b/taverna-reference-api/src/main/java/org/apache/taverna/reference/T2ReferenceGenerator.java
new file mode 100644
index 0000000..1ba4376
--- /dev/null
+++ b/taverna-reference-api/src/main/java/org/apache/taverna/reference/T2ReferenceGenerator.java
@@ -0,0 +1,80 @@
+/*
+* Licensed to the Apache Software Foundation (ASF) under one
+* or more contributor license agreements. See the NOTICE file
+* distributed with this work for additional information
+* regarding copyright ownership. The ASF licenses this file
+* to you 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.apache.taverna.reference;
+
+/**
+ * Provides new unique T2Reference instances. Used by and injected into the
+ * various service interface implementations when registering new reference
+ * sets, error documents and lists.
+ *
+ * @author Tom Oinn
+ * @see T2Reference
+ */
+public interface T2ReferenceGenerator {
+ /**
+ * All T2Reference objects will have this namespace
+ *
+ * @return the namespace as a string
+ */
+ String getNamespace();
+
+ /**
+ * Create a new and otherwise unused T2Reference to a ReferenceSet. The
+ * namespace of the reference will depend on the current workflow run read
+ * from the ReferenceContext.
+ *
+ * @return new T2Reference for a ReferenceSet, namespace and local parts
+ * will be initialized and the reference is ready to use when
+ * returned.
+ */
+ T2Reference nextReferenceSetReference(ReferenceContext context);
+
+ /**
+ * Create a new and otherwise unused T2Reference to an IdentifiedList. The
+ * namespace of the reference will depend on the current workflow run read
+ * from the ReferenceContext.
+ *
+ * @param containsErrors
+ * whether the list this reference is generated for contains
+ * t2references with their containsErrors property set to true.
+ * Returns true if <em>any</em> reference in the list is or
+ * contains an error.
+ * @param listDepth
+ * depth of the list to which this identifier will be applied
+ * @return a new T2Reference for an IdentifiedList. Namespace, type and
+ * local parts will be initialized but depth and error content will
+ * still be at their default values of '0' and 'false' respectively,
+ * these will need to be re-set before the reference is viable.
+ */
+ T2Reference nextListReference(boolean containsErrors, int listDepth,
+ ReferenceContext context);
+
+ /**
+ * Create a new and otherwise unused T2Reference to an ErrorDocument. The
+ * namespace of the reference will depend on the current workflow run read
+ * from the ReferenceContext.
+ *
+ * @param depth
+ * the depth of the error document to which this identifier will
+ * refer
+ * @return a new T2Reference for an ErrorDocument
+ */
+ T2Reference nextErrorDocumentReference(int depth, ReferenceContext context);
+}
http://git-wip-us.apache.org/repos/asf/incubator-taverna-engine/blob/5f1ddb71/taverna-reference-api/src/main/java/org/apache/taverna/reference/T2ReferenceType.java
----------------------------------------------------------------------
diff --git a/taverna-reference-api/src/main/java/org/apache/taverna/reference/T2ReferenceType.java b/taverna-reference-api/src/main/java/org/apache/taverna/reference/T2ReferenceType.java
new file mode 100644
index 0000000..fc2743a
--- /dev/null
+++ b/taverna-reference-api/src/main/java/org/apache/taverna/reference/T2ReferenceType.java
@@ -0,0 +1,46 @@
+/*
+* Licensed to the Apache Software Foundation (ASF) under one
+* or more contributor license agreements. See the NOTICE file
+* distributed with this work for additional information
+* regarding copyright ownership. The ASF licenses this file
+* to you 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.apache.taverna.reference;
+
+/**
+ * The T2Reference interface is used to identify several different kinds of
+ * information, namely ReferenceSet, IdentifiedList and ErrorDocument. Because
+ * the top level reference service needs to determine which sub-service to
+ * delegate to when resolving references we carry this information in each
+ * T2Reference in the form of one of these enumerated types.
+ *
+ * @author Tom Oinn
+ */
+public enum T2ReferenceType {
+ /**
+ * A reference to a ReferenceSet
+ */
+ ReferenceSet,
+
+ /**
+ * A reference to an IdentifiedList of other T2References
+ */
+ IdentifiedList,
+
+ /**
+ * A reference to an ErrorDocument
+ */
+ ErrorDocument;
+}
http://git-wip-us.apache.org/repos/asf/incubator-taverna-engine/blob/5f1ddb71/taverna-reference-api/src/main/java/org/apache/taverna/reference/ValueCarryingExternalReference.java
----------------------------------------------------------------------
diff --git a/taverna-reference-api/src/main/java/org/apache/taverna/reference/ValueCarryingExternalReference.java b/taverna-reference-api/src/main/java/org/apache/taverna/reference/ValueCarryingExternalReference.java
new file mode 100644
index 0000000..3fd54d5
--- /dev/null
+++ b/taverna-reference-api/src/main/java/org/apache/taverna/reference/ValueCarryingExternalReference.java
@@ -0,0 +1,43 @@
+/*
+* Licensed to the Apache Software Foundation (ASF) under one
+* or more contributor license agreements. See the NOTICE file
+* distributed with this work for additional information
+* regarding copyright ownership. The ASF licenses this file
+* to you 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.apache.taverna.reference;
+
+/**
+ * Specialization of ExternalReferenceSPI for reference types which carry a
+ * value type internally. Such references can be de-referenced to the specified
+ * object type very cheaply. Note that this is not to be used to get an object
+ * property of a reference, the returned object must correspond to the value of
+ * the referenced data - this means that the HttpUrlReference does not use this
+ * to return a java.net.URL, but that the InlineStringReference does use it to
+ * return a java.lang.String
+ *
+ * @author Tom Oinn
+ */
+public interface ValueCarryingExternalReference<T> extends ExternalReferenceSPI {
+ /**
+ * Returns the type of the inlined value
+ */
+ Class<T> getValueType();
+
+ /**
+ * Returns the value
+ */
+ T getValue();
+}
http://git-wip-us.apache.org/repos/asf/incubator-taverna-engine/blob/5f1ddb71/taverna-reference-api/src/main/java/org/apache/taverna/reference/ValueToReferenceConversionException.java
----------------------------------------------------------------------
diff --git a/taverna-reference-api/src/main/java/org/apache/taverna/reference/ValueToReferenceConversionException.java b/taverna-reference-api/src/main/java/org/apache/taverna/reference/ValueToReferenceConversionException.java
new file mode 100644
index 0000000..7e2ba25
--- /dev/null
+++ b/taverna-reference-api/src/main/java/org/apache/taverna/reference/ValueToReferenceConversionException.java
@@ -0,0 +1,47 @@
+/*
+* Licensed to the Apache Software Foundation (ASF) under one
+* or more contributor license agreements. See the NOTICE file
+* distributed with this work for additional information
+* regarding copyright ownership. The ASF licenses this file
+* to you 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.apache.taverna.reference;
+
+/**
+ * Thrown by instances of ValueToReferenceConvertor when trying to convert an
+ * object to an instance of ExternalReferenceSPI if the conversion process fails
+ * for some reason.
+ *
+ * @author Tom Oinn
+ */
+public class ValueToReferenceConversionException extends RuntimeException {
+ private static final long serialVersionUID = 3259959719223191820L;
+
+ public ValueToReferenceConversionException() {
+ //
+ }
+
+ public ValueToReferenceConversionException(String message) {
+ super(message);
+ }
+
+ public ValueToReferenceConversionException(Throwable cause) {
+ super(cause);
+ }
+
+ public ValueToReferenceConversionException(String message, Throwable cause) {
+ super(message, cause);
+ }
+}