# repos_asf_usergrid-java **Repository Path**: mirrors_community_gitbox_apache/repos_asf_usergrid-java ## Basic Information - **Project Name**: repos_asf_usergrid-java - **Description**: No description available - **Primary Language**: Unknown - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2021-07-29 - **Last Updated**: 2026-01-11 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 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. ```java 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. ```java 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: ```java UsergridResponse response = Usergrid.GET("collection"); List entities = response.getEntities(); ``` - To get a specific entity in a collection by uuid or name: ```java UsergridResponse response = Usergrid.GET("collection",""); UsergridEntity entities = response.entity(); ``` - To get specific entities in a collection by passing a `UsergridQuery` object: ```java 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 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**): ```java HashMap 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 propertyMap = new HashMap<>(); propertyMap.put("cuisine","pizza"); ArrayList 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 responseEntities = response.getEntities(); // responseEntities should now contain now valid posted entities. ``` - To update an entity in a collection (**PUT**): ```java HashMap 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 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: ```java UsergridResponse response = Usergrid.DELETE("collection", ""); // if successful, entity will now be deleted ``` - To specific entities in a collection to delete by passing a `UsergridQuery` object: ```java 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: ```java entity.reload(); // entity is now reloaded from the server ``` ### save() Saves (or creates) the entity on the server: ```java entity.putProperty("aNewProperty","A new value"); entity.save(); // entity is now updated on the server ``` ### remove() Deletes the entity from the server: ```java 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. ```java Usergrid.setAppAuth(new UsergridAppAuth("", "")); 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. ```java UsergridUserAuth userAuth = new UsergridUserAuth("",""); 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: ```java UsergridUserAuth userAuth = new UsergridUserAuth("",""); 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. ```java // assume Usergrid.authMode = UsergridAuthMode.NONE. Map 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: ```java 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: ```java 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`. ```java user.logout(); // user is now logged out ``` ### resetPassword() Resets the password for the selected user. ```java // 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. ```java 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](http://docs.apigee.com/app-services/content/querying-your-data). 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: ```java UsergridQuery query = new UsergridQuery("cats"); // or UsergridQuery query = new UsergridQuery().collection("cats"); ``` You then can layer on additional queries: ```java 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: ```java UsergridQuery query = new UsergridQuery("cats").eq("color","black").limit(100); // returns a maximum of 100 entities ``` And sort the results: ```java UsergridQuery query = new UsergridQuery("cats").eq("color","black").limit(100).asc("name") // sorts by 'name', ascending ``` And you can do geo-location queries: ```java UsergridQuery query = new UsergridQuery("devices").locationWithin(, , ); ``` ### Using a query in a request Queries can be passed as parameters to GET, PUT, and DELETE requests: ```java // 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.: ```java 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.: ```java 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.: ```java 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](http://docs.apigee.com/api-baas/content/supported-query-operators-data-types). `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: ```java 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. ```java 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: ```java 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",""); // 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",""); // 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: ```java Usergrid.connect(entity1, "relationship", entity2); // entity1 now has an outbound connection to entity2 ``` ### Retrieve Connections Retrieve outbound connections: ```java 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: ```java 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: ```java 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: ```java 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: ```java 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.: ```java UsergridResponse response = Usergrid.GET("activity"); ActivityEntity activityEntity = (ActivityEntity)response.entity(); ```