Adds more documentation about http modules

modules/okhttp-client/README.md

@@ -56,7 +56,7 @@ public static class ProxyHandler implements RequestHandler {
   }
 }
 ```
-## Add metrics to outgoing http requests
+## Adding metrics to outgoing http requests
 
 In order to have metrics for the outgoing http requests, the HttpMetricModule should be used
  together with HttpClientModule. 
@@ -72,4 +72,6 @@ public static void main(String[] args) throws Exception {
               .withModule(HttpMetricModule.create())
               .build();
 }
-```
+```
+
+It's important that `HttpMetricModule` to be declared **AFTER** `HttpClientModule`, otherwise the decorator won't work as expected. This is a short-coming of the framework that we [plan](https://github.com/spotify/apollo/issues/362) to fix in the future.

modules/okhttp-client/src/main/java/com/spotify/apollo/http/client/HttpClientModule.java

@@ -19,17 +19,29 @@
  */
 package com.spotify.apollo.http.client;
 
+import com.google.inject.multibindings.Multibinder;
 import com.spotify.apollo.environment.ClientDecorator;
+import com.spotify.apollo.environment.IncomingRequestAwareClient;
 import com.spotify.apollo.module.AbstractApolloModule;
 import com.spotify.apollo.module.ApolloModule;
-
-import com.google.inject.multibindings.Multibinder;
 import com.squareup.okhttp.OkHttpClient;
 
+/**
+ * Module extends {@link IncomingRequestAwareClient} to be able to handle HTTP calls.
+ *
+ * <p>You can also use the {@link OkHttpClient} in case you don't want to use the apollo client, but
+ * doing so won't provide you with metrics (which still needs to be enabled by using the {@link
+ * HttpMetricModule}).
+ *
+ * @see OkHttpClientProvider
+ * @see HttpMetricModule
+ * @see IncomingRequestAwareClient
+ * @see com.spotify.apollo.Client
+ * @see com.spotify.apollo.Environment#client()
+ */
 public class HttpClientModule extends AbstractApolloModule {
 
-  private HttpClientModule() {
-  }
+  private HttpClientModule() {}
 
   public static ApolloModule create() {
     return new HttpClientModule();
@@ -38,7 +50,8 @@ public static ApolloModule create() {
   @Override
   protected void configure() {
     Multibinder.newSetBinder(binder(), ClientDecorator.class)
-        .addBinding().to(HttpClientDecorator.class);
+        .addBinding()
+        .to(HttpClientDecorator.class);
 
     bind(HttpClient.class);
     bind(OkHttpClient.class).toProvider(OkHttpClientProvider.class);

modules/okhttp-client/src/main/java/com/spotify/apollo/http/client/HttpMetricModule.java

@@ -17,7 +17,6 @@
  * limitations under the License.
  * -/-/-
  */
-
 package com.spotify.apollo.http.client;
 
 import com.google.inject.Inject;
@@ -28,6 +27,35 @@
 import com.spotify.apollo.module.ApolloModule;
 import com.spotify.metrics.core.SemanticMetricRegistry;
 
+/**
+ * Module that adds metrics to any http call using the Apollo client.
+ *
+ * <p>The declaration of this module must be done <b>AFTER</b> the {@link HttpClientModule} like so:
+ *
+ * <blockquote>
+ *
+ * See <a href="https://github.com/spotify/apollo/issues/362">issue#362</a> for more information *
+ * on why the order matters.
+ *
+ * </blockquote>
+ *
+ * <pre>
+ * Services.usingName(SERVICE_NAME)
+ *   // ...
+ *   .withModule(HttpClientModule.create())
+ *   .withModule(HttpMetricModule.create())
+ *   // ...
+ * </pre>
+ *
+ * <p>Any usage of {@link com.spotify.apollo.Client} should now send metrics to the registered
+ * metric registry.
+ *
+ * @see HttpClientModule
+ * @see com.spotify.apollo.Environment#client()
+ * @see IncomingRequestAwareClient
+ * @see com.spotify.apollo.Client
+ * @see MetricsHttpClient
+ */
 public class HttpMetricModule extends AbstractApolloModule {
 
   public static ApolloModule create() {

modules/okhttp-client/src/main/java/com/spotify/apollo/http/client/OkHttpClientProvider.java

@@ -19,20 +19,18 @@
  */
 package com.spotify.apollo.http.client;
 
+import static com.spotify.apollo.environment.ConfigUtil.optionalBoolean;
+import static com.spotify.apollo.environment.ConfigUtil.optionalInt;
+
 import com.google.common.io.Closer;
 import com.google.inject.Inject;
 import com.google.inject.Provider;
-
 import com.squareup.okhttp.ConnectionPool;
 import com.squareup.okhttp.OkHttpClient;
 import com.typesafe.config.Config;
-
 import java.util.Optional;
 import java.util.concurrent.TimeUnit;
 
-import static com.spotify.apollo.environment.ConfigUtil.optionalBoolean;
-import static com.spotify.apollo.environment.ConfigUtil.optionalInt;
-
 class OkHttpClientProvider implements Provider<OkHttpClient> {
 
   private final OkHttpClientConfig config;

modules/okhttp-client/src/test/java/com/spotify/apollo/http/client/HttpClientModuleTest.java

@@ -19,39 +19,33 @@
  */
 package com.spotify.apollo.http.client;
 
-import com.spotify.apollo.core.Service;
-import com.spotify.apollo.core.Services;
-import com.spotify.apollo.environment.ClientDecorator;
+import static org.hamcrest.CoreMatchers.hasItem;
+import static org.hamcrest.CoreMatchers.instanceOf;
+import static org.hamcrest.MatcherAssert.assertThat;
+import static org.hamcrest.Matchers.is;
 
 import com.google.inject.Injector;
 import com.google.inject.Key;
+import com.spotify.apollo.core.Service;
+import com.spotify.apollo.core.Services;
+import com.spotify.apollo.environment.ClientDecorator;
 import com.squareup.okhttp.OkHttpClient;
 import com.typesafe.config.Config;
 import com.typesafe.config.ConfigFactory;
-
-import org.junit.Test;
-
 import java.util.Set;
-
-import static org.hamcrest.CoreMatchers.hasItem;
-import static org.hamcrest.CoreMatchers.instanceOf;
-import static org.hamcrest.Matchers.is;
-import static org.junit.Assert.assertThat;
+import org.junit.Test;
 
 public class HttpClientModuleTest {
 
   Service service() {
-    return Services.usingName("ping")
-        .withModule(HttpClientModule.create())
-        .build();
+    return Services.usingName("ping").withModule(HttpClientModule.create()).build();
   }
 
   @Test
   public void testShouldInsertHttpClientDecorator() throws Exception {
     try (Service.Instance i = service().start()) {
       final Set<ClientDecorator> clientDecorators =
-          i.resolve(Injector.class).getInstance(new Key<Set<ClientDecorator>>() {
-          });
+          i.resolve(Injector.class).getInstance(new Key<Set<ClientDecorator>>() {});
       assertThat(clientDecorators, hasItem(instanceOf(HttpClientDecorator.class)));
     }
   }
@@ -65,16 +59,13 @@ public void testShouldInsertHttpClientDecorator() throws Exception {
   public void testOkHttpClientIsConfigured() throws Exception {
     final Config config = ConfigFactory.parseString("http.client.connectTimeout: 7982");
 
-    final Service service = Services.usingName("test")
-        .withModule(HttpClientModule.create())
-        .build();
+    final Service service =
+        Services.usingName("test").withModule(HttpClientModule.create()).build();
 
     try (Service.Instance i = service.start(new String[] {}, config)) {
 
       final OkHttpClient underlying = i.resolve(OkHttpClient.class);
       assertThat(underlying.getConnectTimeout(), is(7982));
     }
-
   }
-
 }

modules/okhttp-client/src/test/java/com/spotify/apollo/http/client/HttpMetricModuleTest.java

@@ -0,0 +1,98 @@
+/*
+ * -\-\-
+ * Spotify Apollo okhttp Client Module
+ * --
+ * Copyright (C) 2013 - 2015 Spotify AB
+ * --
+ * Licensed 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.
+ * -/-/-
+ */
+package com.spotify.apollo.http.client;
+
+import static org.hamcrest.CoreMatchers.hasItem;
+import static org.hamcrest.CoreMatchers.instanceOf;
+import static org.hamcrest.MatcherAssert.assertThat;
+import static org.mockito.Mockito.mock;
+
+import com.google.inject.Binder;
+import com.google.inject.Injector;
+import com.google.inject.Key;
+import com.spotify.apollo.core.Service;
+import com.spotify.apollo.core.Services;
+import com.spotify.apollo.environment.ClientDecorator;
+import com.spotify.apollo.environment.IncomingRequestAwareClient;
+import com.spotify.apollo.http.client.HttpMetricModule.HttpMetricClientDecorator;
+import com.spotify.apollo.module.ApolloModule;
+import com.spotify.metrics.core.SemanticMetricRegistry;
+import java.io.IOException;
+import java.util.Collections;
+import java.util.Set;
+import org.junit.Before;
+import org.junit.Test;
+import org.mockito.Answers;
+
+class HttpMetricModuleTest {
+
+  private SemanticMetricRegistry mockedMetricRegistry;
+  private IncomingRequestAwareClient mockedClient;
+  private Service service;
+
+  @Before
+  public void setup() {
+    service =
+        Services.usingName("httpMetricModuleTest")
+            .withModule(
+                new ApolloModule() {
+                  @Override
+                  public String getId() {
+                    return "testing-";
+                  }
+
+                  @Override
+                  public double getPriority() {
+                    return 0;
+                  }
+
+                  @Override
+                  public Set<? extends Key<?>> getLifecycleManaged() {
+                    return Collections.emptySet();
+                  }
+
+                  @Override
+                  public void configure(Binder binder) {
+                    mockedMetricRegistry = mock(SemanticMetricRegistry.class);
+                    binder.bind(SemanticMetricRegistry.class).toInstance(mockedMetricRegistry);
+                    mockedClient =
+                        mock(IncomingRequestAwareClient.class, Answers.CALLS_REAL_METHODS);
+                    binder.bind(IncomingRequestAwareClient.class).toInstance(mockedClient);
+                  }
+                })
+            .withModule(HttpMetricModule.create())
+            .build();
+  }
+
+  @Test
+  public void testShouldHaveDecoratorConfigured() throws IOException {
+    // given
+    try (Service.Instance i = service.start()) {
+      final Injector injector = i.resolve(Injector.class);
+
+      // when
+      final Set<ClientDecorator> clientDecorators =
+          injector.getInstance(new Key<Set<ClientDecorator>>() {});
+
+      // then
+      assertThat(clientDecorators, hasItem(instanceOf(HttpMetricClientDecorator.class)));
+    }
+  }
+}