mobi.mtld.da

Class Api

java.lang.Object

mobi.mtld.da.Api

Deprecated.

This API is deprecated, it is highly recommended to use the new "mobi.mtld.da.device.DeviceApi" instead. See DeviceApi

public class Api
extends Object

Used to load the recognition tree and perform lookups of all properties, or get individual properties. Typical usage is as follows:

HashMap tree = Api.getTreeFromFile("data_file/sample.json");
HashMap prps = Api.getProperties(tree, "Nokia6680...");
Object prop = Api.getProperty(tree, "Nokia6680...", "displayWidth");

Note that you should normally use the user-agent that was received in the device's HTTP request. In a JSP environment, you would do this as follows:

String ua = request.getHeader("User-Agent");
int displayWidth = Api.getPropertyAsInteger(tree, ua, "displayWidth");

(Also note the use of the strongly typed property accessors)

Third-party Browsers

In some contexts, the user-agent you want to recognize may have been provided in a different header. Opera's mobile browser, for example, makes requests via an HTTP proxy, which rewrites the headers. in that case, the original device's user-agent is in the "X-OperaMini-Phone-UA" header, and the following code could be used:

 String ua;
 String operaHeader = "X-OperaMini-Phone-UA";
 if (request.getHeader(operaHeader) != null) {
     ua = request.getHeader(operaHeader);
 } else {
     ua = request.getHeader("User-Agent");
 }
 int displayWidth = Api.getPropertyAsInteger(tree, ua, "displayWidth");
 

See here for more information: https://deviceatlas.com/resources/side-loaded-browser-handling

Client side properties

Client side properties can be collected and merged into the results by using the DeviceAtlas Javascript detection file. The results from the client side are sent to the server inside a cookie. The contents of this cookie can be passed to the DeviceAtlas getProperty and getProperties methods. The client side properties over-ride any data file properties and also serve as an input into additional logic to determine other properties such as the iPhone models that are otherwise not detectable. The following code shows how this can be done in a JSP:

 String userAgent = request.getHeader("User-Agent");

 // get the cookie containing the client side properties
 String cookieContents = null;
 Cookie[] cookies = request.getCookies();
 if(cookies != null) {
   for(int i = 0; i < cookies.length; i++) { 
     Cookie cookie = cookies[i];
       if(cookie.getName().equals("DAPROPS")) {
         cookieContents = cookie.getValue();
       }
    }
 }

 HashMap properties = Api.getPropertiesAsTyped(tree, userAgent, cookieContents);
 

Author:

dotMobi

Constructor Summary

Constructors

Constructor and Description
Api() Deprecated.

Method Summary

Methods

