Xmlbeans provides support for types built into XML Schema. It maps these types to a specific type hierarchy as well as, for many of these types, providing convenience functions to access values as more typical Java types. For example, the
xsd:string simple type is mapped to
XmlString but objects with string properties will also have a convenience method to retrieve contents as a standard
This proposal details a mechanism to allow schema code generated by Xmlbeans to provide custom convenience methods for derived simple types. The developer would provide information in the xsdconfig file indicating which simple types to generate custom convenience methods for, the Java type that will be generated, and a static handler that will convert a
org.apache.xmlbeans.SimpleValue to the indicated custom type.
Suppose a schema contains the following derived simple type:
Here, it would be useful to have the
uuid derived type converted to a
java.util.UUID. To accomplish this the xsdconfig file accompanying the schema would contain the following:
com.example.UUIDType would be expected to have the following static methods:
example:uuid simple type is used as an element of a complex type, the static handler would then be invoked by a convenience method returning a
java.util.UUID. The static handler does not throw exceptions. Any provided static handler must be able to parse any information provided to it in the
SimpleValue class. Thus, the schema itself should limit possible inputs to those that can be validly interpreted by the static handler.
xset methods will remain available to set properties using the normally generated type extending
In the initial implementation, the generated code would use the Java reflect API to find and invoke the static handler. This option allows users to build the schema separately from the code that contains the static handler. However, because the use of reflection incurs a performance penalty an option to generate code that calls the static handler directly would likely be necessary for many library users.
Static Handler Methods
The expected method signature on the static handler indicated for a specific type must be public, static, and have a method name of "encode"/"decode" plus the unqualified name of the user type. The unqualified name is required to allow multiple user types to be handled by the same static handler class.
Assuming the user type is named
common:uuid and maps to the Java type
java.util.UUID the method signatures must be:
Assuming the user type is
myns:foobar and maps to the Java type
com.example.Foobar the method signatures must be:
As XMLBeans is designed around a "start-from-Schema" use case, the encode and decode methods must be written such that they are able to handle any value that is valid against the schema. Because validation is an optional operation when loading XML there may be cases when a decoder would be called with invalid input. In such cases either
XmlValueOutOfRangeException should be thrown from the decode method. Such exceptions should not be thrown in cases where the XML input has been successfully validated against the schema (this is just another way of stressing that the decoder must accept all valid input according to the XML Schema). The encoder should never throw such an exception.