mobi.mtld.da.carrier

Class CarrierApi

java.lang.Object

mobi.mtld.da.carrier.CarrierApi

Direct Known Subclasses:

CarrierApiWeb

public class CarrierApi
extends java.lang.Object

The main class for the Carrier Detection API. Used to load the data file and to perform lookups using IPv4 addresses. For usage in a Web Container it is recommended to also include the CarrierApiWeb jar file as this facilitates passing a HttpRequest object.

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

Methods

Modifier and Type	Method and Description
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	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 ipv4) Get the Carrier properties for a given IP address.
Property	getProperty(java.util.Map keyVals, java.lang.String propertyName) Try and get a specific property for a given Map of HTTP Headers.
Property	getProperty(java.lang.String ipv4, java.lang.String propertyName) Try and get 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 input stream.

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 java.io.IOException,
                             DataFileException

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:

java.io.IOException - Thrown when there is a problem loading the file.

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

loadDataFromClassPath

public void loadDataFromClassPath(java.lang.String fileName)
                           throws java.io.IOException,
                                  DataFileException

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:

java.io.IOException - Thrown when there is a problem loading the file.

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

loadDataFromStream

public void loadDataFromStream(java.io.InputStream inputStream)
                        throws java.io.IOException,
                               DataFileException

Load the data from input stream.

Parameters:

inputStream - Input stream

Throws:

java.io.IOException - Thrown when there is a problem loading the file.

DataFileException - 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

getProperties

public Properties getProperties(java.lang.String ipv4)

Get the Carrier properties for a given IP address.

Parameters:

ipv4 - 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 name to HTTP header value. Both must be Strings.

Returns:

The found properties or null if no properties found.

getProperty

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

Try and get 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 than repeated calls to getProperty().

Parameters:

ipv4 - 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 and get 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 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:

ip - The IP address to check

Returns:

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