Package org.javers.repository.jql

Class QueryBuilder

    • Method Detail

      • anyDomainObject

        public static QueryBuilder anyDomainObject()
        Query for selecting changes (or snapshots) made on any object.

        For example, last changes committed on any object can be fetched with: 
         javers.findChanges( QueryBuilder.anyDomainObject().build() );
        Since:
        2.0

      • byClass

        public static QueryBuilder byClass​(java.lang.Class... requiredClasses)
        Query for selecting changes (or snapshots) made on any object (Entity or ValueObject) of given classes.

        For example, last changes on any object of MyClass.class: 
         javers.findChanges( QueryBuilder.byClass(MyClass.class).build() );

      • byInstanceId

        public static QueryBuilder byInstanceId​(java.lang.Object localId,
                                        java.lang.Class entityClass)
        Query for selecting Changes, Snapshots or Shadows for a given Entity instance.

        For example, last Changes on "bob" Person: 
         javers.findChanges( QueryBuilder.byInstanceId("bob", Person.class).build() );
        Parameters:
        localId - Value of an Id-property. When an Entity has Composite-Id (more than one Id-property) — localId should be Map<String, Object> with Id-property name to value pairs.
        See Also:
        CompositeIdExample.groovy

      • byInstanceId

        public static QueryBuilder byInstanceId​(java.lang.Object localId,
                                        java.lang.String typeName)
        Query for selecting Changes, Snapshots or Shadows for a given Entity instance, identified by its type name.

        For example, last Changes on "bob" Person: 
         javers.findChanges( QueryBuilder.byInstanceId("bob", "Person").build() );
        Parameters:
        localId - Value of an Id-property. When an Entity has Composite-Id (more than one Id-property) — localId should be Map<String, Object> with Id-property name to value pairs.
        See Also:
        CompositeIdExample.groovy

      • byInstance

        public static QueryBuilder byInstance​(java.lang.Object instance)
        Query for selecting changes (or snapshots) made on a concrete Entity instance.

        For example, last changes on "bob" Person: 
         javers.findChanges( QueryBuilder.byInstanceId(new Person("bob")).build() );

      • byValueObject

        public static QueryBuilder byValueObject​(java.lang.Class ownerEntityClass,
                                         java.lang.String path)
        Query for selecting changes (or snapshots) made on all ValueObjects at given path, owned by any instance of given Entity.

        See path parameter hints in byValueObjectId(Object, Class, String).

      • byValueObjectId

        public static QueryBuilder byValueObjectId​(java.lang.Object ownerLocalId,
                                           java.lang.Class ownerEntityClass,
                                           java.lang.String path)
        Query for selecting changes (or snapshots) made on a concrete ValueObject (so a ValueObject owned by a concrete Entity instance).

        Path parameter is a relative path from owning Entity instance to ValueObject that you are looking for.

        When ValueObject is just a property, use propertyName. For example: 
         class Employee {
     @Id String name;
     Address primaryAddress;
 }
 ...
 javers.findChanges( QueryBuilder.byValueObjectId("bob", Employee.class, "primaryAddress").build() );
        When ValueObject is stored in a List, use propertyName and list index separated by "/", for example: 
         class Employee {
     @Id String name;
     List<Address> addresses;
 }
 ...
 javers.findChanges( QueryBuilder.byValueObjectId("bob", Employee.class, "addresses/0").build() );
        When ValueObject is stored as a Map value, use propertyName and map key separated by "/", for example: 
         class Employee {
     @Id String name;
     Map<String,Address> addressMap;
 }
 ...
 javers.findChanges( QueryBuilder.byValueObjectId("bob", Employee.class, "addressMap/HOME").build() );

      • withChangedProperty

        public QueryBuilder withChangedProperty​(java.lang.String propertyName)
        Only snapshots with changes on a given property.
        See Also:
        CdoSnapshot.getChanged()

      • withChangedPropertyIn

        public QueryBuilder withChangedPropertyIn​(java.lang.String... propertyNames)
        Only snapshots with changes on one or more properties from a given list.
        See Also:
        CdoSnapshot.getChanged()

      • withNewObjectChanges

        public QueryBuilder withNewObjectChanges()
        Affects changes query only. When switched on, additional changes are generated for the initial snapshot (the first commit of a given object). Off by default.
        It means one NewObject change for each initial snapshot and the full set of initial PropertyChanges with null on the left side and initial property value on the right.

      • withSnapshotType

        public QueryBuilder withSnapshotType​(SnapshotType snapshotType)
        Selects only snapshots with a given type: initial, update or terminal.

        Typical use case: 
         javers.findSnapshots(QueryBuilder.byClass(SnapshotEntity)
       .withChangedProperty("someProperty")
       .withSnapshotTypeUpdate().build())

      • withSnapshotTypeUpdate

        public QueryBuilder withSnapshotTypeUpdate()
        Selects only updating snapshots (without initial ones).

      • limit

        public QueryBuilder limit​(int limit)
        Limits the number of Snapshots to be fetched from JaversRepository in a single query. By default, the limit is set to 100, which works well with small data structures.

        There are four types of query output: List of Changes, List of Snapshots, List of Shadows, and Stream of Shadows. Since all of Javers queries rely on Snapshots in order to generate their output, the limit filter affects all of them, but in a different way:
        • Javers.findSnapshots(JqlQuery) — the limit works intuitively, it's the maximum size of a returned list.
        • Javers.findChanges(JqlQuery) — the size of a returned list can be greater than the limit, because, typically a difference between any two Snapshots consists of many atomic Changes.
        • Javers.findShadows(JqlQuery) — the size of a returned list can be less than the limit and Shadow graphs can be incomplete, because, typically, one Shadow is reconstructed from many Snapshots. Hitting the limit in findShadows() is very likely and it's a bad thing.
        • Javers.findShadowsAndStream(JqlQuery) — the resulting stream is lazily loaded and it's limited only by the size of your JaversRepository and your heap. When the limit is hit, Javers repeats a given query to load a next bunch of Snapshots. Shadow graphs loaded by findShadowsAndStream() are always complete, but can trigger a lot of queries.
        We recommend Javers.findShadowsAndStream(JqlQuery) as a primary method of loading Shadows.

        See QueryBuilderLimitExamples.groovy .
        See Also:
        Change, CdoSnapshot, Shadow, JaversRepository

      • skip

        public QueryBuilder skip​(int skip)
        Sets the number of Snapshots to skip. Use skip() and limit() for paging Snapshots and Changes.

        For paging Shadows use Javers.findShadowsAndStream(JqlQuery) with Stream.skip(long) and Stream.limit(long).

      • withCommitId

        public QueryBuilder withCommitId​(CommitId commitId)
        Only snapshots created in a given commit.

      • withCommitIds

        public QueryBuilder withCommitIds​(java.util.Collection<java.math.BigDecimal> commitIds)
        Only snapshots created in given commits.

      • toCommitId

        public QueryBuilder toCommitId​(CommitId commitId)
        Only snapshots created before this commit or exactly in this commit.

      • withCommitProperty

        public QueryBuilder withCommitProperty​(java.lang.String name,
                                       java.lang.String value)
        Only snapshots with a given commit property.

        all given properties must match with persisted commit properties.
        Since:
        2.0

      • withVersion

        public QueryBuilder withVersion​(long version)
        Only snapshots with a given version.

      • withScopeDeepPlus

        public QueryBuilder withScopeDeepPlus​(int maxGapsToFill)
        Selects ShadowScope.DEEP_PLUS with given maxGapsToFill.

        Read more about Shadow query scopes, profiling, and runtime statistics in Javers.findShadows(JqlQuery) javadoc.

        Only for Shadow queries.
        Parameters:
        maxGapsToFill - Limits the number of referenced entity Shadows to be eagerly loaded. The limit is global for a query. When it is exceeded, references to other entities are nulled. Collections of entities may not be fully loaded.
        Since:
        3.5
        See Also:
        http://javers.org/documentation/jql-examples

      • byAuthor

        public QueryBuilder byAuthor​(java.lang.String author)
        Only snapshots committed by a given author.
        Since:
        2.0