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.
When used within the workflow engine implementations of this interface are
always contained in a ReferenceSet instance.
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.
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.
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