README.md

Usergrid Java SDK

Usergrid SDK written for Java

Initialization

There are two different ways of initializing the Usergrid Java SDK:

1. The singleton pattern is both convenient and enables the developer to use a globally available and always-initialized instance of Usergrid.

Usergrid.initSharedInstance("orgId", "appId");

2. The Instance pattern enables the developer to manage instances of the Usergrid client independently and in an isolated fashion. The primary use-case for this is when an application connects to multiple Usergrid targets.

UsergridClient client = new UsergridClient("orgId","appId");

Note: Examples in this readme assume you are using the Usergrid shared instance. If you've implemented the instance pattern instead, simply replace Usergrid with your client instance variable.

RESTful operations

When making any RESTful call, a type parameter (or path) is always required. Whether you specify this as an argument or in an object as a parameter is up to you.

GET

• To get entities in a collection:

UsergridResponse response = Usergrid.GET("collection");
List<UsergridEntity> entities = response.getEntities();

• To get a specific entity in a collection by uuid or name:

UsergridResponse response = Usergrid.GET("collection","<uuid-or-name>");
UsergridEntity entities = response.entity();

• To get specific entities in a collection by passing a UsergridQuery object:

UsergridQuery query = new UsergridQuery("cats").gt("weight", 2.4)
                                 	.contains("color", "bl*")
                                 .not()
                                 .eq("color", "blue")
                                 .or()
                                 .eq("color", "orange");
	
// this will build out the following query:
// select * where weight > 2.4 and color contains 'bl*' and not color = 'blue' or color = 'orange'
	
UsergridResponse response = Usergrid.GET(query);
List<UsergridEntity> entities = response.getEntities();

POST and PUT

POST and PUT requests both require a JSON body payload. You can pass either a Java object or a UsergridEntity instance. While the former works in principle, best practise is to use a UsergridEntity wherever practical. When an entity has a uuid or name property and already exists on the server, use a PUT request to update it. If it does not, use POST to create it.

• To create a new entity in a collection (POST):

HashMap<String,String> propertyMap = new HashMap<>();
propertyMap.put("cuisine","pizza");
UsergridEntity entity = new UsergridEntity("restaurant","Dino's Deep Dish", propertyMap);	
Usergrid.POST(entity); // entity should now have a uuid property and be created
	
// you can also POST an array of entities:
	
HashMap<String,String> propertyMap = new HashMap<>();
propertyMap.put("cuisine","pizza");

ArrayList<UsergridEntity> entities = new ArrayList<>();
entities.add(new UsergridEntity("restaurant","Dino's Deep Dish", propertyMap));
entities.add(new UsergridEntity("restaurant","Pizza da Napoli", propertyMap));
UsergridResponse response = Usergrid.POST(entities);
List<UsergridEntity> responseEntities = response.getEntities(); // responseEntities should now contain now valid posted entities.

• To update an entity in a collection (PUT):

HashMap<String,String> propertyMap = new HashMap<>();
propertyMap.put("cuisine","pizza");
UsergridEntity entity = new UsergridEntity("restaurant","Dino's Deep Dish", propertyMap);	
UsergridResponse response = Usergrid.POST(entity);
if( response.ok() ) {
	entity.putProperty("owner","Mia Carrara");
	Usergrid.PUT(entity); // entity now has the property 'owner'
}
	
// or update a set of entities by passing a UsergridQuery object

HashMap<String,String> propertiesToUpdate = new HashMap<>();
propertiesToUpdate.put("cuisine","pizza");
UsergridQuery query = new UsergridQuery("restaurants").eq("cuisine","italian");

UsergridResponse response = Usergrid.PUT(query, propertiesToUpdate);
	
    /* the first 10 entities matching this query criteria will be updated:
    e.g.:
        [
            {
                "type": "restaurant",
                "restaurant": "Il Tarazzo",
                "cuisine": "italian",
                "keywords": ["pasta"]
            },
            {
                "type": "restaurant",
                "restaurant": "Cono Sur Pizza & Pasta",
                "cuisine": "italian",
                "keywords": ["pasta"]
            }
        ]
    */

DELETE

