--- /dev/null
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF 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 javax.servlet;
+
+import java.io.BufferedReader;
+import java.io.IOException;
+import java.util.Enumeration;
+import java.util.Locale;
+import java.util.Map;
+
+/**
+ * Defines an object to provide client request information to a servlet. The
+ * servlet container creates a <code>ServletRequest</code> object and passes it
+ * as an argument to the servlet's <code>service</code> method.
+ * <p>
+ * A <code>ServletRequest</code> object provides data including parameter name
+ * and values, attributes, and an input stream. Interfaces that extend
+ * <code>ServletRequest</code> can provide additional protocol-specific data
+ * (for example, HTTP data is provided by
+ * {@link javax.servlet.http.HttpServletRequest}.
+ *
+ * @see javax.servlet.http.HttpServletRequest
+ */
+public interface ServletRequest {
+
+ /**
+ * Returns the value of the named attribute as an <code>Object</code>, or
+ * <code>null</code> if no attribute of the given name exists.
+ * <p>
+ * Attributes can be set two ways. The servlet container may set attributes
+ * to make available custom information about a request. For example, for
+ * requests made using HTTPS, the attribute
+ * <code>javax.servlet.request.X509Certificate</code> can be used to
+ * retrieve information on the certificate of the client. Attributes can
+ * also be set programatically using {@link ServletRequest#setAttribute}.
+ * This allows information to be embedded into a request before a
+ * {@link RequestDispatcher} call.
+ * <p>
+ * Attribute names should follow the same conventions as package names.
+ * Names beginning with <code>java.*</code> and <code>javax.*</code> are
+ * reserved for use by the Servlet specification. Names beginning with
+ * <code>sun.*</code>, <code>com.sun.*</code>, <code>oracle.*</code> and
+ * <code>com.oracle.*</code>) are reserved for use by Oracle Corporation.
+ *
+ * @param name
+ * a <code>String</code> specifying the name of the attribute
+ * @return an <code>Object</code> containing the value of the attribute, or
+ * <code>null</code> if the attribute does not exist
+ */
+ public Object getAttribute(String name);
+
+ /**
+ * Returns an <code>Enumeration</code> containing the names of the
+ * attributes available to this request. This method returns an empty
+ * <code>Enumeration</code> if the request has no attributes available to
+ * it.
+ *
+ * @return an <code>Enumeration</code> of strings containing the names of the
+ * request's attributes
+ */
+ public Enumeration<String> getAttributeNames();
+
+ /**
+ * Returns the name of the character encoding used in the body of this
+ * request. This method returns <code>null</code> if the request does not
+ * specify a character encoding
+ *
+ * @return a <code>String</code> containing the name of the character
+ * encoding, or <code>null</code> if the request does not specify a
+ * character encoding
+ */
+ public String getCharacterEncoding();
+
+ /**
+ * Overrides the name of the character encoding used in the body of this
+ * request. This method must be called prior to reading request parameters
+ * or reading input using getReader().
+ *
+ * @param env
+ * a <code>String</code> containing the name of the character
+ * encoding.
+ * @throws java.io.UnsupportedEncodingException
+ * if this is not a valid encoding
+ */
+ public void setCharacterEncoding(String env)
+ throws java.io.UnsupportedEncodingException;
+
+ /**
+ * Returns the length, in bytes, of the request body and made available by
+ * the input stream, or -1 if the length is not known. For HTTP servlets,
+ * same as the value of the CGI variable CONTENT_LENGTH.
+ *
+ * @return an integer containing the length of the request body or -1 if the
+ * length is not known or is greater than {@link Integer#MAX_VALUE}
+ */
+ public int getContentLength();
+
+ /**
+ * Returns the length, in bytes, of the request body and made available by
+ * the input stream, or -1 if the length is not known. For HTTP servlets,
+ * same as the value of the CGI variable CONTENT_LENGTH.
+ *
+ * @return a long integer containing the length of the request body or -1 if
+ * the length is not known
+ */
+ public long getContentLengthLong();
+
+ /**
+ * Returns the MIME type of the body of the request, or <code>null</code> if
+ * the type is not known. For HTTP servlets, same as the value of the CGI
+ * variable CONTENT_TYPE.
+ *
+ * @return a <code>String</code> containing the name of the MIME type of the
+ * request, or null if the type is not known
+ */
+ public String getContentType();
+
+ /**
+ * Retrieves the body of the request as binary data using a
+ * {@link ServletInputStream}. Either this method or {@link #getReader} may
+ * be called to read the body, not both.
+ *
+ * @return a {@link ServletInputStream} object containing the body of the
+ * request
+ * @exception IllegalStateException
+ * if the {@link #getReader} method has already been called
+ * for this request
+ * @exception IOException
+ * if an input or output exception occurred
+ */
+ public ServletInputStream getInputStream() throws IOException;
+
+ /**
+ * Returns the value of a request parameter as a <code>String</code>, or
+ * <code>null</code> if the parameter does not exist. Request parameters are
+ * extra information sent with the request. For HTTP servlets, parameters
+ * are contained in the query string or posted form data.
+ * <p>
+ * You should only use this method when you are sure the parameter has only
+ * one value. If the parameter might have more than one value, use
+ * {@link #getParameterValues}.
+ * <p>
+ * If you use this method with a multivalued parameter, the value returned
+ * is equal to the first value in the array returned by
+ * <code>getParameterValues</code>.
+ * <p>
+ * If the parameter data was sent in the request body, such as occurs with
+ * an HTTP POST request, then reading the body directly via
+ * {@link #getInputStream} or {@link #getReader} can interfere with the
+ * execution of this method.
+ *
+ * @param name
+ * a <code>String</code> specifying the name of the parameter
+ * @return a <code>String</code> representing the single value of the
+ * parameter
+ * @see #getParameterValues
+ */
+ public String getParameter(String name);
+
+ /**
+ * Returns an <code>Enumeration</code> of <code>String</code> objects
+ * containing the names of the parameters contained in this request. If the
+ * request has no parameters, the method returns an empty
+ * <code>Enumeration</code>.
+ *
+ * @return an <code>Enumeration</code> of <code>String</code> objects, each
+ * <code>String</code> containing the name of a request parameter;
+ * or an empty <code>Enumeration</code> if the request has no
+ * parameters
+ */
+ public Enumeration<String> getParameterNames();
+
+ /**
+ * Returns an array of <code>String</code> objects containing all of the
+ * values the given request parameter has, or <code>null</code> if the
+ * parameter does not exist.
+ * <p>
+ * If the parameter has a single value, the array has a length of 1.
+ *
+ * @param name
+ * a <code>String</code> containing the name of the parameter
+ * whose value is requested
+ * @return an array of <code>String</code> objects containing the parameter's
+ * values
+ * @see #getParameter
+ */
+ public String[] getParameterValues(String name);
+
+ /**
+ * Returns a java.util.Map of the parameters of this request. Request
+ * parameters are extra information sent with the request. For HTTP
+ * servlets, parameters are contained in the query string or posted form
+ * data.
+ *
+ * @return an immutable java.util.Map containing parameter names as keys and
+ * parameter values as map values. The keys in the parameter map are
+ * of type String. The values in the parameter map are of type
+ * String array.
+ */
+ public Map<String, String[]> getParameterMap();
+
+ /**
+ * Returns the name and version of the protocol the request uses in the form
+ * <i>protocol/majorVersion.minorVersion</i>, for example, HTTP/1.1. For
+ * HTTP servlets, the value returned is the same as the value of the CGI
+ * variable <code>SERVER_PROTOCOL</code>.
+ *
+ * @return a <code>String</code> containing the protocol name and version
+ * number
+ */
+ public String getProtocol();
+
+ /**
+ * Returns the name of the scheme used to make this request, for example,
+ * <code>http</code>, <code>https</code>, or <code>ftp</code>. Different
+ * schemes have different rules for constructing URLs, as noted in RFC 1738.
+ *
+ * @return a <code>String</code> containing the name of the scheme used to
+ * make this request
+ */
+ public String getScheme();
+
+ /**
+ * Returns the host name of the server to which the request was sent. It is
+ * the value of the part before ":" in the <code>Host</code> header value,
+ * if any, or the resolved server name, or the server IP address.
+ *
+ * @return a <code>String</code> containing the name of the server
+ */
+ public String getServerName();
+
+ /**
+ * Returns the port number to which the request was sent. It is the value of
+ * the part after ":" in the <code>Host</code> header value, if any, or the
+ * server port where the client connection was accepted on.
+ *
+ * @return an integer specifying the port number
+ */
+ public int getServerPort();
+
+ /**
+ * Retrieves the body of the request as character data using a
+ * <code>BufferedReader</code>. The reader translates the character data
+ * according to the character encoding used on the body. Either this method
+ * or {@link #getInputStream} may be called to read the body, not both.
+ *
+ * @return a <code>BufferedReader</code> containing the body of the request
+ * @exception java.io.UnsupportedEncodingException
+ * if the character set encoding used is not supported and
+ * the text cannot be decoded
+ * @exception IllegalStateException
+ * if {@link #getInputStream} method has been called on this
+ * request
+ * @exception IOException
+ * if an input or output exception occurred
+ * @see #getInputStream
+ */
+ public BufferedReader getReader() throws IOException;
+
+ /**
+ * Returns the Internet Protocol (IP) address of the client or last proxy
+ * that sent the request. For HTTP servlets, same as the value of the CGI
+ * variable <code>REMOTE_ADDR</code>.
+ *
+ * @return a <code>String</code> containing the IP address of the client
+ * that sent the request
+ */
+ public String getRemoteAddr();
+
+ /**
+ * Returns the fully qualified name of the client or the last proxy that
+ * sent the request. If the engine cannot or chooses not to resolve the
+ * hostname (to improve performance), this method returns the dotted-string
+ * form of the IP address. For HTTP servlets, same as the value of the CGI
+ * variable <code>REMOTE_HOST</code>.
+ *
+ * @return a <code>String</code> containing the fully qualified name of the
+ * client
+ */
+ public String getRemoteHost();
+
+ /**
+ * Stores an attribute in this request. Attributes are reset between
+ * requests. This method is most often used in conjunction with
+ * {@link RequestDispatcher}.
+ * <p>
+ * Attribute names should follow the same conventions as package names.
+ * Names beginning with <code>java.*</code> and <code>javax.*</code> are
+ * reserved for use by the Servlet specification. Names beginning with
+ * <code>sun.*</code>, <code>com.sun.*</code>, <code>oracle.*</code> and
+ * <code>com.oracle.*</code>) are reserved for use by Oracle Corporation.
+ * <br>
+ * If the object passed in is null, the effect is the same as calling
+ * {@link #removeAttribute}. <br>
+ * It is warned that when the request is dispatched from the servlet resides
+ * in a different web application by <code>RequestDispatcher</code>, the
+ * object set by this method may not be correctly retrieved in the caller
+ * servlet.
+ *
+ * @param name
+ * a <code>String</code> specifying the name of the attribute
+ * @param o
+ * the <code>Object</code> to be stored
+ */
+ public void setAttribute(String name, Object o);
+
+ /**
+ * Removes an attribute from this request. This method is not generally
+ * needed as attributes only persist as long as the request is being
+ * handled.
+ * <p>
+ * Attribute names should follow the same conventions as package names.
+ * Names beginning with <code>java.*</code> and <code>javax.*</code> are
+ * reserved for use by the Servlet specification. Names beginning with
+ * <code>sun.*</code>, <code>com.sun.*</code>, <code>oracle.*</code> and
+ * <code>com.oracle.*</code>) are reserved for use by Oracle Corporation.
+ *
+ * @param name
+ * a <code>String</code> specifying the name of the attribute to
+ * remove
+ */
+ public void removeAttribute(String name);
+
+ /**
+ * Returns the preferred <code>Locale</code> that the client will accept
+ * content in, based on the Accept-Language header. If the client request
+ * doesn't provide an Accept-Language header, this method returns the
+ * default locale for the server.
+ *
+ * @return the preferred <code>Locale</code> for the client
+ */
+ public Locale getLocale();
+
+ /**
+ * Returns an <code>Enumeration</code> of <code>Locale</code> objects
+ * indicating, in decreasing order starting with the preferred locale, the
+ * locales that are acceptable to the client based on the Accept-Language
+ * header. If the client request doesn't provide an Accept-Language header,
+ * this method returns an <code>Enumeration</code> containing one
+ * <code>Locale</code>, the default locale for the server.
+ *
+ * @return an <code>Enumeration</code> of preferred <code>Locale</code>
+ * objects for the client
+ */
+ public Enumeration<Locale> getLocales();
+
+ /**
+ * Returns a boolean indicating whether this request was made using a secure
+ * channel, such as HTTPS.
+ *
+ * @return a boolean indicating if the request was made using a secure
+ * channel
+ */
+ public boolean isSecure();
+
+ /**
+ * Returns a {@link RequestDispatcher} object that acts as a wrapper for the
+ * resource located at the given path. A <code>RequestDispatcher</code>
+ * object can be used to forward a request to the resource or to include the
+ * resource in a response. The resource can be dynamic or static.
+ * <p>
+ * The pathname specified may be relative, although it cannot extend outside
+ * the current servlet context. If the path begins with a "/" it is
+ * interpreted as relative to the current context root. This method returns
+ * <code>null</code> if the servlet container cannot return a
+ * <code>RequestDispatcher</code>.
+ * <p>
+ * The difference between this method and
+ * {@link ServletContext#getRequestDispatcher} is that this method can take
+ * a relative path.
+ *
+ * @param path
+ * a <code>String</code> specifying the pathname to the resource.
+ * If it is relative, it must be relative against the current
+ * servlet.
+ * @return a <code>RequestDispatcher</code> object that acts as a wrapper for
+ * the resource at the specified path, or <code>null</code> if the
+ * servlet container cannot return a <code>RequestDispatcher</code>
+ * @see RequestDispatcher
+ * @see ServletContext#getRequestDispatcher
+ */
+ public RequestDispatcher getRequestDispatcher(String path);
+
+ /**
+ * @deprecated As of Version 2.1 of the Java Servlet API, use
+ * {@link ServletContext#getRealPath} instead.
+ */
+ @SuppressWarnings("dep-ann")
+ // Spec API does not use @Deprecated
+ public String getRealPath(String path);
+
+ /**
+ * Returns the Internet Protocol (IP) source port of the client or last
+ * proxy that sent the request.
+ *
+ * @return an integer specifying the port number
+ * @since 2.4
+ */
+ public int getRemotePort();
+
+ /**
+ * Returns the host name of the Internet Protocol (IP) interface on which
+ * the request was received.
+ *
+ * @return a <code>String</code> containing the host name of the IP on which
+ * the request was received.
+ * @since 2.4
+ */
+ public String getLocalName();
+
+ /**
+ * Returns the Internet Protocol (IP) address of the interface on which the
+ * request was received.
+ *
+ * @return a <code>String</code> containing the IP address on which the
+ * request was received.
+ * @since 2.4
+ */
+ public String getLocalAddr();
+
+ /**
+ * Returns the Internet Protocol (IP) port number of the interface on which
+ * the request was received.
+ *
+ * @return an integer specifying the port number
+ * @since 2.4
+ */
+ public int getLocalPort();
+
+ /**
+ * @return TODO
+ * @since Servlet 3.0 TODO SERVLET3 - Add comments
+ */
+ public ServletContext getServletContext();
+
+ /**
+ * @return TODO
+ * @throws java.lang.IllegalStateException
+ * If async is not supported for this request
+ * @since Servlet 3.0 TODO SERVLET3 - Add comments
+ */
+ public AsyncContext startAsync() throws IllegalStateException;
+
+ /**
+ * @param servletRequest
+ * @param servletResponse
+ * @return TODO
+ * @throws java.lang.IllegalStateException
+ * @since Servlet 3.0 TODO SERVLET3 - Add comments
+ */
+ public AsyncContext startAsync(ServletRequest servletRequest,
+ ServletResponse servletResponse) throws IllegalStateException;
+
+ /**
+ * @return TODO
+ * @since Servlet 3.0 TODO SERVLET3 - Add comments
+ */
+ public boolean isAsyncStarted();
+
+ /**
+ * @return TODO
+ * @since Servlet 3.0 TODO SERVLET3 - Add comments
+ */
+ public boolean isAsyncSupported();
+
+ /**
+ * @return TODO
+ * @throws java.lang.IllegalStateException
+ * @since Servlet 3.0 TODO SERVLET3 - Add comments
+ */
+ public AsyncContext getAsyncContext();
+
+ /**
+ * @return TODO
+ * @since Servlet 3.0 TODO SERVLET3 - Add comments
+ */
+ public DispatcherType getDispatcherType();
+}
projects / gigi.git / blobdiff