Filed By      : SPB JCK team (  xxxxx@xxxxx  )
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  customer  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  customer  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  customer  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.


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

N/A

Accepted

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

Engineering responded as follows. I have inlined the response, omitting the engineer's name:

---
>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.

 This is not true both writeExpression and writeStatement can be used 
in PersistenceDelegate initialization.


>2. it is writeExpression intended to be used while providing resource 
>bundle stuff
>     Not writeStatement.
>    (new Expression(resourceBundle, "getObject", new Object[] {"hello"}))
>

 This is correct. As far as I can tell you cannot use writeStatement 
 for resource bundles. The paragraph about resource bundles should be 
 removed from writeStatement. For writeExpression, it would help if there 
 was more detail about using ResourceBundles and the XMLEncoder. Perhaps 
 you can refer to this URL:

http://java.sun.com/products/jfc/tsc/articles/persistence4/#i18n

> (See_also part in writeExpression should be omitted)

Not true!

>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.

Agreed. The URL above gives the details. Perhaps you can also use my 
evaluation for 4940298 as guidance.
---

  xxxxx@xxxxx   2003-11-24