Package org.javers.repository.jql

Class QueryBuilder

java.lang.Object
org.javers.repository.jql.QueryBuilder
public class QueryBuilder extends Object
Fluent API for building JqlQuery, executed with Javers.findChanges(JqlQuery) and Javers.findSnapshots(JqlQuery)
See Also:

  • Method Details

    • 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(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(Object localId, 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:

    • byInstanceId

      public static QueryBuilder byInstanceId(Object localId, 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:

    • byInstance

      public static QueryBuilder byInstance(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(Class ownerEntityClass, 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(Object ownerLocalId, Class ownerEntityClass, 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() );

    • byGlobalId

      @Deprecated public static QueryBuilder byGlobalId(GlobalIdDTO globalId)
      Deprecated.

    • withChangedProperty

      public QueryBuilder withChangedProperty(String propertyName)
      Only snapshots with changes on a given property.
      See Also:

    • withChangedPropertyIn

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

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

    • withChildValueObjects

      public QueryBuilder withChildValueObjects(boolean aggregate)
      Only for Snapshot and Changes queries, see withChildValueObjects()
      Since:
      2.1

    • withChildValueObjects

      public QueryBuilder withChildValueObjects()
      Only for Snapshot and Changes queries. When enabled, selects all child ValueObjects owned by selected Entities.

      This switch has no effect on Shadow queries because Shadows are always loaded together with their child ValueObjects (see ShadowScope.CHILD_VALUE_OBJECT).
      Since:
      2.1
      See Also:

    • snapshotQueryLimit

      public QueryBuilder snapshotQueryLimit(Integer snapshotQueryLimit)
      Should be changed only to improve performance of Shadow queries. Please do not confused it with limit(int).

      Works only with Javers.findShadows(JqlQuery) and Javers.findShadowsAndStream(JqlQuery).
      Limits the number of Snapshots to be fetched from a JaversRepository in a single DB query
      — 100 by default.
      Throws:
      JaversException - MALFORMED_JQL if used with Javers.findSnapshots(JqlQuery) or Javers.findChanges(JqlQuery)

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

    • from

      public QueryBuilder from(LocalDateTime from)
      Limits to snapshots created after this date or exactly at this date.
      See Also:

    • fromInstant

      public QueryBuilder fromInstant(Instant fromInstant)
      Limits to snapshots created after this UTC date or exactly at this UTC date.

      See Also:

    • to

      public QueryBuilder to(LocalDateTime to)
      Limits to snapshots created before this date or exactly at this date.
      See Also:

    • toInstant

      public QueryBuilder toInstant(Instant toInstant)
      Limits to snapshots created before this UTC date or exactly at this UTC date.
      See Also:

    • withCommitId

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

    • withCommitId

      public QueryBuilder withCommitId(BigDecimal commitId)
      Delegates to withCommitId(CommitId)

    • withCommitIds

      public QueryBuilder withCommitIds(Collection<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.

    • from

      public QueryBuilder from(LocalDate fromDate)
      delegates to from(LocalDateTime) with MIDNIGHT

    • to

      public QueryBuilder to(LocalDate toDate)
      delegates to to(LocalDateTime) with MIDNIGHT

    • withCommitProperty

      public QueryBuilder withCommitProperty(String name, 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(String name, Collection<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(String name, 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.
      See Also:

    • fromVersion

      public QueryBuilder fromVersion(long fromVersion)
      Only snapshots with a version greater than or equal to (>=) a given version.
      See Also:

    • toVersion

      public QueryBuilder toVersion(long toVersion)
      Only snapshots with a version less than or equal to (<=) a given version.
      See Also:

    • withShadowScope

      public QueryBuilder withShadowScope(ShadowScope shadowScope)
      Choose between shallow, child-value-object, commit-deep or deep+ query scopes.
      The wider the scope, the more object shadows are loaded to the resulting graph.

      Default scope is ShadowScope.SHALLOW.

      Read more about query scopes in Javers.findShadows(JqlQuery) javadoc.

      Only for Shadow queries.
      Since:
      3.2
      See Also:

    • withScopeCommitDeep

      public QueryBuilder withScopeCommitDeep()
      Selects ShadowScope.COMMIT_DEEP for Shadow queries.

      Read about query scopes in Javers.findShadows(JqlQuery) javadoc.
      Since:
      3.5
      See Also:

    • withScopeDeepPlus

      public QueryBuilder withScopeDeepPlus()
      Selects ShadowScope.DEEP_PLUS with maxGapsToFill defaulted to 10.

      Read more about query scopes in Javers.findShadows(JqlQuery) javadoc.

      Only for Shadow queries.
      Since:
      3.5
      See Also:

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

    • withScopeCommitDeepPlus

      @Deprecated public QueryBuilder withScopeCommitDeepPlus()
      Deprecated.
      renamed to withScopeDeepPlus() ()}

    • withScopeCommitDeepPlus

      @Deprecated public QueryBuilder withScopeCommitDeepPlus(int maxGapsToFill)
      Deprecated.
      renamed to withScopeDeepPlus(int) ()}

    • byAuthor

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

    • byAuthorLikeIgnoreCase

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

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

    • build

      public JqlQuery build()

    • withShadowScopeDeep

      @Deprecated public QueryBuilder withShadowScopeDeep()
      Deprecated.
      renamed to withScopeCommitDeep()

    • andProperty

      @Deprecated public QueryBuilder andProperty(String propertyName)
      Deprecated.
      renamed to withChangedProperty(String)