sahan/robozombie

Effortless networking for your Android application.

	RoboZombie   /rō-bō'zŏm'bē/   noun. 1. Makes Android networking a breeze.   2. Accepts an interface which describes the remote service and gives you an implementation of it.
robozombie-1.3.3.jar

##Overview

Here's your model.

public class Repo {

    private String id;
    private String name;
    private boolean fork;
    private int stargazers_count;
    
    ...
}

Define the endpoint.

@Deserialize(JSON)
@Endpoint("https://api.github.com")
public interface GitHubEndpoint {

    @GET("/users/{user}/repos")
    List<Repo> getRepos(@PathParam("user") String user);
}

Looks for Gson on your build path.

Inject and invoke.

@Bite
private GitHubEndpoint endpoint;   

{
    Zombie.infect(this);
}

...

List<Repo> repos = endpoint.getRepos("sahan");

Create as many endpoints as you want...

@Endpoint("http://example.com")
public interface ExampleEndpoint {

    @Serialize(XML) 
    @PUT("/content")
    void putContent(@Entity Content content);
}

Looks for Simple-XML on your build path.

...and inject 'em all.

@Bite
private GitHubEndpoint gitHubEndpoint;

@Bite
private ExampleEndpoint exampleEndpoint;

{
    Zombie.infect(this);
}

RoboZombie requires the **INTERNET** manifest permission for network communication.

<uses-permission android:name="android.permission.INTERNET" />

...and be sure to invoke all synchronous requests from a worker thread.

##Setup > If you opt to use the out-of-the-box JSON (de)serializer add the [Gson](http://code.google.com/p/google-gson) dependency; like wise add the [Simple-XML](http://simple.sourceforge.net) dependency for the XML (de)serializer.
### 1. For Maven based projects.

Add the following dependency to project's pom.xml file.

<dependency>
   <groupId>com.lonepulse</groupId>
   <artifactId>robozombie</artifactId>
   <version>1.3.3</version>
</dependency>

### 2. For Gradle based projects.

Add the following repository and dependency to your project's build.gradle file.

repositories {
    mavenCentral()
}

dependencies {
    compile 'com.lonepulse:robozombie:1.3.3'
}

### 3. Add the JAR to your build path manually.

Download the RoboZombie-1.3.3.jar and add it to your libs folder.

Note that Gson is required for JSON (de)serialization and Simple-XML is required for XML (de)serialization.

##Wiki

Coding with RoboZombie is a breeze. It follows a simple annotation based coding style and adheres to a minimal intrusion policy. Kickoff with the quickstart and follow the rest of the wiki pages.

1. Quickstart

2. Defining, Injecting and Invoking

3. Identifying HTTP Methods

4. Sending Query and Form Parameters

5. Sending a Request Body

6. Serializing Request Content

7. Receiving a Response Body

8. Deserializing Response Content

9. Sending and Receiving Headers

10. Executing Requests Asynchronously

11. Creating Stateful Endpoints

12. Intercepting Requests

13. Overriding, Detaching and Skipping Components

14. Wiring and Injecting Endpoints

15. Configuring RoboZombie
    
    

##License This library is licensed under Apache License, Version 2.0.

robozombie's Issues

Add support for HTTP PATCH requests

Allow endpoints to use the HTTP PATCH method for requests. This method should be treated in conformance with IETF RFC-5789.

Consolidate parameters for @Endpoint

Refactor @Endpoint to accept a single coherent URI string. It's safe to assume that the user will provide a syntactically correct URI. In this case, individual parameters will just be an obtrusion and affect the API UX as well. A single required string parameter would be more concise and mandate a URI. A bare minimum would be scheme://domain.

Update test cases to stop relying on the ICNDB endpoint

The test suite contains an endpoint which relies on the API at ICNDB. Migrate all these test cases to the MockEndpoint contract.

Support state management with cookie stores

Support HTTP state management with cookie stores. Refer Chapter 3 of Apache HC documentation for more information.

Allow inherited metadata to be detached from a request definition

Introduce an annotation named @Detach which can be used to disinherit metadata defined at the endpoint level. This feature should only be activated on metadata which makes sense to be detached - such as @Serializer, @Deserializer and @Async.

It would eliminate repetitive metadata definitions to accommodate a request which strays from the norm. For example, an asynchronous endpoint with just one synchronous request.

Treat all 2xx type response codes as successful operations

Only HttpStatus.SC_OK (a response code of 200) is being treated as a successful operation. Refactor to accept all response codes of class 2xx.

Allow separate request execution configurations to be tailored for each endpoint

Facilitate the provision of a custom configuration for an endpoint to tailor properties such as schemes, timeouts, number of pooled connections ...etc. Expose a template, Zombie.Configuration which can be extended as required to configure the properties and allow these custom extensions to be identified on an endpoint interface via an @Configuration annotation.

Streamline request handling by delegating to a chain of processors

Refactor the current design of creating and growing requests by decoupling each unit of work to a pipeline segment and chaining them to produce the final request. Identify any dependencies among the processors and their hierarchy therein. Differentiate recoverable and unrecoverable segments in the pipeline. Allow for multiple pipelines with different segments and/or varying segment combinations.

Unify all request failures under a single context aware exception

Enforce all execution failures to be acknowledged consistently regardless of whether they are request failures without a 2xx type response code or an erroneous request execution.

Introduce a context aware RequestFailedException which will be thrown for all execution failures. It should support access to the invocation context which initiated the failed request, provide the response if available and produce a stack-trace which identifies any root cause.

Support interception of requests prior to execution

