Skip to content

Files

Latest commit

 

History

History
81 lines (62 loc) · 3.71 KB

java-proto-names.md

File metadata and controls

81 lines (62 loc) · 3.71 KB

+++ title = "Java Proto Names" weight = 655 linkTitle = "Generated Proto Names" description = "Names that are generated by the Java protoc plugin." type = "docs" +++

This document contains information on what the fully-qualified Java name of a proto is, based on the different proto options. This name corresponds to the package you need to import to use that message.

Recommendation { #recommendation }

  • Set option java_multiple_files = true;
  • Set option java_outer_classname = "FileNameProto";
  • Set option java_package = "com.google.package";

Explanation {#explanation}

Multiple Files {#multiple-files}

With java_multiple_files = true, the generated Java class for each message will be placed in a separate .java file. This makes it much easier to move messages from one .proto file to another.

Outer Classname {#outer-classname}

There is a Java class generated for the .proto file itself. The name of the class for the file will be automatically generated if not specified. However, the rules for how that name is generated are overly-complicated and non-obvious. The best policy is to explicitly set the java_outer_classname option to the .proto file name converted to PascalCase with the '.' removed. For example:

  • The file student_record_request.proto should set:

    option java_outer_classname = "StudentRecordRequestProto";

Java Package {#java-package}

The Java package for generated bindings will be automatically set to the proto package. However, this is usually not conformant with Java conventions. To ensure a conventional Java package name, we recommend explicitly setting the java_package option. For example, within Google, the convention is to prepend com.google. to the proto package.

Immutable API Message Names { #immutable-api-message-names }

The Java plugin for protoc will generate names according to this table.

java_multiple_files java_package java_outer_classname Generated full message name
true Not defined ignored com.google.protos.$package.$message
true Defined ignored $java_package.$message
false Not defined Not defined com.google.protos.$package.$derived_outer_class.$message
false Not defined Defined com.google.protos.$package.$java_outer_classname.$message
false Defined Not defined $java_package.$derived_outer_class.$message
false Defined Defined $java_package.$java_outer_classname.$message

Legend

  • $message is the actual name of the proto message.

  • $package is the name of the proto package. This is the name specified by the package directive in the proto file, which is usually at the top of the file.

  • $derived_outer_class is a name generated from the proto file name. Generally it's computed by removing punctuation from the file name and converting it to PascalCase. For example, if the proto is foo_bar.proto, the $derived_outer_class value is FooBar.

    If the generated class name would be the same as one of the messages defined in the proto file, derived_outer_class has OuterClass appended to it. For example, if the proto is foo_bar.proto and contains a FooBar message, the $derived_outer_class value is FooBarOuterClass. The same is true when using the v1 API, whether or not the class name would be the same as one of the messages defined.

  • All other $names are the values of the corresponding file options defined in the .proto file.