Bug 54198

Summary: Improve HttpServletResponse#sendError(int) JavaDoc description
Product: Tomcat 6 Reporter: Michael Osipov <michaelo>
Component: Servlet & JSP APIAssignee: Tomcat Developers Mailing List <dev>
Status: RESOLVED FIXED    
Severity: enhancement    
Priority: P2    
Version: 6.0.36   
Target Milestone: default   
Hardware: All   
OS: All   

Description Michael Osipov 2012-11-23 22:33:12 UTC 
This methods calls sendError(int, null) internally. Thus generating a HTML page without a message. This is not mentioned in the docs. One could assume that the response will be empty.

One could duplicate the first paragraph of the sendError(int,String) method and alter it to "The server defaults to creating the response to look like an HTML-formatted server error page with any specific message, setting the content type to "text/html",..." further "If an error-page declaration has been made for the web application corresponding to the status code passed in, it will be served back." (Might need improvement in this case, I am not a native speaker).

Moreover, I would add "This method is effectively the same as calling sendError(int, null)". Plus add @see #sendError(int,String).

Though the JavaDocs seems to be a verbatim copy of Oracle's Servlet API, it does not reveal this information explicitly.

Should I provide a patch if that doc is available in svn.apache.org?
Comment 1 Konstantin Kolinko 2012-11-25 10:19:15 UTC 
(In reply to comment #0)
> sendError(int) methods calls sendError(int, null) internally. Thus generating a HTML
> page without a message. This is not mentioned in the docs. One could assume
> that the response will be empty.

The sendError() method behaviour is defined by several chapters of the Servlet specification. In "Servlet 3.0 Rev a":

a) ch.5.3 Convenience Methods
b) ch.10.9 Error Handling

It does not matter much which of sendError(..) methods is called.

> seems to be a verbatim copy of Oracle's Servlet API

It is the other way around. The origin is in the old times when Tomcat was the reference implementation. Tomcat Javadocs were maintained as the official ones at that time.
Comment 2 Michael Osipov 2012-11-25 10:27:58 UTC 
(In reply to comment #1)
> (In reply to comment #0)
> > sendError(int) methods calls sendError(int, null) internally. Thus generating a HTML
> > page without a message. This is not mentioned in the docs. One could assume
> > that the response will be empty.
> 
> The sendError() method behaviour is defined by several chapters of the
> Servlet specification. In "Servlet 3.0 Rev a":
> 
> a) ch.5.3 Convenience Methods
> b) ch.10.9 Error Handling
> 
> It does not matter much which of sendError(..) methods is called.
> 
> > seems to be a verbatim copy of Oracle's Servlet API
> 
> It is the other way around. The origin is in the old times when Tomcat was
> the reference implementation. Tomcat Javadocs were maintained as the
> official ones at that time.

Well, this does not mean that we cannot improve the doc for sendError(int). I dont think that one has to read the spec to understand what a method really does. That's the purpose of JavaDoc actually, at least to me.
Comment 3 Mark Thomas 2012-11-26 11:20:34 UTC 
Fixed in trunk, 7.0.x and 6.0.x. Will be included in 7.0.34 and 6.0.37.