This is a Java implementation of Cap’n Proto. It has two main components:
A Java package
org.capnprotothat provides runtime support for
capnpc-java’s generated code.
These components let you make your data mobile,
so that you can manipulate your data in Java
and also easily communicate it
to distributed components written
in other programming languages.
Under the hood, all operations are
If you, for example, want to communicate over a
network, you can just directly write the bytes to the wire.
There is no encode or decode step!
We hope eventually to provide support in Java for a distributed object-capability layer built on top of this serialization layer, but we have not embarked on that project yet.
Schema Compiler and Plugin
You will need to install the
latest release of the Cap’n Proto schema compiler.
in the root directory of the capnproto-java repository
On Windows, you can instead grab a prebuilt win32 executable from here:
For help on how to invoke the schema compiler:
capnp compile --help
Note that you’ll need to include
java.capnp so that you can use the
annotations. This schema is located in
You might find useful this Maven Plugin.
The runtime is available on The Central Repository.
We use maven for building and testing the Java code.
mvn compile at the top-level directory should build
mvn test should run the test suite.
We can define types in a schema like this:
Then, after running the schema compiler, we can then use those types from Java like this:
To read a message:
$ echo '(people = [(id = 123, name = "Alice",' \ 'email = "firstname.lastname@example.org", employment = (school = "MIT"))])' \ | capnp encode --packed examples/src/main/schema/addressbook.capnp \ AddressBook \ | java -cp runtime/target/classes:examples/target/classes \ org.capnproto.examples.AddressbookMain read
To write a message:
$ java -cp runtime/target/classes:examples/target/classes \ org.capnproto.examples.AddressbookMain write \ | capnp decode --packed examples/src/main/schema/addressbook.capnp \ AddressBook
The classes and methods provided by the Java runtime and generated code correspond directly to those provided by the C++ implementation, with just a few adjustments.
Java does not have unsigned integer types, so a
UInt64in a schema gets mapped to a
longin Java, a
UInt32gets mapped to an
intin Java, and so on. You are responsible for correctly handling arithmetic on values of these types. Note that Java 8 has standard functions that can help with this.
Because Java generics don’t get monomorphized at compile time like C++ templates do, generic methods need to have an additional factory argument to allow the proper dispatch to occur.
MessageBuilder.initRoot()are two examples, as shown above.
- The main I/O methods in
SerializePackedare written in terms of
ReadableByteChannel. You should be very careful if you try to convert a
java.nio.channels.Channels.newChannel()method. If your
OutputStreamwas buffered, the new channel-based wrapper of it will have no way to flush it! Note that the stream returned by
There’s a lot left to do, and we’d love to have your help! Here are some missing pieces: