Getting Started

Joe Littlejohn edited this page Dec 14, 2016 · 47 revisions

There are currently five ways to use jsonschema2pojo:

  1. as a maven plugin using jsonschema2pojo-maven-plugin
  2. via the command line using jsonschema2pojo-cli
  3. as an ant task using jsonschema2pojo-ant
  4. as a gradle plugin using gradle-jsonschema2pojo-plugin
  5. directly from your code (embedded) using jsonschema2pojo-core

First though, we need to create a valid JSON Schema document. If you don't have one to hand, you can use the Address example found here:

http://www.json-schema.org/address

The Maven plugin

The Maven plugin provides a generate goal that attaches to the generate-sources phase by default.

For a quick example, place the address schema into src/main/resources/schema and edit your pom.xml to include the following in the <build> section:

        <plugins>
            <plugin>
                <groupId>org.jsonschema2pojo</groupId>
                <artifactId>jsonschema2pojo-maven-plugin</artifactId>
                <version>0.4.29</version>
                <configuration>
                    <sourceDirectory>${basedir}/src/main/resources/schema</sourceDirectory>
                    <targetPackage>com.example.types</targetPackage>
                </configuration>
                <executions>
                    <execution>
                        <goals>
                            <goal>generate</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>

The generated types target Java 6, so if you haven't already then you'll need to set your source/target version to 1.6 or higher by adding the following to the <build> section of your pom:

        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <configuration>
                <source>1.6</source>
                <target>1.6</target>
            </configuration>
        </plugin>

At present the generated types depend on Commons Lang for equals, hashCode and toString. Some schema constructs will also cause parser hints in the form of Jackson annotations. To compile your generated types, you'll need to make the necessary additions to your <dependencies>:

        <dependency>
            <groupId>commons-lang</groupId>
            <artifactId>commons-lang</artifactId>
            <version>2.4</version>
        </dependency>
        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-databind</artifactId>
            <version>2.0.0</version>
        </dependency>

Finally, on running mvn package you'll see a newly generated file target/java-gen/com/example/types/Address.java. You should also notice that the com.example.types.Address class has been compiled and included in your project bundle.

The command line interface

If you're using OSX and brew, try brew install jsonschema2pojo. If not, then start by downloading the latest release from:

https://github.com/joelittlejohn/jsonschema2pojo/releases

Extract the release, you should see some jsonschema2pojo jar files, a lib folder and two scripts (bash and bat).

We'll use the example address schema to generate our types. Download the address schema, and invoke jsonschema2pojo like:

jsonschema2pojo --source address --target java-gen

For the full usage details, use the --help option:

jsonschema2pojo --help

The Ant task

To invoke the jsonschema2pojo Ant task, you'll need to download the latest task itself, and some dependencies:

Either place the downloaded jars in $ANT_HOME/lib, or place them in a folder of your choosing.

Now simply add a the taskdef task to your build.xml to make the jsonschema2pojo task available. Once the taskdef has been added, you can invoke the task. E.g.

    <?xml version="1.0" encoding="UTF-8"?>
    <project name="myproject" default="generate">

        <taskdef name="jsonschema2pojo" classname="org.jsonschema2pojo.ant.Jsonschema2PojoTask">
            <classpath> <!-- classpath only required if jars have *NOT* been added to $ANT_HOME/lib -->
                <fileset dir="my-downloaded-libs">
                    <include name="**/*.jar" />
                </fileset>
            </classpath>
        </taskdef>

        <target name="generate">
            <jsonschema2pojo source="address.json" 
                             targetDirectory="build/generated-types" 
                             targetPackage="com.example"/>
        </target>

    </project>

Using jsonschema2pojo within your Java project (embedded)

To use the jsonschema2pojo API directly from a Java application you'll need to add the jsonschema2pojo-core jar to your build path. You can obtain this by downloading the latest jar or by adding the following dependency to your Maven project:

        <dependency>
            <groupId>org.jsonschema2pojo</groupId>
            <artifactId>jsonschema2pojo-core</artifactId>
            <version>0.4.29</version>
        </dependency>

If you're not using Maven, you'll need to gather some further dependencies:

Now you're ready to use the jsonschema2pojo schema mapper in your code:

JCodeModel codeModel = new JCodeModel();

URL source = new URL("file:///path/to/my/schema.json");

GenerationConfig config = new DefaultGenerationConfig() {
@Override
public boolean isGenerateBuilders() { // set config option by overriding method
return true;
}
};

SchemaMapper mapper = new SchemaMapper(new RuleFactory(config, new Jackson2Annotator(config), new SchemaStore()), new SchemaGenerator());
mapper.generate(codeModel, "ClassName", "com.example", source);

codeModel.build(new File("output"));