1 /*******************************************************************************
2 * Copyright (c) 2007, 2018 Association for Decentralized Information Management
4 * All rights reserved. This program and the accompanying materials
5 * are made available under the terms of the Eclipse Public License v1.0
6 * which accompanies this distribution, and is available at
7 * http://www.eclipse.org/legal/epl-v10.html
10 * VTT Technical Research Centre of Finland - initial API and implementation
11 *******************************************************************************/
12 package org.simantics.db;
14 import java.util.Collection;
18 import org.simantics.databoard.accessor.Accessor;
19 import org.simantics.databoard.binding.Binding;
20 import org.simantics.databoard.binding.mutable.Variant;
21 import org.simantics.databoard.type.Datatype;
22 import org.simantics.databoard.util.binary.RandomAccessBinary;
23 import org.simantics.db.adaption.Adapter;
24 import org.simantics.db.exception.AdaptionException;
25 import org.simantics.db.exception.AssumptionException;
26 import org.simantics.db.exception.BindingException;
27 import org.simantics.db.exception.DatabaseException;
28 import org.simantics.db.exception.DoesNotContainValueException;
29 import org.simantics.db.exception.ManyObjectsForFunctionalRelationException;
30 import org.simantics.db.exception.NoInverseException;
31 import org.simantics.db.exception.NoSingleResultException;
32 import org.simantics.db.exception.ResourceNotFoundException;
33 import org.simantics.db.exception.ServiceException;
34 import org.simantics.db.exception.ValidationException;
35 import org.simantics.db.procedure.SyncListener;
36 import org.simantics.db.procedure.SyncMultiListener;
37 import org.simantics.db.procedure.SyncMultiProcedure;
38 import org.simantics.db.procedure.SyncProcedure;
39 import org.simantics.db.procedure.SyncSetListener;
40 import org.simantics.db.request.Read;
41 import org.simantics.scl.compiler.types.Type;
45 * For accessing and manipulating the graph data in synchronous manner. A client
46 * receives ReadGraph instances for performing requests in {@link Read} and
47 * {@link MultiRead} as well as for reacting to request results using
48 * {@link SyncProcedure}, {@link SyncListener}, {@link SyncMultiProcedure},
49 * {@link SyncMultiListener} and {@link SyncSetListener}
51 * ReadGraph instances are stateful and may not be stored and used outside the
52 * supplier method activation. The methods receiving ReadGraph should not block
53 * for long periods of time since that may delay the processing of other
54 * requests. For an asynchronous counterpart with the same functionality as
55 * ReadGraph see {@link AsyncReadGraph}
58 * All collections returned by the methods on this interface must not be
59 * modified by clients unless explicitly stated otherwise.
62 * @author Antti Villberg
63 * @see RequestProcessor
64 * @see AsyncRequestProcessor
70 public interface ReadGraph extends RequestProcessor {
74 * @see AsyncReadGraph#forURI
76 String getURI(Resource resource) throws AssumptionException, ValidationException, ServiceException;
77 String getPossibleURI(Resource resource) throws ValidationException, ServiceException;
80 * Gets a unique resource associated to the given identifier. See <a
81 * href="https://www.simantics.org/wiki/index.php/URI">Simantics Wiki page
82 * on URIs</a> for more details.
84 * @param uri the identifier
85 * @return the resource
86 * @throws ResourceNotFoundException if a resource for the given identifier
88 * @throws ValidationException if a resource could not be produced due to
90 * @throws ServiceException on connection and database failures
91 * @see AsyncReadGraph#forResourceByURI
93 Resource getResource(String uri) throws ResourceNotFoundException, ValidationException, ServiceException;
96 * Gets a unique resource associated to the given identifier. See <a
97 * href="https://www.simantics.org/wiki/index.php/URI">Simantics Wiki page
98 * on URIs</a> for more details.
100 * @param uri the identifier
101 * @return the resource
102 * @throws ResourceNotFoundException if a resource for the given identifier
104 * @throws ValidationException if a resource could not be produced due to
106 * @throws ServiceException on connection and database failures
107 * @see AsyncReadGraph#forResourceByURI
109 Resource getPossibleResource(String uri) throws ResourceNotFoundException, ValidationException, ServiceException;
112 * Computes a map of objects related to resource with L0.ConsistsOf that also contain a L0.HasName property
114 * @param resource the resource
115 * @return the children
116 * @throws ValidationException if a resource could not be produced due to
118 * @throws ServiceException on connection and database failures
119 * @see AsyncReadGraph#forResourceByURI
121 Map<String,Resource> getChildren(Resource resource) throws ValidationException, ServiceException;
124 * Gets a builtin resource. For a list of builtin resources see TODO Wiki
126 * @param uri the identifier
127 * @return the resource
128 * @throws ResourceNotFoundException if resouce was not found
129 * @throws ServiceException on connection and database failures
130 * @see AsyncReadGraph#forBuiltin
132 Resource getBuiltin(String id) throws ResourceNotFoundException, ServiceException;
135 * Gets all statements (subject, p, o) such that
136 * {@link ReadGraph#isSubrelationOf(p, relation)} returns true. The result
137 * may include asserted statements for which s does not equal subject. See
138 * the assertion mechanisn TODO for more details. If the relation is
139 * functional the request returns a single statement according to the
140 * functional statement shadowing rules TODO if possible. If an invalid
141 * graph is encountered an exception is thrown.
143 * @param subject a resource
144 * @param relation a resource
145 * @return the statements
146 * @throws ManyObjectsForFunctionalRelationException on invalid graph with
147 * more than one functional object
148 * @throws ServiceException on connection and database failures
149 * @see AsyncReadGraph#forEachStatement
150 * @see AsyncReadGraph#forStatementSet
152 Collection<Statement> getStatements(Resource subject, Resource relation)
153 throws ManyObjectsForFunctionalRelationException, ServiceException;
156 * Gets all statements (s, p, o) asserted by subject such that
157 * {@link ReadGraph#isSubrelationOf(p, relation)} returns true. See the
158 * assertion mechanism TODO for more details. If the relation is functional
159 * the request returns a single statement according to the functional
160 * statement shadowing rules TODO if possible. If an invalid graph is
161 * encountered an exception is thrown.
163 * @param subject a resource
164 * @param relation a resource
165 * @return the statements
166 * @throws ManyObjectsForFunctionalRelationException on invalid graph with
167 * more than one functional object
168 * @throws ServiceException on connection and database failures
169 * @see AsyncReadGraph#forEachAssertedStatement
170 * @see AsyncReadGraph#forAssertedStatementSet
172 Collection<Statement> getAssertedStatements(Resource subject, Resource relation)
173 throws ManyObjectsForFunctionalRelationException, ServiceException;
176 * Gets all predicates p from statements (subject, p, o) such that
177 * {@link ReadGraph#isSubrelationOf(p, relation)} returns true. See the
178 * assertion mechanism TODO for more details. If the relation is functional
179 * the request returns a single statement according to the functional
180 * statement shadowing rules TODO if possible. If an invalid graph is
181 * encountered an exception is thrown.
183 * @param subject a resource
184 * @param relation a resource
185 * @return the predicates
186 * @throws ManyObjectsForFunctionalRelationException on invalid graph with
187 * more than one object
188 * @throws ServiceException on connection and database failures
189 * @see AsyncReadGraph#forEachPredicate
190 * @see AsyncReadGraph#forPredicateSet
192 Collection<Resource> getPredicates(Resource subject) throws ServiceException;
195 * Gets a subset of all types of the subject such that no pair of returned
196 * types inherit each other and all types of the subject are supertypes
197 * of some type in the returned set.
199 * @param subject a resource
200 * @return the principal types
201 * @throws ServiceException on connection and database failures
202 * @see AsyncReadGraph#forEachPrincipalType
203 * @see AsyncReadGraph#forPrincipalTypeSet
205 Collection<Resource> getPrincipalTypes(Resource subject) throws ServiceException;
208 * Gets the full type hierarchy for subject.
210 * @param subject a resource
211 * @return the type hierarchy
212 * @throws ServiceException on connection and database failures
213 * @see AsyncReadGraph#forTypes
215 Set<Resource> getTypes(Resource subject) throws ServiceException;
218 * Gets the full supertype hierarchy for subject.
220 * @param subject a resource
221 * @return the supertype hierarchy
222 * @throws ServiceException on connection and database failures
223 * @see AsyncReadGraph#forSupertypes
225 Set<Resource> getSupertypes(Resource subject) throws ServiceException;
228 * Gets the full superrelation hierarchy for subject.
230 * @param subject a resource
231 * @return the superrelation hierarchy
232 * @throws ServiceException on connection and database failures
233 * @see AsyncReadGraph#forSuperrelations
235 Set<Resource> getSuperrelations(Resource subject) throws ServiceException;
236 Resource getPossibleSuperrelation(Resource subject) throws ServiceException;
239 * Gets all objects o from statements (subject, p, o) such that
240 * {@link ReadGraph#isSubrelationOf(p, relation)} returns true. See the
241 * assertion mechanisn TODO for more details. If the relation is functional
242 * the request returns a single object according to the functional statement
243 * shadowing rules TODO if possible. If an invalid graph is encountered an
244 * exception is thrown.
246 * @param subject a resource
247 * @param relation a resource
248 * @return the objects
249 * @throws ManyObjectsForFunctionalRelationException on invalid graph with
250 * more than one functional object
251 * @throws ServiceException on connection and database failures
252 * @see AsyncReadGraph#forEachObject
253 * @see AsyncReadGraph#forObjectSet
255 Collection<Resource> getObjects(Resource subject, Resource relation)
256 throws ServiceException;
259 * Gets all objects o (s, p, o) asserted by subject such that
260 * {@link ReadGraph#isSubrelationOf(p, relation)} returns true. See the
261 * assertion mechanism TODO for more details. If the relation is functional
262 * the request returns a single object according to the functional statement
263 * shadowing rules TODO if possible. If an invalid graph is encountered an
264 * exception is thrown.
266 * @param subject a resource
267 * @param relation a resource
268 * @return the objects
269 * @throws ManyObjectsForFunctionalRelationException on invalid graph with
270 * more than one functional object
271 * @throws ServiceException on connection and database failures
272 * @see AsyncReadGraph#forEachAssertedStatement
273 * @see AsyncReadGraph#forAssertedStatementSet
275 Collection<Resource> getAssertedObjects(Resource subject, Resource relation)
276 throws ManyObjectsForFunctionalRelationException, ServiceException;
279 * Gets the inverse r of relation such that (relation, InverseOf, r). The
280 * methods assumes an inverse exists.
282 * @param relation a resource
283 * @return the inverse
284 * @throws NoInverseException if inverse was not fond
285 * @throws ManyObjectsForFunctionalRelationException on invalid graph with
286 * more than one functional object
287 * @throws ServiceException on connection and database failures
288 * @see AsyncReadGraph#forInverse
290 Resource getInverse(Resource relation) throws NoInverseException, ManyObjectsForFunctionalRelationException,
294 * Gets a single object as returned by {@link ReadGraph#getObjects}. Assumes
297 * @param subject a resource
298 * @param relation a resource
299 * @return the single object
300 * @throws NoSingleResultException if the amount of valid objects was not
302 * @throws ManyObjectsForFunctionalRelationException on invalid graph with
303 * more than one functional object
304 * @throws ServiceException on connection and database failures
305 * @see AsyncReadGraph#forSingleObject
307 Resource getSingleObject(Resource subject, Resource relation) throws NoSingleResultException,
308 ManyObjectsForFunctionalRelationException, ServiceException;
311 * Gets a single statement as returned by {@link ReadGraph#getStatements}.
312 * Assumes a single statement.
314 * @param subject a resource
315 * @param relation a resource
316 * @return the single statement
317 * @throws NoSingleResultException if the amount of valid statements was not
319 * @throws ManyObjectsForFunctionalRelationException on invalid graph with
320 * more than one functional object
321 * @throws ServiceException on connection and database failures
322 * @see AsyncReadGraph#forSingleStatement
324 Statement getSingleStatement(Resource subject, Resource relation) throws NoSingleResultException,
325 ManyObjectsForFunctionalRelationException, ServiceException;
328 * Gets a single type t as returned by {@link ReadGraph#getPrincipalTypes}. Assumes a single type.
330 * @param subject a resource
331 * @param baseType a resource
332 * @return the single type
333 * @throws NoSingleResultException if the amount of valid types was not one
334 * @throws ServiceException on connection and database failures
335 * @see AsyncReadGraph#forSingleType
337 Resource getSingleType(Resource subject) throws NoSingleResultException, ServiceException;
340 * Gets a single type t as returned by {@link ReadGraph#getTypes} where
341 * {@link ReadGraph#isInheritedFrom(t, baseType)}. Assumes a single type.
343 * @param subject a resource
344 * @param baseType a resource
345 * @return the single type
346 * @throws NoSingleResultException if the amount of valid types was not one
347 * @throws ServiceException on connection and database failures
348 * @see AsyncReadGraph#forSingleType
350 Resource getSingleType(Resource subject, Resource baseType) throws NoSingleResultException, ServiceException;
353 * Gets a value associated to subject. Infers {@link Binding} from type t =
354 * {@link ReadGraph#getSingleType(subject, Value)}
356 * @param subject a resource
358 * @throws DoesNotContainValueException if the subject did not contain a
360 * @throws ServiceException on connection and database failure
361 * @see AsyncReadGraph#forValue
363 <T> T getValue(Resource subject) throws DoesNotContainValueException, ServiceException;
366 * Gets a value associated to subject as a Variant. Infers {@link Binding} from type t =
367 * {@link ReadGraph#getSingleType(subject, Value)}
369 * @param subject a resource
371 * @throws DoesNotContainValueException if the subject did not contain a
373 * @throws ServiceException on connection and database failure
374 * @see AsyncReadGraph#forValue
376 Variant getVariantValue(Resource subject) throws DoesNotContainValueException, ServiceException;
379 * Gets a value associated to subject using the given {@link Binding}.
381 * @param subject a resource
382 * @param binding a binding
384 * @throws DoesNotContainValueException if the subject did not contain a
386 * @throws BindingException if value could not be produced using the given
388 * @throws ServiceException on connection and database failure
389 * @see AsyncReadGraph#forValue
391 <T> T getValue(Resource subject, Binding binding) throws DoesNotContainValueException, BindingException,
395 * Gets a single value associated to o such that (subject, r, o) and
396 * {@link ReadGraph#isSubrelationOf(r, relation)}. Assumes a single value.
397 * Infers {@link Binding} from type t =
398 * {@link ReadGraph#getSingleType(o, Value)}
400 * @param subject a resource
401 * @param relation a resource
403 * @throws NoSingleResultException if the amount of valid values was not one
404 * @throws DoesNotContainValueException if suitable o did not contain a
406 * @throws ServiceException on connection and database failure
407 * @see AsyncReadGraph#forRelatedValue
409 <T> T getRelatedValue(Resource subject, Resource relation) throws NoSingleResultException,
410 DoesNotContainValueException, ServiceException;
413 * Gets a single value associated to o such that (subject, r, o) and
414 * {@link ReadGraph#isSubrelationOf(r, relation)} as a Variant. Assumes a single value.
415 * Infers {@link Binding} from type t =
416 * {@link ReadGraph#getSingleType(o, Value)}
418 * @param subject a resource
419 * @param relation a resource
421 * @throws NoSingleResultException if the amount of valid values was not one
422 * @throws DoesNotContainValueException if suitable o did not contain a
424 * @throws ServiceException on connection and database failure
425 * @see AsyncReadGraph#forRelatedValue
427 Variant getRelatedVariantValue(Resource subject, Resource relation) throws NoSingleResultException,
428 DoesNotContainValueException, ServiceException;
431 * Gets a single value associated to o such that (subject, r, o) and
432 * {@link ReadGraph#isSubrelationOf(r, relation)}. Uses the given
433 * {@link Binding}. Assumes a single value.
435 * @param subject a resource
436 * @param relation a resource
438 * @throws NoSingleResultException if the amount of valid values was not one
439 * @throws DoesNotContainValueException if suitable o did not contain a
441 * @throws BindingException if value could not be produced using the given
443 * @throws ServiceException on connection and database failure
444 * @see AsyncReadGraph#forRelatedValue
446 <T> T getRelatedValue(Resource subject, Resource relation, Binding binding) throws NoSingleResultException,
447 DoesNotContainValueException, BindingException, ServiceException;
450 * Tries to adapt the specified resource into an instance of the specified
451 * class T. No guarantees are made on return values of this method. The
452 * returned values can be cached results of previous invocation or they can
453 * be new result object instances. See {@link #adaptUnique(Resource, Class)}
454 * for alternative behaviour.
456 * @param resource a resource
457 * @param clazz the adapter class
459 * @throws AdaptionException if suitable adapter was not found
460 * @throws ValidationException from the adapter
461 * @throws ServiceException on connection and database failure
462 * @see AsyncReadGraph#forAdapted
463 * @see #adaptUnique(Resource, Class)
465 <T> T adapt(Resource resource, Class<T> clazz) throws AdaptionException, ValidationException, ServiceException;
469 * Same as: adapt(getSingleObject(resource, relation), clazz);
471 * @param resource a resource
472 * @param relation a resource
473 * @param clazz the adapter class
475 * @throws AdaptionException if suitable adapter was not found
476 * @throws ValidationException from the adapter
477 * @throws ServiceException on connection and database failure
478 * @see AsyncReadGraph#forAdapted
479 * @see #adaptUnique(Resource, Class)
481 <T> T adaptRelated(Resource resource, Resource relation, Class<T> clazz) throws AdaptionException, NoSingleResultException, ValidationException, ServiceException;
487 * Resource r = getPossibleObject(resource, relation);
488 * if(r == null) return null;
489 * return getPossibleAdapter(r, clazz);
491 * @param resource a resource
492 * @param relation a resource
493 * @param clazz the adapter class
495 * @throws AdaptionException if suitable adapter was not found
496 * @throws ValidationException from the adapter
497 * @throws ServiceException on connection and database failure
498 * @see AsyncReadGraph#forAdapted
499 * @see #adaptUnique(Resource, Class)
501 <T> T getPossibleRelatedAdapter(Resource resource, Resource relation, Class<T> clazz) throws ValidationException, ServiceException;
503 <T,C> T adaptContextual(Resource resource, C context, Class<C> contextClass, Class<T> clazz) throws AdaptionException, NoSingleResultException, ValidationException, ServiceException;
504 <T,C> T getPossibleContextualAdapter(Resource resource, C context, Class<C> contextClass, Class<T> clazz) throws ValidationException, ServiceException;
507 * Tries to adapt the specified resource into an instance of the specified
508 * class T. The difference to {@link #adapt(Resource, Class)} is that this
509 * method does everything possible to return a new object instance for each
510 * separate invocation.
513 * The only case when this cannot be guaranteed is when the adaption result
514 * comes from an {@link Adapter} implementation which can internally do
515 * anything, like always return the same singleton instance.
518 * @param resource a resource
519 * @param clazz the adapter class
521 * @throws AdaptionException if suitable adapter was not found
522 * @throws ValidationException from the adapter
523 * @throws ServiceException on connection and database failure
524 * @see AsyncReadGraph#forAdapted
525 * @see #adapt(Resource, Class)
527 <T> T adaptUnique(Resource resource, Class<T> clazz) throws AdaptionException, ValidationException,
531 * As {@link #getInverse} but returns null instead of an exception if
532 * inverse was not found.
534 * @param relation a resource
535 * @return the inverse or null
536 * @throws ManyObjectsForFunctionalRelationException on invalid graph with
537 * more than one functional object
538 * @throws ServiceException on connection and database failures
539 * @see AsyncReadGraph#forPossibleInverse
541 Resource getPossibleInverse(Resource relation) throws ManyObjectsForFunctionalRelationException, ServiceException;
544 * As {@link #getSingleObject} but returns null instead of an exception if
545 * object was not found.
547 * @param subject a resource
548 * @param relation a resource
549 * @return the object or null
550 * @throws ManyObjectsForFunctionalRelationException on invalid graph with
551 * more than one functional object
552 * @throws ServiceException on connection and database failures
553 * @see AsyncReadGraph#forPossibleObject
555 Resource getPossibleObject(Resource subject, Resource relation) throws ManyObjectsForFunctionalRelationException,
559 * As {@link #getSingleStatement} but returns null instead of an exception
560 * if statement was not found.
562 * @param subject a resource
563 * @param relation a resource
564 * @return the statement or null
565 * @throws ManyObjectsForFunctionalRelationException on invalid graph with
566 * more than one functional object
567 * @throws ServiceException on connection and database failures
568 * @see AsyncReadGraph#forPossibleStatement
570 Statement getPossibleStatement(Resource subject, Resource relation)
571 throws ManyObjectsForFunctionalRelationException, ServiceException;
574 * As {@link #getSingleType} but returns null instead of an exception if
575 * type was not found.
577 * @param subject a resource
578 * @param baseType a resource
579 * @return the type or null
580 * @throws ServiceException on connection and database failures
581 * @see AsyncReadGraph#forPossibleType
583 Resource getPossibleType(Resource subject, Resource baseType) throws ServiceException;
586 * As {@link #getValue} but returns null instead of an exception if value
589 * @param subject a resource
590 * @return the value or null
591 * @throws ServiceException on connection and database failures
592 * @see AsyncReadGraph#forPossibleValue
594 <T> T getPossibleValue(Resource subject) throws ServiceException;
597 * As {@link #getValue} but returns null instead of an exception if value
600 * @param subject a resource
601 * @param binding a {@link Binding}
602 * @return the value or null
603 * @throws BindingException if value could not be produced using the given
605 * @throws ServiceException on connection and database failures
606 * @see AsyncReadGraph#forPossibleValue
608 <T> T getPossibleValue(Resource subject, Binding binding) throws BindingException, ServiceException;
611 * As {@link #getPossibleRelatedValue} but returns null instead of an
612 * exception if value was not found.
614 * @param subject a resource
615 * @param relation a resource
616 * @return the value or null
617 * @throws ManyObjectsForFunctionalRelationException on invalid graph with
618 * more than one functional object
619 * @throws ServiceException on connection and database failures
620 * @see AsyncReadGraph#forPossibleRelatedValue
622 <T> T getPossibleRelatedValue(Resource subject, Resource relation)
623 throws ManyObjectsForFunctionalRelationException, ServiceException;
626 * As {@link #getPossibleRelatedValue} but returns null instead of an
627 * exception if value was not found.
629 * @param subject a resource
630 * @param relation a resource
631 * @param binding a {@link Binding}
632 * @return the value or null
633 * @throws ManyObjectsForFunctionalRelationException on invalid graph with
634 * more than one functional object
635 * @throws BindingException if value could not be produced using the given
637 * @throws ServiceException on connection and database failures
638 * @see AsyncReadGraph#forPossibleRelatedValue
640 <T> T getPossibleRelatedValue(Resource subject, Resource relation, Binding binding)
641 throws ManyObjectsForFunctionalRelationException, BindingException, ServiceException;
644 * As {@link #adapt} but returns null instead of an exception if adapter was
647 * @param subject a resource
648 * @param clazz a Class
649 * @return the adapter or null
650 * @throws ValidationException when ?
651 * @throws ServiceException on connection and database failures
652 * @see {@link AsyncReadGraph#forPossibleAdapted}
654 <T> T getPossibleAdapter(Resource resource, Class<T> clazz) throws ValidationException, ServiceException;
657 * As {@link #adaptUnique} but returns null instead of an exception if
658 * adapter was not found
660 * @param subject a resource
661 * @param clazz a Class
662 * @return the adapter or null
663 * @throws ValidationException when ?
664 * @throws ServiceException on connection and database failures
665 * @see {@link AsyncReadGraph#forPossibleAdapted}
667 <T> T getPossibleUniqueAdapter(Resource resource, Class<T> clazz) throws ValidationException, ServiceException;
670 * Returns true if type is included in the result of {@link #getTypes(resource)}
672 * @param subject a resource
673 * @param type a resource
674 * @return indicates if resource is an instance of type
675 * @throws ServiceException on connection and database failures
676 * @see {@link AsyncReadGraph#forIsInstanceOf}
678 boolean isInstanceOf(Resource resource, Resource type) throws ServiceException;
681 * Returns true if type equals resource or type is included in the result of
682 * {@link #getSupertypes(resource)}
684 * @param subject a resource
685 * @param type a resource
686 * @return indicates if resource is inherited from type
687 * @throws ServiceException on connection and database failures
688 * @see {@link AsyncReadGraph#forIsInheritedFrom}
690 boolean isInheritedFrom(Resource resource, Resource type) throws ServiceException;
693 * Returns true if relation equals resource or relation is included in the result of
694 * {@link #getSuperrelations(resource)}
696 * @param subject a resource
697 * @param relation a resource
698 * @return indicates if resource is a subrelation of relation
699 * @throws ServiceException on connection and database failures
700 * @see {@link AsyncReadGraph#forIsSubrelationOf}
702 boolean isSubrelationOf(Resource resource, Resource relation) throws ServiceException;
705 * Returns true if the result of {@link #getStatements(subject, IsWeaklyRelatedTo)} is nonempty.
707 * @param subject a resource
708 * @return indicates that subject has statements
709 * @throws ServiceException on connection and database failures
710 * @see {@link AsyncReadGraph#forHasStatement}
712 boolean hasStatement(Resource subject) throws ServiceException;
715 * Returns true if the result of {@link #getStatements(subject, relation)} is nonempty.
717 * @param subject a resource
718 * @param relation a resource
719 * @return indicates that subject has statements with predicates as subrelation of relation
720 * @throws ServiceException on connection and database failures
721 * @see {@link AsyncReadGraph#forHasStatement}
723 boolean hasStatement(Resource subject, Resource relation) throws ServiceException;
726 * Returns true if a statement (subject, relation, object) exists after assertions.
728 * @param subject a resource
729 * @param relation a resource
730 * @param object a resource
731 * @return indicates that the given statement exists
732 * @throws ServiceException on connection and database failures
733 * @see {@link AsyncReadGraph#forHasStatement}
735 boolean hasStatement(Resource subject, Resource relation, Resource object) throws ServiceException;
738 * Returns true if there is a value associated with subject.
739 * IMPLEMENTATION NOTE:
740 * Current implementation fetches the value from server. If the value is
741 * large (i.e. not stored in the cluster) this is highly inefficient.
743 * @param subject a resource
744 * @return indicates that a value exists
745 * @throws ServiceException on connection and database failures
746 * @see {@link AsyncReadGraph#forHasValue}
748 boolean hasValue(Resource subject) throws ServiceException;
751 * Returns the data type of the literal.
754 * @throws DatabaseException
756 Datatype getDataType(Resource subject) throws DatabaseException;
759 * Returns an accessory that can be used to partially read the literal
760 * or write if the graph is WriteGraph. The returned accessory is closed
761 * automatically when the transaction ends. The modifications are written
762 * back to graph at transaction completion.
764 * @param <T> is typed accessory for modifying the literal value.
765 * @param resource is the literal containing the value.
766 * @return interface to partially read and write the literal value.
767 * @throws DatabaseException
769 <T extends Accessor> T getAccessor(Resource resource) throws DatabaseException;
772 * Returns an RandomAccessBinary that can be used to partially read the literal
773 * or write if the graph is WriteGraph. The returned interface is closed
774 * automatically when the transaction ends. The modifications are written
775 * back to graph at transaction completion.
778 * @param resource is the literal containing the value.
779 * @return interface to partially read and write the literal value.
780 * @throws DatabaseException
782 RandomAccessBinary getRandomAccessBinary(Resource resource) throws DatabaseException;
783 // @SuppressWarnings("rawtypes")
784 // Function getValueFunction(Resource resource) throws DatabaseException;
787 * Get the value associated with a graph {@link Resource}, using a possible context object and
788 * a default data type binding. An exception is thrown, if the value is not found.
790 * See {@link #getValue2(Resource, Object, Binding)} for more details.
792 * @param r A graph resource with which the value is associated
793 * @param context A context object that is used for acquiring the value, can be {@code null}
794 * @return The value of the graph node.
795 * @throws DoesNotContainValueException No value is associated with the graph node.
796 * @throws DatabaseException Other errors, such as an error in casting the value to the return type or
797 * a runtime error in the value function.
798 * @see #getValue2(Resource, Object, Binding)
799 * @see #getPossibleValue2(Resource, Object)
801 <T> T getValue2(Resource subject, Object context) throws DatabaseException;
804 * Get the value associated with a graph {@link Resource}, using a possible context object and
805 * a default data type binding as a Variant. An exception is thrown, if the value is not found.
807 * See {@link #getValue2(Resource, Object, Binding)} for more details.
809 * @param r A graph resource with which the value is associated
810 * @param context A context object that is used for acquiring the value, can be {@code null}
811 * @return The value of the graph node.
812 * @throws DoesNotContainValueException No value is associated with the graph node.
813 * @throws DatabaseException Other errors, such as an error in casting the value to the return type or
814 * a runtime error in the value function.
815 * @see #getValue2(Resource, Object, Binding)
816 * @see #getPossibleValue2(Resource, Object)
818 Variant getVariantValue2( Resource r, Object context ) throws DatabaseException;
821 * Get a possible value associated with a graph {@link Resource}, using a possible context object and
822 * a desired value binding. Unlike {@link #getValue2(Resource, Object)}, this methods
823 * returns {@code null} for missing values instead of throwing an exception.
825 * See {@link #getValue2(Resource, Object, Binding)} for more details.
827 * @param r A graph resource with which the value is associated
828 * @param context A context object that is used for acquiring the value, can be {@code null}
829 * @return The value of the graph node.
830 * @throws DatabaseException Usually should not happen. A null value is returned for possible errors.
831 * @see #getValue2(Resource, Object)
832 * @see #getPossibleValue2(Resource, Object, Binding)
834 <T> T getPossibleValue2(Resource subject, Object context) throws DatabaseException;
837 * Get the value associated with a graph {@link Resource}, using a possible context object and
838 * a desired value binding. An exception is thrown, if the value is not found.
840 * The following methods are tried in order to retrieve the value:
842 * <li>If the given resource is a {@code L0.Literal}, the value of the literal is returned, using the binding specified by {@code binding}.</li>
843 * <li>If the resource is a {@code L0.ExternalValue}, the value is acquired using
844 * {@link ReflectionUtils#getValue(String)} with the resource URI.</li>
845 * <li>If the resource is associated with a suitable value converter with relation {@code L0.ConvertsToValueWith}
846 * (see {@link #requestValueFunction(Resource)}), the value function is called with the graph, the resource
847 * and the context object.</li>
850 * @param r A graph resource with which the value is associated
851 * @param context A context object that is used for acquiring the value, can be {@code null}
852 * @param binding A binding for the value type
853 * @return The value of the graph node.
854 * @throws DoesNotContainValueException No value is associated with the graph node.
855 * @throws DatabaseException Other errors, such as an error in casting the value to the return type or
856 * a runtime error in the value function.
857 * @see #getValue2(Resource, Object)
858 * @see #getPossibleValue2(Resource, Object, Binding)
860 <T> T getValue2(Resource subject, Object context, Binding binding) throws DatabaseException;
863 * Get a possible value associated with a graph {@link Resource}, using a possible context object and
864 * a desired value binding. Unlike {@link #getValue2(Resource, Object, Binding)}, this methods
865 * returns {@code null} for missing values instead of throwing an exception.
867 * See {@link #getValue2(Resource, Object, Binding)} for more details.
869 * @param r A graph resource with which the value is associated
870 * @param context A context object that is used for acquiring the value, can be {@code null}
871 * @param binding A binding for the value type
872 * @return The value of the graph node.
873 * @throws DatabaseException Usually should not happen. A null value is returned for possible errors.
874 * @see #getValue2(Resource, Object, Bindinge)
875 * @see #getPossibleValue2(Resource, Object)
877 <T> T getPossibleValue2(Resource subject, Object context, Binding binding) throws DatabaseException;
880 * Get the single value associated with a graph resource related with a given subject.
881 * An exception is thrown, if a unique object resource or a value for it is not found.
883 * See {@link #getValue2(Resource, Object, Binding)} for more details.
885 * @param subject A graph resource that indicates the subject node
886 * @param relation A graph resource that indicates the predicate of a relation
887 * @return The value of the unique graph node that is asserted as the object of the given subject and predicate.
888 * @throws NoSingleResultException The number of suitable object resources is not equal to 1 (zero or greater than one)
889 * @throws DoesNotContainValueException No value is associated with the graph node.
890 * @throws DatabaseException Other errors, such as an error in casting the value to the return type or
891 * a runtime error in the value function.
892 * @see #getRelatedValue2(Resource, Resource, Binding)
893 * @see #getRelatedValue2(Resource, Resource, Object)
894 * @see #getRelatedValue2(Resource, Resource, Object, Binding)
895 * @see #getPossibleRelatedValue2(Resource, Resource)
897 <T> T getRelatedValue2(Resource subject, Resource relation) throws DatabaseException;
900 * Get a possible single value associated with a graph resource related with a given subject.
901 * A {@code null} value is returned for missing values or other errors.
903 * See {@link #getValue2(Resource, Object, Binding)} for more details.
905 * @param subject A graph resource that indicates the subject node
906 * @param relation A graph resource that indicates the predicate of a relation
907 * @return The value of the unique graph node that is asserted as the object of the given subject and predicate.
908 * @throws DatabaseException Usually should not happen. A {@code null} value is returned for possible errors.
909 * @see #getPossibleRelatedValue2(Resource, Resource, Binding)
910 * @see #getPossibleRelatedValue2(Resource, Resource, Object)
911 * @see #getPossibleRelatedValue2(Resource, Resource, Object, Binding)
912 * @see #getRelatedValue2(Resource, Resource)
914 <T> T getPossibleRelatedValue2(Resource subject, Resource relation) throws DatabaseException;
917 * Get a possible single value associated with a graph resource related with a given subject.
918 * A {@code null} value is returned for missing values or other errors.
920 * See {@link #getValue2(Resource, Object, Binding)} for more details.
922 * @param subject A graph resource that indicates the subject node
923 * @param relation A graph resource that indicates the predicate of a relation
924 * @return The value of the unique graph node that is asserted as the object of the given subject and predicate.
925 * @throws DatabaseException Usually should not happen. A {@code null} value is returned for possible errors.
926 * @see #getPossibleRelatedValue2(Resource, Resource, Binding)
927 * @see #getPossibleRelatedValue2(Resource, Resource, Object)
928 * @see #getPossibleRelatedValue2(Resource, Resource, Object, Binding)
929 * @see #getRelatedValue2(Resource, Resource)
931 Variant getRelatedVariantValue2( Resource subject, Resource relation ) throws DatabaseException;
934 * Get the single value associated with a graph resource related with a given subject, a possible context object.
935 * An exception is thrown, if a unique object resource or a value for it is not found.
937 * See {@link #getValue2(Resource, Object, Binding)} for more details.
939 * @param subject A graph resource that indicates the subject node
940 * @param relation A graph resource that indicates the predicate of a relation
941 * @param context A context object that is used for acquiring the value, can be {@code null}
942 * @return The value of the unique graph node that is asserted as the object of the given subject and predicate.
943 * @throws NoSingleResultException The number of suitable object resources is not equal to 1 (zero or greater than one)
944 * @throws DoesNotContainValueException No value is associated with the graph node.
945 * @throws DatabaseException Other errors, such as an error in casting the value to the return type or
946 * a runtime error in the value function.
947 * @see #getRelatedValue2(Resource, Resource)
948 * @see #getRelatedValue2(Resource, Resource, Binding)
949 * @see #getRelatedValue2(Resource, Resource, Object, Binding)
950 * @see #getPossibleRelatedValue2(Resource, Resource, Object)
952 <T> T getRelatedValue2(Resource subject, Resource relation, Object context) throws DatabaseException;
955 * Get the single value associated with a graph resource related with a given subject, a possible context object.
956 * An exception is thrown, if a unique object resource or a value for it is not found.
958 * See {@link #getValue2(Resource, Object, Binding)} for more details.
960 * @param subject A graph resource that indicates the subject node
961 * @param relation A graph resource that indicates the predicate of a relation
962 * @param context A context object that is used for acquiring the value, can be {@code null}
963 * @return The value of the unique graph node that is asserted as the object of the given subject and predicate.
964 * @throws NoSingleResultException The number of suitable object resources is not equal to 1 (zero or greater than one)
965 * @throws DoesNotContainValueException No value is associated with the graph node.
966 * @throws DatabaseException Other errors, such as an error in casting the value to the return type or
967 * a runtime error in the value function.
968 * @see #getRelatedValue2(Resource, Resource, Object)
969 * @see #getPossibleRelatedValue2(Resource, Resource, Object)
971 Variant getRelatedVariantValue2( Resource subject, Resource relation, Object context ) throws DatabaseException;
974 * Get a possible single value associated with a graph resource related with a given subject and a possible context object.
975 * A {@code null} value is returned for missing values or other errors.
977 * See {@link #getValue2(Resource, Object, Binding)} for more details.
979 * @param subject A graph resource that indicates the subject node
980 * @param relation A graph resource that indicates the predicate of a relation
981 * @param context A context object that is used for acquiring the value, can be {@code null}
982 * @return The value of the unique graph node that is asserted as the object of the given subject and predicate.
983 * @throws DatabaseException Usually should not happen. A {@code null} value is returned for possible errors.
984 * @see #getPossibleRelatedValue2(Resource, Resource)
985 * @see #getPossibleRelatedValue2(Resource, Resource, Binding)
986 * @see #getPossibleRelatedValue2(Resource, Resource, Object, Binding)
987 * @see #getRelatedValue2(Resource, Resource, Object)
989 <T> T getPossibleRelatedValue2(Resource subject, Resource relation, Object context) throws DatabaseException;
992 * Get the single value associated with a graph resource related with a given subject and
993 * a desired value binding. An exception is thrown, if a unique object resource or a value for it is not found.
995 * See {@link #getValue2(Resource, Object, Binding)} for more details.
997 * @param subject A graph resource that indicates the subject node
998 * @param relation A graph resource that indicates the predicate of a relation
999 * @param binding A binding for the value type
1000 * @return The value of the unique graph node that is asserted as the object of the given subject and predicate.
1001 * @throws NoSingleResultException The number of suitable object resources is not equal to 1 (zero or greater than one)
1002 * @throws DoesNotContainValueException No value is associated with the graph node.
1003 * @throws DatabaseException Other errors, such as an error in casting the value to the return type or
1004 * a runtime error in the value function.
1005 * @see #getRelatedValue2(Resource, Resource)
1006 * @see #getRelatedValue2(Resource, Resource, Object)
1007 * @see #getRelatedValue2(Resource, Resource, Object, Binding)
1008 * @see #getPossibleRelatedValue2(Resource, Resource, Binding)
1010 <T> T getRelatedValue2(Resource subject, Resource relation, Binding binding) throws DatabaseException;
1013 * Get a possible single value associated with a graph resource related with a given subject and
1014 * a desired value binding. A {@code null} value is returned for missing values or other errors.
1016 * See {@link #getValue2(Resource, Object, Binding)} for more details.
1018 * @param subject A graph resource that indicates the subject node
1019 * @param relation A graph resource that indicates the predicate of a relation
1020 * @param binding A binding for the value type
1021 * @return The value of the unique graph node that is asserted as the object of the given subject and predicate.
1022 * @throws DatabaseException Usually should not happen. A {@code null} value is returned for possible errors.
1023 * @see #getPossibleRelatedValue2(Resource, Resource)
1024 * @see #getPossibleRelatedValue2(Resource, Resource, Object)
1025 * @see #getPossibleRelatedValue2(Resource, Resource, Object, Binding)
1026 * @see #getRelatedValue2(Resource, Resource, Binding)
1028 <T> T getPossibleRelatedValue2(Resource subject, Resource relation, Binding binding) throws DatabaseException;
1031 * Get the single value associated with a graph resource related with a given subject, a possible context object and
1032 * a desired value binding. An exception is thrown, if a unique object resource or a value for it is not found.
1034 * See {@link #getValue2(Resource, Object, Binding)} for more details.
1036 * @param subject A graph resource that indicates the subject node
1037 * @param relation A graph resource that indicates the predicate of a relation
1038 * @param context A context object that is used for acquiring the value, can be {@code null}
1039 * @param binding A binding for the value type
1040 * @return The value of the unique graph node that is asserted as the object of the given subject and predicate.
1041 * @throws NoSingleResultException The number of suitable object resources is not equal to 1 (zero or greater than one)
1042 * @throws DoesNotContainValueException No value is associated with the graph node.
1043 * @throws DatabaseException Other errors, such as an error in casting the value to the return type or
1044 * a runtime error in the value function.
1045 * @see #getRelatedValue2(Resource, Resource)
1046 * @see #getRelatedValue2(Resource, Resource, Binding)
1047 * @see #getRelatedValue2(Resource, Resource, Object)
1048 * @see #getPossibleRelatedValue2(Resource, Resource, Object, Binding)
1050 <T> T getRelatedValue2(Resource subject, Resource relation, Object context, Binding binding) throws DatabaseException;
1053 * Get a possible single value associated with a graph resource related with a given subject, a possible context object and
1054 * a desired value binding. A {@code null} value is returned for missing values or other errors.
1056 * See {@link #getValue2(Resource, Object, Binding)} for more details.
1058 * @param subject A graph resource that indicates the subject node
1059 * @param relation A graph resource that indicates the predicate of a relation
1060 * @param context A context object that is used for acquiring the value, can be {@code null}
1061 * @param binding A binding for the value type
1062 * @return The value of the unique graph node that is asserted as the object of the given subject and predicate.
1063 * @throws DatabaseException Usually should not happen. A {@code null} value is returned for possible errors.
1064 * @see #getPossibleRelatedValue2(Resource, Resource)
1065 * @see #getPossibleRelatedValue2(Resource, Resource, Binding)
1066 * @see #getPossibleRelatedValue2(Resource, Resource, Object)
1067 * @see #getRelatedValue2(Resource, Resource, Object, Binding)
1069 <T> T getPossibleRelatedValue2(Resource subject, Resource relation, Object context, Binding binding) throws DatabaseException;
1072 * Get the parsed SCL type declaration from the string value of a graph resource that is the unique object of a
1073 * given subject and predicate.
1075 * See {@link #getValue2(Resource, Object, Binding)} for more details.
1077 * @param subject A resource that indicates the subject of a statement
1078 * @param relation A resource that indicates the predicate of the statement
1079 * @return A compiled SCL type definition of the string value of a unique object resource
1080 * @throws DatabaseException For any errors in locating a unique value or compiling it as an SCL type statement
1082 Type getRelatedValueType(Resource subject, Resource relation) throws DatabaseException;
1084 boolean setSynchronous(boolean value);
1085 boolean getSynchronous();
1087 boolean isImmutable(Resource resource) throws DatabaseException;