DELETE requests require either a specific entity or a UsergridQuery object to be passed as an argument.

• To delete a specific entity in a collection by uuid or name:

UsergridResponse response = Usergrid.DELETE("collection", "<uuid-or-name>"); // if successful, entity will now be deleted

• To specific entities in a collection to delete by passing a UsergridQuery object:

UsergridQuery query = new UsergridQuery("cats").eq("color","black").or().eq("color","white");
	
// this will build out the following query:
// select * where color = 'black' or color = 'white'
	
UsergridResponse response = Usergrid.DELETE(query); // the first 10 entities matching this query criteria will be deleted

Entity operations and convenience methods

UsergridEntity has a number of helper/convenience methods to make working with entities more convenient.

reload()

Reloads the entity from the server:

entity.reload(); // entity is now reloaded from the server

save()

Saves (or creates) the entity on the server:

entity.putProperty("aNewProperty","A new value");
entity.save(); // entity is now updated on the server

remove()

Deletes the entity from the server:

entity.remove(); // entity is now deleted on the server and the local instance should be destroyed

Authentication, current user, and auth-fallback

appAuth and authenticateApp()

Usergrid can use the app client ID and secret that were passed upon initialization and automatically retrieve an app-level token for these credentials.

Usergrid.setAppAuth(new UsergridAppAuth("<client-id>", "<client-secret>"));
Usergrid.authenticateApp(); // Usergrid.appAuth is authenticated automatically when this call is successful

currentUser, userAuth, and authenticateUser()

Usergrid has a special currentUser property.

By default, when calling authenticateUser(), .currentUser will be set to this user if the authentication flow is successful.

UsergridUserAuth userAuth = new UsergridUserAuth("<username>","<password>");
Usergrid.authenticateUser(userAuth); // Usergrid.currentUser is set to the authenticated user and the token is stored within that context

If you want to utilize authenticateUser without setting as the current user, simply pass a false boolean value as the second parameter:

UsergridUserAuth userAuth = new UsergridUserAuth("<username>","<password>");
Usergrid.authenticateUser(userAuth,false); // user is authenticated but Usergrid.currentUser is not set.

authMode

Auth-mode defines what the client should pass in for the authorization header.

By default, Usergrid.authMode is set to .User, when a Usergrid.currentUser is present and authenticated, an API call will be performed using the token for the user.

If Usergrid.authMode is set to .None, all API calls will be performed unauthenticated.

If instead Usergrid.authMode is set to .App, the API call will instead be performed using client credentials, if they're available (i.e. authenticateApp() was performed at some point).

usingAuth()

At times it is desireable to have complete, granular control over the authentication context of an API call.

To facilitate this, the passthrough function .usingAuth() allows you to pre-define the auth context of the next API call.

// assume Usergrid.authMode = UsergridAuthMode.NONE.

Map<String, String> permissionsMap = new HashMap<>();
permissionsMap.put("permission","get,post,put,delete:/**");
UsergridResponse response = Usergrid.usingAuth(Usergrid.getAppAuth()).POST("roles/guest/permissions",permissionsMap);

// here we've temporarily used the client credentials to modify permissions
// subsequent calls will not use this auth context

User operations and convenience methods

UsergridUser has a number of helper/convenience methods to make working with user entities more convenient. If you are not utilizing the Usergrid shared instance, you must pass an instance of UsergridClient as the first argument to any of these helper methods.

create()

Creating a new user:

UsergridUser user = new UsergridUser("username","password");
user.create(); // user has now been created and should have a valid uuid

login()

A simpler means of retrieving a user-level token:

user.login("username","password"); // user is now logged in

logout()

Logs out the selected user. You can also use this convenience method on Usergrid.currentUser.

user.logout(); // user is now logged out

resetPassword()

Resets the password for the selected user.

// if it was done correctly, the new password will be changed
user.resetPassword("oldPassword", "newPassword");

UsergridUser.CheckAvailable()

This is a class (static) method that allows you to check whether a username or email address is available or not.

boolean available = UsergridUser.checkAvailable("email", null); // 'available' == whether an email already exists for a user

available = UsergridUser.checkAvailable(null, "username"); // 'available' == whether an username already exists for a user

