Author: markt Date: Fri Oct 12 08:24:42 2012 New Revision: 1397465 URL: http://svn.apache.org/viewvc?rev=1397465&view=rev Log: Clean-up - Servlet 3.0 Javadoc - line-length
Modified: tomcat/tc7.0.x/trunk/java/javax/servlet/http/Cookie.java tomcat/tc7.0.x/trunk/java/javax/servlet/http/HttpServlet.java Modified: tomcat/tc7.0.x/trunk/java/javax/servlet/http/Cookie.java URL: http://svn.apache.org/viewvc/tomcat/tc7.0.x/trunk/java/javax/servlet/http/Cookie.java?rev=1397465&r1=1397464&r2=1397465&view=diff ============================================================================== --- tomcat/tc7.0.x/trunk/java/javax/servlet/http/Cookie.java (original) +++ tomcat/tc7.0.x/trunk/java/javax/servlet/http/Cookie.java Fri Oct 12 08:24:42 2012 @@ -50,9 +50,6 @@ import java.util.ResourceBundle; * This class supports both the Version 0 (by Netscape) and Version 1 (by RFC * 2109) cookie specifications. By default, cookies are created using Version 0 * to ensure the best interoperability. - * - * @author Various - * @version $Version$ */ public class Cookie implements Cloneable, Serializable { @@ -96,7 +93,7 @@ public class Cookie implements Cloneable * By default, cookies are created according to the Netscape cookie * specification. The version can be changed with the * <code>setVersion</code> method. - * + * * @param name * a <code>String</code> specifying the name of the cookie * @param value @@ -140,7 +137,7 @@ public class Cookie implements Cloneable * Specifies a comment that describes a cookie's purpose. The comment is * useful if the browser presents the cookie to the user. Comments are not * supported by Netscape Version 0 cookies. - * + * * @param purpose * a <code>String</code> specifying the comment to display to the * user @@ -153,7 +150,7 @@ public class Cookie implements Cloneable /** * Returns the comment describing the purpose of this cookie, or * <code>null</code> if the cookie has no comment. - * + * * @return a <code>String</code> containing the comment, or * <code>null</code> if none * @see #setComment @@ -170,7 +167,7 @@ public class Cookie implements Cloneable * visible to servers in a specified Domain Name System (DNS) zone (for * example, <code>www.foo.com</code>, but not <code>a.b.foo.com</code>). By * default, cookies are only returned to the server that sent them. - * + * * @param pattern * a <code>String</code> containing the domain name within which * this cookie is visible; form is according to RFC 2109 @@ -183,7 +180,7 @@ public class Cookie implements Cloneable /** * Returns the domain name set for this cookie. The form of the domain name * is set by RFC 2109. - * + * * @return a <code>String</code> containing the domain name * @see #setDomain */ @@ -201,7 +198,7 @@ public class Cookie implements Cloneable * A negative value means that the cookie is not stored persistently and * will be deleted when the Web browser exits. A zero value causes the * cookie to be deleted. - * + * * @param expiry * an integer specifying the maximum age of the cookie in * seconds; if negative, means the cookie is not stored; if zero, @@ -216,7 +213,7 @@ public class Cookie implements Cloneable * Returns the maximum age of the cookie, specified in seconds, By default, * <code>-1</code> indicating the cookie will persist until browser * shutdown. - * + * * @return an integer specifying the maximum age of the cookie in seconds; if * negative, means the cookie persists until browser shutdown * @see #setMaxAge @@ -237,7 +234,7 @@ public class Cookie implements Cloneable * <p> * Consult RFC 2109 (available on the Internet) for more information on * setting path names for cookies. - * + * * @param uri * a <code>String</code> specifying a path * @see #getPath @@ -249,7 +246,7 @@ public class Cookie implements Cloneable /** * Returns the path on the server to which the browser returns this cookie. * The cookie is visible to all subpaths on the server. - * + * * @return a <code>String</code> specifying a path that contains a servlet * name, for example, <i>/catalog</i> * @see #setPath @@ -263,7 +260,7 @@ public class Cookie implements Cloneable * secure protocol, such as HTTPS or SSL. * <p> * The default value is <code>false</code>. - * + * * @param flag * if <code>true</code>, sends the cookie from the browser to the * server only when using a secure protocol; if @@ -278,7 +275,7 @@ public class Cookie implements Cloneable * Returns <code>true</code> if the browser is sending cookies only over a * secure protocol, or <code>false</code> if the browser can send cookies * using any protocol. - * + * * @return <code>true</code> if the browser uses a secure protocol; * otherwise, <code>true</code> * @see #setSecure @@ -290,7 +287,7 @@ public class Cookie implements Cloneable /** * Returns the name of the cookie. The name cannot be changed after * creation. - * + * * @return a <code>String</code> specifying the cookie's name */ public String getName() { @@ -305,7 +302,7 @@ public class Cookie implements Cloneable * parentheses, equals signs, commas, double quotes, slashes, question * marks, at signs, colons, and semicolons. Empty values may not behave the * same way on all browsers. - * + * * @param newValue * a <code>String</code> specifying the new value * @see #getValue @@ -317,7 +314,7 @@ public class Cookie implements Cloneable /** * Returns the value of the cookie. - * + * * @return a <code>String</code> containing the cookie's present value * @see #setValue * @see Cookie @@ -331,7 +328,7 @@ public class Cookie implements Cloneable * complies with RFC 2109, and version 0 complies with the original cookie * specification drafted by Netscape. Cookies provided by a browser use and * identify the browser's cookie version. - * + * * @return 0 if the cookie complies with the original Netscape specification; * 1 if the cookie complies with RFC 2109 * @see #setVersion @@ -347,7 +344,7 @@ public class Cookie implements Cloneable * <p> * Since RFC 2109 is still somewhat new, consider version 1 as experimental; * do not use it yet on production sites. - * + * * @param v * 0 if the cookie should comply with the original Netscape * specification; 1 if the cookie should comply with RFC 2109 @@ -359,7 +356,7 @@ public class Cookie implements Cloneable // Note -- disabled for now to allow full Netscape compatibility // from RFC 2068, token special case characters - // + // // private static final String tspecials = "()<>@,;:\\\"/[]?={} \t"; private static final String tspecials = ",; "; @@ -394,11 +391,13 @@ public class Cookie implements Cloneable "org.apache.catalina.STRICT_SERVLET_COMPLIANCE", "false")).booleanValue(); - String fwdSlashIsSeparator = System.getProperty("org.apache.tomcat.util.http.ServerCookie.FWD_SLASH_IS_SEPARATOR"); + String fwdSlashIsSeparator = System.getProperty( + "org.apache.tomcat.util.http.ServerCookie.FWD_SLASH_IS_SEPARATOR"); if (fwdSlashIsSeparator == null) { FWD_SLASH_IS_SEPARATOR = STRICT_SERVLET_COMPLIANCE; } else { - FWD_SLASH_IS_SEPARATOR = Boolean.valueOf(fwdSlashIsSeparator).booleanValue(); + FWD_SLASH_IS_SEPARATOR = + Boolean.valueOf(fwdSlashIsSeparator).booleanValue(); } if (FWD_SLASH_IS_SEPARATOR) { @@ -407,7 +406,8 @@ public class Cookie implements Cloneable tspecials2 = tspecials2NoSlash; } - String strictNaming = System.getProperty("org.apache.tomcat.util.http.ServerCookie.STRICT_NAMING"); + String strictNaming = System.getProperty( + "org.apache.tomcat.util.http.ServerCookie.STRICT_NAMING"); if (strictNaming == null) { STRICT_NAMING = STRICT_SERVLET_COMPLIANCE; } else { @@ -451,18 +451,26 @@ public class Cookie implements Cloneable } /** - * @return TODO - * @since Servlet 3.0 TODO SERVLET3 - Add comments + * Sets the flag that controls if this cookie will be hidden from scripts on + * the client side. + * + * @param httpOnly The new value of the flag + * + * @since Servlet 3.0 */ - public boolean isHttpOnly() { - return httpOnly; + public void setHttpOnly(boolean httpOnly) { + this.httpOnly = httpOnly; } /** - * @param httpOnly - * @since Servlet 3.0 TODO SERVLET3 - Add comments + * Gets the flag that controls if this cookie will be hidden from scripts on + * the client side. + * + * @return <code>true</code> if the cookie is hidden from scripts, else + * <code>false</code> + * @since Servlet 3.0 */ - public void setHttpOnly(boolean httpOnly) { - this.httpOnly = httpOnly; + public boolean isHttpOnly() { + return httpOnly; } } Modified: tomcat/tc7.0.x/trunk/java/javax/servlet/http/HttpServlet.java URL: http://svn.apache.org/viewvc/tomcat/tc7.0.x/trunk/java/javax/servlet/http/HttpServlet.java?rev=1397465&r1=1397464&r2=1397465&view=diff ============================================================================== --- tomcat/tc7.0.x/trunk/java/javax/servlet/http/HttpServlet.java (original) +++ tomcat/tc7.0.x/trunk/java/javax/servlet/http/HttpServlet.java Fri Oct 12 08:24:42 2012 @@ -35,7 +35,7 @@ import javax.servlet.ServletResponse; /** * Provides an abstract class to be subclassed to create * an HTTP servlet suitable for a Web site. A subclass of - * <code>HttpServlet</code> must override at least + * <code>HttpServlet</code> must override at least * one method, usually one of these: * * <ul> @@ -43,27 +43,27 @@ import javax.servlet.ServletResponse; * <li> <code>doPost</code>, for HTTP POST requests * <li> <code>doPut</code>, for HTTP PUT requests * <li> <code>doDelete</code>, for HTTP DELETE requests - * <li> <code>init</code> and <code>destroy</code>, + * <li> <code>init</code> and <code>destroy</code>, * to manage resources that are held for the life of the servlet * <li> <code>getServletInfo</code>, which the servlet uses to - * provide information about itself + * provide information about itself * </ul> * * <p>There's almost no reason to override the <code>service</code> * method. <code>service</code> handles standard HTTP * requests by dispatching them to the handler methods - * for each HTTP request type (the <code>do</code><i>XXX</i> + * for each HTTP request type (the <code>do</code><i>Method</i> * methods listed above). * - * <p>Likewise, there's almost no reason to override the + * <p>Likewise, there's almost no reason to override the * <code>doOptions</code> and <code>doTrace</code> methods. - * + * * <p>Servlets typically run on multithreaded servers, * so be aware that a servlet must handle concurrent * requests and be careful to synchronize access to shared resources. * Shared resources include in-memory data such as * instance or class variables and external objects - * such as files, database connections, and network + * such as files, database connections, and network * connections. * See the * <a href="http://java.sun.com/Series/Tutorial/java/threads/multithreaded.html"> @@ -87,24 +87,24 @@ public abstract class HttpServlet extend private static final String HEADER_IFMODSINCE = "If-Modified-Since"; private static final String HEADER_LASTMOD = "Last-Modified"; - + private static final String LSTRING_FILE = "javax.servlet.http.LocalStrings"; private static ResourceBundle lStrings = ResourceBundle.getBundle(LSTRING_FILE); - - + + /** * Does nothing, because this is an abstract class. */ public HttpServlet() { // NOOP } - - + + /** * Called by the server (via the <code>service</code> method) to - * allow a servlet to handle a GET request. + * allow a servlet to handle a GET request. * * <p>Overriding this method to support a GET request also * automatically supports an HTTP HEAD request. A HEAD @@ -112,7 +112,7 @@ public abstract class HttpServlet extend * response, only the request header fields. * * <p>When overriding this method, read the request data, - * write the response headers, get the response's writer or + * write the response headers, get the response's writer or * output stream object, and finally, write the response data. * It's best to include content type and encoding. When using * a <code>PrintWriter</code> object to return the response, @@ -125,7 +125,7 @@ public abstract class HttpServlet extend * * <p>Where possible, set the Content-Length header (with the * {@link javax.servlet.ServletResponse#setContentLength} method), - * to allow the servlet container to use a persistent connection + * to allow the servlet container to use a persistent connection * to return its response to the client, improving performance. * The content length is automatically set if the entire response fits * inside the response buffer. @@ -141,10 +141,10 @@ public abstract class HttpServlet extend * * <p>The GET method should also be idempotent, meaning * that it can be safely repeated. Sometimes making a - * method safe also makes it idempotent. For example, + * method safe also makes it idempotent. For example, * repeating queries is both safe and idempotent, but * buying a product online or modifying data is neither - * safe nor idempotent. + * safe nor idempotent. * * <p>If the request is incorrectly formatted, <code>doGet</code> * returns an HTTP "Bad Request" message. @@ -156,14 +156,14 @@ public abstract class HttpServlet extend * @param resp an {@link HttpServletResponse} object that * contains the response the servlet sends * to the client - * - * @exception IOException if an input or output error is + * + * @exception IOException if an input or output error is * detected when the servlet handles * the GET request * * @exception ServletException if the request for the GET * could not be handled - * + * * @see javax.servlet.ServletResponse#setContentType */ protected void doGet(HttpServletRequest req, HttpServletResponse resp) @@ -191,7 +191,7 @@ public abstract class HttpServlet extend * This makes browser and proxy caches work more effectively, * reducing the load on server and network resources. * - * @param req the <code>HttpServletRequest</code> + * @param req the <code>HttpServletRequest</code> * object that is sent to the servlet * * @return a <code>long</code> integer specifying @@ -257,28 +257,28 @@ public abstract class HttpServlet extend * * <p>When overriding this method, read the request data, * write the response headers, get the response's writer or output - * stream object, and finally, write the response data. It's best + * stream object, and finally, write the response data. It's best * to include content type and encoding. When using a - * <code>PrintWriter</code> object to return the response, set the - * content type before accessing the <code>PrintWriter</code> object. + * <code>PrintWriter</code> object to return the response, set the + * content type before accessing the <code>PrintWriter</code> object. * * <p>The servlet container must write the headers before committing the - * response, because in HTTP the headers must be sent before the + * response, because in HTTP the headers must be sent before the * response body. * * <p>Where possible, set the Content-Length header (with the * {@link javax.servlet.ServletResponse#setContentLength} method), - * to allow the servlet container to use a persistent connection + * to allow the servlet container to use a persistent connection * to return its response to the client, improving performance. * The content length is automatically set if the entire response fits - * inside the response buffer. + * inside the response buffer. * * <p>When using HTTP 1.1 chunked encoding (which means that the response - * has a Transfer-Encoding header), do not set the Content-Length header. + * has a Transfer-Encoding header), do not set the Content-Length header. * * <p>This method does not need to be either safe or idempotent. * Operations requested through POST can have side effects for - * which the user can be held accountable, for example, + * which the user can be held accountable, for example, * updating stored data or buying items online. * * <p>If the HTTP POST request is incorrectly formatted, @@ -292,8 +292,8 @@ public abstract class HttpServlet extend * @param resp an {@link HttpServletResponse} object that * contains the response the servlet sends * to the client - * - * @exception IOException if an input or output error is + * + * @exception IOException if an input or output error is * detected when the servlet handles * the request * @@ -320,8 +320,8 @@ public abstract class HttpServlet extend * Called by the server (via the <code>service</code> method) * to allow a servlet to handle a PUT request. * - * The PUT operation allows a client to - * place a file on the server and is similar to + * The PUT operation allows a client to + * place a file on the server and is similar to * sending a file by FTP. * * <p>When overriding this method, leave intact @@ -377,7 +377,7 @@ public abstract class HttpServlet extend * * The DELETE operation allows a client to remove a document * or Web page from the server. - * + * * <p>This method does not need to be either safe * or idempotent. Operations requested through * DELETE can have side effects for which users @@ -396,7 +396,7 @@ public abstract class HttpServlet extend * * @param resp the {@link HttpServletResponse} object that * contains the response the servlet returns - * to the client + * to the client * * @exception IOException if an input or output error occurs * while the servlet is handling the @@ -417,7 +417,7 @@ public abstract class HttpServlet extend resp.sendError(HttpServletResponse.SC_BAD_REQUEST, msg); } } - + private static Method[] getAllDeclaredMethods(Class<?> c) { @@ -427,7 +427,7 @@ public abstract class HttpServlet extend Method[] parentMethods = getAllDeclaredMethods(c.getSuperclass()); Method[] thisMethods = c.getDeclaredMethods(); - + if ((parentMethods != null) && (parentMethods.length > 0)) { Method[] allMethods = new Method[parentMethods.length + thisMethods.length]; @@ -447,7 +447,7 @@ public abstract class HttpServlet extend * Called by the server (via the <code>service</code> method) * to allow a servlet to handle a OPTIONS request. * - * The OPTIONS request determines which HTTP methods + * The OPTIONS request determines which HTTP methods * the server supports and * returns an appropriate header. For example, if a servlet * overrides <code>doGet</code>, this method returns the @@ -456,7 +456,7 @@ public abstract class HttpServlet extend * <p><code>Allow: GET, HEAD, TRACE, OPTIONS</code> * * <p>There's no need to override this method unless the - * servlet implements new HTTP methods, beyond those + * servlet implements new HTTP methods, beyond those * implemented by HTTP 1.1. * * @param req the {@link HttpServletRequest} object that @@ -465,7 +465,7 @@ public abstract class HttpServlet extend * * @param resp the {@link HttpServletResponse} object that * contains the response the servlet returns - * to the client + * to the client * * @exception IOException if an input or output error occurs * while the servlet is handling the @@ -479,7 +479,7 @@ public abstract class HttpServlet extend throws ServletException, IOException { Method[] methods = getAllDeclaredMethods(this.getClass()); - + boolean ALLOW_GET = false; boolean ALLOW_HEAD = false; boolean ALLOW_POST = false; @@ -487,22 +487,22 @@ public abstract class HttpServlet extend boolean ALLOW_DELETE = false; boolean ALLOW_TRACE = true; boolean ALLOW_OPTIONS = true; - + for (int i=0; i<methods.length; i++) { Method m = methods[i]; - + if (m.getName().equals("doGet")) { ALLOW_GET = true; ALLOW_HEAD = true; } - if (m.getName().equals("doPost")) + if (m.getName().equals("doPost")) ALLOW_POST = true; if (m.getName().equals("doPut")) ALLOW_PUT = true; if (m.getName().equals("doDelete")) ALLOW_DELETE = true; } - + String allow = null; if (ALLOW_GET) allow=METHOD_GET; @@ -524,18 +524,18 @@ public abstract class HttpServlet extend if (ALLOW_OPTIONS) if (allow==null) allow=METHOD_OPTIONS; else allow += ", " + METHOD_OPTIONS; - + resp.setHeader("Allow", allow); } - - + + /** * Called by the server (via the <code>service</code> method) * to allow a servlet to handle a TRACE request. * * A TRACE returns the headers sent with the TRACE * request to the client, so that they can be used in - * debugging. There's no need to override this method. + * debugging. There's no need to override this method. * * @param req the {@link HttpServletRequest} object that * contains the request the client made of @@ -543,7 +543,7 @@ public abstract class HttpServlet extend * * @param resp the {@link HttpServletResponse} object that * contains the response the servlet returns - * to the client + * to the client * * @exception IOException if an input or output error occurs * while the servlet is handling the @@ -552,42 +552,42 @@ public abstract class HttpServlet extend * @exception ServletException if the request for the * TRACE cannot be handled */ - protected void doTrace(HttpServletRequest req, HttpServletResponse resp) + protected void doTrace(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException { - + int responseLength; - + String CRLF = "\r\n"; StringBuilder buffer = new StringBuilder("TRACE ").append(req.getRequestURI()) .append(" ").append(req.getProtocol()); - + Enumeration<String> reqHeaderEnum = req.getHeaderNames(); - + while( reqHeaderEnum.hasMoreElements() ) { String headerName = reqHeaderEnum.nextElement(); buffer.append(CRLF).append(headerName).append(": ") - .append(req.getHeader(headerName)); + .append(req.getHeader(headerName)); } - + buffer.append(CRLF); - + responseLength = buffer.length(); - + resp.setContentType("message/http"); resp.setContentLength(responseLength); ServletOutputStream out = resp.getOutputStream(); - out.print(buffer.toString()); + out.print(buffer.toString()); out.close(); return; - } + } /** * Receives standard HTTP requests from the public * <code>service</code> method and dispatches - * them to the <code>do</code><i>XXX</i> methods defined in - * this class. This method is an HTTP-specific version of the + * them to the <code>do</code><i>Method</i> methods defined in + * this class. This method is an HTTP-specific version of the * {@link javax.servlet.Servlet#service} method. There's no * need to override this method. * @@ -597,7 +597,7 @@ public abstract class HttpServlet extend * * @param resp the {@link HttpServletResponse} object that * contains the response the servlet returns - * to the client + * to the client * * @exception IOException if an input or output error occurs * while the servlet is handling the @@ -605,7 +605,7 @@ public abstract class HttpServlet extend * * @exception ServletException if the HTTP request * cannot be handled - * + * * @see javax.servlet.Servlet#service */ protected void service(HttpServletRequest req, HttpServletResponse resp) @@ -639,19 +639,19 @@ public abstract class HttpServlet extend } else if (method.equals(METHOD_POST)) { doPost(req, resp); - + } else if (method.equals(METHOD_PUT)) { - doPut(req, resp); - + doPut(req, resp); + } else if (method.equals(METHOD_DELETE)) { doDelete(req, resp); - + } else if (method.equals(METHOD_OPTIONS)) { doOptions(req,resp); - + } else if (method.equals(METHOD_TRACE)) { doTrace(req,resp); - + } else { // // Note that this means NO servlet supports whatever @@ -662,7 +662,7 @@ public abstract class HttpServlet extend Object[] errArgs = new Object[1]; errArgs[0] = method; errMsg = MessageFormat.format(errMsg, errArgs); - + resp.sendError(HttpServletResponse.SC_NOT_IMPLEMENTED, errMsg); } } @@ -682,20 +682,20 @@ public abstract class HttpServlet extend if (lastModified >= 0) resp.setDateHeader(HEADER_LASTMOD, lastModified); } - - + + /** * Dispatches client requests to the protected * <code>service</code> method. There's no need to * override this method. - * + * * @param req the {@link HttpServletRequest} object that * contains the request the client made of * the servlet * * @param res the {@link HttpServletResponse} object that * contains the response the servlet returns - * to the client + * to the client * * @exception IOException if an input or output error occurs * while the servlet is handling the @@ -703,7 +703,7 @@ public abstract class HttpServlet extend * * @exception ServletException if the HTTP request cannot * be handled - * + * * @see javax.servlet.Servlet#service */ @Override @@ -712,7 +712,7 @@ public abstract class HttpServlet extend HttpServletRequest request; HttpServletResponse response; - + try { request = (HttpServletRequest) req; response = (HttpServletResponse) res; @@ -809,7 +809,7 @@ class NoBodyResponse extends HttpServlet /* * Servlet output stream that gobbles up all its data. */ - + // file private class NoBodyOutputStream extends ServletOutputStream { @@ -836,15 +836,13 @@ class NoBodyOutputStream extends Servlet } @Override - public void write(byte buf[], int offset, int len) - throws IOException - { + public void write(byte buf[], int offset, int len) throws IOException { if (len >= 0) { contentLength += len; } else { // XXX // isn't this really an IllegalArgumentException? - + String msg = lStrings.getString("err.io.negativelength"); throw new IOException(msg); } --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org For additional commands, e-mail: dev-h...@tomcat.apache.org