README

JSON 2 POJO

This script, json2pojo, attempts to create java POJOs from example JSON files.  
In general, error handling is pretty woeful, so expect it to crash out with a
stacktrace if you do something bad. :)

For command line flags, use json2pojo.rb -h.

There are limits to what can be achieved with automated generation.  This 
script works on a specific subset of JSON.

For example, this will work:

**************************************************************
{
  "foo" : "blah",
  "baz" : 1,
  "xyz" : 2.5
}
**************************************************************

Using the default configuration, the Example java class will be generated in the "output" directory:

**************************************************************
package com.example;




import org.codehaus.jackson.annotate.JsonIgnoreProperties;

/**
 * Created by json2pojo
 */
@JsonIgnoreProperties(ignoreUnknown = true)
public class Example {

  private Double xyz;
  private Long baz;
  private String foo;

  public Double getXyz() {
    return xyz;
  }

  public void setXyz(Double xyz) {
    this.xyz = xyz;
  }

  public Long getBaz() {
    return baz;
  }

  public void setBaz(Long baz) {
    this.baz = baz;
  }

  public String getFoo() {
    return foo;
  }

  public void setFoo(String foo) {
    this.foo = foo;
  }

}
**************************************************************

This example will generate code, but it's not very useful:

**************************************************************
{
  "exchange_rates" : 
  {
    "AUD" : 1.234,
    "USD" : 0.998,
    "JPY" : 5.678
  }
}
**************************************************************

ExchangeRates file in "output" directory:
**************************************************************
package com.example;




import org.codehaus.jackson.annotate.JsonIgnoreProperties;

/**
 * Created by json2pojo
 */
@JsonIgnoreProperties(ignoreUnknown = true)
public class ExchangeRates {

  private Double AUD;
  private Double USD;
  private Double JPY;

  public Double getAUD() {
    return AUD;
  }
  
  public void setAUD(Double AUD) {
    this.AUD = AUD;
  }

  public Double getUSD() {
    return USD;
  }
  
  public void setUSD(Double USD) {
    this.USD = USD;
  }
  
  public Double getJPY() {
    return JPY;
  }
  
  public void setJPY(Double JPY) {
    this.JPY = JPY;
  }

}
**************************************************************

This script can handle simple arrays of primitives.  It looks at the first entry only
to generate the list in Java.  The following will generate a field as
"private List<Double> simpleNumbers;", etc.

**************************************************************
{
  "simple_numbers" : 
  [
    1.234,
    0.998,
    5.678
  ]
}
**************************************************************

The script can handle arrays that contain objects.  It looks at the first entry only
to generate array objects.  The following works:

**************************************************************
{
  "simple_data" : 
  [
    { "key" : 1.234 },
    { "key" : 3.456 },
    { "key" : 7 }
  ]
}
**************************************************************

Note that if the last value ("key" : 7") was first, then the code generated would be
using Long instead of Double.

Also, by default, the script will chop the last character off array/list names.  In
the above example, the default code generation would create a SimpleDat.java file.
Use -n to override.  If your fields use "nice" plurals, then the default behaviour
generates nice java files.

Using this example:


**************************************************************
{
  "links": [
    {"href":"/example/2342342", "rel":"example", "group":"public"}  
  ]
}
**************************************************************

The files generated by default will be Example.java and Link.java.  The Example
class will contain a List<Link> which is more readable for java purposes.

If json2pojo can't determine a java type, it will use Object as the class type by
default.  Use "-u" to override this behaviour and have unknown fields be given a
java class of "UNKNOWN", which will then cause the code to not compile and show
obvious errors for you to fix.

If your data contains fields that are java reserved words, you'll need to use
one or more of the flags "-fp", "-fs", "-cp", "-cs" to add a prefix or suffix
to field names and class names.  Best results for these flags are to use the 
prefix versions ("-fp" and "-cp"), but the suffix versions have been added
for convenience.  Limitation: This does not handle fields or classes in your
data that are specifically named "boolean", "double", "long" or "string".

Example:

**************************************************************

json2pojo.rb -cp Foo -fp foo -e example_with_reserved_words.json

**************************************************************

Note in the above example the use of prefixes for classes ("-cp") and
fields ("-fp") and the different values.  If you need to override the 
class names, it's highly likely you will need to override the field
names as well.

By default, the generated classes are annotated for use with Jackson (see 
http://jackson.codehaus.org/).  Refer to the Configuration in the json2pojo.rb 
file to change this if required.  If you want strict JSON parsing in your java 
application, then clear these properties in the Configuration:

...
self.ignore_unknown_properties_annotation = "@JsonIgnoreProperties(ignoreUnknown = true)"
self.ignore_unknown_properties_import = "import org.codehaus.jackson.annotate.JsonIgnoreProperties;"
...

Note that if you use the flags "-fp" and "-fs" to modify the field names, all fields
generated will be annotated with the @JsonProperty for the real field name within the
JSON.

Finally, feel free to send patches, fixes or suggestions for improving this script.
The code is hack-ish, so apologies for that. :)

Chris
chrisr AT rymich.com