available = UsergridUser.checkAvailable("email", "username"); // 'available' == whether an email or username already exist for a user

Querying and filtering data

UsergridQuery initialization

The UsergridQuery class allows you to build out complex query filters using the Usergrid query syntax.

The first parameter of the UsergridQuery builder pattern should be the collection (or type) you intend to query. You can either pass this as an argument, or as the first builder object:

UsergridQuery query = new UsergridQuery("cats");
// or
UsergridQuery query = new UsergridQuery().collection("cats");

You then can layer on additional queries:

UsergridQuery query = new UsergridQuery("cats").gt("weight",2.4).contains("color","bl*")
                                 .not()
                                 .eq("color","white")
                                 .or()
                                 .eq("color","orange");

You can also adjust the number of results returned:

UsergridQuery query = new UsergridQuery("cats").eq("color","black").limit(100);
                                 
// returns a maximum of 100 entities

And sort the results:

UsergridQuery query = new UsergridQuery("cats").eq("color","black").limit(100).asc("name")
                                 
// sorts by 'name', ascending

And you can do geo-location queries:

UsergridQuery query = new UsergridQuery("devices").locationWithin(<distance>, <lat>, <long>);

Using a query in a request

Queries can be passed as parameters to GET, PUT, and DELETE requests:

// Gets entities matching the query.
Usergrid.GET(query);

// Updates the entities matching the query with the new property.
Usergrid.PUT(query, Collections.singletonMap("aNewProperty","A new value"));

// Deletes entities of a given type matching the query.
Usergrid.DELETE(query);

List of query builder objects

type("string")

The collection name to query

collection("string")

An alias for type

eq("key","value") or equals("key","value") or filter("key","value")

Equal to (e.g. where color = 'black')

contains("key","value") or containsString("key","value") or containsWord("key","value")

Contains a string (e.g. where color contains 'bl*')

gt("key","value") or greaterThan("key","value")

Greater than (e.g. where weight > 2.4)

gte("key","value") or greaterThanOrEqual("key","value")

Greater than or equal to (e.g. where weight >= 2.4)

lt("key","value") or lessThan("key","value")

Less than (e.g. where weight < 2.4)

lte("key","value") or lessThanOrEqual("key","value")

Less than or equal to (e.g. where weight <= 2.4)

not()

Negates the next block in the builder pattern, e.g.:

UsergridQuery query = new UsergridQuery("cats").not().eq("color","black");
// select * from cats where not color = 'black'

and()

Joins two queries by requiring both of them. and is also implied when joining two queries without an operator. E.g.:

UsergridQuery query = new UsergridQuery("cats").eq("color","black").eq("fur","longHair");
// is identical to:
UsergridQuery query = new UsergridQuery("cats").eq("color","black").and().eq("fur","longHair");

or()

Joins two queries by requiring only one of them. or is never implied. e.g.:

UsergridQuery query = new UsergridQuery("cats").eq("color","black").or().eq("color", "white");

When using or() and and() operators, and() joins will take precedence over or() joins. You can read more about query operators and precedence here.

locationWithin(distanceInMeters, latitude, longitude)

Returns entities which have a location within the specified radius. Arguments can be float or int.

asc("key") or ascending("key")

Sorts the results by the specified property, ascending

desc("key") or descending("key")

Sorts the results by the specified property, descending

sort("key",UsergridQuerySortOrder.ASC)

Sorts the results by the specified property, in the specified UsergridQuerySortOrder (.ASC or .DESC).

limit(int)

The maximum number of entities to return

cursor("string")

A pagination cursor string

fromString("query string")

A special builder property that allows you to input a pre-defined query string. All builder properties will be ignored when this property is defined. For example:

UsergridQuery query = new UsergridQuery().fromString("select * where color = 'black' order by name asc");

UsergridResponse object

UsergridResponse is the core class that handles both successful and unsuccessful HTTP responses from Usergrid.

If a request is successful, any entities returned in the response will be automatically parsed into UsergridEntity objects and pushed to the entities property.

If a request fails, the error property will contain information about the problem encountered.

ok

You can check UsergridResponse.ok, a Bool value, to see if the response was successful. Any status code < 400 returns true.

