Java Proto Names

Names that are generated by the Java protoc plugin.

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

Starting with Edition 2024, best practice is to:

  • Set option java_package = "com.example.package"
  • Do not set java_outer_classname or features.(pb.java).nest_in_file_class = YES.

Starting with Edition 2024, the default behaviors have otherwise been improved so that now the default behavior is considered current best practice.

When using Proto2, Proto3, or Edition 2023, best practice is to:

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

Explanation

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.

Starting in Edition 2024 this has been replaced by the feature features.(pb.java).nest_in_file_class which has default value of NO, matching the java_multiple_files = true behavior in older syntax.

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";

Starting in Edition 2024, java_outer_classname is still available, but the default behavior has been changed to match this recommendation and so does not need to be set.

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

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

java_multiple_filesjava_packagejava_outer_classnameGenerated full message name
trueNot definedignoredcom.google.protos.$package.$message
trueDefinedignored$java_package.$message
falseNot definedNot definedcom.google.protos.$package.$derived_outer_class.$message
falseNot definedDefinedcom.google.protos.$package.$java_outer_classname.$message
falseDefinedNot defined$java_package.$derived_outer_class.$message
falseDefinedDefined$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.