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      * <p>
109      * The default implementation in this class returns {@code this}
110      * if the version matches, and creates a new {@link ProtocolVersion}
111      * otherwise.
112      * </p>
113      *
114      * @param major     the major version
115      * @param minor     the minor version
116      *
117      * @return  a protocol version with the same protocol name
118      *          and the argument version
119      */
120     public ProtocolVersion forVersion(final int major, final int minor) {
121 
122         if ((major == this.major) && (minor == this.minor)) {
123             return this;
124         }
125 
126         // argument checking is done in the constructor
127         return new ProtocolVersion(this.protocol, major, minor);
128     }
129 
130 
131     /**
132      * Obtains a hash code consistent with {@link #equals}.
133      *
134      * @return  the hashcode of this protocol version
135      */
136     @Override
137     public final int hashCode() {
138         return this.protocol.hashCode() ^ (this.major * 100000) ^ this.minor;
139     }
140 
141 
142     /**
143      * Checks equality of this protocol version with an object.
144      * The object is equal if it is a protocl version with the same
145      * protocol name, major version number, and minor version number.
146      * The specific class of the object is <i>not</i> relevant,
147      * instances of derived classes with identical attributes are
148      * equal to instances of the base class and vice versa.
149      *
150      * @param obj       the object to compare with
151      *
152      * @return  {@code true} if the argument is the same protocol version,
153      *          {@code false} otherwise
154      */
155     @Override
156     public final boolean equals(final Object obj) {
157         if (this == obj) {
158             return true;
159         }
160         if (!(obj instanceof ProtocolVersion)) {
161             return false;
162         }
163         final ProtocolVersion that = (ProtocolVersion) obj;
164 
165         return ((this.protocol.equals(that.protocol)) &&
166                 (this.major == that.major) &&
167                 (this.minor == that.minor));
168     }
169 
170 
171     /**
172      * Checks whether this protocol can be compared to another one.
173      * Only protocol versions with the same protocol name can be
174      * {@link #compareToVersion compared}.
175      *
176      * @param that      the protocol version to consider
177      *
178      * @return  {@code true} if {@link #compareToVersion compareToVersion}
179      *          can be called with the argument, {@code false} otherwise
180      */
181     public boolean isComparable(final ProtocolVersion that) {
182         return (that != null) && this.protocol.equals(that.protocol);
183     }
184 
185 
186     /**
187      * Compares this protocol version with another one.
188      * Only protocol versions with the same protocol name can be compared.
189      * This method does <i>not</i> define a total ordering, as it would be
190      * required for {@link java.lang.Comparable}.
191      *
192      * @param that      the protocol version to compare with
193      *
194      * @return   a negative integer, zero, or a positive integer
195      *           as this version is less than, equal to, or greater than
196      *           the argument version.
197      *
198      * @throws IllegalArgumentException
199      *         if the argument has a different protocol name than this object,
200      *         or if the argument is {@code null}
201      */
202     public int compareToVersion(final ProtocolVersion that) {
203         Args.notNull(that, "Protocol version");
204         Args.check(this.protocol.equals(that.protocol),
205                 "Versions for different protocols cannot be compared: %s %s", this, that);
206         int delta = getMajor() - that.getMajor();
207         if (delta == 0) {
208             delta = getMinor() - that.getMinor();
209         }
210         return delta;
211     }
212 
213 
214     /**
215      * Tests if this protocol version is greater or equal to the given one.
216      *
217      * @param version   the version against which to check this version
218      *
219      * @return  {@code true} if this protocol version is
220      *          {@link #isComparable comparable} to the argument
221      *          and {@link #compareToVersion compares} as greater or equal,
222      *          {@code false} otherwise
223      */
224     public final boolean greaterEquals(final ProtocolVersion version) {
225         return isComparable(version) && (compareToVersion(version) >= 0);
226     }
227 
228 
229     /**
230      * Tests if this protocol version is less or equal to the given one.
231      *
232      * @param version   the version against which to check this version
233      *
234      * @return  {@code true} if this protocol version is
235      *          {@link #isComparable comparable} to the argument
236      *          and {@link #compareToVersion compares} as less or equal,
237      *          {@code false} otherwise
238      */
239     public final boolean lessEquals(final ProtocolVersion version) {
240         return isComparable(version) && (compareToVersion(version) <= 0);
241     }
242 
243 
244     /**
245      * Converts this protocol version to a string.
246      *
247      * @return  a protocol version string, like "HTTP/1.1"
248      */
249     @Override
250     public String toString() {
251         final StringBuilder buffer = new StringBuilder();
252         buffer.append(this.protocol);
253         buffer.append('/');
254         buffer.append(Integer.toString(this.major));
255         buffer.append('.');
256         buffer.append(Integer.toString(this.minor));
257         return buffer.toString();
258     }
259 
260     @Override
261     public Object clone() throws CloneNotSupportedException {
262         return super.clone();
263     }
264 
265 }