com.google.protobuf:protobuf-java - maven Package Compare versions

Comparing version 4.34.2 to 4.35.0-RC1

google/protobuf/any.proto

@@ -45,119 +45,63 @@ // Protocol Buffers - Google's data interchange format
 //
-// Protobuf library provides support to pack/unpack Any values in the form
-// of utility functions or additional generated methods of the Any type.
+// In its binary encoding, an `Any` is an ordinary message; but in other wire
+// forms like JSON, it has a special encoding. The format of the type URL is
+// described on the `type_url` field.
 //
-// Example 1: Pack and unpack a message in C++.
+// Protobuf APIs provide utilities to interact with `Any` values:
 //
-//     Foo foo = ...;
-//     Any any;
-//     any.PackFrom(foo);
-//     ...
-//     if (any.UnpackTo(&foo)) {
-//       ...
-//     }
+// - A 'pack' operation accepts a message and constructs a generic `Any` wrapper
+//   around it.
+// - An 'unpack' operation reads the content of an `Any` message, either into an
+//   existing message or a new one. Unpack operations must check the type of the
+//   value they unpack against the declared `type_url`.
+// - An 'is' operation decides whether an `Any` contains a message of the given
+//   type, i.e. whether it can 'unpack' that type.
 //
-// Example 2: Pack and unpack a message in Java.
+// The JSON format representation of an `Any` follows one of these cases:
 //
-//     Foo foo = ...;
-//     Any any = Any.pack(foo);
-//     ...
-//     if (any.is(Foo.class)) {
-//       foo = any.unpack(Foo.class);
-//     }
-//     // or ...
-//     if (any.isSameTypeAs(Foo.getDefaultInstance())) {
-//       foo = any.unpack(Foo.getDefaultInstance());
-//     }
+// - For types without special-cased JSON encodings, the JSON format
+//   representation of the `Any` is the same as that of the message, with an
+//   additional `@type` field which contains the type URL.
+// - For types with special-cased JSON encodings (typically called 'well-known'
+//   types, listed in https://protobuf.dev/programming-guides/json/#any), the
+//   JSON format representation has a key `@type` which contains the type URL
+//   and a key `value` which contains the JSON-serialized value.
 //
