Update Java gencode base class documentation to clarify that it is not supported to extend them.

protobuf-github-bot · copybara-github · commit c3177fb1e26f · 2025-06-23T14:06:44.000-07:00
This was already the intended state, but our javadoc didn't say it clearly.

PiperOrigin-RevId: 774919403
diff --git a/java/core/src/main/java/com/google/protobuf/AbstractMessage.java b/java/core/src/main/java/com/google/protobuf/AbstractMessage.java
@@ -24,6 +24,13 @@
  * A partial implementation of the {@link Message} interface which implements as many methods of
  * that interface as possible in terms of other methods.
  *
+ * <p>Users should generally ignore this class and use the Message interface instead.
+ *
+ * <p>This class is intended to only be extended by protoc created gencode. It is not intended or
+ * supported to extend this class, and any protected methods may be removed without it being
+ * considered a breaking change as long as all supported gencode does not depend on the changed
+ * methods.
+ *
  * @author kenton@google.com Kenton Varda
  */
 public abstract class AbstractMessage
diff --git a/java/core/src/main/java/com/google/protobuf/AbstractMessageLite.java b/java/core/src/main/java/com/google/protobuf/AbstractMessageLite.java
@@ -22,6 +22,13 @@
  * A partial implementation of the {@link MessageLite} interface which implements as many methods of
  * that interface as possible in terms of other methods.
  *
+ * <p>Users should generally ignore this class and use the MessageLite interface instead.
+ *
+ * <p>This class is intended to only be extended by protoc created gencode. It is not intended or
+ * supported to extend this class, and any protected methods may be removed without it being
+ * considered a breaking change as long as all supported gencode does not depend on the changed
+ * methods.
+ *
  * @author kenton@google.com Kenton Varda
  */
 public abstract class AbstractMessageLite<
diff --git a/java/core/src/main/java/com/google/protobuf/GeneratedMessage.java b/java/core/src/main/java/com/google/protobuf/GeneratedMessage.java
@@ -38,8 +38,14 @@
 
 /**
  * All generated protocol message classes extend this class. This class implements most of the
- * Message and Builder interfaces using Java reflection. Users can ignore this class and pretend
- * that generated messages implement the Message interface directly.
+ * Message and Builder interfaces using Java reflection.
+ *
+ * <p>Users should generally ignore this class and use the Message interface instead.
+ *
+ * <p>This class is intended to only be extended by protoc created gencode. It is not intended or
+ * supported to extend this class, and any protected methods may be removed without it being
+ * considered a breaking change as long as all supported gencode does not depend on the changed
+ * methods.
  *
  * @author kenton@google.com Kenton Varda
  */
diff --git a/java/core/src/main/java/com/google/protobuf/GeneratedMessageLite.java b/java/core/src/main/java/com/google/protobuf/GeneratedMessageLite.java
@@ -31,6 +31,13 @@
 /**
  * Lite version of {@link GeneratedMessage}.
  *
+ * <p>Users should generally ignore this class and use the MessageLite interface instead.
+ *
+ * <p>This class is intended to only be extended by protoc created gencode. It is not intended or
+ * supported to extend this class, and any protected methods may be removed without it being
+ * considered a breaking change as long as all supported gencode does not depend on the changed
+ * methods.
+ *
  * @author kenton@google.com Kenton Varda
  */
 public abstract class GeneratedMessageLite<
diff --git a/java/core/src/main/java/com/google/protobuf/Message.java b/java/core/src/main/java/com/google/protobuf/Message.java
@@ -14,6 +14,9 @@
 /**
  * Abstract interface implemented by Protocol Message objects.
  *
+ * <p>This interface is intended to only be implemented by protoc created gencode. It is not
+ * intended or supported to implement this interface manually.
+ *
  * <p>See also {@link MessageLite}, which defines most of the methods that typical users care about.
  * {@link Message} adds methods that are not available in the "lite" runtime. The biggest added
  * features are introspection and reflection; that is, getting descriptors for the message type and
diff --git a/java/core/src/main/java/com/google/protobuf/MessageLite.java b/java/core/src/main/java/com/google/protobuf/MessageLite.java
@@ -14,6 +14,9 @@
 /**
  * Abstract interface implemented by Protocol Message objects.
  *
+ * <p>This interface is intended to only be implemented by protoc created gencode. It is not
+ * intended or supported to implement this interface manually.
+ *
  * <p>This interface is implemented by all protocol message objects. Non-lite messages additionally
  * implement the Message interface, which is a subclass of MessageLite. Use MessageLite instead when
  * you only need the subset of features which it supports -- namely, nothing that uses descriptors
diff --git a/java/core/src/main/java/com/google/protobuf/MessageLiteOrBuilder.java b/java/core/src/main/java/com/google/protobuf/MessageLiteOrBuilder.java
@@ -11,6 +11,9 @@
  * Base interface for methods common to {@link MessageLite} and {@link MessageLite.Builder} to
  * provide type equivalency.
  *
+ * <p>This interface is intended to only be implemented by protoc created gencode. It is not
+ * intended or supported to implement this interface manually.
+ *
  * @author jonp@google.com (Jon Perlow)
  */
 @CheckReturnValue
diff --git a/java/core/src/main/java/com/google/protobuf/MessageOrBuilder.java b/java/core/src/main/java/com/google/protobuf/MessageOrBuilder.java
@@ -14,6 +14,9 @@
  * Base interface for methods common to {@link Message} and {@link Message.Builder} to provide type
  * equivalency.
  *
+ * <p>This interface is intended to only be implemented by protoc created gencode. It is not
+ * intended or supported to implement this interface manually.
+ *
  * @author jonp@google.com (Jon Perlow)
  */
 @CheckReturnValue
