README.txt revision e2d542951c059563a3b7f74c257dac4f222d9dc5
1Protocol Buffers - Google's data interchange format 2Copyright 2008 Google Inc. 3 4This directory contains the Java Protocol Buffers runtime library. 5 6Installation - With Maven 7========================= 8 9The Protocol Buffers build is managed using Maven. If you would 10rather build without Maven, see below. 11 121) Install Apache Maven if you don't have it: 13 14 http://maven.apache.org/ 15 162) Build the C++ code, or obtain a binary distribution of protoc. If 17 you install a binary distribution, make sure that it is the same 18 version as this package. If in doubt, run: 19 20 $ protoc --version 21 22 You will need to place the protoc executable in ../src. (If you 23 built it yourself, it should already be there.) 24 253) Run the tests: 26 27 $ mvn test 28 29 If some tests fail, this library may not work correctly on your 30 system. Continue at your own risk. 31 324) Install the library into your Maven repository: 33 34 $ mvn install 35 365) If you do not use Maven to manage your own build, you can build a 37 .jar file to use: 38 39 $ mvn package 40 41 The .jar will be placed in the "target" directory. 42 43Installation - 'Lite' Version - With Maven 44========================================== 45 46Building the 'lite' version of the Java Protocol Buffers library is 47the same as building the full version, except that all commands are 48run using the 'lite' profile. (see 49http://maven.apache.org/guides/introduction/introduction-to-profiles.html) 50 51E.g. to install the lite version of the jar, you would run: 52 53 $ mvn install -P lite 54 55The resulting artifact has the 'lite' classifier. To reference it 56for dependency resolution, you would specify it as: 57 58 <dependency> 59 <groupId>com.google.protobuf</groupId> 60 <artifactId>protobuf-java</artifactId> 61 <version>${version}</version> 62 <classifier>lite</classifier> 63 </dependency> 64 65Installation - Without Maven 66============================ 67 68If you would rather not install Maven to build the library, you may 69follow these instructions instead. Note that these instructions skip 70running unit tests. 71 721) Build the C++ code, or obtain a binary distribution of protoc. If 73 you install a binary distribution, make sure that it is the same 74 version as this package. If in doubt, run: 75 76 $ protoc --version 77 78 If you built the C++ code without installing, the compiler binary 79 should be located in ../src. 80 812) Invoke protoc to build DescriptorProtos.java: 82 83 $ protoc --java_out=src/main/java -I../src \ 84 ../src/google/protobuf/descriptor.proto 85 863) Compile the code in src/main/java using whatever means you prefer. 87 884) Install the classes wherever you prefer. 89 90Micro version 91============================ 92 93The runtime and generated code for MICRO_RUNTIME is smaller 94because it does not include support for the descriptor, 95reflection or extensions. Also, not currently supported 96are packed repeated elements nor testing of java_multiple_files. 97 98To create a jar file for the runtime and run tests invoke 99"mvn package -P micro" from the <protobuf-root>/java 100directory. The generated jar file is 101<protobuf-root>java/target/protobuf-java-2.2.0-micro.jar. 102 103If you wish to compile the MICRO_RUTIME your self, place 104the 7 files below, in <root>/com/google/protobuf and 105create a jar file for use with your code and the generated 106code: 107 108ByteStringMicro.java 109CodedInputStreamMicro.java 110CodedOutputStreamMicro.java 111InvalidProtocolBufferException.java 112MessageMicro.java 113StringUtf8Micro.java 114WireFormatMicro.java 115 116If you wish to change on the code generator it is located 117in /src/google/protobuf/compiler/javamicro. 118 119To generate code for the MICRO_RUNTIME invoke protoc with 120--javamicro_out command line parameter. javamciro_out takes 121a series of optional sub-parameters separated by comma's 122and a final parameter, with a colon separator, which defines 123the source directory. Sub-paraemeters begin with a name 124followed by an equal and if that sub-parameter has multiple 125parameters they are seperated by "|". The command line options 126are: 127 128opt -> speed or space 129java_use_vector -> true or false 130java_package -> <file-name>|<package-name> 131java_outer_classname -> <file-name>|<package-name> 132 133opt: 134 This change the code generation to optimize for speed, 135 opt=speed, or space, opt=space. When opt=speed this 136 changes the code generation for strings to use 137 StringUtf8Micro which eliminates multiple conversions 138 of the string to utf8. The default value is opt=space. 139 140java_use_vector: 141 Is a boolean flag either java_use_vector=true or 142 java_use_vector=false. When java_use_vector=true the 143 code generated for repeated elements uses 144 java.util.Vector and when java_use_vector=false the 145 java.util.ArrayList<> is used. When java.util.Vector 146 is used the code must be compiled with Java 1.3 and 147 when ArrayList is used Java 1.5 or above must be used. 148 The using javac the source parameter maybe used to 149 control the version of the srouce: "javac -source 1.3". 150 You can also change the <source> xml element for the 151 maven-compiler-plugin. Below is for 1.5 sources: 152 153 <plugin> 154 <artifactId>maven-compiler-plugin</artifactId> 155 <configuration> 156 <source>1.5</source> 157 <target>1.5</target> 158 </configuration> 159 </plugin> 160 161 When compiling for 1.5 java_use_vector=false or not 162 present where the default value is false. 163 164 And below would be for 1.3 sources note when changing 165 to 1.3 you must also set java_use_vector=true: 166 167 <plugin> 168 <artifactId>maven-compiler-plugin</artifactId> 169 <configuration> 170 <source>1.3</source> 171 <target>1.5</target> 172 </configuration> 173 </plugin> 174 175java_package: 176 The allows setting/overriding the java_package option 177 and associates allows a package name for a file to 178 be specified on the command line. Overriding any 179 "option java_package xxxx" in the file. The default 180 if not present is to use the value from the package 181 statment or "option java_package xxxx" in the file. 182 183java_outer_classname: 184 This allows the setting/overriding of the outer 185 class name option and associates a class name 186 to a file. An outer class name is required and 187 must be specified if there are multiple messages 188 in a single proto file either in the proto source 189 file or on the command line. If not present the 190 no outer class name will be used. 191 192Below are a series of examples for clarification of the 193various javamicro_out parameters using 194src/test/proto/simple-data.proto: 195 196package testprotobuf; 197 198message SimpleData { 199 optional fixed64 id = 1; 200 optional string description = 2; 201 optional bool ok = 3 [default = false]; 202}; 203 204 205Assuming you've only compiled and not installed protoc and 206your current working directory java/, then a simple 207command line to compile simple-data would be: 208 209../src/protoc --javamicro_out=. src/test/proto/simple-data.proto 210 211This will create testprotobuf/SimpleData.java 212 213The directory testprotobuf is created because on line 1 214of simple-data.proto is "package testprotobuf;". If you 215wanted a different package name you could use the 216java_package option command line sub-parameter: 217 218../src/protoc '--javamicro_out=java_package=src/test/proto/simple-data.proto|my_package:.' src/test/proto/simple-data.proto 219 220Here you see the new java_package sub-parameter which 221itself needs two parameters the file name and the 222package name, these are separated by "|". Now you'll 223find my_package/SimpleData.java. 224 225If you wanted to also change the optimization for 226speed you'd add opt=speed with the comma seperator 227as follows: 228 229../src/protoc '--javamicro_out=opt=speed,java_package=src/test/proto/simple-data.proto|my_package:.' src/test/proto/simple-data.proto 230 231Finally if you also wanted an outer class name you'd 232do the following: 233 234../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 235 236Now you'll find my_packate/OuterName.java. 237 238As mentioned java_package and java_outer_classname 239may also be specified in the file. In the example 240below we must define java_outer_classname because 241there are multiple messages in 242src/test/proto/two-messages.proto 243 244package testmicroruntime; 245 246option java_package = "com.example"; 247option java_outer_classname = "TestMessages"; 248 249message TestMessage1 { 250 required int32 id = 1; 251} 252 253message TestMessage2 { 254 required int32 id = 1; 255} 256 257This could be compiled using: 258 259../src/protoc --javamicro_out=. src/test/proto/two-message.proto 260 261With the result will be com/example/TestMessages.java 262 263 264Usage 265===== 266 267The complete documentation for Protocol Buffers is available via the 268web at: 269 270 http://code.google.com/apis/protocolbuffers/ 271