-//  Example 3: Pack and unpack a message in Python.
-//
-//     foo = Foo(...)
-//     any = Any()
-//     any.Pack(foo)
-//     ...
-//     if any.Is(Foo.DESCRIPTOR):
-//       any.Unpack(foo)
-//       ...
-//
-//  Example 4: Pack and unpack a message in Go
-//
-//      foo := &pb.Foo{...}
-//      any, err := anypb.New(foo)
-//      if err != nil {
-//        ...
-//      }
-//      ...
-//      foo := &pb.Foo{}
-//      if err := any.UnmarshalTo(foo); err != nil {
-//        ...
-//      }
-//
-// The pack methods provided by protobuf library will by default use
-// 'type.googleapis.com/full.type.name' as the type URL and the unpack
-// methods only use the fully qualified type name after the last '/'
-// in the type URL, for example "foo.bar.com/x/y.z" will yield type
-// name "y.z".
-//
-// JSON
-// ====
-// The JSON representation of an `Any` value uses the regular
-// representation of the deserialized, embedded message, with an
-// additional field `@type` which contains the type URL. Example:
-//
-//     package google.profile;
-//     message Person {
-//       string first_name = 1;
-//       string last_name = 2;
-//     }
-//
-//     {
-//       "@type": "type.googleapis.com/google.profile.Person",
-//       "firstName": <string>,
-//       "lastName": <string>
-//     }
-//
-// If the embedded message type is well-known and has a custom JSON
-// representation, that representation will be embedded adding a field
-// `value` which holds the custom JSON in addition to the `@type`
-// field. Example (for message [google.protobuf.Duration][]):
-//
-//     {
-//       "@type": "type.googleapis.com/google.protobuf.Duration",
-//       "value": "1.212s"
-//     }
-//
+// The text format representation of an `Any` is like a message with one field
+// whose name is the type URL in brackets. For example, an `Any` containing a
+// `foo.Bar` message may be written `[type.googleapis.com/foo.Bar] { a: 2 }`.
 message Any {
-  // A URL/resource name that uniquely identifies the type of the serialized
-  // protocol buffer message. This string must contain at least
-  // one "/" character. The last segment of the URL's path must represent
-  // the fully qualified name of the type (as in
-  // `path/google.protobuf.Duration`). The name should be in a canonical form
-  // (e.g., leading "." is not accepted).
+  // Identifies the type of the serialized Protobuf message with a URI reference
+  // consisting of a prefix ending in a slash and the fully-qualified type name.
   //
-  // In practice, teams usually precompile into the binary all types that they
-  // expect it to use in the context of Any. However, for URLs which use the
-  // scheme `http`, `https`, or no scheme, one can optionally set up a type
-  // server that maps type URLs to message definitions as follows:
+  // Example: type.googleapis.com/google.protobuf.StringValue
   //
-  // * If no scheme is provided, `https` is assumed.
-  // * An HTTP GET on the URL must yield a [google.protobuf.Type][]
-  //   value in binary format, or produce an error.
-  // * Applications are allowed to cache lookup results based on the
-  //   URL, or have them precompiled into a binary to avoid any
-  //   lookup. Therefore, binary compatibility needs to be preserved
-  //   on changes to types. (Use versioned type names to manage
-  //   breaking changes.)
+  // This string must contain at least one `/` character, and the content after
+  // the last `/` must be the fully-qualified name of the type in canonical
+  // form, without a leading dot. Do not write a scheme on these URI references
+  // so that clients do not attempt to contact them.
   //
-  // Note: this functionality is not currently available in the official
-  // protobuf release, and it is not used for type URLs beginning with
-  // type.googleapis.com. As of May 2023, there are no widely used type server
-  // implementations and no plans to implement one.
+  // The prefix is arbitrary and Protobuf implementations are expected to
+  // simply strip off everything up to and including the last `/` to identify
+  // the type. `type.googleapis.com/` is a common default prefix that some
+  // legacy implementations require. This prefix does not indicate the origin of
+  // the type, and URIs containing it are not expected to respond to any
+  // requests.
   //
-  // Schemes other than `http`, `https` (or the empty scheme) might be
-  // used with implementation specific semantics.
+  // All type URL strings must be legal URI references with the additional
+  // restriction (for the text format) that the content of the reference
+  // must consist only of alphanumeric characters, percent-encoded escapes, and
+  // characters in the following set (not including the outer backticks):
+  // `/-.~_!$&()*+,;=`. Despite our allowing percent encodings, implementations
+  // should not unescape them to prevent confusion with existing parsers. For
+  // example, `type.googleapis.com%2FFoo` should be rejected.
   //
+  // In the original design of `Any`, the possibility of launching a type
+  // resolution service at these type URLs was considered but Protobuf never
+  // implemented one and considers contacting these URLs to be problematic and
+  // a potential security issue. Do not attempt to contact type URLs.
   string type_url = 1;
 
-  // Must be a valid serialized protocol buffer of the above specified type.
+  // Holds a Protobuf serialization of the type described by type_url.
   bytes value = 2;
 }

google/protobuf/descriptor.proto

 // Protocol Buffers - Google's data interchange format
-// Copyright 2008 Google Inc.  All rights reserved.
-// https://developers.google.com/protocol-buffers/
+// Copyright 2008 Google LLC.  All rights reserved.
 //
