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.ObjectUtil.checkNotNull;
21
22 /**
23 * The request method of HTTP or its derived protocols, such as
24 * <a href="https://en.wikipedia.org/wiki/Real_Time_Streaming_Protocol">RTSP</a> and
25 * <a href="https://en.wikipedia.org/wiki/Internet_Content_Adaptation_Protocol">ICAP</a>.
26 */
27 public class HttpMethod implements Comparable<HttpMethod> {
28
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(AsciiString.cached("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(AsciiString.cached("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(AsciiString.cached("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(AsciiString.cached("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(AsciiString.cached("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(AsciiString.cached("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(AsciiString.cached("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(AsciiString.cached("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(AsciiString.cached("CONNECT"));
87
88 /**
89 * The QUERY method requests that the request target process the enclosed content in a safe and
90 * idempotent manner and then respond with the result of that processing.
91 */
92 public static final HttpMethod QUERY = new HttpMethod(AsciiString.cached("QUERY"));
93
94 /**
95 * Returns the {@link HttpMethod} represented by the specified name.
96 * If the specified name is a standard HTTP method name, a cached instance
97 * will be returned. Otherwise, a new instance will be returned.
98 */
99 public static HttpMethod valueOf(String name) {
100 switch (name) {
101 case "OPTIONS": return HttpMethod.OPTIONS;
102 case "GET": return HttpMethod.GET;
103 case "HEAD": return HttpMethod.HEAD;
104 case "POST": return HttpMethod.POST;
105 case "PUT": return HttpMethod.PUT;
106 case "PATCH": return HttpMethod.PATCH;
107 case "DELETE": return HttpMethod.DELETE;
108 case "TRACE": return HttpMethod.TRACE;
109 case "CONNECT": return HttpMethod.CONNECT;
110 case "QUERY": return HttpMethod.QUERY;
111 default: return new HttpMethod(name);
112 }
113 }
114
115 private final AsciiString name;
116
117 /**
118 * Private constructor for the built-in constants defined in this class.
119 * The names are compiler-controlled literals that are already valid HTTP tokens,
120 * so there is no need to validate or trim them at runtime.
121 */
122 private HttpMethod(AsciiString name) {
123 this.name = name;
124 }
125
126 /**
127 * Creates a new HTTP method with the specified name. You will not need to
128 * create a new method unless you are implementing a protocol derived from
129 * HTTP, such as
130 * <a href="https://en.wikipedia.org/wiki/Real_Time_Streaming_Protocol">RTSP</a> and
131 * <a href="https://en.wikipedia.org/wiki/Internet_Content_Adaptation_Protocol">ICAP</a>
132 */
133 public HttpMethod(String name) {
134 checkNotNull(name, "name");
135 // The name must be non-empty and contain only valid HTTP token characters.
136 if (name.isEmpty()) {
137 throw new IllegalArgumentException("name cannot be empty");
138 }
139 int index = HttpHeaderValidationUtil.validateToken(name);
140 if (index != -1) {
141 throw new IllegalArgumentException(
142 "Illegal character in HTTP Method: 0x" + Integer.toHexString(name.charAt(index)));
143 }
144 this.name = AsciiString.cached(name);
145 }
146
147 /**
148 * Returns the name of this method.
149 */
150 public String name() {
151 return name.toString();
152 }
153
154 /**
155 * Returns the name of this method.
156 */
157 public AsciiString asciiName() {
158 return name;
159 }
160
161 @Override
162 public int hashCode() {
163 return name().hashCode();
164 }
165
166 @Override
167 public boolean equals(Object o) {
168 if (this == o) {
169 return true;
170 }
171 if (!(o instanceof HttpMethod)) {
172 return false;
173 }
174
175 HttpMethod that = (HttpMethod) o;
176 return name().equals(that.name());
177 }
178
179 @Override
180 public String toString() {
181 return name.toString();
182 }
183
184 @Override
185 public int compareTo(HttpMethod o) {
186 if (o == this) {
187 return 0;
188 }
189 return name().compareTo(o.name());
190 }
191
192 }