Repository: incubator-usergrid Updated Branches: refs/heads/USERGRID-510 [created] 607b5107d
[USERGRID-510] added comment to see if RootResource is actually being used Adding a README for the new rest test framework. Project: http://git-wip-us.apache.org/repos/asf/incubator-usergrid/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-usergrid/commit/607b5107 Tree: http://git-wip-us.apache.org/repos/asf/incubator-usergrid/tree/607b5107 Diff: http://git-wip-us.apache.org/repos/asf/incubator-usergrid/diff/607b5107 Branch: refs/heads/USERGRID-510 Commit: 607b5107d1f0b69bc3a6764d844b02d4e8fadebf Parents: 6db7ce9 Author: GERey <[email protected]> Authored: Mon Mar 30 11:54:20 2015 -0700 Committer: GERey <[email protected]> Committed: Mon Mar 30 11:54:20 2015 -0700 ---------------------------------------------------------------------- .../rest/test/resource2point0/README.md | 111 +++++++++++++++++++ .../resource2point0/endpoints/RootResource.java | 1 + 2 files changed, 112 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/607b5107/stack/rest/src/test/java/org/apache/usergrid/rest/test/resource2point0/README.md ---------------------------------------------------------------------- diff --git a/stack/rest/src/test/java/org/apache/usergrid/rest/test/resource2point0/README.md b/stack/rest/src/test/java/org/apache/usergrid/rest/test/resource2point0/README.md new file mode 100644 index 0000000..b82c6f7 --- /dev/null +++ b/stack/rest/src/test/java/org/apache/usergrid/rest/test/resource2point0/README.md @@ -0,0 +1,111 @@ +#Rest Test Framework (RTF) + +##What is it? +It is a java framework that helps abstract some of the difficulty in working with the rest tier. Each endpoint is a different part of the builder pattern that ends with a request at the end. This request is sent to an embedded tomcat that has a usergrid war deployed on it. When the response comes back the RTF parses the response and allows the user to query information returned. + +##How does it work? +It works by modeling the REST tier in Usergrid. We construct our query using usergrid endpoints that create our path and after it gets sent using POST/PUT/GET/DELETE. + +##Where is it +All of the code is stored in resource2point0. The older resource folder holds the old rest testing framework. + +##Requirements +First you must have java 8 running on your machine. Then setup local instances of elasticsearch and cassandra on your box. + +##How do I use it? + +###For example... + +It helps to start out with an example. Let's deconstruct the following line step by step + + clientSetup.getRestClient().management().orgs().post( payload ); + +1. clientSetup + + 1. The clientSetup is what stores the context of the rest call. It also creates a new superuser/org/app/user and stores information specific to each one in the clientsetup. If you don't want to create a new org or app then you are free to call the getters in the clientSetup for the context of the current rest calls. + +2. getRestClient() + + 1. This returns our RestClient that handles the setup for our Jersey WebResource. In the RestClient class we handle the setup of the client and the configuration of the client. + + 2. It also stores the top level rest properties that can be called. This client starts by appending the serverUrl to the resource path. + + 1. The serverUrl for our rest tests is the localhost:port. These are both automatically assigned. + + 3. Next we have the option of calling any of the endpoint detailed in the RestClient.java. You'll see many options but the two most important are probably /management and /org which allow you to access a majority of usergrid endpoints. + +3. management() + + 1. This appends the "management" endpoint unto our path. Right now we have the following path "localhost:8080/management". + + 2. In the ManagementResource class you will find other endpoints that you can call. In this example we're calling ```orgs()```. + +4. orgs() + + 1. This appends "/organizations" to the path, so now we have "localhost:8080/management/organizations" + + 2. This sends us to OrganizationResource.java and will be the first instance where it will give you access to do a REST call. + +5. post( payload ); + + 1. Here the organization class let's us know what endpoints we have available to us. In this case we want to post, but the individual classes will let you know what next steps are available. + 2. So now we have a POST command against the locally embedded tomcat at the following endpoint "localhost:8080/management/organizations" and it will post the payload. + 3. The payload is often a map object but specific types and return types will be covered later in the README. + +###ClientSetup +####What does it do? +It setups and stores a new organization/owner/application/superuser for each test. Since this happens at the beginning of each test we can call the ClientSetup class for information when we don't want/need to create our own organization/owner/application/superuser. + +####For Example... + String org = this.clientSetup.getOrganizationName(); + String app = this.clientSetup.getAppName(); + + clientSetup.getRestClient().org(org).app(app).collection("cities").get(); + +The above example is a call you could make in a rest test as soon as you start writing one. You don't have to create the org and application and you can just reference the ones already created for you. + +###RestClient +####What does it do? +Handles the setup for our Jersey WebResource. In the RestClient class we handle the configuration of the JerseyClient so we can send our rest calls against the tomcat. The rest client also contains the methods to call all of our top level classes. So from the RestClient we can call any of our top level endpoints. + + +###AbstractRestIT + +####What does it do? +This class handles a lot of the setup required by the testing functionality. It also stores helper methods central to each test and setup the tomcat that the tests will be querying. That is why it is extended by every test class. + +####What helper methods does it give me access to? +Every single one of the test queries makes a call from the context ( because it needs access to the unique org and application ) to get the client. There are methods to make the tests look cleaner by automating the calls and getting the endpoint you want without writing + + clientSetup.getRestClient() + +###Endpoints +####What does it do? +Holds the classes that contain the builder pattern. There are a lot of classes here currently so its easy to get lost. Following the RestClient through the hierarchy of the calls you want to run will give you the greatest insight into how they are organized. + + +###Model +This folder handles the data that gets returned from the api and the payloads that go into the api. + +####For Example... + +To create an organization we can create a model object for the specific kind of entity we want to post. + + Organization payload = new Organization( String orgName, String username, String email, String ownerName, String password, Map<String,Object> properties ); + +Now that we have an organization payload, we can POST to create the organization. + + Organization org = clientSetup.getRestClient().management().orgs().post( payload ); + +This in turn creates an Organization object we've called ```org``` that is intialized with the POST response. This gives us easy access to the organization information to verify that it was indeed created correctly. + + +For a more in-depth explanation for how they work look at the readme in the model folder (Work-In-Progress). + + + +<!-- The below needs to be refactored into a different readme just for the model class. + +####How does the RET model responses? +We model responses by serializing the response into its respective model class. At the lowest level we use a ApiResponse. The ApiResponse contains fields for every kind of response we could recieve from the api. If there is any doubt about what class you need to return or push the response in you should use the ApiResponse. From the ApiResponse we model --> + \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/607b5107/stack/rest/src/test/java/org/apache/usergrid/rest/test/resource2point0/endpoints/RootResource.java ---------------------------------------------------------------------- diff --git a/stack/rest/src/test/java/org/apache/usergrid/rest/test/resource2point0/endpoints/RootResource.java b/stack/rest/src/test/java/org/apache/usergrid/rest/test/resource2point0/endpoints/RootResource.java index 65b2b93..4570bac 100644 --- a/stack/rest/src/test/java/org/apache/usergrid/rest/test/resource2point0/endpoints/RootResource.java +++ b/stack/rest/src/test/java/org/apache/usergrid/rest/test/resource2point0/endpoints/RootResource.java @@ -32,6 +32,7 @@ import com.sun.jersey.api.client.WebResource; * 2.) Is the organization resource i.e /<orgname>/<appname>... * This is where top level elements are contained and managemend */ +//TODO: check to see if this actually ever gets called. It doesn't seem like so remove once verified. public class RootResource implements UrlResource {
