Feign makes developing against apis that feign restfulness a little bit easier

This pull request introduces Feign, a java to http client binder inspired by [Dagger](https://github.com/square/dagger), [Retrofit](https://github.com/square/retrofit), [jclouds](https://github.com/jclouds/jclouds), and [JAXRS-2.0](https://jax-rs-spec.java.net/nonav/2.0/apidocs/index.html).

### Why Feign and not X?

Restful apis have normalized patterns, formats, and idempotency constraints.  Restful apis can be defined in JAXRS annotations and magically turned into implementations.

Feign aims to make binding java to http apis that [feign restfulness](http://www.slideshare.net/adrianfcole/99problems) easy, too!  Using Feign's regex and overridable codecs, you can write clients for any http service using the same programming model.  Yes.. even SOAP!.  

If you are lucky enough to work with a HATEOAS api, Feign supports advanced restful patterns such as URL discovery and filtering to make that easier, too.  Basically, whether the api is restful or feigns restfulness, you should be able to write a client for it using Feign.

Feign works by processing annotations into a templatized request.  Just before sending it off, arguments are applied to these templates in a straightforward fashion.  While this limits Feign to only supporting text-based apis, it dramatically simplified system aspects such as replaying requests.  It is also stupid easy to unit test your conversions knowing this.

### Basics

Usage typically looks like this, an adaptation of the [canonical Retrofit sample](https://github.com/square/retrofit/blob/master/retrofit-samples/github-client/src/main/java/com/example/retrofit/GitHubClient.java).

```java
interface GitHub {
    @GET
    @Path("/repos/{owner}/{repo}/contributors")
    List<Contributor> contributors(@PathParam("owner") String owner, @PathParam("repo") String repo);
}

static class Contributor {
    String login;
    int contributions;
}

public static void main(String... args) {
  GitHub github = Feign.create(GitHub.class, "https://api.github.com", new GsonGitHubModule());
  for (Entry<String, String> contributor : contributors.entrySet()) {
    System.out.println(contributor.getKey() + " (" + contributor.getValue() + ")");
  }
}
```
### Decoders
The last argument to `Feign.create` specifies how to decode the responses.  You can plug-in your favorite library, such as gson, or use builtin RegEx Pattern decoders.  Here's how the Gson module looks.

```java
@Module(overrides = true, library = true)
static class GsonGitHubModule {
  Gson gson = new Gson();

  @Provides
  @Singleton
  Map<String, Decoder> decoders() {
    // feign can be used for many apis, the key "GitHub" corresponds to the interface simple name.
    return ImmutableMap.<String, Decoder> of("GitHub", new Decoder() {

      @Override
      protected Object decode(Request request, Reader reader, TypeToken<?> type) {
        return gson.fromJson(reader, type.getType());
      }

    });
  }
}
```
In this case, you are choosing to use reflection for the convenience of object mapping.  This usually only implies a few millisecond overhead per response and only a single extra library dependency.  Feign doesn't offer a built-in json decoder as you can see above it is very few lines of code to wire yours in.  If you are a jackson user, you'd probably thank us for not dragging in a dependency you don't use.

### Multiple Interfaces
Feign can produce multiple api interfaces.  These are defined as `Target<T>` (default `HardCodedTarget<T>`), which allow for dynamic discovery and decoration of requests prior to execution.

For example, the following pattern might decorate each request with the current url and auth token from the identity service.

```java
CloudDNS  cloudDNS =  Feign.create().newInstance(new CloudIdentityTarget<CloudDNS>(user, apiKey));
```

You can find [several examples](https://github.com/Netflix/denominator/tree/http/feign/src/test/java/feign/examples) in the test tree.  Do take time to look at them, as seeing is believing!
### Advanced usage and Dagger
#### Wire Logging
You can log the http messages going to and from the target by setting up a `Wire`.  Here's the easiest way to do that:
```java
@Module(overrides = true)
class Overrides {
  @Provides
  @Singleton
  Wire provideWire() {
    return new Wire.LoggingWire().appendToFile("logs/http-wire.log");
  }
}
GitHub github = Feign.create(GitHub.class, "https://api.github.com", new GsonGitHubModule(), new Overrides());
```
#### Dagger
Feign can be directly wired into Dagger as well.  This allows you to take advantage of `Singleton`, `Lazy`, and other handy features, as well use Dagger for config as opposed to writing builders.  Taking the example above, I could wire up like so..

```java
@Module(injects = Rackspace.class, complete = false)
static class RackspaceModule {
  ...
  @Provides
  @Singleton
  CloudDNS cloudDNS(Feign feign, CloudDNSTarget target) {
    return feign.newInstance(target);
  }
}

static class CloudDNSTarget implements Target<CloudDNS> {
  private final Lazy<UrlAndToken> lazyUrlAndToken;

  @Inject
  CloudDNSTarget(Lazy<UrlAndToken> lazyUrlAndToken) {
    this.lazyUrlAndToken = lazyUrlAndToken;
  }
  ...
  @Override
  public String url() {
    return lazyUrlAndToken.get().getUrl();
  }

  @Override
  public Request apply(RequestTemplate input) {
    input.insert(0, urlAndToken.get().getUrl()));
    input.header("X-Auth-Token", urlAndToken.get().getToken());
    return input.request();
  }
}
```
#### Regex Decoders
If you have sparse (but reliably shaped) structures to parse, you might consider the builtin regex pattern decoders.  These allow you a lot of control about how to create objects.  Here's how that would look.
```java
@Module(overrides = true, library = true)
static class RegexGitHubModule {
  @Provides
  @Singleton
  Map<String, Decoder> decoders() {
    return ImmutableMap.of(
        // notice you can also narrow down decoder to method names in javadoc link format
        "GitHub#contributors(String,String)",
        transformSubsequencesIntoElements("\"login\":\"([^\"]+)\".*?\"contributions\":([0-9]+)",
            contributorFactory));
  }

  Function<List<String>, Contributor> contributorFactory = new Function<List<String>, Contributor>() {

    @Override
    public Contributor apply(List<String> input) {
      Contributor contributor = new Contributor();
      contributor.login = input.get(0);
      contributor.contributions = Ints.tryParse(input.get(1));
      return contributor;
    }

  };
}
```