Java Servlet API documentation (2.1A) (ii)

Description of the Servlet API object \ r
This section contains detailed instructions for all classes and interfaces of the Java Servlet API. This description is similar to the Javadoc API, but this document provides more information.
The API contains two packages, 12 interfaces, and nine classes.
Package: Javax.servlet
The included interfaces: Requestdispatcher;servlet;servletconfig;servletcontext;servletrequest;servletresponse;singlethreadmodel.
Included classes: Genericservlet;servletinputstream;servletoutputstream;servletexception;unavailableexception.

First, RequestDispatcher interface:
Defined:
public interface RequestDispatcher;
Define an object, receive the request from the client, and then send it to the server's available resources (such as servlet, CGI, HTML file, JSP file). The servlet engine creates the request dispatcher object that encapsulates the server resources defined by a specific URL.
This interface is dedicated to encapsulating the servlet, but a servlet engine can create a request dispatcher object to encapsulate any type of resource.
The request dispatcher object was built by the servlet engine, not by the servlet developer.
Method
1, forward
public void forward (ServletRequest request, servletreponse response)
Throws Servletexception, IOException;
is used to deliver requests from this servlet to other server resources. This method can be used when a servlet responds to the response in a preliminary manner and requires other objects to respond to it.
When the request object is passed to the target object, the requested URL path and other path parameters are adjusted to reflect the target URL path of the target object.
If a Servletoutputstream object or PrintWriter object has been returned by a response, this method will not work, otherwise this method throws a illegalstateexception.
2, include
public void include (ServletRequest request, servletresponse response)
Throws Servletexception, IOException
Used to include the content of the response sent to other server resources. Essentially, this method reflects the contents of the server side.
The request URL path and path information for the call request is reflected when the requested object is passed to the target object. This response object can only invoke the Servletoutputstream object and PrintWriter object of this servlet.
A servlet calling include cannot set the header domain, and if the Servlet calls a method (such as a cookie) that must set the header field, this method will not guarantee normal use. As a servlet developer, you must properly address the methods that might store the header domain directly. For example, even if you use session tracking, in order to ensure that sessions are working properly, you must start your conversation outside of a servlet that invokes the include

Second, the servlet interface.
Definition \ r
public interface Servlet
This interface defines a servlet: A Java class that inherits this functionality on a Web server.
Method
1. Init
public void init (ServletConfig config) throws servletexception;
The servlet engine calls the Init method precisely before the servlet is instantiated, before it is placed into service. The Init method must exit successfully before invoking the service method.
If the Init method throws a servletexception, you cannot place the servlet in the service, and if the Init method does not complete within the timeout range, we can also assume that the servlet is non-functional and cannot be placed into the service.
2. Service
public void Service (ServletRequest request, servletresponse response)
Throws Servletexception, IOException;
The servlet engine calls this method to allow the servlet to respond to requests. This method cannot be invoked before the servlet is successfully initialized. The servlet engine can block pending requests until the servlet is initialized.
The servlet engine cannot call this method after a Servlet object is unloaded until a new servelt is initialized
3, Destroy
public void Destroy ();
The servlet engine calls this method when a servlet is removed from the service. The Destroy method cannot be invoked when all threads of this object's service method are not fully exited or the engine does not consider a timeout operation.
4, Getservletconfig
Public ServletConfig getservletconfig ();
Returns a ServletConfig object, as a servlet developer, you should store the ServletConfig object through the Init method so that this method can return the object. For your convenience, Genericservlet has done so in the execution of this interface.
5, Getservletinfo
Public String getservletinfo ();
Allows the servlet to provide information about itself to the servlet runtime of the host. The returned string should be in plain text format without any flags (such as html,xml, etc.).

Three, ServletConfig interface
Definition \ r
public interface ServletConfig
This interface defines an object through which the servlet engine configures a servlet and allows the servlet to obtain a description of its ServletContext interface. Each ServletConfig object corresponds to a unique servlet.
Method
1, Getinitparameter
public string Getinitparameter (string name);
This method returns a string that contains the initialization parameters specified by the servlet. If this parameter does not exist, the null value is returned.
2, Getinitparameternames
Public enumeration getinitparameternames ();
This method returns a list string object that includes all the initialization parameter names for the servlet. If the servlet does not initialize the parameter, Getinitparameternames returns an empty list.
3, Getservletcontext
Public ServletContext getservletcontext ();
Returns the ServletContext object for this servlet.

