I agree that we should make a clarification. I'll implement a proposal and put it out for review. I would try to use descriptions similar to those provided for the corresponding HTTPServletResponse methods.
Note that the setProperty description in MimeResponse contains the following description:
void setProperty(String key,
Sets a String property to be returned to the portal.
Response properties can be viewed as header values set for the portal application. If these header values are intended to be transmitted to the client they should be set before the response is committed.
This method resets all properties previously added with the same key.
In spite of that, I'll explicitly note that the status code must be set before the response is committed in the field description for HTTP_STATUS_CODE.
I agree that this would be applicable if we implement
See the test portlet PORTLETSPEC3_26 in portletbox for tests that exercise the setting of header information and getting the WindowState and PortletMode (issue
PORTLETSPEC3-27) in the resource phase.
It's interesting that WebSphere works slightly differently than Pluto. Both allow HTTP header information to be changed after getWriter() is called and after data is written, but that is probably an accident of implementation rather than design. There are two significant differences between the Pluto and the WebSphere implementations:
1) WebSphere allows an undefined, but "good" 2xx status code (such as "235"), to be set and sent back to the client, while Pluto converts it to "200", even if the status code is set before a call to getWriter().
I think the Pluto implementation is wrong in this area, since the HTTP spec states that the status codes are to be extensible. The client is required by the HTTP spec to understand unknown 2xx status codes as being equivalent to 200.
2) Pluto doesn't seem to allow a Locale with a variant string to be set. The variant portion never gets into the HTTP content-language header.
I think Pluto is wrong here, as well.