Class Query<T>

  • Type Parameters:
    T - The entity class the query will return results for.
    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 entities.
    See Also:
    QueryBuilder
    • Method Detail

      • finalize

        protected void finalize()
                         throws java.lang.Throwable
        Explicitly call close() instead to avoid expensive finalization.
        Overrides:
        finalize in class java.lang.Object
        Throws:
        java.lang.Throwable
      • close

        public void close()
        If possible, try to close the query once you are done with it to reclaim resources immediately.
        Specified by:
        close in interface java.lang.AutoCloseable
        Specified by:
        close in interface java.io.Closeable
      • findFirst

        @Nullable
        public T findFirst()
        Find the first Object matching the query.
      • findUnique

        @Nullable
        public T findUnique()
        Find the unique Object matching the query.
        Throws:
        NonUniqueResultException - if result was not unique
      • 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 between the given offset and limit. This helps with pagination.
      • 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)
        Like findIds() but with a offset/limit param, e.g. for pagination.

        Note: a filter set with QueryBuilder.filter(QueryFilter) will be silently ignored!

      • findLazy

        public LazyList<T> findLazy()
        Find all Objects matching the query without actually loading the Objects. See @LazyList for details.
      • property

        public PropertyQuery property​(Property property)
        Creates a PropertyQuery 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. Like findLazy(), 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.

      • findLazyCached

        @Nonnull
        public LazyList<T> findLazyCached()
        Find all Objects matching the query without actually loading the Objects. See @LazyList for details.
      • 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 the QueryBuilder to a new value.
      • setParameter

        public Query<T> setParameter​(Property property,
                                     long value)
        Sets a parameter previously given to the QueryBuilder to a new value.
      • setParameter

        public Query<T> setParameter​(Property property,
                                     double value)
        Sets a parameter previously given to the QueryBuilder to a new value.
      • setParameter

        public Query<T> setParameter​(Property property,
                                     java.util.Date value)
        Sets a parameter previously given to the QueryBuilder 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 the QueryBuilder to a new value.
        Parameters:
        alias - as defined using QueryBuilder.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 the QueryBuilder to a new value.
      • setParameters

        public Query<T> setParameters​(Property property,
                                      long value1,
                                      long value2)
        Sets a parameter previously given to the QueryBuilder to new values.
      • setParameters

        public Query<T> setParameters​(Property property,
                                      int[] values)
        Sets a parameter previously given to the QueryBuilder to new values.
      • setParameters

        public Query<T> setParameters​(Property property,
                                      long[] values)
        Sets a parameter previously given to the QueryBuilder to new values.
      • setParameters

        public Query<T> setParameters​(Property property,
                                      double value1,
                                      double value2)
        Sets a parameter previously given to the QueryBuilder to new values.
      • setParameters

        public Query<T> setParameters​(Property property,
                                      java.lang.String[] values)
        Sets a parameter previously given to the QueryBuilder to new values.
      • setParameter

        public Query<T> setParameter​(Property property,
                                     byte[] value)
        Sets a parameter previously given to the QueryBuilder to new values.
      • remove

        public long remove()
        Removes (deletes) all Objects matching the query
        Returns:
        count of removed Objects
      • subscribe

        public SubscriptionBuilder<java.util.List<T>> subscribe()
        A DataObserver can be subscribed to data changes using the returned builder. The observer is supplied via SubscriptionBuilder.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 your DataObservers active. If this Query is not referenced anymore (along with its DataSubscriptions, which hold a reference to the Query internally), it may be GCed and observers may become stale (won't receive anymore data).

      • publish

        public void publish()
        Publishes the current data to all subscribed @DataObservers. 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.