1 /*******************************************************************************
2 * Copyright (c) 2007, 2010 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.MultiRead;
41 import org.simantics.db.request.Read;
42 import org.simantics.scl.compiler.types.Type;
46 * For accessing and manipulating the graph data in synchronous manner. A client
47 * receives ReadGraph instances for performing requests in {@link Read} and
48 * {@link MultiRead} as well as for reacting to request results using
49 * {@link SyncProcedure}, {@link SyncListener}, {@link SyncMultiProcedure},
50 * {@link SyncMultiListener} and {@link SyncSetListener}
52 * ReadGraph instances are stateful and may not be stored and used outside the
53 * supplier method activation. The methods receiving ReadGraph should not block
54 * for long periods of time since that may delay the processing of other
55 * requests. For an asynchronous counterpart with the same functionality as
56 * ReadGraph see {@link AsyncReadGraph}
59 * All collections returned by the methods on this interface must not be
60 * modified by clients unless explicitly stated otherwise.
63 * @author Antti Villberg
64 * @see RequestProcessor
65 * @see AsyncRequestProcessor
71 public interface ReadGraph extends AsyncReadGraph, RequestProcessor {
75 * @see AsyncReadGraph#forURI
77 String getURI(Resource resource) throws AssumptionException, ValidationException, ServiceException;
78 String getPossibleURI(Resource resource) throws ValidationException, ServiceException;
81 * Gets a unique resource associated to the given identifier. See <a
82 * href="https://www.simantics.org/wiki/index.php/URI">Simantics Wiki page
83 * on URIs</a> for more details.
85 * @param uri the identifier
86 * @return the resource
87 * @throws ResourceNotFoundException if a resource for the given identifier
89 * @throws ValidationException if a resource could not be produced due to
91 * @throws ServiceException on connection and database failures
92 * @see AsyncReadGraph#forResourceByURI
94 Resource getResource(String uri) throws ResourceNotFoundException, ValidationException, ServiceException;
97 * Gets a unique resource associated to the given identifier. See <a
98 * href="https://www.simantics.org/wiki/index.php/URI">Simantics Wiki page
99 * on URIs</a> for more details.
101 * @param uri the identifier
102 * @return the resource
103 * @throws ResourceNotFoundException if a resource for the given identifier
105 * @throws ValidationException if a resource could not be produced due to
107 * @throws ServiceException on connection and database failures
108 * @see AsyncReadGraph#forResourceByURI
110 Resource getPossibleResource(String uri) throws ResourceNotFoundException, ValidationException, ServiceException;
113 * Computes a map of objects related to resource with L0.ConsistsOf that also contain a L0.HasName property
115 * @param resource the resource
116 * @return the children
117 * @throws ValidationException if a resource could not be produced due to
119 * @throws ServiceException on connection and database failures
120 * @see AsyncReadGraph#forResourceByURI
122 Map<String,Resource> getChildren(Resource resource) throws ValidationException, ServiceException;
125 * Gets a builtin resource. For a list of builtin resources see TODO Wiki
127 * @param uri the identifier
128 * @return the resource
129 * @throws ResourceNotFoundException if resouce was not found
130 * @throws ServiceException on connection and database failures
131 * @see AsyncReadGraph#forBuiltin
133 Resource getBuiltin(String id) throws ResourceNotFoundException, ServiceException;
136 * Gets all statements (subject, p, o) such that
137 * {@link ReadGraph#isSubrelationOf(p, relation)} returns true. The result
138 * may include asserted statements for which s does not equal subject. See
139 * the assertion mechanisn TODO for more details. If the relation is
140 * functional the request returns a single statement according to the
141 * functional statement shadowing rules TODO if possible. If an invalid
142 * graph is encountered an exception is thrown.
144 * @param subject a resource
145 * @param relation a resource
146 * @return the statements
147 * @throws ManyObjectsForFunctionalRelationException on invalid graph with
148 * more than one functional object
149 * @throws ServiceException on connection and database failures
150 * @see AsyncReadGraph#forEachStatement
151 * @see AsyncReadGraph#forStatementSet
153 Collection<Statement> getStatements(Resource subject, Resource relation)
154 throws ManyObjectsForFunctionalRelationException, ServiceException;
157 * Gets all statements (s, p, o) asserted by subject such that
158 * {@link ReadGraph#isSubrelationOf(p, relation)} returns true. See the
159 * assertion mechanism TODO for more details. If the relation is functional
160 * the request returns a single statement according to the functional
161 * statement shadowing rules TODO if possible. If an invalid graph is
162 * encountered an exception is thrown.
164 * @param subject a resource
165 * @param relation a resource
166 * @return the statements
167 * @throws ManyObjectsForFunctionalRelationException on invalid graph with
168 * more than one functional object
169 * @throws ServiceException on connection and database failures
170 * @see AsyncReadGraph#forEachAssertedStatement
171 * @see AsyncReadGraph#forAssertedStatementSet
173 Collection<Statement> getAssertedStatements(Resource subject, Resource relation)
174 throws ManyObjectsForFunctionalRelationException, ServiceException;
177 * Gets all predicates p from statements (subject, p, o) such that
178 * {@link ReadGraph#isSubrelationOf(p, relation)} returns true. See the
179 * assertion mechanism TODO for more details. If the relation is functional
180 * the request returns a single statement according to the functional
181 * statement shadowing rules TODO if possible. If an invalid graph is
182 * encountered an exception is thrown.
184 * @param subject a resource
185 * @param relation a resource
186 * @return the predicates
187 * @throws ManyObjectsForFunctionalRelationException on invalid graph with
188 * more than one object
189 * @throws ServiceException on connection and database failures
190 * @see AsyncReadGraph#forEachPredicate
191 * @see AsyncReadGraph#forPredicateSet
193 Collection<Resource> getPredicates(Resource subject) throws ServiceException;
196 * Gets a subset of all types of the subject such that no pair of returned
197 * types inherit each other and all types of the subject are supertypes
198 * of some type in the returned set.
200 * @param subject a resource
201 * @return the principal types
202 * @throws ServiceException on connection and database failures
203 * @see AsyncReadGraph#forEachPrincipalType
204 * @see AsyncReadGraph#forPrincipalTypeSet
206 Collection<Resource> getPrincipalTypes(Resource subject) throws ServiceException;
209 * Gets the full type hierarchy for subject.
211 * @param subject a resource
212 * @return the type hierarchy
213 * @throws ServiceException on connection and database failures
214 * @see AsyncReadGraph#forTypes
216 Set<Resource> getTypes(Resource subject) throws ServiceException;
219 * Gets the full supertype hierarchy for subject.
221 * @param subject a resource
222 * @return the supertype hierarchy
223 * @throws ServiceException on connection and database failures
224 * @see AsyncReadGraph#forSupertypes
226 Set<Resource> getSupertypes(Resource subject) throws ServiceException;
229 * Gets the full superrelation hierarchy for subject.
231 * @param subject a resource
232 * @return the superrelation hierarchy
233 * @throws ServiceException on connection and database failures
234 * @see AsyncReadGraph#forSuperrelations
236 Set<Resource> getSuperrelations(Resource subject) throws ServiceException;
237 Resource getPossibleSuperrelation(Resource subject) throws ServiceException;
240 * Gets all objects o from statements (subject, p, o) such that
241 * {@link ReadGraph#isSubrelationOf(p, relation)} returns true. See the
242 * assertion mechanisn TODO for more details. If the relation is functional
243 * the request returns a single object according to the functional statement
244 * shadowing rules TODO if possible. If an invalid graph is encountered an
245 * exception is thrown.
247 * @param subject a resource
248 * @param relation a resource
249 * @return the objects
250 * @throws ManyObjectsForFunctionalRelationException on invalid graph with
251 * more than one functional object
252 * @throws ServiceException on connection and database failures
253 * @see AsyncReadGraph#forEachObject
254 * @see AsyncReadGraph#forObjectSet
256 Collection<Resource> getObjects(Resource subject, Resource relation)
257 throws ServiceException;
260 * Gets all objects o (s, p, o) asserted by subject such that
261 * {@link ReadGraph#isSubrelationOf(p, relation)} returns true. See the
262 * assertion mechanism TODO for more details. If the relation is functional
263 * the request returns a single object according to the functional statement
264 * shadowing rules TODO if possible. If an invalid graph is encountered an
265 * exception is thrown.
267 * @param subject a resource
268 * @param relation a resource
269 * @return the objects
270 * @throws ManyObjectsForFunctionalRelationException on invalid graph with
271 * more than one functional object
272 * @throws ServiceException on connection and database failures
273 * @see AsyncReadGraph#forEachAssertedStatement
274 * @see AsyncReadGraph#forAssertedStatementSet
276 Collection<Resource> getAssertedObjects(Resource subject, Resource relation)
277 throws ManyObjectsForFunctionalRelationException, ServiceException;
280 * Gets the inverse r of relation such that (relation, InverseOf, r). The
281 * methods assumes an inverse exists.
283 * @param relation a resource
284 * @return the inverse
285 * @throws NoInverseException if inverse was not fond
286 * @throws ManyObjectsForFunctionalRelationException on invalid graph with
287 * more than one functional object
288 * @throws ServiceException on connection and database failures
289 * @see AsyncReadGraph#forInverse
291 Resource getInverse(Resource relation) throws NoInverseException, ManyObjectsForFunctionalRelationException,
295 * Gets a single object as returned by {@link ReadGraph#getObjects}. Assumes
298 * @param subject a resource
299 * @param relation a resource
300 * @return the single object
301 * @throws NoSingleResultException if the amount of valid objects was not
303 * @throws ManyObjectsForFunctionalRelationException on invalid graph with
304 * more than one functional object
305 * @throws ServiceException on connection and database failures
306 * @see AsyncReadGraph#forSingleObject
308 Resource getSingleObject(Resource subject, Resource relation) throws NoSingleResultException,
309 ManyObjectsForFunctionalRelationException, ServiceException;
312 * Gets a single statement as returned by {@link ReadGraph#getStatements}.
313 * Assumes a single statement.
315 * @param subject a resource
316 * @param relation a resource
317 * @return the single statement
318 * @throws NoSingleResultException if the amount of valid statements was not
320 * @throws ManyObjectsForFunctionalRelationException on invalid graph with
321 * more than one functional object
322 * @throws ServiceException on connection and database failures
323 * @see AsyncReadGraph#forSingleStatement
325 Statement getSingleStatement(Resource subject, Resource relation) throws NoSingleResultException,
326 ManyObjectsForFunctionalRelationException, ServiceException;
329 * Gets a single type t as returned by {@link ReadGraph#getPrincipalTypes}. Assumes a single type.
331 * @param subject a resource
332 * @param baseType a resource
333 * @return the single type
334 * @throws NoSingleResultException if the amount of valid types was not one
335 * @throws ServiceException on connection and database failures
336 * @see AsyncReadGraph#forSingleType
338 Resource getSingleType(Resource subject) throws NoSingleResultException, ServiceException;
341 * Gets a single type t as returned by {@link ReadGraph#getTypes} where
342 * {@link ReadGraph#isInheritedFrom(t, baseType)}. Assumes a single type.
344 * @param subject a resource
345 * @param baseType a resource
346 * @return the single type
347 * @throws NoSingleResultException if the amount of valid types was not one
348 * @throws ServiceException on connection and database failures
349 * @see AsyncReadGraph#forSingleType
351 Resource getSingleType(Resource subject, Resource baseType) throws NoSingleResultException, ServiceException;
354 * Gets a value associated to subject. Infers {@link Binding} from type t =
355 * {@link ReadGraph#getSingleType(subject, Value)}
357 * @param subject a resource
359 * @throws DoesNotContainValueException if the subject did not contain a
361 * @throws ServiceException on connection and database failure
362 * @see AsyncReadGraph#forValue
364 <T> T getValue(Resource subject) throws DoesNotContainValueException, ServiceException;
367 * Gets a value associated to subject as a Variant. Infers {@link Binding} from type t =
368 * {@link ReadGraph#getSingleType(subject, Value)}
370 * @param subject a resource
372 * @throws DoesNotContainValueException if the subject did not contain a
374 * @throws ServiceException on connection and database failure
375 * @see AsyncReadGraph#forValue
377 Variant getVariantValue(Resource subject) throws DoesNotContainValueException, ServiceException;
380 * Gets a value associated to subject using the given {@link Binding}.
382 * @param subject a resource
383 * @param binding a binding
385 * @throws DoesNotContainValueException if the subject did not contain a
387 * @throws BindingException if value could not be produced using the given
389 * @throws ServiceException on connection and database failure
390 * @see AsyncReadGraph#forValue
392 <T> T getValue(Resource subject, Binding binding) throws DoesNotContainValueException, BindingException,
396 * Gets a single value associated to o such that (subject, r, o) and
397 * {@link ReadGraph#isSubrelationOf(r, relation)}. Assumes a single value.
398 * Infers {@link Binding} from type t =
399 * {@link ReadGraph#getSingleType(o, Value)}
401 * @param subject a resource
402 * @param relation a resource
404 * @throws NoSingleResultException if the amount of valid values was not one
405 * @throws DoesNotContainValueException if suitable o did not contain a
407 * @throws ServiceException on connection and database failure
408 * @see AsyncReadGraph#forRelatedValue
410 <T> T getRelatedValue(Resource subject, Resource relation) throws NoSingleResultException,
411 DoesNotContainValueException, ServiceException;
414 * Gets a single value associated to o such that (subject, r, o) and
415 * {@link ReadGraph#isSubrelationOf(r, relation)} as a Variant. Assumes a single value.
416 * Infers {@link Binding} from type t =
417 * {@link ReadGraph#getSingleType(o, Value)}
419 * @param subject a resource
420 * @param relation a resource
422 * @throws NoSingleResultException if the amount of valid values was not one
423 * @throws DoesNotContainValueException if suitable o did not contain a
425 * @throws ServiceException on connection and database failure
426 * @see AsyncReadGraph#forRelatedValue
428 Variant getRelatedVariantValue(Resource subject, Resource relation) throws NoSingleResultException,
429 DoesNotContainValueException, ServiceException;
432 * Gets a single value associated to o such that (subject, r, o) and
433 * {@link ReadGraph#isSubrelationOf(r, relation)}. Uses the given
434 * {@link Binding}. Assumes a single value.
436 * @param subject a resource
437 * @param relation a resource
439 * @throws NoSingleResultException if the amount of valid values was not one
440 * @throws DoesNotContainValueException if suitable o did not contain a
442 * @throws BindingException if value could not be produced using the given
444 * @throws ServiceException on connection and database failure
445 * @see AsyncReadGraph#forRelatedValue
447 <T> T getRelatedValue(Resource subject, Resource relation, Binding binding) throws NoSingleResultException,
448 DoesNotContainValueException, BindingException, ServiceException;
451 * Tries to adapt the specified resource into an instance of the specified
452 * class T. No guarantees are made on return values of this method. The
453 * returned values can be cached results of previous invocation or they can
454 * be new result object instances. See {@link #adaptUnique(Resource, Class)}
455 * for alternative behaviour.
457 * @param resource a resource
458 * @param clazz the adapter class
460 * @throws AdaptionException if suitable adapter was not found
461 * @throws ValidationException from the adapter
462 * @throws ServiceException on connection and database failure
463 * @see AsyncReadGraph#forAdapted
464 * @see #adaptUnique(Resource, Class)
466 <T> T adapt(Resource resource, Class<T> clazz) throws AdaptionException, ValidationException, ServiceException;
470 * Same as: adapt(getSingleObject(resource, relation), clazz);
472 * @param resource a resource
473 * @param relation a resource
474 * @param clazz the adapter class
476 * @throws AdaptionException if suitable adapter was not found
477 * @throws ValidationException from the adapter
478 * @throws ServiceException on connection and database failure
479 * @see AsyncReadGraph#forAdapted
480 * @see #adaptUnique(Resource, Class)
482 <T> T adaptRelated(Resource resource, Resource relation, Class<T> clazz) throws AdaptionException, NoSingleResultException, ValidationException, ServiceException;
488 * Resource r = getPossibleObject(resource, relation);
489 * if(r == null) return null;
490 * return getPossibleAdapter(r, clazz);
492 * @param resource a resource
493 * @param relation a resource
494 * @param clazz the adapter class
496 * @throws AdaptionException if suitable adapter was not found
497 * @throws ValidationException from the adapter
498 * @throws ServiceException on connection and database failure
499 * @see AsyncReadGraph#forAdapted
500 * @see #adaptUnique(Resource, Class)
502 <T> T getPossibleRelatedAdapter(Resource resource, Resource relation, Class<T> clazz) throws ValidationException, ServiceException;
504 <T,C> T adaptContextual(Resource resource, C context, Class<C> contextClass, Class<T> clazz) throws AdaptionException, NoSingleResultException, ValidationException, ServiceException;
505 <T,C> T getPossibleContextualAdapter(Resource resource, C context, Class<C> contextClass, Class<T> clazz) throws ValidationException, ServiceException;
508 * Tries to adapt the specified resource into an instance of the specified
509 * class T. The difference to {@link #adapt(Resource, Class)} is that this
510 * method does everything possible to return a new object instance for each
511 * separate invocation.
514 * The only case when this cannot be guaranteed is when the adaption result
515 * comes from an {@link Adapter} implementation which can internally do
516 * anything, like always return the same singleton instance.
519 * @param resource a resource
520 * @param clazz the adapter class
522 * @throws AdaptionException if suitable adapter was not found
523 * @throws ValidationException from the adapter
524 * @throws ServiceException on connection and database failure
525 * @see AsyncReadGraph#forAdapted
526 * @see #adapt(Resource, Class)
528 <T> T adaptUnique(Resource resource, Class<T> clazz) throws AdaptionException, ValidationException,
532 * As {@link #getInverse} but returns null instead of an exception if
533 * inverse was not found.
535 * @param relation a resource
536 * @return the inverse or null
537 * @throws ManyObjectsForFunctionalRelationException on invalid graph with
538 * more than one functional object
539 * @throws ServiceException on connection and database failures
540 * @see AsyncReadGraph#forPossibleInverse
542 Resource getPossibleInverse(Resource relation) throws ManyObjectsForFunctionalRelationException, ServiceException;
545 * As {@link #getSingleObject} but returns null instead of an exception if
546 * object was not found.
548 * @param subject a resource
549 * @param relation a resource
550 * @return the object or null
551 * @throws ManyObjectsForFunctionalRelationException on invalid graph with
552 * more than one functional object
553 * @throws ServiceException on connection and database failures
554 * @see AsyncReadGraph#forPossibleObject
556 Resource getPossibleObject(Resource subject, Resource relation) throws ManyObjectsForFunctionalRelationException,
560 * As {@link #getSingleStatement} but returns null instead of an exception
561 * if statement was not found.
563 * @param subject a resource
564 * @param relation a resource
565 * @return the statement or null
566 * @throws ManyObjectsForFunctionalRelationException on invalid graph with
567 * more than one functional object
568 * @throws ServiceException on connection and database failures
569 * @see AsyncReadGraph#forPossibleStatement
571 Statement getPossibleStatement(Resource subject, Resource relation)
572 throws ManyObjectsForFunctionalRelationException, ServiceException;
575 * As {@link #getSingleType} but returns null instead of an exception if
576 * type was not found.
578 * @param subject a resource
579 * @param baseType a resource
580 * @return the type or null
581 * @throws ServiceException on connection and database failures
582 * @see AsyncReadGraph#forPossibleType
584 Resource getPossibleType(Resource subject, Resource baseType) throws ServiceException;
587 * As {@link #getValue} but returns null instead of an exception if value
590 * @param subject a resource
591 * @return the value or null
592 * @throws ServiceException on connection and database failures
593 * @see AsyncReadGraph#forPossibleValue
595 <T> T getPossibleValue(Resource subject) throws ServiceException;
598 * As {@link #getValue} but returns null instead of an exception if value
601 * @param subject a resource
602 * @param binding a {@link Binding}
603 * @return the value or null
604 * @throws BindingException if value could not be produced using the given
606 * @throws ServiceException on connection and database failures
607 * @see AsyncReadGraph#forPossibleValue
609 <T> T getPossibleValue(Resource subject, Binding binding) throws BindingException, ServiceException;
612 * As {@link #getPossibleRelatedValue} but returns null instead of an
613 * exception if value was not found.
615 * @param subject a resource
616 * @param relation a resource
617 * @return the value or null
618 * @throws ManyObjectsForFunctionalRelationException on invalid graph with
619 * more than one functional object
620 * @throws ServiceException on connection and database failures
621 * @see AsyncReadGraph#forPossibleRelatedValue
623 <T> T getPossibleRelatedValue(Resource subject, Resource relation)
624 throws ManyObjectsForFunctionalRelationException, ServiceException;
627 * As {@link #getPossibleRelatedValue} but returns null instead of an
628 * exception if value was not found.
630 * @param subject a resource
631 * @param relation a resource
632 * @param binding a {@link Binding}
633 * @return the value or null
634 * @throws ManyObjectsForFunctionalRelationException on invalid graph with
635 * more than one functional object
636 * @throws BindingException if value could not be produced using the given
638 * @throws ServiceException on connection and database failures
639 * @see AsyncReadGraph#forPossibleRelatedValue
641 <T> T getPossibleRelatedValue(Resource subject, Resource relation, Binding binding)
642 throws ManyObjectsForFunctionalRelationException, BindingException, ServiceException;
645 * As {@link #adapt} but returns null instead of an exception if adapter was
648 * @param subject a resource
649 * @param clazz a Class
650 * @return the adapter or null
651 * @throws ValidationException when ?
652 * @throws ServiceException on connection and database failures
653 * @see {@link AsyncReadGraph#forPossibleAdapted}
655 <T> T getPossibleAdapter(Resource resource, Class<T> clazz) throws ValidationException, ServiceException;
658 * As {@link #adaptUnique} but returns null instead of an exception if
659 * adapter was not found
661 * @param subject a resource
662 * @param clazz a Class
663 * @return the adapter or null
664 * @throws ValidationException when ?
665 * @throws ServiceException on connection and database failures
666 * @see {@link AsyncReadGraph#forPossibleAdapted}
668 <T> T getPossibleUniqueAdapter(Resource resource, Class<T> clazz) throws ValidationException, ServiceException;
671 * Returns true if type is included in the result of {@link #getTypes(resource)}
673 * @param subject a resource
674 * @param type a resource
675 * @return indicates if resource is an instance of type
676 * @throws ServiceException on connection and database failures
677 * @see {@link AsyncReadGraph#forIsInstanceOf}
679 boolean isInstanceOf(Resource resource, Resource type) throws ServiceException;
682 * Returns true if type equals resource or type is included in the result of
683 * {@link #getSupertypes(resource)}
685 * @param subject a resource
686 * @param type a resource
687 * @return indicates if resource is inherited from type
688 * @throws ServiceException on connection and database failures
689 * @see {@link AsyncReadGraph#forIsInheritedFrom}
691 boolean isInheritedFrom(Resource resource, Resource type) throws ServiceException;
694 * Returns true if relation equals resource or relation is included in the result of
695 * {@link #getSuperrelations(resource)}
697 * @param subject a resource
698 * @param relation a resource
699 * @return indicates if resource is a subrelation of relation
700 * @throws ServiceException on connection and database failures
701 * @see {@link AsyncReadGraph#forIsSubrelationOf}
703 boolean isSubrelationOf(Resource resource, Resource relation) throws ServiceException;
706 * Returns true if the result of {@link #getStatements(subject, IsWeaklyRelatedTo)} is nonempty.
708 * @param subject a resource
709 * @return indicates that subject has statements
710 * @throws ServiceException on connection and database failures
711 * @see {@link AsyncReadGraph#forHasStatement}
713 boolean hasStatement(Resource subject) throws ServiceException;
716 * Returns true if the result of {@link #getStatements(subject, relation)} is nonempty.
718 * @param subject a resource
719 * @param relation a resource
720 * @return indicates that subject has statements with predicates as subrelation of relation
721 * @throws ServiceException on connection and database failures
722 * @see {@link AsyncReadGraph#forHasStatement}
724 boolean hasStatement(Resource subject, Resource relation) throws ServiceException;
727 * Returns true if a statement (subject, relation, object) exists after assertions.
729 * @param subject a resource
730 * @param relation a resource
731 * @param object a resource
732 * @return indicates that the given statement exists
733 * @throws ServiceException on connection and database failures
734 * @see {@link AsyncReadGraph#forHasStatement}
736 boolean hasStatement(Resource subject, Resource relation, Resource object) throws ServiceException;
739 * Returns true if there is a value associated with subject.
740 * IMPLEMENTATION NOTE:
741 * Current implementation fetches the value from server. If the value is
742 * large (i.e. not stored in the cluster) this is highly inefficient.
744 * @param subject a resource
745 * @return indicates that a value exists
746 * @throws ServiceException on connection and database failures
747 * @see {@link AsyncReadGraph#forHasValue}
749 boolean hasValue(Resource subject) throws ServiceException;
752 * Returns the data type of the literal.
755 * @throws DatabaseException
757 Datatype getDataType(Resource subject) throws DatabaseException;
760 * Returns an accessory that can be used to partially read the literal
761 * or write if the graph is WriteGraph. The returned accessory is closed
762 * automatically when the transaction ends. The modifications are written
763 * back to graph at transaction completion.
765 * @param <T> is typed accessory for modifying the literal value.
766 * @param resource is the literal containing the value.
767 * @return interface to partially read and write the literal value.
768 * @throws DatabaseException
770 <T extends Accessor> T getAccessor(Resource resource) throws DatabaseException;
773 * Returns an RandomAccessBinary that can be used to partially read the literal
774 * or write if the graph is WriteGraph. The returned interface is closed
775 * automatically when the transaction ends. The modifications are written
776 * back to graph at transaction completion.
779 * @param resource is the literal containing the value.
780 * @return interface to partially read and write the literal value.
781 * @throws DatabaseException
783 RandomAccessBinary getRandomAccessBinary(Resource resource) throws DatabaseException;
784 // @SuppressWarnings("rawtypes")
785 // Function getValueFunction(Resource resource) throws DatabaseException;
788 * Get the value associated with a graph {@link Resource}, using a possible context object and
789 * a default data type binding. An exception is thrown, if the value is not found.
791 * See {@link #getValue2(Resource, Object, Binding)} for more details.
793 * @param r A graph resource with which the value is associated
794 * @param context A context object that is used for acquiring the value, can be {@code null}
795 * @return The value of the graph node.
796 * @throws DoesNotContainValueException No value is associated with the graph node.
797 * @throws DatabaseException Other errors, such as an error in casting the value to the return type or
798 * a runtime error in the value function.
799 * @see #getValue2(Resource, Object, Binding)
800 * @see #getPossibleValue2(Resource, Object)
802 <T> T getValue2(Resource subject, Object context) throws DatabaseException;
805 * Get the value associated with a graph {@link Resource}, using a possible context object and
806 * a default data type binding as a Variant. An exception is thrown, if the value is not found.
808 * See {@link #getValue2(Resource, Object, Binding)} for more details.
810 * @param r A graph resource with which the value is associated
811 * @param context A context object that is used for acquiring the value, can be {@code null}
812 * @return The value of the graph node.
813 * @throws DoesNotContainValueException No value is associated with the graph node.
814 * @throws DatabaseException Other errors, such as an error in casting the value to the return type or
815 * a runtime error in the value function.
816 * @see #getValue2(Resource, Object, Binding)
817 * @see #getPossibleValue2(Resource, Object)
819 Variant getVariantValue2( Resource r, Object context ) throws DatabaseException;
822 * Get a possible value associated with a graph {@link Resource}, using a possible context object and
823 * a desired value binding. Unlike {@link #getValue2(Resource, Object)}, this methods
824 * returns {@code null} for missing values instead of throwing an exception.
826 * See {@link #getValue2(Resource, Object, Binding)} for more details.
828 * @param r A graph resource with which the value is associated
829 * @param context A context object that is used for acquiring the value, can be {@code null}
830 * @return The value of the graph node.
831 * @throws DatabaseException Usually should not happen. A null value is returned for possible errors.
832 * @see #getValue2(Resource, Object)
833 * @see #getPossibleValue2(Resource, Object, Binding)
835 <T> T getPossibleValue2(Resource subject, Object context) throws DatabaseException;
838 * Get the value associated with a graph {@link Resource}, using a possible context object and
839 * a desired value binding. An exception is thrown, if the value is not found.
841 * The following methods are tried in order to retrieve the value:
843 * <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>
844 * <li>If the resource is a {@code L0.ExternalValue}, the value is acquired using
845 * {@link ReflectionUtils#getValue(String)} with the resource URI.</li>
846 * <li>If the resource is associated with a suitable value converter with relation {@code L0.ConvertsToValueWith}
847 * (see {@link #requestValueFunction(Resource)}), the value function is called with the graph, the resource
848 * and the context object.</li>
851 * @param r A graph resource with which the value is associated
852 * @param context A context object that is used for acquiring the value, can be {@code null}
853 * @param binding A binding for the value type
854 * @return The value of the graph node.
855 * @throws DoesNotContainValueException No value is associated with the graph node.
856 * @throws DatabaseException Other errors, such as an error in casting the value to the return type or
857 * a runtime error in the value function.
858 * @see #getValue2(Resource, Object)
859 * @see #getPossibleValue2(Resource, Object, Binding)
861 <T> T getValue2(Resource subject, Object context, Binding binding) throws DatabaseException;
864 * Get a possible value associated with a graph {@link Resource}, using a possible context object and
865 * a desired value binding. Unlike {@link #getValue2(Resource, Object, Binding)}, this methods
866 * returns {@code null} for missing values instead of throwing an exception.
868 * See {@link #getValue2(Resource, Object, Binding)} for more details.
870 * @param r A graph resource with which the value is associated
871 * @param context A context object that is used for acquiring the value, can be {@code null}
872 * @param binding A binding for the value type
873 * @return The value of the graph node.
874 * @throws DatabaseException Usually should not happen. A null value is returned for possible errors.
875 * @see #getValue2(Resource, Object, Bindinge)
876 * @see #getPossibleValue2(Resource, Object)
878 <T> T getPossibleValue2(Resource subject, Object context, Binding binding) throws DatabaseException;
881 * Get the single value associated with a graph resource related with a given subject.
882 * An exception is thrown, if a unique object resource or a value for it is not found.
884 * See {@link #getValue2(Resource, Object, Binding)} for more details.
886 * @param subject A graph resource that indicates the subject node
887 * @param relation A graph resource that indicates the predicate of a relation
888 * @return The value of the unique graph node that is asserted as the object of the given subject and predicate.
889 * @throws NoSingleResultException The number of suitable object resources is not equal to 1 (zero or greater than one)
890 * @throws DoesNotContainValueException No value is associated with the graph node.
891 * @throws DatabaseException Other errors, such as an error in casting the value to the return type or
892 * a runtime error in the value function.
893 * @see #getRelatedValue2(Resource, Resource, Binding)
894 * @see #getRelatedValue2(Resource, Resource, Object)
895 * @see #getRelatedValue2(Resource, Resource, Object, Binding)
896 * @see #getPossibleRelatedValue2(Resource, Resource)
898 <T> T getRelatedValue2(Resource subject, Resource relation) throws DatabaseException;
901 * Get a possible single value associated with a graph resource related with a given subject.
902 * A {@code null} value is returned for missing values or other errors.
904 * See {@link #getValue2(Resource, Object, Binding)} for more details.
906 * @param subject A graph resource that indicates the subject node
907 * @param relation A graph resource that indicates the predicate of a relation
908 * @return The value of the unique graph node that is asserted as the object of the given subject and predicate.
909 * @throws DatabaseException Usually should not happen. A {@code null} value is returned for possible errors.
910 * @see #getPossibleRelatedValue2(Resource, Resource, Binding)
911 * @see #getPossibleRelatedValue2(Resource, Resource, Object)
912 * @see #getPossibleRelatedValue2(Resource, Resource, Object, Binding)
913 * @see #getRelatedValue2(Resource, Resource)
915 <T> T getPossibleRelatedValue2(Resource subject, Resource relation) throws DatabaseException;
918 * Get a possible single value associated with a graph resource related with a given subject.
919 * A {@code null} value is returned for missing values or other errors.
921 * See {@link #getValue2(Resource, Object, Binding)} for more details.
923 * @param subject A graph resource that indicates the subject node
924 * @param relation A graph resource that indicates the predicate of a relation
925 * @return The value of the unique graph node that is asserted as the object of the given subject and predicate.
926 * @throws DatabaseException Usually should not happen. A {@code null} value is returned for possible errors.
927 * @see #getPossibleRelatedValue2(Resource, Resource, Binding)
928 * @see #getPossibleRelatedValue2(Resource, Resource, Object)
929 * @see #getPossibleRelatedValue2(Resource, Resource, Object, Binding)
930 * @see #getRelatedValue2(Resource, Resource)
932 Variant getRelatedVariantValue2( Resource subject, Resource relation ) throws DatabaseException;
935 * Get the single value associated with a graph resource related with a given subject, a possible context object.
936 * An exception is thrown, if a unique object resource or a value for it is not found.
938 * See {@link #getValue2(Resource, Object, Binding)} for more details.
940 * @param subject A graph resource that indicates the subject node
941 * @param relation A graph resource that indicates the predicate of a relation
942 * @param context A context object that is used for acquiring the value, can be {@code null}
943 * @return The value of the unique graph node that is asserted as the object of the given subject and predicate.
944 * @throws NoSingleResultException The number of suitable object resources is not equal to 1 (zero or greater than one)
945 * @throws DoesNotContainValueException No value is associated with the graph node.
946 * @throws DatabaseException Other errors, such as an error in casting the value to the return type or
947 * a runtime error in the value function.
948 * @see #getRelatedValue2(Resource, Resource)
949 * @see #getRelatedValue2(Resource, Resource, Binding)
950 * @see #getRelatedValue2(Resource, Resource, Object, Binding)
951 * @see #getPossibleRelatedValue2(Resource, Resource, Object)
953 <T> T getRelatedValue2(Resource subject, Resource relation, Object context) throws DatabaseException;
956 * Get the single value associated with a graph resource related with a given subject, a possible context object.
957 * An exception is thrown, if a unique object resource or a value for it is not found.
959 * See {@link #getValue2(Resource, Object, Binding)} for more details.
961 * @param subject A graph resource that indicates the subject node
962 * @param relation A graph resource that indicates the predicate of a relation
963 * @param context A context object that is used for acquiring the value, can be {@code null}
964 * @return The value of the unique graph node that is asserted as the object of the given subject and predicate.
965 * @throws NoSingleResultException The number of suitable object resources is not equal to 1 (zero or greater than one)
966 * @throws DoesNotContainValueException No value is associated with the graph node.
967 * @throws DatabaseException Other errors, such as an error in casting the value to the return type or
968 * a runtime error in the value function.
969 * @see #getRelatedValue2(Resource, Resource, Object)
970 * @see #getPossibleRelatedValue2(Resource, Resource, Object)
972 Variant getRelatedVariantValue2( Resource subject, Resource relation, Object context ) throws DatabaseException;
975 * Get a possible single value associated with a graph resource related with a given subject and a possible context object.
976 * A {@code null} value is returned for missing values or other errors.
978 * See {@link #getValue2(Resource, Object, Binding)} for more details.
980 * @param subject A graph resource that indicates the subject node
981 * @param relation A graph resource that indicates the predicate of a relation
982 * @param context A context object that is used for acquiring the value, can be {@code null}
983 * @return The value of the unique graph node that is asserted as the object of the given subject and predicate.
984 * @throws DatabaseException Usually should not happen. A {@code null} value is returned for possible errors.
985 * @see #getPossibleRelatedValue2(Resource, Resource)
986 * @see #getPossibleRelatedValue2(Resource, Resource, Binding)
987 * @see #getPossibleRelatedValue2(Resource, Resource, Object, Binding)
988 * @see #getRelatedValue2(Resource, Resource, Object)
990 <T> T getPossibleRelatedValue2(Resource subject, Resource relation, Object context) throws DatabaseException;
993 * Get the single value associated with a graph resource related with a given subject and
994 * a desired value binding. An exception is thrown, if a unique object resource or a value for it is not found.
996 * See {@link #getValue2(Resource, Object, Binding)} for more details.
998 * @param subject A graph resource that indicates the subject node
999 * @param relation A graph resource that indicates the predicate of a relation
1000 * @param binding A binding for the value type
1001 * @return The value of the unique graph node that is asserted as the object of the given subject and predicate.
1002 * @throws NoSingleResultException The number of suitable object resources is not equal to 1 (zero or greater than one)
1003 * @throws DoesNotContainValueException No value is associated with the graph node.
1004 * @throws DatabaseException Other errors, such as an error in casting the value to the return type or
1005 * a runtime error in the value function.
1006 * @see #getRelatedValue2(Resource, Resource)
1007 * @see #getRelatedValue2(Resource, Resource, Object)
1008 * @see #getRelatedValue2(Resource, Resource, Object, Binding)
1009 * @see #getPossibleRelatedValue2(Resource, Resource, Binding)
1011 <T> T getRelatedValue2(Resource subject, Resource relation, Binding binding) throws DatabaseException;
1014 * Get a possible single value associated with a graph resource related with a given subject and
1015 * a desired value binding. A {@code null} value is returned for missing values or other errors.
1017 * See {@link #getValue2(Resource, Object, Binding)} for more details.
1019 * @param subject A graph resource that indicates the subject node
1020 * @param relation A graph resource that indicates the predicate of a relation
1021 * @param binding A binding for the value type
1022 * @return The value of the unique graph node that is asserted as the object of the given subject and predicate.
1023 * @throws DatabaseException Usually should not happen. A {@code null} value is returned for possible errors.
1024 * @see #getPossibleRelatedValue2(Resource, Resource)
1025 * @see #getPossibleRelatedValue2(Resource, Resource, Object)
1026 * @see #getPossibleRelatedValue2(Resource, Resource, Object, Binding)
1027 * @see #getRelatedValue2(Resource, Resource, Binding)
1029 <T> T getPossibleRelatedValue2(Resource subject, Resource relation, Binding binding) throws DatabaseException;
1032 * Get the single value associated with a graph resource related with a given subject, a possible context object and
1033 * a desired value binding. An exception is thrown, if a unique object resource or a value for it is not found.
1035 * See {@link #getValue2(Resource, Object, Binding)} for more details.
1037 * @param subject A graph resource that indicates the subject node
1038 * @param relation A graph resource that indicates the predicate of a relation
1039 * @param context A context object that is used for acquiring the value, can be {@code null}
1040 * @param binding A binding for the value type
1041 * @return The value of the unique graph node that is asserted as the object of the given subject and predicate.
1042 * @throws NoSingleResultException The number of suitable object resources is not equal to 1 (zero or greater than one)
1043 * @throws DoesNotContainValueException No value is associated with the graph node.
1044 * @throws DatabaseException Other errors, such as an error in casting the value to the return type or
1045 * a runtime error in the value function.
1046 * @see #getRelatedValue2(Resource, Resource)
1047 * @see #getRelatedValue2(Resource, Resource, Binding)
1048 * @see #getRelatedValue2(Resource, Resource, Object)
1049 * @see #getPossibleRelatedValue2(Resource, Resource, Object, Binding)
1051 <T> T getRelatedValue2(Resource subject, Resource relation, Object context, Binding binding) throws DatabaseException;
1054 * Get a possible single value associated with a graph resource related with a given subject, a possible context object and
1055 * a desired value binding. A {@code null} value is returned for missing values or other errors.
1057 * See {@link #getValue2(Resource, Object, Binding)} for more details.
1059 * @param subject A graph resource that indicates the subject node
1060 * @param relation A graph resource that indicates the predicate of a relation
1061 * @param context A context object that is used for acquiring the value, can be {@code null}
1062 * @param binding A binding for the value type
1063 * @return The value of the unique graph node that is asserted as the object of the given subject and predicate.
1064 * @throws DatabaseException Usually should not happen. A {@code null} value is returned for possible errors.
1065 * @see #getPossibleRelatedValue2(Resource, Resource)
1066 * @see #getPossibleRelatedValue2(Resource, Resource, Binding)
1067 * @see #getPossibleRelatedValue2(Resource, Resource, Object)
1068 * @see #getRelatedValue2(Resource, Resource, Object, Binding)
1070 <T> T getPossibleRelatedValue2(Resource subject, Resource relation, Object context, Binding binding) throws DatabaseException;
1073 * Get the parsed SCL type declaration from the string value of a graph resource that is the unique object of a
1074 * given subject and predicate.
1076 * See {@link #getValue2(Resource, Object, Binding)} for more details.
1078 * @param subject A resource that indicates the subject of a statement
1079 * @param relation A resource that indicates the predicate of the statement
1080 * @return A compiled SCL type definition of the string value of a unique object resource
1081 * @throws DatabaseException For any errors in locating a unique value or compiling it as an SCL type statement
1083 Type getRelatedValueType(Resource subject, Resource relation) throws DatabaseException;
1085 boolean setSynchronous(boolean value);
1086 boolean getSynchronous();