KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > avalon > framework > Version


1 /* ====================================================================
2  * The Apache Software License, Version 1.1
3  *
4  * Copyright (c) 1997-2003 The Apache Software Foundation. All rights
5  * reserved.
6  *
7  * Redistribution and use in source and binary forms, with or without
8  * modification, are permitted provided that the following conditions
9  * are met:
10  *
11  * 1. Redistributions of source code must retain the above copyright
12  * notice, this list of conditions and the following disclaimer.
13  *
14  * 2. Redistributions in binary form must reproduce the above copyright
15  * notice, this list of conditions and the following disclaimer in
16  * the documentation and/or other materials provided with the
17  * distribution.
18  *
19  * 3. The end-user documentation included with the redistribution,
20  * if any, must include the following acknowledgment:
21  * "This product includes software developed by the
22  * Apache Software Foundation (http://www.apache.org/)."
23  * Alternately, this acknowledgment may appear in the software
24  * itself, if and wherever such third-party acknowledgments
25  * normally appear.
26  *
27  * 4. The names "Jakarta", "Avalon", and "Apache Software Foundation"
28  * must not be used to endorse or promote products derived from this
29  * software without prior written permission. For written
30  * permission, please contact apache@apache.org.
31  *
32  * 5. Products derived from this software may not be called "Apache",
33  * nor may "Apache" appear in their name, without prior written
34  * permission of the Apache Software Foundation.
35  *
36  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
37  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
38  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
39  * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
40  * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
41  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
42  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
43  * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
44  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
45  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
46  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
47  * SUCH DAMAGE.
48  * ====================================================================
49  *
50  * This software consists of voluntary contributions made by many
51  * individuals on behalf of the Apache Software Foundation. For more
52  * information on the Apache Software Foundation, please see
53  * <http://www.apache.org/>.
54  */
55 package org.apache.avalon.framework;
56
57 import java.io.Serializable JavaDoc;
58 import java.util.StringTokenizer JavaDoc;
59
60 /**
61  * This class is used to hold version information pertaining to a Component or interface.
62  * <p />
63  *
64  * The version number of a <code>Component</code> is made up of three
65  * dot-separated fields:
66  * <p />
67  * &quot;<b>major.minor.micro</b>&quot;
68  * <p />
69  * The <b>major</b>, <b>minor</b> and <b>micro</b> fields are
70  * <i>integer</i> numbers represented in decimal notation and have the
71  * following meaning:
72  * <ul>
73  *
74  * <p /><li><b>major</b> - When the major version changes (in ex. from
75  * &quot;1.5.12&quot; to &quot;2.0.0&quot;), then backward compatibility
76  * with previous releases is not granted.</li><p />
77  *
78  * <p /><li><b>minor</b> - When the minor version changes (in ex. from
79  * &quot;1.5.12&quot; to &quot;1.6.0&quot;), then backward compatibility
80  * with previous releases is granted, but something changed in the
81  * implementation of the Component. (ie it methods could have been added)</li><p />
82  *
83  * <p /><li><b>micro</b> - When the micro version changes (in ex.
84  * from &quot;1.5.12&quot; to &quot;1.5.13&quot;), then the the changes are
85  * small forward compatible bug fixes or documentation modifications etc.
86  * </li>
87  * </ul>
88  *
89  * @author <a HREF="mailto:dev@avalon.apache.org">Avalon Development Team</a>
90  * @version CVS $Revision: 1.26 $ $Date: 2003/02/11 16:19:27 $
91  */
92 public final class Version
93     implements Serializable JavaDoc
94 {
95     private int m_major;
96     private int m_minor;
97     private int m_micro;
98
99     /**
100      * Parse a version out of a string.
101      * The version string format is <major>.<minor>.<micro> where
102      * both minor and micro are optional.
103      *
104      * @param version The input version string
105      * @return the new Version object
106      * @throws NumberFormatException if an error occurs
107      * @throws IllegalArgumentException if an error occurs
108      * @since 4.1
109      */
110     public static Version getVersion( final String JavaDoc version )
111         throws NumberFormatException JavaDoc, IllegalArgumentException JavaDoc
112     {
113         final StringTokenizer JavaDoc tokenizer = new StringTokenizer JavaDoc( version, "." );
114         final String JavaDoc[] levels = new String JavaDoc[ tokenizer.countTokens() ];
115         for( int i = 0; i < levels.length; i++ )
116         {
117             levels[ i ] = tokenizer.nextToken();
118         }
119
120         if( 0 == levels.length || 3 < levels.length )
121         {
122             throw new IllegalArgumentException JavaDoc( "Malformed version string " + version );
123         }
124
125         final int major = Integer.parseInt( levels[ 0 ] );
126
127         int minor = 0;
128         if( 1 < levels.length )
129         {
130             minor = Integer.parseInt( levels[ 1 ] );
131         }
132
133         int micro = 0;
134         if( 2 < levels.length )
135         {
136             micro = Integer.parseInt( levels[ 2 ] );
137         }
138
139         return new Version( major, minor, micro );
140     }
141
142     /**
143      * Create a new instance of a <code>Version</code> object with the
144      * specified version numbers.
145      *
146      * @param major This <code>Version</code> major number.
147      * @param minor This <code>Version</code> minor number.
148      * @param micro This <code>Version</code> micro number.
149      */
150     public Version( final int major, final int minor, final int micro )
151     {
152         m_major = major;
153         m_minor = minor;
154         m_micro = micro;
155     }
156
157     /**
158      * Retrieve major component of version.
159      *
160      * @return the major component of version
161      * @since 4.1
162      */
163     public int getMajor()
164     {
165         return m_major;
166     }
167
168     /**
169      * Retrieve minor component of version.
170      *
171      * @return the minor component of version
172      * @since 4.1
173      */
174     public int getMinor()
175     {
176         return m_minor;
177     }
178
179     /**
180      * Retrieve micro component of version.
181      *
182      * @return the micro component of version.
183      * @since 4.1
184      */
185     public int getMicro()
186     {
187         return m_micro;
188     }
189
190     /**
191      * Check this <code>Version</code> against another for equality.
192      * <p />
193      * If this <code>Version</code> is compatible with the specified one, then
194      * <b>true</b> is returned, otherwise <b>false</b>.
195      *
196      * @param other The other <code>Version</code> object to be compared with this
197      * for equality.
198      * @return <b>true</b> if this <code>Version</code> is compatible with the specified one
199      * @since 4.1
200      */
201     public boolean equals( final Version other )
202     {
203         if( m_major != other.m_major )
204         {
205             return false;
206         }
207         else if( m_minor != other.m_minor )
208         {
209             return false;
210         }
211         else if( m_micro != other.m_micro )
212         {
213             return false;
214         }
215         else
216         {
217             return true;
218         }
219     }
220
221     /**
222      * Indicates whether some other object is "equal to" this <code>Version</code>.
223      * Returns <b>true</b> if the other object is an instance of <code>Version</code>
224      * and has the same major, minor, and micro components.
225      *
226      * @param other an <code>Object</code> value
227      * @return <b>true</b> if the other object is equal to this <code>Version</code>
228      */
229     public boolean equals( final Object JavaDoc other )
230     {
231         if( other instanceof Version )
232         {
233             return equals( (Version)other );
234         }
235         else
236         {
237             return false;
238         }
239     }
240
241     /**
242      * Check this <code>Version</code> against another for compliancy
243      * (compatibility).
244      * <p />
245      * If this <code>Version</code> is compatible with the specified one, then
246      * <b>true</b> is returned, otherwise <b>false</b>. Be careful when using
247      * this method since, in example, version 1.3.7 is compliant to version
248      * 1.3.6, while the opposite is not.
249      * <p />
250      * The following example displays the expected behaviour and results of version.
251      * <pre>
252      * final Version v1 = new Version( 1, 3 , 6 );
253      * final Version v2 = new Version( 1, 3 , 7 );
254      * final Version v3 = new Version( 1, 4 , 0 );
255      * final Version v4 = new Version( 2, 0 , 1 );
256      *
257      * assert( v1.complies( v1 ) );
258      * assert( ! v1.complies( v2 ) );
259      * assert( v2.complies( v1 ) );
260      * assert( ! v1.complies( v3 ) );
261      * assert( v3.complies( v1 ) );
262      * assert( ! v1.complies( v4 ) );
263      * assert( ! v4.complies( v1 ) );
264      * </pre>
265      *
266      * @param other The other <code>Version</code> object to be compared with this
267      * for compliancy (compatibility).
268      * @return <b>true</b> if this <code>Version</code> is compatible with the specified one
269      */
270     public boolean complies( final Version other )
271     {
272         if( m_major != other.m_major )
273         {
274             return false;
275         }
276         else if( m_minor < other.m_minor )
277         {
278             //If of major version but lower minor version then incompatible
279 return false;
280         }
281         else if( m_minor == other.m_minor
282             && m_micro < other.m_micro )
283         {
284             //If same major version, same minor version but lower micro level
285 //then incompatible
286 return false;
287         }
288         else
289         {
290             return true;
291         }
292     }
293
294     /**
295      * Overload toString to report version correctly.
296      *
297      * @return the dot seperated version string
298      */
299     public String JavaDoc toString()
300     {
301         return m_major + "." + m_minor + "." + m_micro;
302     }
303 }
304
Popular Tags