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:
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>!"); } }
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(); } }
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 ... } }
You can also find a hello world demo in the Source Content Management System (SCM) under examples/helloworld.