VersionNumber.java

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

  18. import java.io.Serializable;
  19. import java.util.ArrayList;
  20. import java.util.Arrays;
  21. import java.util.Collections;
  22. import java.util.List;
  23. import java.util.regex.Pattern;

  25. import javax.annotation.Nonnull;
  26. import javax.annotation.Nullable;

  28. import net.sf.qualitycheck.Check;
  29. import net.sf.qualitycheck.exception.IllegalStateOfArgumentException;
  30. import net.sf.uadetector.internal.util.AlphanumComparator;

  32. /**
  33.  * The {@code VersionNumber} class represents the version number of an operating system or User-Agent.<br>
  34.  * <br>
  35.  * A {@code VersionNumber} object is immutable, their values cannot be changed after creation.
  36.  * 
  37.  * @author André Rouél
  38.  */
  39. public final class VersionNumber implements ReadableVersionNumber, Serializable {

  41.     /**
  42.      * Empty extension or addition of a version number
  43.      */
  44.     public static final String EMPTY_EXTENSION = "";

  46.     /**
  47.      * Empty group or category of a version number
  48.      */
  49.     public static final String EMPTY_GROUP = "";

  51.     /**
  52.      * Minimum number of numeric group a version number
  53.      */
  54.     private static final int MIN_GROUP_SIZE = 3;

  56.     /**
  57.      * Regular expression to find only numerical values ​​in strings
  58.      */
  59.     private static final Pattern NUMERIC = Pattern.compile("\\d+");

  61.     /**
  62.      * Separator between numeric groups of a version number
  63.      */
  64.     private static final char SEPARATOR = '.';

  66.     /**
  67.      * Serialization version
  68.      */
  69.     private static final long serialVersionUID = 1L;

  71.     /**
  72.      * Defines an empty or not set version number
  73.      */
  74.     public static final VersionNumber UNKNOWN = new VersionNumber(EMPTY_GROUP);

  76.     /**
  77.      * Checks a string that only numerical values ​​are present. Negative numbers are not included.
  78.      * 
  79.      * @param text
  80.      *            string to be tested
  81.      * @return {@code true} if only numeric characters are present, otherwise {@code false}
  82.      */
  83.     private static boolean isNumeric(final String text) {
  84.         return NUMERIC.matcher(text).matches();
  85.     }

  87.     /**
  88.      * Interprets a string with version information. The last version number in the string will be searched and
  89.      * processed.
  90.      * 
  91.      * @param text
  92.      *            string with version information
  93.      * @return an object of {@code VersionNumber}, never {@code null}
  94.      */
  95.     public static VersionNumber parseLastVersionNumber(@Nonnull final String text) {
  96.         return VersionParser.parseLastVersionNumber(Check.notNull(text, "text"));
  97.     }

  99.     /**
  100.      * Try to determine the version number of the operating system by parsing the user agent string.
  101.      * 
  102.      * 
  103.      * @param family
  104.      *            family of the operating system
  105.      * @param userAgent
  106.      *            user agent string
  107.      * @return extracted version number
  108.      */
  109.     public static VersionNumber parseOperatingSystemVersion(@Nonnull final OperatingSystemFamily family, @Nonnull final String userAgent) {
  110.         Check.notNull(family, "family");
  111.         Check.notNull(userAgent, "userAgent");
  112.         return VersionParser.parseOperatingSystemVersion(family, userAgent);
  113.     }

  115.     /**
  116.      * Interprets a string with version information. The first found group will be taken and processed.
  117.      * 
  118.      * @param version
  119.      *            version as string
  120.      * @return an object of {@code VersionNumber}, never {@code null}
  121.      */
  122.     public static VersionNumber parseVersion(@Nonnull final String version) {
  123.         return VersionParser.parseVersion(Check.notNull(version, "version"));
  124.     }

  126.     /**
  127.      * Replaces all {@code null} values in the given list of groups with {@code VersionNumber#EMPTY_GROUP}.
  128.      * 
  129.      * @param groups
  130.      *            list of numbers of a version number
  131.      * @return a new list of groups without {@code null} values
  132.      */
  133.     public static List<String> replaceNullValueWithEmptyGroup(@Nonnull final List<String> groups) {
  134.         Check.notNull(groups, "groups");

  136.         final List<String> result = new ArrayList<String>(groups.size());
  137.         for (final String group : groups) {
  138.             if (group == null) {
  139.                 result.add(EMPTY_GROUP);
  140.             } else {
  141.                 result.add(group);
  142.             }
  143.         }
  144.         for (int i = result.size(); i < MIN_GROUP_SIZE; i++) {
  145.             result.add(EMPTY_GROUP);
  146.         }
  147.         return result;
  148.     }

  150.     /**
  151.      * Converts the given list of numbers in a version string. The groups of the version number will be separated by a
  152.      * dot.
  153.      * 
  154.      * @param groups
  155.      *            list of numbers of a version number
  156.      * @return a formated version string
  157.      */
  158.     private static String toVersionString(@Nonnull final List<String> groups) {
  159.         final StringBuilder builder = new StringBuilder(6);
  160.         int count = 0;
  161.         for (final String segment : groups) {
  162.             if (EMPTY_GROUP.equals(segment)) {
  163.                 break;
  164.             } else {
  165.                 if (count > 0) {
  166.                     builder.append(SEPARATOR);
  167.                 }
  168.                 builder.append(segment);
  169.             }
  170.             count++;
  171.         }
  172.         return builder.toString();
  173.     }

  175.     /**
  176.      * Extension or suffix of the version number consisting of alphanumeric and special characters
  177.      */
  178.     @Nonnull
  179.     private final String extension;

  181.     /**
  182.      * Groups, segments or categories of the version number
  183.      */
  184.     @Nonnull
  185.     private final List<String> groups;

  187.     /**
  188.      * Constructs a {@code VersionNumber} with the given numeric groups, such as major, minor and bugfix number.
  189.      * 
  190.      * @param groups
  191.      *            list of numbers of a version number
  192.      * @throws net.sf.qualitycheck.exception.IllegalNullArgumentException
  193.      *             if the given argument is {@code null}
  194.      * @throws net.sf.qualitycheck.exception.IllegalStateOfArgumentException
  195.      *             if one of the segments of the version number is smaller than 0 and not empty
  196.      */
  197.     public VersionNumber(@Nonnull final List<String> groups) {
  198.         this(groups, EMPTY_EXTENSION);
  199.     }

  201.     /**
  202.      * Constructs a {@code VersionNumber} with the given numeric groups, such as major, minor and bugfix number and
  203.      * extension.
  204.      * 
  205.      * @param groups
  206.      *            list of numbers of a version number
  207.      * @param extension
  208.      *            extension of a version number
  209.      * @throws net.sf.qualitycheck.exception.IllegalNullArgumentException
  210.      *             if one of the given arguments is {@code null}
  211.      * @throws net.sf.qualitycheck.exception.IllegalStateOfArgumentException
  212.      *             if one of the groups of the version number is not empty or a positive number
  213.      */
  214.     public VersionNumber(@Nonnull final List<String> groups, @Nonnull final String extension) {
  215.         Check.notNull(groups, "groups");
  216.         Check.notNull(extension, "extension");

  218.         final List<String> segments = replaceNullValueWithEmptyGroup(groups);
  219.         int i = 0;
  220.         for (final String segment : segments) {
  221.             if (!EMPTY_GROUP.equals(segment) && !isNumeric(segment)) {
  222.                 throw new IllegalStateOfArgumentException("The segment on position " + i + " (" + segment + ") must be a number.");
  223.             }
  224.             i++;
  225.         }

  227.         this.groups = segments;
  228.         this.extension = extension;
  229.     }

  231.     /**
  232.      * Constructs a {@code VersionNumber} with the given major number and without a minor and bugfix number.
  233.      * 
  234.      * @param major
  235.      *            major group of the version number
  236.      * @throws net.sf.qualitycheck.exception.IllegalNullArgumentException
  237.      *             if the given argument is {@code null}
  238.      * @throws net.sf.qualitycheck.exception.IllegalStateOfArgumentException
  239.      *             if the major segment is smaller than 0 and not empty
  240.      */
  241.     public VersionNumber(@Nonnull final String major) {
  242.         this(Check.notNull(major, "major"), EMPTY_GROUP);
  243.     }

  245.     /**
  246.      * Constructs a {@code VersionNumber} with the given major, minor number and without a bugfix number.
  247.      * 
  248.      * @param major
  249.      *            major group of the version number
  250.      * @param minor
  251.      *            minor group of the version number
  252.      * @throws net.sf.qualitycheck.exception.IllegalNullArgumentException
  253.      *             if one of the given arguments is {@code null}
  254.      * @throws net.sf.qualitycheck.exception.IllegalStateOfArgumentException
  255.      *             if the major or minor segment is smaller than 0 and not empty
  256.      */
  257.     public VersionNumber(@Nonnull final String major, @Nonnull final String minor) {
  258.         this(Check.notNull(major, "major"), Check.notNull(minor, "minor"), EMPTY_GROUP);
  259.     }

  261.     /**
  262.      * Constructs a {@code VersionNumber} with the given major, minor and bugfix number.
  263.      * 
  264.      * @param major
  265.      *            major group of the version number
  266.      * @param minor
  267.      *            minor group of the version number
  268.      * @param bugfix
  269.      *            bugfix group of the version number
  270.      * @throws net.sf.qualitycheck.exception.IllegalNullArgumentException
  271.      *             if one of the given arguments is {@code null}
  272.      * @throws net.sf.qualitycheck.exception.IllegalStateOfArgumentException
  273.      *             if the major, minor or bugfix segment is smaller than 0 and not empty
  274.      */
  275.     public VersionNumber(@Nonnull final String major, @Nonnull final String minor, @Nonnull final String bugfix) {
  276.         this(Check.notNull(major, "major"), Check.notNull(minor, "minor"), Check.notNull(bugfix, "bugfix"), EMPTY_EXTENSION);
  277.     }

  279.     /**
  280.      * Constructs a {@code VersionNumber} with the given major, minor and bugfix number and extension.
  281.      * 
  282.      * @param major
  283.      *            major group of the version number
  284.      * @param minor
  285.      *            minor group of the version number
  286.      * @param bugfix
  287.      *            bugfix group of the version number
  288.      * @param extension
  289.      *            extension of a version number
  290.      * @throws net.sf.qualitycheck.exception.IllegalNullArgumentException
  291.      *             if one of the given arguments is {@code null}
  292.      * @throws net.sf.qualitycheck.exception.IllegalStateOfArgumentException
  293.      *             if the major, minor or bugfix segment is smaller than 0 and not empty
  294.      */
  295.     public VersionNumber(@Nonnull final String major, @Nonnull final String minor, @Nonnull final String bugfix,
  296.             @Nonnull final String extension) {
  297.         this(Arrays.asList(Check.notNull(major, "major"), Check.notNull(minor, "minor"), Check.notNull(bugfix, "bugfix")), Check.notNull(
  298.                 extension, "extension"));
  299.     }

  301.     /**
  302.      * Compares this version number with the specified version number for order. Returns a negative integer, zero, or a
  303.      * positive integer as this version number is less than, equal to, or greater than the specified version number.
  304.      * 
  305.      * @return a negative integer, zero, or a positive integer as this version number is less than, equal to, or greater
  306.      *         than the specified version number.
  307.      */
  308.     @Override
  309.     public int compareTo(@Nullable final ReadableVersionNumber other) {
  310.         int result = 0;
  311.         if (other == null) {
  312.             result = -1;
  313.         } else {
  314.             Check.notNull(other.getGroups(), "other.getGroups()");
  315.             final int length = groups.size() < other.getGroups().size() ? groups.size() : other.getGroups().size();
  316.             final AlphanumComparator comparator = new AlphanumComparator();
  317.             result = comparator.compare(toVersionString(groups.subList(0, length)), toVersionString(other.getGroups().subList(0, length)));
  318.             if (result == 0) {
  319.                 result = groups.size() > other.getGroups().size() ? 1 : groups.size() < other.getGroups().size() ? -1 : 0;
  320.             }
  321.             if (result == 0) {
  322.                 result = extension.compareTo(other.getExtension());
  323.             }
  324.             if (result == 0) {
  325.                 result = comparator.compare(toVersionString(), other.toVersionString());
  326.             }
  327.         }
  328.         return result;
  329.     }

  331.     /**
  332.      * Indicates whether some other object is "equal to" this version number.
  333.      * 
  334.      * @return {@code true} if the given version number is equal to this one
  335.      */
  336.     @Override
  337.     public boolean equals(final Object obj) {
  338.         if (this == obj) {
  339.             return true;
  340.         }
  341.         if (obj == null) {
  342.             return false;
  343.         }
  344.         if (getClass() != obj.getClass()) {
  345.             return false;
  346.         }
  347.         final VersionNumber other = (VersionNumber) obj;
  348.         if (!groups.equals(other.groups)) {
  349.             return false;
  350.         }
  351.         if (!extension.equals(other.extension)) {
  352.             return false;
  353.         }
  354.         return true;
  355.     }

  357.     /**
  358.      * Gets the bugfix category of the version number.
  359.      */
  360.     @Override
  361.     public String getBugfix() {
  362.         return groups.get(2);
  363.     }

  365.     /**
  366.      * Gets the addition or extension of the version number.
  367.      * 
  368.      * @return extension of the version number
  369.      */
  370.     @Override
  371.     public String getExtension() {
  372.         return extension;
  373.     }

  375.     /**
  376.      * Get all groups (or categories) of this version number. The first element in the list is the major category,
  377.      * followed by the minor and bugfix segment of the version number.<br>
  378.      * <br>
  379.      * The returned list of the version number segments is immutable.
  380.      * 
  381.      * @return an unmodifiable view of the of the version number groups
  382.      */
  383.     @Override
  384.     public List<String> getGroups() {
  385.         return Collections.unmodifiableList(groups);
  386.     }

  388.     /**
  389.      * Gets the major category of the version number.
  390.      */
  391.     @Override
  392.     public String getMajor() {
  393.         return groups.get(0);
  394.     }

  396.     /**
  397.      * Gets the major category of the version number.
  398.      */
  399.     @Override
  400.     public String getMinor() {
  401.         return groups.get(1);
  402.     }

  404.     @Override
  405.     public int hashCode() {
  406.         final int prime = 31;
  407.         int result = 1;
  408.         result = prime * result + groups.hashCode();
  409.         result = prime * result + extension.hashCode();
  410.         return result;
  411.     }

  413.     /**
  414.      * Returns a string representation of the version number.
  415.      * 
  416.      * @return a string representation of this version number
  417.      */
  418.     @Nonnull
  419.     @Override
  420.     public String toString() {
  421.         return "VersionNumber [groups=" + groups + ", extension=" + extension + "]";
  422.     }

  424.     /**
  425.      * Gets this version number as string.
  426.      * 
  427.      * @return numeric groups as dot separated version number string
  428.      */
  429.     @Nonnull
  430.     @Override
  431.     public String toVersionString() {
  432.         return toVersionString(groups) + extension;
  433.     }

  435. }
Created with JaCoCo 0.6.2.201302030002