-// Redistribution and use in source and binary forms, with or without
-// modification, are permitted provided that the following conditions are
-// met:
-//
-//     * Redistributions of source code must retain the above copyright
-// notice, this list of conditions and the following disclaimer.
-//     * Redistributions in binary form must reproduce the above
-// copyright notice, this list of conditions and the following disclaimer
-// in the documentation and/or other materials provided with the
-// distribution.
-//     * Neither the name of Google Inc. nor the names of its
-// contributors may be used to endorse or promote products derived from
-// this software without specific prior written permission.
-//
-// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
-// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
-// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
-// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
-// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
-// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
-// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
-// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
-// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
-// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file or at
+// https://developers.google.com/open-source/licenses/bsd
 
@@ -88,2 +65,3 @@ // Author: [e-mail] (Kenton Varda)
   EDITION_2024 = 1001;
+  EDITION_2026 = 1002;
 
@@ -193,2 +171,5 @@ // A placeholder edition for developing and testing unscheduled features.
 message ExtensionRangeOptions {
+  // Range reserved for first-class custom options defined by the Protobuf
+  // team. User custom options must use the 1000+ range instead.
+  extensions 990 to 998;
   // The parser stores options it doesn't recognize here. See above.
@@ -588,2 +569,10 @@ repeated UninterpretedOption uninterpreted_option = 999;
 
+  // Range reserved for first-class custom options defined by the Protobuf
+  // team. User custom options must use the 1000+ range instead.
+  extensions 990 to 998 [declaration = {
+    number: 990,
+    full_name: ".pb.file.cpp",
+    type: ".pb.file.CppFileOptions"
+  }];
+
   // The parser stores options it doesn't recognize here.
@@ -678,2 +667,6 @@ // See the documentation for the "Options" section above.
 
+  // Range reserved for first-class custom options defined by the Protobuf
+  // team. User custom options must use the 1000+ range instead.
+  extensions 990 to 998;
+
   // The parser stores options it doesn't recognize here. See above.
@@ -849,2 +842,6 @@ repeated UninterpretedOption uninterpreted_option = 999;
 
+  // Range reserved for first-class custom options defined by the Protobuf
+  // team. User custom options must use the 1000+ range instead.
+  extensions 990 to 998;
+
   // The parser stores options it doesn't recognize here. See above.
@@ -867,2 +864,6 @@ repeated UninterpretedOption uninterpreted_option = 999;
 
+  // Range reserved for first-class custom options defined by the Protobuf
+  // team. User custom options must use the 1000+ range instead.
+  extensions 990 to 998;
+
   // The parser stores options it doesn't recognize here. See above.
@@ -903,2 +904,6 @@ repeated UninterpretedOption uninterpreted_option = 999;
 
+  // Range reserved for first-class custom options defined by the Protobuf
+  // team. User custom options must use the 1000+ range instead.
+  extensions 990 to 998;
+
   // The parser stores options it doesn't recognize here. See above.
@@ -932,2 +937,6 @@ repeated UninterpretedOption uninterpreted_option = 999;
 
+  // Range reserved for first-class extension options defined by the Protobuf
+  // team. Custom options must use the 1000+ range instead.
+  extensions 990 to 998;
+
   // The parser stores options it doesn't recognize here. See above.
@@ -959,2 +968,6 @@ repeated UninterpretedOption uninterpreted_option = 999;
 
+  // Range reserved for first-class custom options defined by the Protobuf
+  // team. User custom options must use the 1000+ range instead.
+  extensions 990 to 998;
+
   // The parser stores options it doesn't recognize here. See above.
@@ -997,2 +1010,6 @@ repeated UninterpretedOption uninterpreted_option = 999;
 
+  // Range reserved for first-class custom options defined by the Protobuf
+  // team. User custom options must use the 1000+ range instead.
+  extensions 990 to 998;
+
   // The parser stores options it doesn't recognize here. See above.
@@ -1146,2 +1163,3 @@ repeated UninterpretedOption uninterpreted_option = 999;
     STYLE_LEGACY = 2;
+    STYLE2026 = 3;
   }
