com.stackmob.sdk.api
Class StackMobQuery

java.lang.Object
  com.stackmob.sdk.api.StackMobQuery

public class StackMobQuery
extends Object

A class that builds queries for data access methods like those in StackMob. Example usage:

 StackMobQuery query = new StackMobQuery("user")
                             .fieldIsGreaterThan("age", 20)
                             .fieldIsLessThanOrEqualTo("age", 40)
                             .fieldIsIn("friend", Arrays.asList("joe", "bob", "alice");

     //Of if you have multiple constraints on the same field and you want to type less
     StackMobQuery query = new StackMobQuery("user")
                             .field(new StackMobQueryField("age").isGreaterThan(20).isLessThanOrEqualTo(40))
                             .field(new StackMobQueryField("friend").isIn(Arrays.asList("joe", "bob", "alice")));
 
 

A few helpful notes about this object:

• this class is not thread safe. make sure to synchronize all calls
• the field(StackMobQueryField) method helps you build up part of your query on a specific field
• you can only operate on one field at a time, but you can call field("field") as many times as you want
• you can call methods like fieldIsGreaterThan("field", "value") or fieldIsLessThanOrEqualTo("field", "value") directly on a StackMobQuery object.

Nested Class Summary

static class

StackMobQuery.Ordering Represents ascending or descending order

Constructor Summary

StackMobQuery()
creates an empty query.

StackMobQuery(String objectName)
create a query on a specific object

Method Summary

StackMobQuery	add(StackMobQuery other) copy the constraints in a give query to this one
StackMobQuery	and() Separate two constraints with an AND.
StackMobQuery	and(StackMobQuery clauses) Add a new parenthesized expression to be joined by AND with the other constraints in the query.
StackMobQuery	field(StackMobQueryField field) Begin adding constraints to a field via a StackMobQueryField
StackMobQuery	fieldIsEqualTo(String field, int val) add an "=" to your query.
StackMobQuery	fieldIsEqualTo(String field, String val) add an "=" to your query.
StackMobQuery	fieldIsGreaterThan(String field, int val) same as fieldIsLessThan(String, String), except applies ">" instead of "<"
StackMobQuery	fieldIsGreaterThan(String field, String val) same as fieldIsLessThan(String, String), except applies ">" instead of "<"
StackMobQuery	fieldIsGreaterThanOrEqualTo(String field, int val) same as fieldIsLessThan(String, String), except applies ">=" instead of "<"
StackMobQuery	fieldIsGreaterThanOrEqualTo(String field, String val) same as fieldIsLessThan(String, String), except applies ">=" instead of "<"
StackMobQuery	fieldIsIn(String field, List<String> values) add an "IN" to your query.
StackMobQuery	fieldIsLessThan(String field, int val) same as fieldIsLessThan(String, String), except works with Strings
StackMobQuery	fieldIsLessThan(String field, String val) same as fieldIsLessThan(String, String), except works with Strings
StackMobQuery	fieldIsLessThanOrEqualTo(String field, int val) same as fieldIsLessThan(String, String), except applies "<=" instead of "<"
StackMobQuery	fieldIslessThanOrEqualTo(String field, String val) same as fieldIsLessThan(String, String), except applies "<=" instead of "<"
StackMobQuery	fieldIsNear(String field, StackMobGeoPoint point) add a "NEAR" to your query for the given StackMobGeoPoint field.
StackMobQuery	fieldIsNearWithinKm(String field, StackMobGeoPoint point, Double maxDistanceKm) add a "NEAR" to your query for the given StackMobGeoPoint field.
StackMobQuery	fieldIsNearWithinMi(String field, StackMobGeoPoint point, Double maxDistanceMi) add a "NEAR" to your query for the given StackMobGeoPoint field.
StackMobQuery	fieldIsNotEqual(String field, String val) add a "NE" to your query.
StackMobQuery	fieldIsNotNull(String field) add a "NULL" to your query.
StackMobQuery	fieldIsNull(String field) add a "NULL" to your query.
StackMobQuery	fieldIsOrderedBy(String field, StackMobQuery.Ordering ordering) add an "ORDER BY" to your query
StackMobQuery	fieldIsWithinBox(String field, StackMobGeoPoint lowerLeft, StackMobGeoPoint upperRight) add a "WITHIN" to your query for the given StackMobGeoPoint field.
StackMobQuery	fieldIsWithinRadiusInKm(String field, StackMobGeoPoint point, Double radiusInKm) add a "WITHIN" to your query for the given StackMobGeoPoint field.
StackMobQuery	fieldIsWithinRadiusInMi(String field, StackMobGeoPoint point, Double radiusInMi) add a "WITHIN" to your query for the given StackMobGeoPoint field.
List<Map.Entry<String,String>>	getArguments() get the arguments generated by this query
Map<String,String>	getHeaders() get the headers generated by this query
String	getObjectName() get the schema being queried against
StackMobQuery	isInRange(Integer start) same thing as isInRange(Integer, Integer), except does not specify an end to the range.
StackMobQuery	isInRange(Integer start, Integer end) this method lets you add a "LIMIT" and "SKIP" to your query at once.
static StackMobQuery	objects(String objectName) create a query on a specific object
StackMobQuery	or() Separate two constraints with an OR.
StackMobQuery	or(StackMobQuery clauses) Add a new parenthesized expression to be joined by OR with the other constraints in the query.
void	setObjectName(String objectName) set the schema being queried against

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

StackMobQuery

public StackMobQuery()

creates an empty query. StackMobQuery(String) should be used in almost all cases. Only use this if you then later call setObjectName(String)

StackMobQuery

public StackMobQuery(String objectName)

create a query on a specific object

Parameters:

objectName - the schema you're querying against

Method Detail

objects

public static StackMobQuery objects(String objectName)

create a query on a specific object

Parameters:

objectName - the schema you're querying against

Returns:

the new query

setObjectName

public void setObjectName(String objectName)

set the schema being queried against

Parameters:

objectName - the schema

getObjectName

public String getObjectName()

get the schema being queried against

Returns:

objectName the schema

getHeaders

public Map<String,String> getHeaders()

get the headers generated by this query

Returns:

headers

getArguments

public List<Map.Entry<String,String>> getArguments()

get the arguments generated by this query

Returns:

arguments

add

public StackMobQuery add(StackMobQuery other)

copy the constraints in a give query to this one

Parameters:

other - the query to copy

Returns:

a new query contain all the constraints of both

and

public StackMobQuery and()

Separate two constraints with an AND. Constraints are separated like this by default, but this allows your queries to read naturally. You cannot mix AND and OR at the same level of a query; instead you need to start a sub-expression with and(StackMobQuery clauses), effectively adding parenthesis

Returns:

the query ready to accept another statement

and

public StackMobQuery and(StackMobQuery clauses)

Add a new parenthesized expression to be joined by AND with the other constraints in the query. The sub-expression will be treated as the logical OR of a set of clauses, giving you A && (B || C || ...) StackMob only supports one such parenthesized OR block in a query, but it can contain any number of clauses.

Parameters:

clauses - a sub-query. Each constraint added to it is combined into an OR statement.

Returns:

A new query with the OR statement joined with AND to the rest of the clauses.

or

public StackMobQuery or()

Separate two constraints with an OR. This can be done at the top level of a query, or within a sub-query added with and(StackMobQuery clauses) You cannot mix AND and OR at the same level of a query; instead you need to start a sub-expression with ,or(StackMobQuery clauses) effectively adding parenthesis

Returns:

the query ready to accept another statement

or

public StackMobQuery or(StackMobQuery clauses)

Add a new parenthesized expression to be joined by OR with the other constraints in the query. The sub-expression will be treated as the logical AND of a set of clauses, giving you A || (B && C && ...) Redundant nested AND statements will be rejected.

Parameters:

clauses - a sub-query. Each constraint added to it is combined into an AND statement.

Returns:

A new query with the AND statement joined with OR to the rest of the clauses

field

public StackMobQuery field(StackMobQueryField field)

Begin adding constraints to a field via a StackMobQueryField

Parameters:

field - the name of the field

Returns:

a query specific to that field

fieldIsNear

public StackMobQuery fieldIsNear(String field,
                                 StackMobGeoPoint point)

add a "NEAR" to your query for the given StackMobGeoPoint field. Query results are automatically returned sorted by distance closest to the queried point

Parameters:

field - the StackMobGeoPoint field whose value to test

point - the lon/lat location to center the search

Returns:

the new query that resulted from adding this operation

fieldIsNearWithinMi

public StackMobQuery fieldIsNearWithinMi(String field,
                                         StackMobGeoPoint point,
                                         Double maxDistanceMi)

add a "NEAR" to your query for the given StackMobGeoPoint field. Query results are automatically returned sorted by distance closest to the queried point

Parameters:

field - the StackMobGeoPoint field whose value to test

point - the lon/lat location to center the search

maxDistanceMi - the maximum distance in miles a matched field can be from point.

Returns:

the new query that resulted from adding this operation

fieldIsNearWithinKm

public StackMobQuery fieldIsNearWithinKm(String field,
                                         StackMobGeoPoint point,
                                         Double maxDistanceKm)

add a "NEAR" to your query for the given StackMobGeoPoint field. Query results are automatically returned sorted by distance closest to the queried point

Parameters:

field - the StackMobGeoPoint field whose value to test

point - the lon/lat location to center the search

maxDistanceKm - the maximum distance in kilometers a matched field can be from point.

Returns:

the new query that resulted from adding this operation

fieldIsWithinRadiusInMi

public StackMobQuery fieldIsWithinRadiusInMi(String field,
                                             StackMobGeoPoint point,
                                             Double radiusInMi)

add a "WITHIN" to your query for the given StackMobGeoPoint field. Query results are not sorted by distance.

Parameters:

field - the StackMobGeoPoint field whose value to test

point - the lon/lat location to center the search

radiusInMi - the maximum distance in miles a matched field can be from point.

Returns:

the new query that resulted from adding this operation

fieldIsWithinRadiusInKm

public StackMobQuery fieldIsWithinRadiusInKm(String field,
                                             StackMobGeoPoint point,
                                             Double radiusInKm)

add a "WITHIN" to your query for the given StackMobGeoPoint field. Query results are not sorted by distance.

Parameters:

field - the StackMobGeoPoint field whose value to test

point - the lon/lat location to center the search

radiusInKm - the maximum distance in kilometers a matched field can be from point.

Returns:

the new query that resulted from adding this operation

fieldIsWithinBox

public StackMobQuery fieldIsWithinBox(String field,
                                      StackMobGeoPoint lowerLeft,
                                      StackMobGeoPoint upperRight)

add a "WITHIN" to your query for the given StackMobGeoPoint field. Matched fields will be within the 2-dimensional bounds defined by the lowerLeft and upperRight StackMobGeoPoints given

Parameters:

field - the StackMobGeoPoint field whose value to test

lowerLeft - the lon/lat location of the lower left corner of the bounding box

upperRight - the lon/lat location of the upper right corner of the bounding box

Returns:

the new query that resulted from adding this operation

fieldIsIn

public StackMobQuery fieldIsIn(String field,
                               List<String> values)

add an "IN" to your query. test whether the given field's value is in the given list of possible values

Parameters:

field - the field whose value to test

values - the values against which to match

Returns:

the new query that resulted from adding this operation

fieldIsNotEqual

public StackMobQuery fieldIsNotEqual(String field,
                                     String val)

add a "NE" to your query. test whether the given field's value is not equal to the given value

Parameters:

field - the field whose value to test

val - the value against which to match

Returns:

the new query that resulted from adding this operation

fieldIsNull

public StackMobQuery fieldIsNull(String field)

add a "NULL" to your query. test whether the given field's value is null

Parameters:

field - the field whose value to test

Returns:

the new query that resulted from adding this operation

fieldIsNotNull

public StackMobQuery fieldIsNotNull(String field)

add a "NULL" to your query. test whether the given field's value is not null

Parameters:

field - the field whose value to test

Returns:

the new query that resulted from adding this operation

fieldIsLessThan

public StackMobQuery fieldIsLessThan(String field,
                                     String val)

same as fieldIsLessThan(String, String), except works with Strings

Parameters:

field - the field whose value to test

val - the value against which to test

Returns:

the new query that resulted from adding this operation

fieldIsLessThan

public StackMobQuery fieldIsLessThan(String field,
                                     int val)

same as fieldIsLessThan(String, String), except works with Strings

Parameters:

field - the field whose value to test

val - the value against which to test

Returns:

the new query that resulted from adding this operation

fieldIslessThanOrEqualTo

public StackMobQuery fieldIslessThanOrEqualTo(String field,
                                              String val)

same as fieldIsLessThan(String, String), except applies "<=" instead of "<"

Parameters:

field - the field whose value to test

val - the value against which to test

Returns:

the new query that resulted from adding this operation

fieldIsLessThanOrEqualTo

public StackMobQuery fieldIsLessThanOrEqualTo(String field,
                                              int val)

same as fieldIsLessThan(String, String), except applies "<=" instead of "<"

Parameters:

field - the field whose value to test

val - the value against which to test

Returns:

the new query that resulted from adding this operation

fieldIsGreaterThan

public StackMobQuery fieldIsGreaterThan(String field,
                                        String val)

same as fieldIsLessThan(String, String), except applies ">" instead of "<"

Parameters:

field - the field whose value to test

val - the value against which to test

Returns:

the new query that resulted from adding this operation

fieldIsGreaterThan

public StackMobQuery fieldIsGreaterThan(String field,
                                        int val)

same as fieldIsLessThan(String, String), except applies ">" instead of "<"

Parameters:

field - the field whose value to test

val - the value against which to test

Returns:

the new query that resulted from adding this operation

fieldIsGreaterThanOrEqualTo

public StackMobQuery fieldIsGreaterThanOrEqualTo(String field,
                                                 String val)

same as fieldIsLessThan(String, String), except applies ">=" instead of "<"

Parameters:

field - the field whose value to test

val - the value against which to test

Returns:

the new query that resulted from adding this operation

fieldIsGreaterThanOrEqualTo

public StackMobQuery fieldIsGreaterThanOrEqualTo(String field,
                                                 int val)

same as fieldIsLessThan(String, String), except applies ">=" instead of "<"

Parameters:

field - the field whose value to test

val - the value against which to test

Returns:

the new query that resulted from adding this operation

fieldIsEqualTo

public StackMobQuery fieldIsEqualTo(String field,
                                    String val)

add an "=" to your query. test whether the given field's value is equal to the given value

Parameters:

field - the field whose value to test

val - the value against which to test

Returns:

the new query that resulted from adding this operation

fieldIsEqualTo

public StackMobQuery fieldIsEqualTo(String field,
                                    int val)

add an "=" to your query. test whether the given field's value is equal to the given value

Parameters:

field - the field whose value to test

val - the value against which to test

Returns:

the new query that resulted from adding this operation

fieldIsOrderedBy

public StackMobQuery fieldIsOrderedBy(String field,
                                      StackMobQuery.Ordering ordering)

add an "ORDER BY" to your query

Parameters:

field - the field to order by

ordering - the ordering of that field

Returns:

the new query that resulted from adding this operation

isInRange

public StackMobQuery isInRange(Integer start,
                               Integer end)

this method lets you add a "LIMIT" and "SKIP" to your query at once. Can be used to implement pagination in your app.

Parameters:

start - the starting object number (inclusive)

end - the ending object number (inclusive)

Returns:

the new query that resulted from adding this operation

isInRange

public StackMobQuery isInRange(Integer start)

same thing as isInRange(Integer, Integer), except does not specify an end to the range. instead, gets all objects from a starting point (including)

Parameters:

start - the starting object number

Returns:

the new query that resulted from adding this operation