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

        @Deprecated
public QueryBuilder withNewObjectChanges​(boolean newObjectChanges)
        Deprecated.
        Since Javers 6.0 this method is deprecated and has no effect.

        Since Javers 6.0, the newObjectChanges flag is renamed to initialChanges and can be set only on a Javers instance level, see JaversBuilder.withInitialChanges(boolean).

      • withNewObjectChanges

        @Deprecated
public QueryBuilder withNewObjectChanges()
        Deprecated.
        Since Javers 6.0 this method is deprecated and has no effect.

        Since Javers 6.0, the newObjectChanges flag is renamed to initialChanges and can be set only on a Javers instance level, see JaversBuilder.withInitialChanges(boolean).

      • 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 or Shadows to be fetched from a JaversRepository. By default, the limit is set to 100.

        There are four types of JQL query output: List of Changes, List of Snapshots, Stream of Shadows, and List of Shadows. The limit() filter affects all of them, but in a different way:

        • Javers.findSnapshots(JqlQuery) — limit() works intuitively, it's the maximum size of a returned list.
        • Javers.findChanges(JqlQuery) — limit() is applied to the Snapshots query, which underlies the Changes query. The size of the returned list can be greater than limit(), because, typically a difference between any two Snapshots consists of many atomic Changes.
        • Javers.findShadows(JqlQuery) — limit() is applied to Shadows, it limits the size of the returned list. The underlying Snapshots query uses its own limit — snapshotQueryLimit(Integer). Since one Shadow might be reconstructed from many Snapshots, when snapshotQueryLimit() is hit, Javers repeats a given Shadow query to load a next frame of Shadows until required limit is reached.
        • Javers.findShadowsAndStream(JqlQuery) — limit() works like in findShadows(), it limits the size of the returned stream. The main difference is that the stream is lazy loaded and subsequent frame queries are executed gradually, during the stream consumption.
        See QueryBuilderLimitExamples.groovy .

      • skip

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

        See limit(int)

      • 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.

        If this method is called multiple times, all given conditions must match.

      • withCommitPropertyIn

        public QueryBuilder withCommitPropertyIn​(java.lang.String name,
                                         java.util.Collection<java.lang.String> values)
        Only snapshots with a given commit property having any of given values.
        Equivalent to SQL clause: WHERE property_value IN ('value1', ...)

        If this method is called multiple times, all given conditions must match.

      • withCommitPropertyLike

        public QueryBuilder withCommitPropertyLike​(java.lang.String name,
                                           java.lang.String valueFragment)
        Only snapshots with a given commit property partially containing a given value, ignoring case.
        Equivalent to SQL clause: WHERE lower(property_value) LIKE lower('%valueFragment%')

        If this method is called multiple times -- all given conditions must match.

      • 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

      • byAuthorLikeIgnoreCase

        public QueryBuilder byAuthorLikeIgnoreCase​(java.lang.String authorFragment)
        Only snapshots committed by a partially matching author name, ignoring case.

        Equivalent to SQL clause: WHERE lower(author) LIKE lower('%authorFragment%')