Re: Clarification needed regarding default value of newLine in DOMSerializer of DOM L3 LS spec

Ramesh Babu Mandava wrote:
> Hi:
>    
>  Java binding of DOM L3 LS at
> 
> http://www.w3.org/TR/2003/WD-DOM-Level-3-LS-20030619/
> 
> contain unclear javadoc for getNewLine and setNewLine methods of DOMSerializer class. 
> 
>  From the javadoc it is not clear that what should getNewLine return in case setNewLine is not called before ( default value ). Whether "null" should be returned or the "platform default end-of-line sequence"? 
>   
>  The javadoc for setNewLine is exactly same as getNewLine?
>  There is need for changing the javadoc for getNewLine and setNewLine and make it different to define specific purpose of each method.
>   
>  Whether the intention is that when "null" value is
> passed to setNewLine, then the end-of-line sequence   
>  need to be defaulted to platform specific one? And
>  getNewLine should never return "null"

I believe the spec does currently reflect the intent here. The spec does 
say (and the bindings that you quoted from also say) that the default 
value of this attribute is null, and it's clearly defined that the 
implementation is then expected to pick a good default newline sequence 
in the environment in question. And this attribute can be null, and that 
indicates that the implementation will use the default. There was never 
an intent to reflect to the application what that default newline sequence.

If you feel that this still needs clarification, please let us know.

> 
>  Here is snippet of javadoc for getNewLine/setNewLine.
> 
> ===
> /**
>      *  The end-of-line sequence of characters to be used in the XML being
>      * written out. Any string is supported, but these are the recommended
>      * end-of-line sequences (using other character sequences than these
>      * recommended ones can result in a document that is either not
>      * serializable or not well-formed):
>      * <dl>
>      * <dt><code>null</code></dt>
>      * <dd> Use a default
>      * end-of-line sequence. DOM implementations should choose the default
>      * to match the usual convention for text files in the environment being
>      * used. Implementations must choose a default sequence that matches one
>      * of those allowed by section 2.11, "End-of-Line Handling" in [<a href='http://www.w3.org/TR/2000/REC-xml-200010
> 06'>XML 1.0</a>], if the
>      * serialized content is XML 1.0 or section 2.11, "End-of-Line Handling"
>      * in [<a href='http://www.w3.org/TR/2002/CR-xml11-20021015/'>XML 1.1</a>], if the
>      * serialized content is XML 1.1. </dd>
>      * <dt>CR</dt>
>      * <dd>The carriage-return character (#xD).</dd>
>      * <dt>
>      * CR-LF</dt>
>      * <dd> The carriage-return and line-feed characters (#xD #xA). </dd>
>      * <dt>LF</dt>
>      * <dd> The
>      * line-feed character (#xA). </dd>
>      * </dl>
>      * <br>The default value for this attribute is <code>null</code>.
>      */
>     public String getNewLine();
> 
> ====
> 
> Regards
> -Ramesh
>  
> 

-- 
jst

Received on Wednesday, 12 November 2003 00:25:17 UTC