51Degrees-Java Files

------------------------------- 1 INTRODUCTION --------------------------------

HomePage: <https://51degrees.com>
Documentation: <https://51degrees.com/support/documentation/java>
Support: <https://51degrees.com/support/forum>
Repository: <https://github.com/51Degrees/Java-Device-Detection>

51Degrees Java API provides device detection capabilities for both offline and 
real time use. The API exposes a number of methods to match an HTTP User-Agent 
string, a collection of relevant HTTP headers and a device ID and provide a 
result containing device information such as the manufacturer, device type, 
browser-related information and many more properties. For a full list of 
supported properties see: https://51degrees.com/resources/property-dictionary

The source code as well as the Lite data files are distributed under 
Mozilla Public Licence Version 2.0 (MPL2). A copy of MPL2 can be found in the 
root of this package.

Enterprise and Premium data files are subject to Data Licence Terms:
https://51degrees.com/Purchase/Data

Enterprise and Premium data files provide considerably more properties and 
device-software combinations as well as additional features such as:
    -Automatic Daily/Weekly Updates
    -Bandwidth Monitoring
    -Device Type(such as Tablet)
    -Operating System
    -Screen Dimension
    -Input Method
	See <https://51degrees.com/compare-data-options> to compare the various 
	device data options.

For automatic updates, tablet, operating system and physical screen size
see 51Degrees Premium Data at <https://51degrees.com/products/device-detection>

------------------------------- 2 QUICK START ---------------------------------

Please note that as of version 3.2.2.20-beta the project structure has been 
changed to Maven project. In addition the Maven coordinates have changed in 
order to accommodate the new project structure:
http://search.maven.org/#search|ga|1|g%3A%22com.51degrees%22

2.1. Obtaining a 51Degrees data file:
- Codeplex: <http://51degrees.codeplex.com/>
- Github: <https://github.com/51Degrees/Java-Device-Detection/tree/master/data>
- Premium and Enterprise data files: <https://51degrees.com/compare-data-options>

2.2. Using the Core API:

51Degrees provides two detection algorithms: Pattern and Trie. In short: Pattern 
is more memory efficient with smaller data files while Trie is faster but 
requires more memory and the data files are considerably larger. For more info 
on the algorithms please see: 
<https://51degrees.com/support/documentation/how-device-detection-works>

2.2.1. Pattern.

	Pattern relies on the Provider object that interacts with device data through 
	the dataset. The Dataset in turn can be created using either StreamFactory:
	
	Provider p = new Provider(StreamFactory.create("path/to/data/file.dat", false));
	
	or using MemoryFactory:
	
	Provider p = new Provider(MemoryFactory.create("path/to/data/file.dat"));

	StreamFactory creates a dataset that interacts directly with the data file, 
	so all detection results are retrieved from the data file on each request.
	MemoryFactory fully loads the data file in to memory so that the data file 
	is not used for detection at all.
	
	Detection takes place in the match method of the Provider object:
	
	Match match = p.match("User agent string goes here.");
	
	You can then access detection results via the match object as follows:
	
	match.getValues("IsMobile");
	
	By default all results are returned as Strings.
	
2.2.2. Trie.
	
	Trie relies on the TrieProvider to interact with the Trie data file to 
	retrieve detection results. Trie provider can be created as follows:
	
	TrieProvider trp = TrieFactory.create("path\\to\\file.trie");
	
	Note that the Pattern data file (.dat) will not work with the Trie (.trie) 
	Provider and vice versa.
	
	To obtain the device information you need to first find the index of the 
	device as follows:
	
	int index = trp.getDeviceIndex("User agent");
	
	and then retrieve the property values for the found index:
	
	String isMobile = provider.getPropertyValue(index, "IsMobile");

