From ce7a2b0149bfa8bf78cb6520b2520b54c1a5c250 Mon Sep 17 00:00:00 2001 From: Wink Saville Date: Sat, 29 May 2010 13:13:38 -0700 Subject: Add support for Java micro protobuf's to protobuf-2.3.0. See README.android for additional information. Change-Id: I6693e405c0d651eacacd3227a876129865dd0d3c --- java/README.txt | 174 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 174 insertions(+) (limited to 'java/README.txt') diff --git a/java/README.txt b/java/README.txt index 3ed06a1e..4a2839ab 100644 --- a/java/README.txt +++ b/java/README.txt @@ -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 /java +directory. The generated jar file is +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 /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 -> | +java_outer_classname -> | + +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 xml element for the + maven-compiler-plugin. Below is for 1.5 sources: + + + maven-compiler-plugin + + 1.5 + 1.5 + + + + 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: + + + maven-compiler-plugin + + 1.3 + 1.5 + + + +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 ===== -- cgit v1.2.3