Package org.javers.repository.jql
Class QueryBuilder
- java.lang.Object
-
- org.javers.repository.jql.QueryBuilder
-
public class QueryBuilder extends java.lang.Object
Fluent API for buildingJqlQuery
, executed withJavers.findChanges(JqlQuery)
andJavers.findSnapshots(JqlQuery)
-
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description QueryBuilder
andProperty(java.lang.String propertyName)
Deprecated.static QueryBuilder
anyDomainObject()
Query for selecting changes (or snapshots) made on any object.JqlQuery
build()
QueryBuilder
byAuthor(java.lang.String author)
Only snapshots committed by a given author.static QueryBuilder
byClass(java.lang.Class... requiredClasses)
Query for selecting changes (or snapshots) made on any object (Entity or ValueObject) of given classes.static QueryBuilder
byGlobalId(GlobalIdDTO globalId)
Deprecated.static QueryBuilder
byInstance(java.lang.Object instance)
Query for selecting changes (or snapshots) made on a concrete Entity instance.static QueryBuilder
byInstanceId(java.lang.Object localId, java.lang.Class entityClass)
Query for selecting Changes, Snapshots or Shadows for a given Entity instance.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.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.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).QueryBuilder
from(java.time.LocalDate fromDate)
delegates tofrom(LocalDateTime)
with MIDNIGHTQueryBuilder
from(java.time.LocalDateTime from)
Limits to snapshots created after this date or exactly at this date.QueryBuilder
fromInstant(java.time.Instant fromInstant)
Limits to snapshots created after this UTC date or exactly at this UTC date.QueryBuilder
limit(int limit)
Limits the number of Snapshots or Shadows to be fetched from a JaversRepository.QueryBuilder
skip(int skip)
Sets the number of Snapshots or Shadows to skip.
Use skip() and limit() for paging.QueryBuilder
snapshotQueryLimit(java.lang.Integer snapshotQueryLimit)
Should be changed only to improve performance of Shadow queries. Please do not confused it withlimit(int)
.QueryBuilder
to(java.time.LocalDate toDate)
delegates toto(LocalDateTime)
with MIDNIGHTQueryBuilder
to(java.time.LocalDateTime to)
Limits to snapshots created before this date or exactly at this date.QueryBuilder
toCommitId(CommitId commitId)
Only snapshots created before this commit or exactly in this commit.QueryBuilder
toInstant(java.time.Instant toInstant)
Limits to snapshots created before this UTC date or exactly at this UTC date.QueryBuilder
withChangedProperty(java.lang.String propertyName)
Only snapshots with changes on a given property.QueryBuilder
withChangedPropertyIn(java.lang.String... propertyNames)
Only snapshots with changes on one or more properties from a given list.QueryBuilder
withChildValueObjects()
Only for Snapshot and Changes queries.QueryBuilder
withChildValueObjects(boolean aggregate)
Only for Snapshot and Changes queries, seewithChildValueObjects()
QueryBuilder
withCommitId(java.math.BigDecimal commitId)
Delegates towithCommitId(CommitId)
QueryBuilder
withCommitId(CommitId commitId)
Only snapshots created in a given commit.QueryBuilder
withCommitIds(java.util.Collection<java.math.BigDecimal> commitIds)
Only snapshots created in given commits.QueryBuilder
withCommitProperty(java.lang.String name, java.lang.String value)
Only snapshots with a given commit property.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.QueryBuilder
withCommitPropertyLike(java.lang.String name, java.lang.String value)
Only snapshots with a given commit property partially containing a given value.
Equivalent to SQL clause: WHERE property_value LIKE '%value%'
The matching is case insensitive on MongoDB and on most SQL databases.QueryBuilder
withNewObjectChanges()
Deprecated.QueryBuilder
withNewObjectChanges(boolean newObjectChanges)
Deprecated.QueryBuilder
withScopeCommitDeep()
SelectsShadowScope.COMMIT_DEEP
for Shadow queries.QueryBuilder
withScopeCommitDeepPlus()
Deprecated.renamed towithScopeDeepPlus()
()}QueryBuilder
withScopeCommitDeepPlus(int maxGapsToFill)
Deprecated.renamed towithScopeDeepPlus(int)
()}QueryBuilder
withScopeDeepPlus()
SelectsShadowScope.DEEP_PLUS
withmaxGapsToFill
defaulted to 10.QueryBuilder
withScopeDeepPlus(int maxGapsToFill)
SelectsShadowScope.DEEP_PLUS
with givenmaxGapsToFill
.QueryBuilder
withShadowScope(ShadowScope shadowScope)
Choose between shallow, child-value-object, commit-deep or deep+ query scopes.QueryBuilder
withShadowScopeDeep()
Deprecated.QueryBuilder
withSnapshotType(SnapshotType snapshotType)
Selects only snapshots with a given type: initial, update or terminal.QueryBuilder
withSnapshotTypeUpdate()
Selects only updating snapshots (without initial ones).QueryBuilder
withVersion(long version)
Only snapshots with a given version.
-
-
-
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 beMap<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 beMap<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 inbyValueObjectId(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() );
-
byGlobalId
@Deprecated public static QueryBuilder byGlobalId(GlobalIdDTO globalId)
Deprecated.
-
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, thenewObjectChanges
flag is renamed toinitialChanges
and can be set only on a Javers instance level, seeJaversBuilder.withInitialChanges(boolean)
.
-
withNewObjectChanges
@Deprecated public QueryBuilder withNewObjectChanges()
Deprecated.Since Javers 6.0 this method is deprecated and has no effect.
Since Javers 6.0, thenewObjectChanges
flag is renamed toinitialChanges
and can be set only on a Javers instance level, seeJaversBuilder.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, seewithChildValueObjects()
- 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 (seeShadowScope.CHILD_VALUE_OBJECT
).- Since:
- 2.1
- See Also:
- http://javers.org/documentation/jql-examples
-
snapshotQueryLimit
public QueryBuilder snapshotQueryLimit(java.lang.Integer snapshotQueryLimit)
Should be changed only to improve performance of Shadow queries. Please do not confused it withlimit(int)
.
Works only withJavers.findShadows(JqlQuery)
andJavers.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 withJavers.findSnapshots(JqlQuery)
orJavers.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 thanlimit()
, 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, whensnapshotQueryLimit()
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 infindShadows()
, 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.
-
skip
public QueryBuilder skip(int skip)
-
from
public QueryBuilder from(java.time.LocalDateTime from)
Limits to snapshots created after this date or exactly at this date.- See Also:
CommitMetadata.getCommitDate()
,}
,to(LocalDateTime)
-
fromInstant
public QueryBuilder fromInstant(java.time.Instant fromInstant)
Limits to snapshots created after this UTC date or exactly at this UTC date.
-
to
public QueryBuilder to(java.time.LocalDateTime to)
Limits to snapshots created before this date or exactly at this date.- See Also:
CommitMetadata.getCommitDate()
,}
,from(LocalDateTime)
-
toInstant
public QueryBuilder toInstant(java.time.Instant toInstant)
Limits to snapshots created before this UTC date or exactly at this UTC date.
-
withCommitId
public QueryBuilder withCommitId(CommitId commitId)
Only snapshots created in a given commit.
-
withCommitId
public QueryBuilder withCommitId(java.math.BigDecimal commitId)
Delegates towithCommitId(CommitId)
-
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.
-
from
public QueryBuilder from(java.time.LocalDate fromDate)
delegates tofrom(LocalDateTime)
with MIDNIGHT
-
to
public QueryBuilder to(java.time.LocalDate toDate)
delegates toto(LocalDateTime)
with MIDNIGHT
-
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 value)
Only snapshots with a given commit property partially containing a given value.
Equivalent to SQL clause: WHERE property_value LIKE '%value%'
The matching is case insensitive on MongoDB and on most SQL databases.
If this method is called multiple times, all given conditions must match.
-
withVersion
public QueryBuilder withVersion(long version)
Only snapshots with a given version.
-
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 isShadowScope.SHALLOW
.
Read more about query scopes inJavers.findShadows(JqlQuery)
javadoc.
Only for Shadow queries.- Since:
- 3.2
- See Also:
- http://javers.org/documentation/jql-examples
-
withScopeCommitDeep
public QueryBuilder withScopeCommitDeep()
SelectsShadowScope.COMMIT_DEEP
for Shadow queries.
Read about query scopes inJavers.findShadows(JqlQuery)
javadoc.- Since:
- 3.5
- See Also:
- http://javers.org/documentation/jql-examples
-
withScopeDeepPlus
public QueryBuilder withScopeDeepPlus()
SelectsShadowScope.DEEP_PLUS
withmaxGapsToFill
defaulted to 10.
Read more about query scopes inJavers.findShadows(JqlQuery)
javadoc.
Only for Shadow queries.- Since:
- 3.5
- See Also:
- http://javers.org/documentation/jql-examples
-
withScopeDeepPlus
public QueryBuilder withScopeDeepPlus(int maxGapsToFill)
SelectsShadowScope.DEEP_PLUS
with givenmaxGapsToFill
.
Read more about Shadow query scopes, profiling, and runtime statistics inJavers.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
-
withScopeCommitDeepPlus
@Deprecated public QueryBuilder withScopeCommitDeepPlus()
Deprecated.renamed towithScopeDeepPlus()
()}
-
withScopeCommitDeepPlus
@Deprecated public QueryBuilder withScopeCommitDeepPlus(int maxGapsToFill)
Deprecated.renamed towithScopeDeepPlus(int)
()}
-
byAuthor
public QueryBuilder byAuthor(java.lang.String author)
Only snapshots committed by a given author.- Since:
- 2.0
-
build
public JqlQuery build()
-
withShadowScopeDeep
@Deprecated public QueryBuilder withShadowScopeDeep()
Deprecated.renamed towithScopeCommitDeep()
-
andProperty
@Deprecated public QueryBuilder andProperty(java.lang.String propertyName)
Deprecated.renamed towithChangedProperty(String)
-
-