UsergridResponse response = Usergrid.GET("collection");
if( response.ok() ) {
    // woo!
}

entity, entities, user, users, first, last

Depending on the call you make, any entities returned in the response will be automatically parsed into UsergridEntity objects and pushed to the entities property. If you're querying the users collection, these will also be UsergridUser objects, a subclass of UsergridEntity.

• .first() returns the first entity in an array of entities; .entity() is an alias to .first(). If there are no entities, both of these will be undefined.

• .last() returns the last entity in an array of entities; if there is only one entity in the array, this will be the same as .first() and .entity(), and will be undefined if there are no entities in the response.

• .getEntities() will either be an array of entities in the response, or an empty array.

• .user() is a special alias for .entity() for when querying the users() collection. Instead of being a UsergridEntity, it will be its subclass, UsergridUser.

• .users() is the same as .user(), though behaves as .getEntities() does by returning either an array of UsergridUser objects or an empty array.

Examples:

UsergridResponse response = Usergrid.GET("collection");
    // you can access:
    //     response.getEntities() (the returned entities)
    //     response.first() (the first entity)
    //     response.entity() (same as response.first)
    //     response.last() (the last entity returned)

UsergridResponse response = Usergrid.GET("collection","<uuid-or-name>");
    // you can access:
    //     response.entity() (the returned entity) 
    //     response.getEntities() (containing only the returned entity)
    //     response.first() (same as response.entity)
    //     response.last() (same as response.entity)

UsergridResponse response = Usergrid.GET("users");
    // you can access:
    //     response.users() (the returned users)
    //     response.getEntities() (same as response.users)
    //     response.user() (the first user)    
    //     response.entity() (same as response.user)   
    //     response.first() (same as response.user)  
    //     response.last() (the last user)

UsergridResponse response = Usergrid.GET("users","<uuid-or-name>");
    // you can access;
    //     response.users() (containing only the one user)
    //     response.getEntities() (same as response.users)
    //     response.user() (the returned user)    
    //     response.entity() (same as response.user)   
    //     response.first() (same as response.user)  
    //     response.last() (same as response.user)  

Connections

Connections can be managed using Usergrid.connect(), Usergrid.disconnect(), and Usergrid.getConnections(), or entity convenience methods of the same name.

When retrieving connections via Usergrid.getConnections(), you can pass in a optional UsergridQuery object in order to filter the connectioned entities returned.

Connect

Create a connection between two entities:

Usergrid.connect(entity1, "relationship", entity2); // entity1 now has an outbound connection to entity2

Retrieve Connections

Retrieve outbound connections:

Usergrid.getConnections(UsergridDirection.OUT, entity1, "relationship");
    // entities is an array of entities that entity1 is connected to via 'relationship'
    // in this case, we'll see entity2 in the array

Retrieve inbound connections:

Usergrid.getConnections(UsergridDirection.IN, entity2, "relationship");
    // entities is an array of entities that connect to entity2 via 'relationship'
    // in this case, we'll see entity1 in the array

Disconnect

Delete a connection between two entities:

Usergrid.disconnect(entity1, "relationship", entity2);
    // entity1's outbound connection to entity2 has been destroyed

Custom UsergridEntity Subclasses

Creating custom subclasses of the base UsergridEntity class (just like UsergridUser and UsergridDevice) is possible.

• To do so, subclass UsergridEntity and implement the required methods:

public class ActivityEntity extends UsergridEntity {
	public static final String ACTIVITY_ENTITY_TYPE = "activity";
	
   public ActivityEntity(){
       super(ACTIVITY_ENTITY_TYPE);
   }
}

• You will also need to register the custom subclass:

Usergrid.initSharedInstance("orgId","appId");
UsergridEntity.mapCustomSubclassToType("activity", ActivityEntity.class);

By registering your custom subclass, the UsergridEntity and UsergridResponse classes are able to generate instances of these classes based on the an entities type.

In the above example, entities which have a type value of activity can now be cast as ActivityEntity objects. e.g.:

UsergridResponse response = Usergrid.GET("activity");
ActivityEntity activityEntity = (ActivityEntity)response.entity();