Version


1   /*
2    * $Header: /cvsroot/eclipse/org.eclipse.pde.build/src_ant/org/eclipse/pde/internal/build/tasks/Version.java,v 1.1 2007/02/04 17:03:16 prapicau Exp $
3    * 
4    * Copyright (c) OSGi Alliance (2004, 2006). All Rights Reserved.
5    * 
6    * Licensed under the Apache License, Version 2.0 (the "License");
7    * you may not use this file except in compliance with the License.
8    * You may obtain a copy of the License at
9    *
10   *      http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing, software
13   * distributed under the License is distributed on an "AS IS" BASIS,
14   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15   * See the License for the specific language governing permissions and
16   * limitations under the License.
17   */
18  
19  package org.eclipse.pde.internal.build.tasks;
20  
21  import java.util.NoSuchElementException  ;
22  import java.util.StringTokenizer  ;
23  
24  /**
25   * Version identifier for bundles and packages.
26   * 
27   * <p>
28   * Version identifiers have four components.
29   * <ol>
30   * <li>Major version. A non-negative integer.</li>
31   * <li>Minor version. A non-negative integer.</li>
32   * <li>Micro version. A non-negative integer.</li>
33   * <li>Qualifier. A text string. See <code>Version(String)</code> for the
34   * format of the qualifier string.</li>
35   * </ol>
36   * 
37   * <p>
38   * <code>Version</code> objects are immutable.
39   * 
40   * @version $Revision: 1.1 $
41   * @since 1.3
42   */
43  
44  public class Version implements Comparable   {
45      private final int           major;
46      private final int           minor;
47      private final int           micro;
48      private final String          qualifier;
49      private static final String   SEPARATOR       = ".";                  //$NON-NLS-1$
50  
51      /**
52       * The empty version "0.0.0". Equivalent to calling
53       * <code>new Version(0,0,0)</code>.
54       */
55      public static final Version emptyVersion    = new Version(0, 0, 0);
56  
57      /**
58       * Creates a version identifier from the specified numerical components.
59       * 
60       * <p>
61       * The qualifier is set to the empty string.
62       * 
63       * @param major Major component of the version identifier.
64       * @param minor Minor component of the version identifier.
65       * @param micro Micro component of the version identifier.
66       * @throws IllegalArgumentException If the numerical components are
67       *         negative.
68       */
69      public Version(int major, int minor, int micro) {
70          this(major, minor, micro, null);
71      }
72  
73      /**
74       * Creates a version identifier from the specifed components.
75       * 
76       * @param major Major component of the version identifier.
77       * @param minor Minor component of the version identifier.
78       * @param micro Micro component of the version identifier.
79       * @param qualifier Qualifier component of the version identifier. If
80       *        <code>null</code> is specified, then the qualifier will be set
81       *        to the empty string.
82       * @throws IllegalArgumentException If the numerical components are negative
83       *         or the qualifier string is invalid.
84       */
85      public Version(int major, int minor, int micro, String   qualifier) {
86          if (qualifier == null) {
87              qualifier = ""; //$NON-NLS-1$
88          }
89  
90          this.major = major;
91          this.minor = minor;
92          this.micro = micro;
93          this.qualifier = qualifier;
94          validate();
95      }
96  
97      /**
98       * Created a version identifier from the specified string.
99       * 
100      * <p>
101      * Here is the grammar for version strings.
102      * 
103      * <pre>
104      * version ::= major('.'minor('.'micro('.'qualifier)?)?)?
105      * major ::= digit+
106      * minor ::= digit+
107      * micro ::= digit+
108      * qualifier ::= (alpha|digit|'_'|'-')+
109      * digit ::= [0..9]
110      * alpha ::= [a..zA..Z]
111      * </pre>
112      * 
113      * There must be no whitespace in version.
114      * 
115      * @param version String representation of the version identifier.
116      * @throws IllegalArgumentException If <code>version</code> is improperly
117      *         formatted.
118      */
119     public Version(String   version) {
120         int major = 0;
121         int minor = 0;
122         int micro = 0;
123         String   qualifier = ""; //$NON-NLS-1$
124 
125         try {
126             StringTokenizer   st = new StringTokenizer  (version, SEPARATOR, true);
127             major = Integer.parseInt(st.nextToken());
128 
129             if (st.hasMoreTokens()) {
130                 st.nextToken(); // consume delimiter
131                 minor = Integer.parseInt(st.nextToken());
132 
133                 if (st.hasMoreTokens()) {
134                     st.nextToken(); // consume delimiter
135                     micro = Integer.parseInt(st.nextToken());
136 
137                     if (st.hasMoreTokens()) {
138                         st.nextToken(); // consume delimiter
139                         qualifier = st.nextToken();
140 
141                         if (st.hasMoreTokens()) {
142                             throw new IllegalArgumentException  ("invalid format"); //$NON-NLS-1$
143                         }
144                     }
145                 }
146             }
147         }
148         catch (NoSuchElementException   e) {
149             throw new IllegalArgumentException  ("invalid format"); //$NON-NLS-1$
150         }
151 
152         this.major = major;
153         this.minor = minor;
154         this.micro = micro;
155         this.qualifier = qualifier;
156         validate();
157     }
158 
159     /**
160      * Called by the Version constructors to validate the version components.
161      * 
162      * @throws IllegalArgumentException If the numerical components are negative
163      *         or the qualifier string is invalid.
164      */
165     private void validate() {
166         if (major < 0) {
167             throw new IllegalArgumentException  ("negative major"); //$NON-NLS-1$
168         }
169         if (minor < 0) {
170             throw new IllegalArgumentException  ("negative minor"); //$NON-NLS-1$
171         }
172         if (micro < 0) {
173             throw new IllegalArgumentException  ("negative micro"); //$NON-NLS-1$
174         }
175         int length = qualifier.length();
176         for (int i = 0; i < length; i++) {
177             if ("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_-".indexOf(qualifier.charAt(i)) == -1) { //$NON-NLS-1$
178                 throw new IllegalArgumentException  ("invalid qualifier"); //$NON-NLS-1$
179             }
180         }
181     }
182 
183     /**
184      * Parses a version identifier from the specified string.
185      * 
186      * <p>
187      * See <code>Version(String)</code> for the format of the version string.
188      * 
189      * @param version String representation of the version identifier. Leading
190      *        and trailing whitespace will be ignored.
191      * @return A <code>Version</code> object representing the version
192      *         identifier. If <code>version</code> is <code>null</code> or
193      *         the empty string then <code>emptyVersion</code> will be
194      *         returned.
195      * @throws IllegalArgumentException If <code>version</code> is improperly
196      *         formatted.
197      */
198     public static Version parseVersion(String   version) {
199         if (version == null) {
200             return emptyVersion;
201         }
202 
203         version = version.trim();
204         if (version.length() == 0) {
205             return emptyVersion;
206         }
207 
208         return new Version(version);
209     }
210 
211     /**
212      * Returns the major component of this version identifier.
213      * 
214      * @return The major component.
215      */
216     public int getMajor() {
217         return major;
218     }
219 
220     /**
221      * Returns the minor component of this version identifier.
222      * 
223      * @return The minor component.
224      */
225     public int getMinor() {
226         return minor;
227     }
228 
229     /**
230      * Returns the micro component of this version identifier.
231      * 
232      * @return The micro component.
233      */
234     public int getMicro() {
235         return micro;
236     }
237 
238     /**
239      * Returns the qualifier component of this version identifier.
240      * 
241      * @return The qualifier component.
242      */
243     public String   getQualifier() {
244         return qualifier;
245     }
246 
247     /**
248      * Returns the string representation of this version identifier.
249      * 
250      * <p>
251      * The format of the version string will be <code>major.minor.micro</code>
252      * if qualifier is the empty string or
253      * <code>major.minor.micro.qualifier</code> otherwise.
254      * 
255      * @return The string representation of this version identifier.
256      */
257     public String   toString() {
258         String   base = major + SEPARATOR + minor + SEPARATOR + micro;
259         if (qualifier.length() == 0) { //$NON-NLS-1$
260             return base;
261         }
262         else {
263             return base + SEPARATOR + qualifier;
264         }
265     }
266 
267     /**
268      * Returns a hash code value for the object.
269      * 
270      * @return An integer which is a hash code value for this object.
271      */
272     public int hashCode() {
273         return (major << 24) + (minor << 16) + (micro << 8)
274                 + qualifier.hashCode();
275     }
276 
277     /**
278      * Compares this <code>Version</code> object to another object.
279      * 
280      * <p>
281      * A version is considered to be <b>equal to </b> another version if the
282      * major, minor and micro components are equal and the qualifier component
283      * is equal (using <code>String.equals</code>).
284      * 
285      * @param object The <code>Version</code> object to be compared.
286      * @return <code>true</code> if <code>object</code> is a
287      *         <code>Version</code> and is equal to this object;
288      *         <code>false</code> otherwise.
289      */
290     public boolean equals(Object   object) {
291         if (object == this) { // quicktest
292             return true;
293         }
294 
295         if (!(object instanceof Version)) {
296             return false;
297         }
298 
299         Version other = (Version) object;
300         return (major == other.major) && (minor == other.minor)
301                 && (micro == other.micro) && qualifier.equals(other.qualifier);
302     }
303 
304     /**
305      * Compares this <code>Version</code> object to another object.
306      * 
307      * <p>
308      * A version is considered to be <b>less than </b> another version if its
309      * major component is less than the other version's major component, or the
310      * major components are equal and its minor component is less than the other
311      * version's minor component, or the major and minor components are equal
312      * and its micro component is less than the other version's micro component,
313      * or the major, minor and micro components are equal and it's qualifier
314      * component is less than the other version's qualifier component (using
315      * <code>String.compareTo</code>).
316      * 
317      * <p>
318      * A version is considered to be <b>equal to</b> another version if the
319      * major, minor and micro components are equal and the qualifier component
320      * is equal (using <code>String.compareTo</code>).
321      * 
322      * @param object The <code>Version</code> object to be compared.
323      * @return A negative integer, zero, or a positive integer if this object is
324      *         less than, equal to, or greater than the specified
325      *         <code>Version</code> object.
326      * @throws ClassCastException If the specified object is not a
327      *         <code>Version</code>.
328      */
329     public int compareTo(Object   object) {
330         if (object == this) { // quicktest
331             return 0;
332         }
333 
334         Version other = (Version) object;
335 
336         int result = major - other.major;
337         if (result != 0) {
338             return result;
339         }
340 
341         result = minor - other.minor;
342         if (result != 0) {
343             return result;
344         }
345 
346         result = micro - other.micro;
347         if (result != 0) {
348             return result;
349         }
350 
351         return qualifier.compareTo(other.qualifier);
352     }
353 }
354
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags