<![CDATA[
# DeviceAtlas Data File Configuration #
Automated data file download and load configuration.
### Overview ###
The DeviceAtlas Device API and Carrier API provide the functionality of
downloading and loading their respective data files given a URL. After
the first data file load a background task is scheduled to load a fresh
data file at a configured time in the future to ensure the API has the latest
version of DeviceAtlas data.
Please note that basic telemetry data such as the number of API lookups
are collected when using the download and load functionality.
### Obtaining the data file download URL ###
#### Device Data File URL ####
Navigate to https://deviceatlas.com/user and copy the device data file download URL
located at "API Data Files" -> "Device Identification" -> "Download Data" -> "ZIP"
#### Carrier Data File URL ####
Navigate to https://deviceatlas.com/user and copy the carrier data file download URL
located at "API Data Files" -> "Carrier Identification" -> "Download Data" -> "ZIP"
### Basic Usage ###
To change the default download and load behaviour you must create an instance of the
`DataFile` class and pass it to the `downloadAndLoadDataFile` method in either the
`DeviceApi` or `CarrierApi`:
```
// Device data file example usage
DataFile deviceDataFile = new DataFile.Builder(<data file download URL>).fileDirectory(<persistent download directory>).buildDeviceDataFile();
DeviceApi deviceApi = new DeviceApi();
deviceApi.downloadAndLoadDataFile(deviceDataFile);
// Carrier data file example usage
DataFile carrierDataFile = new DataFile.Builder(<carrier file download URL>).fileDirectory(<persistent download directory>).buildCarrierDataFile();
CarrierApi carrierApi = new CarrierApi();
carrierApi.downloadAndLoadDataFile(carrierDataFile);
```
### DataFile class ###
The DeviceAtlas DataFile class provides options to customize the frequency,
location and validation of the DeviceAtlas data file downloads.
* Download and load frequency
* Download file location
* Data file download connection timeout
* Data file download validation
* Disabling automatic data file download and load
#### Download and load frequency ####
The frequency in days to download and load the latest data file.
Note the minimum value is 1 day.
**DataFile methods**
```
downloadAndLoadFrequencyDays(<integer>)
```
**Default value**
1
#### Download and load schedule time ####
The time of day to schedule the download and load of the data file.
The format is HH:mm:ss (hours:minutes:seconds) e.g "13:00:00" will schedule
the file to be downloaded and loaded at 1PM.
Please note that this option is ignored on the first data file load and only
applies to the background task that downloads and loads the latest data file.
**DataFile methods**
```
downloadAndLoadScheduleTime(<string>)
```
**Default value**
The current time in hours, minutes and seconds
#### Download file location ####
The file system directory where the data file will be downloaded to.
It is strongly recommended to set this to a persistent file path to
ensure there is always a data file on the system that can be loaded
immediately.
**DataFile methods**
```
fileDirectory(<string>)
```
**Default value**
The system's temporary directory.
#### Data file download connection timeout ####
The time in milliseconds allowed to establish a connection to the download
server.
**DataFile methods**
```
downloadConnectionTimeoutMilliseconds(<integer>)
```
**Default value**
60000 (60 seconds)
#### Data file download read timeout ####
The time in milliseconds allowed to read data from the download server.
**DataFile methods**
```
downloadReadTimeoutMilliseconds(<integer>)
```
**Default value**
60000 (60 seconds)
#### Disabling automatic data file download and load ####
If for any reason it is necessary to prevent the scheduled load and
reload of the data file this can be achieved by calling the
`disableScheduledDownloadAndReload` method with `true`.
**DataFile methods**
```
disableScheduledDownloadAndReload(<boolean>)
```
#### Dealing with scheduled background data file load failures ####
In the event that the background task that loads the data file into the
API fails you may implement the `DownloadAndLoadTaskFailureCallback` interface
and set it in the `DataFile` object. If an exception occurs the `handle` method
of the interface will be called and an object of class `Exception` is passed
as a parameter. An example use case for this callback would be to log the exception.
**DataFile methods**
```
downloadAndLoadTaskFailureCallback(<DownloadAndLoadTaskFailureCallback>)
```
**Example usage**
```
class DeviceAtlasDataFileFailure implements DownloadAndLoadTaskFailureCallback {
private static Logger logger = LogManager.getLogger(DeviceAtlasDataFileFailure.class);
public void handle(DataFileException dataFileException) {
logger.error("Error loading DeviceAtlas data file", dataFileException);
}
}
DataFile dataFile = new DataFile.Builder(<data file download URL>).downloadAndLoadTaskFailureCallback(new DeviceAtlasDataFileFailure()).buildDeviceDataFile();
```
#### Scheduled data file load background task success callback ####
In addition to handling errors during the background task that loads the data file, a
success callback is also provided.
**DataFile methods**
```
downloadAndLoadTaskSuccessCallback(<DownloadAndLoadTaskSuccessCallback>)
```
**Example usage**
```
class DeviceAtlasDataFileSuccess implements DownloadAndLoadTaskSuccessCallback {
private static Logger logger = LogManager.getLogger(DeviceAtlasDataFileSuccess.class);
public void handle() {
logger.info("DeviceAtlas data file loaded successfully");
}
}
DataFile dataFile = new DataFile.Builder(<data file download URL>).downloadAndLoadTaskSuccessCallback(new DeviceAtlasDataFileSuccess()).buildDeviceDataFile();
```
### Custom Endpoint Data File Provisioning ###
If you would like to provision the data files from a custom endpoint please
note the following:
#### Supported content types ####
For both the Device and Carrier data files ZIP and GZIP compression are supported. For
ZIP files please provide "application/zip" as a "Content-Type" response header. For
GZIP files please provide "application/x-gzip" as a "Content-Type" response header.
Uncompressed data files are also supported. For uncompressed Device data files please provide
"application/json" as a "Content-Type" response header. For uncompressed Carrier data files
please provide "application/octet-stream" as a "Content-Type" response header.
#### Data file download validation ####
The data file download is validated by comparing the MD5 checksum of the data file
against the MD5 checksum header (Content-MD5) sent with the data file download.
It is recommended to provide an MD5 checksum of the data file as a "Content-MD5"
response header.
If you do not wish to send an MD5 checksum header this validation can be disabled by
passing `false` to the `validateMd5` method. The name of the header containing the MD5
checksum can also be modified using the `headerContentMd5` method.
**DataFile methods**
```
validateMd5(<boolean>)
headerContentMd5(<string>)
```
**Validate MD5 default value**
true
**MD5 header default value**
Content-MD5
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
_ Copyright (c) DeviceAtlas Limited 2023. 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 class="disabled"><a href="README.DataFile.html">Data File Configuration</a></li><li><a href="README.DeviceApi.html">Device API Usage</a></li><li><a href="README.ClientHints.html">Client Hints Support</a></li><li><a href="README.Upgrade.html">Device API Upgrade</a></li><li><a href="README.CarrierApi.html">Carrier Identification API</a></li><li class="divider"></li><li><a href="./Javadoc/index.html">Javadoc</a></li></ul></div>]]>