GAXB

What is it?

GAXB (Generic Architecture for XML Bindings) is an XML schema-based code generation tool that supports custom cross-language model data serialization and deserialization.

What does GAXB do?

GAXB is fully serializable--model data can be used to generate XML (serializing) and XML can be used to generate model data (deserializing).

It supports custom lua templates and currently includes templates for Objective C, Objective C ARC, and Java.

Rather than writing out all of the classes in your desired language, you can instead build an XML schema. Then, instead of initializing model objects in code, you can write XML that conform to that schema. When your project is compiled, GAXB generates the code for your classes and code for the serializer and deserializer needed to convert those objects to XML and vice-versa.

How does it work?

Compile time code generation:

During compile time GAXB generates the header and implementation files for all of the elements defined in your schema, as well as class stubs that extend these generated base classes that can be used to write custom code for your objects. GAXB also generates an XML Loader for serializing and deserializing objects to and from your XML files.

Run time deserialization and serialization:

During run time you can use the XML Loader to read in your XML files, which will deserialize them into instances of your class objects that can then be manipulated in your application code.

Conversely, any class objects you create in your application code can be serialized to XML files for later use.

Examples

Schema Example:

This schema defines the structure of our Galaxy data model. This snippet shows the structure that a Planet will conform to.

You can view the full schema file here.

<!-- Galaxy.xsd -->
<schema xmlns="http://www.w3.org/2001/XMLSchema"
    xmlns:ga="http://schema.smallplanet.com/Galaxy"
    targetNamespace="http://schema.smallplanet.com/Galaxy">
    
    ... (other element definitions) ...
    
    <!-- Planet -->
    <element name="Planet" type="ga:Planet"/>
    <complexType name="Planet">
        <complexContent>
            <extension base="ga:AstronomicalObject">
                <sequence>
                    <element ref="ga:Moon" minOccurs="0" maxOccurs="unbounded" />
                </sequence>
                <attribute name="hasRings" type="boolean" default="false" />
            </extension>
        </complexContent>
    </complexType>

	...
    
</schema>

XML Example:

This XML file conforms to the Galaxy.xsd schema and defines a Star System with one Planet that has a Moon.

Our very own system, the Solar System, might look like this.

<?xml version="1.0" encoding="utf-8" ?>
<StarSystem xmlns="http://schema.smallplanet.com/Planets">
    
    <Planet name="Planet X" mass="1" hasRings="false"
        <Moon name="Moon Y"/>
    </Planet>

</StarSystem>

Generated Base Class Example:

Base classes are generated from the schema by GAXB during compile time. These base classes will be re-generated any time a change is made to that object in the schema.

The following code is the generated Galaxy_PlanetBase Objective C header file. This is one of the generated code files that results from compiling an Objective C project using the Galaxy.xsd schema.

// Galaxy_PlanetBase.h
// Autogenerated by gaxb at 10:21:03 AM on 01/01/13

@class Galaxy_Moon;
@interface Galaxy_PlanetBase : Galaxy_AstronomicalObject
{	
    // Attributes
    BOOL hasRings;
    BOOL hasRingsExists;

    // Subelements
    NSMutableArray *Moons;
}

@property (nonatomic) BOOL hasRings;
@property (nonatomic,readonly) BOOL hasRingsExists;
@property (nonatomic,retain) NSMutableArray * Moons;

- (NSString *) hasRingsAsString;
- (void) setHasRingsWithString:(NSString *)string;

@end

Custom Code Example:

Along with each generated base class, GAXB also generates header and implementation file stubs that subclass their base-class. These classes are only generated once and are used to write your custom logic.

Here is the generated and ready-to-use implementation file stub for Galaxy_Planet, which extends Galaxy_PlanetBase.

// Galaxy_Planet.mm
// Autogenerated by gaxb at 10:21:03 AM on 01/01/13
#import "Galaxy_Planet.h"

@implementation Galaxy_Planet

// Write your custom Galaxy_Planet object logic.

@end

The GAXB repository contains a fully-functional Objective-C project based on these examples. Follow the installation instructions in the next section and take a look at the BigPlanets example project.

Installation

Installation Prerequisites

In order to install GAXB, your system will require git, CMake 2.8, libxml2, and a compiler tool-chain.

Install git from their setup page.

Install brew from the Homebrew Page so we can install cmake.

To install cmake for Mac OS X:

brew update
brew install cmake

To install cmake, a tool-chain, and libxml2 on Linux:

apt-get install build-essential
apt-get install cmake
apt-get install libxml2-dev

GAXB Installation

Now you can clone the repository:

git clone git://github.com/SmallPlanet/gaxb.git
cd gaxb
git submodule update --init lua

Then build it using cmake:

mkdir build && cd build
cmake ..
make

The executable (gaxb) will be waiting for you in the current directory!

Command Line Usage

There is a sample.xsd schema in the Examples/Sample directory that you can build from the command line. Try the following in that directory:

mkdir Generated
../../build/gaxb objc sample.xsd -t ../../templates -o Generated

This will generate some quick Objective-C classes in Generated/ based on the schema at sample.xsd.

XCode Usage

A sample XCode project for an iOS app using gaxb-generated classes is included in Examples/BigPlanet. Open BigPlanet.xcodeproj from that directory in XCode, select iPhone or iPad Simulator, then Build and Run. This simple example uses the schema located at XMLSchema/Planets.xsd and loads sample data from BigPlanets/sol.xml.

License

GAXB is free software distributed under the terms of the MIT license, reproduced below. GAXB may be used for any purpose, including commercial purposes, at absolutely no cost. No paperwork, no royalties, no GNU-like "copyleft" restrictions. Just download and enjoy.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

About Small Planet

Small Planet is a mobile agency in Brooklyn, NY that creates lovely experiences for smartphones and tablets. GAXB has made our lives a lot easier and we hope it does the same for you. You can find us at www.smallplanet.com.

IvanRublev / gaxb