usergrid-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From g...@apache.org
Subject [09/15] usergrid git commit: Updating ReadMe.
Date Thu, 19 May 2016 17:17:23 GMT
Updating ReadMe.


Project: http://git-wip-us.apache.org/repos/asf/usergrid/repo
Commit: http://git-wip-us.apache.org/repos/asf/usergrid/commit/09dd7f69
Tree: http://git-wip-us.apache.org/repos/asf/usergrid/tree/09dd7f69
Diff: http://git-wip-us.apache.org/repos/asf/usergrid/diff/09dd7f69

Branch: refs/heads/master
Commit: 09dd7f69d40074137bd2115be2b2298cbfeaee4b
Parents: 960ada2
Author: Robert Walsh <rjwalsh1985@gmail.com>
Authored: Thu Apr 14 14:27:07 2016 -0500
Committer: Robert Walsh <rjwalsh1985@gmail.com>
Committed: Thu Apr 14 14:27:07 2016 -0500

----------------------------------------------------------------------
 sdks/java/README.md | 598 +++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 579 insertions(+), 19 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/usergrid/blob/09dd7f69/sdks/java/README.md
----------------------------------------------------------------------
diff --git a/sdks/java/README.md b/sdks/java/README.md
index 7943c41..95e4d04 100644
--- a/sdks/java/README.md
+++ b/sdks/java/README.md
@@ -1,20 +1,580 @@
+# Usergrid Java SDK
 
-#Usergrid Java Client
-
-#License
-Licensed to the Apache Software Foundation (ASF) under one
-or more contributor license agreements.  See the NOTICE file
-distributed with this work for additional information
-regarding copyright ownership.  The ASF licenses this file
-to you under the Apache License, Version 2.0 (the
-"License"); you may not use this file except in compliance
-with the License.  You may obtain a copy of the License at
-
-  http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing,
-software distributed under the License is distributed on an
-"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-KIND, either express or implied.  See the License for the
-specific language governing permissions and limitations
-under the License.
+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<UsergridEntity> entities = response.getEntities();
+```
+
+- To get a specific entity in a collection by uuid or name:
+
+```java
+UsergridResponse response = Usergrid.GET("collection","<uuid-or-name>");
+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<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**):
+
+```java
+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**):
+
+```java
+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:
+
+```java
+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:
+
+```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("<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.
+
+```java
+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:
+
+```java
+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.
+
+```java
+// 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:
+
+```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(<distance>, <lat>,
<long>);
+```
+
+### 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","<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:
+
+```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();
+```


Mime
View raw message