1 /*******************************************************************************
\r
2 * Copyright (c) 2007, 2010 Association for Decentralized Information Management
\r
3 * in Industry THTH ry.
\r
4 * All rights reserved. This program and the accompanying materials
\r
5 * are made available under the terms of the Eclipse Public License v1.0
\r
6 * which accompanies this distribution, and is available at
\r
7 * http://www.eclipse.org/legal/epl-v10.html
\r
10 * VTT Technical Research Centre of Finland - initial API and implementation
\r
11 *******************************************************************************/
\r
12 package org.simantics.db;
\r
14 import java.util.Collection;
\r
15 import java.util.Set;
\r
17 import org.simantics.databoard.accessor.Accessor;
\r
18 import org.simantics.databoard.binding.Binding;
\r
19 import org.simantics.databoard.binding.mutable.Variant;
\r
20 import org.simantics.databoard.type.Datatype;
\r
21 import org.simantics.databoard.util.binary.RandomAccessBinary;
\r
22 import org.simantics.db.adaption.Adapter;
\r
23 import org.simantics.db.exception.AdaptionException;
\r
24 import org.simantics.db.exception.AssumptionException;
\r
25 import org.simantics.db.exception.BindingException;
\r
26 import org.simantics.db.exception.DatabaseException;
\r
27 import org.simantics.db.exception.DoesNotContainValueException;
\r
28 import org.simantics.db.exception.ManyObjectsForFunctionalRelationException;
\r
29 import org.simantics.db.exception.NoInverseException;
\r
30 import org.simantics.db.exception.NoSingleResultException;
\r
31 import org.simantics.db.exception.ResourceNotFoundException;
\r
32 import org.simantics.db.exception.ServiceException;
\r
33 import org.simantics.db.exception.ValidationException;
\r
34 import org.simantics.db.procedure.SyncListener;
\r
35 import org.simantics.db.procedure.SyncMultiListener;
\r
36 import org.simantics.db.procedure.SyncMultiProcedure;
\r
37 import org.simantics.db.procedure.SyncProcedure;
\r
38 import org.simantics.db.procedure.SyncSetListener;
\r
39 import org.simantics.db.request.MultiRead;
\r
40 import org.simantics.db.request.Read;
\r
41 import org.simantics.scl.compiler.types.Type;
\r
45 * For accessing and manipulating the graph data in synchronous manner. A client
\r
46 * receives ReadGraph instances for performing requests in {@link Read} and
\r
47 * {@link MultiRead} as well as for reacting to request results using
\r
48 * {@link SyncProcedure}, {@link SyncListener}, {@link SyncMultiProcedure},
\r
49 * {@link SyncMultiListener} and {@link SyncSetListener}
\r
51 * ReadGraph instances are stateful and may not be stored and used outside the
\r
52 * supplier method activation. The methods receiving ReadGraph should not block
\r
53 * for long periods of time since that may delay the processing of other
\r
54 * requests. For an asynchronous counterpart with the same functionality as
\r
55 * ReadGraph see {@link AsyncReadGraph}
\r
58 * All collections returned by the methods on this interface must not be
\r
59 * modified by clients unless explicitly stated otherwise.
\r
62 * @author Antti Villberg
\r
63 * @see RequestProcessor
\r
64 * @see AsyncRequestProcessor
\r
65 * @see AsyncReadGraph
\r
70 public interface ReadGraph extends AsyncReadGraph, RequestProcessor {
\r
74 * @see AsyncReadGraph#forURI
\r
76 String getURI(Resource resource) throws AssumptionException, ValidationException, ServiceException;
\r
77 String getPossibleURI(Resource resource) throws ValidationException, ServiceException;
\r
80 * Gets a unique resource associated to the given identifier. See <a
\r
81 * href="https://www.simantics.org/wiki/index.php/URI">Simantics Wiki page
\r
82 * on URIs</a> for more details.
\r
84 * @param uri the identifier
\r
85 * @return the resource
\r
86 * @throws ResourceNotFoundException if a resource for the given identifier
\r
88 * @throws ValidationException if a resource could not be produced due to
\r
90 * @throws ServiceException on connection and database failures
\r
91 * @see AsyncReadGraph#forResourceByURI
\r
93 Resource getResource(String uri) throws ResourceNotFoundException, ValidationException, ServiceException;
\r
96 * Gets a unique resource associated to the given identifier. See <a
\r
97 * href="https://www.simantics.org/wiki/index.php/URI">Simantics Wiki page
\r
98 * on URIs</a> for more details.
\r
100 * @param uri the identifier
\r
101 * @return the resource
\r
102 * @throws ResourceNotFoundException if a resource for the given identifier
\r
103 * was not specified
\r
104 * @throws ValidationException if a resource could not be produced due to
\r
105 * invalid semantics
\r
106 * @throws ServiceException on connection and database failures
\r
107 * @see AsyncReadGraph#forResourceByURI
\r
109 Resource getPossibleResource(String uri) throws ResourceNotFoundException, ValidationException, ServiceException;
\r
112 * Gets a builtin resource. For a list of builtin resources see TODO Wiki
\r
114 * @param uri the identifier
\r
115 * @return the resource
\r
116 * @throws ResourceNotFoundException if resouce was not found
\r
117 * @throws ServiceException on connection and database failures
\r
118 * @see AsyncReadGraph#forBuiltin
\r
120 Resource getBuiltin(String id) throws ResourceNotFoundException, ServiceException;
\r
123 * Gets all statements (subject, p, o) such that
\r
124 * {@link ReadGraph#isSubrelationOf(p, relation)} returns true. The result
\r
125 * may include asserted statements for which s does not equal subject. See
\r
126 * the assertion mechanisn TODO for more details. If the relation is
\r
127 * functional the request returns a single statement according to the
\r
128 * functional statement shadowing rules TODO if possible. If an invalid
\r
129 * graph is encountered an exception is thrown.
\r
131 * @param subject a resource
\r
132 * @param relation a resource
\r
133 * @return the statements
\r
134 * @throws ManyObjectsForFunctionalRelationException on invalid graph with
\r
135 * more than one functional object
\r
136 * @throws ServiceException on connection and database failures
\r
137 * @see AsyncReadGraph#forEachStatement
\r
138 * @see AsyncReadGraph#forStatementSet
\r
140 Collection<Statement> getStatements(Resource subject, Resource relation)
\r
141 throws ManyObjectsForFunctionalRelationException, ServiceException;
\r
144 * Gets all statements (s, p, o) asserted by subject such that
\r
145 * {@link ReadGraph#isSubrelationOf(p, relation)} returns true. See the
\r
146 * assertion mechanism TODO for more details. If the relation is functional
\r
147 * the request returns a single statement according to the functional
\r
148 * statement shadowing rules TODO if possible. If an invalid graph is
\r
149 * encountered an exception is thrown.
\r
151 * @param subject a resource
\r
152 * @param relation a resource
\r
153 * @return the statements
\r
154 * @throws ManyObjectsForFunctionalRelationException on invalid graph with
\r
155 * more than one functional object
\r
156 * @throws ServiceException on connection and database failures
\r
157 * @see AsyncReadGraph#forEachAssertedStatement
\r
158 * @see AsyncReadGraph#forAssertedStatementSet
\r
160 Collection<Statement> getAssertedStatements(Resource subject, Resource relation)
\r
161 throws ManyObjectsForFunctionalRelationException, ServiceException;
\r
164 * Gets all predicates p from statements (subject, p, o) such that
\r
165 * {@link ReadGraph#isSubrelationOf(p, relation)} returns true. See the
\r
166 * assertion mechanism TODO for more details. If the relation is functional
\r
167 * the request returns a single statement according to the functional
\r
168 * statement shadowing rules TODO if possible. If an invalid graph is
\r
169 * encountered an exception is thrown.
\r
171 * @param subject a resource
\r
172 * @param relation a resource
\r
173 * @return the predicates
\r
174 * @throws ManyObjectsForFunctionalRelationException on invalid graph with
\r
175 * more than one object
\r
176 * @throws ServiceException on connection and database failures
\r
177 * @see AsyncReadGraph#forEachPredicate
\r
178 * @see AsyncReadGraph#forPredicateSet
\r
180 Collection<Resource> getPredicates(Resource subject) throws ServiceException;
\r
183 * Gets a subset of all types of the subject such that no pair of returned
\r
184 * types inherit each other and all types of the subject are supertypes
\r
185 * of some type in the returned set.
\r
187 * @param subject a resource
\r
188 * @return the principal types
\r
189 * @throws ServiceException on connection and database failures
\r
190 * @see AsyncReadGraph#forEachPrincipalType
\r
191 * @see AsyncReadGraph#forPrincipalTypeSet
\r
193 Collection<Resource> getPrincipalTypes(Resource subject) throws ServiceException;
\r
196 * Gets the full type hierarchy for subject.
\r
198 * @param subject a resource
\r
199 * @return the type hierarchy
\r
200 * @throws ServiceException on connection and database failures
\r
201 * @see AsyncReadGraph#forTypes
\r
203 Set<Resource> getTypes(Resource subject) throws ServiceException;
\r
206 * Gets the full supertype hierarchy for subject.
\r
208 * @param subject a resource
\r
209 * @return the supertype hierarchy
\r
210 * @throws ServiceException on connection and database failures
\r
211 * @see AsyncReadGraph#forSupertypes
\r
213 Set<Resource> getSupertypes(Resource subject) throws ServiceException;
\r
216 * Gets the full superrelation hierarchy for subject.
\r
218 * @param subject a resource
\r
219 * @return the superrelation hierarchy
\r
220 * @throws ServiceException on connection and database failures
\r
221 * @see AsyncReadGraph#forSuperrelations
\r
223 Set<Resource> getSuperrelations(Resource subject) throws ServiceException;
\r
224 Resource getPossibleSuperrelation(Resource subject) throws ServiceException;
\r
227 * Gets all objects o from statements (subject, p, o) such that
\r
228 * {@link ReadGraph#isSubrelationOf(p, relation)} returns true. See the
\r
229 * assertion mechanisn TODO for more details. If the relation is functional
\r
230 * the request returns a single object according to the functional statement
\r
231 * shadowing rules TODO if possible. If an invalid graph is encountered an
\r
232 * exception is thrown.
\r
234 * @param subject a resource
\r
235 * @param relation a resource
\r
236 * @return the objects
\r
237 * @throws ManyObjectsForFunctionalRelationException on invalid graph with
\r
238 * more than one functional object
\r
239 * @throws ServiceException on connection and database failures
\r
240 * @see AsyncReadGraph#forEachObject
\r
241 * @see AsyncReadGraph#forObjectSet
\r
243 Collection<Resource> getObjects(Resource subject, Resource relation)
\r
244 throws ServiceException;
\r
247 * Gets all objects o (s, p, o) asserted by subject such that
\r
248 * {@link ReadGraph#isSubrelationOf(p, relation)} returns true. See the
\r
249 * assertion mechanism TODO for more details. If the relation is functional
\r
250 * the request returns a single object according to the functional statement
\r
251 * shadowing rules TODO if possible. If an invalid graph is encountered an
\r
252 * exception is thrown.
\r
254 * @param subject a resource
\r
255 * @param relation a resource
\r
256 * @return the objects
\r
257 * @throws ManyObjectsForFunctionalRelationException on invalid graph with
\r
258 * more than one functional object
\r
259 * @throws ServiceException on connection and database failures
\r
260 * @see AsyncReadGraph#forEachAssertedStatement
\r
261 * @see AsyncReadGraph#forAssertedStatementSet
\r
263 Collection<Resource> getAssertedObjects(Resource subject, Resource relation)
\r
264 throws ManyObjectsForFunctionalRelationException, ServiceException;
\r
267 * Gets the inverse r of relation such that (relation, InverseOf, r). The
\r
268 * methods assumes an inverse exists.
\r
270 * @param relation a resource
\r
271 * @return the inverse
\r
272 * @throws NoInverseException if inverse was not fond
\r
273 * @throws ManyObjectsForFunctionalRelationException on invalid graph with
\r
274 * more than one functional object
\r
275 * @throws ServiceException on connection and database failures
\r
276 * @see AsyncReadGraph#forInverse
\r
278 Resource getInverse(Resource relation) throws NoInverseException, ManyObjectsForFunctionalRelationException,
\r
282 * Gets a single object as returned by {@link ReadGraph#getObjects}. Assumes
\r
285 * @param subject a resource
\r
286 * @param relation a resource
\r
287 * @return the single object
\r
288 * @throws NoSingleResultException if the amount of valid objects was not
\r
290 * @throws ManyObjectsForFunctionalRelationException on invalid graph with
\r
291 * more than one functional object
\r
292 * @throws ServiceException on connection and database failures
\r
293 * @see AsyncReadGraph#forSingleObject
\r
295 Resource getSingleObject(Resource subject, Resource relation) throws NoSingleResultException,
\r
296 ManyObjectsForFunctionalRelationException, ServiceException;
\r
299 * Gets a single statement as returned by {@link ReadGraph#getStatements}.
\r
300 * Assumes a single statement.
\r
302 * @param subject a resource
\r
303 * @param relation a resource
\r
304 * @return the single statement
\r
305 * @throws NoSingleResultException if the amount of valid statements was not
\r
307 * @throws ManyObjectsForFunctionalRelationException on invalid graph with
\r
308 * more than one functional object
\r
309 * @throws ServiceException on connection and database failures
\r
310 * @see AsyncReadGraph#forSingleStatement
\r
312 Statement getSingleStatement(Resource subject, Resource relation) throws NoSingleResultException,
\r
313 ManyObjectsForFunctionalRelationException, ServiceException;
\r
316 * Gets a single type t as returned by {@link ReadGraph#getPrincipalTypes}. Assumes a single type.
\r
318 * @param subject a resource
\r
319 * @param baseType a resource
\r
320 * @return the single type
\r
321 * @throws NoSingleResultException if the amount of valid types was not one
\r
322 * @throws ServiceException on connection and database failures
\r
323 * @see AsyncReadGraph#forSingleType
\r
325 Resource getSingleType(Resource subject) throws NoSingleResultException, ServiceException;
\r
328 * Gets a single type t as returned by {@link ReadGraph#getTypes} where
\r
329 * {@link ReadGraph#isInheritedFrom(t, baseType)}. Assumes a single type.
\r
331 * @param subject a resource
\r
332 * @param baseType a resource
\r
333 * @return the single type
\r
334 * @throws NoSingleResultException if the amount of valid types was not one
\r
335 * @throws ServiceException on connection and database failures
\r
336 * @see AsyncReadGraph#forSingleType
\r
338 Resource getSingleType(Resource subject, Resource baseType) throws NoSingleResultException, ServiceException;
\r
341 * Gets a value associated to subject. Infers {@link Binding} from type t =
\r
342 * {@link ReadGraph#getSingleType(subject, Value)}
\r
344 * @param subject a resource
\r
345 * @return the value
\r
346 * @throws DoesNotContainValueException if the subject did not contain a
\r
348 * @throws ServiceException on connection and database failure
\r
349 * @see AsyncReadGraph#forValue
\r
351 <T> T getValue(Resource subject) throws DoesNotContainValueException, ServiceException;
\r
354 * Gets a value associated to subject as a Variant. Infers {@link Binding} from type t =
\r
355 * {@link ReadGraph#getSingleType(subject, Value)}
\r
357 * @param subject a resource
\r
358 * @return the value
\r
359 * @throws DoesNotContainValueException if the subject did not contain a
\r
361 * @throws ServiceException on connection and database failure
\r
362 * @see AsyncReadGraph#forValue
\r
364 Variant getVariantValue(Resource subject) throws DoesNotContainValueException, ServiceException;
\r
367 * Gets a value associated to subject using the given {@link Binding}.
\r
369 * @param subject a resource
\r
370 * @param binding a binding
\r
371 * @return the value
\r
372 * @throws DoesNotContainValueException if the subject did not contain a
\r
374 * @throws BindingException if value could not be produced using the given
\r
376 * @throws ServiceException on connection and database failure
\r
377 * @see AsyncReadGraph#forValue
\r
379 <T> T getValue(Resource subject, Binding binding) throws DoesNotContainValueException, BindingException,
\r
383 * Gets a single value associated to o such that (subject, r, o) and
\r
384 * {@link ReadGraph#isSubrelationOf(r, relation)}. Assumes a single value.
\r
385 * Infers {@link Binding} from type t =
\r
386 * {@link ReadGraph#getSingleType(o, Value)}
\r
388 * @param subject a resource
\r
389 * @param relation a resource
\r
390 * @return the value
\r
391 * @throws NoSingleResultException if the amount of valid values was not one
\r
392 * @throws DoesNotContainValueException if suitable o did not contain a
\r
394 * @throws ServiceException on connection and database failure
\r
395 * @see AsyncReadGraph#forRelatedValue
\r
397 <T> T getRelatedValue(Resource subject, Resource relation) throws NoSingleResultException,
\r
398 DoesNotContainValueException, ServiceException;
\r
401 * Gets a single value associated to o such that (subject, r, o) and
\r
402 * {@link ReadGraph#isSubrelationOf(r, relation)} as a Variant. Assumes a single value.
\r
403 * Infers {@link Binding} from type t =
\r
404 * {@link ReadGraph#getSingleType(o, Value)}
\r
406 * @param subject a resource
\r
407 * @param relation a resource
\r
408 * @return the value
\r
409 * @throws NoSingleResultException if the amount of valid values was not one
\r
410 * @throws DoesNotContainValueException if suitable o did not contain a
\r
412 * @throws ServiceException on connection and database failure
\r
413 * @see AsyncReadGraph#forRelatedValue
\r
415 Variant getRelatedVariantValue(Resource subject, Resource relation) throws NoSingleResultException,
\r
416 DoesNotContainValueException, ServiceException;
\r
419 * Gets a single value associated to o such that (subject, r, o) and
\r
420 * {@link ReadGraph#isSubrelationOf(r, relation)}. Uses the given
\r
421 * {@link Binding}. Assumes a single value.
\r
423 * @param subject a resource
\r
424 * @param relation a resource
\r
425 * @return the value
\r
426 * @throws NoSingleResultException if the amount of valid values was not one
\r
427 * @throws DoesNotContainValueException if suitable o did not contain a
\r
429 * @throws BindingException if value could not be produced using the given
\r
431 * @throws ServiceException on connection and database failure
\r
432 * @see AsyncReadGraph#forRelatedValue
\r
434 <T> T getRelatedValue(Resource subject, Resource relation, Binding binding) throws NoSingleResultException,
\r
435 DoesNotContainValueException, BindingException, ServiceException;
\r
438 * Tries to adapt the specified resource into an instance of the specified
\r
439 * class T. No guarantees are made on return values of this method. The
\r
440 * returned values can be cached results of previous invocation or they can
\r
441 * be new result object instances. See {@link #adaptUnique(Resource, Class)}
\r
442 * for alternative behaviour.
\r
444 * @param resource a resource
\r
445 * @param clazz the adapter class
\r
447 * @throws AdaptionException if suitable adapter was not found
\r
448 * @throws ValidationException from the adapter
\r
449 * @throws ServiceException on connection and database failure
\r
450 * @see AsyncReadGraph#forAdapted
\r
451 * @see #adaptUnique(Resource, Class)
\r
453 <T> T adapt(Resource resource, Class<T> clazz) throws AdaptionException, ValidationException, ServiceException;
\r
457 * Same as: adapt(getSingleObject(resource, relation), clazz);
\r
459 * @param resource a resource
\r
460 * @param relation a resource
\r
461 * @param clazz the adapter class
\r
463 * @throws AdaptionException if suitable adapter was not found
\r
464 * @throws ValidationException from the adapter
\r
465 * @throws ServiceException on connection and database failure
\r
466 * @see AsyncReadGraph#forAdapted
\r
467 * @see #adaptUnique(Resource, Class)
\r
469 <T> T adaptRelated(Resource resource, Resource relation, Class<T> clazz) throws AdaptionException, NoSingleResultException, ValidationException, ServiceException;
\r
475 * Resource r = getPossibleObject(resource, relation);
\r
476 * if(r == null) return null;
\r
477 * return getPossibleAdapter(r, clazz);
\r
479 * @param resource a resource
\r
480 * @param relation a resource
\r
481 * @param clazz the adapter class
\r
483 * @throws AdaptionException if suitable adapter was not found
\r
484 * @throws ValidationException from the adapter
\r
485 * @throws ServiceException on connection and database failure
\r
486 * @see AsyncReadGraph#forAdapted
\r
487 * @see #adaptUnique(Resource, Class)
\r
489 <T> T getPossibleRelatedAdapter(Resource resource, Resource relation, Class<T> clazz) throws ValidationException, ServiceException;
\r
491 <T,C> T adaptContextual(Resource resource, C context, Class<C> contextClass, Class<T> clazz) throws AdaptionException, NoSingleResultException, ValidationException, ServiceException;
\r
492 <T,C> T getPossibleContextualAdapter(Resource resource, C context, Class<C> contextClass, Class<T> clazz) throws ValidationException, ServiceException;
\r
495 * Tries to adapt the specified resource into an instance of the specified
\r
496 * class T. The difference to {@link #adapt(Resource, Class)} is that this
\r
497 * method does everything possible to return a new object instance for each
\r
498 * separate invocation.
\r
501 * The only case when this cannot be guaranteed is when the adaption result
\r
502 * comes from an {@link Adapter} implementation which can internally do
\r
503 * anything, like always return the same singleton instance.
\r
506 * @param resource a resource
\r
507 * @param clazz the adapter class
\r
509 * @throws AdaptionException if suitable adapter was not found
\r
510 * @throws ValidationException from the adapter
\r
511 * @throws ServiceException on connection and database failure
\r
512 * @see AsyncReadGraph#forAdapted
\r
513 * @see #adapt(Resource, Class)
\r
515 <T> T adaptUnique(Resource resource, Class<T> clazz) throws AdaptionException, ValidationException,
\r
519 * As {@link #getInverse} but returns null instead of an exception if
\r
520 * inverse was not found.
\r
522 * @param relation a resource
\r
523 * @return the inverse or null
\r
524 * @throws ManyObjectsForFunctionalRelationException on invalid graph with
\r
525 * more than one functional object
\r
526 * @throws ServiceException on connection and database failures
\r
527 * @see AsyncReadGraph#forPossibleInverse
\r
529 Resource getPossibleInverse(Resource relation) throws ManyObjectsForFunctionalRelationException, ServiceException;
\r
532 * As {@link #getSingleObject} but returns null instead of an exception if
\r
533 * object was not found.
\r
535 * @param subject a resource
\r
536 * @param relation a resource
\r
537 * @return the object or null
\r
538 * @throws ManyObjectsForFunctionalRelationException on invalid graph with
\r
539 * more than one functional object
\r
540 * @throws ServiceException on connection and database failures
\r
541 * @see AsyncReadGraph#forPossibleObject
\r
543 Resource getPossibleObject(Resource subject, Resource relation) throws ManyObjectsForFunctionalRelationException,
\r
547 * As {@link #getSingleStatement} but returns null instead of an exception
\r
548 * if statement was not found.
\r
550 * @param subject a resource
\r
551 * @param relation a resource
\r
552 * @return the statement or null
\r
553 * @throws ManyObjectsForFunctionalRelationException on invalid graph with
\r
554 * more than one functional object
\r
555 * @throws ServiceException on connection and database failures
\r
556 * @see AsyncReadGraph#forPossibleStatement
\r
558 Statement getPossibleStatement(Resource subject, Resource relation)
\r
559 throws ManyObjectsForFunctionalRelationException, ServiceException;
\r
562 * As {@link #getSingleType} but returns null instead of an exception if
\r
563 * type was not found.
\r
565 * @param subject a resource
\r
566 * @param baseType a resource
\r
567 * @return the type or null
\r
568 * @throws ServiceException on connection and database failures
\r
569 * @see AsyncReadGraph#forPossibleType
\r
571 Resource getPossibleType(Resource subject, Resource baseType) throws ServiceException;
\r
574 * As {@link #getValue} but returns null instead of an exception if value
\r
577 * @param subject a resource
\r
578 * @return the value or null
\r
579 * @throws ServiceException on connection and database failures
\r
580 * @see AsyncReadGraph#forPossibleValue
\r
582 <T> T getPossibleValue(Resource subject) throws ServiceException;
\r
585 * As {@link #getValue} but returns null instead of an exception if value
\r
588 * @param subject a resource
\r
589 * @param binding a {@link Binding}
\r
590 * @return the value or null
\r
591 * @throws BindingException if value could not be produced using the given
\r
593 * @throws ServiceException on connection and database failures
\r
594 * @see AsyncReadGraph#forPossibleValue
\r
596 <T> T getPossibleValue(Resource subject, Binding binding) throws BindingException, ServiceException;
\r
599 * As {@link #getPossibleRelatedValue} but returns null instead of an
\r
600 * exception if value was not found.
\r
602 * @param subject a resource
\r
603 * @param relation a resource
\r
604 * @return the value or null
\r
605 * @throws ManyObjectsForFunctionalRelationException on invalid graph with
\r
606 * more than one functional object
\r
607 * @throws ServiceException on connection and database failures
\r
608 * @see AsyncReadGraph#forPossibleRelatedValue
\r
610 <T> T getPossibleRelatedValue(Resource subject, Resource relation)
\r
611 throws ManyObjectsForFunctionalRelationException, ServiceException;
\r
614 * As {@link #getPossibleRelatedValue} but returns null instead of an
\r
615 * exception if value was not found.
\r
617 * @param subject a resource
\r
618 * @param relation a resource
\r
619 * @param binding a {@link Binding}
\r
620 * @return the value or null
\r
621 * @throws ManyObjectsForFunctionalRelationException on invalid graph with
\r
622 * more than one functional object
\r
623 * @throws BindingException if value could not be produced using the given
\r
625 * @throws ServiceException on connection and database failures
\r
626 * @see AsyncReadGraph#forPossibleRelatedValue
\r
628 <T> T getPossibleRelatedValue(Resource subject, Resource relation, Binding binding)
\r
629 throws ManyObjectsForFunctionalRelationException, BindingException, ServiceException;
\r
632 * As {@link #adapt} but returns null instead of an exception if adapter was
\r
635 * @param subject a resource
\r
636 * @param clazz a Class
\r
637 * @return the adapter or null
\r
638 * @throws ValidationException when ?
\r
639 * @throws ServiceException on connection and database failures
\r
640 * @see {@link AsyncReadGraph#forPossibleAdapted}
\r
642 <T> T getPossibleAdapter(Resource resource, Class<T> clazz) throws ValidationException, ServiceException;
\r
645 * As {@link #adaptUnique} but returns null instead of an exception if
\r
646 * adapter was not found
\r
648 * @param subject a resource
\r
649 * @param clazz a Class
\r
650 * @return the adapter or null
\r
651 * @throws ValidationException when ?
\r
652 * @throws ServiceException on connection and database failures
\r
653 * @see {@link AsyncReadGraph#forPossibleAdapted}
\r
655 <T> T getPossibleUniqueAdapter(Resource resource, Class<T> clazz) throws ValidationException, ServiceException;
\r
658 * Returns true if type is included in the result of {@link #getTypes(resource)}
\r
660 * @param subject a resource
\r
661 * @param type a resource
\r
662 * @return indicates if resource is an instance of type
\r
663 * @throws ServiceException on connection and database failures
\r
664 * @see {@link AsyncReadGraph#forIsInstanceOf}
\r
666 boolean isInstanceOf(Resource resource, Resource type) throws ServiceException;
\r
669 * Returns true if type equals resource or type is included in the result of
\r
670 * {@link #getSupertypes(resource)}
\r
672 * @param subject a resource
\r
673 * @param type a resource
\r
674 * @return indicates if resource is inherited from type
\r
675 * @throws ServiceException on connection and database failures
\r
676 * @see {@link AsyncReadGraph#forIsInheritedFrom}
\r
678 boolean isInheritedFrom(Resource resource, Resource type) throws ServiceException;
\r
681 * Returns true if relation equals resource or relation is included in the result of
\r
682 * {@link #getSuperrelations(resource)}
\r
684 * @param subject a resource
\r
685 * @param relation a resource
\r
686 * @return indicates if resource is a subrelation of relation
\r
687 * @throws ServiceException on connection and database failures
\r
688 * @see {@link AsyncReadGraph#forIsSubrelationOf}
\r
690 boolean isSubrelationOf(Resource resource, Resource relation) throws ServiceException;
\r
693 * Returns true if the result of {@link #getStatements(subject, IsWeaklyRelatedTo)} is nonempty.
\r
695 * @param subject a resource
\r
696 * @return indicates that subject has statements
\r
697 * @throws ServiceException on connection and database failures
\r
698 * @see {@link AsyncReadGraph#forHasStatement}
\r
700 boolean hasStatement(Resource subject) throws ServiceException;
\r
703 * Returns true if the result of {@link #getStatements(subject, relation)} is nonempty.
\r
705 * @param subject a resource
\r
706 * @param relation a resource
\r
707 * @return indicates that subject has statements with predicates as subrelation of relation
\r
708 * @throws ServiceException on connection and database failures
\r
709 * @see {@link AsyncReadGraph#forHasStatement}
\r
711 boolean hasStatement(Resource subject, Resource relation) throws ServiceException;
\r
714 * Returns true if a statement (subject, relation, object) exists after assertions.
\r
716 * @param subject a resource
\r
717 * @param relation a resource
\r
718 * @param object a resource
\r
719 * @return indicates that the given statement exists
\r
720 * @throws ServiceException on connection and database failures
\r
721 * @see {@link AsyncReadGraph#forHasStatement}
\r
723 boolean hasStatement(Resource subject, Resource relation, Resource object) throws ServiceException;
\r
726 * Returns true if there is a value associated with subject.
\r
727 * IMPLEMENTATION NOTE:
\r
728 * Current implementation fetches the value from server. If the value is
\r
729 * large (i.e. not stored in the cluster) this is highly inefficient.
\r
731 * @param subject a resource
\r
732 * @return indicates that a value exists
\r
733 * @throws ServiceException on connection and database failures
\r
734 * @see {@link AsyncReadGraph#forHasValue}
\r
736 boolean hasValue(Resource subject) throws ServiceException;
\r
739 * Returns the data type of the literal.
\r
742 * @throws DatabaseException
\r
744 Datatype getDataType(Resource subject) throws DatabaseException;
\r
747 * Returns an accessory that can be used to partially read the literal
\r
748 * or write if the graph is WriteGraph. The returned accessory is closed
\r
749 * automatically when the transaction ends. The modifications are written
\r
750 * back to graph at transaction completion.
\r
752 * @param <T> is typed accessory for modifying the literal value.
\r
753 * @param resource is the literal containing the value.
\r
754 * @return interface to partially read and write the literal value.
\r
755 * @throws DatabaseException
\r
757 <T extends Accessor> T getAccessor(Resource resource) throws DatabaseException;
\r
760 * Returns an RandomAccessBinary that can be used to partially read the literal
\r
761 * or write if the graph is WriteGraph. The returned interface is closed
\r
762 * automatically when the transaction ends. The modifications are written
\r
763 * back to graph at transaction completion.
\r
766 * @param resource is the literal containing the value.
\r
767 * @return interface to partially read and write the literal value.
\r
768 * @throws DatabaseException
\r
770 RandomAccessBinary getRandomAccessBinary(Resource resource) throws DatabaseException;
\r
771 // @SuppressWarnings("rawtypes")
\r
772 // Function getValueFunction(Resource resource) throws DatabaseException;
\r
775 * Get the value associated with a graph {@link Resource}, using a possible context object and
\r
776 * a default data type binding. An exception is thrown, if the value is not found.
\r
778 * See {@link #getValue2(Resource, Object, Binding)} for more details.
\r
780 * @param r A graph resource with which the value is associated
\r
781 * @param context A context object that is used for acquiring the value, can be {@code null}
\r
782 * @return The value of the graph node.
\r
783 * @throws DoesNotContainValueException No value is associated with the graph node.
\r
784 * @throws DatabaseException Other errors, such as an error in casting the value to the return type or
\r
785 * a runtime error in the value function.
\r
786 * @see #getValue2(Resource, Object, Binding)
\r
787 * @see #getPossibleValue2(Resource, Object)
\r
789 <T> T getValue2(Resource subject, Object context) throws DatabaseException;
\r
792 * Get the value associated with a graph {@link Resource}, using a possible context object and
\r
793 * a default data type binding as a Variant. An exception is thrown, if the value is not found.
\r
795 * See {@link #getValue2(Resource, Object, Binding)} for more details.
\r
797 * @param r A graph resource with which the value is associated
\r
798 * @param context A context object that is used for acquiring the value, can be {@code null}
\r
799 * @return The value of the graph node.
\r
800 * @throws DoesNotContainValueException No value is associated with the graph node.
\r
801 * @throws DatabaseException Other errors, such as an error in casting the value to the return type or
\r
802 * a runtime error in the value function.
\r
803 * @see #getValue2(Resource, Object, Binding)
\r
804 * @see #getPossibleValue2(Resource, Object)
\r
806 Variant getVariantValue2( Resource r, Object context ) throws DatabaseException;
\r
809 * Get a possible value associated with a graph {@link Resource}, using a possible context object and
\r
810 * a desired value binding. Unlike {@link #getValue2(Resource, Object)}, this methods
\r
811 * returns {@code null} for missing values instead of throwing an exception.
\r
813 * See {@link #getValue2(Resource, Object, Binding)} for more details.
\r
815 * @param r A graph resource with which the value is associated
\r
816 * @param context A context object that is used for acquiring the value, can be {@code null}
\r
817 * @return The value of the graph node.
\r
818 * @throws DatabaseException Usually should not happen. A null value is returned for possible errors.
\r
819 * @see #getValue2(Resource, Object)
\r
820 * @see #getPossibleValue2(Resource, Object, Binding)
\r
822 <T> T getPossibleValue2(Resource subject, Object context) throws DatabaseException;
\r
825 * Get the value associated with a graph {@link Resource}, using a possible context object and
\r
826 * a desired value binding. An exception is thrown, if the value is not found.
\r
828 * The following methods are tried in order to retrieve the value:
\r
830 * <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>
\r
831 * <li>If the resource is a {@code L0.ExternalValue}, the value is acquired using
\r
832 * {@link ReflectionUtils#getValue(String)} with the resource URI.</li>
\r
833 * <li>If the resource is associated with a suitable value converter with relation {@code L0.ConvertsToValueWith}
\r
834 * (see {@link #requestValueFunction(Resource)}), the value function is called with the graph, the resource
\r
835 * and the context object.</li>
\r
838 * @param r A graph resource with which the value is associated
\r
839 * @param context A context object that is used for acquiring the value, can be {@code null}
\r
840 * @param binding A binding for the value type
\r
841 * @return The value of the graph node.
\r
842 * @throws DoesNotContainValueException No value is associated with the graph node.
\r
843 * @throws DatabaseException Other errors, such as an error in casting the value to the return type or
\r
844 * a runtime error in the value function.
\r
845 * @see #getValue2(Resource, Object)
\r
846 * @see #getPossibleValue2(Resource, Object, Binding)
\r
848 <T> T getValue2(Resource subject, Object context, Binding binding) throws DatabaseException;
\r
851 * Get a possible value associated with a graph {@link Resource}, using a possible context object and
\r
852 * a desired value binding. Unlike {@link #getValue2(Resource, Object, Binding)}, this methods
\r
853 * returns {@code null} for missing values instead of throwing an exception.
\r
855 * See {@link #getValue2(Resource, Object, Binding)} for more details.
\r
857 * @param r A graph resource with which the value is associated
\r
858 * @param context A context object that is used for acquiring the value, can be {@code null}
\r
859 * @param binding A binding for the value type
\r
860 * @return The value of the graph node.
\r
861 * @throws DatabaseException Usually should not happen. A null value is returned for possible errors.
\r
862 * @see #getValue2(Resource, Object, Bindinge)
\r
863 * @see #getPossibleValue2(Resource, Object)
\r
865 <T> T getPossibleValue2(Resource subject, Object context, Binding binding) throws DatabaseException;
\r
868 * Get the single value associated with a graph resource related with a given subject.
\r
869 * An exception is thrown, if a unique object resource or a value for it is not found.
\r
871 * See {@link #getValue2(Resource, Object, Binding)} for more details.
\r
873 * @param subject A graph resource that indicates the subject node
\r
874 * @param relation A graph resource that indicates the predicate of a relation
\r
875 * @return The value of the unique graph node that is asserted as the object of the given subject and predicate.
\r
876 * @throws NoSingleResultException The number of suitable object resources is not equal to 1 (zero or greater than one)
\r
877 * @throws DoesNotContainValueException No value is associated with the graph node.
\r
878 * @throws DatabaseException Other errors, such as an error in casting the value to the return type or
\r
879 * a runtime error in the value function.
\r
880 * @see #getRelatedValue2(Resource, Resource, Binding)
\r
881 * @see #getRelatedValue2(Resource, Resource, Object)
\r
882 * @see #getRelatedValue2(Resource, Resource, Object, Binding)
\r
883 * @see #getPossibleRelatedValue2(Resource, Resource)
\r
885 <T> T getRelatedValue2(Resource subject, Resource relation) throws DatabaseException;
\r
888 * Get a possible single value associated with a graph resource related with a given subject.
\r
889 * A {@code null} value is returned for missing values or other errors.
\r
891 * See {@link #getValue2(Resource, Object, Binding)} for more details.
\r
893 * @param subject A graph resource that indicates the subject node
\r
894 * @param relation A graph resource that indicates the predicate of a relation
\r
895 * @return The value of the unique graph node that is asserted as the object of the given subject and predicate.
\r
896 * @throws DatabaseException Usually should not happen. A {@code null} value is returned for possible errors.
\r
897 * @see #getPossibleRelatedValue2(Resource, Resource, Binding)
\r
898 * @see #getPossibleRelatedValue2(Resource, Resource, Object)
\r
899 * @see #getPossibleRelatedValue2(Resource, Resource, Object, Binding)
\r
900 * @see #getRelatedValue2(Resource, Resource)
\r
902 <T> T getPossibleRelatedValue2(Resource subject, Resource relation) throws DatabaseException;
\r
905 * Get a possible single value associated with a graph resource related with a given subject.
\r
906 * A {@code null} value is returned for missing values or other errors.
\r
908 * See {@link #getValue2(Resource, Object, Binding)} for more details.
\r
910 * @param subject A graph resource that indicates the subject node
\r
911 * @param relation A graph resource that indicates the predicate of a relation
\r
912 * @return The value of the unique graph node that is asserted as the object of the given subject and predicate.
\r
913 * @throws DatabaseException Usually should not happen. A {@code null} value is returned for possible errors.
\r
914 * @see #getPossibleRelatedValue2(Resource, Resource, Binding)
\r
915 * @see #getPossibleRelatedValue2(Resource, Resource, Object)
\r
916 * @see #getPossibleRelatedValue2(Resource, Resource, Object, Binding)
\r
917 * @see #getRelatedValue2(Resource, Resource)
\r
919 Variant getRelatedVariantValue2( Resource subject, Resource relation ) throws DatabaseException;
\r
922 * Get the single value associated with a graph resource related with a given subject, a possible context object.
\r
923 * An exception is thrown, if a unique object resource or a value for it is not found.
\r
925 * See {@link #getValue2(Resource, Object, Binding)} for more details.
\r
927 * @param subject A graph resource that indicates the subject node
\r
928 * @param relation A graph resource that indicates the predicate of a relation
\r
929 * @param context A context object that is used for acquiring the value, can be {@code null}
\r
930 * @return The value of the unique graph node that is asserted as the object of the given subject and predicate.
\r
931 * @throws NoSingleResultException The number of suitable object resources is not equal to 1 (zero or greater than one)
\r
932 * @throws DoesNotContainValueException No value is associated with the graph node.
\r
933 * @throws DatabaseException Other errors, such as an error in casting the value to the return type or
\r
934 * a runtime error in the value function.
\r
935 * @see #getRelatedValue2(Resource, Resource)
\r
936 * @see #getRelatedValue2(Resource, Resource, Binding)
\r
937 * @see #getRelatedValue2(Resource, Resource, Object, Binding)
\r
938 * @see #getPossibleRelatedValue2(Resource, Resource, Object)
\r
940 <T> T getRelatedValue2(Resource subject, Resource relation, Object context) throws DatabaseException;
\r
943 * Get the single value associated with a graph resource related with a given subject, a possible context object.
\r
944 * An exception is thrown, if a unique object resource or a value for it is not found.
\r
946 * See {@link #getValue2(Resource, Object, Binding)} for more details.
\r
948 * @param subject A graph resource that indicates the subject node
\r
949 * @param relation A graph resource that indicates the predicate of a relation
\r
950 * @param context A context object that is used for acquiring the value, can be {@code null}
\r
951 * @return The value of the unique graph node that is asserted as the object of the given subject and predicate.
\r
952 * @throws NoSingleResultException The number of suitable object resources is not equal to 1 (zero or greater than one)
\r
953 * @throws DoesNotContainValueException No value is associated with the graph node.
\r
954 * @throws DatabaseException Other errors, such as an error in casting the value to the return type or
\r
955 * a runtime error in the value function.
\r
956 * @see #getRelatedValue2(Resource, Resource, Object)
\r
957 * @see #getPossibleRelatedValue2(Resource, Resource, Object)
\r
959 Variant getRelatedVariantValue2( Resource subject, Resource relation, Object context ) throws DatabaseException;
\r
962 * Get a possible single value associated with a graph resource related with a given subject and a possible context object.
\r
963 * A {@code null} value is returned for missing values or other errors.
\r
965 * See {@link #getValue2(Resource, Object, Binding)} for more details.
\r
967 * @param subject A graph resource that indicates the subject node
\r
968 * @param relation A graph resource that indicates the predicate of a relation
\r
969 * @param context A context object that is used for acquiring the value, can be {@code null}
\r
970 * @return The value of the unique graph node that is asserted as the object of the given subject and predicate.
\r
971 * @throws DatabaseException Usually should not happen. A {@code null} value is returned for possible errors.
\r
972 * @see #getPossibleRelatedValue2(Resource, Resource)
\r
973 * @see #getPossibleRelatedValue2(Resource, Resource, Binding)
\r
974 * @see #getPossibleRelatedValue2(Resource, Resource, Object, Binding)
\r
975 * @see #getRelatedValue2(Resource, Resource, Object)
\r
977 <T> T getPossibleRelatedValue2(Resource subject, Resource relation, Object context) throws DatabaseException;
\r
980 * Get the single value associated with a graph resource related with a given subject and
\r
981 * a desired value binding. An exception is thrown, if a unique object resource or a value for it is not found.
\r
983 * See {@link #getValue2(Resource, Object, Binding)} for more details.
\r
985 * @param subject A graph resource that indicates the subject node
\r
986 * @param relation A graph resource that indicates the predicate of a relation
\r
987 * @param binding A binding for the value type
\r
988 * @return The value of the unique graph node that is asserted as the object of the given subject and predicate.
\r
989 * @throws NoSingleResultException The number of suitable object resources is not equal to 1 (zero or greater than one)
\r
990 * @throws DoesNotContainValueException No value is associated with the graph node.
\r
991 * @throws DatabaseException Other errors, such as an error in casting the value to the return type or
\r
992 * a runtime error in the value function.
\r
993 * @see #getRelatedValue2(Resource, Resource)
\r
994 * @see #getRelatedValue2(Resource, Resource, Object)
\r
995 * @see #getRelatedValue2(Resource, Resource, Object, Binding)
\r
996 * @see #getPossibleRelatedValue2(Resource, Resource, Binding)
\r
998 <T> T getRelatedValue2(Resource subject, Resource relation, Binding binding) throws DatabaseException;
\r
1001 * Get a possible single value associated with a graph resource related with a given subject and
\r
1002 * a desired value binding. A {@code null} value is returned for missing values or other errors.
\r
1004 * See {@link #getValue2(Resource, Object, Binding)} for more details.
\r
1006 * @param subject A graph resource that indicates the subject node
\r
1007 * @param relation A graph resource that indicates the predicate of a relation
\r
1008 * @param binding A binding for the value type
\r
1009 * @return The value of the unique graph node that is asserted as the object of the given subject and predicate.
\r
1010 * @throws DatabaseException Usually should not happen. A {@code null} value is returned for possible errors.
\r
1011 * @see #getPossibleRelatedValue2(Resource, Resource)
\r
1012 * @see #getPossibleRelatedValue2(Resource, Resource, Object)
\r
1013 * @see #getPossibleRelatedValue2(Resource, Resource, Object, Binding)
\r
1014 * @see #getRelatedValue2(Resource, Resource, Binding)
\r
1016 <T> T getPossibleRelatedValue2(Resource subject, Resource relation, Binding binding) throws DatabaseException;
\r
1019 * Get the single value associated with a graph resource related with a given subject, a possible context object and
\r
1020 * a desired value binding. An exception is thrown, if a unique object resource or a value for it is not found.
\r
1022 * See {@link #getValue2(Resource, Object, Binding)} for more details.
\r
1024 * @param subject A graph resource that indicates the subject node
\r
1025 * @param relation A graph resource that indicates the predicate of a relation
\r
1026 * @param context A context object that is used for acquiring the value, can be {@code null}
\r
1027 * @param binding A binding for the value type
\r
1028 * @return The value of the unique graph node that is asserted as the object of the given subject and predicate.
\r
1029 * @throws NoSingleResultException The number of suitable object resources is not equal to 1 (zero or greater than one)
\r
1030 * @throws DoesNotContainValueException No value is associated with the graph node.
\r
1031 * @throws DatabaseException Other errors, such as an error in casting the value to the return type or
\r
1032 * a runtime error in the value function.
\r
1033 * @see #getRelatedValue2(Resource, Resource)
\r
1034 * @see #getRelatedValue2(Resource, Resource, Binding)
\r
1035 * @see #getRelatedValue2(Resource, Resource, Object)
\r
1036 * @see #getPossibleRelatedValue2(Resource, Resource, Object, Binding)
\r
1038 <T> T getRelatedValue2(Resource subject, Resource relation, Object context, Binding binding) throws DatabaseException;
\r
1041 * Get a possible single value associated with a graph resource related with a given subject, a possible context object and
\r
1042 * a desired value binding. A {@code null} value is returned for missing values or other errors.
\r
1044 * See {@link #getValue2(Resource, Object, Binding)} for more details.
\r
1046 * @param subject A graph resource that indicates the subject node
\r
1047 * @param relation A graph resource that indicates the predicate of a relation
\r
1048 * @param context A context object that is used for acquiring the value, can be {@code null}
\r
1049 * @param binding A binding for the value type
\r
1050 * @return The value of the unique graph node that is asserted as the object of the given subject and predicate.
\r
1051 * @throws DatabaseException Usually should not happen. A {@code null} value is returned for possible errors.
\r
1052 * @see #getPossibleRelatedValue2(Resource, Resource)
\r
1053 * @see #getPossibleRelatedValue2(Resource, Resource, Binding)
\r
1054 * @see #getPossibleRelatedValue2(Resource, Resource, Object)
\r
1055 * @see #getRelatedValue2(Resource, Resource, Object, Binding)
\r
1057 <T> T getPossibleRelatedValue2(Resource subject, Resource relation, Object context, Binding binding) throws DatabaseException;
\r
1060 * Get the parsed SCL type declaration from the string value of a graph resource that is the unique object of a
\r
1061 * given subject and predicate.
\r
1063 * See {@link #getValue2(Resource, Object, Binding)} for more details.
\r
1065 * @param subject A resource that indicates the subject of a statement
\r
1066 * @param relation A resource that indicates the predicate of the statement
\r
1067 * @return A compiled SCL type definition of the string value of a unique object resource
\r
1068 * @throws DatabaseException For any errors in locating a unique value or compiling it as an SCL type statement
\r
1070 Type getRelatedValueType(Resource subject, Resource relation) throws DatabaseException;
\r
1072 boolean setSynchronous(boolean value);
\r
1073 boolean getSynchronous();
\r