X-Git-Url: https://gerrit.simantics.org/r/gitweb?a=blobdiff_plain;f=bundles%2Forg.simantics.db%2Fsrc%2Forg%2Fsimantics%2Fdb%2FReadGraph.java;h=36081c3a802276bd8ec81f7a974b9b9617d90958;hb=e460fd6f0af60314e2ca28391ef7ff2043016d97;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..36081c3a8 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,1091 @@ -/******************************************************************************* - * 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: - *

    - *
  1. If the given resource is a {@code L0.Literal}, the value of the literal is returned, using the binding specified by {@code binding}.
    2. - *
  2. If the resource is a {@code L0.ExternalValue}, the value is acquired using - * {@link ReflectionUtils#getValue(String)} with the resource URI.
    3. - *
  3. 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.
    4. - * - * - * @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, 2018 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.Map; +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.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 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; + + /** + * Computes a map of objects related to resource with L0.ConsistsOf that also contain a L0.HasName property + * + * @param resource the resource + * @return the children + * @throws ValidationException if a resource could not be produced due to + * invalid semantics + * @throws ServiceException on connection and database failures + * @see AsyncReadGraph#forResourceByURI + */ + Map getChildren(Resource resource) throws 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: + *

      + *
    1. If the given resource is a {@code L0.Literal}, the value of the literal is returned, using the binding specified by {@code binding}.
      2. + *
    2. If the resource is a {@code L0.ExternalValue}, the value is acquired using + * {@link ReflectionUtils#getValue(String)} with the resource URI.
      3. + *
    3. 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.
      4. + * + * + * @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(); + + boolean isImmutable(Resource resource) throws DatabaseException; + + int thread(); + +}