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 * https://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.checkNonEmptyAfterTrim;
22
23 /**
24 * The request method of HTTP or its derived protocols, such as
25 * <a href="https://en.wikipedia.org/wiki/Real_Time_Streaming_Protocol">RTSP</a> and
26 * <a href="https://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 // fast-path
110 if (name == HttpMethod.GET.name()) {
111 return HttpMethod.GET;
112 }
113 if (name == HttpMethod.POST.name()) {
114 return HttpMethod.POST;
115 }
116 // "slow"-path
117 HttpMethod result = methodMap.get(name);
118 return result != null ? result : new HttpMethod(name);
119 }
120
121 private final AsciiString name;
122
123 /**
124 * Creates a new HTTP method with the specified name. You will not need to
125 * create a new method unless you are implementing a protocol derived from
126 * HTTP, such as
127 * <a href="https://en.wikipedia.org/wiki/Real_Time_Streaming_Protocol">RTSP</a> and
128 * <a href="https://en.wikipedia.org/wiki/Internet_Content_Adaptation_Protocol">ICAP</a>
129 */
130 public HttpMethod(String name) {
131 name = checkNonEmptyAfterTrim(name, "name");
132
133 for (int i = 0; i < name.length(); i ++) {
134 char c = name.charAt(i);
135 if (Character.isISOControl(c) || Character.isWhitespace(c)) {
136 throw new IllegalArgumentException("invalid character in name");
137 }
138 }
139
140 this.name = AsciiString.cached(name);
141 }
142
143 /**
144 * Returns the name of this method.
145 */
146 public String name() {
147 return name.toString();
148 }
149
150 /**
151 * Returns the name of this method.
152 */
153 public AsciiString asciiName() {
154 return name;
155 }
156
157 @Override
158 public int hashCode() {
159 return name().hashCode();
160 }
161
162 @Override
163 public boolean equals(Object o) {
164 if (this == o) {
165 return true;
166 }
167 if (!(o instanceof HttpMethod)) {
168 return false;
169 }
170
171 HttpMethod that = (HttpMethod) o;
172 return name().equals(that.name());
173 }
174
175 @Override
176 public String toString() {
177 return name.toString();
178 }
179
180 @Override
181 public int compareTo(HttpMethod o) {
182 if (o == this) {
183 return 0;
184 }
185 return name().compareTo(o.name());
186 }
187
188 private static final class EnumNameMap<T> {
189 private final EnumNameMap.Node<T>[] values;
190 private final int valuesMask;
191
192 EnumNameMap(EnumNameMap.Node<T>... nodes) {
193 values = (EnumNameMap.Node<T>[]) new EnumNameMap.Node[findNextPositivePowerOfTwo(nodes.length)];
194 valuesMask = values.length - 1;
195 for (EnumNameMap.Node<T> node : nodes) {
196 int i = hashCode(node.key) & valuesMask;
197 if (values[i] != null) {
198 throw new IllegalArgumentException("index " + i + " collision between values: [" +
199 values[i].key + ", " + node.key + ']');
200 }
201 values[i] = node;
202 }
203 }
204
205 T get(String name) {
206 EnumNameMap.Node<T> node = values[hashCode(name) & valuesMask];
207 return node == null || !node.key.equals(name) ? null : node.value;
208 }
209
210 private static int hashCode(String name) {
211 // This hash code needs to produce a unique index in the "values" array for each HttpMethod. If new
212 // HttpMethods are added this algorithm will need to be adjusted. The constructor will "fail fast" if there
213 // are duplicates detected.
214 // For example with the current set of HttpMethods it just so happens that the String hash code value
215 // shifted right by 6 bits modulo 16 is unique relative to all other HttpMethod values.
216 return name.hashCode() >>> 6;
217 }
218
219 private static final class Node<T> {
220 final String key;
221 final T value;
222
223 Node(String key, T value) {
224 this.key = key;
225 this.value = value;
226 }
227 }
228 }
229 }