@@ -1163,3 +1181,4 @@ optional EnforceNamingStyle enforce_naming_style = 7 [
     edition_defaults = { edition: EDITION_LEGACY, value: "STYLE_LEGACY" },
-    edition_defaults = { edition: EDITION_2024, value: "STYLE2024" }
+    edition_defaults = { edition: EDITION_2024, value: "STYLE2024" },
+    edition_defaults = { edition: EDITION_UNSTABLE, value: "STYLE2026" }
   ];
@@ -1218,2 +1237,7 @@
     declaration = {
+      number: 1004,
+      full_name: ".pb.csharp",
+      type: ".pb.CSharpFeatures"
+    },
+    declaration = {
       number: 1100,
@@ -1220,0 +1244,0 @@ full_name: ".imp.impress_feature_set",

google/protobuf/struct.proto

@@ -43,10 +43,15 @@ // Protocol Buffers - Google's data interchange format
 
-// `Struct` represents a structured data value, consisting of fields
-// which map to dynamically typed values. In some languages, `Struct`
-// might be supported by a native representation. For example, in
-// scripting languages like JS a struct is represented as an
-// object. The details of that representation are described together
-// with the proto support for the language.
+// Represents a JSON object.
 //
-// The JSON representation for `Struct` is JSON object.
+// An unordered key-value map, intending to perfectly capture the semantics of a
+// JSON object. This enables parsing any arbitrary JSON payload as a message
+// field in ProtoJSON format.
+//
+// This follows RFC 8259 guidelines for interoperable JSON: notably this type
+// cannot represent large Int64 values or `NaN`/`Infinity` numbers,
+// since the JSON format generally does not support those values in its number
+// type.
+//
+// If you do not intend to parse arbitrary JSON into your message, a custom
+// typed message should be preferred instead of using this type.
 message Struct {
@@ -57,22 +62,30 @@ // Unordered map of dynamically typed values.
 
+// Represents a JSON value.
+//
 // `Value` represents a dynamically typed value which can be either
 // null, a number, a string, a boolean, a recursive struct value, or a
 // list of values. A producer of value is expected to set one of these
-// variants. Absence of any variant indicates an error.
-//
-// The JSON representation for `Value` is JSON value.
+// variants. Absence of any variant is an invalid state.
 message Value {
   // The kind of value.
   oneof kind {
-    // Represents a null value.
+    // Represents a JSON `null`.
     NullValue null_value = 1;
-    // Represents a double value.
+
+    // Represents a JSON number. Must not be `NaN`, `Infinity` or
+    // `-Infinity`, since those are not supported in JSON. This also cannot
+    // represent large Int64 values, since JSON format generally does not
+    // support them in its number type.
     double number_value = 2;
-    // Represents a string value.
+
+    // Represents a JSON string.
     string string_value = 3;
-    // Represents a boolean value.
+
+    // Represents a JSON boolean (`true` or `false` literal in JSON).
     bool bool_value = 4;
-    // Represents a structured value.
+
+    // Represents a JSON object.
     Struct struct_value = 5;
-    // Represents a repeated `Value`.
+
+    // Represents a JSON array.
     ListValue list_value = 6;
@@ -82,6 +95,11 @@ }
 
-// `NullValue` is a singleton enumeration to represent the null value for the
-// `Value` type union.
+// Represents a JSON `null`.
 //
-// The JSON representation for `NullValue` is JSON `null`.
+// `NullValue` is a sentinel, using an enum with only one value to represent
+// the null value for the `Value` type union.
+//
+// A field of type `NullValue` with any value other than `0` is considered
+// invalid. Most ProtoJSON serializers will emit a Value with a `null_value` set
+// as a JSON `null` regardless of the integer value, and so will round trip to
+// a `0` value.
 enum NullValue {
@@ -92,5 +110,3 @@ // Null value.
 
-// `ListValue` is a wrapper around a repeated field of values.
-//
-// The JSON representation for `ListValue` is JSON array.
+// Represents a JSON array.
 message ListValue {
@@ -97,0 +113,0 @@ // Repeated field of dynamically typed values.

No alert changes

No metric changes