/*
 * Copyright 2012 The Netty Project
 *
 * The Netty Project licenses this file to you under the Apache License,
 * version 2.0 (the "License"); you may not use this file except in compliance
 * with the License. You may obtain a copy of the License at:
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 * License for the specific language governing permissions and limitations
 * under the License.
 */
package io.netty.handler.codec.http;

import io.netty.util.AsciiString;

import static io.netty.util.internal.MathUtil.findNextPositivePowerOfTwo;
import static io.netty.util.internal.ObjectUtil.checkNotNull;

The request method of HTTP or its derived protocols, such as
RTSP and
ICAP.
/**
 * The request method of HTTP or its derived protocols, such as
 * <a href="http://en.wikipedia.org/wiki/Real_Time_Streaming_Protocol">RTSP</a> and
 * <a href="http://en.wikipedia.org/wiki/Internet_Content_Adaptation_Protocol">ICAP</a>.
 */
public class HttpMethod implements Comparable<HttpMethod> {
    
The OPTIONS method represents a request for information about the communication options
available on the request/response chain identified by the Request-URI. This method allows
the client to determine the options and/or requirements associated with a resource, or the
capabilities of a server, without implying a resource action or initiating a resource
retrieval.
/**
     * The OPTIONS method represents a request for information about the communication options
     * available on the request/response chain identified by the Request-URI. This method allows
     * the client to determine the options and/or requirements associated with a resource, or the
     * capabilities of a server, without implying a resource action or initiating a resource
     * retrieval.
     */
    public static final HttpMethod OPTIONS = new HttpMethod("OPTIONS");

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

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

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

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

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

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

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

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

    private static final EnumNameMap<HttpMethod> methodMap;

    static {
        methodMap = new EnumNameMap<HttpMethod>(
                new EnumNameMap.Node<HttpMethod>(OPTIONS.toString(), OPTIONS),
                new EnumNameMap.Node<HttpMethod>(GET.toString(), GET),
                new EnumNameMap.Node<HttpMethod>(HEAD.toString(), HEAD),
                new EnumNameMap.Node<HttpMethod>(POST.toString(), POST),
                new EnumNameMap.Node<HttpMethod>(PUT.toString(), PUT),
                new EnumNameMap.Node<HttpMethod>(PATCH.toString(), PATCH),
                new EnumNameMap.Node<HttpMethod>(DELETE.toString(), DELETE),
                new EnumNameMap.Node<HttpMethod>(TRACE.toString(), TRACE),
                new EnumNameMap.Node<HttpMethod>(CONNECT.toString(), CONNECT));
    }

    
Returns the HttpMethod represented by the specified name. If the specified name is a standard HTTP method name, a cached instance will be returned. Otherwise, a new instance will be returned. /**
     * Returns the {@link HttpMethod} represented by the specified name.
     * If the specified name is a standard HTTP method name, a cached instance
     * will be returned.  Otherwise, a new instance will be returned.
     */
    public static HttpMethod valueOf(String name) {
        HttpMethod result = methodMap.get(name);
        return result != null ? result : new HttpMethod(name);
    }

    private final AsciiString name;

    
Creates a new HTTP method with the specified name.  You will not need to
create a new method unless you are implementing a protocol derived from
HTTP, such as
RTSP and
ICAP
/**
     * Creates a new HTTP method with the specified name.  You will not need to
     * create a new method unless you are implementing a protocol derived from
     * HTTP, such as
     * <a href="http://en.wikipedia.org/wiki/Real_Time_Streaming_Protocol">RTSP</a> and
     * <a href="http://en.wikipedia.org/wiki/Internet_Content_Adaptation_Protocol">ICAP</a>
     */
    public HttpMethod(String name) {
        name = checkNotNull(name, "name").trim();
        if (name.isEmpty()) {
            throw new IllegalArgumentException("empty name");
        }

        for (int i = 0; i < name.length(); i ++) {
            char c = name.charAt(i);
            if (Character.isISOControl(c) || Character.isWhitespace(c)) {
                throw new IllegalArgumentException("invalid character in name");
            }
        }

        this.name = AsciiString.cached(name);
    }

    
Returns the name of this method.
/**
     * Returns the name of this method.
     */
    public String name() {
        return name.toString();
    }

    
Returns the name of this method.
/**
     * Returns the name of this method.
     */
    public AsciiString asciiName() {
        return name;
    }

    @Override
    public int hashCode() {
        return name().hashCode();
    }

    @Override
    public boolean equals(Object o) {
        if (!(o instanceof HttpMethod)) {
            return false;
        }

        HttpMethod that = (HttpMethod) o;
        return name().equals(that.name());
    }

    @Override
    public String toString() {
        return name.toString();
    }

    @Override
    public int compareTo(HttpMethod o) {
        return name().compareTo(o.name());
    }

    private static final class EnumNameMap<T> {
        private final EnumNameMap.Node<T>[] values;
        private final int valuesMask;

        EnumNameMap(EnumNameMap.Node<T>... nodes) {
            values = (EnumNameMap.Node<T>[]) new EnumNameMap.Node[findNextPositivePowerOfTwo(nodes.length)];
            valuesMask = values.length - 1;
            for (EnumNameMap.Node<T> node : nodes) {
                int i = hashCode(node.key) & valuesMask;
                if (values[i] != null) {
                    throw new IllegalArgumentException("index " + i + " collision between values: [" +
                            values[i].key + ", " + node.key + ']');
                }
                values[i] = node;
            }
        }

        T get(String name) {
            EnumNameMap.Node<T> node = values[hashCode(name) & valuesMask];
            return node == null || !node.key.equals(name) ? null : node.value;
        }

        private static int hashCode(String name) {
            // This hash code needs to produce a unique index in the "values" array for each HttpMethod. If new
            // HttpMethods are added this algorithm will need to be adjusted. The constructor will "fail fast" if there
            // are duplicates detected.
            // For example with the current set of HttpMethods it just so happens that the String hash code value
            // shifted right by 6 bits modulo 16 is unique relative to all other HttpMethod values.
            return name.hashCode() >>> 6;
        }

        private static final class Node<T> {
            final String key;
            final T value;

            Node(String key, T value) {
                this.key = key;
                this.value = value;
            }
        }
    }
}