com.deviceatlas.carrier

Class CarrierApi

java.lang.Object

com.deviceatlas.BaseDeviceAtlasApi

com.deviceatlas.carrier.CarrierApi

All Implemented Interfaces:

DeviceAtlasApi

Direct Known Subclasses:

CarrierApiWeb

public class CarrierApi
extends BaseDeviceAtlasApi

The main class for the Carrier Detection API. Used to load the data file and perform lookups using IPv4 and IPv6 addresses. If you want to use the DeviceAtlas Carrier API in a servlet container then it is strongly recommended to use CarrierApiWeb instead of this library.

Please note that it is advisable to load only a single instance of this class to avoid multiple loadings of the data file. This can be done in a Web Container by storing a reference to it in the ServletContext.

Example usage:

     String ip = "62.40.34.220";
     CarrierApi carrierApi = new CarrierApi();
     carrierApi.loadDataFromFile("/path/to/sample.dat");

     // get all properties
     Properties props = carrierApi.getProperties(ip);
     // .... use the properties ....
     if (props.containsKey("networkOperator"))  {
         Property property = (Property)props.get("networkOperator");
         String operatorName = property.asString();
         System.out.println("networkOperator: "+operatorName);
     }

     // get a single property
     Property mccProp = carrierApi.getProperty(ip, "mcc");
     if (mccProp != null) {
         String mcc = mccProp.asString();
         System.out.println("MCC: " + mcc);
     }
 

Please see the code in the Examples directory for additional samples.

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String[]	HEADERS_TO_CHECK A list of HTTP headers to choose the original client IP address from.

Constructor Summary

Constructors

Constructor and Description
CarrierApi()

Method Summary

Modifier and Type	Method and Description
static java.lang.String	getApiVersion() Returns the version of the Carrier API.
java.lang.String	getDataFileCopyright() Returns the data file copyright text.
java.lang.String	getDataFileCreationDate() Returns the data file creation date in ISO8601 format.
java.lang.String	getDataFileVersion() Returns the version of the data file.
java.lang.String	getDeviceAtlasApiVersion()
java.lang.String	getIp(java.util.Map keyVals) Get the most suitable IP address from the given keyVals set of HTTP headers.
Properties	getProperties(java.util.Map keyVals) Get the Carrier properties for a given Map of HTTP Headers.
Properties	getProperties(java.lang.String ip) Get the Carrier properties for a given IP address.
Property	getProperty(java.util.Map keyVals, java.lang.String propertyName) Try to obtain a specific property for a given Map of HTTP Headers.
Property	getProperty(java.lang.String ip, java.lang.String propertyName) Try to obtain a specific property for a given IP address.
java.util.Set	getPropertyNames() A Set of all the possible property names.
static boolean	isPublicIp(java.lang.String ipStr) An IP address is considered public if it is not in any of the following ranges:
void	loadDataFromClassPath(java.lang.String fileName) Load the data file from the class path.
void	loadDataFromFile(java.lang.String path) Load the data file from the provided path.
void	loadDataFromStream(java.io.InputStream inputStream) Load the data from an input stream.

Methods inherited from class com.deviceatlas.BaseDeviceAtlasApi

downloadAndLoadDataFile, downloadAndLoadDataFile, getDetectionLookupCount, isDataFileReload, resetDetectionLookupCount

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

HEADERS_TO_CHECK

public static final java.lang.String[] HEADERS_TO_CHECK

A list of HTTP headers to choose the original client IP address from. In addition to these the RemoteAddr (REMOTE_ADDR) is also used as a final fallback.

Constructor Detail

CarrierApi

public CarrierApi()

Method Detail

loadDataFromFile

public void loadDataFromFile(java.lang.String path)
                      throws DataLoadingException

Load the data file from the provided path. The data file is reloaded every time this method is called.

Parameters:

path - The path on disk to the data file.

Throws:

DataLoadingException - thrown when there is a problem with the data file.

loadDataFromClassPath

public void loadDataFromClassPath(java.lang.String fileName)
                           throws DataLoadingException

