Bug 54198 - Improve HttpServletResponse#sendError(int) JavaDoc description
Summary: Improve HttpServletResponse#sendError(int) JavaDoc description
Status: RESOLVED FIXED
Alias: None
Product: Tomcat 6
Classification: Unclassified
Component: Servlet & JSP API (show other bugs)
Version: 6.0.36
Hardware: All All
: P2 enhancement (vote)
Target Milestone: default
Assignee: Tomcat Developers Mailing List
URL:
Keywords:
Depends on:
Blocks:
 
Reported: 2012-11-23 22:33 UTC by Michael Osipov
Modified: 2012-11-26 11:20 UTC (History)
0 users



Attachments

Note You need to log in before you can comment on or make changes to this bug.
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.