Modifier and Type	Method and Description
static int	getApiRevision() Deprecated. Returns the revision number of this API
static HashMap	getProperties(HashMap tree, String userAgent) Deprecated. Returns a HashMap of known properties (as strings) for the user agent
static HashMap	getProperties(HashMap tree, String userAgent, String cookie) Deprecated. Returns a HashMap of known properties merged with properties from the client side JavaScript.
static HashMap	getPropertiesAsTyped(HashMap tree, String userAgent) Deprecated. Returns a HashMap of known properties (as typed) for the user agent
static HashMap	getPropertiesAsTyped(HashMap tree, String userAgent, String cookie) Deprecated. Returns a HashMap of known properties merged with properties from the client side JavaScript.
static String	getProperty(HashMap tree, String userAgent, String property) Deprecated. Returns a value for the named property for this user agent
static String	getProperty(HashMap tree, String userAgent, String cookie, String property) Deprecated. Returns a value for the named property for this user agent
static boolean	getPropertyAsBoolean(HashMap tree, String userAgent, String property) Deprecated. Strongly typed property accessor.
static boolean	getPropertyAsBoolean(HashMap tree, String userAgent, String cookie, String property) Deprecated. Strongly typed property accessor.
static String	getPropertyAsDate(HashMap tree, String userAgent, String property) Deprecated.
static String	getPropertyAsDate(HashMap tree, String userAgent, String cookie, String property) Deprecated.
static int	getPropertyAsInteger(HashMap tree, String userAgent, String property) Deprecated. Strongly typed property accessor.
static int	getPropertyAsInteger(HashMap tree, String userAgent, String cookie, String property) Deprecated. Strongly typed property accessor.
static String	getPropertyAsString(HashMap tree, String userAgent, String property) Deprecated. Strongly typed property accessor.
static String	getPropertyAsString(HashMap tree, String userAgent, String cookie, String property) Deprecated. Strongly typed property accessor.
static HashMap	getTreeFromFile(String filename) Deprecated. Returns a tree from a JSON file, If it has been previously loaded then the version from the static cache will be returned.
static HashMap	getTreeFromFile(String filename, boolean reload) Deprecated. Returns a tree from a JSON file.
static HashMap	getTreeFromFile(String filename, boolean reload, boolean includeChangeableUserAgentProperties) Deprecated. Returns a tree from a JSON file.
static HashMap	getTreeFromString(String json) Deprecated. Returns a loaded JSON tree from a string of JSON data.
static HashMap	getTreeFromString(String json, boolean includeChangeableUserAgentProperties) Deprecated. Returns a loaded JSON tree from a string of JSON data.
static String	getTreeGeneration(HashMap tree) Deprecated. Get the generation date for this tree.
static int	getTreeGenerationAsTimestamp(HashMap tree) Deprecated. Get the generation date for this tree as a UNIX timestamp.
static int	getTreeRevision(HashMap tree) Deprecated. Returns the revision number of the tree
static HashMap	listProperties(HashMap tree) Deprecated. Returns a HashMap of known property names available for the user agents in this file, with their data type names

Methods inherited from class java.lang.Object

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

Constructor Detail

Api

public Api()

Deprecated.

Method Detail

getTreeFromString

public static HashMap getTreeFromString(String json)
                                 throws JsonException

Deprecated.

Returns a loaded JSON tree from a string of JSON data. This will also initialise the changeable property recognition.

Some properties cannot be known before runtime and can change from user-agent to user-agent. The most common of these are the OS Version and the Browser Version. This API is able to dynamically detect these changing properties but introduces a small overhead to do so. To disable returning these extra properties call getTreeFromString() with includeChangeableUserAgentProperties set to false.

This method does not use the built in static cache.

Parameters:

json - The JSON HashMap object

Returns:

The loaded JSON tree

Throws:

JsonException

getTreeFromString

public static HashMap getTreeFromString(String json,
                        boolean includeChangeableUserAgentProperties)
                                 throws JsonException

Deprecated.

Returns a loaded JSON tree from a string of JSON data.

Some properties cannot be known before runtime and can change from user-agent to user-agent. The most common of these are the OS Version and the Browser Version. This API is able to dynamically detect these changing properties but introduces a small overhead to do so. To disable returning these extra properties set includeChangeableUserAgentProperties to false.

This method does not use the built in static cache.

Parameters:

json - The string of json data.

includeChangeableUserAgentProperties - Also detect changeable user-agent properties

Returns:

The loaded JSON tree

Throws:

JsonException - JsonException

getTreeFromFile

public static HashMap getTreeFromFile(String filename)
                               throws JsonException,
                                      IOException

Deprecated.

Returns a tree from a JSON file, If it has been previously loaded then the version from the static cache will be returned. To reload from file call getTreeFromFile() with reload set to true.

Some properties cannot be known before runtime and can change from user-agent to user-agent. The most common of these are the OS Version and the Browser Version. This API is able to dynamically detect these changing properties but introduces a small overhead to do so. To disable returning these extra properties set includeChangeableUserAgentProperties to false.

Parameters:

filename - the location of the file to read in. Use an absolute path name to be sure of success if the current working directory is not clear.

Returns:

HashMap The loaded JSON tree

