Commit ce7a2b01 authored by Wink Saville's avatar Wink Saville

Add support for Java micro protobuf's to protobuf-2.3.0.

See README.android for additional information.

Change-Id: I6693e405c0d651eacacd3227a876129865dd0d3c
parent 5ab6e296
......@@ -87,6 +87,180 @@ running unit tests.
4) Install the classes wherever you prefer.
Micro version
============================
The runtime and generated code for MICRO_RUNTIME is smaller
because it does not include support for the descriptor,
reflection or extensions. Also, not currently supported
are packed repeated elements nor testing of java_multiple_files.
To create a jar file for the runtime and run tests invoke
"mvn package -P micro" from the <protobuf-root>/java
directory. The generated jar file is
<protobuf-root>java/target/protobuf-java-2.2.0-micro.jar.
If you wish to compile the MICRO_RUTIME your self, place
the 7 files below, in <root>/com/google/protobuf and
create a jar file for use with your code and the generated
code:
ByteStringMicro.java
CodedInputStreamMicro.java
CodedOutputStreamMicro.java
InvalidProtocolBufferException.java
MessageMicro.java
StringUtf8Micro.java
WireFormatMicro.java
If you wish to change on the code generator it is located
in /src/google/protobuf/compiler/javamicro.
To generate code for the MICRO_RUNTIME invoke protoc with
--javamicro_out command line parameter. javamciro_out takes
a series of optional sub-parameters separated by comma's
and a final parameter, with a colon separator, which defines
the source directory. Sub-paraemeters begin with a name
followed by an equal and if that sub-parameter has multiple
parameters they are seperated by "|". The command line options
are:
opt -> speed or space
java_use_vector -> true or false
java_package -> <file-name>|<package-name>
java_outer_classname -> <file-name>|<package-name>
opt:
This change the code generation to optimize for speed,
opt=speed, or space, opt=space. When opt=speed this
changes the code generation for strings to use
StringUtf8Micro which eliminates multiple conversions
of the string to utf8. The default value is opt=space.
java_use_vector:
Is a boolean flag either java_use_vector=true or
java_use_vector=false. When java_use_vector=true the
code generated for repeated elements uses
java.util.Vector and when java_use_vector=false the
java.util.ArrayList<> is used. When java.util.Vector
is used the code must be compiled with Java 1.3 and
when ArrayList is used Java 1.5 or above must be used.
The using javac the source parameter maybe used to
control the version of the srouce: "javac -source 1.3".
You can also change the <source> xml element for the
maven-compiler-plugin. Below is for 1.5 sources:
<plugin>
<artifactId>maven-compiler-plugin</artifactId>
<configuration>
<source>1.5</source>
<target>1.5</target>
</configuration>
</plugin>
When compiling for 1.5 java_use_vector=false or not
present where the default value is false.
And below would be for 1.3 sources note when changing
to 1.3 you must also set java_use_vector=true:
<plugin>
<artifactId>maven-compiler-plugin</artifactId>
<configuration>
<source>1.3</source>
<target>1.5</target>
</configuration>
</plugin>
java_package:
The allows setting/overriding the java_package option
and associates allows a package name for a file to
be specified on the command line. Overriding any
"option java_package xxxx" in the file. The default
if not present is to use the value from the package
statment or "option java_package xxxx" in the file.
java_outer_classname:
This allows the setting/overriding of the outer
class name option and associates a class name
to a file. An outer class name is required and
must be specified if there are multiple messages
in a single proto file either in the proto source
file or on the command line. If not present the
no outer class name will be used.
Below are a series of examples for clarification of the
various javamicro_out parameters using
src/test/proto/simple-data.proto:
package testprotobuf;
message SimpleData {
optional fixed64 id = 1;
optional string description = 2;
optional bool ok = 3 [default = false];
};
Assuming you've only compiled and not installed protoc and
your current working directory java/, then a simple
command line to compile simple-data would be:
../src/protoc --javamicro_out=. src/test/proto/simple-data.proto
This will create testprotobuf/SimpleData.java
The directory testprotobuf is created because on line 1
of simple-data.proto is "package testprotobuf;". If you
wanted a different package name you could use the
java_package option command line sub-parameter:
../src/protoc '--javamicro_out=java_package=src/test/proto/simple-data.proto|my_package:.' src/test/proto/simple-data.proto
Here you see the new java_package sub-parameter which
itself needs two parameters the file name and the
package name, these are separated by "|". Now you'll
find my_package/SimpleData.java.
If you wanted to also change the optimization for
speed you'd add opt=speed with the comma seperator
as follows:
../src/protoc '--javamicro_out=opt=speed,java_package=src/test/proto/simple-data.proto|my_package:.' src/test/proto/simple-data.proto
Finally if you also wanted an outer class name you'd
do the following:
../src/protoc '--javamicro_out=opt=speed,java_package=src/test/proto/simple-data.proto|my_package,java_outer_classname=src/test/proto/simple-data.proto|OuterName:.' src/test/proto/simple-data.proto
Now you'll find my_packate/OuterName.java.
As mentioned java_package and java_outer_classname
may also be specified in the file. In the example
below we must define java_outer_classname because
there are multiple messages in
src/test/proto/two-messages.proto
package testmicroruntime;
option java_package = "com.example";
option java_outer_classname = "TestMessages";
message TestMessage1 {
required int32 id = 1;
}
message TestMessage2 {
required int32 id = 1;
}
This could be compiled using:
../src/protoc --javamicro_out=. src/test/proto/two-message.proto
With the result will be com/example/TestMessages.java
Usage
=====
......
This diff is collapsed.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment