Skip to content

Latest commit

 

History

History
155 lines (113 loc) · 5.53 KB

README.md

File metadata and controls

155 lines (113 loc) · 5.53 KB
Raw

Wire Mobile Protocol Buffers

“A man got to have a code!” - Omar Little

Introduction

Wire is a library for lightweight protocol buffers for mobile Java. Code generated by Wire has many fewer methods than standard protocol buffer code, which helps applications avoid the notorious 64k limit on methods in Android applications. Wire also generates clean, human-readable code for protocol buffer messages.

Compiling .proto files

The wire-compiler package contains the WireCompiler class, which compiles standard .proto files into Java source code.

For example, to compile the file protos-repo/google/protobuf/descriptor.proto, which may (recursively) import other .proto files within the protos-repo/ directory:

% mvn clean package

% java -jar wire-compiler/target/wire-compiler-1.0-SNAPSHOT-jar-with-dependencies.jar \
    --proto_path=protos-repo \
    --java_out=out google/protobuf/descriptor.proto

Reading proto source file protos-repo/google/protobuf/descriptor.proto
Writing generated code to out/com/google/protobuf/DescriptorProtos.java

% head -11 out/com/google/protobuf/DescriptorProto.java
// Code generated by Wire protocol buffer compiler, do not edit.
// Source file: protos-repo/google/protobuf/descriptor.proto
package com.google.protobuf;

import com.squareup.wire.Message;
import com.squareup.wire.ProtoField;
import java.util.Collections;
import java.util.List;

public final class DescriptorProto
    implements Message {

Instead of supplying individual filename arguments on the command line, the --files flag may be used to specify a single file containing a list of .proto files. The file names are interpreted relative to the value given for the --proto_path flag.

% cat protos.include
google/protobuf/descriptor.proto
yourcompany/protos/stuff.proto
...

% java -jar wire-compiler/target/wire-compiler-1.0-SNAPSHOT-jar-with-dependencies.jar \
    --proto_path=protos-repo \
    --java_out=out \
    --files=protos.include

Reading proto source file protos-repo/google/protobuf/descriptor.proto
Writing generated code to out/com/google/protobuf/DescriptorProtos.java
Reading proto source file protos-repo/yourcompany/protos/stuff.proto
Writing generated code to out/com/yourcompany/protos/stuff/Stuff.java
...

The compiler will (recursively) import any needed .proto files from the protos-repo/ directory, but will only generate output for the .proto files listed on the command line or in the file specified by the --files flag.

Using Wire in your application

The wire-runtime package contains runtime support libraries that must be included in applications that use Wire-generated code.

For Maven projects, simply add wire-runtime as a dependency:

<dependency>
  <groupId>com.squareup.wire</groupId>
  <artifactId>wire-runtime</artifactId>
  <version>(latest version)</version>
</dependency>

How Wire works

The Wire compiler generates a Java class for each message or enum defined in a .proto file specified on the command line. Each message class has an associated Builder class that may be used to construct an instance manually:

MyMessage msg = new MyMessage.Builder().some_int_field(123).build();

Note that field names are not converted to camel case.

Wire messages contain a public final field for each field of the protocol buffer message. Each field is annotated with a @ProtoField annotation containing the field metadata required by the Wire runtime.

Numeric and boolean values are stored using boxed primitive types (e.g., Integer or Long). If a field is unset, its value is null. Wire does not generate methods such as getXXX(), hasXXX(), setXXX(), etc. Repeated fields are stored as Lists of values.

A field some_field has a constant DEFAULT_SOME_FIELD containing the default value for that field. A convenience method Wire.get allows substitution of a default value for null:

// Equivalent to:
// x = msg.some_field != null ? msg.some_field :  MyMessage.DEFAULT_SOME_FIELD

int x = Wire.get(msg.some_field, MyMessage.DEFAULT_SOME_FIELD);

Builders contain a public field for each field of the protocol buffer message, as well as a method with the same name that sets the given value and returns the Builder instance for chaining.

You can serialize a message by calling its write or toByteArray methods:

byte[] serializedMsg = msg.toByteArray();

To parse messages from their serialized representations, use the Wire class. Typically you will want to create a singleton instance of Wire for use throughout your application.

Wire wire = new Wire();
MyMessage newMsg = wire.parseFrom(MyMessage.class, serializedMsg);
int x = newMsg.some_int_field; // 123

To use protocol buffer extensions, pass the classes that define the extensions you wish to use as arguments to the Wire constructor:

// Assume MessageWithExtensions contains a message SomeMessage that defines
// an extension field some_extension to the MyMessage message.
Wire wire = new Wire(Ext_SomeMessage.class);
MyMessage msg = new MyMessage.Builder()
    .setExtension(Ext_SomeMessage.some_extension, 3)
    .build();
int x = msg.getExtension(Ext_SomeMessage.some_extension); // 3

Unsupported

Wire does not support:

  • Groups - they are skipping when parsing binary input data
  • Services - they are ignored by the compiler
  • Custom options - they are ignored