add example code and some documentation
Project: http://git-wip-us.apache.org/repos/asf/incubator-wave/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-wave/commit/7847a841 Tree: http://git-wip-us.apache.org/repos/asf/incubator-wave/tree/7847a841 Diff: http://git-wip-us.apache.org/repos/asf/incubator-wave/diff/7847a841 Branch: refs/heads/master Commit: 7847a841dd6fbacb7a2d413ec3fe5b7fd4e916cc Parents: d5f2f78 Author: Andreas 'count' Kotes <co...@flatline.de> Authored: Tue Feb 2 19:08:00 2016 +0100 Committer: Andreas 'count' Kotes <co...@flatline.de> Committed: Tue Feb 2 19:08:00 2016 +0100 ---------------------------------------------------------------------- pst/README.md | 58 ++++++++++++++++++++++++++++++++++++++++++ pst/example/.gitignore | 1 + pst/example/beans.st | 52 +++++++++++++++++++++++++++++++++++++ pst/example/example.proto | 14 ++++++++++ pst/example/example.st | 26 +++++++++++++++++++ 5 files changed, 151 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-wave/blob/7847a841/pst/README.md ---------------------------------------------------------------------- diff --git a/pst/README.md b/pst/README.md new file mode 100644 index 0000000..b006f84 --- /dev/null +++ b/pst/README.md @@ -0,0 +1,58 @@ + +# 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 + +execve("/usr/bin/java", ["java", "-jar", "build/libs/wave-pst-0.1.jar", "-d", "example", "-f", "example/example.proto", "example/example.st"], [/* 32 vars */]) = 0 +[pid 12254] execve("/usr/bin/protoc", ["protoc", "example/example.proto", "-I.", "--java_out", "/tmp/1454436070071-0"], [/* 34 vars */]) = 0 +[pid 12259] execve("/usr/bin/javac", ["javac", "/tmp/1454436070071-0/com/example/Example.java", "-d", "/tmp/1454436070071-0", "-verbose", "-cp", "//tmp/1454436070071-0/:/home/count/repos/github-berlincount-incubator-wave/pst/build/libs/wave-pst-0.1.jar"], [/* 34 vars */]) = 0 http://git-wip-us.apache.org/repos/asf/incubator-wave/blob/7847a841/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/7847a841/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/7847a841/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/7847a841/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)$}$ +}
