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.Set;
  16
  17 import org.simantics.databoard.accessor.Accessor;
  18 import org.simantics.databoard.binding.Binding;
  19 import org.simantics.databoard.binding.mutable.Variant;
  20 import org.simantics.databoard.type.Datatype;
  21 import org.simantics.databoard.util.binary.RandomAccessBinary;
  22 import org.simantics.db.adaption.Adapter;
  23 import org.simantics.db.exception.AdaptionException;
  24 import org.simantics.db.exception.AssumptionException;
  25 import org.simantics.db.exception.BindingException;
  26 import org.simantics.db.exception.DatabaseException;
  27 import org.simantics.db.exception.DoesNotContainValueException;
  28 import org.simantics.db.exception.ManyObjectsForFunctionalRelationException;
  29 import org.simantics.db.exception.NoInverseException;
  30 import org.simantics.db.exception.NoSingleResultException;
  31 import org.simantics.db.exception.ResourceNotFoundException;
  32 import org.simantics.db.exception.ServiceException;
  33 import org.simantics.db.exception.ValidationException;
  34 import org.simantics.db.procedure.SyncListener;
  35 import org.simantics.db.procedure.SyncMultiListener;
  36 import org.simantics.db.procedure.SyncMultiProcedure;
  37 import org.simantics.db.procedure.SyncProcedure;
  38 import org.simantics.db.procedure.SyncSetListener;
  39 import org.simantics.db.request.MultiRead;
  40 import org.simantics.db.request.Read;
  41 import org.simantics.scl.compiler.types.Type;
  42
  43 /**
  44  *
  45  * For accessing and manipulating the graph data in synchronous manner. A client
  46  * receives ReadGraph instances for performing requests in {@link Read} and
  47  * {@link MultiRead} as well as for reacting to request results using
  48  * {@link SyncProcedure}, {@link SyncListener}, {@link SyncMultiProcedure},
  49  * {@link SyncMultiListener} and {@link SyncSetListener}
  50  * <p>
  51  * ReadGraph instances are stateful and may not be stored and used outside the
  52  * supplier method activation. The methods receiving ReadGraph should not block
  53  * for long periods of time since that may delay the processing of other
  54  * requests. For an asynchronous counterpart with the same functionality as
  55  * ReadGraph see {@link AsyncReadGraph}
  56  *
  57  * <p>
  58  * All collections returned by the methods on this interface must not be
  59  * modified by clients unless explicitly stated otherwise.
  60  *
  61  * @version 0.7
  62  * @author Antti Villberg
  63  * @see RequestProcessor
  64  * @see AsyncRequestProcessor
  65  * @see AsyncReadGraph
  66  * @see Resource
  67  * @see Statement
  68  * @noimplement
  69  */
  70 public interface ReadGraph extends AsyncReadGraph, RequestProcessor {
  71
  72     /**
  73      *
  74      * @see AsyncReadGraph#forURI
  75      */
  76     String getURI(Resource resource) throws AssumptionException, ValidationException, ServiceException;
  77     String getPossibleURI(Resource resource) throws ValidationException, ServiceException;
  78
  79     /**
  80      * Gets a unique resource associated to the given identifier. See <a
  81      * href="https://www.simantics.org/wiki/index.php/URI">Simantics Wiki page
  82      * on URIs</a> for more details.
  83      *
  84      * @param uri the identifier
  85      * @return the resource
  86      * @throws ResourceNotFoundException if a resource for the given identifier
  87      *         was not specified
  88      * @throws ValidationException if a resource could not be produced due to
  89      *         invalid semantics
  90      * @throws ServiceException on connection and database failures
  91      * @see AsyncReadGraph#forResourceByURI
  92      */
  93     Resource getResource(String uri) throws ResourceNotFoundException, ValidationException, ServiceException;
  94
  95     /**
  96      * Gets a unique resource associated to the given identifier. See <a
  97      * href="https://www.simantics.org/wiki/index.php/URI">Simantics Wiki page
  98      * on URIs</a> for more details.
  99      *
 100      * @param uri the identifier
 101      * @return the resource
 102      * @throws ResourceNotFoundException if a resource for the given identifier
 103      *         was not specified
 104      * @throws ValidationException if a resource could not be produced due to
 105      *         invalid semantics
 106      * @throws ServiceException on connection and database failures
 107      * @see AsyncReadGraph#forResourceByURI
 108      */
 109     Resource getPossibleResource(String uri) throws ResourceNotFoundException, ValidationException, ServiceException;
 110
 111     /**
 112      * Gets a builtin resource. For a list of builtin resources see TODO Wiki
 113      *
 114      * @param uri the identifier
 115      * @return the resource
 116      * @throws ResourceNotFoundException if resouce was not found
 117      * @throws ServiceException on connection and database failures
 118      * @see AsyncReadGraph#forBuiltin
 119      */
 120     Resource getBuiltin(String id) throws ResourceNotFoundException, ServiceException;
 121
 122     /**
 123      * Gets all statements (subject, p, o) such that
 124      * {@link ReadGraph#isSubrelationOf(p, relation)} returns true. The result
 125      * may include asserted statements for which s does not equal subject. See
 126      * the assertion mechanisn TODO for more details. If the relation is
 127      * functional the request returns a single statement according to the
 128      * functional statement shadowing rules TODO if possible. If an invalid
 129      * graph is encountered an exception is thrown.
 130      *
 131      * @param subject a resource
 132      * @param relation a resource
 133      * @return the statements
 134      * @throws ManyObjectsForFunctionalRelationException on invalid graph with
 135      *         more than one functional object
 136      * @throws ServiceException on connection and database failures
 137      * @see AsyncReadGraph#forEachStatement
 138      * @see AsyncReadGraph#forStatementSet
 139      */
 140     Collection<Statement> getStatements(Resource subject, Resource relation)
 141     throws ManyObjectsForFunctionalRelationException, ServiceException;
 142
 143     /**
 144      * Gets all statements (s, p, o) asserted by subject such that
 145      * {@link ReadGraph#isSubrelationOf(p, relation)} returns true. See the
 146      * assertion mechanism TODO for more details. If the relation is functional
 147      * the request returns a single statement according to the functional
 148      * statement shadowing rules TODO if possible. If an invalid graph is
 149      * encountered an exception is thrown.
 150      *
 151      * @param subject a resource
 152      * @param relation a resource
 153      * @return the statements
 154      * @throws ManyObjectsForFunctionalRelationException on invalid graph with
 155      *         more than one functional object
 156      * @throws ServiceException on connection and database failures
 157      * @see AsyncReadGraph#forEachAssertedStatement
 158      * @see AsyncReadGraph#forAssertedStatementSet
 159      */
 160     Collection<Statement> getAssertedStatements(Resource subject, Resource relation)
 161     throws ManyObjectsForFunctionalRelationException, ServiceException;
 162
 163     /**
 164      * Gets all predicates p from statements (subject, p, o) such that
 165      * {@link ReadGraph#isSubrelationOf(p, relation)} returns true. See the
 166      * assertion mechanism TODO for more details. If the relation is functional
 167      * the request returns a single statement according to the functional
 168      * statement shadowing rules TODO if possible. If an invalid graph is
 169      * encountered an exception is thrown.
 170      *
 171      * @param subject a resource
 172      * @param relation a resource
 173      * @return the predicates
 174      * @throws ManyObjectsForFunctionalRelationException on invalid graph with
 175      *         more than one object
 176      * @throws ServiceException on connection and database failures
 177      * @see AsyncReadGraph#forEachPredicate
 178      * @see AsyncReadGraph#forPredicateSet
 179      */
 180     Collection<Resource> getPredicates(Resource subject) throws ServiceException;
 181
 182     /**
 183      * Gets a subset of all types of the subject such that no pair of returned
 184      * types inherit each other and all types of the subject are supertypes
 185      * of some type in the returned set.
 186      *
 187      * @param subject a resource
 188      * @return the principal types
 189      * @throws ServiceException on connection and database failures
 190      * @see AsyncReadGraph#forEachPrincipalType
 191      * @see AsyncReadGraph#forPrincipalTypeSet
 192      */
 193     Collection<Resource> getPrincipalTypes(Resource subject) throws ServiceException;
 194
 195     /**
 196      * Gets the full type hierarchy for subject.
 197      *
 198      * @param subject a resource
 199      * @return the type hierarchy
 200      * @throws ServiceException on connection and database failures
 201      * @see AsyncReadGraph#forTypes
 202      */
 203     Set<Resource> getTypes(Resource subject) throws ServiceException;
 204
 205     /**
 206      * Gets the full supertype hierarchy for subject.
 207      *
 208      * @param subject a resource
 209      * @return the supertype hierarchy
 210      * @throws ServiceException on connection and database failures
 211      * @see AsyncReadGraph#forSupertypes
 212      */
 213     Set<Resource> getSupertypes(Resource subject) throws ServiceException;
 214
 215     /**
 216      * Gets the full superrelation hierarchy for subject.
 217      *
 218      * @param subject a resource
 219      * @return the superrelation hierarchy
 220      * @throws ServiceException on connection and database failures
 221      * @see AsyncReadGraph#forSuperrelations
 222      */
 223     Set<Resource> getSuperrelations(Resource subject) throws ServiceException;
 224     Resource getPossibleSuperrelation(Resource subject) throws ServiceException;
 225
 226     /**
 227      * Gets all objects o from statements (subject, p, o) such that
 228      * {@link ReadGraph#isSubrelationOf(p, relation)} returns true. See the
 229      * assertion mechanisn TODO for more details. If the relation is functional
 230      * the request returns a single object according to the functional statement
 231      * shadowing rules TODO if possible. If an invalid graph is encountered an
 232      * exception is thrown.
 233      *
 234      * @param subject a resource
 235      * @param relation a resource
 236      * @return the objects
 237      * @throws ManyObjectsForFunctionalRelationException on invalid graph with
 238      *         more than one functional object
 239      * @throws ServiceException on connection and database failures
 240      * @see AsyncReadGraph#forEachObject
 241      * @see AsyncReadGraph#forObjectSet
 242      */
 243     Collection<Resource> getObjects(Resource subject, Resource relation)
 244     throws ServiceException;
 245
 246     /**
 247      * Gets all objects o (s, p, o) asserted by subject such that
 248      * {@link ReadGraph#isSubrelationOf(p, relation)} returns true. See the
 249      * assertion mechanism TODO for more details. If the relation is functional
 250      * the request returns a single object according to the functional statement
 251      * shadowing rules TODO if possible. If an invalid graph is encountered an
 252      * exception is thrown.
 253      *
 254      * @param subject a resource
 255      * @param relation a resource
 256      * @return the objects
 257      * @throws ManyObjectsForFunctionalRelationException on invalid graph with
 258      *         more than one functional object
 259      * @throws ServiceException on connection and database failures
 260      * @see AsyncReadGraph#forEachAssertedStatement
 261      * @see AsyncReadGraph#forAssertedStatementSet
 262      */
 263     Collection<Resource> getAssertedObjects(Resource subject, Resource relation)
 264     throws ManyObjectsForFunctionalRelationException, ServiceException;
 265
 266     /**
 267      * Gets the inverse r of relation such that (relation, InverseOf, r). The
 268      * methods assumes an inverse exists.
 269      *
 270      * @param relation a resource
 271      * @return the inverse
 272      * @throws NoInverseException if inverse was not fond
 273      * @throws ManyObjectsForFunctionalRelationException on invalid graph with
 274      *         more than one functional object
 275      * @throws ServiceException on connection and database failures
 276      * @see AsyncReadGraph#forInverse
 277      */
 278     Resource getInverse(Resource relation) throws NoInverseException, ManyObjectsForFunctionalRelationException,
 279     ServiceException;
 280
 281     /**
 282      * Gets a single object as returned by {@link ReadGraph#getObjects}. Assumes
 283      * a single object.
 284      *
 285      * @param subject a resource
 286      * @param relation a resource
 287      * @return the single object
 288      * @throws NoSingleResultException if the amount of valid objects was not
 289      *         one
 290      * @throws ManyObjectsForFunctionalRelationException on invalid graph with
 291      *         more than one functional object
 292      * @throws ServiceException on connection and database failures
 293      * @see AsyncReadGraph#forSingleObject
 294      */
 295     Resource getSingleObject(Resource subject, Resource relation) throws NoSingleResultException,
 296     ManyObjectsForFunctionalRelationException, ServiceException;
 297
 298     /**
 299      * Gets a single statement as returned by {@link ReadGraph#getStatements}.
 300      * Assumes a single statement.
 301      *
 302      * @param subject a resource
 303      * @param relation a resource
 304      * @return the single statement
 305      * @throws NoSingleResultException if the amount of valid statements was not
 306      *         one
 307      * @throws ManyObjectsForFunctionalRelationException on invalid graph with
 308      *         more than one functional object
 309      * @throws ServiceException on connection and database failures
 310      * @see AsyncReadGraph#forSingleStatement
 311      */
 312     Statement getSingleStatement(Resource subject, Resource relation) throws NoSingleResultException,
 313     ManyObjectsForFunctionalRelationException, ServiceException;
 314
 315     /**
 316      * Gets a single type t as returned by {@link ReadGraph#getPrincipalTypes}. Assumes a single type.
 317      *
 318      * @param subject a resource
 319      * @param baseType a resource
 320      * @return the single type
 321      * @throws NoSingleResultException if the amount of valid types was not one
 322      * @throws ServiceException on connection and database failures
 323      * @see AsyncReadGraph#forSingleType
 324      */
 325     Resource getSingleType(Resource subject) throws NoSingleResultException, ServiceException;
 326
 327     /**
 328      * Gets a single type t as returned by {@link ReadGraph#getTypes} where
 329      * {@link ReadGraph#isInheritedFrom(t, baseType)}. 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, Resource baseType) throws NoSingleResultException, ServiceException;
 339
 340     /**
 341      * Gets a value associated to subject. Infers {@link Binding} from type t =
 342      * {@link ReadGraph#getSingleType(subject, Value)}
 343      *
 344      * @param subject a resource
 345      * @return the value
 346      * @throws DoesNotContainValueException if the subject did not contain a
 347      *         resource
 348      * @throws ServiceException on connection and database failure
 349      * @see AsyncReadGraph#forValue
 350      */
 351     <T> T getValue(Resource subject) throws DoesNotContainValueException, ServiceException;
 352
 353     /**
 354      * Gets a value associated to subject as a Variant. 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     Variant getVariantValue(Resource subject) throws DoesNotContainValueException, ServiceException;
 365
 366     /**
 367      * Gets a value associated to subject using the given {@link Binding}.
 368      *
 369      * @param subject a resource
 370      * @param binding a binding
 371      * @return the value
 372      * @throws DoesNotContainValueException if the subject did not contain a
 373      *         resource
 374      * @throws BindingException if value could not be produced using the given
 375      *         {@link Binding}
 376      * @throws ServiceException on connection and database failure
 377      * @see AsyncReadGraph#forValue
 378      */
 379     <T> T getValue(Resource subject, Binding binding) throws DoesNotContainValueException, BindingException,
 380     ServiceException;
 381
 382     /**
 383      * Gets a single value associated to o such that (subject, r, o) and
 384      * {@link ReadGraph#isSubrelationOf(r, relation)}. Assumes a single value.
 385      * Infers {@link Binding} from type t =
 386      * {@link ReadGraph#getSingleType(o, Value)}
 387      *
 388      * @param subject a resource
 389      * @param relation a resource
 390      * @return the value
 391      * @throws NoSingleResultException if the amount of valid values was not one
 392      * @throws DoesNotContainValueException if suitable o did not contain a
 393      *         resource
 394      * @throws ServiceException on connection and database failure
 395      * @see AsyncReadGraph#forRelatedValue
 396      */
 397     <T> T getRelatedValue(Resource subject, Resource relation) throws NoSingleResultException,
 398     DoesNotContainValueException, ServiceException;
 399
 400     /**
 401      * Gets a single value associated to o such that (subject, r, o) and
 402      * {@link ReadGraph#isSubrelationOf(r, relation)} as a Variant. Assumes a single value.
 403      * Infers {@link Binding} from type t =
 404      * {@link ReadGraph#getSingleType(o, Value)}
 405      *
 406      * @param subject a resource
 407      * @param relation a resource
 408      * @return the value
 409      * @throws NoSingleResultException if the amount of valid values was not one
 410      * @throws DoesNotContainValueException if suitable o did not contain a
 411      *         resource
 412      * @throws ServiceException on connection and database failure
 413      * @see AsyncReadGraph#forRelatedValue
 414      */
 415     Variant getRelatedVariantValue(Resource subject, Resource relation) throws NoSingleResultException,
 416     DoesNotContainValueException, ServiceException;
 417
 418     /**
 419      * Gets a single value associated to o such that (subject, r, o) and
 420      * {@link ReadGraph#isSubrelationOf(r, relation)}. Uses the given
 421      * {@link Binding}. Assumes a single value.
 422      *
 423      * @param subject a resource
 424      * @param relation a resource
 425      * @return the value
 426      * @throws NoSingleResultException if the amount of valid values was not one
 427      * @throws DoesNotContainValueException if suitable o did not contain a
 428      *         resource
 429      * @throws BindingException if value could not be produced using the given
 430      *         {@link Binding}
 431      * @throws ServiceException on connection and database failure
 432      * @see AsyncReadGraph#forRelatedValue
 433      */
 434     <T> T getRelatedValue(Resource subject, Resource relation, Binding binding) throws NoSingleResultException,
 435     DoesNotContainValueException, BindingException, ServiceException;
 436
 437     /**
 438      * Tries to adapt the specified resource into an instance of the specified
 439      * class T. No guarantees are made on return values of this method. The
 440      * returned values can be cached results of previous invocation or they can
 441      * be new result object instances. See {@link #adaptUnique(Resource, Class)}
 442      * for alternative behaviour.
 443      *
 444      * @param resource a resource
 445      * @param clazz the adapter class
 446      * @return
 447      * @throws AdaptionException if suitable adapter was not found
 448      * @throws ValidationException from the adapter
 449      * @throws ServiceException on connection and database failure
 450      * @see AsyncReadGraph#forAdapted
 451      * @see #adaptUnique(Resource, Class)
 452      */
 453     <T> T adapt(Resource resource, Class<T> clazz) throws AdaptionException, ValidationException, ServiceException;
 454
 455     /**
 456      *
 457      * Same as: adapt(getSingleObject(resource, relation), clazz);
 458      *
 459      * @param resource a resource
 460      * @param relation a resource
 461      * @param clazz the adapter class
 462      * @return
 463      * @throws AdaptionException if suitable adapter was not found
 464      * @throws ValidationException from the adapter
 465      * @throws ServiceException on connection and database failure
 466      * @see AsyncReadGraph#forAdapted
 467      * @see #adaptUnique(Resource, Class)
 468      */
 469     <T> T adaptRelated(Resource resource, Resource relation, Class<T> clazz) throws AdaptionException, NoSingleResultException, ValidationException, ServiceException;
 470
 471     /**
 472      *
 473      * Same as:
 474      *
 475      *  Resource r = getPossibleObject(resource, relation);
 476      *  if(r == null) return null;
 477      *  return getPossibleAdapter(r, clazz);
 478      *
 479      * @param resource a resource
 480      * @param relation a resource
 481      * @param clazz the adapter class
 482      * @return
 483      * @throws AdaptionException if suitable adapter was not found
 484      * @throws ValidationException from the adapter
 485      * @throws ServiceException on connection and database failure
 486      * @see AsyncReadGraph#forAdapted
 487      * @see #adaptUnique(Resource, Class)
 488      */
 489     <T> T getPossibleRelatedAdapter(Resource resource, Resource relation, Class<T> clazz) throws ValidationException, ServiceException;
 490
 491     <T,C> T adaptContextual(Resource resource, C context, Class<C> contextClass, Class<T> clazz) throws AdaptionException, NoSingleResultException, ValidationException, ServiceException;
 492     <T,C> T getPossibleContextualAdapter(Resource resource, C context, Class<C> contextClass, Class<T> clazz) throws ValidationException, ServiceException;
 493
 494     /**
 495      * Tries to adapt the specified resource into an instance of the specified
 496      * class T. The difference to {@link #adapt(Resource, Class)} is that this
 497      * method does everything possible to return a new object instance for each
 498      * separate invocation.
 499      *
 500      * <p>
 501      * The only case when this cannot be guaranteed is when the adaption result
 502      * comes from an {@link Adapter} implementation which can internally do
 503      * anything, like always return the same singleton instance.
 504      * </p>
 505      *
 506      * @param resource a resource
 507      * @param clazz the adapter class
 508      * @return
 509      * @throws AdaptionException if suitable adapter was not found
 510      * @throws ValidationException from the adapter
 511      * @throws ServiceException on connection and database failure
 512      * @see AsyncReadGraph#forAdapted
 513      * @see #adapt(Resource, Class)
 514      */
 515     <T> T adaptUnique(Resource resource, Class<T> clazz) throws AdaptionException, ValidationException,
 516     ServiceException;
 517
 518     /**
 519      * As {@link #getInverse} but returns null instead of an exception if
 520      * inverse was not found.
 521      *
 522      * @param relation a resource
 523      * @return the inverse or null
 524      * @throws ManyObjectsForFunctionalRelationException on invalid graph with
 525      *         more than one functional object
 526      * @throws ServiceException on connection and database failures
 527      * @see AsyncReadGraph#forPossibleInverse
 528      */
 529     Resource getPossibleInverse(Resource relation) throws ManyObjectsForFunctionalRelationException, ServiceException;
 530
 531     /**
 532      * As {@link #getSingleObject} but returns null instead of an exception if
 533      * object was not found.
 534      *
 535      * @param subject a resource
 536      * @param relation a resource
 537      * @return the object or null
 538      * @throws ManyObjectsForFunctionalRelationException on invalid graph with
 539      *         more than one functional object
 540      * @throws ServiceException on connection and database failures
 541      * @see AsyncReadGraph#forPossibleObject
 542      */
 543     Resource getPossibleObject(Resource subject, Resource relation) throws ManyObjectsForFunctionalRelationException,
 544     ServiceException;
 545
 546     /**
 547      * As {@link #getSingleStatement} but returns null instead of an exception
 548      * if statement was not found.
 549      *
 550      * @param subject a resource
 551      * @param relation a resource
 552      * @return the statement or null
 553      * @throws ManyObjectsForFunctionalRelationException on invalid graph with
 554      *         more than one functional object
 555      * @throws ServiceException on connection and database failures
 556      * @see AsyncReadGraph#forPossibleStatement
 557      */
 558     Statement getPossibleStatement(Resource subject, Resource relation)
 559     throws ManyObjectsForFunctionalRelationException, ServiceException;
 560
 561     /**
 562      * As {@link #getSingleType} but returns null instead of an exception if
 563      * type was not found.
 564      *
 565      * @param subject a resource
 566      * @param baseType a resource
 567      * @return the type or null
 568      * @throws ServiceException on connection and database failures
 569      * @see AsyncReadGraph#forPossibleType
 570      */
 571     Resource getPossibleType(Resource subject, Resource baseType) throws ServiceException;
 572
 573     /**
 574      * As {@link #getValue} but returns null instead of an exception if value
 575      * was not found.
 576      *
 577      * @param subject a resource
 578      * @return the value or null
 579      * @throws ServiceException on connection and database failures
 580      * @see AsyncReadGraph#forPossibleValue
 581      */
 582     <T> T getPossibleValue(Resource subject) throws ServiceException;
 583
 584     /**
 585      * As {@link #getValue} but returns null instead of an exception if value
 586      * was not found.
 587      *
 588      * @param subject a resource
 589      * @param binding a {@link Binding}
 590      * @return the value or null
 591      * @throws BindingException if value could not be produced using the given
 592      *         {@link Binding}
 593      * @throws ServiceException on connection and database failures
 594      * @see AsyncReadGraph#forPossibleValue
 595      */
 596     <T> T getPossibleValue(Resource subject, Binding binding) throws BindingException, ServiceException;
 597
 598     /**
 599      * As {@link #getPossibleRelatedValue} but returns null instead of an
 600      * exception if value was not found.
 601      *
 602      * @param subject a resource
 603      * @param relation a resource
 604      * @return the value or null
 605      * @throws ManyObjectsForFunctionalRelationException on invalid graph with
 606      *         more than one functional object
 607      * @throws ServiceException on connection and database failures
 608      * @see AsyncReadGraph#forPossibleRelatedValue
 609      */
 610     <T> T getPossibleRelatedValue(Resource subject, Resource relation)
 611     throws ManyObjectsForFunctionalRelationException, ServiceException;
 612
 613     /**
 614      * As {@link #getPossibleRelatedValue} but returns null instead of an
 615      * exception if value was not found.
 616      *
 617      * @param subject a resource
 618      * @param relation a resource
 619      * @param binding a {@link Binding}
 620      * @return the value or null
 621      * @throws ManyObjectsForFunctionalRelationException on invalid graph with
 622      *         more than one functional object
 623      * @throws BindingException if value could not be produced using the given
 624      *         {@link Binding}
 625      * @throws ServiceException on connection and database failures
 626      * @see AsyncReadGraph#forPossibleRelatedValue
 627      */
 628     <T> T getPossibleRelatedValue(Resource subject, Resource relation, Binding binding)
 629     throws ManyObjectsForFunctionalRelationException, BindingException, ServiceException;
 630
 631     /**
 632      * As {@link #adapt} but returns null instead of an exception if adapter was
 633      * not found
 634      *
 635      * @param subject a resource
 636      * @param clazz a Class
 637      * @return the adapter or null
 638      * @throws ValidationException when ?
 639      * @throws ServiceException on connection and database failures
 640      * @see {@link AsyncReadGraph#forPossibleAdapted}
 641      */
 642     <T> T getPossibleAdapter(Resource resource, Class<T> clazz) throws ValidationException, ServiceException;
 643
 644     /**
 645      * As {@link #adaptUnique} but returns null instead of an exception if
 646      * adapter was 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 getPossibleUniqueAdapter(Resource resource, Class<T> clazz) throws ValidationException, ServiceException;
 656
 657     /**
 658      * Returns true if type is included in the result of {@link #getTypes(resource)}
 659      *
 660      * @param subject a resource
 661      * @param type a resource
 662      * @return indicates if resource is an instance of type
 663      * @throws ServiceException on connection and database failures
 664      * @see {@link AsyncReadGraph#forIsInstanceOf}
 665      */
 666     boolean isInstanceOf(Resource resource, Resource type) throws ServiceException;
 667
 668     /**
 669      * Returns true if type equals resource or type is included in the result of
 670      * {@link #getSupertypes(resource)}
 671      *
 672      * @param subject a resource
 673      * @param type a resource
 674      * @return indicates if resource is inherited from type
 675      * @throws ServiceException on connection and database failures
 676      * @see {@link AsyncReadGraph#forIsInheritedFrom}
 677      */
 678     boolean isInheritedFrom(Resource resource, Resource type) throws ServiceException;
 679
 680     /**
 681      * Returns true if relation equals resource or relation is included in the result of
 682      * {@link #getSuperrelations(resource)}
 683      *
 684      * @param subject a resource
 685      * @param relation a resource
 686      * @return indicates if resource is a subrelation of relation
 687      * @throws ServiceException on connection and database failures
 688      * @see {@link AsyncReadGraph#forIsSubrelationOf}
 689      */
 690     boolean isSubrelationOf(Resource resource, Resource relation) throws ServiceException;
 691
 692     /**
 693      * Returns true if the result of {@link #getStatements(subject, IsWeaklyRelatedTo)} is nonempty.
 694      *
 695      * @param subject a resource
 696      * @return indicates that subject has statements
 697      * @throws ServiceException on connection and database failures
 698      * @see {@link AsyncReadGraph#forHasStatement}
 699      */
 700     boolean hasStatement(Resource subject) throws ServiceException;
 701
 702     /**
 703      * Returns true if the result of {@link #getStatements(subject, relation)} is nonempty.
 704      *
 705      * @param subject a resource
 706      * @param relation a resource
 707      * @return indicates that subject has statements with predicates as subrelation of relation
 708      * @throws ServiceException on connection and database failures
 709      * @see {@link AsyncReadGraph#forHasStatement}
 710      */
 711     boolean hasStatement(Resource subject, Resource relation) throws ServiceException;
 712
 713     /**
 714      * Returns true if a statement (subject, relation, object) exists after assertions.
 715      *
 716      * @param subject a resource
 717      * @param relation a resource
 718      * @param object a resource
 719      * @return indicates that the given statement exists
 720      * @throws ServiceException on connection and database failures
 721      * @see {@link AsyncReadGraph#forHasStatement}
 722      */
 723     boolean hasStatement(Resource subject, Resource relation, Resource object) throws ServiceException;
 724
 725     /**
 726      * Returns true if there is a value associated with subject.
 727      * IMPLEMENTATION NOTE:
 728      * Current implementation fetches the value from server. If the value is
 729      * large (i.e. not stored in the cluster) this is highly inefficient.
 730      *
 731      * @param subject a resource
 732      * @return indicates that a value exists
 733      * @throws ServiceException on connection and database failures
 734      * @see {@link AsyncReadGraph#forHasValue}
 735      */
 736     boolean hasValue(Resource subject) throws ServiceException;
 737
 738     /**
 739      * Returns the data type of the literal.
 740      * @param subject
 741      * @return
 742      * @throws DatabaseException
 743      */
 744     Datatype getDataType(Resource subject) throws DatabaseException;
 745
 746     /**
 747      * Returns an accessory that can be used to partially read the literal
 748      * or write if the graph is WriteGraph. The returned accessory is closed
 749      * automatically when the transaction ends. The modifications are written
 750      * back to graph at transaction completion.
 751      *
 752      * @param <T> is typed accessory for modifying the literal value.
 753      * @param resource is the literal containing the value.
 754      * @return interface to partially read and write the literal value.
 755      * @throws DatabaseException
 756      */
 757     <T extends Accessor> T getAccessor(Resource resource) throws DatabaseException;
 758
 759     /**
 760      * Returns an RandomAccessBinary that can be used to partially read the literal
 761      * or write if the graph is WriteGraph. The returned interface is closed
 762      * automatically when the transaction ends. The modifications are written
 763      * back to graph at transaction completion.
 764      *
 765      * @param <T>
 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     RandomAccessBinary getRandomAccessBinary(Resource resource) throws DatabaseException;
 771 //    @SuppressWarnings("rawtypes")
 772 //      Function getValueFunction(Resource resource) throws DatabaseException;
 773
 774     /**
 775      * Get the value associated with a graph {@link Resource}, using a possible context object and
 776      * a default data type binding. An exception is thrown, if the value is not found.
 777      * <p>
 778      * See {@link #getValue2(Resource, Object, Binding)} for more details.
 779      *
 780      * @param r  A graph resource with which the value is associated
 781      * @param context  A context object that is used for acquiring the value, can be {@code null}
 782      * @return  The value of the graph node.
 783      * @throws DoesNotContainValueException  No value is associated with the graph node.
 784      * @throws DatabaseException  Other errors, such as an error in casting the value to the return type or
 785      *         a runtime error in the value function.
 786      * @see #getValue2(Resource, Object, Binding)
 787      * @see #getPossibleValue2(Resource, Object)
 788      */
 789     <T> T getValue2(Resource subject, Object context) throws DatabaseException;
 790
 791     /**
 792      * Get the value associated with a graph {@link Resource}, using a possible context object and
 793      * a default data type binding as a Variant. An exception is thrown, if the value is not found.
 794      * <p>
 795      * See {@link #getValue2(Resource, Object, Binding)} for more details.
 796      *
 797      * @param r  A graph resource with which the value is associated
 798      * @param context  A context object that is used for acquiring the value, can be {@code null}
 799      * @return  The value of the graph node.
 800      * @throws DoesNotContainValueException  No value is associated with the graph node.
 801      * @throws DatabaseException  Other errors, such as an error in casting the value to the return type or
 802      *         a runtime error in the value function.
 803      * @see #getValue2(Resource, Object, Binding)
 804      * @see #getPossibleValue2(Resource, Object)
 805      */
 806     Variant getVariantValue2( Resource r, Object context ) throws DatabaseException;
 807
 808     /**
 809      * Get a possible value associated with a graph {@link Resource}, using a possible context object and
 810      * a desired value binding. Unlike {@link #getValue2(Resource, Object)}, this methods
 811      * returns {@code null} for missing values instead of throwing an exception.
 812      * <p>
 813      * See {@link #getValue2(Resource, Object, Binding)} for more details.
 814      *
 815      * @param r  A graph resource with which the value is associated
 816      * @param context  A context object that is used for acquiring the value, can be {@code null}
 817      * @return  The value of the graph node.
 818      * @throws DatabaseException  Usually should not happen. A null value is returned for possible errors.
 819      * @see #getValue2(Resource, Object)
 820      * @see #getPossibleValue2(Resource, Object, Binding)
 821      */
 822     <T> T getPossibleValue2(Resource subject, Object context) throws DatabaseException;
 823
 824     /**
 825      * Get the value associated with a graph {@link Resource}, using a possible context object and
 826      * a desired value binding. An exception is thrown, if the value is not found.
 827      * <p>
 828      * The following methods are tried in order to retrieve the value:
 829      * <ol>
 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>
 831      *   <li>If the resource is a {@code L0.ExternalValue}, the value is acquired using
 832      *       {@link ReflectionUtils#getValue(String)} with the resource URI.</li>
 833      *   <li>If the resource is associated with a suitable value converter with relation {@code L0.ConvertsToValueWith}
 834      *       (see {@link #requestValueFunction(Resource)}), the value function is called with the graph, the resource
 835      *       and the context object.</li>
 836      * </ul>
 837      *
 838      * @param r  A graph resource with which the value is associated
 839      * @param context  A context object that is used for acquiring the value, can be {@code null}
 840      * @param binding  A binding for the value type
 841      * @return  The value of the graph node.
 842      * @throws DoesNotContainValueException  No value is associated with the graph node.
 843      * @throws DatabaseException  Other errors, such as an error in casting the value to the return type or
 844      *         a runtime error in the value function.
 845      * @see #getValue2(Resource, Object)
 846      * @see #getPossibleValue2(Resource, Object, Binding)
 847      */
 848     <T> T getValue2(Resource subject, Object context, Binding binding) throws DatabaseException;
 849
 850     /**
 851      * Get a possible value associated with a graph {@link Resource}, using a possible context object and
 852      * a desired value binding. Unlike {@link #getValue2(Resource, Object, Binding)}, this methods
 853      * returns {@code null} for missing values instead of throwing an exception.
 854      * <p>
 855      * See {@link #getValue2(Resource, Object, Binding)} for more details.
 856      *
 857      * @param r  A graph resource with which the value is associated
 858      * @param context  A context object that is used for acquiring the value, can be {@code null}
 859      * @param binding  A binding for the value type
 860      * @return  The value of the graph node.
 861      * @throws DatabaseException  Usually should not happen. A null value is returned for possible errors.
 862      * @see #getValue2(Resource, Object, Bindinge)
 863      * @see #getPossibleValue2(Resource, Object)
 864      */
 865     <T> T getPossibleValue2(Resource subject, Object context, Binding binding) throws DatabaseException;
 866
 867     /**
 868      * Get the single value associated with a graph resource related with a given subject.
 869      * An exception is thrown, if a unique object resource or a value for it is not found.
 870      * <p>
 871      * See {@link #getValue2(Resource, Object, Binding)} for more details.
 872      *
 873      * @param subject  A graph resource that indicates the subject node
 874      * @param relation  A graph resource that indicates the predicate of a relation
 875      * @return  The value of the unique graph node that is asserted as the object of the given subject and predicate.
 876      * @throws NoSingleResultException  The number of suitable object resources is not equal to 1 (zero or greater than one)
 877      * @throws DoesNotContainValueException  No value is associated with the graph node.
 878      * @throws DatabaseException  Other errors, such as an error in casting the value to the return type or
 879      *         a runtime error in the value function.
 880      * @see #getRelatedValue2(Resource, Resource, Binding)
 881      * @see #getRelatedValue2(Resource, Resource, Object)
 882      * @see #getRelatedValue2(Resource, Resource, Object, Binding)
 883      * @see #getPossibleRelatedValue2(Resource, Resource)
 884      */
 885     <T> T getRelatedValue2(Resource subject, Resource relation) throws DatabaseException;
 886
 887     /**
 888      * Get a possible single value associated with a graph resource related with a given subject.
 889      * A {@code null} value is returned for missing values or other errors.
 890      * <p>
 891      * See {@link #getValue2(Resource, Object, Binding)} for more details.
 892      *
 893      * @param subject  A graph resource that indicates the subject node
 894      * @param relation  A graph resource that indicates the predicate of a relation
 895      * @return  The value of the unique graph node that is asserted as the object of the given subject and predicate.
 896      * @throws DatabaseException  Usually should not happen. A {@code null} value is returned for possible errors.
 897      * @see #getPossibleRelatedValue2(Resource, Resource, Binding)
 898      * @see #getPossibleRelatedValue2(Resource, Resource, Object)
 899      * @see #getPossibleRelatedValue2(Resource, Resource, Object, Binding)
 900      * @see #getRelatedValue2(Resource, Resource)
 901      */
 902     <T> T getPossibleRelatedValue2(Resource subject, Resource relation) throws DatabaseException;
 903
 904     /**
 905      * Get a possible single value associated with a graph resource related with a given subject.
 906      * A {@code null} value is returned for missing values or other errors.
 907      * <p>
 908      * See {@link #getValue2(Resource, Object, Binding)} for more details.
 909      *
 910      * @param subject  A graph resource that indicates the subject node
 911      * @param relation  A graph resource that indicates the predicate of a relation
 912      * @return  The value of the unique graph node that is asserted as the object of the given subject and predicate.
 913      * @throws DatabaseException  Usually should not happen. A {@code null} value is returned for possible errors.
 914      * @see #getPossibleRelatedValue2(Resource, Resource, Binding)
 915      * @see #getPossibleRelatedValue2(Resource, Resource, Object)
 916      * @see #getPossibleRelatedValue2(Resource, Resource, Object, Binding)
 917      * @see #getRelatedValue2(Resource, Resource)
 918      */
 919     Variant getRelatedVariantValue2( Resource subject, Resource relation ) throws DatabaseException;
 920
 921     /**
 922      * Get the single value associated with a graph resource related with a given subject, a possible context object.
 923      * An exception is thrown, if a unique object resource or a value for it is not found.
 924      * <p>
 925      * See {@link #getValue2(Resource, Object, Binding)} for more details.
 926      *
 927      * @param subject  A graph resource that indicates the subject node
 928      * @param relation  A graph resource that indicates the predicate of a relation
 929      * @param context  A context object that is used for acquiring the value, can be {@code null}
 930      * @return  The value of the unique graph node that is asserted as the object of the given subject and predicate.
 931      * @throws NoSingleResultException  The number of suitable object resources is not equal to 1 (zero or greater than one)
 932      * @throws DoesNotContainValueException  No value is associated with the graph node.
 933      * @throws DatabaseException  Other errors, such as an error in casting the value to the return type or
 934      *         a runtime error in the value function.
 935      * @see #getRelatedValue2(Resource, Resource)
 936      * @see #getRelatedValue2(Resource, Resource, Binding)
 937      * @see #getRelatedValue2(Resource, Resource, Object, Binding)
 938      * @see #getPossibleRelatedValue2(Resource, Resource, Object)
 939      */
 940     <T> T getRelatedValue2(Resource subject, Resource relation, Object context) throws DatabaseException;
 941
 942     /**
 943      * Get the single value associated with a graph resource related with a given subject, a possible context object.
 944      * An exception is thrown, if a unique object resource or a value for it is not found.
 945      * <p>
 946      * See {@link #getValue2(Resource, Object, Binding)} for more details.
 947      *
 948      * @param subject  A graph resource that indicates the subject node
 949      * @param relation  A graph resource that indicates the predicate of a relation
 950      * @param context  A context object that is used for acquiring the value, can be {@code null}
 951      * @return  The value of the unique graph node that is asserted as the object of the given subject and predicate.
 952      * @throws NoSingleResultException  The number of suitable object resources is not equal to 1 (zero or greater than one)
 953      * @throws DoesNotContainValueException  No value is associated with the graph node.
 954      * @throws DatabaseException  Other errors, such as an error in casting the value to the return type or
 955      *         a runtime error in the value function.
 956      * @see #getRelatedValue2(Resource, Resource, Object)
 957      * @see #getPossibleRelatedValue2(Resource, Resource, Object)
 958      */
 959     Variant getRelatedVariantValue2( Resource subject, Resource relation, Object context ) throws DatabaseException;
 960
 961     /**
 962      * Get a possible single value associated with a graph resource related with a given subject and a possible context object.
 963      * A {@code null} value is returned for missing values or other errors.
 964      * <p>
 965      * See {@link #getValue2(Resource, Object, Binding)} for more details.
 966      *
 967      * @param subject  A graph resource that indicates the subject node
 968      * @param relation  A graph resource that indicates the predicate of a relation
 969      * @param context  A context object that is used for acquiring the value, can be {@code null}
 970      * @return  The value of the unique graph node that is asserted as the object of the given subject and predicate.
 971      * @throws DatabaseException  Usually should not happen. A {@code null} value is returned for possible errors.
 972      * @see #getPossibleRelatedValue2(Resource, Resource)
 973      * @see #getPossibleRelatedValue2(Resource, Resource, Binding)
 974      * @see #getPossibleRelatedValue2(Resource, Resource, Object, Binding)
 975      * @see #getRelatedValue2(Resource, Resource, Object)
 976      */
 977     <T> T getPossibleRelatedValue2(Resource subject, Resource relation, Object context) throws DatabaseException;
 978
 979     /**
 980      * Get the single value associated with a graph resource related with a given subject and
 981      * a desired value binding. An exception is thrown, if a unique object resource or a value for it is not found.
 982      * <p>
 983      * See {@link #getValue2(Resource, Object, Binding)} for more details.
 984      *
 985      * @param subject  A graph resource that indicates the subject node
 986      * @param relation  A graph resource that indicates the predicate of a relation
 987      * @param binding  A binding for the value type
 988      * @return  The value of the unique graph node that is asserted as the object of the given subject and predicate.
 989      * @throws NoSingleResultException  The number of suitable object resources is not equal to 1 (zero or greater than one)
 990      * @throws DoesNotContainValueException  No value is associated with the graph node.
 991      * @throws DatabaseException  Other errors, such as an error in casting the value to the return type or
 992      *         a runtime error in the value function.
 993      * @see #getRelatedValue2(Resource, Resource)
 994      * @see #getRelatedValue2(Resource, Resource, Object)
 995      * @see #getRelatedValue2(Resource, Resource, Object, Binding)
 996      * @see #getPossibleRelatedValue2(Resource, Resource, Binding)
 997      */
 998     <T> T getRelatedValue2(Resource subject, Resource relation, Binding binding) throws DatabaseException;
 999
1000     /**
1001      * Get a possible single value associated with a graph resource related with a given subject and
1002      * a desired value binding. A {@code null} value is returned for missing values or other errors.
1003      * <p>
1004      * See {@link #getValue2(Resource, Object, Binding)} for more details.
1005      *
1006      * @param subject  A graph resource that indicates the subject node
1007      * @param relation  A graph resource that indicates the predicate of a relation
1008      * @param binding  A binding for the value type
1009      * @return  The value of the unique graph node that is asserted as the object of the given subject and predicate.
1010      * @throws DatabaseException  Usually should not happen. A {@code null} value is returned for possible errors.
1011      * @see #getPossibleRelatedValue2(Resource, Resource)
1012      * @see #getPossibleRelatedValue2(Resource, Resource, Object)
1013      * @see #getPossibleRelatedValue2(Resource, Resource, Object, Binding)
1014      * @see #getRelatedValue2(Resource, Resource, Binding)
1015      */
1016     <T> T getPossibleRelatedValue2(Resource subject, Resource relation, Binding binding) throws DatabaseException;
1017
1018     /**
1019      * Get the single value associated with a graph resource related with a given subject, a possible context object and
1020      * a desired value binding. An exception is thrown, if a unique object resource or a value for it is not found.
1021      * <p>
1022      * See {@link #getValue2(Resource, Object, Binding)} for more details.
1023      *
1024      * @param subject  A graph resource that indicates the subject node
1025      * @param relation  A graph resource that indicates the predicate of a relation
1026      * @param context  A context object that is used for acquiring the value, can be {@code null}
1027      * @param binding  A binding for the value type
1028      * @return  The value of the unique graph node that is asserted as the object of the given subject and predicate.
1029      * @throws NoSingleResultException  The number of suitable object resources is not equal to 1 (zero or greater than one)
1030      * @throws DoesNotContainValueException  No value is associated with the graph node.
1031      * @throws DatabaseException  Other errors, such as an error in casting the value to the return type or
1032      *         a runtime error in the value function.
1033      * @see #getRelatedValue2(Resource, Resource)
1034      * @see #getRelatedValue2(Resource, Resource, Binding)
1035      * @see #getRelatedValue2(Resource, Resource, Object)
1036      * @see #getPossibleRelatedValue2(Resource, Resource, Object, Binding)
1037      */
1038     <T> T getRelatedValue2(Resource subject, Resource relation, Object context, Binding binding) throws DatabaseException;
1039
1040     /**
1041      * Get a possible single value associated with a graph resource related with a given subject, a possible context object and
1042      * a desired value binding. A {@code null} value is returned for missing values or other errors.
1043      * <p>
1044      * See {@link #getValue2(Resource, Object, Binding)} for more details.
1045      *
1046      * @param subject  A graph resource that indicates the subject node
1047      * @param relation  A graph resource that indicates the predicate of a relation
1048      * @param context  A context object that is used for acquiring the value, can be {@code null}
1049      * @param binding  A binding for the value type
1050      * @return  The value of the unique graph node that is asserted as the object of the given subject and predicate.
1051      * @throws DatabaseException  Usually should not happen. A {@code null} value is returned for possible errors.
1052      * @see #getPossibleRelatedValue2(Resource, Resource)
1053      * @see #getPossibleRelatedValue2(Resource, Resource, Binding)
1054      * @see #getPossibleRelatedValue2(Resource, Resource, Object)
1055      * @see #getRelatedValue2(Resource, Resource, Object, Binding)
1056      */
1057     <T> T getPossibleRelatedValue2(Resource subject, Resource relation, Object context, Binding binding) throws DatabaseException;
1058
1059     /**
1060      * Get the parsed SCL type declaration from the string value of a graph resource that is the unique object of a
1061      * given subject and predicate.
1062      * <p>
1063      * See {@link #getValue2(Resource, Object, Binding)} for more details.
1064      *
1065      * @param subject  A resource that indicates the subject of a statement
1066      * @param relation  A resource that indicates the predicate of the statement
1067      * @return  A compiled SCL type definition of the string value of a unique object resource
1068      * @throws DatabaseException  For any errors in locating a unique value or compiling it as an SCL type statement
1069      */
1070     Type getRelatedValueType(Resource subject, Resource relation) throws DatabaseException;
1071
1072     boolean setSynchronous(boolean value);
1073     boolean getSynchronous();
1074 }