1 /*
2  * Copyright 2012 The Netty Project
3  *
4  * The Netty Project licenses this file to you under the Apache License,
5  * version 2.0 (the "License"); you may not use this file except in compliance
6  * with the License. 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, WITHOUT
12  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13  * License for the specific language governing permissions and limitations
14  * under the License.
15  */

16 package io.netty.handler.codec.http;
17
18 import io.netty.util.AsciiString;
19
20 import static io.netty.util.internal.MathUtil.findNextPositivePowerOfTwo;
21 import static io.netty.util.internal.ObjectUtil.checkNotNull;
22
23 /**
24  * The request method of HTTP or its derived protocols, such as
25  * <a href="http://en.wikipedia.org/wiki/Real_Time_Streaming_Protocol">RTSP</a> and
26  * <a href="http://en.wikipedia.org/wiki/Internet_Content_Adaptation_Protocol">ICAP</a>.
27  */

28 public class HttpMethod implements Comparable<HttpMethod> {
29     /**
30      * The OPTIONS method represents a request for information about the communication options
31      * available on the request/response chain identified by the Request-URI. This method allows
32      * the client to determine the options and/or requirements associated with a resource, or the
33      * capabilities of a server, without implying a resource action or initiating a resource
34      * retrieval.
35      */

36     public static final HttpMethod OPTIONS = new HttpMethod("OPTIONS");
37
38     /**
39      * The GET method means retrieve whatever information (in the form of an entity) is identified
40      * by the Request-URI.  If the Request-URI refers to a data-producing process, it is the
41      * produced data which shall be returned as the entity in the response and not the source text
42      * of the process, unless that text happens to be the output of the process.
43      */

44     public static final HttpMethod GET = new HttpMethod("GET");
45
46     /**
47      * The HEAD method is identical to GET except that the server MUST NOT return a message-body
48      * in the response.
49      */

50     public static final HttpMethod HEAD = new HttpMethod("HEAD");
51
52     /**
53      * The POST method is used to request that the origin server accept the entity enclosed in the
54      * request as a new subordinate of the resource identified by the Request-URI in the
55      * Request-Line.
56      */

57     public static final HttpMethod POST = new HttpMethod("POST");
58
59     /**
60      * The PUT method requests that the enclosed entity be stored under the supplied Request-URI.
61      */

62     public static final HttpMethod PUT = new HttpMethod("PUT");
63
64     /**
65      * The PATCH method requests that a set of changes described in the
66      * request entity be applied to the resource identified by the Request-URI.
67      */

68     public static final HttpMethod PATCH = new HttpMethod("PATCH");
69
70     /**
71      * The DELETE method requests that the origin server delete the resource identified by the
72      * Request-URI.
73      */

74     public static final HttpMethod DELETE = new HttpMethod("DELETE");
75
76     /**
77      * The TRACE method is used to invoke a remote, application-layer loop- back of the request
78      * message.
79      */

80     public static final HttpMethod TRACE = new HttpMethod("TRACE");
81
82     /**
83      * This specification reserves the method name CONNECT for use with a proxy that can dynamically
84      * switch to being a tunnel
85      */

86     public static final HttpMethod CONNECT = new HttpMethod("CONNECT");
87
88     private static final EnumNameMap<HttpMethod> methodMap;
89
90     static {
91         methodMap = new EnumNameMap<HttpMethod>(
92                 new EnumNameMap.Node<HttpMethod>(OPTIONS.toString(), OPTIONS),
93                 new EnumNameMap.Node<HttpMethod>(GET.toString(), GET),
94                 new EnumNameMap.Node<HttpMethod>(HEAD.toString(), HEAD),
95                 new EnumNameMap.Node<HttpMethod>(POST.toString(), POST),
96                 new EnumNameMap.Node<HttpMethod>(PUT.toString(), PUT),
97                 new EnumNameMap.Node<HttpMethod>(PATCH.toString(), PATCH),
98                 new EnumNameMap.Node<HttpMethod>(DELETE.toString(), DELETE),
99                 new EnumNameMap.Node<HttpMethod>(TRACE.toString(), TRACE),
100                 new EnumNameMap.Node<HttpMethod>(CONNECT.toString(), CONNECT));
101     }
102
103     /**
104      * Returns the {@link HttpMethod} represented by the specified name.
105      * If the specified name is a standard HTTP method name, a cached instance
106      * will be returned.  Otherwise, a new instance will be returned.
107      */

108     public static HttpMethod valueOf(String name) {
109         HttpMethod result = methodMap.get(name);
110         return result != null ? result : new HttpMethod(name);
111     }
112
113     private final AsciiString name;
114
115     /**
116      * Creates a new HTTP method with the specified name.  You will not need to
117      * create a new method unless you are implementing a protocol derived from
118      * HTTP, such as
119      * <a href="http://en.wikipedia.org/wiki/Real_Time_Streaming_Protocol">RTSP</a> and
120      * <a href="http://en.wikipedia.org/wiki/Internet_Content_Adaptation_Protocol">ICAP</a>
121      */

122     public HttpMethod(String name) {
123         name = checkNotNull(name, "name").trim();
124         if (name.isEmpty()) {
125             throw new IllegalArgumentException("empty name");
126         }
127
128         for (int i = 0; i < name.length(); i ++) {
129             char c = name.charAt(i);
130             if (Character.isISOControl(c) || Character.isWhitespace(c)) {
131                 throw new IllegalArgumentException("invalid character in name");
132             }
133         }
134
135         this.name = AsciiString.cached(name);
136     }
137
138     /**
139      * Returns the name of this method.
140      */

141     public String name() {
142         return name.toString();
143     }
144
145     /**
146      * Returns the name of this method.
147      */

148     public AsciiString asciiName() {
149         return name;
150     }
151
152     @Override
153     public int hashCode() {
154         return name().hashCode();
155     }
156
157     @Override
158     public boolean equals(Object o) {
159         if (this == o) {
160             return true;
161         }
162         if (!(o instanceof HttpMethod)) {
163             return false;
164         }
165
166         HttpMethod that = (HttpMethod) o;
167         return name().equals(that.name());
168     }
169
170     @Override
171     public String toString() {
172         return name.toString();
173     }
174
175     @Override
176     public int compareTo(HttpMethod o) {
177         if (o == this) {
178             return 0;
179         }
180         return name().compareTo(o.name());
181     }
182
183     private static final class EnumNameMap<T> {
184         private final EnumNameMap.Node<T>[] values;
185         private final int valuesMask;
186
187         EnumNameMap(EnumNameMap.Node<T>... nodes) {
188             values = (EnumNameMap.Node<T>[]) new EnumNameMap.Node[findNextPositivePowerOfTwo(nodes.length)];
189             valuesMask = values.length - 1;
190             for (EnumNameMap.Node<T> node : nodes) {
191                 int i = hashCode(node.key) & valuesMask;
192                 if (values[i] != null) {
193                     throw new IllegalArgumentException("index " + i + " collision between values: [" +
194                             values[i].key + ", " + node.key + ']');
195                 }
196                 values[i] = node;
197             }
198         }
199
200         T get(String name) {
201             EnumNameMap.Node<T> node = values[hashCode(name) & valuesMask];
202             return node == null || !node.key.equals(name) ? null : node.value;
203         }
204
205         private static int hashCode(String name) {
206             // This hash code needs to produce a unique index in the "values" array for each HttpMethod. If new
207             // HttpMethods are added this algorithm will need to be adjusted. The constructor will "fail fast" if there
208             // are duplicates detected.
209             // For example with the current set of HttpMethods it just so happens that the String hash code value
210             // shifted right by 6 bits modulo 16 is unique relative to all other HttpMethod values.
211             return name.hashCode() >>> 6;
212         }
213
214         private static final class Node<T> {
215             final String key;
216             final T value;
217
218             Node(String key, T value) {
219                 this.key = key;
220                 this.value = value;
221             }
222         }
223     }
224 }
225