mobi.mtld.da
Class Api

java.lang.Object
  mobi.mtld.da.Api

public class Api
extends java.lang.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("sample/DeviceAtlas.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 accessor)

Third-party Browsers

In some contexts, the user-agent you want to recognise 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: http://deviceatlas.com/resourcecentre/Knowledgebase/Opera+Detection

Author:

MTLD (dotMobi)

Constructor Summary

Api()

Method Summary

static int	getApiRevision() Returns the revision number of this API
static java.util.HashMap	getProperties(java.util.HashMap tree, java.lang.String userAgent) Returns a HashMap of known properties (as strings) for the user agent
static java.util.HashMap	getPropertiesAsTyped(java.util.HashMap tree, java.lang.String userAgent) Returns a HashMap of known properties (as typed) for the user agent
static java.lang.String	getProperty(java.util.HashMap tree, java.lang.String userAgent, java.lang.String property) Returns a value for the named property for this user agent
static boolean	getPropertyAsBoolean(java.util.HashMap tree, java.lang.String userAgent, java.lang.String property) Strongly typed property accessor.
static java.lang.String	getPropertyAsDate(java.util.HashMap tree, java.lang.String userAgent, java.lang.String property) Strongly typed property accessor.
static int	getPropertyAsInteger(java.util.HashMap tree, java.lang.String userAgent, java.lang.String property) Strongly typed property accessor.
static java.lang.String	getPropertyAsString(java.util.HashMap tree, java.lang.String userAgent, java.lang.String property) Strongly typed property accessor.
static java.util.HashMap	getTreeFromFile(java.lang.String filename) Returns a tree from a JSON file, If it has been previously loaded then the version from the static cache will be returned.
static java.util.HashMap	getTreeFromFile(java.lang.String filename, boolean reload) Returns a tree from a JSON file.
static java.util.HashMap	getTreeFromFile(java.lang.String filename, boolean reload, boolean includeChangeableUserAgentProperties) Returns a tree from a JSON file.
static java.util.HashMap	getTreeFromString(java.lang.String json) Returns a loaded JSON tree from a string of JSON data.
static java.util.HashMap	getTreeFromString(java.lang.String json, boolean includeChangeableUserAgentProperties) Returns a loaded JSON tree from a string of JSON data.
static java.lang.String	getTreeGeneration(java.util.HashMap tree) Get the generation date for this tree.
static int	getTreeGenerationAsTimestamp(java.util.HashMap tree) Get the generation date for this tree as a UNIX timestamp.
static int	getTreeRevision(java.util.HashMap tree) Returns the revision number of the tree
static java.util.HashMap	listProperties(java.util.HashMap tree) 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

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

Constructor Detail

Api

public Api()

Method Detail

getTreeFromString

public static java.util.HashMap getTreeFromString(java.lang.String json)
                                           throws JsonException

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 java.util.HashMap getTreeFromString(java.lang.String json,
                                                  boolean includeChangeableUserAgentProperties)
                                           throws JsonException

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 java.util.HashMap getTreeFromFile(java.lang.String filename)
                                         throws JsonException,
                                                java.io.IOException

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

java.io.IOException - There was an unknown error reading the JSON file

getTreeFromFile

public static java.util.HashMap getTreeFromFile(java.lang.String filename,
                                                boolean reload)
                                         throws JsonException,
                                                java.io.IOException

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

java.io.IOException - There was an unknown error reading the JSON file

getTreeFromFile

public static java.util.HashMap getTreeFromFile(java.lang.String filename,
                                                boolean reload,
                                                boolean includeChangeableUserAgentProperties)
                                         throws JsonException,
                                                java.io.IOException

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

java.io.IOException - There was an unknown error reading the JSON file

getTreeGeneration

public static java.lang.String getTreeGeneration(java.util.HashMap tree)

Get the generation date for this tree.

Parameters:

tree -

Returns:

The time/date the tree was generated.

getTreeGenerationAsTimestamp

public static int getTreeGenerationAsTimestamp(java.util.HashMap tree)

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()

Returns the revision number of this API

Returns:

integer revision

getTreeRevision

public static int getTreeRevision(java.util.HashMap tree)

Returns the revision number of the tree

Parameters:

tree - previously generated HashMap tree

Returns:

integer revision

listProperties

public static java.util.HashMap listProperties(java.util.HashMap tree)

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 java.util.HashMap getProperties(java.util.HashMap tree,
                                              java.lang.String userAgent)

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

Parameters:

tree - previously generated HashMap tree

userAgent - string from the device's User-Agent header

Returns:

HashMap properties

getPropertiesAsTyped

public static java.util.HashMap getPropertiesAsTyped(java.util.HashMap tree,
                                                     java.lang.String userAgent)

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

Parameters:

tree - previously generated HashMap tree

userAgent - string from the device's User-Agent header

Returns:

HashMap properties

getProperty

public static java.lang.String getProperty(java.util.HashMap tree,
                                           java.lang.String userAgent,
                                           java.lang.String property)
                                    throws InvalidPropertyException,
                                           UnknownPropertyException

Returns a value for the named property for this user agent

Parameters:

tree - previously generated HashMap tree

userAgent - string from the device's User-Agent header

property - the name of the property to return

Returns:

Object property

Throws:

InvalidPropertyException - See InvalidPropertyException

UnknownPropertyException - See UnknownPropertyException

getPropertyAsString

public static java.lang.String getPropertyAsString(java.util.HashMap tree,
                                                   java.lang.String userAgent,
                                                   java.lang.String property)
                                            throws IncorrectPropertyTypeException,
                                                   InvalidPropertyException,
                                                   UnknownPropertyException

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 - string from the device's User-Agent header

property - the name of the property to return

Returns:

String property

Throws:

IncorrectPropertyTypeException - See IncorrectPropertyTypeException

InvalidPropertyException - See InvalidPropertyException

UnknownPropertyException - See UnknownPropertyException

See Also:

getProperty(HashMap,String,String)

getPropertyAsBoolean

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

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 - string from the device's User-Agent header

property - the name of the property to return

Returns:

boolean property

Throws:

IncorrectPropertyTypeException - See IncorrectPropertyTypeException

InvalidPropertyException - See InvalidPropertyException

UnknownPropertyException - See UnknownPropertyException

See Also:

getProperty(HashMap,String,String)

getPropertyAsInteger

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

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 - string from the device's User-Agent header

property - the name of the property to return

Returns:

int property

Throws:

IncorrectPropertyTypeException - See IncorrectPropertyTypeException

InvalidPropertyException - See InvalidPropertyException

UnknownPropertyException - See UnknownPropertyException

See Also:

getProperty(HashMap,String,String)

getPropertyAsDate

public static java.lang.String getPropertyAsDate(java.util.HashMap tree,
                                                 java.lang.String userAgent,
                                                 java.lang.String property)
                                          throws IncorrectPropertyTypeException,
                                                 InvalidPropertyException,
                                                 UnknownPropertyException

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

Parameters:

tree - previously generated HashMap tree

userAgent - string from the device's User-Agent header

property - the name of the property to return

Returns:

String property

Throws:

IncorrectPropertyTypeException - See IncorrectPropertyTypeException

InvalidPropertyException - See InvalidPropertyException

UnknownPropertyException - See UnknownPropertyException

See Also:

getProperty(HashMap,String,String)