This is an automated email from the ASF dual-hosted git repository.
lhotari pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/pulsar.git
The following commit(s) were added to refs/heads/master by this push:
new f3608074f53 [improve][broker] Add javadoc for PulsarDecoder handle*
method parameter lifecycle (#18998)
f3608074f53 is described below
commit f3608074f537471545926a84df8a1d061b30692c
Author: Lari Hotari <[email protected]>
AuthorDate: Tue Dec 20 20:18:38 2022 +0200
[improve][broker] Add javadoc for PulsarDecoder handle* method parameter
lifecycle (#18998)
---
.../src/main/java/org/apache/pulsar/broker/service/ServerCnx.java | 6 ++++++
.../src/main/java/org/apache/pulsar/client/impl/ClientCnx.java | 6 ++++++
.../main/java/org/apache/pulsar/common/protocol/PulsarDecoder.java | 6 ++++++
.../main/java/org/apache/pulsar/common/protocol/PulsarHandler.java | 3 +++
.../main/java/org/apache/pulsar/proxy/server/ProxyClientCnx.java | 6 ++++++
.../main/java/org/apache/pulsar/proxy/server/ProxyConnection.java | 4 +++-
6 files changed, 30 insertions(+), 1 deletion(-)
diff --git
a/pulsar-broker/src/main/java/org/apache/pulsar/broker/service/ServerCnx.java
b/pulsar-broker/src/main/java/org/apache/pulsar/broker/service/ServerCnx.java
index af7488bd652..88e51341a8c 100644
---
a/pulsar-broker/src/main/java/org/apache/pulsar/broker/service/ServerCnx.java
+++
b/pulsar-broker/src/main/java/org/apache/pulsar/broker/service/ServerCnx.java
@@ -169,6 +169,12 @@ import
org.apache.pulsar.transaction.coordinator.impl.MLTransactionMetadataStore
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
+/**
+ * Channel handler for the Pulsar broker.
+ * <p>
+ * Please see {@link org.apache.pulsar.common.protocol.PulsarDecoder} javadoc
for important details about handle* method
+ * parameter instance lifecycle.
+ */
public class ServerCnx extends PulsarHandler implements TransportCnx {
private final BrokerService service;
private final SchemaRegistryService schemaService;
diff --git
a/pulsar-client/src/main/java/org/apache/pulsar/client/impl/ClientCnx.java
b/pulsar-client/src/main/java/org/apache/pulsar/client/impl/ClientCnx.java
index 8b46aec2e0c..f2ebb12f957 100644
--- a/pulsar-client/src/main/java/org/apache/pulsar/client/impl/ClientCnx.java
+++ b/pulsar-client/src/main/java/org/apache/pulsar/client/impl/ClientCnx.java
@@ -103,6 +103,12 @@ import
org.apache.pulsar.common.util.collections.ConcurrentLongHashMap;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
+/**
+ * Channel handler for the Pulsar client.
+ * <p>
+ * Please see {@link org.apache.pulsar.common.protocol.PulsarDecoder} javadoc
for important details about handle* method
+ * parameter instance lifecycle.
+ */
@SuppressWarnings("unchecked")
public class ClientCnx extends PulsarHandler {
diff --git
a/pulsar-common/src/main/java/org/apache/pulsar/common/protocol/PulsarDecoder.java
b/pulsar-common/src/main/java/org/apache/pulsar/common/protocol/PulsarDecoder.java
index 15952ea8598..72212fe16c7 100644
---
a/pulsar-common/src/main/java/org/apache/pulsar/common/protocol/PulsarDecoder.java
+++
b/pulsar-common/src/main/java/org/apache/pulsar/common/protocol/PulsarDecoder.java
@@ -89,6 +89,12 @@ import org.slf4j.LoggerFactory;
/**
* Basic implementation of the channel handler to process inbound Pulsar data.
+ * <p>
+ * Please be aware that the decoded protocol command instance passed to a
handle* method is cleared and reused for the
+ * next protocol command after the method completes. This is done in order to
minimize object allocations for
+ * performance reasons. <b>It is not allowed to retain a reference to the
handle* method parameter command instance
+ * after the method returns.</b> If you need to pass an instance of the
command instance to another thread or retain a
+ * reference to it after the handle* method completes, you must make a deep
copy of the command instance.
*/
public abstract class PulsarDecoder extends ChannelInboundHandlerAdapter {
diff --git
a/pulsar-common/src/main/java/org/apache/pulsar/common/protocol/PulsarHandler.java
b/pulsar-common/src/main/java/org/apache/pulsar/common/protocol/PulsarHandler.java
index e116a5844e0..7a783d89c3f 100644
---
a/pulsar-common/src/main/java/org/apache/pulsar/common/protocol/PulsarHandler.java
+++
b/pulsar-common/src/main/java/org/apache/pulsar/common/protocol/PulsarHandler.java
@@ -31,6 +31,9 @@ import org.slf4j.LoggerFactory;
/**
* Implementation of the channel handler to process inbound Pulsar data.
+ * <p>
+ * Please see {@link org.apache.pulsar.common.protocol.PulsarDecoder} javadoc
for important details about handle* method
+ * parameter instance lifecycle.
*/
public abstract class PulsarHandler extends PulsarDecoder {
protected ChannelHandlerContext ctx;
diff --git
a/pulsar-proxy/src/main/java/org/apache/pulsar/proxy/server/ProxyClientCnx.java
b/pulsar-proxy/src/main/java/org/apache/pulsar/proxy/server/ProxyClientCnx.java
index 6f41af62342..6985e1f96e0 100644
---
a/pulsar-proxy/src/main/java/org/apache/pulsar/proxy/server/ProxyClientCnx.java
+++
b/pulsar-proxy/src/main/java/org/apache/pulsar/proxy/server/ProxyClientCnx.java
@@ -31,6 +31,12 @@ import
org.apache.pulsar.common.api.proto.CommandAuthChallenge;
import org.apache.pulsar.common.protocol.Commands;
@Slf4j
+/**
+ * Channel handler for Pulsar proxy's Pulsar broker client connections.
+ * <p>
+ * Please see {@link org.apache.pulsar.common.protocol.PulsarDecoder} javadoc
for important details about handle*
+ * method parameter instance lifecycle.
+ */
public class ProxyClientCnx extends ClientCnx {
private final boolean forwardClientAuthData;
private final String clientAuthMethod;
diff --git
a/pulsar-proxy/src/main/java/org/apache/pulsar/proxy/server/ProxyConnection.java
b/pulsar-proxy/src/main/java/org/apache/pulsar/proxy/server/ProxyConnection.java
index 531f9f67eb4..56fbe946069 100644
---
a/pulsar-proxy/src/main/java/org/apache/pulsar/proxy/server/ProxyConnection.java
+++
b/pulsar-proxy/src/main/java/org/apache/pulsar/proxy/server/ProxyConnection.java
@@ -77,7 +77,9 @@ import org.slf4j.LoggerFactory;
/**
* Handles incoming discovery request from client and sends appropriate
response back to client.
- *
+ * <p>
+ * Please see {@link org.apache.pulsar.common.protocol.PulsarDecoder} javadoc
for important details about handle* method
+ * parameter instance lifecycle.
*/
public class ProxyConnection extends PulsarHandler {
private static final Logger LOG =
LoggerFactory.getLogger(ProxyConnection.class);
