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

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