Allow interception of requests for custom processing just before they are executed. This allows the API user to hook into the very end of the request processor chain and manipulate the request under-the-hood. Such interaction might be required to circumvent any rigidity in the current API which would otherwise disable a successful request execution.

Provide a generic Interceptor contract which all interceptors must implement and allow them to be attached via an @Interceptor annotation or be passed in as a request parameter.

Eliminate coupling with GSON and Simple-XML

The current approach for parsing JSON or XML response content with @Parser using ParserType.JSON or ParserType.XML is tightly coupled with GSON and JAXB. From an API user's perspective this would be an imposition. In addition, if the API user opts for another library for JSON parsing, the GSON dependency will simply be an overhead.

Current dependency on JAXB is to be dropped in favor of Simple-XML which is more lightweight and Android friendly.

Offer the prefabricated JSON and XML response parsers only when GSON or Simple-XML is detected on the classpath. Issue a warning on class-loading and an informative error upon usage of either parser in the absence of the required libraries.

Streamline response handling by delegating to a chain of processors

Refactor the current design for handling responses and parsing entities by decoupling each unit of work to a pipeline segment and chaining them to produce the final result. Identify any dependencies among the processors and their hierarchy therein. Differentiate recoverable and unrecoverable segments in the pipeline. Allow for multiple pipelines with different segments and/or varying segment combinations.

Deprecate constructor injection for endpoints

So far, constructor injection for endpoints seems to have no redeeming features over field or setter injection. Its current implementation (at v1.2.3) is not quite comprehensive as one would want it to be. Even if it was to grow, usage would undoubtedly be unwieldy. It will be unusable if the design (e.g. a factory method) doesn't permit it, or more importantly if a full-fledged DI container is already being used.

No deprecation cycle will be followed.

RoboZombie with ProGuard

Short question: is RoboZombie supposed to work in an app that was minified by ProGuard? If so, is any special configuration needed in proguard-project.txt?

How does RoboZombie differ from Retrofit ?

Looks like those project are close, what are the differences ?

Separate content conversion to serialization and deserialization

Revise the current design for response parsing via @Parser, ParserType and AbstractResponseParser to clearly define its role as a content deserializer. This establishes the definition for the output as being a model rather than a parse tree - where a parse tree would be an intermediate step to arriving at a complete model. In addition, it conveys the idea that a content format used for transmission should be converted to an object state in memory.

Refactor @Parser to @Deserializer and AbstractResponseParser to AbstractDeserializer. Deprecate ParserType and allocate a ContentType to all prefabricated deserializers. Retain the rules for annotation overriding at request level.

Similarly, allow request entities to be serialized to the specified ContentType using a set of prefabricated serializers identified by @Serialize.

Given below is a sample endpoint definition with separate serializers and deserializers.

import static com.lonepulse.robozombie.annotation.Entity.ContentType.*;
import static com.lonepulse.robozombie.annotation.Request.RequestMethod.*;


@Serializer(JSON) 
@Deserializer(JSON) 
@Endpoint("www.example.com")
public interface TravelPlannerEndpoint {

    @Request(path = "/travellers/{id}")
    Traveller getTraveller(@PathParam("id") String id);

    @Request(path = "/travellers", method = PUT)
    void putTraveller(@Entity Traveller traveller);

    @Deserializer(XML) 
    @Request(path = "/routes?{waypoints}")
    Route getRoute(@PathParam("waypoints") String waypoints);
}

Enable selective component skipping

Allow inherited components to be skipped selectively for a particular request definition using an @Skip annotation.

Fix TypeToken usage on JsonDeserializer

Fix JsonDeserializer for proper usage of TypeToken with parameterized types.

Allow batch identification of query and form params

Allow identification of query and form parameters as a map of name and value pairs using two separate annotations, @QueryParams and @FormParams. This should provide a much more concise definition for requests with many query or form parameters.

Allow constant query and form parameters to be specified using the same annotations with a common @Param annotation.

Update request metadata to be more concise and expressive

The existing annotation @Request should be altered for use as a meta-annotation on more succinct types such as @GET and @PUT. This abbreviates the definition and clearly expresses the method type.

As an afterthought, this would provide a stepping stone for custom API user annotations annotated with @Request should such supporting features ever be considered.

Refactor design for populating request parameters to strictly adhere with RFC-2616

Refactor the current design for populating request parameters using the generic model of annotating an endpoint request argument with @Param or using @Request.Param on the request itself. This mapping should result in a request parameter whose format and mode of usage conforms with its HTTP/1.1 request method (as defined in Section 9 of the RFC).

Confine hierarchical searches for wired endpoints

Allow the provision of packages prefixes to identify the domains whose types should be scanned for wired endpoints. This is a rudimentary solution to confining the search space when traversing up an inheritance hierarchy to look for injection targets.

Allow explicit identification of query params, form-url-encoded params and entities to be enclosed

Allow the explicit identification of query params by @QueryParam, form-url-encoded params by @FormParam and entities to be enclosed by @Entity. This is a divergence from the generic model of using @Param for GET, POST and PUT requests.

The generic model makes a set of assumptions which might make it impossible to define contracts for certain endpoints. With these annotations we have more flexibility and it eliminates API ambiguity. However, adhere to HTTP/1.1 (as defined in Section 9 of the RFC) where possible and give a polite warning when usage deviates.

P.S. consider deprecating @Param - which now seems redundant... Tim Toady Bicarbonate?

Eliminate the need for a separate annotation on RESTful requests

Eliminate the need for a separate @Rest annotation on RESTful requests. Currently, this annotation is used only to detect the potential existence of path parameters - defer this to the generic @Request annotation.

P.S. maintain backwards compatibility on the next 1.3.0 semantic version and follow a deprecation cycle till the next major release.