Package com.deviceatlas.cloud.deviceidentification.client

Class Client

  • public class Client
extends java.lang.Object
    DeviceAtlas Cloud API. This client library can be used to easily get device data from the DeviceAtlas Cloud service. To reduce cloud calls and improve performance the API locally caches the data returned from the cloud service. The client is queried by passing either an HttpServletRequest object or a collection of HTTP headers to it or a user-agent string. The device properties will then be returned.

    Example 1:
    Using the Request object from the app container. 
     // HttpServletRequest request: Request object from Servlet container
 first use
 Client client = Client.getInstance(CacheProvider);
 following use
 Client client = Client.getInstance();
 client.setLicenceKey("DeviceAtlas-licence-key");
 try {
     Result results = client.getResult(request);
 } catch (Exception x) { // handle exceptions etc... }
 // The useragent used in the lookup
 String ua = results.getHeaders().get(ClientConstants.KEY_USERAGENT.toString());
 // The source of the data - cache, cloud etc
 String dataSource = results.getSource();
 // The actual device properties
 Properties properties = results.getProperties();

    Example 2:
    Passing a custom list of HTTP headers. This can be useful if the app is not under a servlet container. 
     Map  headers = new HashMap();
 // get data by passing headers (headers named are not case sensitive and may include  "_" or start with "HTTP_")
 headers.put("User-Agent", "Mozilla/5.0 (SymbianOS/9.2; U; Series60/3.1 NokiaN95_8GB/15.0.015; Profile/MIDP-2.0 Configuration/CLDC-1.1 ) AppleWebKit/413 (KHTML, like Gecko) Safari/413");
 headers.put("X-Profile", "http://nds.nokia.com/uaprof/NN95_8GB-1r100.xml");
 headers.put("Accept", "text/html,text/css,multipart/mixed,application/java-archive, application/java");
 headers.put("Accept-Language", "en-us,en;q=0.5");
 Client client = Client.getInstance();
 try {
     Result results = client.getResultByHeaders(headers);
 } catch (Exception x) { // handle exceptions etc... }
 // The useragent used in the lookup
 String ua = results.getHeaders().get(ClientConstants.KEY_USERAGENT.toString());
 // The source of the data - cache, cloud etc
 String dataSource = results.getSource();
 // The actual device properties
 Properties properties = results.getProperties();

    Example 3:
    Passing a user-agent. This can be useful if the app is not under a servlet container. 
     Client client = Client.getInstance();
 String ua = "Mozilla/5.0 (SymbianOS/9.2; U; Series60/3.1 NokiaN95_8GB/15.0.015; Profile/MIDP-2.0 Configuration/CLDC-1.1 ) AppleWebKit/413 (KHTML, like Gecko) Safari/413";
 try {
     Result results = client.getResultByUserAgent(ua);
 } catch (Exception x) { // handle exceptions etc... }
 // The useragent used in the lookup
 String ua = results.getHeaders().get(ClientConstants.KEY_USERAGENT.toString()));
 // The source of the data - cache, cloud etc
 String dataSource = results.getSource();
 // The actual device properties
 Properties properties = results.getProperties();
    Copyright (c) DeviceAtlas Limited 2023. All Rights Reserved.

    • Field Detail

      • API_VERSION

        @Deprecated
public static final java.lang.String API_VERSION
        Deprecated.
        Please see ClientConstants.API_VERSION.toString()

      • CLIENT_COOKIE_NAME

        @Deprecated
public static final java.lang.String CLIENT_COOKIE_NAME
        Deprecated.
        Please see ClientConstants.CLIENT_COOKIE_NAME.toString()

      • KEY_USERAGENT

        @Deprecated
public static final java.lang.String KEY_USERAGENT
        Deprecated.
        Please see ClientConstants.KEY_USERAGENT.toString()

      • KEY_SOURCE

        @Deprecated
public static final java.lang.String KEY_SOURCE
        Deprecated.
        Please see ClientConstants.KEY_SOURCE.toString()

      • KEY_PROPERTIES

        @Deprecated
public static final java.lang.String KEY_PROPERTIES
        Deprecated.
        Please see ClientConstants.KEY_PROPERTIES.toString()

      • SOURCE_CACHE

        @Deprecated
public static final java.lang.String SOURCE_CACHE
        Deprecated.
        Please see ClientConstants.SOURCE_CACHE.toString()

      • SOURCE_CLOUD

        @Deprecated
public static final java.lang.String SOURCE_CLOUD
        Deprecated.
        Please see ClientConstants.SOURCE_CLOUD.toString()

      • SOURCE_NONE

        @Deprecated
public static final java.lang.String SOURCE_NONE
        Deprecated.
        Please see ClientConstants.SOURCE_NONE.toString()

      • DA_HEADER_PREFIX

        @Deprecated
public static final java.lang.String DA_HEADER_PREFIX
        Deprecated.
        Please see HeaderConstants.DA_HEADER_PREFIX.toString()

      • CLIENT_COOKIE_HEADER

        @Deprecated
public static final java.lang.String CLIENT_COOKIE_HEADER
        Deprecated.
        Please see HeaderConstants.CLIENT_COOKIE_HEADER.toString()

    • Method Detail

      • getInstance

        public static Client getInstance​(CacheService cacheService)
                          throws CacheException
        Get the instance for the Client
        Parameters:
        cacheService - CacheService object with the cache provider
        Returns:
        The instance of the Client
        Throws:
        CacheException - This occurs if the Cache could not be initialized properly.

      • getInstance

        public static Client getInstance​(CacheProvider cacheProvider)
                          throws CacheException
        Get the instance for the Client
        Parameters:
        cacheProvider - CacheProvider object with the cache provider
        Returns:
        The instance of the Client
        Throws:
        CacheException - This occurs if the Cache could not be initialized properly.

      • getCloudUrl

        public java.lang.String getCloudUrl()
        Get the last DeviceAtlas cloud service end-point (server) URL called to get device properties
        Returns:
        null or a URL. Null means no call to a DeviceAtlas cloud end-point was done probably because the data was fetched from cache.

      • setCloudUrl

        public void setCloudUrl​(java.lang.String lastUsedCloudUrl)
        Sets the last endpoint url used when call the service
        Parameters:
        lastUsedCloudUrl -

      • getRankingStatus

        public java.lang.String getRankingStatus()

      • getEndPoints

        public EndPoint[] getEndPoints()
                        throws ClientException
        Getter for cloud server list. The end-points in the returned array are used for making DeviceAtlas cloud calls. The top end-point will most likely be used unless it fails and the call falls to the next end-point and so on.
        Returns:
        An array of EndPoint objects (each object is a DeviceAtlas cloud end-point)
        Throws:
        ClientException - when an exception from the Cloud instance side appears
        CacheException - when cache fails to be written

      • setEndPoints

        public void setEndPoints​(EndPoint[] endPoints)
        Setter for cloud server list. To set DeviceAtlas cloud end-points manually. The order of this array matters. While healthy the top end-point will be used.
        Parameters:
        endPoints - An array of EndPoint objects, each object is a DeviceAtlas cloud end-point

      • getAutoServerRanking

        public boolean getAutoServerRanking()
        Getter for auto server ranking.
        Returns:
        true = the API will auto rank DeviceAtlas end-points. false = the default built-in DeviceAtlas end-points array or one provided manually will be used by the API.

      • setAutoServerRanking

        public void setAutoServerRanking​(boolean autoServerRanking)
        Setter for auto server ranking.
        Parameters:
        autoServerRanking - true = the API must auto rank DeviceAtlas end-points. false = the API should use the built-in EndPoint array or one which is provided to it.

      • getCloudServiceTimeout

        public int getCloudServiceTimeout()
        Getter for cloud service timeout. If the API requests service from a DeviceAtlas end-point, shall the end-point not response in this amount of time the next end-point in the list will be used.
        Returns:
        Time in seconds.

      • setCloudServiceTimeout

        public void setCloudServiceTimeout​(int cloudServiceTimeout)
        Setter for cloud service timeout. If the API requests service from a DeviceAtlas end-point, shall the end-point not response in this amount of time the next end-point in the list will be used.
        Parameters:
        cloudServiceTimeout - Time in seconds.

      • getAutoServerRankingMaxFailures

        public int getAutoServerRankingMaxFailures()
        Getter for max server failures.
        Returns:
        Number of times an end-point is allowed to fail during auto ranking.

      • setAutoServerRankingMaxFailures

        public void setAutoServerRankingMaxFailures​(int autoServerRankingMaxFailures)
        Setter for max server failures. Number of times an end-point is allowed to fail during auto ranking. Failing more times and the end-pint will be excluded.
        Parameters:
        autoServerRankingMaxFailures - End-point fail tolerance during auto ranking.

      • getAutoServerRankingNumRequests

        public int getAutoServerRankingNumRequests()
        When auto ranking end-points, this number of requests will be sent to each end-point and the mean time will be used for ranking the end-point.
        Returns:
        Number or requests per end-point during auto-ranking.

      • setAutoServerRankingNumRequests

        public void setAutoServerRankingNumRequests​(int autoServerRankingNumRequests)
        When auto ranking end-points, this number of requests will be sent to each end-point and the mean time will be used for ranking the end-point.
        Parameters:
        autoServerRankingNumRequests - Number or requests per end-point during auto-ranking.

      • getServerRankingLifetime

        public int getServerRankingLifetime()
        Returns the server ranking cache lifetime
        Returns:
        serverRankingLifetime

      • setServerRankingLifetime

        public void setServerRankingLifetime​(int serverRankingListLifetime)
        Sets the server ranking cache lifetime
        Parameters:
        serverRankingListLifetime -

      • getPhaseOutLifetime

        @Deprecated
public int getPhaseOutLifetime()
        Deprecated.
        As of release 1.5 getServerPhaseOutLifetime() and getAutoServerRankingLifetime() have been merged.
        Getter for manual ranking server phase out Lifetime. When not auto-ranking shall the top end-point fail the list will be re-arranged and the failed end-point will be moved to the bottom. ServerPhaseOutLifetime indicated for how long should this re-arranged EndPoint list be used over the original.
        Returns:
        Time in minutes.

      • setPhaseOutLifetime

        @Deprecated
public void setPhaseOutLifetime​(int serverRankListLifetime)
        Deprecated.
        As of release 1.5 setPhaseOutLifetime() and setPhaseOutLifetime() have been merged.
        Setter for auto ranking cached end-point list lifetime. After each auto ranking the ranked end point list will be valid for this amount of time. When the list is too old the API will rank it again unless the auto ranking is off.

      • getAutoServerRankingLifetime

        @Deprecated
public int getAutoServerRankingLifetime()
        Deprecated.
        As of release 1.5 getAutoServerRankingLifetime() and getAutoServerRankingLifetime() have been merged.
        Getter for auto ranking cached end-point list lifetime. After each auto ranking the ranked end point list will be valid for this amount of time. When the list is too old the API will rank it again unless the auto ranking is off. AutoServerRankingLifetime indicated for how long should this re-arranged EndPoint list be used over the original.
        Returns:
        Time in minutes.

      • setAutoServerRankingLifetime

        @Deprecated
public void setAutoServerRankingLifetime​(int serverRankListLifetime)
        Deprecated.
        As of release 1.5 setAutoServerRankingLifeTime() and setAutoServerRankingLifetime() have been merged.
        Setter for auto ranking cached end-point list lifetime. After each auto ranking the ranked end point list will be valid for this amount of time. When the list is too old the API will rank it again unless the auto ranking is off.

      • getCacheService

        public CacheService getCacheService()
        Returns the cache layer
        Returns:
        cacheService

      • getEndPointService

        public EndPointService getEndPointService()
        Returns the endPoint layer
        Returns:
        cacheService

      • getDeviceIdentificatorService

        public DeviceIdentificatorService getDeviceIdentificatorService()
        Returns the identificator layer
        Returns:
        cacheService

      • getLicenceKey

        public java.lang.String getLicenceKey()
        Getter for DeviceAtlas cloud licence key.
        Returns:
        DeviceAtlas licence key

      • setLicenceKey

        public void setLicenceKey​(java.lang.String licenceKey)
        Setter for DeviceAtlas cloud licence key.
        Parameters:
        licenceKey - The licence key issued to gain access to DeviceAtlas Cloud.

      • getVersion

        public static java.lang.String getVersion()
        Get the API version
        Returns:
        API VERSION

      • getDeviceData

        @Deprecated
public java.util.Map getDeviceData​(javax.servlet.http.HttpServletRequest request)
                            throws ClientException
        Deprecated.
        Get the cloud service data from the identificator layer
        Parameters:
        request -
        Returns:
        Map
        Throws:
        ClientException

      • getDeviceData

        @Deprecated
public java.util.Map getDeviceData​(java.lang.String userAgent)
                            throws ClientException
        Deprecated.
        Get the cloud service data from the identificator layer
        Parameters:
        userAgent -
        Returns:
        Map
        Throws:
        ClientException

      • getDeviceData

        @Deprecated
public java.util.Map getDeviceData​(java.util.Map<java.lang.String,​java.lang.String> headers)
                            throws ClientException
        Deprecated.
        Get the cloud service data from the identificator layer
        Parameters:
        headers -
        Returns:
        Map
        Throws:
        ClientException

      • getDeviceDataByUserAgent

        @Deprecated
public java.util.Map getDeviceDataByUserAgent​(java.lang.String userAgent)
                                       throws ClientException
        Deprecated.
        Get the cloud service data from the identificator layer
        Parameters:
        userAgent -
        Returns:
        Map
        Throws:
        ClientException

      • getDeviceDataByHeaders

        @Deprecated
public java.util.Map getDeviceDataByHeaders​(java.util.Map<java.lang.String,​java.lang.String> headers)
                                     throws ClientException
        Deprecated.
        Get the cloud service data from the identificator layer
        Parameters:
        headers -
        Returns:
        Map
        Throws:
        ClientException

      • getResult

        public Result getResult​(javax.servlet.http.HttpServletRequest request)
                 throws ClientException
        Get the cloud service data from the identificator layer
        Parameters:
        request -
        Returns:
        Result
        Throws:
        ClientException

      • getResult

        public Result getResult​(java.lang.String userAgent)
                 throws ClientException
        Get the cloud service data from the identificator layer
        Parameters:
        userAgent -
        Returns:
        Result
        Throws:
        ClientException

      • getResult

        public Result getResult​(java.util.Map<java.lang.String,​java.lang.String> headers)
                 throws ClientException
        Get the cloud service data from the identificator layer
        Parameters:
        headers -
        Returns:
        Result
        Throws:
        ClientException

      • getResultByUserAgent

        public Result getResultByUserAgent​(java.lang.String userAgent)
                            throws ClientException
        Get the cloud service data from the identificator layer
        Parameters:
        userAgent -
        Returns:
        Result
        Throws:
        ClientException

      • getResultByHeaders

        public Result getResultByHeaders​(java.util.Map<java.lang.String,​java.lang.String> headers)
                          throws ClientException
        Get the cloud service data from the identificator layer
        Parameters:
        headers -
        Returns:
        Result
        Throws:
        ClientException

      • setProxy

        public void setProxy​(java.net.Proxy proxy)
        Sets the optional proxy for reaching cloud's service
        Parameters:
        proxy -

      • clone

        public java.lang.Object clone()
                       throws java.lang.CloneNotSupportedException
        This throws an exception to prevent cloning this singleton.
        Returns:
        Nothing as exception always thrown
        Throws:
        java.lang.CloneNotSupportedException - when tries to clone using the singleton pattern

      • getServersLatencies

        public EndPoint[] getServersLatencies()
        Get DeviceAtlas cloud end-point list. If auto-ranking is on then the ranked end-point list is returned otherwise the manual or default original or fail-over list will be returned. If auto-ranking is on but no valid end-pont list is found inside the cache then the end-points will be ranked and cached.
        Returns:
        An array of EndPoint objects

      • getServersLatencies

        public EndPoint[] getServersLatencies​(int numRequests)
        Get endPoints and their service latencies.
        Parameters:
        numRequests - Number of times to request from server
        Returns:
        An array of EndPoint objects

      • rankServers

        public EndPoint[] rankServers()
                       throws CacheException
        If auto-ranking is on then rank the DeviceAtlas cloud end-points and put in cache.
        Returns:
        The ranked or re-ordered end-point list
        Throws:
        CacheException - when an error checking server latencies appears

      • getUseClientCookie

        public boolean getUseClientCookie()
        Getter for the useClientCookie setting. Defaults to true. If TRUE then if device data which is created by the DeviceAtlas client side component (JS library) exists it will be used
        Returns:
        The sendExtraHeaders setting. Defaults to false

      • setUseClientCookie

        public void setUseClientCookie​(boolean useClientCookie)
        Setter for the useClientCookie setting. Defaults to true. If TRUE then if device data which is created by the DeviceAtlas client side component (JS library) exists it will be used
        Parameters:
        useClientCookie - true = use device data which is created by the DeviceAtlas client side component if exists

      • getUseCache

        public boolean getUseCache()
        Is device data being cached by the API or not.
        Returns:
        true(default) = data is being cached.

      • setUseCache

        public void setUseCache​(boolean useCache)
        Setter to cache or not to cache device data.
        Parameters:
        useCache - true = cache data after getting device data from DeviceAtlas cloud

      • clearCache

        public void clearCache()
        Clear all cached data.

      • shutdown

        public void shutdown()
        This should be called when shutting down your application. It asks the cache manager to shutdown the cache and write the cache to disk. See http://ehcache.org/documentation/code-samples#shutdown-the-cachemanager

      • getSendExtraHeaders

        public boolean getSendExtraHeaders()
        Getter for the sendExtraHeaders setting. Defaults to false. If this TRUE then extra client headers are sent with each request to the service. If this is FALSE then only select headers essential for detection are sent.
        Returns:
        The sendExtraHeaders setting. Defaults to false.

      • setSendExtraHeaders

        public void setSendExtraHeaders​(boolean sendExtraHeaders)
        Setter for the sendExtraHeaders setting. Defaults to false. If this TRUE then extra client headers are sent with each request to the service. If this is FALSE then only select headers essential for detection are sent.
        Parameters:
        sendExtraHeaders - TRUE if to send extra headers, FALSE to just send essential headers.