X-Git-Url: https://code.wpia.club/?p=gigi.git;a=blobdiff_plain;f=lib%2Fservlet-api%2Fjavax%2Fservlet%2FServletRequest.java;fp=lib%2Fservlet-api%2Fjavax%2Fservlet%2FServletRequest.java;h=f32dff3c9c508ca6dd34f2a34bd644065b140493;hp=0000000000000000000000000000000000000000;hb=454e6afd89d77c1005eae4838e74e82fae759668;hpb=c2ca9ecd6facc79051cca2e6d46f211dfd54c7b9 diff --git a/lib/servlet-api/javax/servlet/ServletRequest.java b/lib/servlet-api/javax/servlet/ServletRequest.java new file mode 100644 index 00000000..f32dff3c --- /dev/null +++ b/lib/servlet-api/javax/servlet/ServletRequest.java @@ -0,0 +1,492 @@ +/* + * 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 ServletRequest object and passes it + * as an argument to the servlet's service method. + *

+ * A ServletRequest object provides data including parameter name + * and values, attributes, and an input stream. Interfaces that extend + * ServletRequest 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 Object, or + * null if no attribute of the given name exists. + *

+ * 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 + * javax.servlet.request.X509Certificate 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. + *

+ * Attribute names should follow the same conventions as package names. + * Names beginning with java.* and javax.* are + * reserved for use by the Servlet specification. Names beginning with + * sun.*, com.sun.*, oracle.* and + * com.oracle.*) are reserved for use by Oracle Corporation. + * + * @param name + * a String specifying the name of the attribute + * @return an Object containing the value of the attribute, or + * null if the attribute does not exist + */ + public Object getAttribute(String name); + + /** + * Returns an Enumeration containing the names of the + * attributes available to this request. This method returns an empty + * Enumeration if the request has no attributes available to + * it. + * + * @return an Enumeration of strings containing the names of the + * request's attributes + */ + public Enumeration getAttributeNames(); + + /** + * Returns the name of the character encoding used in the body of this + * request. This method returns null if the request does not + * specify a character encoding + * + * @return a String containing the name of the character + * encoding, or null 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 String 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 null if + * the type is not known. For HTTP servlets, same as the value of the CGI + * variable CONTENT_TYPE. + * + * @return a String 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 String, or + * null 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. + *

+ * 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}. + *

+ * If you use this method with a multivalued parameter, the value returned + * is equal to the first value in the array returned by + * getParameterValues. + *

+ * 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 String specifying the name of the parameter + * @return a String representing the single value of the + * parameter + * @see #getParameterValues + */ + public String getParameter(String name); + + /** + * Returns an Enumeration of String objects + * containing the names of the parameters contained in this request. If the + * request has no parameters, the method returns an empty + * Enumeration. + * + * @return an Enumeration of String objects, each + * String containing the name of a request parameter; + * or an empty Enumeration if the request has no + * parameters + */ + public Enumeration getParameterNames(); + + /** + * Returns an array of String objects containing all of the + * values the given request parameter has, or null if the + * parameter does not exist. + *

+ * If the parameter has a single value, the array has a length of 1. + * + * @param name + * a String containing the name of the parameter + * whose value is requested + * @return an array of String 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 getParameterMap(); + + /** + * Returns the name and version of the protocol the request uses in the form + * protocol/majorVersion.minorVersion, for example, HTTP/1.1. For + * HTTP servlets, the value returned is the same as the value of the CGI + * variable SERVER_PROTOCOL. + * + * @return a String containing the protocol name and version + * number + */ + public String getProtocol(); + + /** + * Returns the name of the scheme used to make this request, for example, + * http, https, or ftp. Different + * schemes have different rules for constructing URLs, as noted in RFC 1738. + * + * @return a String 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 Host header value, + * if any, or the resolved server name, or the server IP address. + * + * @return a String 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 Host 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 + * BufferedReader. 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 BufferedReader 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 REMOTE_ADDR. + * + * @return a String 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 REMOTE_HOST. + * + * @return a String 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}. + *

+ * Attribute names should follow the same conventions as package names. + * Names beginning with java.* and javax.* are + * reserved for use by the Servlet specification. Names beginning with + * sun.*, com.sun.*, oracle.* and + * com.oracle.*) are reserved for use by Oracle Corporation. + *
+ * If the object passed in is null, the effect is the same as calling + * {@link #removeAttribute}.
+ * It is warned that when the request is dispatched from the servlet resides + * in a different web application by RequestDispatcher, the + * object set by this method may not be correctly retrieved in the caller + * servlet. + * + * @param name + * a String specifying the name of the attribute + * @param o + * the Object 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. + *

+ * Attribute names should follow the same conventions as package names. + * Names beginning with java.* and javax.* are + * reserved for use by the Servlet specification. Names beginning with + * sun.*, com.sun.*, oracle.* and + * com.oracle.*) are reserved for use by Oracle Corporation. + * + * @param name + * a String specifying the name of the attribute to + * remove + */ + public void removeAttribute(String name); + + /** + * Returns the preferred Locale 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 Locale for the client + */ + public Locale getLocale(); + + /** + * Returns an Enumeration of Locale 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 Enumeration containing one + * Locale, the default locale for the server. + * + * @return an Enumeration of preferred Locale + * objects for the client + */ + public Enumeration 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 RequestDispatcher + * 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. + *

+ * 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 + * null if the servlet container cannot return a + * RequestDispatcher. + *

+ * The difference between this method and + * {@link ServletContext#getRequestDispatcher} is that this method can take + * a relative path. + * + * @param path + * a String specifying the pathname to the resource. + * If it is relative, it must be relative against the current + * servlet. + * @return a RequestDispatcher object that acts as a wrapper for + * the resource at the specified path, or null if the + * servlet container cannot return a RequestDispatcher + * @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 String 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 String 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(); +}