http://protostuff.googlecode.com/files/protostuff.jpg' />

Protostuff is the stuff that leverages google's protobuf.

The 1.0.x versions are hosted on this repo (no new features will be added).

Going forward, all new developments will be on github

A serialization library with built-in support for forward-backward compatibility (schema evolution) and validation. * available formats: * protostuff (native) * graph (protostuff with support for cyclic references. See SerializingObjectGraphs) * protobuf * json * smile (binary json useable from the protostuff-json module) * xml * yaml (ser only) * kvp (binary uwsgi header) * support for messages that are generated by the protostuff-compiler (java_bean) * cyclic references via graph format * see CompilerOptions for more customized compilation of .proto files * support for existing pojos (See runtime schemas) * cyclic references via graph format * polymorphic (a nested message can be an interface/abstract class or even java.lang.Object) * support for existing protoc-generated java messages * see the io instructions for json, xml, yaml) * no support for cyclic references (limitation of the builder pattern)

Interoperability across various mobile platforms * android * kindle * j2me (protostuff-me module)

Transcoding support * converts one encoding to another. See PipeUsage. * Source and Sink * protostuff, protobuf, json, json-numeric, smile, smile-numeric, xml * Sink only * yaml

Latest changes * http://protostuff.googlecode.com/svn/trunk/VERSION.txt

Note that releases are available in the central maven repositories (since 1.0.0)

The protostuff modules:

protostuff-api - 48kb * the serialization api for messages/pojos with built-in support for schema evolution. * Unobtrusive and Flexibile * designed to work with existing objects. All that's needed is a schema, which could be: * code-generated * generated at runtime via protostuff-runtime * hand-written (for more customization) * IO utilities to efficiently write scalar types, base64-code, etc.

protostuff-core - 45kb * bundles 3 binary formats: protostuff, graph and protobuf * Differences from protostuff and protobuf: * protobuf has a field encoding type named "group" and protostuff uses that for the nested messages (w/c gives protostuff the ability to stream messages). * Apart from length-delimited repeated messages, protostuff could use a tail delimiter to handle a stream of messages(could be unbounded). * First class support for cyclic references in the native format * If using the protobuf format, note that: * Unknown fields are discarded (google's protobuf stores them, except for their official python impl) * Extensions not supported * It is not optimized on writes when the data has lots of large nested messages. (you're better off using google's protobuf) * If your app needs to store unknown fields or extensions, you're better off using google's protobuf (and possibly use java_v2protoc_schema for the other formats) * Dependencies: * protostuff-api

protostuff-me - 81kb * module for j2me with no extra dependencies * combines api and core, with the java generics removed

protostuff-collectionschema - 51kb * pre-defined schemas for standard jdk collections (map,collection,list,set,queue,deque,sortedmap,treemap,concurrentmap,etc). * used by protostuff-runtime to efficiently serialize collections with simple generic types (scalar values,enums,pojos) * Dependencies: * protostuff-api

protostuff-runtime - 328kb * automatically enables your existing pojos to ser/deser to various formats. See ProtostuffRuntime * deferred runtime serialization strategies w/c can be configured via system properties. * Dependencies: * protostuff-api * protostuff-collectionschema

protostuff-runtime-md - 272kb * a variant of protostuff-runtime that compiles/runs fine on Modern Devices (such as android and kindle) * Dependencies: * protostuff-api * protostuff-collectionschema

protostuff-runtime-registry - 36kb * benefits polymorphic datasets by using an int as the identifier instead of string (FQCN) * 2 built-in strategies: * ExplicitIdStrategy * all pojos/enums/collections/maps that need to be serialized must be registered during initialization. * IncrementalIdStrategy * No registration needed, ids are generated and mapped on the fly (atomic) * you can optionally reserve the first few ids and register your core pojos during initialization. * Sample code from unit tests are here * Dependencies: * protostuff-runtime/protostuff-runtime-md

protostuff-json - 27kb * json ser/deser for messages/pojos. * forward and backward compatibility for scalar fields. * Dependencies: * protostuff-api * jackson-core-asl-1.7.9 (low-level) - 203kb * If also using the smile format, include jackson-smile-1.7.9 - 47kb

protostuff-xml - 16kb * xml ser/deser for messages/pojos. * forward and backward compatibility for scalar fields. * uses the low-level stax api. * Dependencies: * protostuff-api * stax impl provider (e.g woodstox, aalto, etc)

protostuff-yaml - 8kb * yaml serialization for messages/pojos. * the most human-readable format w/c makes it great for visualizing data (from your webservice/datastore). * Dependencies: * protostuff-api

protostuff-parser * A lexer/parser for .proto files using ANTLR v3 * Used by protostuff-compiler

protostuff-compiler * compiler for .proto sources. * the imported .proto sources could be loaded from the filesystem, classpath or from an http url. * the system property -Dproto_path=$path can also be used to tell the compiler where to load the imported protos from. * can easily be extended/customized to compile to any output. * To compile, execute: java -jar protostuff-compiler-1.0.8-jarjar.jar protostuff.properties

protostuff.properties modules = foo foo.source = path/to/your/foo.proto #java_bean, gwt_overlay, java_v2protoc_schema foo.output = java_bean foo.outputDir = generated foo.options = some_key,key:value,another_key

See the compiler options.

• Currently the implemented compilers are:
  • java_bean
    • simple pojos with cached schemas for ser/deser and validation
    • useable for environments like android and kindle
  • gwt_overlay
    • gwt overlays with built-in json stringify and parse capabilites.
    • features the compiler option "dev_mode" when developing on hosted mode.
  • java_v2protoc_schema
    • complements the existing code generated by c++ protoc
  • java_bean_me
    • a java_bean variant for j2me (removes generics)
  • java_bean_model
    • designed to give you a lot of flexibility for generated schemas through out polymorphism and extended use of annotations.
    • extremely useful when you already have existing pojos (only a schema is generated)
  • proto_extender
    • designed to make one possible to extend his proto messages with another ones
    • works like a preprocessor for your proto files and can help you to handle some inheritance issues
• Dependencies:
  • protostuff-parser

protostuff-maven-plugin * configuration, compilation and code generation of .proto files via maven2 * sample config <plugin> <groupId>com.dyuproject.protostuff</groupId> <artifactId>protostuff-maven-plugin</artifactId> <version>1.0.8</version> <configuration> <protoModules> <protoModule> <source>src/main/resources/media.proto</source> <outputDir>target/generated-sources</outputDir> <output>java_bean</output> <encoding>UTF-8</encoding> <options> <property> <name>separate_schema</name> </property> <property> <name>generate_field_map</name> </property> </options> </protoModule> </protoModules> </configuration> <executions> <execution> <id>generate-sources</id> <phase>generate-sources</phase> <goals> <goal>compile</goal> </goals> </execution> </executions> </plugin>

image made with wordle