Project

jaxb2ruby

0.01
Low commit activity in last 3 years
No release in over a year
jaxb2ruby generates Java XML mappings via xjc, reads the resulting annotations, and passes the extracted info to an ERB template. This allows one to automatically map an XML schema to pure Ruby classes (i.e. classes that don't require JRuby) using the mapping framework of their choice. Several templates are included: ROXML, HappyMapper and generic Ruby class (PORO).
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies

Development

~> 10.0

Runtime

~> 0.5.4
 Project Readme

jaxb2ruby

Build Status Code Climate

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:

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