Merge pull request #18 from maxmind/greg/ws-v2.1

Greg/ws v2.1

Author: autarch

CHANGELOG.md

@@ -1,6 +1,15 @@
 CHANGELOG
 =========
 
+0.8.0 (2014-07-XX)
+------------------
+
+* The web service client API has been updated for the v2.1 release of the web
+  service. In particular, the `cityIspOrg` and `omni` methods on
+  `WebServiceClient` have been deprecated. The `city` method now provides all
+  of the data formerly provided by `cityIspOrg`, and the `omni` method has
+  been replaced by the `insights` method.
+
 0.7.2 (2014-06-02)
 ------------------
 

README.md

@@ -12,7 +12,7 @@ website](http://www.maxmind.com/en/geoip2_beta).
 
 ## Description ##
 
-This distribution provides an API for the GeoIP2 [web services]
+This distribution provides an API for the GeoIP2 [Precision web services]
 (http://dev.maxmind.com/geoip/geoip2/web-services) and [databases]
 (http://dev.maxmind.com/geoip/geoip2/downloadable). The API also works with
 the free [GeoLite2 databases](http://dev.maxmind.com/geoip/geoip2/geolite2/).
@@ -28,7 +28,7 @@ To do this, add the dependency to your pom.xml:
     <dependency>
         <groupId>com.maxmind.geoip2</groupId>
         <artifactId>geoip2</artifactId>
-        <version>0.7.2</version>
+        <version>0.8.0-SNAPSHOT</version>
     </dependency>
 ```
 
@@ -56,9 +56,9 @@ See the API documentation for more details.
 // Replace "42" with your user ID and "license_key" with your license key.
 WebServiceClient client = new WebServiceClient.Builder(42, "license_key").build();
 
-// Replace "omni" with the method corresponding to the web service that
-// you are using, e.g., "country", "cityIspOrg", "city".
-OmniResponse response = client.omni(InetAddress.getByName("128.101.101.101"));
+// Replace "city" with the method corresponding to the web service that
+// you are using, e.g., "country" or "insights".
+CityResponse response = client.city(InetAddress.getByName("128.101.101.101"));
 
 System.out.println(response.getCountry().getIsoCode()); // 'US'
 System.out.println(response.getCountry().getName()); // 'United States'
@@ -87,7 +87,7 @@ appropriate method (e.g., `city`) for your database, passing it the IP address
 you want to look up.
 
 If the lookup succeeds, the method call will return a response class for the
-GeoIP lookup. The class in turn contains multiple record classes, each of
+GeoIP2 lookup. The class in turn contains multiple record classes, each of
 which represents part of the data returned by the database.
 
 We recommend reusing the `DatabaseReader` object rather than creating a new
@@ -192,7 +192,8 @@ System.out.println(response.getOrganization()); // 'University of Minnesota'
 ## Exceptions ##
 
 For details on the possible errors returned by the web service itself, [see
-the GeoIP2 web service documentation](http://dev.maxmind.com/geoip2/geoip/web-services).
+the GeoIP2 Precision web service
+documentation](http://dev.maxmind.com/geoip2/geoip/web-services).
 
 If the web service returns an explicit error document, this is thrown as an
 `AddressNotFoundException`, an `AuthenticationException`, an

pom.xml

@@ -3,10 +3,10 @@
     <modelVersion>4.0.0</modelVersion>
     <groupId>com.maxmind.geoip2</groupId>
     <artifactId>geoip2</artifactId>
-    <version>0.7.3-SNAPSHOT</version>
+    <version>0.8.0-SNAPSHOT</version>
     <packaging>jar</packaging>
     <name>MaxMind GeoIP2 API</name>
-    <description>API for accessing MaxMind's GeoIP2 web service</description>
+    <description>GeoIP2 webservice client and database reader</description>
     <url>http://dev.maxmind.com/geoip/geoip2/web-services</url>
     <licenses>
         <license>

src/main/java/com/maxmind/geoip2/DatabaseReader.java

@@ -16,13 +16,7 @@
 import com.maxmind.db.Reader.FileMode;
 import com.maxmind.geoip2.exception.AddressNotFoundException;
 import com.maxmind.geoip2.exception.GeoIp2Exception;
-import com.maxmind.geoip2.model.CityIspOrgResponse;
-import com.maxmind.geoip2.model.CityResponse;
-import com.maxmind.geoip2.model.ConnectionTypeResponse;
-import com.maxmind.geoip2.model.CountryResponse;
-import com.maxmind.geoip2.model.DomainResponse;
-import com.maxmind.geoip2.model.IspResponse;
-import com.maxmind.geoip2.model.OmniResponse;
+import com.maxmind.geoip2.model.*;
 
 /**
  * Instances of this class provide a reader for the GeoIP2 database format. IP
@@ -193,18 +187,28 @@ public CityResponse city(InetAddress ipAddress) throws IOException,
         return this.get(ipAddress, CityResponse.class);
     }
 
+
+    @SuppressWarnings("deprecation")
     @Override
+    @Deprecated
     public CityIspOrgResponse cityIspOrg(InetAddress ipAddress)
             throws IOException, GeoIp2Exception {
         return this.get(ipAddress, CityIspOrgResponse.class);
     }
 
+    @SuppressWarnings("deprecation")
     @Override
+    @Deprecated
     public OmniResponse omni(InetAddress ipAddress) throws IOException,
             GeoIp2Exception {
         return this.get(ipAddress, OmniResponse.class);
     }
 
+    public InsightsResponse insights(InetAddress ipAddress) throws IOException,
+    GeoIp2Exception {
+            return this.get(ipAddress, InsightsResponse.class);
+}
+
     public ConnectionTypeResponse connectionType(InetAddress ipAddress)
             throws IOException, GeoIp2Exception {
         return this.get(ipAddress, ConnectionTypeResponse.class, false);

src/main/java/com/maxmind/geoip2/GeoIp2Provider.java

@@ -9,6 +9,7 @@
 import com.maxmind.geoip2.model.CountryResponse;
 import com.maxmind.geoip2.model.OmniResponse;
 
+@SuppressWarnings("deprecation")
 public interface GeoIp2Provider {
 
     /**
@@ -43,7 +44,10 @@ public CityResponse city(InetAddress ipAddress) throws IOException,
      *             if there is an error looking up the IP
      * @throws IOException
      *             if there is an IO error
+     *
+     * @deprecated As of 0.8.0, this has been replaced by {@link #city(InetAddress)}.
      */
+    @Deprecated
     public CityIspOrgResponse cityIspOrg(InetAddress ipAddress)
             throws IOException, GeoIp2Exception;
 
@@ -55,7 +59,10 @@ public CityIspOrgResponse cityIspOrg(InetAddress ipAddress)
      *             if there is an error looking up the IP
      * @throws IOException
      *             if there is an IO error
+     *
+     * @deprecated As of 0.8.0, use {@link WebServiceClient#insights(InetAddress)} instead.
      */
+    @Deprecated
     public OmniResponse omni(InetAddress ipAddress) throws IOException,
             GeoIp2Exception;
 }

src/main/java/com/maxmind/geoip2/WebServiceClient.java

@@ -11,31 +11,17 @@
 import com.fasterxml.jackson.databind.DeserializationFeature;
 import com.fasterxml.jackson.databind.InjectableValues;
 import com.fasterxml.jackson.databind.ObjectMapper;
-import com.google.api.client.http.GenericUrl;
-import com.google.api.client.http.HttpHeaders;
-import com.google.api.client.http.HttpRequest;
-import com.google.api.client.http.HttpRequestFactory;
-import com.google.api.client.http.HttpResponse;
-import com.google.api.client.http.HttpResponseException;
-import com.google.api.client.http.HttpTransport;
+import com.google.api.client.http.*;
 import com.google.api.client.http.javanet.NetHttpTransport;
-import com.maxmind.geoip2.exception.AddressNotFoundException;
-import com.maxmind.geoip2.exception.AuthenticationException;
-import com.maxmind.geoip2.exception.GeoIp2Exception;
-import com.maxmind.geoip2.exception.HttpException;
-import com.maxmind.geoip2.exception.InvalidRequestException;
-import com.maxmind.geoip2.exception.OutOfQueriesException;
-import com.maxmind.geoip2.model.CityIspOrgResponse;
-import com.maxmind.geoip2.model.CityResponse;
-import com.maxmind.geoip2.model.CountryResponse;
-import com.maxmind.geoip2.model.OmniResponse;
+import com.maxmind.geoip2.exception.*;
+import com.maxmind.geoip2.model.*;
 
 /**
  * <p>
- * This class provides a client API for all the GeoIP2 web service's end points.
- * The end points are Country, City, City/ISP/Org, and Omni. Each end point
+ * This class provides a client API for all the GeoIP2 Precision web service end points.
+ * The end points are Country and Insights. Each end point
  * returns a different set of data about an IP address, with Country returning
- * the least data and Omni the most.
+ * the least data and Insights the most.
  * </p>
  *
  * <p>
@@ -241,33 +227,71 @@ public CityResponse city(InetAddress ipAddress) throws IOException,
      *             if there is an error from the web service
      * @throws IOException
      *             if an IO error happens during the request
+     *
+     * @deprecated As of 0.8.0, use {@link #city()} instead.
      */
+@SuppressWarnings("deprecation")
+@Deprecated
     public CityIspOrgResponse cityIspOrg() throws IOException, GeoIp2Exception {
         return this.cityIspOrg(null);
     }
 
+    @SuppressWarnings("deprecation")
+    @Deprecated
     @Override
     public CityIspOrgResponse cityIspOrg(InetAddress ipAddress)
             throws IOException, GeoIp2Exception {
-        return this.responseFor("city_isp_org", ipAddress,
+        return this.responseFor("city", ipAddress,
                 CityIspOrgResponse.class);
     }
 
+    /**
+     * @return An Insights model for the requesting IP address
+     * @throws GeoIp2Exception
+     *             if there is an error from the web service
+     * @throws IOException
+     *             if an IO error happens during the request
+     */
+    public InsightsResponse insights() throws IOException, GeoIp2Exception {
+        return this.insights(null);
+    }
+
+
+    /**
+     * @param ipAddress
+     *            IPv4 or IPv6 address to lookup.
+     * @return A Insight model for the requested IP address.
+     * @throws GeoIp2Exception
+     *             if there is an error looking up the IP
+     * @throws IOException
+     *             if there is an IO error
+     */
+    public InsightsResponse insights(InetAddress ipAddress) throws IOException,
+            GeoIp2Exception {
+        return this.responseFor("insights", ipAddress, InsightsResponse.class);
+    }
+
     /**
      * @return An Omni model for the requesting IP address
      * @throws GeoIp2Exception
      *             if there is an error from the web service
      * @throws IOException
      *             if an IO error happens during the request
+     *
+     * @deprecated As of 0.8.0, use {@link #insights()} instead.
      */
+    @SuppressWarnings("deprecation")
+    @Deprecated
     public OmniResponse omni() throws IOException, GeoIp2Exception {
         return this.omni(null);
     }
 
+    @SuppressWarnings("deprecation")
+    @Deprecated
     @Override
     public OmniResponse omni(InetAddress ipAddress) throws IOException,
             GeoIp2Exception {
-        return this.responseFor("omni", ipAddress, OmniResponse.class);
+        return this.responseFor("insights", ipAddress, OmniResponse.class);
     }
 
     private <T> T responseFor(String path, InetAddress ipAddress, Class<T> cls)
@@ -408,7 +432,7 @@ private static void handleErrorWithJsonBody(Map<String, String> content,
     }
 
     private GenericUrl createUri(String path, InetAddress ipAddress) {
-        return new GenericUrl("https://" + this.host + "/geoip/v2.0/" + path
+        return new GenericUrl("https://" + this.host + "/geoip/v2.1/" + path
                 + "/" + (ipAddress == null ? "me" : ipAddress.getHostAddress()));
 
     }

src/main/java/com/maxmind/geoip2/model/CityIspOrgResponse.java

@@ -1,15 +1,18 @@
 package com.maxmind.geoip2.model;
 
 /**
- * This class provides a model for the data returned by the GeoIP2 City/ISP/Org
- * end point.
+ * This class provides a model for the data returned by the GeoIP2 Precision:
+ * City end point.
  *
- * The only difference between the City, City/ISP/Org, and Omni model classes is
+ * The only difference between the City and Insights model classes is
  * which fields in each record may be populated.
  *
  * @see <a href="http://dev.maxmind.com/geoip/geoip2/web-services">GeoIP2 Web
  *      Services</a>
+ *
+ * @deprecated As of 0.8.0, this has been replaced by {@link CityResponse}.
  */
+@Deprecated
 final public class CityIspOrgResponse extends AbstractCityResponse {
     public CityIspOrgResponse() {
     }

src/main/java/com/maxmind/geoip2/model/CityResponse.java

@@ -1,10 +1,10 @@
 package com.maxmind.geoip2.model;
 
 /**
- * This class provides a model for the data returned by the GeoIP2 City end
- * point.
+ * This class provides a model for the data returned by the GeoIP2 Precision:
+ * City end point.
  *
- * The only difference between the City, City/ISP/Org, and Omni model classes is
+ * The only difference between the City and Insights model classes is
  * which fields in each record may be populated.
  *
  * @see <a href="http://dev.maxmind.com/geoip/geoip2/web-services">GeoIP2 Web

src/main/java/com/maxmind/geoip2/model/CountryResponse.java

@@ -1,11 +1,8 @@
 package com.maxmind.geoip2.model;
 
 /**
- * This class provides a model for the data returned by the GeoIP2 Country end
- * point.
- *
- * The only difference between the City, City/ISP/Org, and Omni model classes is
- * which fields in each record may be populated.
+ * This class provides a model for the data returned by the GeoIP2 Precision:
+ * Country end point.
  *
  * @see <a href="http://dev.maxmind.com/geoip/geoip2/web-services">GeoIP2 Web
  *      Services</a>

src/main/java/com/maxmind/geoip2/model/InsightsResponse.java

@@ -0,0 +1,16 @@
+package com.maxmind.geoip2.model;
+
+/**
+ * This class provides a model for the data returned by the GeoIP2 Precision:
+ * Insights end point.
+ *
+ * The only difference between the City and Insights model classes is
+ * which fields in each record may be populated.
+ *
+ * @see <a href="http://dev.maxmind.com/geoip/geoip2/web-services">GeoIP2 Web
+ *      Services</a>
+ */
+final public class InsightsResponse extends AbstractCityResponse {
+    public InsightsResponse() {
+    }
+}