com.parse.ParseQuery Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of parse-android Show documentation
A library that gives you access to the powerful Parse cloud platform from your Android app.
There is a newer version: 1.17.3
/*
 * Copyright (c) 2015-present, Parse, LLC.
 * All rights reserved.
 *
 * This source code is licensed under the BSD-style license found in the
 * LICENSE file in the root directory of this source tree. An additional grant
 * of patent rights can be found in the PATENTS file in the same directory.
 */
package com.parse;

import org.json.JSONException;
import org.json.JSONObject;

import java.util.ArrayList;
import java.util.Collection;
import java.util.Collections;
import java.util.HashMap;
import java.util.HashSet;
import java.util.List;
import java.util.Locale;
import java.util.Map;
import java.util.Set;
import java.util.concurrent.Callable;
import java.util.regex.Pattern;

import bolts.Continuation;
import bolts.Task;

/**
 * The {@code ParseQuery} class defines a query that is used to fetch {@link ParseObject}s. The most
 * common use case is finding all objects that match a query through the {@link #findInBackground()}
 * method, using a {@link FindCallback}. For example, this sample code fetches all objects of class
 * {@code "MyClass"}. It calls a different function depending on whether the fetch succeeded or not.
 * 
 * 
 * ParseQuery<ParseObject> query = ParseQuery.getQuery("MyClass");
 * query.findInBackground(new FindCallback<ParseObject>() {
 *     public void done(List<ParseObject> objects, ParseException e) {
 *         if (e == null) {
 *             objectsWereRetrievedSuccessfully(objects);
 *         } else {
 *             objectRetrievalFailed();
 *         }
 *     }
 * }
 * 
 * 
 * A {@code ParseQuery} can also be used to retrieve a single object whose id is known, through the
 * {@link #getInBackground(String)} method, using a {@link GetCallback}. For example, this
 * sample code fetches an object of class {@code "MyClass"} and id {@code myId}. It calls
 * a different function depending on whether the fetch succeeded or not.
 * 

 * 
 * ParseQuery<ParseObject> query = ParseQuery.getQuery("MyClass");
 * query.getInBackground(myId, new GetCallback<ParseObject>() {
 *     public void done(ParseObject object, ParseException e) {
 *         if (e == null) {
 *             objectWasRetrievedSuccessfully(object);
 *         } else {
 *             objectRetrievalFailed();
 *         }
 *     }
 * }
 * 
 * 
 * A {@code ParseQuery} can also be used to count the number of objects that match the query without
 * retrieving all of those objects. For example, this sample code counts the number of objects of
 * the class {@code "MyClass"}.
 * 

 * 
 * ParseQuery<ParseObject> query = ParseQuery.getQuery("MyClass");
 * query.countInBackground(new CountCallback() {
 *     public void done(int count, ParseException e) {
 *         if (e == null) {
 *             objectsWereCounted(count);
 *         } else {
 *             objectCountFailed();
 *         }
 *     }
 * }
 * 
 * 
 * Using the callback methods is usually preferred because the network operation will not block the
 * calling thread. However, in some cases it may be easier to use the {@link #find()},
 * {@link #get(String)} or {@link #count()} calls, which do block the calling thread. For example,
 * if your application has already spawned a background task to perform work, that background task
 * could use the blocking calls and avoid the code complexity of callbacks.
 */
public class ParseQuery {

  private static ParseQueryController getQueryController() {
    return ParseCorePlugins.getInstance().getQueryController();
  }

  /**
   * Constraints for a {@code ParseQuery}'s where clause. A map of field names to constraints. The
   * values can either be actual values to compare with for equality, or instances of
   * {@link KeyConstraints}.
   */
  @SuppressWarnings("serial")
  /* package */ static class QueryConstraints extends HashMap {

    public QueryConstraints() {
      super();
    }

    public QueryConstraints(Map map) {
      super(map);
    }
  }

  /**
   * Constraints for a particular field in a query. If this is used, it's a may where the keys are
   * special operators, such as $greaterThan or $nin. The values are the actual values to compare
   * against.
   */
  @SuppressWarnings("serial")
  /* package */ static class KeyConstraints extends HashMap {
  }

  /**
   * Constraint for a $relatedTo query.
   */
  /* package */ static class RelationConstraint {
    private String key;
    private ParseObject object;

    public RelationConstraint(String key, ParseObject object) {
      if (key == null || object == null) {
        throw new IllegalArgumentException("Arguments must not be null.");
      }
      this.key = key;
      this.object = object;
    }

    public String getKey() {
      return key;
    }

    public ParseObject getObject() {
      return object;
    }

    public ParseRelation getRelation() {
      return object.getRelation(key);
    }

    /**
     * Encodes the constraint in a format appropriate for including in the query.
     */
    public JSONObject encode(ParseEncoder objectEncoder) {
      JSONObject json = new JSONObject();
      try {
        json.put("key", key);
        json.put("object", objectEncoder.encodeRelatedObject(object));
      } catch (JSONException e) {
        // This can never happen.
        throw new RuntimeException(e);
      }
      return json;
    }
  }

