updated docs, renamed some service methods

Author: yassine

README.md

@@ -6,42 +6,101 @@
 [![Reliability](https://sonarcloud.io/api/project_badges/measure?metric=reliability_rating&project=yassine_ipdata-java-client)](https://sonarcloud.io/dashboard/index/yassine_ipdata-java-client)
 
 
-An <i>ipdata.co</i> java client.
+An 100% compliant [ipdata.co](https://ipdata.co) API java client.
 
-Recipes:
-1. I wanna call the api without caching results :
-```java
-URL url = new URL("https://api.ipdata.co");
-IpdataService ipdataService = Ipdata.builder().url(url)
-      .noCache()
-      .key("MY_KEY")
-      .get();
-IpdataModel model = ipdataService.get("1.1.1.1");
+**Table of Contents**
+
+- [Install](#install)
+- [Use](#use)
+  - [Configuration](#configuration)
+  - [API](#create-an-instance)
+    - [Basic Usage](#basic-usage)
+    - [Single Field Selection](#single-field-selection)
+    - [Multiple Field Selection](#multiple-field-selection)
+    - [Bulk data](#bulk-data)
+  
+
+## Install
+You can have the library from Maven Central.
+```
+<dependency>
+    <groupId>co.ipdata.client</groupId>
+    <artifactId>ipdata-java-client</artifactId>
+    <version>TBD</version>
+</dependency>
 ```
-2. I wanna call the api while caching results for further calls on the same IP (caching will yield you a latency of less than 1ms for requests that hit the cache):
+
+## Use
+
+### Configuration
+A builder is available to help configure your client configuration, you'll have to provide the API endpoint and an [API key](https://ipdata.co/pricing.html):
 ```java
+import io.ipdata.client.Ipdata;
+
+/.../
 URL url = new URL("https://api.ipdata.co");
 IpdataService ipdataService = Ipdata.builder().url(url)
-      .withDefaultCache()
       .key("MY_KEY").get();
-IpdataModel model = ipdataService.get("1.1.1.1"); //cache miss here
-ipdataService.get("1.1.1.1"); //cache hit from here on ip address "1.1.1.1"
+/.../
 ```
+Optionally, you can configure a cache for faster access (less than 1ms latency on requests that hit the cache). 
 
-3. My 50% user session length is 30 minutes, and I don't want to have more than 8 * 1024 items in cache, 
-how can I do that?
+The cache is configurable for time and space eviction policies:
 
 ```java
 URL url = new URL("https://api.ipdata.co");
 IpdataService ipdataService = Ipdata.builder().url(url)
       .withCache()
-        .timeout(30, TimeUnit.MINUTES)
-        .maxSize(8 * 1024)
+        .timeout(30, TimeUnit.MINUTES) //ttl after first write
+        .maxSize(8 * 1024) //no more than 8*1024 items shall be stored in cache
         .registerCacheConfig()
       .key("MY_KEY")
       .get();
-IpdataModel model = ipdataService.get("1.1.1.1"); //cache miss here
-ipdataService.get("1.1.1.1"); //cache hit from here on ip address "1.1.1.1"
+IpdataModel model = ipdataService.ipdata("1.1.1.1"); //cache miss here
+ipdataService.ipdata("1.1.1.1"); //cache hit from now on on ip address "1.1.1.1"
+```
+
+### API
+The client is fully compliant with the API. The data model of the api is available under the package ``io.ipdata.client.model``.
+Interaction with the API is captured by the Service Interface ``io.ipdata.client.service.IpdataService``:
+
+#### Basic Usage
+To get all available information about a given IP address, you can use the ``get`` method of the service Interface:
+```java
+IpdataModel model = ipdataService.ipdata("1.1.1.1");
+System.out.println(jsonSerialize(model));
 ```
 
+#### Single Field Selection
+If you're interested in only one field from the model capturing an IP address information, The service interface
+exposes some a method on each available field:
+
+```java
+boolean isEu = ipdataService.isEu("1.1.1.1");
+AsnModel asn = ipdataService.asn("1.1.1.1");
+TimeZone tz  = ipdataService.timeZone("1.1.1.1");
+ThreatModel threat = ipdataService.threat("1.1.1.1");
+/*...*/
+```
+The list of available fields is available [here](https://docs.ipdata.co/api-reference/response-fields)
+
+#### Multiple Field Selection
+If you're interested by multiple fields for a given IP address, you'll use the ``getFields`` method:
+```java
+import io.ipdata.client.service.IpdataField;
+import io.ipdata.client.service.IpdataService;
+
+/* The model will be hydrated by the selected fields only */
+IpdataModel model = ipdataService.getFields("1.1.1.1", IpdataField.ASN, IpdataField.CURRENCY);
+
+```
+
+### Bulk data
+You can as well get multiple responses at once by using the ``bulk`` api:
+
+```java
+List<IpdataModel> models = ipdataService.bulkIpdata(Arrays.asList("1.1.1.1", "8.8.8.8"));
+```
+
+
 

pom.groovy

@@ -27,6 +27,7 @@ project {
     'version.client.feign' '9.7.0'
     'version.build.jacoco' '0.8.4'
     'version.build.surefire' '3.0.0-M3'
+    'version.build.sonar' '3.7.0.1746'
     'sonar.organization' 'yassine-github'
     'sonar.coverage.jacoco.xmlReportPaths' '${project.build.directory}/site/code-coverage/jacoco.xml'
     'sonar.links.homepage' 'https://github.com/yassine/ipdata-java-client'
@@ -112,7 +113,7 @@ project {
           argLine '${surefireArgLine}'
         }
       }
-      plugin('org.codehaus.mojo:sonar-maven-plugin:3.6.0.1398')
+      plugin('org.codehaus.mojo:sonar-maven-plugin:${version.build.sonar}')
       plugin('org.apache.maven.plugins:maven-source-plugin:3.2.1') {
         executions {
           execution('attach-sources') {

src/main/java/io/ipdata/client/Ipdata.java

@@ -68,7 +68,7 @@ public Builder noCache(){
      */
     public Builder withDefaultCache() {
       return new CacheConfigBuilder(this)
-        .maxSize(Long.MAX_VALUE)
+        .maxSize(1024)
         .timeout(4, TimeUnit.HOURS)
         .registerCacheConfig();
     }

src/main/java/io/ipdata/client/service/IpdataInternalClient.java

@@ -13,7 +13,7 @@ interface IpdataInternalClient {
   IpdataModel ipdata(@Param("ip") String ip) throws IpdataException;
 
   @RequestLine("POST /bulk")
-  List<IpdataModel> bulkIpdata(List<String> ips) throws IpdataException;
+  List<IpdataModel> bulk(List<String> ips) throws IpdataException;
 
   @Cacheable
   @RequestLine("GET /{ip}?fields={fields}")

src/main/java/io/ipdata/client/service/IpdataService.java

@@ -9,9 +9,9 @@ public interface IpdataService extends IpdataInternalSingleFieldClient {
 
   IpdataModel ipdata(String ip) throws IpdataException;
 
-  List<IpdataModel> bulkIpdata(List<String> ips) throws IpdataException;
+  List<IpdataModel> bulk(List<String> ips) throws IpdataException;
 
-  IpdataModel[] bulkIpdataAsArray(List<String> ips) throws IpdataException;
+  IpdataModel[] bulkAsArray(List<String> ips) throws IpdataException;
 
   IpdataModel getFields(String ip, IpdataField<?>... fields) throws IpdataException;
 }

src/main/java/io/ipdata/client/service/IpdataServiceSupport.java

@@ -30,8 +30,8 @@ private IpdataInternalSingleFieldClient getApi() {
   }
 
   @Override
-  public IpdataModel[] bulkIpdataAsArray(List<String> ips) throws IpdataException {
-    return bulkIpdata(ips).toArray(new IpdataModel[0]);
+  public IpdataModel[] bulkAsArray(List<String> ips) throws IpdataException {
+    return bulk(ips).toArray(new IpdataModel[0]);
   }
 
   @Override

src/test/java/io/ipdata/client/IpdataFunctionalTest.java

@@ -135,7 +135,7 @@ public void testSingleFields() {
   @SneakyThrows
   @Test
   public void testBulkResponse() {
-    List<IpdataModel> ipdataModels = ipdataService.bulkIpdata(Arrays.asList("8.8.8.8", "1.1.1.1"));
+    List<IpdataModel> ipdataModels = ipdataService.bulk(Arrays.asList("8.8.8.8", "1.1.1.1"));
     String serialized = MAPPER.writeValueAsString(ipdataModels);
     String expected = TestUtils.post(HTTP_CLIENT, "/bulk", "[\"8.8.8.8\",\"1.1.1.1\"]", null);
     expected = MAPPER.writeValueAsString(MAPPER.readValue(expected, IpdataModel[].class));