Fork me on GitHub

Usage

Requirements

This library depends on Simple Logging Facade for Java (also known as SLF4J) to allow our end users to plug in whatever logging framework he wants at deployment time. Additionally it depends on Quality-Check to do technical runtime checks easily and JSR-305 Annotations to document possible states about methods, fields and arguments for Software Defect Detection.

This means that if you use UADetector library, all compile and runtime dependencies must exists in your classpath. You can get detailed informations about the required dependencies for each module here:

Usage in a simple Servlet

To use this library you must add them with all their sub-dependencies to your classpath. With Apache Maven you can start with this guide quickly.

Then you should have access to the classes of the library. For example, you might want to make a Servlet as the following to detect an requesting client.

package net.sf.uadetector.example;

import java.io.IOException;
import javax.servlet.*;
import net.sf.uadetector.service.UADetectorServiceFactory;
import net.sf.uadetector.UserAgent;
import net.sf.uadetector.UserAgentStringParser;

public class HelloServlet extends HttpServlet {

	private static final long serialVersionUID = 1L;

	protected void doGet(HttpServletRequest request, HttpServletResponse response)
			throws ServletException, IOException {

		response.setContentType("text/html");
		response.setStatus(HttpServletResponse.SC_OK);

		PrintWriter out = response.getWriter();

		// Get an UserAgentStringParser and analyze the requesting client
		UserAgentStringParser parser = UADetectorServiceFactory.getResourceModuleParser();
		ReadableUserAgent agent = parser.parse(request.getHeader("User-Agent"));

		out.append("You're a <em>");
		out.append(agent.getName());
		out.append("</em> on <em>");
		out.append(agent.getOperatingSystem().getName());
		out.append("</em>!");
	}

}

Improve Performance by Caching

Since the parsing of user agent strings is very processing costly, it's recommended to build a cache on top of the parser. You can use a simple HashMap or Guava's CacheBuilder for example.

package to.noc.uadetector.example;

import java.util.concurrent.TimeUnit;
import net.sf.uadetector.ReadableUserAgent;
import net.sf.uadetector.UserAgentStringParser;
import net.sf.uadetector.service.UADetectorServiceFactory;
import com.google.common.cache.Cache;
import com.google.common.cache.CacheBuilder;

public final class CachedUserAgentStringParser implements UserAgentStringParser {

	private final UserAgentStringParser parser = UADetectorServiceFactory
							.getCachingAndUpdatingParser();
	private final Cache<String, ReadableUserAgent> cache = CacheBuilder.newBuilder()
							.maximumSize(100)
							.expireAfterWrite(2, TimeUnit.HOURS)
							.build();

	@Override
	public String getDataVersion() {
		return parser.getDataVersion();
	}

	@Override
	public ReadableUserAgent parse(final String userAgentString) {
		ReadableUserAgent result = cache.getIfPresent(userAgentString);
		if (result == null) {
			result = parser.parse(userAgentString);
			cache.put(userAgentString, result);
		}
		return result;
	}

	@Override
	public void shutdown() {
		parser.shutdown();
	}

}

Redeploying / Undeploying UADetector

In environments where the JVM will never shut down while reinstalling UADetector, it is necessary to manually shutdown running threads. Therefore we provide since uadetector-core-0.9.6 UserAgentStringParser#shutdown() and ExecutorServices#shutdownAll() to stop running executors and schedulers if necessary.

For example, during destroying a servlet you can clean up used parsers within your web application like this.

public class HelloServlet extends HttpServlet {

	@Override
	public void destroy() {
		// undeploy used parser cleanly
		UADetectorServiceFactory.getOnlineUpdatingParser().shutdown();
	}

	@Override
	protected void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {
		// working with an updating UserAgentStringParser
		UserAgentStringParser parser = UADetectorServiceFactory.getOnlineUpdatingParser();

		// ... do something ...
	}

}

Demo

You can also find a hello world demo in the Source Content Management System (SCM) under examples/helloworld.