Throws:

JsonException - JsonException

IOException - There was an unknown error reading the JSON file

getTreeFromFile

public static HashMap getTreeFromFile(String filename,
                      boolean reload)
                               throws JsonException,
                                      IOException

Deprecated.

Returns a tree from a JSON file. The loaded tree is stored in a static cache to avoid multiple reloads if this method is repeatedly called. To reload from the JSON file set reload to true.

Some properties cannot be known before runtime and can change from user-agent to user-agent. The most common of these are the OS Version and the Browser Version. This API is able to dynamically detect these changing properties but introduces a small overhead to do so. To disable returning these extra properties call getTreeFromFile() with includeChangeableUserAgentProperties set to false.

Parameters:

filename - the location of the file to read in. Use an absolute path name to be sure of success if the current working directory is not clear.

reload - set true to reload regardless of static cache

Returns:

HashMap The loaded JSON tree

Throws:

JsonException - JsonException

IOException - There was an unknown error reading the JSON file

getTreeFromFile

public static HashMap getTreeFromFile(String filename,
                      boolean reload,
                      boolean includeChangeableUserAgentProperties)
                               throws JsonException,
                                      IOException

Deprecated.

Returns a tree from a JSON file. The loaded tree is stored in a static cache to avoid multiple reloads if this method is repeatedly called. To reload from the JSON file set reload to true.

Some properties cannot be known before runtime and can change from user-agent to user-agent. The most common of these are the OS Version and the Browser Version. This API is able to dynamically detect these changing properties but introduces a small overhead to do so. To disable returning these extra properties set includeChangeableUserAgentProperties to false.

Parameters:

filename - the location of the file to read in. Use an absolute path name to be sure of success if the current working directory is not clear.

reload - set true to reload regardless of static cache

includeChangeableUserAgentProperties - Also detect changeable user-agent properties

Returns:

HashMap tree

Throws:

JsonException - JsonException

IOException - There was an unknown error reading the JSON file

getTreeGeneration

public static String getTreeGeneration(HashMap tree)

Deprecated.

Get the generation date for this tree.

Parameters:

tree -

Returns:

The time/date the tree was generated.

getTreeGenerationAsTimestamp

public static int getTreeGenerationAsTimestamp(HashMap tree)

Deprecated.

Get the generation date for this tree as a UNIX timestamp.

Parameters:

tree -

Returns:

The time/date the tree was generated.

getApiRevision

public static int getApiRevision()

Deprecated.

Returns the revision number of this API

Returns:

integer revision

getTreeRevision

public static int getTreeRevision(HashMap tree)

Deprecated.

Returns the revision number of the tree

Parameters:

tree - previously generated HashMap tree

Returns:

integer revision

listProperties

public static HashMap listProperties(HashMap tree)

Deprecated.

Returns a HashMap of known property names available for the user agents in this file, with their data type names

Parameters:

tree - previously generated HashMap tree

Returns:

HashMap properties

getProperties

public static HashMap getProperties(HashMap tree,
                    String userAgent)

Deprecated.

Returns a HashMap of known properties (as strings) for the user agent

Parameters:

tree - previously generated HashMap tree

userAgent - The device's User-Agent header string

Returns:

HashMap properties

getProperties

public static HashMap getProperties(HashMap tree,
                    String userAgent,
                    String cookie)
                             throws ClientPropertiesException

Deprecated.

Returns a HashMap of known properties merged with properties from the client side JavaScript. The client side JavaScript sets a cookie with collected properties. The contents of this cookie must be passed to this method for it to work. The client properties over-ride any properties discovered from the main JSON data file.

Parameters:

tree - previously generated HashMap tree

userAgent - the device's User-Agent header string

cookie - the contents of the cookie containing the client side properties

Returns:

HashMap a map of properties. Property name => Property value

Throws:

ClientPropertiesException - See ClientPropertiesException

getPropertiesAsTyped

