{"id":22327144,"url":"https://github.com/msgbuf/msgbuf","last_synced_at":"2025-03-26T06:22:24.452Z","repository":{"id":57730517,"uuid":"367922225","full_name":"msgbuf/msgbuf","owner":"msgbuf","description":"Code generator for GWT-compatible Java data classes suitable for typed client-server messaging","archived":false,"fork":false,"pushed_at":"2024-04-14T18:14:06.000Z","size":3004,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-25T20:23:01.410Z","etag":null,"topics":["dart","data-class","gwt","java","protocol-buffers"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/msgbuf.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2021-05-16T15:42:43.000Z","updated_at":"2023-12-06T08:42:17.000Z","dependencies_parsed_at":"2024-01-21T10:43:35.997Z","dependency_job_id":null,"html_url":"https://github.com/msgbuf/msgbuf","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/msgbuf%2Fmsgbuf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/msgbuf%2Fmsgbuf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/msgbuf%2Fmsgbuf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/msgbuf%2Fmsgbuf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/msgbuf","download_url":"https://codeload.github.com/msgbuf/msgbuf/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245599305,"owners_count":20642073,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dart","data-class","gwt","java","protocol-buffers"],"created_at":"2024-12-04T03:08:29.789Z","updated_at":"2025-03-26T06:22:24.430Z","avatar_url":"https://github.com/msgbuf.png","language":"Java","readme":"# msgbuf\nCode generator for GWT-compatible Java data classes suitable for typed client-server messaging.\n\nInspired by Google's [protocol buffers](https://developers.google.com/protocol-buffers), `msgbuf` provides a code generator that produces data classes out of a concise protocol definition file. \n\nIn contrast to `protobuf`, `msgbuf` supports:\n * Code generation compatible with the [GWT Java-to-Javascript compiler](http://www.gwtproject.org/).\n * Inheritance of data classes.\n * Abstract data classes defining the root of a hierarchy of exchangable data fragments.\n * Polymorphic data compositions.\n * [Visitor pattern](https://en.wikipedia.org/wiki/Visitor_pattern) for processing polomorphic data structures.\n \n`msgbuf` currently serializes messages in JSON format. For GWT-compatibility it uses a modified `JsonReader`/`JsonWriter` from the [gson library](https://github.com/google/gson) that was abstracted from the unsupported `Reader`/`Writer` Java API.\n\n## Setup with Maven\n\n### Add the MsgBuf runtime libary dependency to your project\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003ede.haumacher.msgbuf\u003c/groupId\u003e\n    \u003cartifactId\u003emsgbuf-api\u003c/artifactId\u003e\n    \u003cversion\u003e1.1.5\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n### Add the MsgBuf generator to your pom.xml\n\nTo the `build/plugins` section add:\n\n```xml\n\u003cplugin\u003e\n    \u003cgroupId\u003ede.haumacher.msgbuf\u003c/groupId\u003e\n    \u003cartifactId\u003emsgbuf-generator-maven-plugin\u003c/artifactId\u003e\n    \u003cversion\u003e1.1.5\u003c/version\u003e\n    \n    \u003cexecutions\u003e\n        \u003cexecution\u003e\n            \u003cid\u003egenerate-protocols\u003c/id\u003e\n            \u003cgoals\u003e\n                \u003cgoal\u003egenerate\u003c/goal\u003e\n            \u003c/goals\u003e\n        \u003c/execution\u003e\n    \u003c/executions\u003e\n\u003c/plugin\u003e\n```\n\nNow you are ready to create `*.proto` files in your source folder and build them with `mvn compile`.\n\n## Usage\n \nThe `msgbuf` definition language is an extension of the [proto format](https://developers.google.com/protocol-buffers/docs/proto3) from `protobuf`. A defined message can `extend` another message type, or it can be marked `abstract`. \n\nAssume, you want to describe shapes in a graphics application, you could define the data types as follows. You may start with an `abstract` shape class, defining coordinates of the origin of its coordinate system:\n\nAdd `src/main/java/my/app/model/shape.proto` with the following contents:\n```protobuf\npackage my.app.model;\n\nsyntax = \"msgbuf\";\n\nabstract message Shape {\n  int32 xCoordinate;\n  int32 yCoordinate;\n}\n```\n\nBased on that, you create concrete classes for circles and rectangles:\n\n```protobuf\nmessage Circle extends Shape {\n  int32 radius;\n}\n\nmessage Rectangle extends Shape {\n  int32 width;\n  int32 height;\n}\n```\n\nFinally, you could create a group class that allows combining arbitrary shapes by placing them into a new coordinate system:\n\n```protobuf\nmessage Group extends Shape {\n  repeated Shape shapes;\n}\n```\n\nPassing these definitions to the `msgbuf` compiler gives you a class hierarchy with classes `Shape`, `Circle`, `Rectangle`, and `Group`. You can inspect the generation result in the test package [test.hierarchy](https://github.com/msgbuf/msgbuf/tree/main/de.haumacher.msgbuf.generator/src/test/java/test/hierarchy/data) of the compiler. The source of the example data class definitions can be seen in the [hierarchy.proto](https://github.com/msgbuf/msgbuf/tree/main/de.haumacher.msgbuf.generator/src/test/java/test/hierarchy/data/hierarchy.proto) file.\n\n## Global protocol options\n\n### `@NoJson`\nDisables generation of read and write methods for the JSON format.\n\n### `@NoBinary`\nDisables generation of read and write methods for binary format.\n\n### `@NoXml`\nDisables generation of read and write methods for XML format.\n\n### `@NoXmlNames`\nDisables generation of constants for the XML format.\n\n### `@NoInterfaces`\nDisables generation interfaces for data classes. Normally, data classes are represented by a Java interface. This \nenables multiple inheritance for data classes. To reduce the amout of generated code, this can be disabled for simple \ncases, where no multiple inheritance is required. \n\n### `@NoListener`\nDisables generation of listener interfaces and corresponding registration methods. Add this options, if observing \ndata classes for changes is not required.\n\n### `@NoReflection`\nDisables generation of reflective access methods that allow access to properties through their property names.\n\n### `@NoVisitor`\nDisables generation of visitor interfaces and visit methods. \n\n### `@NoVisitorExceptions`\nProduces visitor interfaces that cannot throw declared exceptions.\n\n### `@NoTypeKind`\nSuppresses the type kind enumeration for a data class hierarchy.\n\n### `@SharedGraph`\nAllows to handle multiple synchronized instances of a data class graph. Each graph can be observed for changes. Changes\ngenerate synchronization messages to keep other instances of the same shared graph up to date. With this option, \na shared graph can be instantiated on a server, transfered to a client while keeping the state in sync when changes \noccur on each side.\n\n## Message options\n\n### Mix-in interfaces (`@Operations(...)`)\n\nThe data classes can extends mix-in interfaces with operations.\n\n```protobuf\n/** The data class */\n@Operations(\"test.operations.DataOperations\")\nmessage Data {\n  int x;\n}\n```\n```java\n/** The mix-in interface with operations on data. */\npublic interface DataOperations {\n    /** Access to the data. */\n    Data self();\n    \n    /** Operation added to data class. */\n    default void inc() {\n        self().setX(self().getX() + 1);\n    }\n}\n\n/** Testing the mix-in operation. */\npublic void testOperations() {\n    Data data = Data.create();\n    data.inc();\n    data.inc();\n    assertEquals(2, data.getX());\n}\n```\n\n## Property options\n\n### `@Nullable`\nA property of a primitive type that does not allow `null` values (e.g. `int` and `string`) can be explicitly marked to \nallow `null` values.\n\n### `@Name(\"myProp\")`\nSets a custom property name. This name is used in JSON serialization.\n\n### `@XmlName(\"myProp\")`\nSets a custom tag name for XML serialization.\n\n### `@Reverse(\"otherProp\")`\nMarks a reference to be the reverse end of the reference with the given name in the target type.\n\n### `@Container`\nMarks a reference point to the container of the current object.\n\n### `@type_id(4711)`\nSets a custom ID for binary serialization.\n\n\n### XML reference embedding (`@Embedded`)\nWhen serializing data classes to XML, all data fields and references are normally represented by XML tags with the same \nname as the field or reference. By adding the `@Embedded` annotation to a reference, the tag for the reference can be \nomitted. The contents of the reference is placed directly within the tag for the containing element. Care must be taken \nthat the tag names for referenced elements do not clash with tag names of other attributes and references of the \ncontainer.\n\nIn the following example, a container with contents A and B can be written `\u003ccontainer\u003e\u003ca/\u003e\u003cb/\u003e\u003c/container\u003e` instead of \nwrapping the contents into an extra element as in `\u003ccontainer\u003e\u003ccontents\u003e\u003ca/\u003e\u003cb/\u003e\u003c/contents\u003e\u003c/container\u003e`. \n \n```protobuf\nmessage Container {\n    @Embedded\n    repeated Base contents;\n}\n\nabstract message Base {}\nmessage A extends Base {}\nmessage B extends Base {}\n```\n\nHowever, even with the `@Embedded` annotation, the verbose serialization with the wrapping reference element is also \nunderstood.\n\n## Plugin options\n`@DartLib(\"../lib/protocol.dart\")`\n\n## Installation in Eclipse\n\nThere is an Eclipse plugin providing a project builder that automatically generates corresponding Java files whenever you create or modify a `*.proto` definition file. To install and enable the plugin with the following steps:\n\n### Add update site\n\n * Open the dialog `Help \u003e Install new Software`.\n * Enter `msgbuf - https://msgbuf.github.io/msgbuf/update-site/` in the `Work with` field, click the `Add...` button, and acknowledge the addition. \n * Select the `MsgBuf Project Builder` checkbox and click `Finish`. \n * Accept the license and the installation of unsigned content.\n\n### Enable the MsgBuf Builder in your project\n\n * Select your project in the `Package Explorer`.\n * In the context menu, select `Configure \u003e Enable MsgBuf Builder`.\n\n### Test the installtion\n\n * Create a `MyMessage.proto` file in one of your packages in the source folder.\n * Add the package definition and a message declaration.\n * Immediately, when you save your changes, a corresponding `MyMessage` class should appear that can be directly used in your code.\n\n## Features\n\n### Polymorphic JSON serialization\n\nAll of the generated data classes have get- and set-methods for their properties. Additionally, each class has methods for writing its contents to JSON format and reading it back:\n\n```java\n/** Reads a new instance from the given reader. */\npublic static Rectangle readRectangle(JsonReader in) throws IOException {\n   ...\n}\n\n/** Writes this instance to the given output. */\npublic final void writeTo(JsonWriter out) throws IOException {\n   ...\n}\n```\n\nIn polymorphic hierarchy of classes as defined above, it is not enough for a class to just write its own properties. Consider a `Group` instance from the example above. Its `shapes` list may contain multiple instances of either circles, rectangles, or even nested groups. Therefore, a class in a polymorphic hierarchy not only serializes its properties, but also its type. Reading back such polymorphic instance instantiates the correct class and fills it with its properties.\n\n### Visitor pattern\n\nFor processing polymorphic messages, generated classes provide support for the [visitor pattern](https://en.wikipedia.org/wiki/Visitor_pattern) to allow writing custom code for each possible sub-type. Since the generated code should not be modified, you cannot add custom code directly to the data class. If you want to process (e.g. render) a received shape instance from the example above, you could of cause use an `instanceof` test to handle circles differently from rectangles and groups. But this leads to fragile code, where one of the possible choices is missed.\n\nA better alternative is the visitor pattern. This allows to separate processing code from the data class hierarchy without `instanceof` tests. An `abstract` base class provides a `Visitor` interface and a `visit(...)` method accepting such a visitor:\n\n```java\npublic abstract class Shape {\n\n   /** Visitor interface for the {@link Shape} hierarchy.*/\n   public interface Visitor\u003cR,A\u003e {\n\n      /** Visit case for {@link Circle}.*/\n      R visit(Circle self, A arg);\n\n     /** Visit case for {@link Rectangle}.*/\n     R visit(Rectangle self, A arg);\n\n     /** Visit case for {@link Group}.*/\n     R visit(Group self, A arg);\n\n   }\n  \n   ...\n\n   /** Accepts the given visitor. */\n   public abstract \u003cR,A\u003e R visit(Visitor\u003cR,A\u003e v, A arg);\n}\n```\n\nEach of the concrete sub-classes implement the `abstract` visit-method by delegating to the correspoinding case-method from the `Visitor` interface:\n\n```java\npublic class Rectangle extends Shape {\n\n   ...\n\n   @Override\n   public \u003cR,A\u003e R visit(Shape.Visitor\u003cR,A\u003e v, A arg) {\n      return v.visit(this, arg);\n   }\n}\n```\n\nThis allow to creating e.g. a renderer implementation that is able to process all concrete types from the shape hierarchy by applying the appropriate code to them:\n\n```java\npublic class ShapeRenderer implements Shape.Visitor\u003cVoid, Graphics2D\u003e {\n   @Override\n   public Void visit(Rectangle self, Graphics2D g2d) {\n      g2d.drawRect(self.getXCoordinate(), self.getYCoordinate(), self.getWidth(), self.getHeight());\n      return null;\n   }\n\n   @Override\n   public Void visit(Circle self, Graphics2D g2d) {\n      ...\n   }\n\n   @Override\n   public Void visit(Group self, Graphics2D g2d) {\n      for (Shape shape : self.getShapes()) {\n         shape.visit(this, g2d);\n      }\n      return null;\n   }\n}\n```\n\nHaving an arbitrary `Shape` instance and a renderer from above, you can render the shape to a `Graphics2D` with the following code:\n\n```java\nShape shape = ...;\nShapeRenderer renderer = ...;\nGraphics2D g2d = ...;\n\nshape.visit(renderer, g2d);\n```\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmsgbuf%2Fmsgbuf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmsgbuf%2Fmsgbuf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmsgbuf%2Fmsgbuf/lists"}