View Javadoc

1   /*
2    * ====================================================================
3    * Licensed to the Apache Software Foundation (ASF) under one
4    * or more contributor license agreements.  See the NOTICE file
5    * distributed with this work for additional information
6    * regarding copyright ownership.  The ASF licenses this file
7    * to you under the Apache License, Version 2.0 (the
8    * "License"); you may not use this file except in compliance
9    * with the License.  You may obtain a copy of the License at
10   *
11   *   http://www.apache.org/licenses/LICENSE-2.0
12   *
13   * Unless required by applicable law or agreed to in writing,
14   * software distributed under the License is distributed on an
15   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16   * KIND, either express or implied.  See the License for the
17   * specific language governing permissions and limitations
18   * under the License.
19   * ====================================================================
20   *
21   * This software consists of voluntary contributions made by many
22   * individuals on behalf of the Apache Software Foundation.  For more
23   * information on the Apache Software Foundation, please see
24   * <http://www.apache.org/>.
25   *
26   */
27  
28  package org.apache.http;
29  
30  import java.io.Serializable;
31  
32  import org.apache.http.annotation.Immutable;
33  import org.apache.http.util.Args;
34  
35  /**
36   * Represents a protocol version. The "major.minor" numbering
37   * scheme is used to indicate versions of the protocol.
38   * <p>
39   * This class defines a protocol version as a combination of
40   * protocol name, major version number, and minor version number.
41   * Note that {@link #equals} and {@link #hashCode} are defined as
42   * final here, they cannot be overridden in derived classes.
43   * </p>
44   *
45   * @since 4.0
46   */
47  @Immutable
48  public class ProtocolVersion implements Serializable, Cloneable {
49  
50      private static final long serialVersionUID = 8950662842175091068L;
51  
52  
53      /** Name of the protocol. */
54      protected final String protocol;
55  
56      /** Major version number of the protocol */
57      protected final int major;
58  
59      /** Minor version number of the protocol */
60      protected final int minor;
61  
62  
63      /**
64       * Create a protocol version designator.
65       *
66       * @param protocol   the name of the protocol, for example "HTTP"
67       * @param major      the major version number of the protocol
68       * @param minor      the minor version number of the protocol
69       */
70      public ProtocolVersion(final String protocol, final int major, final int minor) {
71          this.protocol = Args.notNull(protocol, "Protocol name");
72          this.major = Args.notNegative(major, "Protocol minor version");
73          this.minor = Args.notNegative(minor, "Protocol minor version");
74      }
75  
76      /**
77       * Returns the name of the protocol.
78       *
79       * @return the protocol name
80       */
81      public final String getProtocol() {
82          return protocol;
83      }
84  
85      /**
86       * Returns the major version number of the protocol.
87       *
88       * @return the major version number.
89       */
90      public final int getMajor() {
91          return major;
92      }
93  
94      /**
95       * Returns the minor version number of the HTTP protocol.
96       *
97       * @return the minor version number.
98       */
99      public final int getMinor() {
100         return minor;
101     }
102 
103 
104     /**
105      * Obtains a specific version of this protocol.
106      * This can be used by derived classes to instantiate themselves instead
107      * of the base class, and to define constants for commonly used versions.
108      * <br/>
109      * The default implementation in this class returns <code>this</code>
110      * if the version matches, and creates a new {@link ProtocolVersion}
111      * otherwise.
112      *
113      * @param major     the major version
114      * @param minor     the minor version
115      *
116      * @return  a protocol version with the same protocol name
117      *          and the argument version
118      */
119     public ProtocolVersion forVersion(final int major, final int minor) {
120 
121         if ((major == this.major) && (minor == this.minor)) {
122             return this;
123         }
124 
125         // argument checking is done in the constructor
126         return new ProtocolVersion(this.protocol, major, minor);
127     }
128 
129 
130     /**
131      * Obtains a hash code consistent with {@link #equals}.
132      *
133      * @return  the hashcode of this protocol version
134      */
135     @Override
136     public final int hashCode() {
137         return this.protocol.hashCode() ^ (this.major * 100000) ^ this.minor;
138     }
139 
140 
141     /**
142      * Checks equality of this protocol version with an object.
143      * The object is equal if it is a protocl version with the same
144      * protocol name, major version number, and minor version number.
145      * The specific class of the object is <i>not</i> relevant,
146      * instances of derived classes with identical attributes are
147      * equal to instances of the base class and vice versa.
148      *
149      * @param obj       the object to compare with
150      *
151      * @return  <code>true</code> if the argument is the same protocol version,
152      *          <code>false</code> otherwise
153      */
154     @Override
155     public final boolean equals(final Object obj) {
156         if (this == obj) {
157             return true;
158         }
159         if (!(obj instanceof ProtocolVersion)) {
160             return false;
161         }
162         final ProtocolVersion that = (ProtocolVersion) obj;
163 
164         return ((this.protocol.equals(that.protocol)) &&
165                 (this.major == that.major) &&
166                 (this.minor == that.minor));
167     }
168 
169 
170     /**
171      * Checks whether this protocol can be compared to another one.
172      * Only protocol versions with the same protocol name can be
173      * {@link #compareToVersion compared}.
174      *
175      * @param that      the protocol version to consider
176      *
177      * @return  <code>true</code> if {@link #compareToVersion compareToVersion}
178      *          can be called with the argument, <code>false</code> otherwise
179      */
180     public boolean isComparable(final ProtocolVersion that) {
181         return (that != null) && this.protocol.equals(that.protocol);
182     }
183 
184 
185     /**
186      * Compares this protocol version with another one.
187      * Only protocol versions with the same protocol name can be compared.
188      * This method does <i>not</i> define a total ordering, as it would be
189      * required for {@link java.lang.Comparable}.
190      *
191      * @param that      the protocol version to compare with
192      *
193      * @return   a negative integer, zero, or a positive integer
194      *           as this version is less than, equal to, or greater than
195      *           the argument version.
196      *
197      * @throws IllegalArgumentException
198      *         if the argument has a different protocol name than this object,
199      *         or if the argument is <code>null</code>
200      */
201     public int compareToVersion(final ProtocolVersion that) {
202         Args.notNull(that, "Protocol version");
203         Args.check(this.protocol.equals(that.protocol),
204                 "Versions for different protocols cannot be compared: %s %s", this, that);
205         int delta = getMajor() - that.getMajor();
206         if (delta == 0) {
207             delta = getMinor() - that.getMinor();
208         }
209         return delta;
210     }
211 
212 
213     /**
214      * Tests if this protocol version is greater or equal to the given one.
215      *
216      * @param version   the version against which to check this version
217      *
218      * @return  <code>true</code> if this protocol version is
219      *          {@link #isComparable comparable} to the argument
220      *          and {@link #compareToVersion compares} as greater or equal,
221      *          <code>false</code> otherwise
222      */
223     public final boolean greaterEquals(final ProtocolVersion version) {
224         return isComparable(version) && (compareToVersion(version) >= 0);
225     }
226 
227 
228     /**
229      * Tests if this protocol version is less or equal to the given one.
230      *
231      * @param version   the version against which to check this version
232      *
233      * @return  <code>true</code> if this protocol version is
234      *          {@link #isComparable comparable} to the argument
235      *          and {@link #compareToVersion compares} as less or equal,
236      *          <code>false</code> otherwise
237      */
238     public final boolean lessEquals(final ProtocolVersion version) {
239         return isComparable(version) && (compareToVersion(version) <= 0);
240     }
241 
242 
243     /**
244      * Converts this protocol version to a string.
245      *
246      * @return  a protocol version string, like "HTTP/1.1"
247      */
248     @Override
249     public String toString() {
250         final StringBuilder buffer = new StringBuilder();
251         buffer.append(this.protocol);
252         buffer.append('/');
253         buffer.append(Integer.toString(this.major));
254         buffer.append('.');
255         buffer.append(Integer.toString(this.minor));
256         return buffer.toString();
257     }
258 
259     @Override
260     public Object clone() throws CloneNotSupportedException {
261         return super.clone();
262     }
263 
264 }