A DESCRIPTION OF THE REQUEST :
The documentation for the use of Persistent Beans seems to be the article http://java.sun.com/products/jfc/tsc/articles/persistence3/, which contains a short description of how to use persistent beans.  There is also a DTD in http://java.sun.com/products/jfc/tsc/articles/persistence3/javabeans.dtd.

It turns out that the actual behaviour of Persistent Beans is not completely covered by these documents.
Consider the following XML code:

<?xml version="1.0"?>
<java>
<!-- Case 1 -->
<string id="foobar">FOOBAR</string>

<void class="java.lang.System" field="err">
  <void method="println">
    <object idref="foobar" method="toLowerCase"/>
  </void>
</void>

<!-- Case 2 -->
<void class="java.lang.String">
  <string>BARFOO</string>
  <void id="lowercase" method="toLowerCase"/>
</void>

<void class="java.lang.System" field="err">
  <void method="println">
    <object idref="lowercase"/>
  </void>
</void>
</java>

If read in by a program such as http://java.sun.com/products/jfc/tsc/articles/persistence3/TestInput.java,
this code will output:
FOOBAR
barfoo

What apparently happens is that in Case 1 the element <object idref="foobar" method="toLowerCase"/>  silently ignores the method attribute and the element is interpreted as if it only said <object idref="foobar"/>.  In Case 2 the operation is divided up into two steps to give the desired result.


JUSTIFICATION :
It took me a long while to figure out what was going wrong in my code, because:
1.  The parsing does not emit any error messages, it just silently ignores the method attribute.
2.  The explanatory article, while not showing any example of the construction shown in Case 1, does not explicitly forbid it either.
3.  The DTD does not imply that the construction is illegal.

Now, once I figured out what the problem is, I can work around it with few problems, but I prefer the documentation to be complete.

EXPECTED VERSUS ACTUAL BEHAVIOR :
EXPECTED -
While I would prefer that it be possible to write Case 1 and get the output

foobar

it may be that there are reasons for why this is not allowed, in which case I would like this to be spelled out in the documentation (including the DTD).
ACTUAL -
Currently the actual behaviour is undocumented.

CUSTOMER SUBMITTED WORKAROUND :
Case 2 is a workaround for Case 1.  Now this is a much simplified version of the original code I had problems with.  It turns out that there are bean descriptions that become easier to modularise if idrefs can be used to perform method calls.