Name: sdR10048			Date: 10/20/2003


Filed By      : SPB JCK team (###@###.###)
JDK           : java full version "1.5.0-beta-b23"
JCK           : 1.5


Specification excerpt:
======================
--------- J2SE API spec v.1.5 ---------
...
public void writeStatement(Statement oldStm)
    Records the Statement so that the Encoder will produce the actual
    output when the stream is flushed. 

    This method should only be called within the context of initializing
    a persistence delegate or setting up an encoder to read from a 
    resource bundle. 

Overrides:
    writeStatement in class Encoder
Parameters:
    oldStm - The statement that will be written to the stream.
SeeAlso:
    PersistenceDelegate.initialize(java.lang.Class, java.lang.Object, java.lang.Object, java.beans.Encoder)

======

public void writeExpression(Expression oldExp)
    Records the Expression so that the Encoder will produce the actual 
    output when the stream is flushed. 

    This method should only be called within the context of initializing 
    a persistence delegate or setting up an encoder to read from a 
    resource bundle. 

Overrides:
    writeExpression in class Encoder
Parameters:
    oldExp - The expression that will be written to the stream.
SeeAlso:
    PersistenceDelegate.initialize(java.lang.Class, java.lang.Object, java.lang.Object, java.beans.Encoder)
...
---------- end-of-excerpt ---------------

Problem description
===================
The spec for these two methods contains the following (the same) assertion:

"This method should only be called within the context of initializing
 a persistence delegate or setting up an encoder to read from a 
 resource bundle."

I believe that this assertion should be splitted into two parts and each part
should be moved to corresponding method's javadoc since:
1. it is writeStatement intended to be used in PersistenceDelegate.initialize,
    Not writeExpression.
2. it is writeExpression intended to be used while providing resource bundle stuff
    Not writeStatement.
   (new Expression(resourceBundle, "getObject", new Object[] {"hello"}))
   (See_also part in writeExpression should be omitted)

Also I believe that there should be posted some more details about the 
"setting up an encoder to read from a resource bundle". At this moment it
is not quite clear point.


======================================================================