public static HashMap getPropertiesAsTyped(HashMap tree,
                           String userAgent)

Deprecated.

Returns a HashMap of known properties (as typed) for the user agent

Parameters:

tree - previously generated HashMap tree

userAgent - the device's User-Agent header string

Returns:

HashMap a map of properties. Property name => Property value

getPropertiesAsTyped

public static HashMap getPropertiesAsTyped(HashMap tree,
                           String userAgent,
                           String cookie)
                                    throws ClientPropertiesException

Deprecated.

Returns a HashMap of known properties merged with properties from the client side JavaScript. The client side JavaScript sets a cookie with collected properties. The contents of this cookie must be passed to this method for it to work. The client properties over-ride any properties discovered from the main JSON data file.

Parameters:

tree - previously generated HashMap tree

userAgent - the device's User-Agent header string

cookie - the contents of the cookie containing the client side properties

Returns:

HashMap a map of properties. Property name => Property value

Throws:

ClientPropertiesException - See ClientPropertiesException

getProperty

public static String getProperty(HashMap tree,
                 String userAgent,
                 String property)
                          throws InvalidPropertyException,
                                 UnknownPropertyException

Deprecated.

Returns a value for the named property for this user agent

Parameters:

tree - previously generated HashMap tree

userAgent - the device's User-Agent header string

property - the name of the property to return

Returns:

Object property

Throws:

InvalidPropertyException - See InvalidPropertyException

UnknownPropertyException - See UnknownPropertyException

getProperty

public static String getProperty(HashMap tree,
                 String userAgent,
                 String cookie,
                 String property)
                          throws InvalidPropertyException,
                                 UnknownPropertyException,
                                 ClientPropertiesException

Deprecated.

Returns a value for the named property for this user agent

Parameters:

tree - previously generated HashMap tree

userAgent - the device's User-Agent header string

cookie - the contents of the cookie containing the client side properties

property - the name of the property to return

Returns:

Object property

Throws:

InvalidPropertyException - See InvalidPropertyException

UnknownPropertyException - See UnknownPropertyException

ClientPropertiesException

getPropertyAsString

public static String getPropertyAsString(HashMap tree,
                         String userAgent,
                         String property)
                                  throws IncorrectPropertyTypeException,
                                         InvalidPropertyException,
                                         UnknownPropertyException

Deprecated.

Strongly typed property accessor. Returns a string property (or throws an exception if the property is actually of another type)

Parameters:

tree - previously generated HashMap tree

userAgent - the device's User-Agent header string

property - the name of the property to return

Returns:

String property

Throws:

IncorrectPropertyTypeException - See IncorrectPropertyTypeException

InvalidPropertyException - See InvalidPropertyException

UnknownPropertyException - See UnknownPropertyException

ClientPropertiesException - See ClientPropertiesException

See Also:

getProperty(HashMap,String,String)

getPropertyAsString

public static String getPropertyAsString(HashMap tree,
                         String userAgent,
                         String cookie,
                         String property)
                                  throws IncorrectPropertyTypeException,
                                         InvalidPropertyException,
                                         UnknownPropertyException,
                                         ClientPropertiesException

Deprecated.

Strongly typed property accessor. Returns a string property (or throws an exception if the property is actually of another type)

Parameters:

tree - previously generated HashMap tree

userAgent - the device's User-Agent header string

cookie - the contents of the cookie containing the client side properties

property - the name of the property to return

Returns:

String property

Throws:

IncorrectPropertyTypeException - See IncorrectPropertyTypeException

InvalidPropertyException - See InvalidPropertyException

UnknownPropertyException - See UnknownPropertyException

ClientPropertiesException - See ClientPropertiesException

See Also:

getProperty(HashMap,String,String)

getPropertyAsBoolean

public static boolean getPropertyAsBoolean(HashMap tree,
                           String userAgent,
                           String property)
                                    throws IncorrectPropertyTypeException,
                                           InvalidPropertyException,
                                           UnknownPropertyException