  /**
   * Constructs a query that is the {@code or} of the given queries.
   *
   * @param queries
   *          The list of {@code ParseQuery}s to 'or' together
   * @return A {@code ParseQuery} that is the 'or' of the passed in queries
   */
  public static  ParseQuery or(List> queries) {
    if (queries.isEmpty()) {
      throw new IllegalArgumentException("Can't take an or of an empty list of queries");
    }

    List> builders = new ArrayList<>();
    for (ParseQuery query : queries) {
      builders.add(query.getBuilder());
    }
    return new ParseQuery<>(State.Builder.or(builders));
  }

  /**
   * Creates a new query for the given {@link ParseObject} subclass type. A default query with no
   * further parameters will retrieve all {@link ParseObject}s of the provided class.
   *
   * @param subclass
   *          The {@link ParseObject} subclass type to retrieve.
   * @return A new {@code ParseQuery}.
   */
  public static  ParseQuery getQuery(Class subclass) {
    return new ParseQuery<>(subclass);
  }

  /**
   * Creates a new query for the given class name. A default query with no further parameters will
   * retrieve all {@link ParseObject}s of the provided class name.
   *
   * @param className
   *          The name of the class to retrieve {@link ParseObject}s for.
   * @return A new {@code ParseQuery}.
   */
  public static  ParseQuery getQuery(String className) {
    return new ParseQuery<>(className);
  }

  /**
   * Constructs a query for {@link ParseUser}s.
   *
   * @deprecated Please use {@link ParseUser#getQuery()} instead.
   */
  @Deprecated
  public static ParseQuery getUserQuery() {
    return ParseUser.getQuery();
  }

  /**
   * {@code CachePolicy} specifies different caching policies that could be used with
   * {@link ParseQuery}.
   * 

   * This lets you show data when the user's device is offline, or when the app has just started and
   * network requests have not yet had time to complete. Parse takes care of automatically flushing
   * the cache when it takes up too much space.
   * 

   * Note: Cache policy can only be set when Local Datastore is not enabled.
   *
   * @see com.parse.ParseQuery
   */
  public enum CachePolicy {
    /**
     * The query does not load from the cache or save results to the cache.
     * 

     * This is the default cache policy.
     */
    IGNORE_CACHE,

    /**
     * The query only loads from the cache, ignoring the network.
     * 

     * If there are no cached results, this causes a {@link ParseException#CACHE_MISS}.
     */
    CACHE_ONLY,

    /**
     * The query does not load from the cache, but it will save results to the cache.
     */
    NETWORK_ONLY,

    /**
     * The query first tries to load from the cache, but if that fails, it loads results from the
     * network.
     * 

     * If there are no cached results, this causes a {@link ParseException#CACHE_MISS}.
     */
    CACHE_ELSE_NETWORK,

    /**
     * The query first tries to load from the network, but if that fails, it loads results from the
     * cache.
     * 

     * If there are no cached results, this causes a {@link ParseException#CACHE_MISS}.
     */
    NETWORK_ELSE_CACHE,

    /**
     * The query first loads from the cache, then loads from the network.
     * The callback will be called twice - first with the cached results, then with the network
     * results. Since it returns two results at different times, this cache policy cannot be used
     * with synchronous or task methods.
     */
    // TODO(grantland): Remove this and come up with a different solution, since it breaks our
    // "callbacks get called at most once" paradigm. (v2)
    CACHE_THEN_NETWORK
  }

  private static void throwIfLDSEnabled() {
    throwIfLDSEnabled(false);
  }

  private static void throwIfLDSDisabled() {
    throwIfLDSEnabled(true);
  }

  private static void throwIfLDSEnabled(boolean enabled) {
    boolean ldsEnabled = Parse.isLocalDatastoreEnabled();
    if (enabled && !ldsEnabled) {
      throw new IllegalStateException("Method requires Local Datastore. " +
          "Please refer to `Parse#enableLocalDatastore(Context)`.");
    }
    if (!enabled && ldsEnabled) {
      throw new IllegalStateException("Unsupported method when Local Datastore is enabled.");
    }
  }

