Adds example code and some documentation for PST. https://reviews.apache.org/r/43301
Project: http://git-wip-us.apache.org/repos/asf/incubator-wave/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-wave/commit/c3e32934 Tree: http://git-wip-us.apache.org/repos/asf/incubator-wave/tree/c3e32934 Diff: http://git-wip-us.apache.org/repos/asf/incubator-wave/diff/c3e32934 Branch: refs/heads/master Commit: c3e32934bc073c2e9bc53d01943bf3df80b9e22c Parents: 16903c0 Author: Andreas Kotes <[email protected]> Authored: Sun Feb 7 23:06:29 2016 +0200 Committer: Yuri Zelikov <[email protected]> Committed: Sun Feb 7 23:06:29 2016 +0200 ---------------------------------------------------------------------- pst/README.md | 54 ++++++++++++++++++++++++++++++++++++++++++ pst/example/.gitignore | 1 + pst/example/beans.st | 52 ++++++++++++++++++++++++++++++++++++++++ pst/example/example.proto | 14 +++++++++++ pst/example/example.st | 26 ++++++++++++++++++++ 5 files changed, 147 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-wave/blob/c3e32934/pst/README.md ---------------------------------------------------------------------- diff --git a/pst/README.md b/pst/README.md new file mode 100644 index 0000000..93e6084 --- /dev/null +++ b/pst/README.md @@ -0,0 +1,54 @@ + +# PST - Protocol Buffers String Templating + +## Abstract + +PST allows to quickly generate Java Sourcecode from Protocol Buffer +specifications by automating the process of boiler-plating, compilation and +field definition via templates. + +## Building + +Generally, PST is an integral part of the Apache Wave build process, and not +called directly. If you want to build it, you can run + + `gradle build` + +but it'll usually will be built for your. + +## Standalone use + +If you want to test PST directly, you'll need to build a standalone version +with + + `gradle shadowJar` + +which allows you check out the example via + + `java -jar build/libs/wave-pst-0.1.jar -d example -f example/example.proto example/example.st` + +which will result in example/com/example/Person.java being created from the +Protobuf definition of the Person schema in example/example.proto. + +The boilerplate code will be coming from example/example.st, which references +example/broto.st, providing the per-field code definitions. + +## Way of working + +PST generates the corresponding java code using the following steps: + +* protoc is called to create Java code from example/example.proto +* the resulting Example.java is compiled using javac +* each Message definition found in the Protocol Buffer file is matched against + example/example.st +* the resulting Java code is passed through a styler to make it more human-readable + +## Use within Apache Wave + +Apache Wave is using proto2 Protocol Buffers as documented in +https://developers.google.com/protocol-buffers/docs/proto .. the task +generateMessages in wave/build.gradle is responsible for combining String +Templates as per http://www.stringtemplate.org/ to Java Classes. + +A quick introduction to String Templates can be found under +https://theantlrguy.atlassian.net/wiki/display/ST/Five+minute+Introduction http://git-wip-us.apache.org/repos/asf/incubator-wave/blob/c3e32934/pst/example/.gitignore ---------------------------------------------------------------------- diff --git a/pst/example/.gitignore b/pst/example/.gitignore new file mode 100644 index 0000000..6de13f0 --- /dev/null +++ b/pst/example/.gitignore @@ -0,0 +1 @@ +com http://git-wip-us.apache.org/repos/asf/incubator-wave/blob/c3e32934/pst/example/beans.st ---------------------------------------------------------------------- diff --git a/pst/example/beans.st b/pst/example/beans.st new file mode 100644 index 0000000..5e2235b --- /dev/null +++ b/pst/example/beans.st @@ -0,0 +1,52 @@ +/* Example field template in the Public Domain */ + +$if (f.optional)$ + + /** Returns whether $f.name$ has been set. */ + boolean has$f.capName$(); + + /** Clears the value of $f.name$. */ + void clear$f.capName$(); + +$endif$ + +$if (f.repeated)$ + + /** Returns $f.name$, or null if hasn't been set. */ + $if (f.message)$ + List<? extends $f.javaType$> $f.getter$(); + $else$ + List<$f.boxedJavaType$> $f.getter$(); + $endif$ + + /** Adds an element to $f.name$. */ + void add$f.capName$($f.javaType$ value); + + /** Adds a list of elements to $f.name$. */ + $if (f.message)$ + void addAll$f.capName$(List<? extends $f.javaType$> $f.name$); + $else$ + void addAll$f.capName$(List<$f.boxedJavaType$> $f.name$); + $endif$ + + /** Returns the nth element of $f.name$. */ + $f.javaType$ $f.getter$(int n); + + /** Sets the nth element of $f.name$. */ + void $f.setter$(int n, $f.javaType$ value); + + /** Returns the length of $f.name$. */ + int $f.getter$Size(); + + /** Clears $f.name$. */ + void clear$f.capName$(); + +$else$ + + /** Returns $f.name$, or null if hasn't been set. */ + $f.javaType$ $f.getter$(); + + /** Sets $f.name$. */ + void $f.setter$($f.javaType$ $f.name$); + +$endif$ http://git-wip-us.apache.org/repos/asf/incubator-wave/blob/c3e32934/pst/example/example.proto ---------------------------------------------------------------------- diff --git a/pst/example/example.proto b/pst/example/example.proto new file mode 100644 index 0000000..a9601f2 --- /dev/null +++ b/pst/example/example.proto @@ -0,0 +1,14 @@ +// Example protobuffer definition in the Public Domain. + +syntax = "proto2"; + +option java_package = "com.example"; +option java_outer_classname = "Example"; + +package example; + +message Person { + required string name = 1; + required int32 id = 2; // Unique ID number for this person. +} + http://git-wip-us.apache.org/repos/asf/incubator-wave/blob/c3e32934/pst/example/example.st ---------------------------------------------------------------------- diff --git a/pst/example/example.st b/pst/example/example.st new file mode 100644 index 0000000..2d98329 --- /dev/null +++ b/pst/example/example.st @@ -0,0 +1,26 @@ +/* Example Protobuffer Class template in the Public Domain */ + +public interface $m.javaType$ { + + $m.nestedEnums: {e|$enum(e=e)$}$ + $m.nestedMessages: {nested|$interface(m=nested)$}$ + + ///** Does a deep copy from model. */ + void copyFrom($m.javaType$ model); + + /** + * Tests if this model is equal to another object. + * "Equal" is recursively defined as: + * <ul> + * <li>both objects implement this interface,</li> + * <li>all corresponding primitive fields of both objects have the same value, and</li> + * <li>all corresponding nested-model fields of both objects are "equal".</li> + * </ul> + * + * This is a coarser equivalence than provided by the equals() methods. Two + * objects may not be equal() to each other, but may be isEqualTo() each other. + */ + boolean isEqualTo(Object o); + + $m.fields: {f|$beans(f=f)$}$ +}
