Java Binding

Contents

• Package and Class Names
• Primitive Types
• Enum Type
• Fixed Type
• Array Type
• Map Type
• Record Type
• Error Type
• Union Type
• Custom Java Class Binding for Primitive Types
• Fields class
• Clone Method
• Escaping for Reserved Words
• Exceptions
• Running the Code Generator

This section describes the details of the Java classes (dataModels) generated by the code generator.

Package and Class Names

The Java binding determines the package and class names of the generated and/or built-in classes using the following rules.

{ "type" : "map", "values" : "boolean" }
{ "type" : "array", "items" : { "type" : "map" : "values" : "string" } }

package com.linkedin.data.template;
public class BooleanMap extends DirectArrayTemplate&ltBoolean&gt ...
public class StringMapArray extends DirectArrayTemplate&ltStringMap&gt ...

{ "type" : "record", "name" : "a.b.c.d.Foo", "fields" : ... }
{ "type" : "enum", "name" : "Bar", "namespace" : "x.y.z", "package": "x.y.z.test", symbols" : ... }

package a.b.c.d;
public class Foo extends RecordTemplate ...


package x.y.z.test;
public enum class Bar ...

{ "type" : "map", "values" : "a.b.c.d.Foo" }
{ "type" : "map", "values" : { "type" : "array", "items" : "a.b.c.d.Foo" } }


{ "type" : "array", "items" : "x.y.z.Bar" }
{ "type" : "array", "items" : { "type" : "map", "values" : "x.y.z.Bar" } }

package a.b.c.d;
 
public class FooMap extends WrappingMapTemplate<Foo> ...
public class FooArrayMap extends WrappingMapTemplate<Foo&gt ...
 
package x.y.z.test;
public class BarArray extends DirectArrayTemplate<Bar&gt ...
public class BarMapArray extends DirectArrayTemplate<Bar&gt ...

{
  "type" : "record",
  "name" : "a.b.c.d.Foo",
  "fields" : [ { "name" : "bar", "type" : [ "int", "string" ] } ]
}

package a.b.c.d;
public class Foo extends RecordTemplate {
  public class Bar extends UnionTemplate ...
}

{
  "type" : "typeref",
  "name" : "a.b.c.d.Bar",
  "package" : "a.b.c.d.test",
  "ref"  : [ "int", "string" ] 
}

package a.b.c.d.test;
public class Bar extends UnionTemplate implements HasTyperefInfo {
  ...
  public TyperefInfo typerefInfo() 
  {
    ... 
  }
}

{
  "type" : "record",
  "name" : "a.b.c.d.Foo",
  "fields" : [
    { "name" : "members", "type" : { "type" : "array", "items" : [ "int", "string" ] } }
    { "name" : "locations", "type" : { "type" : "map", "values" : [ "int", "string" ]  } }
  ]
}

package a.b.c.d;
public class Foo extends RecordTemplate {
  public class Members extends UnionTemplate ...
  public class MembersArray extends WrappingArrayTemplate<Members> ...
  public class Locations extends UnionTemplate ...
  public class LocationsMap extends WrappingMapTemplate<Locations&t; ...
 

  public MembersArray getMembers() ...
  public LocationsMap getLocations() ...
}

{
  "type" : "typeref",
  "name" : "a.b.c.d.Bar",
  "package": "a.b.c.d.test",
  "ref"  : [ "int", "string" ] 
}

 
{
  "type" : "record",
  "name" : "a.b.c.d.Foo",
  "package" : "a.b.c.d.test",
  "fields" : [
    { "name" : "members", "type" : { "type" : "array", "items" : "Bar" } }
    { "name" : "locations", "type" : { "type" : "map", "values" : "Bar" } }
  ]
}

package a.b.c.d.test;

 
public class Bar extends UnionTemplate ...
public class BarArray extends WrappingArrayTemplate<Bar> ...
public class BarMap extends WrappingMapTemplate<Bar> ...

 
public class Foo extends RecordTemplate
{
  public BarArray getMembers() ...
  public BarMap getLocations() ...
}

Primitive Types

The Java binding for primitive schema types are as follows:

(1) Depending on the method, un-boxed types will be preferred to boxed types if applicable when input or output arguments can never be null.

In addition to the standard bindings, custom Java class bindings may be defined for these types to specify a user-defined class as substitute for the standard Java class bindings. For additional details, see Custom Java Class Binding for Primitive Types.

Enum Type

The code generator generates a Java enum class. There will be a corresponding symbol in the Java enum class for each symbol in the enum schema. In addition, the code generator will add a $UNKNOWN symbol to the generated enum class. $UNKNOWN will be returned if the value stored in the Data layer cannot be mapped to a symbol present in the Java enum class. For example, this may occur if an enum symbol has been added to a new version of the enum schema and is transmitted to client that has not been updated with the new enum schema.

Enums also supports a symbolDocs attribute to provide documentation for each enum symbol. E.g.

...
"symbols" : [ "APPLE", "BANANA", ... ],
"symbolDocs" : { "APPLE":"A red, yellow or green fruit.", "BANANA":"A yellow fruit.", ... } 
...

package com.linkedin.pegasus.generator.examples;

...
/**
* A fruit
*
*/
public enum Fruits {

  /**
   * A red, yellow or green fruit.
   * 
   */
  APPLE,

  /**
   * A yellow fruit.
   * 
   */
  BANANA,

  /**
   * An orange fruit.
   * 
   */
  ORANGE,

  /**
   * A yellow fruit.
   * 
   */
  PINEAPPLE,
  $UNKNOWN;
}

Note: Due to the addition of doclint in JDK8, anything under the symbolDocs attribute must be W3C HTML 4.01 compliant. This is because the contents of this string will appear as Javadocs in the generated Java ‘data template’ classes later. Please take this into consideration when writing your documentation.

Fixed Type

The code generator generates a class that extends com.linkedin.data.template.FixedTemplate. This class provides the following methods:

A fixed instance is immutable once constructed.

Array Type

The code generator generates a class that extends com.linkedin.data.template.DirectArrayTemplate<E> or com.linkedin.data.template.WrappingArrayTemplate<E extends DataTemplate<?>>. The latter is used for item types whose Java binding require wrapping. The former is used for items types whose Java binding that do not require wrapping. The E generic type variable is the Java class of the array’s item type. By creating a concrete subclass per map type, this binding avoids lost of item type information due to Java generics type erasure.

The primary characteristics of both base classes are as follows:

• They implement java.util.List<E>.
• Their methods perform runtime checks on updates and inserts to ensure that the value types of arguments are either the exact type specified by the type variable or types that can be coerced to the specified type.

The methods with more specific behavior are described below.

Map Type

The code generator generates a class that extends com.linkedin.data.template.DirectMapTemplate<E> or com.linkedin.data.template.WrappingMapTemplate<E extends DataTemplate<?>>. The latter is used for item types whose Java binding require wrapping. The former is used for items types whose Java binding that do not require wrapping. The E generic type variable is the Java class of the map’s value type. By creating a concrete subclass per map type, this binding avoids lost of value type information due to Java generics type erasure.

The primary characteristics of both base classes are as follows:

• They implement java.util.Map<String, E>.
• Their methods perform runtime checks on updates and inserts to ensure that the value types of arguments are either the exact type specified by the type variable or are types that can be coerced to the specified type.

The methods with somewhat specialized behavior are described below.

Record Type

The code generator generates a class that extends com.linkedin.data.template.RecordTemplate. This class provides the following methods:

The code generator generates the following methods in the generated class for each field. FieldName is the name of field with the first character capitalized.

GetMode

When getting a field from a record, the caller must specify the behavior of the function in case the requested field does not exist in the record.

The available GetModes are:

• NULL
  If the field is present, then return the value of the field. If the field is not present, then return null (even if there is a default value).
• DEFAULT
  If the field is present, then return the value of the field. If the field is not present and there is a default value, then return the default value. If the field is not present and there is no default value, then return null.
• STRICT
  If the field is present, then return the value of the field.
  If the field is not present and the field has a default value, then return the default value.
  If the field is not present and the field is not optional, then throw com.linkedin.data.template.RequiredFieldNotPresentException.
  If the field is not present and the field is optional, then return null.

SetMode

When setting a field in a record, the caller must specify the behavior of the function in case the field is attempted to be set to null.

The available SetModes are:

• IGNORE_NULL
  If the provided value is null, then do nothing i.e. the value of the field is not changed. The field may or may be present.
• REMOVE_IF_NULL
  If the provided value is null, then remove the field. This occurs regardless of whether the field is optional.
• REMOVE_OPTIONAL_IF_NULL
  If the provided value is null and the field is an optional field, then remove the field. If the provided value is null and the field is a mandatory field, then throw java.lang.IllegalArgumentException.
• DISALLOW_NULL
  The provided value cannot be null. If the provided value is null, then throw java.lang.NullPointerException.

package com.linkedin.pegasus.generator.examples;

...

public class Foo extends RecordTemplate
{
    public Foo() ...
    public Foo(DataMap data) ...
    ...

    // intField - field of int type
    public boolean hasIntField() ...
    public void removeIntField() ...
    public Integer getIntField(GetMode mode) ...
    public Integer getIntField() { return getIntField(GetMode.STRICT); }
    public Foo setIntField(int value) { ... ; return this; }
    public Foo setIntField(Integer value, SetMode mode { ... ; return this; }
    ...

    // bytesField - field of bytes, Java binding for bytes is ByteString
    public boolean hasBytesField() ...
    public void removeBytesField() ...
    public ByteString getBytesField(GetMode mode) { return getBytesField(GetMode.STRICT); }
    public ByteString getBytesField() ...
    public Foo setBytesField(ByteString value) { ... ; return this; }
    public Foo setBytesField(ByteString value, SetMode mode) { ... ; return this; }
    ...

    // fruitsField - field of enum
    public boolean hasFruitsField() ...
    public void removeFruitsField() ...
    public Fruits getFruitsField(GetMode mode) ...
    public Fruits getFruitsField() { return getFruitsField(GetMode.STRICT); }
    public Foo setFruitsField(Fruits value) { ... ; return this; }
    public Foo setFruitsField(Fruits value, SetMode mode) { ... ; return this; }
    ...

    // intArrayField - field of { "type" : "array", "items" : "int" }
    public boolean hasIntArrayField() ...
    public void removeIntArrayField() ...
    public IntegerArray getIntArrayField(GetMode mode) ...
    public IntegerArray getIntArrayField() { return getIntArrayField(GetMode.STRICT); }
    public Foo setIntArrayField(IntegerArray value) { ... ; return this; }
    public Foo setIntArrayField(IntegerArray value, SetMode mode) { ... ; return this; }

    // stringMapField - field of { "type" : "map", "values" : "string" }
    public boolean hasStringMapField() ...
    public void removeStringMapField() ...
    public StringMap getStringMapField(GetMode mode) ...
    public StringMap getStringMapField() { return getIntStringMapField(GetMode.STRICT); }
    public Foo setStringMapField(StringMap value) { ... ; return this; }
    public Foo setStringMapField(StringMap value, SetMode mode) { ... ; return this; }
    ...

    // unionField - field of union
    public boolean hasUnionField() ...
    public void removeUnionField() ...
    public Foo.UnionField getUnionField(GetMode mode) ...
    public Foo.UnionField getUnionField() { return getUnionField(GetMode.STRICT); }
    public Foo setUnionField(Foo.UnionField value) { ... ; return this; }
    public Foo setUnionField(Foo.UnionField value, SetMode mode) { ... ; return this; }

    // get fields
    public static Foo.Fields fields() {
        ...;
    }

    public static class Fields
        extends PathSpec
    {
        ...
        public PathSpec intField() { ... }
        public PathSpec longField() { ... }
        public PathSpec bytesField() { ... }
        public PathSpec fruitsField() { ... }
        public PathSpec intArrayField() { ... }
        public PathSpec stringMapField() { ... }
        public Foo.UnionField.Fields unionField() { ... }
    }
}

Error Type

Error types are specialized record types. The code generator generates a class that extends com.linkedin.data.template.ExceptionTemplate. The generated class has the same methods as a generated class for a record with the same fields. Unlike RecordTemplate instances, ExceptionTemplate instances can be thrown and caught. ExceptionTemplate extends java.lang.Exception.

Union Type

The code generator generates a class that extends com.linkedin.data.template.UnionTemplate. This class provides the following methods:

The code generator generates the following methods in the generated class for each member type of the union. In the following table, MemberKey is either the member’s alias (if specified) or the member’s non-fully qualified type name with the first character capitalized.

Here is an example generated class for a union who’s members are not aliased.

package com.linkedin.pegasus.examples;

...
public class Foo extends RecordTemplate
{
  ...
  public final static class UnionField extends UnionTemplate
  {
    public UnionField() ...
    public UnionField(Object data) ...

    // int value
    public boolean isInt() ...
    public Integer getInt() ...
    public void setInt(Integer value) ...

    // string value
    public boolean isString() ...
    public String getString() ...
    public void setString(String value) ...

    // com.linkedin.pegasus.generator.examples.Fruits enum value
    public boolean isFruits() ...
    public Fruits getFruits() ...
    public void setFruits(Fruits value) ...

    // com.linkedin.pegasus.generator.examples.Foo record value
    public boolean isFoo() ...
    public Foo getFoo() ...
    public void setFoo(Foo value) ...

    // array value ({ "type" : "array", "items" : "string" })
    public boolean isArray() ...
    public StringArray getArray() ...
    public void setArray(StringArray value) ...

    // map value ({ "type" : "map", "values" : "long" })
    public boolean isMap() ...
    public LongMap getMap() ...
    public void setMap(LongMap value) ...
  }

  public static class Fields extends PathSpec
  {
    ...
    public Foo.Fields Foo() { ... }
  }
}

For a union who’s members are aliased, the generated methods will use the alias instead of the member’s type name like illustrated below.

package com.linkedin.pegasus.examples;

...
public class Foo extends RecordTemplate
{
  ...
  public final static class UnionField extends UnionTemplate
  {
    public UnionField() ...
    public UnionField(Object data) ...

    // int with alias ({ "type" : "int", "alias" : "count" })
    public UnionField createWithCount(Integer value) ...
    public boolean isCount() ...
    public Integer getCount() ...
    public void setCount(Integer value) ...

    // string with alias ({ "type" : "string", "alias" : "message" })
    public UnionField createWithMessage(String value) ...
    public boolean isMessage() ...
    public String getMessage() ...
    public void setMessage(String value) ...

    // another string with alias ({ "type" : "string", "alias" : "greeting" })
    public UnionField createWithGreeting(String value) ...
    public boolean isGreeting() ...
    public String getGreeting() ...
    public void setGreeting(String value) ...
  }

  public static class Fields extends PathSpec
  {
    ...
    public Foo.Fields Foo() { ... }
  }
}

Custom Java Class Binding for Primitive Types

A typeref can also be used to define a custom Java class binding for a primitive type. The primary intended use is to provide a more developer friendly experience by having the framework perform conversions from primitive type to a more friendly Java class that can implement methods for manipulating the underlying primitive data. Custom Java class binding also provides additional type-safety by allowing typerefs of the same primitive type to be bound to different custom Java classes. This enables compile time type-checking to disambiguate typeref’s, e.g. a Urn typeref to a string can be bound to a different Java class than a FileName typeref to a string.

When a typeref has a custom Java binding, the generated Java data templates that reference this type will accept and return parameters of the custom Java class instead of standard Java class for the primitive type. The value stored in the underlying DataMap or DataList will always be of the corresponding primitive Java type (not the custom Java type.)

A custom Java class binding is declared by:

• defining a typeref of the primitive type,
• adding a “java” attribute whose value is a map to the typeref declaration,
• adding a “class” attribute to the “java” map whose value is a string that identifies the name of custom Java class.

A custom class must meet the following requirements:

1. Instances of the custom class must be immutable.
2. A coercer must be defined that can coerce the primitive Java class of the type to the custom Java class of the type, in both the input and output directions. The coercer implements the DirectCoercer interface.
3. An instance of the coercer must be registered with the data template framework.

{
  "type" : "typeref",
  "name" : "CustomPoint",
  "ref"  : "string",
  "java" : {
    "class" : "CustomPoint"
  }
}

//
// The custom class
// It has to be immutable.
//
public class CustomPoint
{
  private int _x;
  private int _y;

  public CustomPoint(String s)
  {
    String parts[] = s.split(",");
    _x = Integer.parseInt(parts"0":0);
    _y = Integer.parseInt(parts"1":1);
  }

  public CustomPoint(int x, int y)
  {
    _x = x;
    _y = y;
  }

  public int getX()
  {
    return _x;
  }

  public int getY()
  {
    return _y;
  }

  // Implement equals, hashCode, toString, ...

  //
  // The custom class's DirectCoercer.
  //
  public static class CustomPointCoercer implements DirectCoercer<CustomPoint>
  {
    @Override
    public Object coerceInput(CustomPoint object)
      throws ClassCastException
    {
      return object.toString();
    }

    @Override
    public CustomPoint coerceOutput(Object object)
      throws TemplateOutputCastException
    {
      if (object instanceof String == false)
      {
        throw new TemplateOutputCastException("Output " + object + 
                                              " is not a string, and cannot be coerced to " + 
                                              CustomPoint.class.getName());
      }
      return new CustomPoint((String) object);
    }
  }

  //
  // Automatically register Java custom class and its coercer.
  //
  static
  {
    Custom.registerCoercer(CustomPoint.class, new CustomPointCoercer());
  }
}

Fields class

The code generator also generates a Fields class within the generated class for certain complex types. The primary use case for the Fields class is to provide a type-safe way to refer or identify a field within a record or a member of a union. The Fields class of a record is accessed through the generated fields() method of the generated class for a record. Only record types have the generated fields() method.

If there are nested complex types, a path to a particular nested field may be obtained by chaining method invocations on Fields classes along the path to the field, e.g. Foo.fields().barField().bazField(). The path may be used to specify the nested fields to return from a resource request, i.e. deep projection.

The following table summarizes which complex types will have a generated Fields class and the content of the Fields class.

Clone Method

For the classes that wrap DataMap or DataList, their clone method will clone the underlying DataMap or DataList and then create and return a new DataTemplate of the same class to wrap the clone. This clone operation performs a shallow copy.

Escaping for Reserved Words

When symbols such as schema names or enum symbol names are the same as one of the reserved words in Java, the code generator will escape these symbols by appending an underscore (“_”) to the name to obtain the Java name of the symbol.

Exceptions

The Data layer can throw two exceptions:

• java.lang.ClassCastException - This exception is thrown if the input argument to a method is not the expected type, cannot be cast or coerced to the expected type.
• com.linkedin.data.TemplateOutputCastException - This exception if the underlying data cannot be wrapped, cast or coerced to the type to type of the output argument.

Running the Code Generator

The code generator that generates the Java bindings is the com.linkedin.pegasus.generator.PegasusDataTemplateGenerator class.

The arguments to the main method of this class are targetDirectoryPath [sourceFile or schemaName]+”.

• targetDirectoryPath provides the root of the output directory for Java source files generated by the code generator. The output directory structure will follow the Java convention, with Java source files residing in sub-directories corresponding to the package name of the classes in the Java source files.
• sourceFile provides the name of a file. Files containing schemas should have an .pdsc extension. Although a file name provided as an argument to the code generator need not end with .pdsc, only .pdsc files will be read by the schema resolver when trying to resolve a name to schema. Java type: String.
• schemaName provides the fully qualified name of a schema. The schema resolver computes a relative path name from this argument and enumerate through resolver paths to locate a file with this relative name. If a file is found, the code generator will parse the file looking for a schema with the specified name. Java type: String[].

The resolver path is provided by the “generator.resolver.path” property. Its format is the same as the format for Java classpath. Each path is separated by a colon (“:”). Only file system directory paths may be specified (i.e. the resolver does not comprehend .jar files in the resolver path.). You can set this in java by System.setProperty().

The dependencies of the code generator are:

• com.sun.codemodel:codemodel:2.2
• org.codehaus.jackson-core-asl:jackson-core-asl:1.4.0
• com.linkedin.pegasus:cow
• com.linkedin.pegasus:r2
• com.linkedin.pegasus:generator

Running the Code Generator from Command Line

Running the Code Generator with Gradle

A dataTemplate.gradle script is available in the build_script/ directory of pegasus. To use it, add the script to your project, then add this to your build.gradle file:

apply from: "${buildScriptDirPath}/dataTemplate.gradle"

and put the .pdl files in a directory structure of the form: ‘src/\<sourceset\>/pegasus’, where typically it would be src/main/pegasus. The plugin is set to trigger on this sort of directory structure and have the files laid out like a java source tree, ie if the namespace of my foo schema is “com.linkedin.foo.rest.api”, the file would be located at src/main/pegasus/com/linkedin/foo/rest/api/Foo.pdl. See restli-example-api/build.gradle in the Pegasus codebase for an example. This script will generate the required Java classes before the compileJava task, so that other classes can refer to it.

Note this will only generate the data templates, but further steps will be needed to generate the rest.li IDL and the clientModel.