Class WebServiceClient
- java.lang.Object
-
- com.maxmind.geoip2.WebServiceClient
-
- All Implemented Interfaces:
GeoIp2Provider
,Closeable
,AutoCloseable
public class WebServiceClient extends Object implements GeoIp2Provider, Closeable
The
WebServiceClient
class provides a client API for all the GeoIP2 Precision web service end points. The end points are Country, City, and Insights. Each end point returns a different set of data about an IP address, with Country returning the least data and Insights the most.Each web service end point is represented by a different model class, and these model classes in turn contain multiple Record classes. The record classes have attributes which contain data about the IP address.
If the web service does not return a particular piece of data for an IP address, the associated attribute is not populated.
The web service may not return any information for an entire record, in which case all of the attributes for that record class will be empty.
Usage
To use the web service API, you must create a new
WebServiceClient
using theWebServiceClient.Builder
. You must provide theBuilder
constructor your MaxMindaccountId
andlicenseKey
. You may also set atimeout
, specify a specifichost
, or set thelocales
fallback order using the methods on theBuilder
. After you have created theWebServiceClient
, you may then call the method corresponding to a specific end point, passing it the IP address you want to look up.If the request succeeds, the method call will return a model class for the end point you called. This model in turn contains multiple record classes, each of which represents part of the data returned by the web service.
If the request fails, the client class throws an exception.
The
WebServiceClient
object is safe to share across threads. If you are making multiple requests, the object should be reused so that new connections are not created for each request. Once you have finished making requests, you should close the object to ensure the connections are closed and any resources are promptly returned to the system.Exceptions
For details on the possible errors returned by the web service itself, see the GeoIP2 web service documentation.
If the web service returns an explicit error document, this is thrown as a
InvalidRequestException
. If some other sort of transport error occurs, this is thrown as aHttpException
. The difference is that the web service error includes an error message and error code delivered by the web service. The latter is thrown when some sort of unanticipated error occurs, such as the web service returning a 500 or an invalid error document.If the web service returns any status code besides 200, 4xx, or 5xx, this also becomes a
HttpException
.Finally, if the web service returns a 200 but the body is invalid, the client throws a
GeoIp2Exception
.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
WebServiceClient.Builder
Builder
creates instances ofWebServiceClient
from values set by the methods.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description CityResponse
city()
CityResponse
city(InetAddress ipAddress)
void
close()
Close any open connections and return resources to the system.CountryResponse
country()
CountryResponse
country(InetAddress ipAddress)
InsightsResponse
insights()
InsightsResponse
insights(InetAddress ipAddress)
String
toString()
-
-
-
Method Detail
-
country
public CountryResponse country() throws IOException, GeoIp2Exception
- Returns:
- A Country model for the requesting IP address
- Throws:
GeoIp2Exception
- if there is an error from the web serviceIOException
- if an IO error happens during the request
-
country
public CountryResponse country(InetAddress ipAddress) throws IOException, GeoIp2Exception
- Specified by:
country
in interfaceGeoIp2Provider
- Parameters:
ipAddress
- IPv4 or IPv6 address to lookup.- Returns:
- A Country model for the requested IP address.
- Throws:
IOException
- if there is an IO errorGeoIp2Exception
- if there is an error looking up the IP
-
city
public CityResponse city() throws IOException, GeoIp2Exception
- Returns:
- A City model for the requesting IP address
- Throws:
GeoIp2Exception
- if there is an error from the web serviceIOException
- if an IO error happens during the request
-
city
public CityResponse city(InetAddress ipAddress) throws IOException, GeoIp2Exception
- Specified by:
city
in interfaceGeoIp2Provider
- Parameters:
ipAddress
- IPv4 or IPv6 address to lookup.- Returns:
- A City model for the requested IP address.
- Throws:
IOException
- if there is an IO errorGeoIp2Exception
- if there is an error looking up the IP
-
insights
public InsightsResponse insights() throws IOException, GeoIp2Exception
- Returns:
- An Insights model for the requesting IP address
- Throws:
GeoIp2Exception
- if there is an error from the web serviceIOException
- if an IO error happens during the request
-
insights
public InsightsResponse insights(InetAddress ipAddress) throws IOException, GeoIp2Exception
- Parameters:
ipAddress
- IPv4 or IPv6 address to lookup.- Returns:
- A Insight model for the requested IP address.
- Throws:
GeoIp2Exception
- if there is an error looking up the IPIOException
- if there is an IO error
-
close
public void close() throws IOException
Close any open connections and return resources to the system.- Specified by:
close
in interfaceAutoCloseable
- Specified by:
close
in interfaceCloseable
- Throws:
IOException
-
-