Clarify what property names are used in @JsonbPropertyOrder

[aguibert]

If I have a JSON-B data class like this:

@JsonbPropertyOrder({"????"})
public class JsonbObject {

    @JsonbProperty("identity")
    long id;
    @JsonbProperty("desc")
    String description;
    @JsonbProperty("thecost")
    double cost;
    @JsonbProperty("tstamp")
    Date timeStamp;

From reading the spec, it is not clear if the String array passed into @JsonbPropertyOrder should be the original name of the java properties (id, description, cost, timeStamp) or the final JSON-B property names (identity, desc, thecost, tstamp).

I am not sure what the original intent of the spec was, but I think that using the final JSON-B property names (identity, desc, thecost, tstamp) makes the most sense.

[aguibert]

I just noticed this fragment in the end of section 4.2 of the 1.0 spec:

4.2 Customizing Property Order

...
The order is applied to already renamed properties as stated in 4.1.

which seems to indicate that my understanding in the OP was correct. However, I still think we should clarify this behavior in the javadoc so users do not need to reference the spec to understand.

Also this TCK test confirms that order strategy should be supplied AFTER property renames: https://github.com/eclipse-ee4j/jakartaee-tck/blob/febd0176d513a2b4d9b13354bf69b6d6c03d79a3/src/com/sun/ts/tests/jsonb/customizedmapping/propertyorder/PropertyOrderCustomizationTest.java#L368

[aguibert]

It seems that the @JsonbPropertyOrder.value() attribute has its own javadoc which I had been missing, which explicitly defines behavior:

    /**
     * Order in which properties are serialized. Names must correspond to original
     * names defined in Java class before any customization applied.
     *
     * @return Array of property names which defines an order.
     */
    String[] value();

Although this directly conflicts with how PropertyOrderStrategy works, at least it is clearly specified.

In the next version of JSON-B we should add this portion of javadoc to the @JsonbPropertyOrder class-level javadoc, because it is easy to miss the value() javadoc as the attribute name is inferred most of the time so users (including myself) may not see it.