Load the data file from the class path. The data file is reloaded every time this method is called.

Parameters:

fileName - The name of the file on the class path

Throws:

DataLoadingException - thrown when there is a problem with the data file.

loadDataFromStream

public void loadDataFromStream(java.io.InputStream inputStream)
                        throws DataLoadingException

Load the data from an input stream.

Parameters:

inputStream - Input stream

Throws:

DataLoadingException - thrown when there is a problem with the data file.

getDataFileCopyright

public java.lang.String getDataFileCopyright()

Returns the data file copyright text.

Returns:

the copyright

getDataFileCreationDate

public java.lang.String getDataFileCreationDate()

Returns the data file creation date in ISO8601 format.

Returns:

the creationDate

getDataFileVersion

public java.lang.String getDataFileVersion()

Returns the version of the data file.

Returns:

the version

getApiVersion

public static java.lang.String getApiVersion()

Returns the version of the Carrier API.

Returns:

the Carrier API version

getProperties

public Properties getProperties(java.lang.String ip)

Get the Carrier properties for a given IP address.

Parameters:

ip - The IP address to find carrier properties for.

Returns:

The found properties or null if no properties found.

getProperties

public Properties getProperties(java.util.Map keyVals)

Get the Carrier properties for a given Map of HTTP Headers. The API will choose the most appropriate IP to use.

The following headers are checked in order to find the most suitable IP address.

• X-Forwarded-For
• Client-Ip
• X-Client-Ip
• rlnClientIpAddr
• Proxy-Client-Ip
• Wl-Proxy-Client-Ip
• X-Forwarded
• Forwarded-For
• Forwarded

Parameters:

keyVals - A map of HTTP header names to HTTP header values. Both must be Strings.

Returns:

The found properties or null if no properties found.

getProperty

public Property getProperty(java.lang.String ip,
                            java.lang.String propertyName)
                     throws InvalidPropertyNameException

Try to obtain a specific property for a given IP address.

Note: if multiple properties are needed for the same IP it is more efficient to call getProperties() once rather than repeated calls to getProperty().

Parameters:

ip - The IP address to find carrier properties for.

propertyName - The name of the property to return

Returns:

The Property or null if no property found.

Throws:

InvalidPropertyNameException - Thrown if the property name does not exist.

getProperty

public Property getProperty(java.util.Map keyVals,
                            java.lang.String propertyName)
                     throws InvalidPropertyNameException

Try to obtain a specific property for a given Map of HTTP Headers. The API will choose the most appropriate IP to use.

Note: if multiple properties are needed for the same IP it is more efficient to call getProperties() once rather than repeated calls to getProperty().

Parameters:

keyVals - A map of HTTP header name to HTTP header value. Both must be Strings.

propertyName - The name of the property to return

Returns:

The Property or null if no property found.

Throws:

InvalidPropertyNameException - Thrown if the property name does not exist.

getPropertyNames

public java.util.Set getPropertyNames()

A Set of all the possible property names. The Set contains PropertyName objects that each have a String name and an associated data type.

Returns:

A Set of property names

getIp

public java.lang.String getIp(java.util.Map keyVals)

Get the most suitable IP address from the given keyVals set of HTTP headers. This function checks the headers defined in HEADERS_TO_CHECK.

Parameters:

keyVals - A map of HTTP header name to HTTP header value

Returns:

The most suitable IP or NULL if a suitable IP could not be found.

isPublicIp

public static boolean isPublicIp(java.lang.String ipStr)

An IP address is considered public if it is not in any of the following ranges:

  1) any local address
     IP:  0

  2) a local loopback address
     range:  127/8

  3) a site local address i.e. IP is in any of the ranges:
     range:  10/8
     range:  172.16/12
     range:  192.168/16

  4) a link local address
     range:  169.254/16
 

Parameters:

ipStr - The IP address to check

Returns:

True if it is a public IP, false if the IP is invalid or is not public.

getDeviceAtlasApiVersion

public java.lang.String getDeviceAtlasApiVersion()