X-Git-Url: https://gerrit.simantics.org/r/gitweb?a=blobdiff_plain;ds=inline;f=bundles%2Forg.simantics.db%2Fsrc%2Forg%2Fsimantics%2Fdb%2FReadGraph.java;h=bead66644ff103a67c6a3ad4db713457f068c2fd;hb=bcf895e26d56bb9861d8f4a2c41c813e6d9842b7;hp=46c504f3fa8f205605aeb7e4d48125d9bca21342;hpb=969bd23cab98a79ca9101af33334000879fb60c5;p=simantics%2Fplatform.git
diff --git a/bundles/org.simantics.db/src/org/simantics/db/ReadGraph.java b/bundles/org.simantics.db/src/org/simantics/db/ReadGraph.java
index 46c504f3f..bead66644 100644
--- a/bundles/org.simantics.db/src/org/simantics/db/ReadGraph.java
+++ b/bundles/org.simantics.db/src/org/simantics/db/ReadGraph.java
@@ -1,1074 +1,1074 @@
-/*******************************************************************************
- * Copyright (c) 2007, 2010 Association for Decentralized Information Management
- * in Industry THTH ry.
- * All rights reserved. This program and the accompanying materials
- * are made available under the terms of the Eclipse Public License v1.0
- * which accompanies this distribution, and is available at
- * http://www.eclipse.org/legal/epl-v10.html
- *
- * Contributors:
- * VTT Technical Research Centre of Finland - initial API and implementation
- *******************************************************************************/
-package org.simantics.db;
-
-import java.util.Collection;
-import java.util.Set;
-
-import org.simantics.databoard.accessor.Accessor;
-import org.simantics.databoard.binding.Binding;
-import org.simantics.databoard.binding.mutable.Variant;
-import org.simantics.databoard.type.Datatype;
-import org.simantics.databoard.util.binary.RandomAccessBinary;
-import org.simantics.db.adaption.Adapter;
-import org.simantics.db.exception.AdaptionException;
-import org.simantics.db.exception.AssumptionException;
-import org.simantics.db.exception.BindingException;
-import org.simantics.db.exception.DatabaseException;
-import org.simantics.db.exception.DoesNotContainValueException;
-import org.simantics.db.exception.ManyObjectsForFunctionalRelationException;
-import org.simantics.db.exception.NoInverseException;
-import org.simantics.db.exception.NoSingleResultException;
-import org.simantics.db.exception.ResourceNotFoundException;
-import org.simantics.db.exception.ServiceException;
-import org.simantics.db.exception.ValidationException;
-import org.simantics.db.procedure.SyncListener;
-import org.simantics.db.procedure.SyncMultiListener;
-import org.simantics.db.procedure.SyncMultiProcedure;
-import org.simantics.db.procedure.SyncProcedure;
-import org.simantics.db.procedure.SyncSetListener;
-import org.simantics.db.request.MultiRead;
-import org.simantics.db.request.Read;
-import org.simantics.scl.compiler.types.Type;
-
-/**
- *
- * For accessing and manipulating the graph data in synchronous manner. A client
- * receives ReadGraph instances for performing requests in {@link Read} and
- * {@link MultiRead} as well as for reacting to request results using
- * {@link SyncProcedure}, {@link SyncListener}, {@link SyncMultiProcedure},
- * {@link SyncMultiListener} and {@link SyncSetListener}
- *
- * ReadGraph instances are stateful and may not be stored and used outside the
- * supplier method activation. The methods receiving ReadGraph should not block
- * for long periods of time since that may delay the processing of other
- * requests. For an asynchronous counterpart with the same functionality as
- * ReadGraph see {@link AsyncReadGraph}
- *
- *
- * All collections returned by the methods on this interface must not be
- * modified by clients unless explicitly stated otherwise.
- *
- * @version 0.7
- * @author Antti Villberg
- * @see RequestProcessor
- * @see AsyncRequestProcessor
- * @see AsyncReadGraph
- * @see Resource
- * @see Statement
- * @noimplement
- */
-public interface ReadGraph extends AsyncReadGraph, RequestProcessor {
-
- /**
- *
- * @see AsyncReadGraph#forURI
- */
- String getURI(Resource resource) throws AssumptionException, ValidationException, ServiceException;
- String getPossibleURI(Resource resource) throws ValidationException, ServiceException;
-
- /**
- * Gets a unique resource associated to the given identifier. See Simantics Wiki page
- * on URIs for more details.
- *
- * @param uri the identifier
- * @return the resource
- * @throws ResourceNotFoundException if a resource for the given identifier
- * was not specified
- * @throws ValidationException if a resource could not be produced due to
- * invalid semantics
- * @throws ServiceException on connection and database failures
- * @see AsyncReadGraph#forResourceByURI
- */
- Resource getResource(String uri) throws ResourceNotFoundException, ValidationException, ServiceException;
-
- /**
- * Gets a unique resource associated to the given identifier. See Simantics Wiki page
- * on URIs for more details.
- *
- * @param uri the identifier
- * @return the resource
- * @throws ResourceNotFoundException if a resource for the given identifier
- * was not specified
- * @throws ValidationException if a resource could not be produced due to
- * invalid semantics
- * @throws ServiceException on connection and database failures
- * @see AsyncReadGraph#forResourceByURI
- */
- Resource getPossibleResource(String uri) throws ResourceNotFoundException, ValidationException, ServiceException;
-
- /**
- * Gets a builtin resource. For a list of builtin resources see TODO Wiki
- *
- * @param uri the identifier
- * @return the resource
- * @throws ResourceNotFoundException if resouce was not found
- * @throws ServiceException on connection and database failures
- * @see AsyncReadGraph#forBuiltin
- */
- Resource getBuiltin(String id) throws ResourceNotFoundException, ServiceException;
-
- /**
- * Gets all statements (subject, p, o) such that
- * {@link ReadGraph#isSubrelationOf(p, relation)} returns true. The result
- * may include asserted statements for which s does not equal subject. See
- * the assertion mechanisn TODO for more details. If the relation is
- * functional the request returns a single statement according to the
- * functional statement shadowing rules TODO if possible. If an invalid
- * graph is encountered an exception is thrown.
- *
- * @param subject a resource
- * @param relation a resource
- * @return the statements
- * @throws ManyObjectsForFunctionalRelationException on invalid graph with
- * more than one functional object
- * @throws ServiceException on connection and database failures
- * @see AsyncReadGraph#forEachStatement
- * @see AsyncReadGraph#forStatementSet
- */
- Collection getStatements(Resource subject, Resource relation)
- throws ManyObjectsForFunctionalRelationException, ServiceException;
-
- /**
- * Gets all statements (s, p, o) asserted by subject such that
- * {@link ReadGraph#isSubrelationOf(p, relation)} returns true. See the
- * assertion mechanism TODO for more details. If the relation is functional
- * the request returns a single statement according to the functional
- * statement shadowing rules TODO if possible. If an invalid graph is
- * encountered an exception is thrown.
- *
- * @param subject a resource
- * @param relation a resource
- * @return the statements
- * @throws ManyObjectsForFunctionalRelationException on invalid graph with
- * more than one functional object
- * @throws ServiceException on connection and database failures
- * @see AsyncReadGraph#forEachAssertedStatement
- * @see AsyncReadGraph#forAssertedStatementSet
- */
- Collection getAssertedStatements(Resource subject, Resource relation)
- throws ManyObjectsForFunctionalRelationException, ServiceException;
-
- /**
- * Gets all predicates p from statements (subject, p, o) such that
- * {@link ReadGraph#isSubrelationOf(p, relation)} returns true. See the
- * assertion mechanism TODO for more details. If the relation is functional
- * the request returns a single statement according to the functional
- * statement shadowing rules TODO if possible. If an invalid graph is
- * encountered an exception is thrown.
- *
- * @param subject a resource
- * @param relation a resource
- * @return the predicates
- * @throws ManyObjectsForFunctionalRelationException on invalid graph with
- * more than one object
- * @throws ServiceException on connection and database failures
- * @see AsyncReadGraph#forEachPredicate
- * @see AsyncReadGraph#forPredicateSet
- */
- Collection getPredicates(Resource subject) throws ServiceException;
-
- /**
- * Gets a subset of all types of the subject such that no pair of returned
- * types inherit each other and all types of the subject are supertypes
- * of some type in the returned set.
- *
- * @param subject a resource
- * @return the principal types
- * @throws ServiceException on connection and database failures
- * @see AsyncReadGraph#forEachPrincipalType
- * @see AsyncReadGraph#forPrincipalTypeSet
- */
- Collection getPrincipalTypes(Resource subject) throws ServiceException;
-
- /**
- * Gets the full type hierarchy for subject.
- *
- * @param subject a resource
- * @return the type hierarchy
- * @throws ServiceException on connection and database failures
- * @see AsyncReadGraph#forTypes
- */
- Set getTypes(Resource subject) throws ServiceException;
-
- /**
- * Gets the full supertype hierarchy for subject.
- *
- * @param subject a resource
- * @return the supertype hierarchy
- * @throws ServiceException on connection and database failures
- * @see AsyncReadGraph#forSupertypes
- */
- Set getSupertypes(Resource subject) throws ServiceException;
-
- /**
- * Gets the full superrelation hierarchy for subject.
- *
- * @param subject a resource
- * @return the superrelation hierarchy
- * @throws ServiceException on connection and database failures
- * @see AsyncReadGraph#forSuperrelations
- */
- Set getSuperrelations(Resource subject) throws ServiceException;
- Resource getPossibleSuperrelation(Resource subject) throws ServiceException;
-
- /**
- * Gets all objects o from statements (subject, p, o) such that
- * {@link ReadGraph#isSubrelationOf(p, relation)} returns true. See the
- * assertion mechanisn TODO for more details. If the relation is functional
- * the request returns a single object according to the functional statement
- * shadowing rules TODO if possible. If an invalid graph is encountered an
- * exception is thrown.
- *
- * @param subject a resource
- * @param relation a resource
- * @return the objects
- * @throws ManyObjectsForFunctionalRelationException on invalid graph with
- * more than one functional object
- * @throws ServiceException on connection and database failures
- * @see AsyncReadGraph#forEachObject
- * @see AsyncReadGraph#forObjectSet
- */
- Collection getObjects(Resource subject, Resource relation)
- throws ServiceException;
-
- /**
- * Gets all objects o (s, p, o) asserted by subject such that
- * {@link ReadGraph#isSubrelationOf(p, relation)} returns true. See the
- * assertion mechanism TODO for more details. If the relation is functional
- * the request returns a single object according to the functional statement
- * shadowing rules TODO if possible. If an invalid graph is encountered an
- * exception is thrown.
- *
- * @param subject a resource
- * @param relation a resource
- * @return the objects
- * @throws ManyObjectsForFunctionalRelationException on invalid graph with
- * more than one functional object
- * @throws ServiceException on connection and database failures
- * @see AsyncReadGraph#forEachAssertedStatement
- * @see AsyncReadGraph#forAssertedStatementSet
- */
- Collection getAssertedObjects(Resource subject, Resource relation)
- throws ManyObjectsForFunctionalRelationException, ServiceException;
-
- /**
- * Gets the inverse r of relation such that (relation, InverseOf, r). The
- * methods assumes an inverse exists.
- *
- * @param relation a resource
- * @return the inverse
- * @throws NoInverseException if inverse was not fond
- * @throws ManyObjectsForFunctionalRelationException on invalid graph with
- * more than one functional object
- * @throws ServiceException on connection and database failures
- * @see AsyncReadGraph#forInverse
- */
- Resource getInverse(Resource relation) throws NoInverseException, ManyObjectsForFunctionalRelationException,
- ServiceException;
-
- /**
- * Gets a single object as returned by {@link ReadGraph#getObjects}. Assumes
- * a single object.
- *
- * @param subject a resource
- * @param relation a resource
- * @return the single object
- * @throws NoSingleResultException if the amount of valid objects was not
- * one
- * @throws ManyObjectsForFunctionalRelationException on invalid graph with
- * more than one functional object
- * @throws ServiceException on connection and database failures
- * @see AsyncReadGraph#forSingleObject
- */
- Resource getSingleObject(Resource subject, Resource relation) throws NoSingleResultException,
- ManyObjectsForFunctionalRelationException, ServiceException;
-
- /**
- * Gets a single statement as returned by {@link ReadGraph#getStatements}.
- * Assumes a single statement.
- *
- * @param subject a resource
- * @param relation a resource
- * @return the single statement
- * @throws NoSingleResultException if the amount of valid statements was not
- * one
- * @throws ManyObjectsForFunctionalRelationException on invalid graph with
- * more than one functional object
- * @throws ServiceException on connection and database failures
- * @see AsyncReadGraph#forSingleStatement
- */
- Statement getSingleStatement(Resource subject, Resource relation) throws NoSingleResultException,
- ManyObjectsForFunctionalRelationException, ServiceException;
-
- /**
- * Gets a single type t as returned by {@link ReadGraph#getPrincipalTypes}. Assumes a single type.
- *
- * @param subject a resource
- * @param baseType a resource
- * @return the single type
- * @throws NoSingleResultException if the amount of valid types was not one
- * @throws ServiceException on connection and database failures
- * @see AsyncReadGraph#forSingleType
- */
- Resource getSingleType(Resource subject) throws NoSingleResultException, ServiceException;
-
- /**
- * Gets a single type t as returned by {@link ReadGraph#getTypes} where
- * {@link ReadGraph#isInheritedFrom(t, baseType)}. Assumes a single type.
- *
- * @param subject a resource
- * @param baseType a resource
- * @return the single type
- * @throws NoSingleResultException if the amount of valid types was not one
- * @throws ServiceException on connection and database failures
- * @see AsyncReadGraph#forSingleType
- */
- Resource getSingleType(Resource subject, Resource baseType) throws NoSingleResultException, ServiceException;
-
- /**
- * Gets a value associated to subject. Infers {@link Binding} from type t =
- * {@link ReadGraph#getSingleType(subject, Value)}
- *
- * @param subject a resource
- * @return the value
- * @throws DoesNotContainValueException if the subject did not contain a
- * resource
- * @throws ServiceException on connection and database failure
- * @see AsyncReadGraph#forValue
- */
- T getValue(Resource subject) throws DoesNotContainValueException, ServiceException;
-
- /**
- * Gets a value associated to subject as a Variant. Infers {@link Binding} from type t =
- * {@link ReadGraph#getSingleType(subject, Value)}
- *
- * @param subject a resource
- * @return the value
- * @throws DoesNotContainValueException if the subject did not contain a
- * resource
- * @throws ServiceException on connection and database failure
- * @see AsyncReadGraph#forValue
- */
- Variant getVariantValue(Resource subject) throws DoesNotContainValueException, ServiceException;
-
- /**
- * Gets a value associated to subject using the given {@link Binding}.
- *
- * @param subject a resource
- * @param binding a binding
- * @return the value
- * @throws DoesNotContainValueException if the subject did not contain a
- * resource
- * @throws BindingException if value could not be produced using the given
- * {@link Binding}
- * @throws ServiceException on connection and database failure
- * @see AsyncReadGraph#forValue
- */
- T getValue(Resource subject, Binding binding) throws DoesNotContainValueException, BindingException,
- ServiceException;
-
- /**
- * Gets a single value associated to o such that (subject, r, o) and
- * {@link ReadGraph#isSubrelationOf(r, relation)}. Assumes a single value.
- * Infers {@link Binding} from type t =
- * {@link ReadGraph#getSingleType(o, Value)}
- *
- * @param subject a resource
- * @param relation a resource
- * @return the value
- * @throws NoSingleResultException if the amount of valid values was not one
- * @throws DoesNotContainValueException if suitable o did not contain a
- * resource
- * @throws ServiceException on connection and database failure
- * @see AsyncReadGraph#forRelatedValue
- */
- T getRelatedValue(Resource subject, Resource relation) throws NoSingleResultException,
- DoesNotContainValueException, ServiceException;
-
- /**
- * Gets a single value associated to o such that (subject, r, o) and
- * {@link ReadGraph#isSubrelationOf(r, relation)} as a Variant. Assumes a single value.
- * Infers {@link Binding} from type t =
- * {@link ReadGraph#getSingleType(o, Value)}
- *
- * @param subject a resource
- * @param relation a resource
- * @return the value
- * @throws NoSingleResultException if the amount of valid values was not one
- * @throws DoesNotContainValueException if suitable o did not contain a
- * resource
- * @throws ServiceException on connection and database failure
- * @see AsyncReadGraph#forRelatedValue
- */
- Variant getRelatedVariantValue(Resource subject, Resource relation) throws NoSingleResultException,
- DoesNotContainValueException, ServiceException;
-
- /**
- * Gets a single value associated to o such that (subject, r, o) and
- * {@link ReadGraph#isSubrelationOf(r, relation)}. Uses the given
- * {@link Binding}. Assumes a single value.
- *
- * @param subject a resource
- * @param relation a resource
- * @return the value
- * @throws NoSingleResultException if the amount of valid values was not one
- * @throws DoesNotContainValueException if suitable o did not contain a
- * resource
- * @throws BindingException if value could not be produced using the given
- * {@link Binding}
- * @throws ServiceException on connection and database failure
- * @see AsyncReadGraph#forRelatedValue
- */
- T getRelatedValue(Resource subject, Resource relation, Binding binding) throws NoSingleResultException,
- DoesNotContainValueException, BindingException, ServiceException;
-
- /**
- * Tries to adapt the specified resource into an instance of the specified
- * class T. No guarantees are made on return values of this method. The
- * returned values can be cached results of previous invocation or they can
- * be new result object instances. See {@link #adaptUnique(Resource, Class)}
- * for alternative behaviour.
- *
- * @param resource a resource
- * @param clazz the adapter class
- * @return
- * @throws AdaptionException if suitable adapter was not found
- * @throws ValidationException from the adapter
- * @throws ServiceException on connection and database failure
- * @see AsyncReadGraph#forAdapted
- * @see #adaptUnique(Resource, Class)
- */
- T adapt(Resource resource, Class clazz) throws AdaptionException, ValidationException, ServiceException;
-
- /**
- *
- * Same as: adapt(getSingleObject(resource, relation), clazz);
- *
- * @param resource a resource
- * @param relation a resource
- * @param clazz the adapter class
- * @return
- * @throws AdaptionException if suitable adapter was not found
- * @throws ValidationException from the adapter
- * @throws ServiceException on connection and database failure
- * @see AsyncReadGraph#forAdapted
- * @see #adaptUnique(Resource, Class)
- */
- T adaptRelated(Resource resource, Resource relation, Class clazz) throws AdaptionException, NoSingleResultException, ValidationException, ServiceException;
-
- /**
- *
- * Same as:
- *
- * Resource r = getPossibleObject(resource, relation);
- * if(r == null) return null;
- * return getPossibleAdapter(r, clazz);
- *
- * @param resource a resource
- * @param relation a resource
- * @param clazz the adapter class
- * @return
- * @throws AdaptionException if suitable adapter was not found
- * @throws ValidationException from the adapter
- * @throws ServiceException on connection and database failure
- * @see AsyncReadGraph#forAdapted
- * @see #adaptUnique(Resource, Class)
- */
- T getPossibleRelatedAdapter(Resource resource, Resource relation, Class clazz) throws ValidationException, ServiceException;
-
- T adaptContextual(Resource resource, C context, Class contextClass, Class clazz) throws AdaptionException, NoSingleResultException, ValidationException, ServiceException;
- T getPossibleContextualAdapter(Resource resource, C context, Class contextClass, Class clazz) throws ValidationException, ServiceException;
-
- /**
- * Tries to adapt the specified resource into an instance of the specified
- * class T. The difference to {@link #adapt(Resource, Class)} is that this
- * method does everything possible to return a new object instance for each
- * separate invocation.
- *
- *
- * The only case when this cannot be guaranteed is when the adaption result
- * comes from an {@link Adapter} implementation which can internally do
- * anything, like always return the same singleton instance.
- *
- *
- * @param resource a resource
- * @param clazz the adapter class
- * @return
- * @throws AdaptionException if suitable adapter was not found
- * @throws ValidationException from the adapter
- * @throws ServiceException on connection and database failure
- * @see AsyncReadGraph#forAdapted
- * @see #adapt(Resource, Class)
- */
- T adaptUnique(Resource resource, Class clazz) throws AdaptionException, ValidationException,
- ServiceException;
-
- /**
- * As {@link #getInverse} but returns null instead of an exception if
- * inverse was not found.
- *
- * @param relation a resource
- * @return the inverse or null
- * @throws ManyObjectsForFunctionalRelationException on invalid graph with
- * more than one functional object
- * @throws ServiceException on connection and database failures
- * @see AsyncReadGraph#forPossibleInverse
- */
- Resource getPossibleInverse(Resource relation) throws ManyObjectsForFunctionalRelationException, ServiceException;
-
- /**
- * As {@link #getSingleObject} but returns null instead of an exception if
- * object was not found.
- *
- * @param subject a resource
- * @param relation a resource
- * @return the object or null
- * @throws ManyObjectsForFunctionalRelationException on invalid graph with
- * more than one functional object
- * @throws ServiceException on connection and database failures
- * @see AsyncReadGraph#forPossibleObject
- */
- Resource getPossibleObject(Resource subject, Resource relation) throws ManyObjectsForFunctionalRelationException,
- ServiceException;
-
- /**
- * As {@link #getSingleStatement} but returns null instead of an exception
- * if statement was not found.
- *
- * @param subject a resource
- * @param relation a resource
- * @return the statement or null
- * @throws ManyObjectsForFunctionalRelationException on invalid graph with
- * more than one functional object
- * @throws ServiceException on connection and database failures
- * @see AsyncReadGraph#forPossibleStatement
- */
- Statement getPossibleStatement(Resource subject, Resource relation)
- throws ManyObjectsForFunctionalRelationException, ServiceException;
-
- /**
- * As {@link #getSingleType} but returns null instead of an exception if
- * type was not found.
- *
- * @param subject a resource
- * @param baseType a resource
- * @return the type or null
- * @throws ServiceException on connection and database failures
- * @see AsyncReadGraph#forPossibleType
- */
- Resource getPossibleType(Resource subject, Resource baseType) throws ServiceException;
-
- /**
- * As {@link #getValue} but returns null instead of an exception if value
- * was not found.
- *
- * @param subject a resource
- * @return the value or null
- * @throws ServiceException on connection and database failures
- * @see AsyncReadGraph#forPossibleValue
- */
- T getPossibleValue(Resource subject) throws ServiceException;
-
- /**
- * As {@link #getValue} but returns null instead of an exception if value
- * was not found.
- *
- * @param subject a resource
- * @param binding a {@link Binding}
- * @return the value or null
- * @throws BindingException if value could not be produced using the given
- * {@link Binding}
- * @throws ServiceException on connection and database failures
- * @see AsyncReadGraph#forPossibleValue
- */
- T getPossibleValue(Resource subject, Binding binding) throws BindingException, ServiceException;
-
- /**
- * As {@link #getPossibleRelatedValue} but returns null instead of an
- * exception if value was not found.
- *
- * @param subject a resource
- * @param relation a resource
- * @return the value or null
- * @throws ManyObjectsForFunctionalRelationException on invalid graph with
- * more than one functional object
- * @throws ServiceException on connection and database failures
- * @see AsyncReadGraph#forPossibleRelatedValue
- */
- T getPossibleRelatedValue(Resource subject, Resource relation)
- throws ManyObjectsForFunctionalRelationException, ServiceException;
-
- /**
- * As {@link #getPossibleRelatedValue} but returns null instead of an
- * exception if value was not found.
- *
- * @param subject a resource
- * @param relation a resource
- * @param binding a {@link Binding}
- * @return the value or null
- * @throws ManyObjectsForFunctionalRelationException on invalid graph with
- * more than one functional object
- * @throws BindingException if value could not be produced using the given
- * {@link Binding}
- * @throws ServiceException on connection and database failures
- * @see AsyncReadGraph#forPossibleRelatedValue
- */
- T getPossibleRelatedValue(Resource subject, Resource relation, Binding binding)
- throws ManyObjectsForFunctionalRelationException, BindingException, ServiceException;
-
- /**
- * As {@link #adapt} but returns null instead of an exception if adapter was
- * not found
- *
- * @param subject a resource
- * @param clazz a Class
- * @return the adapter or null
- * @throws ValidationException when ?
- * @throws ServiceException on connection and database failures
- * @see {@link AsyncReadGraph#forPossibleAdapted}
- */
- T getPossibleAdapter(Resource resource, Class clazz) throws ValidationException, ServiceException;
-
- /**
- * As {@link #adaptUnique} but returns null instead of an exception if
- * adapter was not found
- *
- * @param subject a resource
- * @param clazz a Class
- * @return the adapter or null
- * @throws ValidationException when ?
- * @throws ServiceException on connection and database failures
- * @see {@link AsyncReadGraph#forPossibleAdapted}
- */
- T getPossibleUniqueAdapter(Resource resource, Class clazz) throws ValidationException, ServiceException;
-
- /**
- * Returns true if type is included in the result of {@link #getTypes(resource)}
- *
- * @param subject a resource
- * @param type a resource
- * @return indicates if resource is an instance of type
- * @throws ServiceException on connection and database failures
- * @see {@link AsyncReadGraph#forIsInstanceOf}
- */
- boolean isInstanceOf(Resource resource, Resource type) throws ServiceException;
-
- /**
- * Returns true if type equals resource or type is included in the result of
- * {@link #getSupertypes(resource)}
- *
- * @param subject a resource
- * @param type a resource
- * @return indicates if resource is inherited from type
- * @throws ServiceException on connection and database failures
- * @see {@link AsyncReadGraph#forIsInheritedFrom}
- */
- boolean isInheritedFrom(Resource resource, Resource type) throws ServiceException;
-
- /**
- * Returns true if relation equals resource or relation is included in the result of
- * {@link #getSuperrelations(resource)}
- *
- * @param subject a resource
- * @param relation a resource
- * @return indicates if resource is a subrelation of relation
- * @throws ServiceException on connection and database failures
- * @see {@link AsyncReadGraph#forIsSubrelationOf}
- */
- boolean isSubrelationOf(Resource resource, Resource relation) throws ServiceException;
-
- /**
- * Returns true if the result of {@link #getStatements(subject, IsWeaklyRelatedTo)} is nonempty.
- *
- * @param subject a resource
- * @return indicates that subject has statements
- * @throws ServiceException on connection and database failures
- * @see {@link AsyncReadGraph#forHasStatement}
- */
- boolean hasStatement(Resource subject) throws ServiceException;
-
- /**
- * Returns true if the result of {@link #getStatements(subject, relation)} is nonempty.
- *
- * @param subject a resource
- * @param relation a resource
- * @return indicates that subject has statements with predicates as subrelation of relation
- * @throws ServiceException on connection and database failures
- * @see {@link AsyncReadGraph#forHasStatement}
- */
- boolean hasStatement(Resource subject, Resource relation) throws ServiceException;
-
- /**
- * Returns true if a statement (subject, relation, object) exists after assertions.
- *
- * @param subject a resource
- * @param relation a resource
- * @param object a resource
- * @return indicates that the given statement exists
- * @throws ServiceException on connection and database failures
- * @see {@link AsyncReadGraph#forHasStatement}
- */
- boolean hasStatement(Resource subject, Resource relation, Resource object) throws ServiceException;
-
- /**
- * Returns true if there is a value associated with subject.
- * IMPLEMENTATION NOTE:
- * Current implementation fetches the value from server. If the value is
- * large (i.e. not stored in the cluster) this is highly inefficient.
- *
- * @param subject a resource
- * @return indicates that a value exists
- * @throws ServiceException on connection and database failures
- * @see {@link AsyncReadGraph#forHasValue}
- */
- boolean hasValue(Resource subject) throws ServiceException;
-
- /**
- * Returns the data type of the literal.
- * @param subject
- * @return
- * @throws DatabaseException
- */
- Datatype getDataType(Resource subject) throws DatabaseException;
-
- /**
- * Returns an accessory that can be used to partially read the literal
- * or write if the graph is WriteGraph. The returned accessory is closed
- * automatically when the transaction ends. The modifications are written
- * back to graph at transaction completion.
- *
- * @param is typed accessory for modifying the literal value.
- * @param resource is the literal containing the value.
- * @return interface to partially read and write the literal value.
- * @throws DatabaseException
- */
- T getAccessor(Resource resource) throws DatabaseException;
-
- /**
- * Returns an RandomAccessBinary that can be used to partially read the literal
- * or write if the graph is WriteGraph. The returned interface is closed
- * automatically when the transaction ends. The modifications are written
- * back to graph at transaction completion.
- *
- * @param
- * @param resource is the literal containing the value.
- * @return interface to partially read and write the literal value.
- * @throws DatabaseException
- */
- RandomAccessBinary getRandomAccessBinary(Resource resource) throws DatabaseException;
-// @SuppressWarnings("rawtypes")
-// Function getValueFunction(Resource resource) throws DatabaseException;
-
- /**
- * Get the value associated with a graph {@link Resource}, using a possible context object and
- * a default data type binding. An exception is thrown, if the value is not found.
- *
- * See {@link #getValue2(Resource, Object, Binding)} for more details.
- *
- * @param r A graph resource with which the value is associated
- * @param context A context object that is used for acquiring the value, can be {@code null}
- * @return The value of the graph node.
- * @throws DoesNotContainValueException No value is associated with the graph node.
- * @throws DatabaseException Other errors, such as an error in casting the value to the return type or
- * a runtime error in the value function.
- * @see #getValue2(Resource, Object, Binding)
- * @see #getPossibleValue2(Resource, Object)
- */
- T getValue2(Resource subject, Object context) throws DatabaseException;
-
- /**
- * Get the value associated with a graph {@link Resource}, using a possible context object and
- * a default data type binding as a Variant. An exception is thrown, if the value is not found.
- *
- * See {@link #getValue2(Resource, Object, Binding)} for more details.
- *
- * @param r A graph resource with which the value is associated
- * @param context A context object that is used for acquiring the value, can be {@code null}
- * @return The value of the graph node.
- * @throws DoesNotContainValueException No value is associated with the graph node.
- * @throws DatabaseException Other errors, such as an error in casting the value to the return type or
- * a runtime error in the value function.
- * @see #getValue2(Resource, Object, Binding)
- * @see #getPossibleValue2(Resource, Object)
- */
- Variant getVariantValue2( Resource r, Object context ) throws DatabaseException;
-
- /**
- * Get a possible value associated with a graph {@link Resource}, using a possible context object and
- * a desired value binding. Unlike {@link #getValue2(Resource, Object)}, this methods
- * returns {@code null} for missing values instead of throwing an exception.
- *
- * See {@link #getValue2(Resource, Object, Binding)} for more details.
- *
- * @param r A graph resource with which the value is associated
- * @param context A context object that is used for acquiring the value, can be {@code null}
- * @return The value of the graph node.
- * @throws DatabaseException Usually should not happen. A null value is returned for possible errors.
- * @see #getValue2(Resource, Object)
- * @see #getPossibleValue2(Resource, Object, Binding)
- */
- T getPossibleValue2(Resource subject, Object context) throws DatabaseException;
-
- /**
- * Get the value associated with a graph {@link Resource}, using a possible context object and
- * a desired value binding. An exception is thrown, if the value is not found.
- *
- * The following methods are tried in order to retrieve the value:
- *
- * - If the given resource is a {@code L0.Literal}, the value of the literal is returned, using the binding specified by {@code binding}.
- * - If the resource is a {@code L0.ExternalValue}, the value is acquired using
- * {@link ReflectionUtils#getValue(String)} with the resource URI.
- * - If the resource is associated with a suitable value converter with relation {@code L0.ConvertsToValueWith}
- * (see {@link #requestValueFunction(Resource)}), the value function is called with the graph, the resource
- * and the context object.
- *
- *
- * @param r A graph resource with which the value is associated
- * @param context A context object that is used for acquiring the value, can be {@code null}
- * @param binding A binding for the value type
- * @return The value of the graph node.
- * @throws DoesNotContainValueException No value is associated with the graph node.
- * @throws DatabaseException Other errors, such as an error in casting the value to the return type or
- * a runtime error in the value function.
- * @see #getValue2(Resource, Object)
- * @see #getPossibleValue2(Resource, Object, Binding)
- */
- T getValue2(Resource subject, Object context, Binding binding) throws DatabaseException;
-
- /**
- * Get a possible value associated with a graph {@link Resource}, using a possible context object and
- * a desired value binding. Unlike {@link #getValue2(Resource, Object, Binding)}, this methods
- * returns {@code null} for missing values instead of throwing an exception.
- *
- * See {@link #getValue2(Resource, Object, Binding)} for more details.
- *
- * @param r A graph resource with which the value is associated
- * @param context A context object that is used for acquiring the value, can be {@code null}
- * @param binding A binding for the value type
- * @return The value of the graph node.
- * @throws DatabaseException Usually should not happen. A null value is returned for possible errors.
- * @see #getValue2(Resource, Object, Bindinge)
- * @see #getPossibleValue2(Resource, Object)
- */
- T getPossibleValue2(Resource subject, Object context, Binding binding) throws DatabaseException;
-
- /**
- * Get the single value associated with a graph resource related with a given subject.
- * An exception is thrown, if a unique object resource or a value for it is not found.
- *
- * See {@link #getValue2(Resource, Object, Binding)} for more details.
- *
- * @param subject A graph resource that indicates the subject node
- * @param relation A graph resource that indicates the predicate of a relation
- * @return The value of the unique graph node that is asserted as the object of the given subject and predicate.
- * @throws NoSingleResultException The number of suitable object resources is not equal to 1 (zero or greater than one)
- * @throws DoesNotContainValueException No value is associated with the graph node.
- * @throws DatabaseException Other errors, such as an error in casting the value to the return type or
- * a runtime error in the value function.
- * @see #getRelatedValue2(Resource, Resource, Binding)
- * @see #getRelatedValue2(Resource, Resource, Object)
- * @see #getRelatedValue2(Resource, Resource, Object, Binding)
- * @see #getPossibleRelatedValue2(Resource, Resource)
- */
- T getRelatedValue2(Resource subject, Resource relation) throws DatabaseException;
-
- /**
- * Get a possible single value associated with a graph resource related with a given subject.
- * A {@code null} value is returned for missing values or other errors.
- *
- * See {@link #getValue2(Resource, Object, Binding)} for more details.
- *
- * @param subject A graph resource that indicates the subject node
- * @param relation A graph resource that indicates the predicate of a relation
- * @return The value of the unique graph node that is asserted as the object of the given subject and predicate.
- * @throws DatabaseException Usually should not happen. A {@code null} value is returned for possible errors.
- * @see #getPossibleRelatedValue2(Resource, Resource, Binding)
- * @see #getPossibleRelatedValue2(Resource, Resource, Object)
- * @see #getPossibleRelatedValue2(Resource, Resource, Object, Binding)
- * @see #getRelatedValue2(Resource, Resource)
- */
- T getPossibleRelatedValue2(Resource subject, Resource relation) throws DatabaseException;
-
- /**
- * Get a possible single value associated with a graph resource related with a given subject.
- * A {@code null} value is returned for missing values or other errors.
- *
- * See {@link #getValue2(Resource, Object, Binding)} for more details.
- *
- * @param subject A graph resource that indicates the subject node
- * @param relation A graph resource that indicates the predicate of a relation
- * @return The value of the unique graph node that is asserted as the object of the given subject and predicate.
- * @throws DatabaseException Usually should not happen. A {@code null} value is returned for possible errors.
- * @see #getPossibleRelatedValue2(Resource, Resource, Binding)
- * @see #getPossibleRelatedValue2(Resource, Resource, Object)
- * @see #getPossibleRelatedValue2(Resource, Resource, Object, Binding)
- * @see #getRelatedValue2(Resource, Resource)
- */
- Variant getRelatedVariantValue2( Resource subject, Resource relation ) throws DatabaseException;
-
- /**
- * Get the single value associated with a graph resource related with a given subject, a possible context object.
- * An exception is thrown, if a unique object resource or a value for it is not found.
- *
- * See {@link #getValue2(Resource, Object, Binding)} for more details.
- *
- * @param subject A graph resource that indicates the subject node
- * @param relation A graph resource that indicates the predicate of a relation
- * @param context A context object that is used for acquiring the value, can be {@code null}
- * @return The value of the unique graph node that is asserted as the object of the given subject and predicate.
- * @throws NoSingleResultException The number of suitable object resources is not equal to 1 (zero or greater than one)
- * @throws DoesNotContainValueException No value is associated with the graph node.
- * @throws DatabaseException Other errors, such as an error in casting the value to the return type or
- * a runtime error in the value function.
- * @see #getRelatedValue2(Resource, Resource)
- * @see #getRelatedValue2(Resource, Resource, Binding)
- * @see #getRelatedValue2(Resource, Resource, Object, Binding)
- * @see #getPossibleRelatedValue2(Resource, Resource, Object)
- */
- T getRelatedValue2(Resource subject, Resource relation, Object context) throws DatabaseException;
-
- /**
- * Get the single value associated with a graph resource related with a given subject, a possible context object.
- * An exception is thrown, if a unique object resource or a value for it is not found.
- *
- * See {@link #getValue2(Resource, Object, Binding)} for more details.
- *
- * @param subject A graph resource that indicates the subject node
- * @param relation A graph resource that indicates the predicate of a relation
- * @param context A context object that is used for acquiring the value, can be {@code null}
- * @return The value of the unique graph node that is asserted as the object of the given subject and predicate.
- * @throws NoSingleResultException The number of suitable object resources is not equal to 1 (zero or greater than one)
- * @throws DoesNotContainValueException No value is associated with the graph node.
- * @throws DatabaseException Other errors, such as an error in casting the value to the return type or
- * a runtime error in the value function.
- * @see #getRelatedValue2(Resource, Resource, Object)
- * @see #getPossibleRelatedValue2(Resource, Resource, Object)
- */
- Variant getRelatedVariantValue2( Resource subject, Resource relation, Object context ) throws DatabaseException;
-
- /**
- * Get a possible single value associated with a graph resource related with a given subject and a possible context object.
- * A {@code null} value is returned for missing values or other errors.
- *
- * See {@link #getValue2(Resource, Object, Binding)} for more details.
- *
- * @param subject A graph resource that indicates the subject node
- * @param relation A graph resource that indicates the predicate of a relation
- * @param context A context object that is used for acquiring the value, can be {@code null}
- * @return The value of the unique graph node that is asserted as the object of the given subject and predicate.
- * @throws DatabaseException Usually should not happen. A {@code null} value is returned for possible errors.
- * @see #getPossibleRelatedValue2(Resource, Resource)
- * @see #getPossibleRelatedValue2(Resource, Resource, Binding)
- * @see #getPossibleRelatedValue2(Resource, Resource, Object, Binding)
- * @see #getRelatedValue2(Resource, Resource, Object)
- */
- T getPossibleRelatedValue2(Resource subject, Resource relation, Object context) throws DatabaseException;
-
- /**
- * Get the single value associated with a graph resource related with a given subject and
- * a desired value binding. An exception is thrown, if a unique object resource or a value for it is not found.
- *
- * See {@link #getValue2(Resource, Object, Binding)} for more details.
- *
- * @param subject A graph resource that indicates the subject node
- * @param relation A graph resource that indicates the predicate of a relation
- * @param binding A binding for the value type
- * @return The value of the unique graph node that is asserted as the object of the given subject and predicate.
- * @throws NoSingleResultException The number of suitable object resources is not equal to 1 (zero or greater than one)
- * @throws DoesNotContainValueException No value is associated with the graph node.
- * @throws DatabaseException Other errors, such as an error in casting the value to the return type or
- * a runtime error in the value function.
- * @see #getRelatedValue2(Resource, Resource)
- * @see #getRelatedValue2(Resource, Resource, Object)
- * @see #getRelatedValue2(Resource, Resource, Object, Binding)
- * @see #getPossibleRelatedValue2(Resource, Resource, Binding)
- */
- T getRelatedValue2(Resource subject, Resource relation, Binding binding) throws DatabaseException;
-
- /**
- * Get a possible single value associated with a graph resource related with a given subject and
- * a desired value binding. A {@code null} value is returned for missing values or other errors.
- *
- * See {@link #getValue2(Resource, Object, Binding)} for more details.
- *
- * @param subject A graph resource that indicates the subject node
- * @param relation A graph resource that indicates the predicate of a relation
- * @param binding A binding for the value type
- * @return The value of the unique graph node that is asserted as the object of the given subject and predicate.
- * @throws DatabaseException Usually should not happen. A {@code null} value is returned for possible errors.
- * @see #getPossibleRelatedValue2(Resource, Resource)
- * @see #getPossibleRelatedValue2(Resource, Resource, Object)
- * @see #getPossibleRelatedValue2(Resource, Resource, Object, Binding)
- * @see #getRelatedValue2(Resource, Resource, Binding)
- */
- T getPossibleRelatedValue2(Resource subject, Resource relation, Binding binding) throws DatabaseException;
-
- /**
- * Get the single value associated with a graph resource related with a given subject, a possible context object and
- * a desired value binding. An exception is thrown, if a unique object resource or a value for it is not found.
- *
- * See {@link #getValue2(Resource, Object, Binding)} for more details.
- *
- * @param subject A graph resource that indicates the subject node
- * @param relation A graph resource that indicates the predicate of a relation
- * @param context A context object that is used for acquiring the value, can be {@code null}
- * @param binding A binding for the value type
- * @return The value of the unique graph node that is asserted as the object of the given subject and predicate.
- * @throws NoSingleResultException The number of suitable object resources is not equal to 1 (zero or greater than one)
- * @throws DoesNotContainValueException No value is associated with the graph node.
- * @throws DatabaseException Other errors, such as an error in casting the value to the return type or
- * a runtime error in the value function.
- * @see #getRelatedValue2(Resource, Resource)
- * @see #getRelatedValue2(Resource, Resource, Binding)
- * @see #getRelatedValue2(Resource, Resource, Object)
- * @see #getPossibleRelatedValue2(Resource, Resource, Object, Binding)
- */
- T getRelatedValue2(Resource subject, Resource relation, Object context, Binding binding) throws DatabaseException;
-
- /**
- * Get a possible single value associated with a graph resource related with a given subject, a possible context object and
- * a desired value binding. A {@code null} value is returned for missing values or other errors.
- *
- * See {@link #getValue2(Resource, Object, Binding)} for more details.
- *
- * @param subject A graph resource that indicates the subject node
- * @param relation A graph resource that indicates the predicate of a relation
- * @param context A context object that is used for acquiring the value, can be {@code null}
- * @param binding A binding for the value type
- * @return The value of the unique graph node that is asserted as the object of the given subject and predicate.
- * @throws DatabaseException Usually should not happen. A {@code null} value is returned for possible errors.
- * @see #getPossibleRelatedValue2(Resource, Resource)
- * @see #getPossibleRelatedValue2(Resource, Resource, Binding)
- * @see #getPossibleRelatedValue2(Resource, Resource, Object)
- * @see #getRelatedValue2(Resource, Resource, Object, Binding)
- */
- T getPossibleRelatedValue2(Resource subject, Resource relation, Object context, Binding binding) throws DatabaseException;
-
- /**
- * Get the parsed SCL type declaration from the string value of a graph resource that is the unique object of a
- * given subject and predicate.
- *
- * See {@link #getValue2(Resource, Object, Binding)} for more details.
- *
- * @param subject A resource that indicates the subject of a statement
- * @param relation A resource that indicates the predicate of the statement
- * @return A compiled SCL type definition of the string value of a unique object resource
- * @throws DatabaseException For any errors in locating a unique value or compiling it as an SCL type statement
- */
- Type getRelatedValueType(Resource subject, Resource relation) throws DatabaseException;
-
- boolean setSynchronous(boolean value);
- boolean getSynchronous();
-}
+/*******************************************************************************
+ * Copyright (c) 2007, 2010 Association for Decentralized Information Management
+ * in Industry THTH ry.
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the Eclipse Public License v1.0
+ * which accompanies this distribution, and is available at
+ * http://www.eclipse.org/legal/epl-v10.html
+ *
+ * Contributors:
+ * VTT Technical Research Centre of Finland - initial API and implementation
+ *******************************************************************************/
+package org.simantics.db;
+
+import java.util.Collection;
+import java.util.Set;
+
+import org.simantics.databoard.accessor.Accessor;
+import org.simantics.databoard.binding.Binding;
+import org.simantics.databoard.binding.mutable.Variant;
+import org.simantics.databoard.type.Datatype;
+import org.simantics.databoard.util.binary.RandomAccessBinary;
+import org.simantics.db.adaption.Adapter;
+import org.simantics.db.exception.AdaptionException;
+import org.simantics.db.exception.AssumptionException;
+import org.simantics.db.exception.BindingException;
+import org.simantics.db.exception.DatabaseException;
+import org.simantics.db.exception.DoesNotContainValueException;
+import org.simantics.db.exception.ManyObjectsForFunctionalRelationException;
+import org.simantics.db.exception.NoInverseException;
+import org.simantics.db.exception.NoSingleResultException;
+import org.simantics.db.exception.ResourceNotFoundException;
+import org.simantics.db.exception.ServiceException;
+import org.simantics.db.exception.ValidationException;
+import org.simantics.db.procedure.SyncListener;
+import org.simantics.db.procedure.SyncMultiListener;
+import org.simantics.db.procedure.SyncMultiProcedure;
+import org.simantics.db.procedure.SyncProcedure;
+import org.simantics.db.procedure.SyncSetListener;
+import org.simantics.db.request.MultiRead;
+import org.simantics.db.request.Read;
+import org.simantics.scl.compiler.types.Type;
+
+/**
+ *
+ * For accessing and manipulating the graph data in synchronous manner. A client
+ * receives ReadGraph instances for performing requests in {@link Read} and
+ * {@link MultiRead} as well as for reacting to request results using
+ * {@link SyncProcedure}, {@link SyncListener}, {@link SyncMultiProcedure},
+ * {@link SyncMultiListener} and {@link SyncSetListener}
+ *
+ * ReadGraph instances are stateful and may not be stored and used outside the
+ * supplier method activation. The methods receiving ReadGraph should not block
+ * for long periods of time since that may delay the processing of other
+ * requests. For an asynchronous counterpart with the same functionality as
+ * ReadGraph see {@link AsyncReadGraph}
+ *
+ *
+ * All collections returned by the methods on this interface must not be
+ * modified by clients unless explicitly stated otherwise.
+ *
+ * @version 0.7
+ * @author Antti Villberg
+ * @see RequestProcessor
+ * @see AsyncRequestProcessor
+ * @see AsyncReadGraph
+ * @see Resource
+ * @see Statement
+ * @noimplement
+ */
+public interface ReadGraph extends AsyncReadGraph, RequestProcessor {
+
+ /**
+ *
+ * @see AsyncReadGraph#forURI
+ */
+ String getURI(Resource resource) throws AssumptionException, ValidationException, ServiceException;
+ String getPossibleURI(Resource resource) throws ValidationException, ServiceException;
+
+ /**
+ * Gets a unique resource associated to the given identifier. See Simantics Wiki page
+ * on URIs for more details.
+ *
+ * @param uri the identifier
+ * @return the resource
+ * @throws ResourceNotFoundException if a resource for the given identifier
+ * was not specified
+ * @throws ValidationException if a resource could not be produced due to
+ * invalid semantics
+ * @throws ServiceException on connection and database failures
+ * @see AsyncReadGraph#forResourceByURI
+ */
+ Resource getResource(String uri) throws ResourceNotFoundException, ValidationException, ServiceException;
+
+ /**
+ * Gets a unique resource associated to the given identifier. See Simantics Wiki page
+ * on URIs for more details.
+ *
+ * @param uri the identifier
+ * @return the resource
+ * @throws ResourceNotFoundException if a resource for the given identifier
+ * was not specified
+ * @throws ValidationException if a resource could not be produced due to
+ * invalid semantics
+ * @throws ServiceException on connection and database failures
+ * @see AsyncReadGraph#forResourceByURI
+ */
+ Resource getPossibleResource(String uri) throws ResourceNotFoundException, ValidationException, ServiceException;
+
+ /**
+ * Gets a builtin resource. For a list of builtin resources see TODO Wiki
+ *
+ * @param uri the identifier
+ * @return the resource
+ * @throws ResourceNotFoundException if resouce was not found
+ * @throws ServiceException on connection and database failures
+ * @see AsyncReadGraph#forBuiltin
+ */
+ Resource getBuiltin(String id) throws ResourceNotFoundException, ServiceException;
+
+ /**
+ * Gets all statements (subject, p, o) such that
+ * {@link ReadGraph#isSubrelationOf(p, relation)} returns true. The result
+ * may include asserted statements for which s does not equal subject. See
+ * the assertion mechanisn TODO for more details. If the relation is
+ * functional the request returns a single statement according to the
+ * functional statement shadowing rules TODO if possible. If an invalid
+ * graph is encountered an exception is thrown.
+ *
+ * @param subject a resource
+ * @param relation a resource
+ * @return the statements
+ * @throws ManyObjectsForFunctionalRelationException on invalid graph with
+ * more than one functional object
+ * @throws ServiceException on connection and database failures
+ * @see AsyncReadGraph#forEachStatement
+ * @see AsyncReadGraph#forStatementSet
+ */
+ Collection getStatements(Resource subject, Resource relation)
+ throws ManyObjectsForFunctionalRelationException, ServiceException;
+
+ /**
+ * Gets all statements (s, p, o) asserted by subject such that
+ * {@link ReadGraph#isSubrelationOf(p, relation)} returns true. See the
+ * assertion mechanism TODO for more details. If the relation is functional
+ * the request returns a single statement according to the functional
+ * statement shadowing rules TODO if possible. If an invalid graph is
+ * encountered an exception is thrown.
+ *
+ * @param subject a resource
+ * @param relation a resource
+ * @return the statements
+ * @throws ManyObjectsForFunctionalRelationException on invalid graph with
+ * more than one functional object
+ * @throws ServiceException on connection and database failures
+ * @see AsyncReadGraph#forEachAssertedStatement
+ * @see AsyncReadGraph#forAssertedStatementSet
+ */
+ Collection getAssertedStatements(Resource subject, Resource relation)
+ throws ManyObjectsForFunctionalRelationException, ServiceException;
+
+ /**
+ * Gets all predicates p from statements (subject, p, o) such that
+ * {@link ReadGraph#isSubrelationOf(p, relation)} returns true. See the
+ * assertion mechanism TODO for more details. If the relation is functional
+ * the request returns a single statement according to the functional
+ * statement shadowing rules TODO if possible. If an invalid graph is
+ * encountered an exception is thrown.
+ *
+ * @param subject a resource
+ * @param relation a resource
+ * @return the predicates
+ * @throws ManyObjectsForFunctionalRelationException on invalid graph with
+ * more than one object
+ * @throws ServiceException on connection and database failures
+ * @see AsyncReadGraph#forEachPredicate
+ * @see AsyncReadGraph#forPredicateSet
+ */
+ Collection getPredicates(Resource subject) throws ServiceException;
+
+ /**
+ * Gets a subset of all types of the subject such that no pair of returned
+ * types inherit each other and all types of the subject are supertypes
+ * of some type in the returned set.
+ *
+ * @param subject a resource
+ * @return the principal types
+ * @throws ServiceException on connection and database failures
+ * @see AsyncReadGraph#forEachPrincipalType
+ * @see AsyncReadGraph#forPrincipalTypeSet
+ */
+ Collection getPrincipalTypes(Resource subject) throws ServiceException;
+
+ /**
+ * Gets the full type hierarchy for subject.
+ *
+ * @param subject a resource
+ * @return the type hierarchy
+ * @throws ServiceException on connection and database failures
+ * @see AsyncReadGraph#forTypes
+ */
+ Set getTypes(Resource subject) throws ServiceException;
+
+ /**
+ * Gets the full supertype hierarchy for subject.
+ *
+ * @param subject a resource
+ * @return the supertype hierarchy
+ * @throws ServiceException on connection and database failures
+ * @see AsyncReadGraph#forSupertypes
+ */
+ Set getSupertypes(Resource subject) throws ServiceException;
+
+ /**
+ * Gets the full superrelation hierarchy for subject.
+ *
+ * @param subject a resource
+ * @return the superrelation hierarchy
+ * @throws ServiceException on connection and database failures
+ * @see AsyncReadGraph#forSuperrelations
+ */
+ Set getSuperrelations(Resource subject) throws ServiceException;
+ Resource getPossibleSuperrelation(Resource subject) throws ServiceException;
+
+ /**
+ * Gets all objects o from statements (subject, p, o) such that
+ * {@link ReadGraph#isSubrelationOf(p, relation)} returns true. See the
+ * assertion mechanisn TODO for more details. If the relation is functional
+ * the request returns a single object according to the functional statement
+ * shadowing rules TODO if possible. If an invalid graph is encountered an
+ * exception is thrown.
+ *
+ * @param subject a resource
+ * @param relation a resource
+ * @return the objects
+ * @throws ManyObjectsForFunctionalRelationException on invalid graph with
+ * more than one functional object
+ * @throws ServiceException on connection and database failures
+ * @see AsyncReadGraph#forEachObject
+ * @see AsyncReadGraph#forObjectSet
+ */
+ Collection getObjects(Resource subject, Resource relation)
+ throws ServiceException;
+
+ /**
+ * Gets all objects o (s, p, o) asserted by subject such that
+ * {@link ReadGraph#isSubrelationOf(p, relation)} returns true. See the
+ * assertion mechanism TODO for more details. If the relation is functional
+ * the request returns a single object according to the functional statement
+ * shadowing rules TODO if possible. If an invalid graph is encountered an
+ * exception is thrown.
+ *
+ * @param subject a resource
+ * @param relation a resource
+ * @return the objects
+ * @throws ManyObjectsForFunctionalRelationException on invalid graph with
+ * more than one functional object
+ * @throws ServiceException on connection and database failures
+ * @see AsyncReadGraph#forEachAssertedStatement
+ * @see AsyncReadGraph#forAssertedStatementSet
+ */
+ Collection getAssertedObjects(Resource subject, Resource relation)
+ throws ManyObjectsForFunctionalRelationException, ServiceException;
+
+ /**
+ * Gets the inverse r of relation such that (relation, InverseOf, r). The
+ * methods assumes an inverse exists.
+ *
+ * @param relation a resource
+ * @return the inverse
+ * @throws NoInverseException if inverse was not fond
+ * @throws ManyObjectsForFunctionalRelationException on invalid graph with
+ * more than one functional object
+ * @throws ServiceException on connection and database failures
+ * @see AsyncReadGraph#forInverse
+ */
+ Resource getInverse(Resource relation) throws NoInverseException, ManyObjectsForFunctionalRelationException,
+ ServiceException;
+
+ /**
+ * Gets a single object as returned by {@link ReadGraph#getObjects}. Assumes
+ * a single object.
+ *
+ * @param subject a resource
+ * @param relation a resource
+ * @return the single object
+ * @throws NoSingleResultException if the amount of valid objects was not
+ * one
+ * @throws ManyObjectsForFunctionalRelationException on invalid graph with
+ * more than one functional object
+ * @throws ServiceException on connection and database failures
+ * @see AsyncReadGraph#forSingleObject
+ */
+ Resource getSingleObject(Resource subject, Resource relation) throws NoSingleResultException,
+ ManyObjectsForFunctionalRelationException, ServiceException;
+
+ /**
+ * Gets a single statement as returned by {@link ReadGraph#getStatements}.
+ * Assumes a single statement.
+ *
+ * @param subject a resource
+ * @param relation a resource
+ * @return the single statement
+ * @throws NoSingleResultException if the amount of valid statements was not
+ * one
+ * @throws ManyObjectsForFunctionalRelationException on invalid graph with
+ * more than one functional object
+ * @throws ServiceException on connection and database failures
+ * @see AsyncReadGraph#forSingleStatement
+ */
+ Statement getSingleStatement(Resource subject, Resource relation) throws NoSingleResultException,
+ ManyObjectsForFunctionalRelationException, ServiceException;
+
+ /**
+ * Gets a single type t as returned by {@link ReadGraph#getPrincipalTypes}. Assumes a single type.
+ *
+ * @param subject a resource
+ * @param baseType a resource
+ * @return the single type
+ * @throws NoSingleResultException if the amount of valid types was not one
+ * @throws ServiceException on connection and database failures
+ * @see AsyncReadGraph#forSingleType
+ */
+ Resource getSingleType(Resource subject) throws NoSingleResultException, ServiceException;
+
+ /**
+ * Gets a single type t as returned by {@link ReadGraph#getTypes} where
+ * {@link ReadGraph#isInheritedFrom(t, baseType)}. Assumes a single type.
+ *
+ * @param subject a resource
+ * @param baseType a resource
+ * @return the single type
+ * @throws NoSingleResultException if the amount of valid types was not one
+ * @throws ServiceException on connection and database failures
+ * @see AsyncReadGraph#forSingleType
+ */
+ Resource getSingleType(Resource subject, Resource baseType) throws NoSingleResultException, ServiceException;
+
+ /**
+ * Gets a value associated to subject. Infers {@link Binding} from type t =
+ * {@link ReadGraph#getSingleType(subject, Value)}
+ *
+ * @param subject a resource
+ * @return the value
+ * @throws DoesNotContainValueException if the subject did not contain a
+ * resource
+ * @throws ServiceException on connection and database failure
+ * @see AsyncReadGraph#forValue
+ */
+ T getValue(Resource subject) throws DoesNotContainValueException, ServiceException;
+
+ /**
+ * Gets a value associated to subject as a Variant. Infers {@link Binding} from type t =
+ * {@link ReadGraph#getSingleType(subject, Value)}
+ *
+ * @param subject a resource
+ * @return the value
+ * @throws DoesNotContainValueException if the subject did not contain a
+ * resource
+ * @throws ServiceException on connection and database failure
+ * @see AsyncReadGraph#forValue
+ */
+ Variant getVariantValue(Resource subject) throws DoesNotContainValueException, ServiceException;
+
+ /**
+ * Gets a value associated to subject using the given {@link Binding}.
+ *
+ * @param subject a resource
+ * @param binding a binding
+ * @return the value
+ * @throws DoesNotContainValueException if the subject did not contain a
+ * resource
+ * @throws BindingException if value could not be produced using the given
+ * {@link Binding}
+ * @throws ServiceException on connection and database failure
+ * @see AsyncReadGraph#forValue
+ */
+ T getValue(Resource subject, Binding binding) throws DoesNotContainValueException, BindingException,
+ ServiceException;
+
+ /**
+ * Gets a single value associated to o such that (subject, r, o) and
+ * {@link ReadGraph#isSubrelationOf(r, relation)}. Assumes a single value.
+ * Infers {@link Binding} from type t =
+ * {@link ReadGraph#getSingleType(o, Value)}
+ *
+ * @param subject a resource
+ * @param relation a resource
+ * @return the value
+ * @throws NoSingleResultException if the amount of valid values was not one
+ * @throws DoesNotContainValueException if suitable o did not contain a
+ * resource
+ * @throws ServiceException on connection and database failure
+ * @see AsyncReadGraph#forRelatedValue
+ */
+ T getRelatedValue(Resource subject, Resource relation) throws NoSingleResultException,
+ DoesNotContainValueException, ServiceException;
+
+ /**
+ * Gets a single value associated to o such that (subject, r, o) and
+ * {@link ReadGraph#isSubrelationOf(r, relation)} as a Variant. Assumes a single value.
+ * Infers {@link Binding} from type t =
+ * {@link ReadGraph#getSingleType(o, Value)}
+ *
+ * @param subject a resource
+ * @param relation a resource
+ * @return the value
+ * @throws NoSingleResultException if the amount of valid values was not one
+ * @throws DoesNotContainValueException if suitable o did not contain a
+ * resource
+ * @throws ServiceException on connection and database failure
+ * @see AsyncReadGraph#forRelatedValue
+ */
+ Variant getRelatedVariantValue(Resource subject, Resource relation) throws NoSingleResultException,
+ DoesNotContainValueException, ServiceException;
+
+ /**
+ * Gets a single value associated to o such that (subject, r, o) and
+ * {@link ReadGraph#isSubrelationOf(r, relation)}. Uses the given
+ * {@link Binding}. Assumes a single value.
+ *
+ * @param subject a resource
+ * @param relation a resource
+ * @return the value
+ * @throws NoSingleResultException if the amount of valid values was not one
+ * @throws DoesNotContainValueException if suitable o did not contain a
+ * resource
+ * @throws BindingException if value could not be produced using the given
+ * {@link Binding}
+ * @throws ServiceException on connection and database failure
+ * @see AsyncReadGraph#forRelatedValue
+ */
+ T getRelatedValue(Resource subject, Resource relation, Binding binding) throws NoSingleResultException,
+ DoesNotContainValueException, BindingException, ServiceException;
+
+ /**
+ * Tries to adapt the specified resource into an instance of the specified
+ * class T. No guarantees are made on return values of this method. The
+ * returned values can be cached results of previous invocation or they can
+ * be new result object instances. See {@link #adaptUnique(Resource, Class)}
+ * for alternative behaviour.
+ *
+ * @param resource a resource
+ * @param clazz the adapter class
+ * @return
+ * @throws AdaptionException if suitable adapter was not found
+ * @throws ValidationException from the adapter
+ * @throws ServiceException on connection and database failure
+ * @see AsyncReadGraph#forAdapted
+ * @see #adaptUnique(Resource, Class)
+ */
+ T adapt(Resource resource, Class clazz) throws AdaptionException, ValidationException, ServiceException;
+
+ /**
+ *
+ * Same as: adapt(getSingleObject(resource, relation), clazz);
+ *
+ * @param resource a resource
+ * @param relation a resource
+ * @param clazz the adapter class
+ * @return
+ * @throws AdaptionException if suitable adapter was not found
+ * @throws ValidationException from the adapter
+ * @throws ServiceException on connection and database failure
+ * @see AsyncReadGraph#forAdapted
+ * @see #adaptUnique(Resource, Class)
+ */
+ T adaptRelated(Resource resource, Resource relation, Class clazz) throws AdaptionException, NoSingleResultException, ValidationException, ServiceException;
+
+ /**
+ *
+ * Same as:
+ *
+ * Resource r = getPossibleObject(resource, relation);
+ * if(r == null) return null;
+ * return getPossibleAdapter(r, clazz);
+ *
+ * @param resource a resource
+ * @param relation a resource
+ * @param clazz the adapter class
+ * @return
+ * @throws AdaptionException if suitable adapter was not found
+ * @throws ValidationException from the adapter
+ * @throws ServiceException on connection and database failure
+ * @see AsyncReadGraph#forAdapted
+ * @see #adaptUnique(Resource, Class)
+ */
+ T getPossibleRelatedAdapter(Resource resource, Resource relation, Class clazz) throws ValidationException, ServiceException;
+
+ T adaptContextual(Resource resource, C context, Class contextClass, Class clazz) throws AdaptionException, NoSingleResultException, ValidationException, ServiceException;
+ T getPossibleContextualAdapter(Resource resource, C context, Class contextClass, Class clazz) throws ValidationException, ServiceException;
+
+ /**
+ * Tries to adapt the specified resource into an instance of the specified
+ * class T. The difference to {@link #adapt(Resource, Class)} is that this
+ * method does everything possible to return a new object instance for each
+ * separate invocation.
+ *
+ *
+ * The only case when this cannot be guaranteed is when the adaption result
+ * comes from an {@link Adapter} implementation which can internally do
+ * anything, like always return the same singleton instance.
+ *
+ *
+ * @param resource a resource
+ * @param clazz the adapter class
+ * @return
+ * @throws AdaptionException if suitable adapter was not found
+ * @throws ValidationException from the adapter
+ * @throws ServiceException on connection and database failure
+ * @see AsyncReadGraph#forAdapted
+ * @see #adapt(Resource, Class)
+ */
+ T adaptUnique(Resource resource, Class clazz) throws AdaptionException, ValidationException,
+ ServiceException;
+
+ /**
+ * As {@link #getInverse} but returns null instead of an exception if
+ * inverse was not found.
+ *
+ * @param relation a resource
+ * @return the inverse or null
+ * @throws ManyObjectsForFunctionalRelationException on invalid graph with
+ * more than one functional object
+ * @throws ServiceException on connection and database failures
+ * @see AsyncReadGraph#forPossibleInverse
+ */
+ Resource getPossibleInverse(Resource relation) throws ManyObjectsForFunctionalRelationException, ServiceException;
+
+ /**
+ * As {@link #getSingleObject} but returns null instead of an exception if
+ * object was not found.
+ *
+ * @param subject a resource
+ * @param relation a resource
+ * @return the object or null
+ * @throws ManyObjectsForFunctionalRelationException on invalid graph with
+ * more than one functional object
+ * @throws ServiceException on connection and database failures
+ * @see AsyncReadGraph#forPossibleObject
+ */
+ Resource getPossibleObject(Resource subject, Resource relation) throws ManyObjectsForFunctionalRelationException,
+ ServiceException;
+
+ /**
+ * As {@link #getSingleStatement} but returns null instead of an exception
+ * if statement was not found.
+ *
+ * @param subject a resource
+ * @param relation a resource
+ * @return the statement or null
+ * @throws ManyObjectsForFunctionalRelationException on invalid graph with
+ * more than one functional object
+ * @throws ServiceException on connection and database failures
+ * @see AsyncReadGraph#forPossibleStatement
+ */
+ Statement getPossibleStatement(Resource subject, Resource relation)
+ throws ManyObjectsForFunctionalRelationException, ServiceException;
+
+ /**
+ * As {@link #getSingleType} but returns null instead of an exception if
+ * type was not found.
+ *
+ * @param subject a resource
+ * @param baseType a resource
+ * @return the type or null
+ * @throws ServiceException on connection and database failures
+ * @see AsyncReadGraph#forPossibleType
+ */
+ Resource getPossibleType(Resource subject, Resource baseType) throws ServiceException;
+
+ /**
+ * As {@link #getValue} but returns null instead of an exception if value
+ * was not found.
+ *
+ * @param subject a resource
+ * @return the value or null
+ * @throws ServiceException on connection and database failures
+ * @see AsyncReadGraph#forPossibleValue
+ */
+ T getPossibleValue(Resource subject) throws ServiceException;
+
+ /**
+ * As {@link #getValue} but returns null instead of an exception if value
+ * was not found.
+ *
+ * @param subject a resource
+ * @param binding a {@link Binding}
+ * @return the value or null
+ * @throws BindingException if value could not be produced using the given
+ * {@link Binding}
+ * @throws ServiceException on connection and database failures
+ * @see AsyncReadGraph#forPossibleValue
+ */
+ T getPossibleValue(Resource subject, Binding binding) throws BindingException, ServiceException;
+
+ /**
+ * As {@link #getPossibleRelatedValue} but returns null instead of an
+ * exception if value was not found.
+ *
+ * @param subject a resource
+ * @param relation a resource
+ * @return the value or null
+ * @throws ManyObjectsForFunctionalRelationException on invalid graph with
+ * more than one functional object
+ * @throws ServiceException on connection and database failures
+ * @see AsyncReadGraph#forPossibleRelatedValue
+ */
+ T getPossibleRelatedValue(Resource subject, Resource relation)
+ throws ManyObjectsForFunctionalRelationException, ServiceException;
+
+ /**
+ * As {@link #getPossibleRelatedValue} but returns null instead of an
+ * exception if value was not found.
+ *
+ * @param subject a resource
+ * @param relation a resource
+ * @param binding a {@link Binding}
+ * @return the value or null
+ * @throws ManyObjectsForFunctionalRelationException on invalid graph with
+ * more than one functional object
+ * @throws BindingException if value could not be produced using the given
+ * {@link Binding}
+ * @throws ServiceException on connection and database failures
+ * @see AsyncReadGraph#forPossibleRelatedValue
+ */
+ T getPossibleRelatedValue(Resource subject, Resource relation, Binding binding)
+ throws ManyObjectsForFunctionalRelationException, BindingException, ServiceException;
+
+ /**
+ * As {@link #adapt} but returns null instead of an exception if adapter was
+ * not found
+ *
+ * @param subject a resource
+ * @param clazz a Class
+ * @return the adapter or null
+ * @throws ValidationException when ?
+ * @throws ServiceException on connection and database failures
+ * @see {@link AsyncReadGraph#forPossibleAdapted}
+ */
+ T getPossibleAdapter(Resource resource, Class clazz) throws ValidationException, ServiceException;
+
+ /**
+ * As {@link #adaptUnique} but returns null instead of an exception if
+ * adapter was not found
+ *
+ * @param subject a resource
+ * @param clazz a Class
+ * @return the adapter or null
+ * @throws ValidationException when ?
+ * @throws ServiceException on connection and database failures
+ * @see {@link AsyncReadGraph#forPossibleAdapted}
+ */
+ T getPossibleUniqueAdapter(Resource resource, Class clazz) throws ValidationException, ServiceException;
+
+ /**
+ * Returns true if type is included in the result of {@link #getTypes(resource)}
+ *
+ * @param subject a resource
+ * @param type a resource
+ * @return indicates if resource is an instance of type
+ * @throws ServiceException on connection and database failures
+ * @see {@link AsyncReadGraph#forIsInstanceOf}
+ */
+ boolean isInstanceOf(Resource resource, Resource type) throws ServiceException;
+
+ /**
+ * Returns true if type equals resource or type is included in the result of
+ * {@link #getSupertypes(resource)}
+ *
+ * @param subject a resource
+ * @param type a resource
+ * @return indicates if resource is inherited from type
+ * @throws ServiceException on connection and database failures
+ * @see {@link AsyncReadGraph#forIsInheritedFrom}
+ */
+ boolean isInheritedFrom(Resource resource, Resource type) throws ServiceException;
+
+ /**
+ * Returns true if relation equals resource or relation is included in the result of
+ * {@link #getSuperrelations(resource)}
+ *
+ * @param subject a resource
+ * @param relation a resource
+ * @return indicates if resource is a subrelation of relation
+ * @throws ServiceException on connection and database failures
+ * @see {@link AsyncReadGraph#forIsSubrelationOf}
+ */
+ boolean isSubrelationOf(Resource resource, Resource relation) throws ServiceException;
+
+ /**
+ * Returns true if the result of {@link #getStatements(subject, IsWeaklyRelatedTo)} is nonempty.
+ *
+ * @param subject a resource
+ * @return indicates that subject has statements
+ * @throws ServiceException on connection and database failures
+ * @see {@link AsyncReadGraph#forHasStatement}
+ */
+ boolean hasStatement(Resource subject) throws ServiceException;
+
+ /**
+ * Returns true if the result of {@link #getStatements(subject, relation)} is nonempty.
+ *
+ * @param subject a resource
+ * @param relation a resource
+ * @return indicates that subject has statements with predicates as subrelation of relation
+ * @throws ServiceException on connection and database failures
+ * @see {@link AsyncReadGraph#forHasStatement}
+ */
+ boolean hasStatement(Resource subject, Resource relation) throws ServiceException;
+
+ /**
+ * Returns true if a statement (subject, relation, object) exists after assertions.
+ *
+ * @param subject a resource
+ * @param relation a resource
+ * @param object a resource
+ * @return indicates that the given statement exists
+ * @throws ServiceException on connection and database failures
+ * @see {@link AsyncReadGraph#forHasStatement}
+ */
+ boolean hasStatement(Resource subject, Resource relation, Resource object) throws ServiceException;
+
+ /**
+ * Returns true if there is a value associated with subject.
+ * IMPLEMENTATION NOTE:
+ * Current implementation fetches the value from server. If the value is
+ * large (i.e. not stored in the cluster) this is highly inefficient.
+ *
+ * @param subject a resource
+ * @return indicates that a value exists
+ * @throws ServiceException on connection and database failures
+ * @see {@link AsyncReadGraph#forHasValue}
+ */
+ boolean hasValue(Resource subject) throws ServiceException;
+
+ /**
+ * Returns the data type of the literal.
+ * @param subject
+ * @return
+ * @throws DatabaseException
+ */
+ Datatype getDataType(Resource subject) throws DatabaseException;
+
+ /**
+ * Returns an accessory that can be used to partially read the literal
+ * or write if the graph is WriteGraph. The returned accessory is closed
+ * automatically when the transaction ends. The modifications are written
+ * back to graph at transaction completion.
+ *
+ * @param is typed accessory for modifying the literal value.
+ * @param resource is the literal containing the value.
+ * @return interface to partially read and write the literal value.
+ * @throws DatabaseException
+ */
+ T getAccessor(Resource resource) throws DatabaseException;
+
+ /**
+ * Returns an RandomAccessBinary that can be used to partially read the literal
+ * or write if the graph is WriteGraph. The returned interface is closed
+ * automatically when the transaction ends. The modifications are written
+ * back to graph at transaction completion.
+ *
+ * @param
+ * @param resource is the literal containing the value.
+ * @return interface to partially read and write the literal value.
+ * @throws DatabaseException
+ */
+ RandomAccessBinary getRandomAccessBinary(Resource resource) throws DatabaseException;
+// @SuppressWarnings("rawtypes")
+// Function getValueFunction(Resource resource) throws DatabaseException;
+
+ /**
+ * Get the value associated with a graph {@link Resource}, using a possible context object and
+ * a default data type binding. An exception is thrown, if the value is not found.
+ *
+ * See {@link #getValue2(Resource, Object, Binding)} for more details.
+ *
+ * @param r A graph resource with which the value is associated
+ * @param context A context object that is used for acquiring the value, can be {@code null}
+ * @return The value of the graph node.
+ * @throws DoesNotContainValueException No value is associated with the graph node.
+ * @throws DatabaseException Other errors, such as an error in casting the value to the return type or
+ * a runtime error in the value function.
+ * @see #getValue2(Resource, Object, Binding)
+ * @see #getPossibleValue2(Resource, Object)
+ */
+ T getValue2(Resource subject, Object context) throws DatabaseException;
+
+ /**
+ * Get the value associated with a graph {@link Resource}, using a possible context object and
+ * a default data type binding as a Variant. An exception is thrown, if the value is not found.
+ *
+ * See {@link #getValue2(Resource, Object, Binding)} for more details.
+ *
+ * @param r A graph resource with which the value is associated
+ * @param context A context object that is used for acquiring the value, can be {@code null}
+ * @return The value of the graph node.
+ * @throws DoesNotContainValueException No value is associated with the graph node.
+ * @throws DatabaseException Other errors, such as an error in casting the value to the return type or
+ * a runtime error in the value function.
+ * @see #getValue2(Resource, Object, Binding)
+ * @see #getPossibleValue2(Resource, Object)
+ */
+ Variant getVariantValue2( Resource r, Object context ) throws DatabaseException;
+
+ /**
+ * Get a possible value associated with a graph {@link Resource}, using a possible context object and
+ * a desired value binding. Unlike {@link #getValue2(Resource, Object)}, this methods
+ * returns {@code null} for missing values instead of throwing an exception.
+ *
+ * See {@link #getValue2(Resource, Object, Binding)} for more details.
+ *
+ * @param r A graph resource with which the value is associated
+ * @param context A context object that is used for acquiring the value, can be {@code null}
+ * @return The value of the graph node.
+ * @throws DatabaseException Usually should not happen. A null value is returned for possible errors.
+ * @see #getValue2(Resource, Object)
+ * @see #getPossibleValue2(Resource, Object, Binding)
+ */
+ T getPossibleValue2(Resource subject, Object context) throws DatabaseException;
+
+ /**
+ * Get the value associated with a graph {@link Resource}, using a possible context object and
+ * a desired value binding. An exception is thrown, if the value is not found.
+ *
+ * The following methods are tried in order to retrieve the value:
+ *
+ * - If the given resource is a {@code L0.Literal}, the value of the literal is returned, using the binding specified by {@code binding}.
+ * - If the resource is a {@code L0.ExternalValue}, the value is acquired using
+ * {@link ReflectionUtils#getValue(String)} with the resource URI.
+ * - If the resource is associated with a suitable value converter with relation {@code L0.ConvertsToValueWith}
+ * (see {@link #requestValueFunction(Resource)}), the value function is called with the graph, the resource
+ * and the context object.
+ *
+ *
+ * @param r A graph resource with which the value is associated
+ * @param context A context object that is used for acquiring the value, can be {@code null}
+ * @param binding A binding for the value type
+ * @return The value of the graph node.
+ * @throws DoesNotContainValueException No value is associated with the graph node.
+ * @throws DatabaseException Other errors, such as an error in casting the value to the return type or
+ * a runtime error in the value function.
+ * @see #getValue2(Resource, Object)
+ * @see #getPossibleValue2(Resource, Object, Binding)
+ */
+ T getValue2(Resource subject, Object context, Binding binding) throws DatabaseException;
+
+ /**
+ * Get a possible value associated with a graph {@link Resource}, using a possible context object and
+ * a desired value binding. Unlike {@link #getValue2(Resource, Object, Binding)}, this methods
+ * returns {@code null} for missing values instead of throwing an exception.
+ *
+ * See {@link #getValue2(Resource, Object, Binding)} for more details.
+ *
+ * @param r A graph resource with which the value is associated
+ * @param context A context object that is used for acquiring the value, can be {@code null}
+ * @param binding A binding for the value type
+ * @return The value of the graph node.
+ * @throws DatabaseException Usually should not happen. A null value is returned for possible errors.
+ * @see #getValue2(Resource, Object, Bindinge)
+ * @see #getPossibleValue2(Resource, Object)
+ */
+ T getPossibleValue2(Resource subject, Object context, Binding binding) throws DatabaseException;
+
+ /**
+ * Get the single value associated with a graph resource related with a given subject.
+ * An exception is thrown, if a unique object resource or a value for it is not found.
+ *
+ * See {@link #getValue2(Resource, Object, Binding)} for more details.
+ *
+ * @param subject A graph resource that indicates the subject node
+ * @param relation A graph resource that indicates the predicate of a relation
+ * @return The value of the unique graph node that is asserted as the object of the given subject and predicate.
+ * @throws NoSingleResultException The number of suitable object resources is not equal to 1 (zero or greater than one)
+ * @throws DoesNotContainValueException No value is associated with the graph node.
+ * @throws DatabaseException Other errors, such as an error in casting the value to the return type or
+ * a runtime error in the value function.
+ * @see #getRelatedValue2(Resource, Resource, Binding)
+ * @see #getRelatedValue2(Resource, Resource, Object)
+ * @see #getRelatedValue2(Resource, Resource, Object, Binding)
+ * @see #getPossibleRelatedValue2(Resource, Resource)
+ */
+ T getRelatedValue2(Resource subject, Resource relation) throws DatabaseException;
+
+ /**
+ * Get a possible single value associated with a graph resource related with a given subject.
+ * A {@code null} value is returned for missing values or other errors.
+ *
+ * See {@link #getValue2(Resource, Object, Binding)} for more details.
+ *
+ * @param subject A graph resource that indicates the subject node
+ * @param relation A graph resource that indicates the predicate of a relation
+ * @return The value of the unique graph node that is asserted as the object of the given subject and predicate.
+ * @throws DatabaseException Usually should not happen. A {@code null} value is returned for possible errors.
+ * @see #getPossibleRelatedValue2(Resource, Resource, Binding)
+ * @see #getPossibleRelatedValue2(Resource, Resource, Object)
+ * @see #getPossibleRelatedValue2(Resource, Resource, Object, Binding)
+ * @see #getRelatedValue2(Resource, Resource)
+ */
+ T getPossibleRelatedValue2(Resource subject, Resource relation) throws DatabaseException;
+
+ /**
+ * Get a possible single value associated with a graph resource related with a given subject.
+ * A {@code null} value is returned for missing values or other errors.
+ *
+ * See {@link #getValue2(Resource, Object, Binding)} for more details.
+ *
+ * @param subject A graph resource that indicates the subject node
+ * @param relation A graph resource that indicates the predicate of a relation
+ * @return The value of the unique graph node that is asserted as the object of the given subject and predicate.
+ * @throws DatabaseException Usually should not happen. A {@code null} value is returned for possible errors.
+ * @see #getPossibleRelatedValue2(Resource, Resource, Binding)
+ * @see #getPossibleRelatedValue2(Resource, Resource, Object)
+ * @see #getPossibleRelatedValue2(Resource, Resource, Object, Binding)
+ * @see #getRelatedValue2(Resource, Resource)
+ */
+ Variant getRelatedVariantValue2( Resource subject, Resource relation ) throws DatabaseException;
+
+ /**
+ * Get the single value associated with a graph resource related with a given subject, a possible context object.
+ * An exception is thrown, if a unique object resource or a value for it is not found.
+ *
+ * See {@link #getValue2(Resource, Object, Binding)} for more details.
+ *
+ * @param subject A graph resource that indicates the subject node
+ * @param relation A graph resource that indicates the predicate of a relation
+ * @param context A context object that is used for acquiring the value, can be {@code null}
+ * @return The value of the unique graph node that is asserted as the object of the given subject and predicate.
+ * @throws NoSingleResultException The number of suitable object resources is not equal to 1 (zero or greater than one)
+ * @throws DoesNotContainValueException No value is associated with the graph node.
+ * @throws DatabaseException Other errors, such as an error in casting the value to the return type or
+ * a runtime error in the value function.
+ * @see #getRelatedValue2(Resource, Resource)
+ * @see #getRelatedValue2(Resource, Resource, Binding)
+ * @see #getRelatedValue2(Resource, Resource, Object, Binding)
+ * @see #getPossibleRelatedValue2(Resource, Resource, Object)
+ */
+ T getRelatedValue2(Resource subject, Resource relation, Object context) throws DatabaseException;
+
+ /**
+ * Get the single value associated with a graph resource related with a given subject, a possible context object.
+ * An exception is thrown, if a unique object resource or a value for it is not found.
+ *
+ * See {@link #getValue2(Resource, Object, Binding)} for more details.
+ *
+ * @param subject A graph resource that indicates the subject node
+ * @param relation A graph resource that indicates the predicate of a relation
+ * @param context A context object that is used for acquiring the value, can be {@code null}
+ * @return The value of the unique graph node that is asserted as the object of the given subject and predicate.
+ * @throws NoSingleResultException The number of suitable object resources is not equal to 1 (zero or greater than one)
+ * @throws DoesNotContainValueException No value is associated with the graph node.
+ * @throws DatabaseException Other errors, such as an error in casting the value to the return type or
+ * a runtime error in the value function.
+ * @see #getRelatedValue2(Resource, Resource, Object)
+ * @see #getPossibleRelatedValue2(Resource, Resource, Object)
+ */
+ Variant getRelatedVariantValue2( Resource subject, Resource relation, Object context ) throws DatabaseException;
+
+ /**
+ * Get a possible single value associated with a graph resource related with a given subject and a possible context object.
+ * A {@code null} value is returned for missing values or other errors.
+ *
+ * See {@link #getValue2(Resource, Object, Binding)} for more details.
+ *
+ * @param subject A graph resource that indicates the subject node
+ * @param relation A graph resource that indicates the predicate of a relation
+ * @param context A context object that is used for acquiring the value, can be {@code null}
+ * @return The value of the unique graph node that is asserted as the object of the given subject and predicate.
+ * @throws DatabaseException Usually should not happen. A {@code null} value is returned for possible errors.
+ * @see #getPossibleRelatedValue2(Resource, Resource)
+ * @see #getPossibleRelatedValue2(Resource, Resource, Binding)
+ * @see #getPossibleRelatedValue2(Resource, Resource, Object, Binding)
+ * @see #getRelatedValue2(Resource, Resource, Object)
+ */
+ T getPossibleRelatedValue2(Resource subject, Resource relation, Object context) throws DatabaseException;
+
+ /**
+ * Get the single value associated with a graph resource related with a given subject and
+ * a desired value binding. An exception is thrown, if a unique object resource or a value for it is not found.
+ *
+ * See {@link #getValue2(Resource, Object, Binding)} for more details.
+ *
+ * @param subject A graph resource that indicates the subject node
+ * @param relation A graph resource that indicates the predicate of a relation
+ * @param binding A binding for the value type
+ * @return The value of the unique graph node that is asserted as the object of the given subject and predicate.
+ * @throws NoSingleResultException The number of suitable object resources is not equal to 1 (zero or greater than one)
+ * @throws DoesNotContainValueException No value is associated with the graph node.
+ * @throws DatabaseException Other errors, such as an error in casting the value to the return type or
+ * a runtime error in the value function.
+ * @see #getRelatedValue2(Resource, Resource)
+ * @see #getRelatedValue2(Resource, Resource, Object)
+ * @see #getRelatedValue2(Resource, Resource, Object, Binding)
+ * @see #getPossibleRelatedValue2(Resource, Resource, Binding)
+ */
+ T getRelatedValue2(Resource subject, Resource relation, Binding binding) throws DatabaseException;
+
+ /**
+ * Get a possible single value associated with a graph resource related with a given subject and
+ * a desired value binding. A {@code null} value is returned for missing values or other errors.
+ *
+ * See {@link #getValue2(Resource, Object, Binding)} for more details.
+ *
+ * @param subject A graph resource that indicates the subject node
+ * @param relation A graph resource that indicates the predicate of a relation
+ * @param binding A binding for the value type
+ * @return The value of the unique graph node that is asserted as the object of the given subject and predicate.
+ * @throws DatabaseException Usually should not happen. A {@code null} value is returned for possible errors.
+ * @see #getPossibleRelatedValue2(Resource, Resource)
+ * @see #getPossibleRelatedValue2(Resource, Resource, Object)
+ * @see #getPossibleRelatedValue2(Resource, Resource, Object, Binding)
+ * @see #getRelatedValue2(Resource, Resource, Binding)
+ */
+ T getPossibleRelatedValue2(Resource subject, Resource relation, Binding binding) throws DatabaseException;
+
+ /**
+ * Get the single value associated with a graph resource related with a given subject, a possible context object and
+ * a desired value binding. An exception is thrown, if a unique object resource or a value for it is not found.
+ *
+ * See {@link #getValue2(Resource, Object, Binding)} for more details.
+ *
+ * @param subject A graph resource that indicates the subject node
+ * @param relation A graph resource that indicates the predicate of a relation
+ * @param context A context object that is used for acquiring the value, can be {@code null}
+ * @param binding A binding for the value type
+ * @return The value of the unique graph node that is asserted as the object of the given subject and predicate.
+ * @throws NoSingleResultException The number of suitable object resources is not equal to 1 (zero or greater than one)
+ * @throws DoesNotContainValueException No value is associated with the graph node.
+ * @throws DatabaseException Other errors, such as an error in casting the value to the return type or
+ * a runtime error in the value function.
+ * @see #getRelatedValue2(Resource, Resource)
+ * @see #getRelatedValue2(Resource, Resource, Binding)
+ * @see #getRelatedValue2(Resource, Resource, Object)
+ * @see #getPossibleRelatedValue2(Resource, Resource, Object, Binding)
+ */
+ T getRelatedValue2(Resource subject, Resource relation, Object context, Binding binding) throws DatabaseException;
+
+ /**
+ * Get a possible single value associated with a graph resource related with a given subject, a possible context object and
+ * a desired value binding. A {@code null} value is returned for missing values or other errors.
+ *
+ * See {@link #getValue2(Resource, Object, Binding)} for more details.
+ *
+ * @param subject A graph resource that indicates the subject node
+ * @param relation A graph resource that indicates the predicate of a relation
+ * @param context A context object that is used for acquiring the value, can be {@code null}
+ * @param binding A binding for the value type
+ * @return The value of the unique graph node that is asserted as the object of the given subject and predicate.
+ * @throws DatabaseException Usually should not happen. A {@code null} value is returned for possible errors.
+ * @see #getPossibleRelatedValue2(Resource, Resource)
+ * @see #getPossibleRelatedValue2(Resource, Resource, Binding)
+ * @see #getPossibleRelatedValue2(Resource, Resource, Object)
+ * @see #getRelatedValue2(Resource, Resource, Object, Binding)
+ */
+ T getPossibleRelatedValue2(Resource subject, Resource relation, Object context, Binding binding) throws DatabaseException;
+
+ /**
+ * Get the parsed SCL type declaration from the string value of a graph resource that is the unique object of a
+ * given subject and predicate.
+ *
+ * See {@link #getValue2(Resource, Object, Binding)} for more details.
+ *
+ * @param subject A resource that indicates the subject of a statement
+ * @param relation A resource that indicates the predicate of the statement
+ * @return A compiled SCL type definition of the string value of a unique object resource
+ * @throws DatabaseException For any errors in locating a unique value or compiling it as an SCL type statement
+ */
+ Type getRelatedValueType(Resource subject, Resource relation) throws DatabaseException;
+
+ boolean setSynchronous(boolean value);
+ boolean getSynchronous();
+}