Deprecated.

Strongly typed property accessor. Returns a boolean property (or throws an exception if the property is actually of another type)

Parameters:

tree - previously generated HashMap tree

userAgent - the device's User-Agent header string

property - the name of the property to return

Returns:

boolean property

Throws:

IncorrectPropertyTypeException - See IncorrectPropertyTypeException

InvalidPropertyException - See InvalidPropertyException

UnknownPropertyException - See UnknownPropertyException

ClientPropertiesException - See ClientPropertiesException

See Also:

getProperty(HashMap,String,String)

getPropertyAsBoolean

public static boolean getPropertyAsBoolean(HashMap tree,
                           String userAgent,
                           String cookie,
                           String property)
                                    throws IncorrectPropertyTypeException,
                                           InvalidPropertyException,
                                           UnknownPropertyException,
                                           ClientPropertiesException

Deprecated.

Strongly typed property accessor. Returns a boolean property (or throws an exception if the property is actually of another type)

Parameters:

tree - previously generated HashMap tree

userAgent - the device's User-Agent header string

cookie - the contents of the cookie containing the client side properties

property - the name of the property to return

Returns:

boolean property

Throws:

IncorrectPropertyTypeException - See IncorrectPropertyTypeException

InvalidPropertyException - See InvalidPropertyException

UnknownPropertyException - See UnknownPropertyException

ClientPropertiesException - See ClientPropertiesException

See Also:

getProperty(HashMap,String,String)

getPropertyAsInteger

public static int getPropertyAsInteger(HashMap tree,
                       String userAgent,
                       String property)
                                throws IncorrectPropertyTypeException,
                                       InvalidPropertyException,
                                       UnknownPropertyException

Deprecated.

Strongly typed property accessor. Returns an integer property (or throws an exception if the property is actually of another type)

Parameters:

tree - previously generated HashMap tree

userAgent - the device's User-Agent header string

property - the name of the property to return

Returns:

int property

Throws:

IncorrectPropertyTypeException - See IncorrectPropertyTypeException

InvalidPropertyException - See InvalidPropertyException

UnknownPropertyException - See UnknownPropertyException

ClientPropertiesException - See ClientPropertiesException

See Also:

getProperty(HashMap,String,String)

getPropertyAsInteger

public static int getPropertyAsInteger(HashMap tree,
                       String userAgent,
                       String cookie,
                       String property)
                                throws IncorrectPropertyTypeException,
                                       InvalidPropertyException,
                                       UnknownPropertyException,
                                       ClientPropertiesException

Deprecated.

Strongly typed property accessor. Returns an integer property (or throws an exception if the property is actually of another type)

Parameters:

tree - previously generated HashMap tree

userAgent - the device's User-Agent header string

cookie - the contents of the cookie containing the client side properties

property - the name of the property to return

Returns:

int property

Throws:

IncorrectPropertyTypeException - See IncorrectPropertyTypeException

InvalidPropertyException - See InvalidPropertyException

UnknownPropertyException - See UnknownPropertyException

ClientPropertiesException - See ClientPropertiesException

See Also:

getProperty(HashMap,String,String)

getPropertyAsDate

public static String getPropertyAsDate(HashMap tree,
                       String userAgent,
                       String property)
                                throws IncorrectPropertyTypeException,
                                       InvalidPropertyException,
                                       UnknownPropertyException

Deprecated.

Throws:

IncorrectPropertyTypeException

InvalidPropertyException

UnknownPropertyException

getPropertyAsDate

public static String getPropertyAsDate(HashMap tree,
                       String userAgent,
                       String cookie,
                       String property)
                                throws IncorrectPropertyTypeException,
                                       InvalidPropertyException,
                                       UnknownPropertyException,
                                       ClientPropertiesException

Deprecated.

Throws:

IncorrectPropertyTypeException

InvalidPropertyException

UnknownPropertyException

ClientPropertiesException