public interface ReferenceService
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.
Resolution of collections can happen at three different levels:
ListService
resolves the collection ID to a list of
child IDs, and doesn't traverse these children if they are themselves lists.
Use the getListService()
.getList()
to call this method directly on the list service if you need this
functionality, returning a list of T2Reference
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.
renderIdentifier
to a nested structure as in
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 resolveIdentifier
, fail if the reference contains or is an error.Modifier and Type | Method and Description |
---|---|
boolean |
delete(List<T2Reference> references) |
boolean |
delete(T2Reference reference) |
void |
deleteReferencesForWorkflowRun(String workflowRunId) |
ErrorDocumentService |
getErrorDocumentService()
Returns the
ErrorDocumentService this ReferenceService uses, use
this when you need functionality from that service explicitly. |
ListService |
getListService()
Returns the
ListService this ReferenceService uses, use this when
you need functionality from that service explicitly. |
ReferenceSetService |
getReferenceSetService()
Returns the
ReferenceSetService this ReferenceService uses, use
this when you need functionality from that service explicitly. |
T2Reference |
referenceFromString(String reference)
Given a string representation of a T2Reference create a new T2Reference
with the correct depth etc.
|
T2Reference |
register(Object o,
int targetDepth,
boolean useConverterSPI,
ReferenceContext context)
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.
|
Object |
renderIdentifier(T2Reference id,
Class<?> leafClass,
ReferenceContext context)
Resolve the given identifier, building a POJO structure where the
non-list items are of the desired class.
|
Identified |
resolveIdentifier(T2Reference id,
Set<Class<ExternalReferenceSPI>> ensureTypes,
ReferenceContext context)
Perform recursive identifier resolution, building a collection structure
of Identified objects, any collection elements being IdentifiedLists of
Identified subclasses.
|
void |
resolveIdentifierAsynch(T2Reference id,
Set<Class<ExternalReferenceSPI>> ensureTypes,
ReferenceContext context,
ReferenceServiceResolutionCallback callback)
As resolveIdentifier but using a callback object and returning
immediately
|
Iterator<ContextualizedT2Reference> |
traverseFrom(T2Reference source,
int desiredDepth)
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.
|
@Transactional(propagation=REQUIRED, readOnly=false) Identified resolveIdentifier(T2Reference id, Set<Class<ExternalReferenceSPI>> ensureTypes, ReferenceContext context) throws ReferenceServiceException
id
- the T2Reference to resolveensureTypes
- 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.context
- the ReferenceContext to use to resolve this and any
recursively resolved identifiers ReferenceServiceException
- if any problems occur during resolution@Transactional(propagation=REQUIRED, readOnly=false) void resolveIdentifierAsynch(T2Reference id, Set<Class<ExternalReferenceSPI>> ensureTypes, ReferenceContext context, ReferenceServiceResolutionCallback callback) throws ReferenceServiceException
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.Object renderIdentifier(T2Reference id, Class<?> leafClass, ReferenceContext context) throws ReferenceServiceException
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.
If the T2Reference contains or is an error this method will not retrieve it, and instead throws ReferenceServiceException
id
- the T2Reference to render to a POJOleafClass
- the java class for leaves in the resulting POJO structurecontext
- a reference context, potentially used if required by the
openStream methods of ExternalReferenceSPI implementations
used as sources for the POJO construction ReferenceServiceException
- if anything fails during this processStreamToValueConverterSPI
,
ValueCarryingExternalReference
@Transactional(propagation=REQUIRED, readOnly=false) T2Reference register(Object o, int targetDepth, boolean useConverterSPI, ReferenceContext context) throws ReferenceServiceException
This method is only valid on parameters of the following type :
T2Reference
- returned immediately as itself, this is needed
because it means we can register lists of existing T2ReferenceReferenceSet
- registered if not already registered,
otherwise returns existing T2ReferenceErrorDocument
- same behaviour as ReferenceSetExternalReferenceSPI
- wrapped in ReferenceSet, registered
and ID returnedErrorDocument
with no message,
registered and ID returnedIdentifiedList
of T2Reference
and its reference returned.o
- the object to register with the reference system, must comply
with and will be interpreted as shown in the type list above.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).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.context
- ReferenceContext to use if required by component services,
this is most likely to be used by the object to reference
converters if engaged. 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.ValueToReferenceConverterSPI
T2Reference referenceFromString(String reference)
reference
- @Transactional(propagation=SUPPORTS, readOnly=false) boolean delete(T2Reference reference) throws ReferenceServiceException
ReferenceServiceException
@Transactional(propagation=SUPPORTS, readOnly=false) boolean delete(List<T2Reference> references) throws ReferenceServiceException
ReferenceServiceException
@Transactional(propagation=SUPPORTS, readOnly=false) void deleteReferencesForWorkflowRun(String workflowRunId) throws ReferenceServiceException
ReferenceServiceException
ErrorDocumentService getErrorDocumentService()
ErrorDocumentService
this ReferenceService uses, use
this when you need functionality from that service explicitly.ReferenceSetService getReferenceSetService()
ReferenceSetService
this ReferenceService uses, use
this when you need functionality from that service explicitly.ListService getListService()
ListService
this ReferenceService uses, use this when
you need functionality from that service explicitly.@Transactional(propagation=SUPPORTS, readOnly=true) Iterator<ContextualizedT2Reference> traverseFrom(T2Reference source, int desiredDepth)
source
- the T2Reference from which to traverse. In general this is the
root of a collection structure.desiredDepth
- the desired depth of all returned T2References, must be less
than or equal to that of the source reference.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.Copyright © 2015–2016 The Apache Software Foundation. All rights reserved.