Class Query<T>
- java.lang.Object
-
- io.objectbox.query.Query<T>
-
- Type Parameters:
T
- Entity class for which results are returned.
- All Implemented Interfaces:
java.io.Closeable
,java.lang.AutoCloseable
public class Query<T> extends java.lang.Object implements java.io.Closeable
A repeatable Query returning the latest matching Objects.Use
find()
or related methods to fetch the latest results from the BoxStore.Use
property(Property)
to only return values or an aggregate of a single Property.Make sure to
close()
this query once done with it to reclaim resources immediately.See the Queries documentation for details.
-
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description void
close()
Closes this query and frees used resources.Query<T>
copy()
Creates a copy of this for use in another thread.long
count()
Returns the count of Objects matching the query.java.lang.String
describe()
For logging and testing, returns a string describing this query like "Query for entity Example with 4 conditions with properties prop1, prop2".java.lang.String
describeParameters()
For logging and testing, returns a string describing the conditions of this query like "(prop1 == A AND prop2 is null)".protected void
finalize()
Explicitly callclose()
instead to avoid expensive finalization.java.util.List<T>
find()
Find all Objects matching the query.java.util.List<T>
find(long offset, long limit)
Find all Objects matching the query, skipping the first offset results and returning at most limit results.T
findFirst()
Find the first Object matching the query.long
findFirstId()
Returns the ID of the first matching object.long[]
findIds()
Very efficient way to get just the IDs without creating any objects.long[]
findIds(long offset, long limit)
LikefindIds()
but with a offset/limit param, e.g.LazyList<T>
findLazy()
LazyList<T>
findLazyCached()
T
findUnique()
If there is a single matching object, returns it.long
findUniqueId()
If there is a single matching object, returns its ID.void
forEach(QueryConsumer<T> consumer)
Emits query results one by one to the given consumer (synchronously).PropertyQuery
property(Property<T> property)
Creates aPropertyQuery
for the given property.void
publish()
Publishes the current data to all subscribed @DataObserver
s.long
remove()
Removes (deletes) all Objects matching the queryQuery<T>
setParameter(Property<?> property, boolean value)
Sets a parameter previously given to theQueryBuilder
to a new value.Query<T>
setParameter(Property<?> property, byte[] value)
Sets a parameter previously given to theQueryBuilder
to new values.Query<T>
setParameter(Property<?> property, double value)
Sets a parameter previously given to theQueryBuilder
to a new value.Query<T>
setParameter(Property<?> property, long value)
Sets a parameter previously given to theQueryBuilder
to a new value.Query<T>
setParameter(Property<?> property, java.lang.String value)
Sets a parameter previously given to theQueryBuilder
to a new value.Query<T>
setParameter(Property<?> property, java.util.Date value)
Sets a parameter previously given to theQueryBuilder
to a new value.Query<T>
setParameter(java.lang.String alias, boolean value)
Sets a parameter previously given to theQueryBuilder
to a new value.Query<T>
setParameter(java.lang.String alias, byte[] value)
Sets a parameter previously given to theQueryBuilder
to new values.Query<T>
setParameter(java.lang.String alias, double value)
Sets a parameter previously given to theQueryBuilder
to a new value.Query<T>
setParameter(java.lang.String alias, long value)
Sets a parameter previously given to theQueryBuilder
to a new value.Query<T>
setParameter(java.lang.String alias, java.lang.String value)
Sets a parameter previously given to theQueryBuilder
to a new value.Query<T>
setParameter(java.lang.String alias, java.util.Date value)
Sets a parameter previously given to theQueryBuilder
to a new value.Query<T>
setParameters(Property<?> property, double value1, double value2)
Sets a parameter previously given to theQueryBuilder
to new values.Query<T>
setParameters(Property<?> property, int[] values)
Sets a parameter previously given to theQueryBuilder
to new values.Query<T>
setParameters(Property<?> property, long[] values)
Sets a parameter previously given to theQueryBuilder
to new values.Query<T>
setParameters(Property<?> property, long value1, long value2)
Sets a parameter previously given to theQueryBuilder
to new values.Query<T>
setParameters(Property<?> property, java.lang.String[] values)
Sets a parameter previously given to theQueryBuilder
to new values.Query<T>
setParameters(Property<?> property, java.lang.String key, java.lang.String value)
Sets a parameter previously given to theQueryBuilder
to new values.Query<T>
setParameters(java.lang.String alias, double value1, double value2)
Sets a parameter previously given to theQueryBuilder
to new values.Query<T>
setParameters(java.lang.String alias, int[] values)
Sets a parameter previously given to theQueryBuilder
to new values.Query<T>
setParameters(java.lang.String alias, long[] values)
Sets a parameter previously given to theQueryBuilder
to new values.Query<T>
setParameters(java.lang.String alias, long value1, long value2)
Sets a parameter previously given to theQueryBuilder
to new values.Query<T>
setParameters(java.lang.String alias, java.lang.String[] values)
Sets a parameter previously given to theQueryBuilder
to new values.Query<T>
setParameters(java.lang.String alias, java.lang.String key, java.lang.String value)
Sets a parameter previously given to theQueryBuilder
to new values.SubscriptionBuilder<java.util.List<T>>
subscribe()
ADataObserver
can be subscribed to data changes using the returned builder.SubscriptionBuilder<java.util.List<T>>
subscribe(DataSubscriptionList dataSubscriptionList)
Convenience forsubscribe()
with a subsequent call toSubscriptionBuilder.dataSubscriptionList(DataSubscriptionList)
.
-
-
-
Method Detail
-
finalize
protected void finalize() throws java.lang.Throwable
Explicitly callclose()
instead to avoid expensive finalization.- Overrides:
finalize
in classjava.lang.Object
- Throws:
java.lang.Throwable
-
close
public void close()
Closes this query and frees used resources.If possible, call this always once done with this. Otherwise, will be called once this is finalized (e.g. garbage collected).
Calling any other methods of this afterwards will throw an
IllegalStateException
.- Specified by:
close
in interfacejava.lang.AutoCloseable
- Specified by:
close
in interfacejava.io.Closeable
-
findFirst
@Nullable public T findFirst()
Find the first Object matching the query.
-
findUnique
@Nullable public T findUnique()
If there is a single matching object, returns it. If there is more than one matching object, throwsNonUniqueResultException
. If there are no matches returns null.
-
find
@Nonnull public java.util.List<T> find()
Find all Objects matching the query.
-
find
@Nonnull public java.util.List<T> find(long offset, long limit)
Find all Objects matching the query, skipping the first offset results and returning at most limit results. Use this for pagination.
-
findFirstId
public long findFirstId()
Returns the ID of the first matching object. If there are no results returns 0.Like
findFirst()
, but more efficient as no object is created.Ignores any
query filter
.
-
findUniqueId
public long findUniqueId()
If there is a single matching object, returns its ID. If there is more than one matching object, throwsNonUniqueResultException
. If there are no matches returns 0.Like
findUnique()
, but more efficient as no object is created.Ignores any
query filter
.
-
findIds
@Nonnull public long[] findIds()
Very efficient way to get just the IDs without creating any objects. IDs can later be used to lookup objects (lookups by ID are also very efficient in ObjectBox).Note: a filter set with
QueryBuilder.filter(QueryFilter)
will be silently ignored!
-
findIds
@Nonnull public long[] findIds(long offset, long limit)
LikefindIds()
but with a offset/limit param, e.g. for pagination.Note: a filter set with
QueryBuilder.filter(QueryFilter)
will be silently ignored!
-
property
public PropertyQuery property(Property<T> property)
Creates aPropertyQuery
for the given property.A
PropertyQuery
uses the same conditions as this Query object, but returns only the value(s) of a single property (not an entity objects).- Parameters:
property
- the property for which to return values
-
forEach
public void forEach(QueryConsumer<T> consumer)
Emits query results one by one to the given consumer (synchronously). Once this method returns, the consumer will have received all result object). It "streams" each object from the database to the consumer, which is very memory efficient. Because this is run in a read transaction, the consumer gets a consistent view on the data. LikefindLazy()
, this method can be used for a high amount of data.Note: because the consumer is called within a read transaction it may not write to the database.
-
count
public long count()
Returns the count of Objects matching the query.
-
setParameter
public Query<T> setParameter(Property<?> property, java.lang.String value)
Sets a parameter previously given to theQueryBuilder
to a new value.
-
setParameter
public Query<T> setParameter(java.lang.String alias, java.lang.String value)
Sets a parameter previously given to theQueryBuilder
to a new value.- Parameters:
alias
- as defined usingQueryBuilder.parameterAlias(String)
.
-
setParameter
public Query<T> setParameter(Property<?> property, long value)
Sets a parameter previously given to theQueryBuilder
to a new value.
-
setParameter
public Query<T> setParameter(java.lang.String alias, long value)
Sets a parameter previously given to theQueryBuilder
to a new value.- Parameters:
alias
- as defined usingQueryBuilder.parameterAlias(String)
.
-
setParameter
public Query<T> setParameter(Property<?> property, double value)
Sets a parameter previously given to theQueryBuilder
to a new value.
-
setParameter
public Query<T> setParameter(java.lang.String alias, double value)
Sets a parameter previously given to theQueryBuilder
to a new value.- Parameters:
alias
- as defined usingQueryBuilder.parameterAlias(String)
.
-
setParameter
public Query<T> setParameter(Property<?> property, java.util.Date value)
Sets a parameter previously given to theQueryBuilder
to a new value.- Throws:
java.lang.NullPointerException
- if given date is null
-
setParameter
public Query<T> setParameter(java.lang.String alias, java.util.Date value)
Sets a parameter previously given to theQueryBuilder
to a new value.- Parameters:
alias
- as defined usingQueryBuilder.parameterAlias(String)
.- Throws:
java.lang.NullPointerException
- if given date is null
-
setParameter
public Query<T> setParameter(Property<?> property, boolean value)
Sets a parameter previously given to theQueryBuilder
to a new value.
-
setParameter
public Query<T> setParameter(java.lang.String alias, boolean value)
Sets a parameter previously given to theQueryBuilder
to a new value.- Parameters:
alias
- as defined usingQueryBuilder.parameterAlias(String)
.
-
setParameters
public Query<T> setParameters(Property<?> property, long value1, long value2)
Sets a parameter previously given to theQueryBuilder
to new values.
-
setParameters
public Query<T> setParameters(java.lang.String alias, long value1, long value2)
Sets a parameter previously given to theQueryBuilder
to new values.- Parameters:
alias
- as defined usingQueryBuilder.parameterAlias(String)
.
-
setParameters
public Query<T> setParameters(Property<?> property, int[] values)
Sets a parameter previously given to theQueryBuilder
to new values.
-
setParameters
public Query<T> setParameters(java.lang.String alias, int[] values)
Sets a parameter previously given to theQueryBuilder
to new values.- Parameters:
alias
- as defined usingQueryBuilder.parameterAlias(String)
.
-
setParameters
public Query<T> setParameters(Property<?> property, long[] values)
Sets a parameter previously given to theQueryBuilder
to new values.
-
setParameters
public Query<T> setParameters(java.lang.String alias, long[] values)
Sets a parameter previously given to theQueryBuilder
to new values.- Parameters:
alias
- as defined usingQueryBuilder.parameterAlias(String)
.
-
setParameters
public Query<T> setParameters(Property<?> property, double value1, double value2)
Sets a parameter previously given to theQueryBuilder
to new values.
-
setParameters
public Query<T> setParameters(java.lang.String alias, double value1, double value2)
Sets a parameter previously given to theQueryBuilder
to new values.- Parameters:
alias
- as defined usingQueryBuilder.parameterAlias(String)
.
-
setParameters
public Query<T> setParameters(Property<?> property, java.lang.String[] values)
Sets a parameter previously given to theQueryBuilder
to new values.
-
setParameters
public Query<T> setParameters(java.lang.String alias, java.lang.String[] values)
Sets a parameter previously given to theQueryBuilder
to new values.- Parameters:
alias
- as defined usingQueryBuilder.parameterAlias(String)
.
-
setParameters
public Query<T> setParameters(Property<?> property, java.lang.String key, java.lang.String value)
Sets a parameter previously given to theQueryBuilder
to new values.
-
setParameters
public Query<T> setParameters(java.lang.String alias, java.lang.String key, java.lang.String value)
Sets a parameter previously given to theQueryBuilder
to new values.- Parameters:
alias
- as defined usingQueryBuilder.parameterAlias(String)
.
-
setParameter
public Query<T> setParameter(Property<?> property, byte[] value)
Sets a parameter previously given to theQueryBuilder
to new values.
-
setParameter
public Query<T> setParameter(java.lang.String alias, byte[] value)
Sets a parameter previously given to theQueryBuilder
to new values.- Parameters:
alias
- as defined usingQueryBuilder.parameterAlias(String)
.
-
remove
public long remove()
Removes (deletes) all Objects matching the query- Returns:
- count of removed Objects
-
subscribe
public SubscriptionBuilder<java.util.List<T>> subscribe()
ADataObserver
can be subscribed to data changes using the returned builder. The observer is supplied viaSubscriptionBuilder.observer(DataObserver)
and will be notified once the query results have (potentially) changed.With subscribing, the observer will immediately get current query results. The query is run for the subscribing observer.
Threading notes: Query observers are notified from a thread pooled. Observers may be notified in parallel. The notification order is the same as the subscription order, although this may not always be guaranteed in the future.
Stale observers: you must hold on to the Query or
DataSubscription
objects to keep yourDataObserver
s active. If this Query is not referenced anymore (along with itsDataSubscription
s, which hold a reference to the Query internally), it may be GCed and observers may become stale (won't receive anymore data).
-
subscribe
public SubscriptionBuilder<java.util.List<T>> subscribe(DataSubscriptionList dataSubscriptionList)
Convenience forsubscribe()
with a subsequent call toSubscriptionBuilder.dataSubscriptionList(DataSubscriptionList)
.- Parameters:
dataSubscriptionList
- the resultingDataSubscription
will be added to it
-
publish
public void publish()
Publishes the current data to all subscribed @DataObserver
s. This is useful triggering observers when new parameters have been set. Note, that setParameter methods will NOT be propagated to observers.
-
describe
public java.lang.String describe()
For logging and testing, returns a string describing this query like "Query for entity Example with 4 conditions with properties prop1, prop2".Note: the format of the returned string may change without notice.
-
describeParameters
public java.lang.String describeParameters()
For logging and testing, returns a string describing the conditions of this query like "(prop1 == A AND prop2 is null)".Note: the format of the returned string may change without notice.
-
-