< and
the [Device Data guide](https://deviceatlas.com/resources/getting-the-data/device-data)
for more information.
#### Loading the data file ####
The DeviceAtlas API provides multiple methods to load the data file.
##### Downloading and loading the data file #####
The following examples download the data file, save it to the file system,
load it into the DeviceAtlas API and schedule a background task to download and load
a fresh data file at a configured time in the future.
Please see the [Data File Configuration documentation](README.DataFile.html)
to obtain the data file download URL and for data file configuration options.
```java
DeviceApi deviceApi = new DeviceApi();
String dataFileUrl = <data file download URL>;
// Load using custom configuration
DataFile dataFile = new DataFile.Builder(dataFileUrl).fileDirectory(<persistent download directory>).buildDeviceDataFile();
deviceApi.downloadAndLoadDataFile(dataFile);
// Load using default configuration
deviceApi.downloadAndLoadDataFile(dataFileUrl);
```
##### Loading an existing data file #####
The following examples show how to load a data file that is already on the filesystem.
```java
DeviceApi deviceApi = new DeviceApi();
// Load data from a file on the class path
deviceApi.loadDataFromClassPath(<data file name on class path>);
// Load data from file path
deviceApi.loadDataFromFile(<data file path>);
```
##### Loading data from an `InputStream` #####
The following examples show how to load a data file from an `InputStream` object.
This can be used if you do not wish to load the data file from the local file system.
```java
DeviceApi deviceApi = new DeviceApi();
InputStream inputStream = <Obtain InputStream>;
deviceApi.loadDataFromStream(inputStream);
```
### Client Side Component ###
In addition to the properties from the data file, properties can be gathered from
the client's browser and used both on the client side and on the server side.
It is strongly recommended to use the Client-side component when using the DeviceAtlas
API within a web application in order to correctly identify iOS devices.
The client side resource (https://cs.deviceatlas-cdn.com/dacs.js)
must be included on your webpage in order for it to detect the client side properties.
The contents of this cookie are automatically detected by the API.
Please click [here](https://docs.deviceatlas.com/apis/clientside/latest/README.ClientSide.html) for
more information.
```
<!-- Adding the DeviceAtlas client side component to get client side properties -->
<script type="text/javascript" src="https://cs.deviceatlas-cdn.com/dacs.js" async></script>
```
### Basic Usage ###
The API can be used as follows:
#### Detection via HttpServletRequest ####
Create an API instance and load the data file when the servlet starts:
```java
public class ServletContextExample implements ServletContextListener {
public void contextInitialized(ServletContextEvent contextEvent) {
// load the data file in a try/catch block an exceptions may be thrown
try {
DeviceApiWeb deviceApi = new DeviceApiWeb();
DataFile dataFile = new DataFile.Builder(<data file download URL>).fileDirectory(<persistent download directory>).buildDeviceDataFile();
deviceApi.downloadAndLoadDataFile(dataFile);
// store the DeviceApiWeb instance on the servlet context
ServletContext context = contextEvent.getServletContext();
context.setAttribute("DeviceApiWeb", deviceApi);
} catch (DataFileException ex) {
// handle the exceptions related to loading the data file
}
}
}
```
Lookup the device properties when processing requests:
```java
ServletContext context = getServletContext();
DeviceApiWeb deviceApi = (DeviceApiWeb)context.getAttribute("DeviceApiWeb");
Properties properties = deviceApi.getProperties(request);
```
#### Detection via user-agent ####
To lookup the properties by manually passing a user-agent string to the API:
```java
DeviceApi deviceApi = new DeviceApi();
try {
DataFile dataFile = new DataFile.Builder(<data file download URL>).fileDirectory(<persistent download directory>).buildDeviceDataFile();
deviceApi.downloadAndLoadDataFile(dataFileUrl)
String userAgent = "THE USER AGENT VALUE";
Properties properties = deviceApi.getProperties(userAgent);
} catch (DataFileException x) {
// handle the exceptions related to loading the data file
}
```
#### Detection via Make/Model ####
To lookup the properties by manually passing a Make/Model string to the API.
DeviceAtlas expects the make/model string in a specific format, this format
and how to obtain the Make/Model string can be found under the
"Expected string format for DeviceAtlas lookup" section [here](https://deviceatlas.com/resources/getting-started-enterprise-for-apps).
```java
DeviceApi deviceApi = new DeviceApi();
try {
DataFile dataFile = new DataFile.Builder(<data file download URL>).fileDirectory(<persistent download directory>).buildDeviceDataFile();
deviceApi.downloadAndLoadDataFile(dataFile)
String makeModel = "samsung sm-n9005";
Properties properties = deviceApi.getProperties(makeModel);
} catch (DataFileException x) {
// handle the exceptions related to loading the data file
}
```
#### Using the properties ####
```java
// if there is a property named "mobileDevice" and the value is true
if (properties.contains("mobileDevice", true)) {
// example 1: Get the screen width for image optimization
int displayWidth = properties.containsKey("displayWidth")?
properties.get("displayWidth").asInteger(): 100;
// example 2: Get the device vendor name
String vendor = properties.containsKey("vendor")?
properties.get("vendor").asString(): "";
// example 3: Touch screen optimization
boolean useBiggerIcons = properties.contains("touchScreen", true);
// example 4: Send Geo Location JS to client?
boolean supportsGeoLocation = properties.contains("js.geoLocation", true);
}
```
### Examples ###
Please see the Examples directory for examples that encompass the following scenarios:
1. **Analytics**: Located at Examples/Device/analytics
2. **Usage within a command line application**: Located at Examples/Device/basic-usage-cli-detect
3. **iPhone detection**: Located at Examples/Device/basic-usage-cli-detect-iphone
4. **Detecting Opera Mini browser device properties**: Located at Examples/Device/basic-usage-cli-detect-opera
5. **Usage within a web application**: Located at Examples/Device/basic-usage-web
6. **Combined Device and Carrier usage in a command line application**: Located at Examples/Device/combined-apis-basic-usage-cli-detect
7. **Combined Device and Carrier usage in a web application**: Located at Examples/Device/combined-apis-basic-usage-web
8. **Combined Device and Carrier wrapper usage**: Located at Examples/Device/combined-apis-unified-api-wrapper
9. **Content adaptation**: Located at Examples/Device/content-adaptation
10. **Content targeting**: Located at Examples/Device/content-targeting
11. **Usage in a multithreaded environment**: Located at Examples/Device/multithreading
12. **Redirection**: Located at Examples/Device/redirection
13. **Usage with the singleton pattern**: Located at Examples/Device/singleton-wrapper
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
_ Copyright (c) DeviceAtlas Limited 2022. All Rights Reserved. _
_ https://deviceatlas.com _
<!-- HTML+JS for document formatting when opened in browser -->
<div class="btn-group" id="main-menu" style="float:right"><a class="btn dropdown-toggle" data-toggle="dropdown" href="#">Menu<span class="caret"></span></a><ul class="dropdown-menu"><li><a href="README.html">Main</a></li><li><a href="README.Installation.html">Enterprise API Installation</a></li><li><a href="README.DataFile.html">Data File Configuration</a></li><li class="disabled"><a href="README.DeviceApi.html">Device Detection</a></li><li><a href="README.DeviceApi-Config.html">Device Identification API Config</a></li><li><a href="README.CarrierApi.html">Carrier Identification API</a></li><li class="divider"></li><li><a href="./DeviceAtlasApiDocs/index.html">DeviceAtlas API Docs</a></li><li><a href="README.Upgrade.html">API Upgrade</a></li></ul></div>]]>