java/README.txt - platform/external/protobuf - Git at Google

 Protocol Buffers - Google's data interchange format
 Copyright 2008 Google Inc.

 This directory contains the Java Protocol Buffers runtime library.

 Installation - With Maven
 =========================

 The Protocol Buffers build is managed using Maven.  If you would
 rather build without Maven, see below.

 1) Install Apache Maven if you don't have it:

      http://maven.apache.org/

 2) Build the C++ code, or obtain a binary distribution of protoc.  If
    you install a binary distribution, make sure that it is the same
    version as this package.  If in doubt, run:

      $ protoc --version

    You will need to place the protoc executable in ../src.  (If you
    built it yourself, it should already be there.)

 3) Run the tests:

      $ mvn test

    If some tests fail, this library may not work correctly on your
    system.  Continue at your own risk.

 4) Install the library into your Maven repository:

      $ mvn install

 5) If you do not use Maven to manage your own build, you can build a
    .jar file to use:

      $ mvn package

    The .jar will be placed in the "target" directory.

 Installation - 'Lite' Version - With Maven
 ==========================================

 Building the 'lite' version of the Java Protocol Buffers library is
 the same as building the full version, except that all commands are
 run using the 'lite' profile.  (see
 http://maven.apache.org/guides/introduction/introduction-to-profiles.html)

 E.g. to install the lite version of the jar, you would run:

   $ mvn install -P lite

 The resulting artifact has the 'lite' classifier.  To reference it
 for dependency resolution, you would specify it as:

   <dependency>
     <groupId>com.google.protobuf</groupId>
     <artifactId>protobuf-java</artifactId>
     <version>${version}</version>
     <classifier>lite</classifier>
   </dependency>

 Installation - Without Maven
 ============================

 If you would rather not install Maven to build the library, you may
 follow these instructions instead.  Note that these instructions skip
 running unit tests.

 1) Build the C++ code, or obtain a binary distribution of protoc.  If
    you install a binary distribution, make sure that it is the same
    version as this package.  If in doubt, run:

      $ protoc --version

    If you built the C++ code without installing, the compiler binary
    should be located in ../src.

 2) Invoke protoc to build DescriptorProtos.java:

      $ protoc --java_out=src/main/java -I../src \
          ../src/google/protobuf/descriptor.proto

 3) Compile the code in src/main/java using whatever means you prefer.

 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
 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 so that multiple
   conversions to Utf8 are eliminated. 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
 =====

 The complete documentation for Protocol Buffers is available via the
 web at:

   http://code.google.com/apis/protocolbuffers/
	Protocol Buffers - Google's data interchange format
	Copyright 2008 Google Inc.

	This directory contains the Java Protocol Buffers runtime library.

	Installation - With Maven
	=========================

	The Protocol Buffers build is managed using Maven. If you would
	rather build without Maven, see below.

	1) Install Apache Maven if you don't have it:

	http://maven.apache.org/

	2) Build the C++ code, or obtain a binary distribution of protoc. If
	you install a binary distribution, make sure that it is the same
	version as this package. If in doubt, run:

	$ protoc --version

	You will need to place the protoc executable in ../src. (If you
	built it yourself, it should already be there.)

	3) Run the tests:

	$ mvn test

	If some tests fail, this library may not work correctly on your
	system. Continue at your own risk.

	4) Install the library into your Maven repository:

	$ mvn install

	5) If you do not use Maven to manage your own build, you can build a
	.jar file to use:

	$ mvn package

	The .jar will be placed in the "target" directory.

	Installation - 'Lite' Version - With Maven
	==========================================

	Building the 'lite' version of the Java Protocol Buffers library is
	the same as building the full version, except that all commands are
	run using the 'lite' profile. (see
	http://maven.apache.org/guides/introduction/introduction-to-profiles.html)

	E.g. to install the lite version of the jar, you would run:

	$ mvn install -P lite

	The resulting artifact has the 'lite' classifier. To reference it
	for dependency resolution, you would specify it as:

	<dependency>
	<groupId>com.google.protobuf</groupId>
	<artifactId>protobuf-java</artifactId>
	<version>${version}</version>
	<classifier>lite</classifier>
	</dependency>

	Installation - Without Maven
	============================

	If you would rather not install Maven to build the library, you may
	follow these instructions instead. Note that these instructions skip
	running unit tests.

	1) Build the C++ code, or obtain a binary distribution of protoc. If
	you install a binary distribution, make sure that it is the same
	version as this package. If in doubt, run:

	$ protoc --version

	If you built the C++ code without installing, the compiler binary
	should be located in ../src.

	2) Invoke protoc to build DescriptorProtos.java:

	$ protoc --java_out=src/main/java -I../src \
	../src/google/protobuf/descriptor.proto

	3) Compile the code in src/main/java using whatever means you prefer.

	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
	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 so that multiple
	conversions to Utf8 are eliminated. 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
	=====

	The complete documentation for Protocol Buffers is available via the
	web at:

	http://code.google.com/apis/protocolbuffers/