2.2.3. Using the Servlet API.

	Include...
	
	import fiftyone.mobile.detection.webapp.BaseServlet;
	
	Extend:
	
	public class MyServlet extends BaseServlet {
	
	Use:
	
	boolean isMobile = Boolean.parseBoolean(getProperty(request,"IsMobile"));
	
	or:
	
	boolean isTablet = Boolean.parseBoolean(getProperty(request,"IsTablet"));
	
	... to add device detection to your servlet.
	
For examples and tutorials see:
https://51degrees.com/Support/Documentation/APIs/Java-V32/Tutorials
	
--------------------------- 3 PACKAGE CONTENTS --------------------------------

-dist folder: contains core and webapp JAR files of the current version.
-javadoc folder: contains Javadoc for the current version.
-src folder: is the Maven project folder that contains source code, tests and 
			 Lite device data. This folder can be opened as a Maven project in 
			 the IDE of your choilce.
-LICENCE.txt file: contains a copy of the MPL2.
-README.txt file: this file.

----------------------------- 4 BUILDING PROJECT ------------------------------

You can build the source code using your IDE or by invoking the following 
command from your command line/terminal window:

	mvn clean install
	
This will build the projects and run a set of tests. To choose which tests to 
run you can use one of the pre-defined build profiles:

	test-dataset-lite-only runs a full set of tests for Lite data files only.
	test-type-api-only 	   runs a set of tests from the api test package. This 
						   profile is the fastest to complete the build.
						   
To use a Maven profile from command line/terminal:

	mvn clean install –P profile-name

----------------------------- 5 BREAKING CHANGES ------------------------------

As of version 3.2 the following changes have been implemented that will break 
any of the existing implementations:

3.1 The provider object: you can no longer instantiate a provider object 
without providing the dataset object. So the 
	Provider p = new Provider(); 
will no longer work. Instead you will need to do one of the following:

Provider p = new Provider(StreamFactory.create("path/to/data/file.dat", false));
or:
Provider p = new Provider(MemoryFactory.create("path/to/data/file.dat"));

Please note that the StreamFactory now takes in at least 2 parameters:
 - Path to data file.
 - boolean to indicate whether the data file provided is temporary. This will 
   matter when the dispose method is invoked. If the flag is set to true, the 
   API will attempt to delete the data file upon dispose.
   
As of version 3.2.2.20-beta project structure was changed to Maven project.
 
-------------------------------- 6 CHANGELOG ----------------------------------

Version 3.2.3.5 Changes:

Focus on improving tests, cleaning up documentation and API efficiency. 
Version highlights:

Efficiency: IntegerFactory and IntegerEntity removed. More efficient integer 
lists are used instead, hence reducing the number of objects and significantly 
reducing memory consumption in memory mode.

Build.xml has been removed as it no longer serves any purpose.

Tests: general improvements and more realistic values. Memory tests for array 
and memory modes now use a file size multiplier. New tests added to validate 
stream and memory detections produce the same results.

General: indentation and javadoc improvements.

IFixedList removed, ISimpleList is used instead. New interface allows to 
retrieve a reference to a range of values in a list.

Version 3.2.2.20 Changes:

Project structure has been changed to Maven project.

The IDisposable interface has been removed, all classes that provide methods 
to free resources implement Closeable instead.

Provider supports retrieving match results using device IDs generated from 
previous matches.

Automatic update has been re-designed to be more efficient and resilient. 
Returns an update status instead of a boolean.

The cache has been upgraded to use a least recently used (LRU) design. This 
removes the need to service the cache in a background thread, and results in 
a more predictable performance under load.

Duplicate code has been consolidated with a focus on improving documentation 
and implementing recommendations from code analysis and peer reviews. Testing 
coverage has been included with initial unit tests for new features.

Consistent examples have been added in parallel with APIs in other languages. 
The examples are designed to highlight a specific use case for the API. They 
relate to example specific documentation on the 51Degrees web site under 
Support -> Documentation -> Java.

Version 3.2.1.9-beta
- Automatic update function no longer uses the memory to store data downloaded 
  from 51degrees.com update server. Instead a temporary file is used. 
  This should significantly reduce the memory impact of the auto update process.
- The API now supports 51Degrees data files of version 3.2 as well as 3.1 data 
  files. The data files of version 3.2 are on average 20% smaller than the 3.1 
  data files due to the changes to the internal data structure.
- The core API (both Pattern and Trie) has been updated to perform device 
  detection with multiple HTTP headers.
- The API has been updated to implement caching for all major components that 
  require lookup/detection. This change reflects the fact that in the real-world 
  applications/websites subsequent requests are probable and that some user 
  agents that are encountered more often than others. This change should improve 
  detection times even further.
- Breaking change: The embedded data file no longer exists. This makes the JAR 
  very light but you will need to obtain the data file separately.
- Breaking change: Provider object can no longer be instantiated without 
  specifying the dataset to be used. See the breaking changes section.

-------------------------------------------------------------------------------