AbstractUserAgentStringParser.java

/*******************************************************************************
 * Copyright 2012 André Rouél
 * 
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 * 
 *   http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 ******************************************************************************/
package net.sf.uadetector.parser;

import java.util.Map.Entry;
import java.util.regex.Matcher;

import javax.annotation.Nonnull;

import net.sf.uadetector.DeviceCategory;
import net.sf.uadetector.ReadableDeviceCategory.Category;
import net.sf.uadetector.UserAgent;
import net.sf.uadetector.UserAgentStringParser;
import net.sf.uadetector.UserAgentType;
import net.sf.uadetector.VersionNumber;
import net.sf.uadetector.datastore.DataStore;
import net.sf.uadetector.internal.data.Data;
import net.sf.uadetector.internal.data.domain.Browser;
import net.sf.uadetector.internal.data.domain.BrowserPattern;
import net.sf.uadetector.internal.data.domain.Device;
import net.sf.uadetector.internal.data.domain.DevicePattern;
import net.sf.uadetector.internal.data.domain.OperatingSystem;
import net.sf.uadetector.internal.data.domain.OperatingSystemPattern;
import net.sf.uadetector.internal.data.domain.Robot;

public abstract class AbstractUserAgentStringParser implements UserAgentStringParser {

	/**
	 * The number of capturing groups if nothing matches
	 */
	private static final int ZERO_MATCHING_GROUPS = 0;

	/**
	 * Examines the user agent string whether it is a browser.
	 * 
	 * @param userAgent
	 *            String of an user agent
	 * @param builder
	 *            Builder for an user agent information
	 */
	private static void examineAsBrowser(final UserAgent.Builder builder, final Data data) {
		Matcher matcher;
		VersionNumber version = VersionNumber.UNKNOWN;
		for (final Entry<BrowserPattern, Browser> entry : data.getPatternToBrowserMap().entrySet()) {
			matcher = entry.getKey().getPattern().matcher(builder.getUserAgentString());
			if (matcher.find()) {

				entry.getValue().copyTo(builder);

				// try to get the browser version from the first subgroup
				if (matcher.groupCount() > ZERO_MATCHING_GROUPS) {
					version = VersionNumber.parseVersion(matcher.group(1) != null ? matcher.group(1) : "");
				}
				builder.setVersionNumber(version);

				break;
			}
		}
	}

	/**
	 * Examines the user agent string whether it is a robot.
	 * 
	 * @param userAgent
	 *            String of an user agent
	 * @param builder
	 *            Builder for an user agent information
	 * @return {@code true} if it is a robot, otherwise {@code false}
	 */
	private static boolean examineAsRobot(final UserAgent.Builder builder, final Data data) {
		boolean isRobot = false;
		VersionNumber version;
		for (final Robot robot : data.getRobots()) {
			if (robot.getUserAgentString().equals(builder.getUserAgentString())) {
				isRobot = true;
				robot.copyTo(builder);

				// try to get the version from the last found group
				version = VersionNumber.parseLastVersionNumber(robot.getName());
				builder.setVersionNumber(version);

				break;
			}
		}
		return isRobot;
	}

	/**
	 * Examines the user agent string whether has a specific device category.
	 * 
	 * @param userAgent
	 *            String of an user agent
	 * @param builder
	 *            Builder for an user agent information
	 */
	private static void examineDeviceCategory(final UserAgent.Builder builder, final Data data) {

		// a robot will be classified as 'Other'
		if (UserAgentType.ROBOT == builder.getType()) {
			final DeviceCategory category = findDeviceCategoryByValue(Category.OTHER, data);
			builder.setDeviceCategory(category);
			return;
		}

		// classification depends on matching order
		for (final Entry<DevicePattern, Device> entry : data.getPatternToDeviceMap().entrySet()) {
			final Matcher matcher = entry.getKey().getPattern().matcher(builder.getUserAgentString());
			if (matcher.find()) {
				final Category category = Category.evaluate(entry.getValue().getName());
				final DeviceCategory deviceCategory = findDeviceCategoryByValue(category, data);
				builder.setDeviceCategory(deviceCategory);
				return;
			}
		}

		// an unknown user agent type should lead to an unknown device
		if (UserAgentType.UNKNOWN == builder.getType()) {
			builder.setDeviceCategory(DeviceCategory.EMPTY);
			return;
		}

		// if no pattern is available but the type is Other, Library, Validator or UA Anonymizer
		// than classify it as 'Other'
		if (UserAgentType.OTHER == builder.getType() || UserAgentType.LIBRARY == builder.getType()
				|| UserAgentType.VALIDATOR == builder.getType() || UserAgentType.USERAGENT_ANONYMIZER == builder.getType()) {
			final DeviceCategory category = findDeviceCategoryByValue(Category.OTHER, data);
			builder.setDeviceCategory(category);
			return;
		}

		// if no pattern is available but the type is a mobile or WAP browser than classify it as 'Smartphone'
		if (UserAgentType.MOBILE_BROWSER == builder.getType() || UserAgentType.WAP_BROWSER == builder.getType()) {
			final DeviceCategory category = findDeviceCategoryByValue(Category.SMARTPHONE, data);
			builder.setDeviceCategory(category);
			return;
		}

		final DeviceCategory category = findDeviceCategoryByValue(Category.PERSONAL_COMPUTER, data);
		builder.setDeviceCategory(category);
	}

	/**
	 * Examines the operating system of the user agent string, if not available.
	 * 
	 * @param userAgent
	 *            String of an user agent
	 * @param builder
	 *            Builder for an user agent information
	 */
	private static void examineOperatingSystem(final UserAgent.Builder builder, final Data data) {
		if (net.sf.uadetector.OperatingSystem.EMPTY.equals(builder.getOperatingSystem())) {
			for (final Entry<OperatingSystemPattern, OperatingSystem> entry : data.getPatternToOperatingSystemMap().entrySet()) {
				final Matcher matcher = entry.getKey().getPattern().matcher(builder.getUserAgentString());
				if (matcher.find()) {
					entry.getValue().copyTo(builder);
					break;
				}
			}
		}
	}

	private static DeviceCategory findDeviceCategoryByValue(@Nonnull final Category category, @Nonnull final Data data) {
		for (final Device device : data.getDevices()) {
			if (category == device.getCategory()) {
				return new DeviceCategory(category, device.getIcon(), device.getInfoUrl(), device.getName());
			}
		}
		return DeviceCategory.EMPTY;
	}

	/**
	 * Gets the data store of this parser.
	 * 
	 * @return data store of this parser
	 */
	protected abstract DataStore getDataStore();

	@Override
	public String getDataVersion() {
		return getDataStore().getData().getVersion();
	}

	@Override
	public UserAgent parse(final String userAgent) {
		final UserAgent.Builder builder = new UserAgent.Builder(userAgent);

		// work during the analysis always with the same reference of data
		final Data data = getDataStore().getData();

		if (!examineAsRobot(builder, data)) {
			examineAsBrowser(builder, data);
			examineOperatingSystem(builder, data);
		}
		examineDeviceCategory(builder, data);
		return builder.build();
	}

	@Override
	public void shutdown() {
		// nothing to shutdown
	}

}