Four, ServletContext interface
Definition \ r
public interface ServletContext
Defines a servlet's environment object through which the Servlet engine provides environment information to the servlet.
The environment object of a servlet must be at least one by one corresponding to the host on which it resides. In a servlet engine that handles multiple virtual hosts (for example, using HTTP1.1 's primary header domain), each virtual host must be treated as a separate environment. In addition, the servlet engine can create environment objects that correspond to a set of servlet.
Method
1, GetAttribute
Public Object getattribute (String name);
Returns the Property object specified in the Servlet environment object. If the Property object does not exist, a null value is returned. This method allows access to additional information about this servlet engine that is not yet available in other methods of the interface.
2, Getattributenames
Public enumeration getattributenames ();
Returns a list of the property names available in a Servlet environment object.
3, GetContext
Public ServletContext getcontext (String uripath);
Returns a Servlet environment object that includes the servlets and resources of a particular URI path, and returns a null value if the path does not exist. The URI path format is/dir/dir/filename.ext.
For security, if you access the environment object of a restricted servlet through this method, a null value is returned.
4, Getmajorversion
public int getmajorversion ();
Returns the major version number of the Servlet API supported by the servlet engine. For example, for version 2.1, this method returns an integer of 2.
5, Getminorversion
public int getminorversion ();
Returns the minor version number of the Servlet API supported by the servlet engine. For example, for version 2.1, this method returns an integer of 2.
6, GetMimeType
public string GetMimeType (string file);
Returns the MIME type of the specified file, or returns a null value if the MIME type is unknown. The MIME type is determined by the configuration of the servlet engine.
7, Getrealpath
public string Getrealpath (string path);
The format of a specified virtual path that conforms to the URL path format is:/dir/dir/filename.ext. With this method, you can return a string that corresponds to a virtual path that matches the format. The format of this real path should be appropriate for the computer running the servlet engine (including its corresponding path parser).
Whatever the reason, this method returns a null value if the process from which the virtual path is converted to a real path cannot be executed.
8, GetResource
Public URL getresource (String uripath);
Returns a URL object that reflects the resources known to the servlet environment object at the given URL address (format:/dir/dir/filename.ext). Regardless of whether urlstreamhandlers is necessary to access a given environment, the servlet engine must execute. If the servlet environment for the given path does not have a known resource, the method returns a null value.
This method is not exactly the same as the Java.lang.Class GetResource method. Java.lang.Class's GetResource method looks for resources by loading classes. This approach allows the server to generate any servlet that environment variables give to any resource, without having to rely on loading classes, specific zones, and so on.
9, getResourceAsStream
Public InputStream getResourceAsStream (String uripath);
Returns a InputStream object that references the contents of the Servlet environment object for the specified URL. If the servlet environment variable is not found, a null value is returned and the URL path should have this format:/dir/dir/filename.ext.
This method is a convenient way to get the URL object through the GetResource method. Note that when you use this method, meta-information (such as content length, content type) is lost.
10, Getrequestdispatcher
Public RequestDispatcher Getrequestdispatcher (String uripath);
If an active resource (such as a servlet,jsp page, CGI, and so on) can be found under this specified path, the RequestDispatcher object of a particular URL is returned, otherwise a null value is returned, and the servlet engine is responsible for using a request The dispatcher object encapsulates the target path. This request dispatcher object can be used for a fully-requested transfer.
11, Getserverinfo
Public String getserverinfo ();
Returns a String object that includes at least the name and version number of the servlet engine.
12, log
public void log (String msg);
public void log (String msg, Throwable t);
public void log (Exception Exception, String msg); This usage will be canceled \ r
Writes the specified information to a log file of a servlet environment object. The log file being written is specified by the servlet engine, but this is usually an event log. When this method is called by an exception, the log includes the stack trace.
13, SetAttribute
public void setattribute (String name, Object o);
Give the Servlet environment object a name you specified in the object.
14, RemoveAttribute
public void RemoveAttribute (String name);
Deletes a property from the specified Servlet environment object.
Note: The following methods will be canceled \ r
15, Getservlet
Public Servlet Getservlet (String name) throws Servletexception;
A servlet that is originally used to return a specified name and returns a null value if it is not found. If the servlet is able to return, this means that it has been initialized and can accept service requests. This is a dangerous method. When this method is invoked, the state of the servlet may not be known, which can cause problems with the server state. This method of allowing a servlet to access other servlet is also dangerous.
Now this method returns a null value, and in order to maintain compatibility with previous versions, this method has not been canceled. In later versions of the API, the method will be canceled.
16, Getservletnames
Public enumeration getservletnames ();
Originally used to return a list of string objects that represent all known servlet object names in this servlet environment. This list always contains the servlet itself.
This is also a dangerous method, based on the same reason as the previous method.
Now this method returns an empty list. In order to maintain compatibility with previous versions, this method has not been canceled. In later versions of the API, the method will be canceled.
17, Getservlets
Public enumeration getservlets ();
Originally used to return a list of all known servlet objects in this servelet environment. This list always contains the servlet itself.
This is also a dangerous approach, based on the same reasoning as the getservlet approach.
Now this method returns an empty list. In order to maintain compatibility with previous versions, this method has not been canceled. In later versions of the API, the method will be canceled.

Five, ServletRequest interface
Definition \ r
public interface ServletRequest
Defines a servlet engine-generated object through which the servlet can obtain the data requested by the client. This object provides all the data for the name, value, and attributes of the parameter, as well as the input stream, by reading the data of the request body.
Method
1, GetAttribute
Public Object getattribute (String name);
Returns the value of the specified property in the request, and returns a null value if the property does not exist. This method allows access to request information that is not provided to other methods in this interface and other servlet-placed data within the request object.
2, Getattributenames
Public enumeration getattributenames ();
Returns a list of all the property names contained in this request.
3, Getcharacterencoding
Public String getcharacterencoding ();
Returns the character encoding type of the input in the request, which returns a null value if no character encoding type is defined.
4, Getcontentlength
public int getcontentlength ();
The length of the requested content, which returns-1 if the length is unknown.
5, getContentType
Public String getcontenttype ();
Returns the MIME type of the request data body, if the type is unknown, returning a null value.
6, getInputStream
Public ServletInputStream getInputStream () throws IOException;
Returns an input stream used to read binary data from the request body. This method throws a illegalstateexception if the result has been obtained by the Getreader method before.
7, GetParameter
public string GetParameter (string name);
Returns the value of the specified parameter as a string if no null value is returned for this parameter. For example, in an HTTP servlet, this method returns the value of a parameter produced by a specified query statement or the value of a parameter in a submitted form. If a parameter name corresponds to several parameter values, this method can only return the first value in the array returned through the Getparametervalues method. Therefore, if this parameter has (or may have) multiple values, you can only use the Getparametervalues method.
8, Getparameternames
Public enumeration getparameternames ();
Returns a String object list of all parameter names, which returns a null value if there is no input parameter.
9, Getparametervalues
Public string[] Getparametervalues (String name);
Returns the value of the specified parameter through an array of a string object, which returns a null value if the parameter does not exist.
10, Getprotocol
Public String Getprotocol ();
Returns the protocol used for this request in the form of the Protocol/major version number. minor version number. For example, for a HTTP1.0 request, the method returns http/1.0.
11, Getreader
Public BufferedReader Getreader () throws IOException;
This method returns an entity that buffered reader uses to read the request body, encoded in the way that the requested data is encoded. This method throws a illegalstateexception if the input stream of the request has been obtained by the getInputStream call.
12, Getremoteaddr
Public String getremoteaddr ();
Returns the IP address of the sending requester.
13, Getremotehost
Public String getremotehost ();
Returns the host name of the sender who sent the request. This method returns the IP address directly if the engine cannot or chooses not to resolve the host name (in order to improve performance).
14, Getscheme
Public String getscheme ();
Returns the pattern of the URL used by the request. For example, for an HTTP request, this pattern is HTTP.
15, getServerName
Public String getservername ();
Returns the host name of the server that received the request.
16, Getserverport
public int getserverport ();
Returns the port number that receives the request.
17, SetAttribute
public void setattribute (String name, object);
This method adds a property to the request that can be used by other objects that can access the request object, such as a nested servlet.
Note: The following methods will be canceled \ r
Getrealpath
public string Getrealpath (string path);
Returns the true path corresponding to the virtual path, which returns a null value if, for some reason, the procedure cannot be performed.
This method repeats with the Getrealpath method in the ServletContext interface. In version 2.1, the ServletContext interface will illustrate the mapping of all the paths a servlet can use. The result of this method will be exactly the same as the result of the Getrealpath method in ServletContext.

Six, Servletresponse interface
Definition \ r
public interface Servletresponse
Defines a servlet engine-generated object through which the servlet responds to requests from the client. This response should be a MIME entity, possibly an HTML page, image data, or other MIME format.
Method
1, getcharacterencoding
Public String getcharacterencoding ();
Returns the character encoding of a mime entity. The character encoding can be of the specified type, or it can be the most matched type of character encoding acceptable to the client as reflected by the request header field. In the HTTP protocol, this information is transmitted via ACCEPT-CHARSET to the servlet engine.
For more information on character encoding and MIME, see RFC 2047.
2, Getoutputstream
Public Servletoutputstream Getoutputstream () throws IOException;
Returns the output stream of a record binary response data.
If the response object has already called Getwriter, the IllegalStateException will be thrown.
3, Getwriter
Public PrintWriter Getwriter throws IOException;
This method returns a Pringwriter object used to record the formatted response entity. If you want to reflect the character encoding used, you must modify the MIME type of the response. Before calling this method, you must set the content type of the response.
If no such encoding type is provided, a unsupportedencodingexception is thrown, and if the response object has called Getoutputstream, a getoutputstream is thrown.
4, Setcontentlength
public void setcontentlength (int length);
Sets the length of the content of the response, which overrides the previous setting of the content length.
To ensure that the content length of the response header is successfully set, this method must be called before the response is committed to the output stream.
5, setContentType
public void setContentType (String type);
This method is used to set the content type of the response. This type may later be implicitly modified in some other cases, where another scenario may be set for MIME characters when the server finds it necessary.
To ensure that the content type of the response header is successfully set, this method must be called before the response is committed to the output stream.

Seven, Singlethreadmodel interface
Definition \ r
public interface Singlethreadmodel;
This is an empty interface that specifies how the system handles calls to the same servlet. If a servlet is specified by this interface, no two threads will be executed concurrently in the service method in this servlet.
The servlet can implement this guarantee by maintaining a separate servlet instance pool, or by simply having only one thread in the service of the servlet.

Eight, Genericservlet class \ R
Public abstract class Genericservlet implements Servlet,
ServletConfig, Serializable;
The existence of this class makes it more convenient to write a servlet. It provides a simple scenario that is used to perform methods on the servlet lifecycle and to describe the ServletConfig objects and ServletContext objects as they are initialized.
Method
1, destroy
public void Destroy ();
Here the Destroy method does not do any other work.
2, Getinitparameter
public string Getinitparameter (string name);
This is an easy way to call a method with the same name as the ServletConfig object.
3, Getinitparameternames
Public enumeration getinitparameternames ();
This is an easy way to call a method with the same name as the ServletConfig object.
4, Getservletconfig
Public ServletConfig getservletconfig ();
Returns a description of the ServletConfig object produced by the Init method of this class.
5, Getservletcontext
Public ServletContext getservletcontext ();
This is an easy way to call a method with the same name as the ServletConfig object.
6, Getservletinfo
Public String getservletinfo ();
Returns a string that reflects the servlet version.
7. Init
public void Init () throws servletexception;
public void init (ServletConfig config) throws servletexception;
The init (servletconfig config) method is an easy way to initialize the lifecycle of this servlet.
The init () method is used to allow you to extend the Genericservlet class, and you do not need to store config objects or call Super.init (config) when using this method.
The init (servletconfig config) method stores the Config object and then invokes Init (). If you overload this method, you must call Super.init (config) so that other methods of the Genericservlet class will work correctly.
8, log
public void log (String msg);
public void log (String msg, throwable cause);
The Servlet Content object writes the servlet's class name and the given information to the log file.
9. Service
public abstract Void Service (ServletRequest request, Servletresponse
Response) throws Servletexception, IOException;
This is an abstract method, and when you extend the class, you must execute it in order to execute the network request.

Ninth, ServletInputStream class \ R
Definition \ r
Public abstract class ServletInputStream extends InputStream
This class defines an input stream that is used to read the request information of the client. This is an abstract class provided by a servlet engine. A servlet obtains a description of a ServletInputStream object by using the ServletRequest interface.
Subclasses of this class must provide a way to read the information from the InputStream interface.
Method
1, ReadLine
public int readLine (byte[] b, int off, int len) throws IOException;
Reads bytes of the specified length into the specified array, starting at the specified offset of the input stream. If all of the requested contents of the row have been read, the read process will end. If you encounter a new row, the first character of the new line will also be read into the array.

X. Servletoutputstream class \ R
Definition \ r
Public abstract class Servletoutputstream extends OutputStream
This is an abstract class that is used by the servlet engine. The servlet obtains a description of an object of this type by using the use of the Servletresponse interface. This output stream can be used to return data to the client.
Subclasses of this class must provide a way to write information about the OutputStream interface.
In this interface, when a refreshed or closed method is invoked. The information for all data buffers will be sent to the client, which means the response is committed. Note that when you close an object of this type, you do not necessarily close the implied socket stream.
Method
1, print
public void print (String s) throws IOException;
public void Print (Boolean B) throws IOException;
public void print (char c) throws IOException;
public void print (int i) throws IOException;
public void print (long L) throws IOException;
public void print (float f) throws IOException;
public void print (double D) throws IOException;
Output variables to the output stream
2, println
public void println () throws IOException;
public void println (String s) throws IOException;
public void println (Boolean B) throws IOException;
public void println (char c) throws IOException;
public void println (int i) throws IOException;
public void println (long L) throws IOException;
public void println (float f) throws IOException;
public void println (double D) throws IOException;
Output variables into the output stream, and add a carriage return line break \ r

Xi. Servletexception class \ R
Definition \ r
public class Servletexception extends Exception
An exception that is thrown when the servlet encounters a problem.
Constructors
public Servletexception ();
Public servletexception (String message);
Public servletexception (String message, throwable cause);
Public servletexception (Throwable cause);
Constructs a new servletexception, if the constructor includes a throwable parameter, the Throwable object will be used as the reason for this exception to be thrown.
Method
1, Getrootcause
Public Throwable getrootcause ();
If the reason for throwing this exception is configured, this method returns this reason, otherwise a null value is returned.

12, Unavailableexception class \ R
Definition \ r
public class Unavailableexception extends Servletexception
This exception is thrown regardless of whether a servlet is permanently or temporarily invalid. The servlet logs this exception and the appropriate measures to be taken by the servlet engine.
Temporary invalidity means that the servlet is unable to process the request at a certain time due to a temporary problem. For example, a service (possibly a database) at another different application tier cannot be used. This problem may be corrected on its own or other corrective actions need to be taken.
Permanent invalidity means that the servlet will not be able to handle client requests unless the Administrator takes action. For example, this servlet configuration information is missing or the servlet state is corrupted.
The servlet engine can safely handle both exceptions, including permanent invalidity, but normal processing of temporary invalidation can make the servlet engine more robust. In particular, the request to the servlet is only blocked (or postponed) for a period of time, which is obviously more scientific than rejecting the request completely before the service itself restarts.
Constructors
Public Unavailableexception (servlet servlet, String message);
Public unavailableexception (int seconds, servlet servlet,
String message);
Constructs a new exception that contains the specified descriptive information. If this constructor has an argument about the number of seconds, this gives the estimated time that the servlet will be able to process the request after it has been temporarily invalidated. If this argument is not included, this means that the servlet is permanently invalid.
Method
1, Getservlet
Public Servlet Getservlet ();
Returns a servlet with invalid reports. This is used by the servlet engine to identify the affected servlet.
2, Getunavailableseconds
public int getunavailableseconds ();
Returns the invalid time that the servlet expects, if the servlet is permanently invalid, returns-1.
3, Ispermanent
public boolean ispermanent ();
If the servlet is permanently invalid, returns a Boolean value of true, indicating that some administrative action must be taken to make the servlet available.