| /******************************************************************************* |
| * Copyright (C) 2007 The University of Manchester |
| * |
| * Modifications to the initial code base are copyright of their |
| * respective authors, or their employers as appropriate. |
| * |
| * This program is free software; you can redistribute it and/or |
| * modify it under the terms of the GNU Lesser General Public License |
| * as published by the Free Software Foundation; either version 2.1 of |
| * the License, or (at your option) any later version. |
| * |
| * This program is distributed in the hope that it will be useful, but |
| * WITHOUT ANY WARRANTY; without even the implied warranty of |
| * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
| * Lesser General Public License for more details. |
| * |
| * You should have received a copy of the GNU Lesser General Public |
| * License along with this program; if not, write to the Free Software |
| * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 |
| ******************************************************************************/ |
| package net.sf.taverna.t2.reference; |
| |
| import java.io.InputStream; |
| |
| /** |
| * A reference to a single piece of data. This may or may not be within the |
| * enactment infrastructure, it could refer to data held in a file, a URL, a |
| * grid storage system or anything of that nature. Ideally the data this |
| * reference points to should not change - we'd like to say 'must not change' at |
| * this point but this isn't always possible, implementations should aim to |
| * provide the appearance that data are immutable. |
| * <p> |
| * When used within the workflow engine implementations of this interface are |
| * always contained in a ReferenceSet instance. |
| * <p> |
| * Implementors of this interface are strongly advised to use the |
| * AbstractExternalReference superclass - this provides the necessary primary |
| * key information used by hibernate-based implementations of the reference |
| * manager. Technically we don't require it as it's possible that other backend |
| * stores may exist, but the core store used by T2 is based on hibernate so it's |
| * a very good idea to follow this! Basically if you don't your code won't work |
| * in the current system. |
| * <p> |
| * This interface is an SPI - while implementations are never constructed based |
| * on the SPI registry it is used to discover all implementing classes and |
| * automatically register their hibernate mapping files. Implementors should add |
| * their implementation class name to a |
| * META-INF/services/net.sf.taverna.t2.reference.ExternalReferenceSPI file in |
| * the implementation artifact. For examples please refer to the |
| * t2reference-core-extensions module, this contains implementations of this |
| * interface for common basic reference types. |
| * <p> |
| * Note - if your implementation class has a complex hibernate mapping that uses |
| * components which are themselves mapped into the database (perfectly legal to |
| * do) then you must mark those components as instances of HibernateMappedEntity |
| * so their corresponding mapping and class definitions are loaded by the |
| * Hibernate backed reference set dao. If your implementation class uses inline |
| * compound keys or other component types where you reference another class but |
| * the other class is not mapped itself in hibernate you must instead make the |
| * component class an instance of HibernateComponentClass - a marker interface - |
| * for the same reason. Both of these are SPIs themselves, and require the |
| * appropriate entries to be added to their service metadata files in your |
| * extension jar. |
| * |
| * @author Tom Oinn |
| */ |
| public interface ExternalReferenceSPI { |
| |
| /** |
| * Determine, if possible, whether the data this reference refers to is |
| * textual or binary in nature. If this determination is impossible, either |
| * because the ExternalReference implementation does not know or because the |
| * data is not accessible for some reason then this should return |
| * ReferenceDataNature.UNKNOWN |
| * |
| * @return the nature of the referenced data |
| */ |
| public ReferencedDataNature getDataNature(); |
| |
| /** |
| * For textual data return the character set that should be used to pull |
| * data into a java String object. Callers must deal with a null return |
| * value in the event of either unknown charset or unknown or binary data |
| * types. |
| * |
| * @return string character set, for example 'utf-8', or <code>null</code> |
| * if binary or unknown type. |
| */ |
| public String getCharset(); |
| |
| /** |
| * Open and return an InputStream to the data referenced using, if required, |
| * any facilities within the supplied context. |
| * |
| * @param context |
| * the ReferenceContext object used to obtain e.g. security |
| * agents or other facilities required when de-referencing this |
| * reference. |
| * @return an InputStream providing access to the referenced data |
| * @throws DereferenceException |
| * if the reference cannot be de-referenced. This may be because |
| * of problems with the context such as security failures, or it |
| * may be because the reference is inherently not possible to |
| * de-reference (as in the case of a non-serializable API |
| * consumer reference). |
| */ |
| public InputStream openStream(ReferenceContext context) |
| throws DereferenceException; |
| |
| /** |
| * Resolution cost is an informal guide to how costly the process of |
| * de-referencing this reference would be. It's used when assessing which |
| * out of a set of ExternalReferenceSPI implementations to use to get the |
| * value of the reference(s), in particular when rendering to POJOs or when |
| * translating throught the de-reference / construct from stream route. As |
| * this property is highly complex and potentially expensive in itself to |
| * evaluate there's no requirement for it to be absolutely correct, it's |
| * just used as a guide that, for example, it is easier to get bytes from a |
| * file on the local disk than to get them from a resource held on a grid on |
| * the other side of the planet. |
| * |
| * @return a float representing some notion of resolution cost, lower values |
| * represent cheaper de-reference paths. |
| */ |
| public float getResolutionCost(); |
| |
| } |