sshaw / jaxb2ruby

Generate pure Ruby objects from an XML schema (XSD) using JAXB and JRuby. Use your favorite XML to object mapper or a custom ERB template.

jaxb2ruby

Generate pure Ruby classes from an XML schema using JAXB and JRuby

Usage

usage: jaxb2ruby [options] schema
    -c, --classes=MAP1[,MAP2,...]    XML Schema type to Ruby class mappings
                                     MAP can be a string in the form type=class or a YAML file of type/class pairs
    -h, --help                       Show this message
    -I, --include=DIRECTORY          Add DIRECTORY to the load path, usefull for using custom template helpers
    -J, --jvm=[ARG1[,ARG2,...]]      Options to pass to the JVM when calling XJC
    -n, --namespace=MAP1[,MAP2,...]  XML namespace to ruby class mappings
                                     MAP can be a string in the form namespace=class or a YAML file of namespace/class pairs
    -o, --output=DIRECTORY           Directory to output the generated ruby classes, defaults to ruby
    -t, --template=NAME              Template used to generate the ruby classes
                                     Can be a path to an ERB template or one of: roxml (default), happymapper, ruby
    -v, --version                    jaxb2ruby version
    -w, --wsdl                       Treat the schema as a WSDL
                                     Automatically set if the schema has a `.wsdl' extension
    -x, --xjc=PATH                   Path to the XJC executable to use; defaults to xjc

Instalation

gem install jaxb2ruby

jaxb2ruby must be installed and ran under JRuby. The generated classes will not depend on JRuby.

If your underlying JDK version is >= 9 you must use JRuby >= 9.2.12.0.

If your underlying JDK version is >= 11, you must manually install JAXB. In this case you'll likely run jaxb2ruby using the following (on *nix):

CLASSPATH=path/to/jaxb-ri/mod/jakarta.xml.bind-api.jar jaxb2ruby -x path/to/xjc.sh schema.xsd

Ruby Class Mappings

XML Schema Built-in Types

Certain XML schema types are converted to Symbols. You can specify your own XML Schema to Ruby type mapping(s) via the -c option.

For a complete list of mappings see the SCHEMA_TO_RUBY constant.

XML Schema Complex Types

Complex schema types will camelized and turned into Ruby classes. If a type has a namespace the namespace will be converted into a module and the resulting class will be placed inside.

Namespaces are turned into modules using a slightly modified version of the rules outlined in the The Java Architecture for XML Binding (JAXB) 2.0 Section D.5.1 Mapping from a Namespace URI. The differences being:

• The list of module/package strings are joined on "::"
• A module/package string beginning with "_" is replaced with "V"
• Nested, anonymous XML schema types become Ruby inner classes

Some examples:

{http://example.com}User becomes Com::Example::User

{http://example.com/api/15}User becomes Com::Example::Api::V15::User

An XML schema type {http://example.com}User that contains the nested complex type Addresses, which itself contains the type Address will result in the creation of 3 classes: User, User::Addresses and User::Addresses::Address, all within the Com::Example namespace.

You can specify your own namespace to class mapping(s) via the -n option. Namespace mappings have a lower precedence than type mappings.

Code Templates

jaxb2ruby uses ERB templates to create Ruby classes. You can use one of the bundled templates or create your own. Use the -t option to specify the path to a custom template or one of the following bundled ones:

• roxml the default (ROXML)
• happymapper (Nokogiri HappyMapper)
• ruby - plain 'ol Ruby classes

Note that "plain 'ol Ruby classes" does not perform XML serialization.

Rolling out your own templates

Use the -t option to specify the path to your template. This must be a path else it will be interpreted as a jaxb2ruby template. Two variables will be provided to your template:

1. @class, an instance of RubyClass
2. VERSION the version of jaxb2ruby

See lib/templates for some examples.

You can use helper functions in your templates by providing the helper file's directory to the -I option.

TODO

• Map java.util.Hash
• Do something with org.w3c.dom.*
• Don't treat XML Schema types as elements
• Circular dependencies, currently can be resolved by manually adding forward declarations
• Fix other things that surely don't work

See Also

• class2 - easily create class hierarchies that support nested attributes, type conversion, equality, and more, all from a hash specification

Author

Skye Shaw [sshaw AT gmail.com]

License

Released under the MIT License: www.opensource.org/licenses/MIT