United StatesChange Country, Oracle Worldwide Web Sites Communities I am a... I want to...
JDK-4940306 : java.beans.XMLEncoder.writeExpression, writeStatement: spec issues

Details
Type:
Bug
Submit Date:
2003-10-20
Status:
Resolved
Updated Date:
2004-09-17
Project Name:
JDK
Resolved Date:
2004-09-17
Component:
docs
OS:
solaris_2.6
Sub-Component:
guides
CPU:
sparc
Priority:
P4
Resolution:
Fixed
Affected Versions:
5.0
Fixed Versions:
5.0 (b32)

Related Reports

Sub Tasks

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


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

                                    

Comments
EVALUATION

Name: jg118383			Date: 10/24/2003

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

###@###.### 2003-11-24
                                     
2003-11-24
PUBLIC COMMENTS

Putback in build 32.
###@###.### 2003-12-14
                                     
2003-12-14
CONVERTED DATA

BugTraq+ Release Management Values

COMMIT TO FIX:
tiger-beta

FIXED IN:
tiger-beta

INTEGRATED IN:
tiger-b32
tiger-beta

VERIFIED IN:
1.5.0_01


                                     
2004-09-18



Hardware and Software, Engineered to Work Together