  /* package */ static class State {

    /* package */ static class Builder {

      // TODO(grantland): Convert mutable parameter to immutable t6941155
      public static  Builder or(List> builders) {
        if (builders.isEmpty()) {
          throw new IllegalArgumentException("Can't take an or of an empty list of queries");
        }

        String className = null;
        List constraints = new ArrayList<>();
        for (Builder builder : builders) {
          if (className != null && !builder.className.equals(className)) {
            throw new IllegalArgumentException(
                "All of the queries in an or query must be on the same class ");
          }
          if (builder.limit >= 0) {
            throw new IllegalArgumentException("Cannot have limits in sub queries of an 'OR' query");
          }
          if (builder.skip > 0) {
            throw new IllegalArgumentException("Cannot have skips in sub queries of an 'OR' query");
          }
          if (!builder.order.isEmpty()) {
            throw new IllegalArgumentException("Cannot have an order in sub queries of an 'OR' query");
          }
          if (!builder.includes.isEmpty()) {
            throw new IllegalArgumentException("Cannot have an include in sub queries of an 'OR' query");
          }
          if (builder.selectedKeys != null) {
            throw new IllegalArgumentException(
                "Cannot have an selectKeys in sub queries of an 'OR' query");
          }

          className = builder.className;
          constraints.add(builder.where);
        }

        return new State.Builder(className)
            .whereSatifiesAnyOf(constraints);
      }

      private final String className;
      private final QueryConstraints where = new QueryConstraints();
      private final Set includes = new HashSet<>();
      // This is nullable since we allow unset selectedKeys as well as no selectedKeys
      private Set selectedKeys;
      private int limit = -1; // negative limits mean, do not send a limit
      private int skip = 0; // negative skip means do not send a skip
      private List order = new ArrayList<>();
      private final Map extraOptions = new HashMap<>();

      // TODO(grantland): Move out of State
      private boolean trace;

      // Query Caching
      private CachePolicy cachePolicy = CachePolicy.IGNORE_CACHE;
      private long maxCacheAge = Long.MAX_VALUE; // 292 million years should be enough not to cause issues

      // LDS
      private boolean isFromLocalDatastore = false;
      private String pinName;
      private boolean ignoreACLs;

      public Builder(String className) {
        this.className = className;
      }

      public Builder(Class subclass) {
        this(ParseObject.getClassName(subclass));
      }

      public Builder(State state) {
        className = state.className();
        where.putAll(state.constraints());
        includes.addAll(state.includes());
        selectedKeys = state.selectedKeys() != null ? new HashSet(state.selectedKeys()) : null;
        limit = state.limit();
        skip = state.skip();
        order.addAll(state.order());
        extraOptions.putAll(state.extraOptions());
        trace = state.isTracingEnabled();
        cachePolicy = state.cachePolicy();
        maxCacheAge = state.maxCacheAge();
        isFromLocalDatastore = state.isFromLocalDatastore();
        pinName  = state.pinName();
        ignoreACLs = state.ignoreACLs();
      }

      public Builder(Builder builder) {
        className = builder.className;
        where.putAll(builder.where);
        includes.addAll(builder.includes);
        selectedKeys = builder.selectedKeys != null ? new HashSet(builder.selectedKeys) : null;
        limit = builder.limit;
        skip = builder.skip;
        order.addAll(builder.order);
        extraOptions.putAll(builder.extraOptions);
        trace = builder.trace;
        cachePolicy = builder.cachePolicy;
        maxCacheAge = builder.maxCacheAge;
        isFromLocalDatastore = builder.isFromLocalDatastore;
        pinName  = builder.pinName;
        ignoreACLs = builder.ignoreACLs;
      }

      public String getClassName() {
        return className;
      }

      //region Where Constraints

      /**
       * Add a constraint to the query that requires a particular key's value to be equal to the
       * provided value.
       *
       * @param key
       *          The key to check.
       * @param value
       *          The value that the {@link ParseObject} must contain.
       * @return this, so you can chain this call.
       */
      // TODO(grantland): Add typing
      public Builder whereEqualTo(String key, Object value) {
        where.put(key, value);
        return this;
      }

      // TODO(grantland): Convert mutable parameter to immutable t6941155
      public Builder whereDoesNotMatchKeyInQuery(String key, String keyInQuery, Builder builder) {
        Map condition = new HashMap<>();
        condition.put("key", keyInQuery);
        condition.put("query", builder);
        return addConditionInternal(key, "$dontSelect", Collections.unmodifiableMap(condition));
      }

      // TODO(grantland): Convert mutable parameter to immutable t6941155
      public Builder whereMatchesKeyInQuery(String key, String keyInQuery, Builder builder) {
        Map condition = new HashMap<>();
        condition.put("key", keyInQuery);
        condition.put("query", builder);
        return addConditionInternal(key, "$select", Collections.unmodifiableMap(new HashMap<>(condition)));
      }

      // TODO(grantland): Convert mutable parameter to immutable t6941155
      public Builder whereDoesNotMatchQuery(String key, Builder builder) {
        return addConditionInternal(key, "$notInQuery", builder);
      }

      // TODO(grantland): Convert mutable parameter to immutable t6941155
      public Builder whereMatchesQuery(String key, Builder builder) {
        return addConditionInternal(key, "$inQuery", builder);
      }

      public Builder whereNear(String key, ParseGeoPoint point) {
        return addCondition(key, "$nearSphere", point);
      }

      public Builder maxDistance(String key, double maxDistance) {
        return addCondition(key, "$maxDistance", maxDistance);
      }

      public Builder whereWithin(String key, ParseGeoPoint southwest, ParseGeoPoint northeast) {
        List