bundles/org.simantics.db/src/org/simantics/db/ReadGraph.java

   1 /*******************************************************************************
   2  * Copyright (c) 2007, 2010 Association for Decentralized Information Management
   3  * in Industry THTH ry.
   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
   8  *
   9  * Contributors:
  10  *     VTT Technical Research Centre of Finland - initial API and implementation
  11  *******************************************************************************/
  12 package org.simantics.db;
  13
  14 import java.util.Collection;
  15 import java.util.Map;
  16 import java.util.Set;
  17
  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;
  43
  44 /**
  45  *
  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}
  51  * <p>
  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}
  57  *
  58  * <p>
  59  * All collections returned by the methods on this interface must not be
  60  * modified by clients unless explicitly stated otherwise.
  61  *
  62  * @version 0.7
  63  * @author Antti Villberg
  64  * @see RequestProcessor
  65  * @see AsyncRequestProcessor
  66  * @see AsyncReadGraph
  67  * @see Resource
  68  * @see Statement
  69  * @noimplement
  70  */
  71 public interface ReadGraph extends AsyncReadGraph, RequestProcessor {
  72
  73     /**
  74      *
  75      * @see AsyncReadGraph#forURI
  76      */
  77     String getURI(Resource resource) throws AssumptionException, ValidationException, ServiceException;
  78     String getPossibleURI(Resource resource) throws ValidationException, ServiceException;
  79
  80     /**
  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.
  84      *
  85      * @param uri the identifier
  86      * @return the resource
  87      * @throws ResourceNotFoundException if a resource for the given identifier
  88      *         was not specified
  89      * @throws ValidationException if a resource could not be produced due to
  90      *         invalid semantics
  91      * @throws ServiceException on connection and database failures
  92      * @see AsyncReadGraph#forResourceByURI
  93      */
  94     Resource getResource(String uri) throws ResourceNotFoundException, ValidationException, ServiceException;
  95
  96     /**
  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.
 100      *
 101      * @param uri the identifier
 102      * @return the resource
 103      * @throws ResourceNotFoundException if a resource for the given identifier
 104      *         was not specified
 105      * @throws ValidationException if a resource could not be produced due to
 106      *         invalid semantics
 107      * @throws ServiceException on connection and database failures
 108      * @see AsyncReadGraph#forResourceByURI
 109      */
 110     Resource getPossibleResource(String uri) throws ResourceNotFoundException, ValidationException, ServiceException;
 111
 112     /**
 113      * Computes a map of objects related to resource with L0.ConsistsOf that also contain a L0.HasName property
 114      *
 115      * @param resource the resource
 116      * @return the children
 117      * @throws ValidationException if a resource could not be produced due to
 118      *         invalid semantics
 119      * @throws ServiceException on connection and database failures
 120      * @see AsyncReadGraph#forResourceByURI
 121      */
 122     Map<String,Resource> getChildren(Resource resource) throws ValidationException, ServiceException;
 123
 124     /**
 125      * Gets a builtin resource. For a list of builtin resources see TODO Wiki
 126      *
 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
 132      */
 133     Resource getBuiltin(String id) throws ResourceNotFoundException, ServiceException;
 134
 135     /**
 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.
 143      *
 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
 152      */
 153     Collection<Statement> getStatements(Resource subject, Resource relation)
 154     throws ManyObjectsForFunctionalRelationException, ServiceException;
 155
 156     /**
 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.
 163      *
 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
 172      */
 173     Collection<Statement> getAssertedStatements(Resource subject, Resource relation)
 174     throws ManyObjectsForFunctionalRelationException, ServiceException;
 175
 176     /**
 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.
 183      *
 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
 192      */
 193     Collection<Resource> getPredicates(Resource subject) throws ServiceException;
 194
 195     /**
 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.
 199      *
 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
 205      */
 206     Collection<Resource> getPrincipalTypes(Resource subject) throws ServiceException;
 207
 208     /**
 209      * Gets the full type hierarchy for subject.
 210      *
 211      * @param subject a resource
 212      * @return the type hierarchy
 213      * @throws ServiceException on connection and database failures
 214      * @see AsyncReadGraph#forTypes
 215      */
 216     Set<Resource> getTypes(Resource subject) throws ServiceException;
 217
 218     /**
 219      * Gets the full supertype hierarchy for subject.
 220      *
 221      * @param subject a resource
 222      * @return the supertype hierarchy
 223      * @throws ServiceException on connection and database failures
 224      * @see AsyncReadGraph#forSupertypes
 225      */
 226     Set<Resource> getSupertypes(Resource subject) throws ServiceException;
 227
 228     /**
 229      * Gets the full superrelation hierarchy for subject.
 230      *
 231      * @param subject a resource
 232      * @return the superrelation hierarchy
 233      * @throws ServiceException on connection and database failures
 234      * @see AsyncReadGraph#forSuperrelations
 235      */
 236     Set<Resource> getSuperrelations(Resource subject) throws ServiceException;
 237     Resource getPossibleSuperrelation(Resource subject) throws ServiceException;
 238
 239     /**
 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.
 246      *
 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
 255      */
 256     Collection<Resource> getObjects(Resource subject, Resource relation)
 257     throws ServiceException;
 258
 259     /**
 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.
 266      *
 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
 275      */
 276     Collection<Resource> getAssertedObjects(Resource subject, Resource relation)
 277     throws ManyObjectsForFunctionalRelationException, ServiceException;
 278
 279     /**
 280      * Gets the inverse r of relation such that (relation, InverseOf, r). The
 281      * methods assumes an inverse exists.
 282      *
 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
 290      */
 291     Resource getInverse(Resource relation) throws NoInverseException, ManyObjectsForFunctionalRelationException,
 292     ServiceException;
 293
 294     /**
 295      * Gets a single object as returned by {@link ReadGraph#getObjects}. Assumes
 296      * a single object.
 297      *
 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
 302      *         one
 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
 307      */
 308     Resource getSingleObject(Resource subject, Resource relation) throws NoSingleResultException,
 309     ManyObjectsForFunctionalRelationException, ServiceException;
 310
 311     /**
 312      * Gets a single statement as returned by {@link ReadGraph#getStatements}.
 313      * Assumes a single statement.
 314      *
 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
 319      *         one
 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
 324      */
 325     Statement getSingleStatement(Resource subject, Resource relation) throws NoSingleResultException,
 326     ManyObjectsForFunctionalRelationException, ServiceException;
 327
 328     /**
 329      * Gets a single type t as returned by {@link ReadGraph#getPrincipalTypes}. Assumes a single type.
 330      *
 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
 337      */
 338     Resource getSingleType(Resource subject) throws NoSingleResultException, ServiceException;
 339
 340     /**
 341      * Gets a single type t as returned by {@link ReadGraph#getTypes} where
 342      * {@link ReadGraph#isInheritedFrom(t, baseType)}. Assumes a single type.
 343      *
 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
 350      */
 351     Resource getSingleType(Resource subject, Resource baseType) throws NoSingleResultException, ServiceException;
 352
 353     /**
 354      * Gets a value associated to subject. Infers {@link Binding} from type t =
 355      * {@link ReadGraph#getSingleType(subject, Value)}
 356      *
 357      * @param subject a resource
 358      * @return the value
 359      * @throws DoesNotContainValueException if the subject did not contain a
 360      *         resource
 361      * @throws ServiceException on connection and database failure
 362      * @see AsyncReadGraph#forValue
 363      */
 364     <T> T getValue(Resource subject) throws DoesNotContainValueException, ServiceException;
 365
 366     /**
 367      * Gets a value associated to subject as a Variant. Infers {@link Binding} from type t =
 368      * {@link ReadGraph#getSingleType(subject, Value)}
 369      *
 370      * @param subject a resource
 371      * @return the value
 372      * @throws DoesNotContainValueException if the subject did not contain a
 373      *         resource
 374      * @throws ServiceException on connection and database failure
 375      * @see AsyncReadGraph#forValue
 376      */
 377     Variant getVariantValue(Resource subject) throws DoesNotContainValueException, ServiceException;
 378
 379     /**
 380      * Gets a value associated to subject using the given {@link Binding}.
 381      *
 382      * @param subject a resource
 383      * @param binding a binding
 384      * @return the value
 385      * @throws DoesNotContainValueException if the subject did not contain a
 386      *         resource
 387      * @throws BindingException if value could not be produced using the given
 388      *         {@link Binding}
 389      * @throws ServiceException on connection and database failure
 390      * @see AsyncReadGraph#forValue
 391      */
 392     <T> T getValue(Resource subject, Binding binding) throws DoesNotContainValueException, BindingException,
 393     ServiceException;
 394
 395     /**
 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)}
 400      *
 401      * @param subject a resource
 402      * @param relation a resource
 403      * @return the value
 404      * @throws NoSingleResultException if the amount of valid values was not one
 405      * @throws DoesNotContainValueException if suitable o did not contain a
 406      *         resource
 407      * @throws ServiceException on connection and database failure
 408      * @see AsyncReadGraph#forRelatedValue
 409      */
 410     <T> T getRelatedValue(Resource subject, Resource relation) throws NoSingleResultException,
 411     DoesNotContainValueException, ServiceException;
 412
 413     /**
 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)}
 418      *
 419      * @param subject a resource
 420      * @param relation a resource
 421      * @return the value
 422      * @throws NoSingleResultException if the amount of valid values was not one
 423      * @throws DoesNotContainValueException if suitable o did not contain a
 424      *         resource
 425      * @throws ServiceException on connection and database failure
 426      * @see AsyncReadGraph#forRelatedValue
 427      */
 428     Variant getRelatedVariantValue(Resource subject, Resource relation) throws NoSingleResultException,
 429     DoesNotContainValueException, ServiceException;
 430
 431     /**
 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.
 435      *
 436      * @param subject a resource
 437      * @param relation a resource
 438      * @return the value
 439      * @throws NoSingleResultException if the amount of valid values was not one
 440      * @throws DoesNotContainValueException if suitable o did not contain a
 441      *         resource
 442      * @throws BindingException if value could not be produced using the given
 443      *         {@link Binding}
 444      * @throws ServiceException on connection and database failure
 445      * @see AsyncReadGraph#forRelatedValue
 446      */
 447     <T> T getRelatedValue(Resource subject, Resource relation, Binding binding) throws NoSingleResultException,
 448     DoesNotContainValueException, BindingException, ServiceException;
 449
 450     /**
 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.
 456      *
 457      * @param resource a resource
 458      * @param clazz the adapter class
 459      * @return
 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)
 465      */
 466     <T> T adapt(Resource resource, Class<T> clazz) throws AdaptionException, ValidationException, ServiceException;
 467
 468     /**
 469      *
 470      * Same as: adapt(getSingleObject(resource, relation), clazz);
 471      *
 472      * @param resource a resource
 473      * @param relation a resource
 474      * @param clazz the adapter class
 475      * @return
 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)
 481      */
 482     <T> T adaptRelated(Resource resource, Resource relation, Class<T> clazz) throws AdaptionException, NoSingleResultException, ValidationException, ServiceException;
 483
 484     /**
 485      *
 486      * Same as:
 487      *
 488      *  Resource r = getPossibleObject(resource, relation);
 489      *  if(r == null) return null;
 490      *  return getPossibleAdapter(r, clazz);
 491      *
 492      * @param resource a resource
 493      * @param relation a resource
 494      * @param clazz the adapter class
 495      * @return
 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)
 501      */
 502     <T> T getPossibleRelatedAdapter(Resource resource, Resource relation, Class<T> clazz) throws ValidationException, ServiceException;
 503
 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;
 506
 507     /**
 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.
 512      *
 513      * <p>
 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.
 517      * </p>
 518      *
 519      * @param resource a resource
 520      * @param clazz the adapter class
 521      * @return
 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)
 527      */
 528     <T> T adaptUnique(Resource resource, Class<T> clazz) throws AdaptionException, ValidationException,
 529     ServiceException;
 530
 531     /**
 532      * As {@link #getInverse} but returns null instead of an exception if
 533      * inverse was not found.
 534      *
 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
 541      */
 542     Resource getPossibleInverse(Resource relation) throws ManyObjectsForFunctionalRelationException, ServiceException;
 543
 544     /**
 545      * As {@link #getSingleObject} but returns null instead of an exception if
 546      * object was not found.
 547      *
 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
 555      */
 556     Resource getPossibleObject(Resource subject, Resource relation) throws ManyObjectsForFunctionalRelationException,
 557     ServiceException;
 558
 559     /**
 560      * As {@link #getSingleStatement} but returns null instead of an exception
 561      * if statement was not found.
 562      *
 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
 570      */
 571     Statement getPossibleStatement(Resource subject, Resource relation)
 572     throws ManyObjectsForFunctionalRelationException, ServiceException;
 573
 574     /**
 575      * As {@link #getSingleType} but returns null instead of an exception if
 576      * type was not found.
 577      *
 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
 583      */
 584     Resource getPossibleType(Resource subject, Resource baseType) throws ServiceException;
 585
 586     /**
 587      * As {@link #getValue} but returns null instead of an exception if value
 588      * was not found.
 589      *
 590      * @param subject a resource
 591      * @return the value or null
 592      * @throws ServiceException on connection and database failures
 593      * @see AsyncReadGraph#forPossibleValue
 594      */
 595     <T> T getPossibleValue(Resource subject) throws ServiceException;
 596
 597     /**
 598      * As {@link #getValue} but returns null instead of an exception if value
 599      * was not found.
 600      *
 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
 605      *         {@link Binding}
 606      * @throws ServiceException on connection and database failures
 607      * @see AsyncReadGraph#forPossibleValue
 608      */
 609     <T> T getPossibleValue(Resource subject, Binding binding) throws BindingException, ServiceException;
 610
 611     /**
 612      * As {@link #getPossibleRelatedValue} but returns null instead of an
 613      * exception if value was not found.
 614      *
 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
 622      */
 623     <T> T getPossibleRelatedValue(Resource subject, Resource relation)
 624     throws ManyObjectsForFunctionalRelationException, ServiceException;
 625
 626     /**
 627      * As {@link #getPossibleRelatedValue} but returns null instead of an
 628      * exception if value was not found.
 629      *
 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
 637      *         {@link Binding}
 638      * @throws ServiceException on connection and database failures
 639      * @see AsyncReadGraph#forPossibleRelatedValue
 640      */
 641     <T> T getPossibleRelatedValue(Resource subject, Resource relation, Binding binding)
 642     throws ManyObjectsForFunctionalRelationException, BindingException, ServiceException;
 643
 644     /**
 645      * As {@link #adapt} but returns null instead of an exception if adapter was
 646      * not found
 647      *
 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}
 654      */
 655     <T> T getPossibleAdapter(Resource resource, Class<T> clazz) throws ValidationException, ServiceException;
 656
 657     /**
 658      * As {@link #adaptUnique} but returns null instead of an exception if
 659      * adapter was not found
 660      *
 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}
 667      */
 668     <T> T getPossibleUniqueAdapter(Resource resource, Class<T> clazz) throws ValidationException, ServiceException;
 669
 670     /**
 671      * Returns true if type is included in the result of {@link #getTypes(resource)}
 672      *
 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}
 678      */
 679     boolean isInstanceOf(Resource resource, Resource type) throws ServiceException;
 680
 681     /**
 682      * Returns true if type equals resource or type is included in the result of
 683      * {@link #getSupertypes(resource)}
 684      *
 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}
 690      */
 691     boolean isInheritedFrom(Resource resource, Resource type) throws ServiceException;
 692
 693     /**
 694      * Returns true if relation equals resource or relation is included in the result of
 695      * {@link #getSuperrelations(resource)}
 696      *
 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}
 702      */
 703     boolean isSubrelationOf(Resource resource, Resource relation) throws ServiceException;
 704
 705     /**
 706      * Returns true if the result of {@link #getStatements(subject, IsWeaklyRelatedTo)} is nonempty.
 707      *
 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}
 712      */
 713     boolean hasStatement(Resource subject) throws ServiceException;
 714
 715     /**
 716      * Returns true if the result of {@link #getStatements(subject, relation)} is nonempty.
 717      *
 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}
 723      */
 724     boolean hasStatement(Resource subject, Resource relation) throws ServiceException;
 725
 726     /**
 727      * Returns true if a statement (subject, relation, object) exists after assertions.
 728      *
 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}
 735      */
 736     boolean hasStatement(Resource subject, Resource relation, Resource object) throws ServiceException;
 737
 738     /**
 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.
 743      *
 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}
 748      */
 749     boolean hasValue(Resource subject) throws ServiceException;
 750
 751     /**
 752      * Returns the data type of the literal.
 753      * @param subject
 754      * @return
 755      * @throws DatabaseException
 756      */
 757     Datatype getDataType(Resource subject) throws DatabaseException;
 758
 759     /**
 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.
 764      *
 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
 769      */
 770     <T extends Accessor> T getAccessor(Resource resource) throws DatabaseException;
 771
 772     /**
 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.
 777      *
 778      * @param <T>
 779      * @param resource is the literal containing the value.
 780      * @return interface to partially read and write the literal value.
 781      * @throws DatabaseException
 782      */
 783     RandomAccessBinary getRandomAccessBinary(Resource resource) throws DatabaseException;
 784 //    @SuppressWarnings("rawtypes")
 785 //      Function getValueFunction(Resource resource) throws DatabaseException;
 786
 787     /**
 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.
 790      * <p>
 791      * See {@link #getValue2(Resource, Object, Binding)} for more details.
 792      *
 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)
 801      */
 802     <T> T getValue2(Resource subject, Object context) throws DatabaseException;
 803
 804     /**
 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.
 807      * <p>
 808      * See {@link #getValue2(Resource, Object, Binding)} for more details.
 809      *
 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)
 818      */
 819     Variant getVariantValue2( Resource r, Object context ) throws DatabaseException;
 820
 821     /**
 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.
 825      * <p>
 826      * See {@link #getValue2(Resource, Object, Binding)} for more details.
 827      *
 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)
 834      */
 835     <T> T getPossibleValue2(Resource subject, Object context) throws DatabaseException;
 836
 837     /**
 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.
 840      * <p>
 841      * The following methods are tried in order to retrieve the value:
 842      * <ol>
 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>
 849      * </ul>
 850      *
 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)
 860      */
 861     <T> T getValue2(Resource subject, Object context, Binding binding) throws DatabaseException;
 862
 863     /**
 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.
 867      * <p>
 868      * See {@link #getValue2(Resource, Object, Binding)} for more details.
 869      *
 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)
 877      */
 878     <T> T getPossibleValue2(Resource subject, Object context, Binding binding) throws DatabaseException;
 879
 880     /**
 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.
 883      * <p>
 884      * See {@link #getValue2(Resource, Object, Binding)} for more details.
 885      *
 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)
 897      */
 898     <T> T getRelatedValue2(Resource subject, Resource relation) throws DatabaseException;
 899
 900     /**
 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.
 903      * <p>
 904      * See {@link #getValue2(Resource, Object, Binding)} for more details.
 905      *
 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)
 914      */
 915     <T> T getPossibleRelatedValue2(Resource subject, Resource relation) throws DatabaseException;
 916
 917     /**
 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.
 920      * <p>
 921      * See {@link #getValue2(Resource, Object, Binding)} for more details.
 922      *
 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)
 931      */
 932     Variant getRelatedVariantValue2( Resource subject, Resource relation ) throws DatabaseException;
 933
 934     /**
 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.
 937      * <p>
 938      * See {@link #getValue2(Resource, Object, Binding)} for more details.
 939      *
 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)
 952      */
 953     <T> T getRelatedValue2(Resource subject, Resource relation, Object context) throws DatabaseException;
 954
 955     /**
 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.
 958      * <p>
 959      * See {@link #getValue2(Resource, Object, Binding)} for more details.
 960      *
 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)
 971      */
 972     Variant getRelatedVariantValue2( Resource subject, Resource relation, Object context ) throws DatabaseException;
 973
 974     /**
 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.
 977      * <p>
 978      * See {@link #getValue2(Resource, Object, Binding)} for more details.
 979      *
 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)
 989      */
 990     <T> T getPossibleRelatedValue2(Resource subject, Resource relation, Object context) throws DatabaseException;
 991
 992     /**
 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.
 995      * <p>
 996      * See {@link #getValue2(Resource, Object, Binding)} for more details.
 997      *
 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)
1010      */
1011     <T> T getRelatedValue2(Resource subject, Resource relation, Binding binding) throws DatabaseException;
1012
1013     /**
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.
1016      * <p>
1017      * See {@link #getValue2(Resource, Object, Binding)} for more details.
1018      *
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)
1028      */
1029     <T> T getPossibleRelatedValue2(Resource subject, Resource relation, Binding binding) throws DatabaseException;
1030
1031     /**
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.
1034      * <p>
1035      * See {@link #getValue2(Resource, Object, Binding)} for more details.
1036      *
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)
1050      */
1051     <T> T getRelatedValue2(Resource subject, Resource relation, Object context, Binding binding) throws DatabaseException;
1052
1053     /**
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.
1056      * <p>
1057      * See {@link #getValue2(Resource, Object, Binding)} for more details.
1058      *
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)
1069      */
1070     <T> T getPossibleRelatedValue2(Resource subject, Resource relation, Object context, Binding binding) throws DatabaseException;
1071
1072     /**
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.
1075      * <p>
1076      * See {@link #getValue2(Resource, Object, Binding)} for more details.
1077      *
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
1082      */
1083     Type getRelatedValueType(Resource subject, Resource relation) throws DatabaseException;
1084
1085     boolean setSynchronous(boolean value);
1086     boolean getSynchronous();
1087 }