You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@pulsar.apache.org by hj...@apache.org on 2019/12/27 15:11:33 UTC
[pulsar] branch master updated: Fix Javadoc comments in the
pulsar-io-core module (#5884)
This is an automated email from the ASF dual-hosted git repository.
hjf 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 6d6fcca Fix Javadoc comments in the pulsar-io-core module (#5884)
6d6fcca is described below
commit 6d6fcca6da440492529389cff20c7017c53e6b53
Author: Sergii Zhevzhyk <vz...@users.noreply.github.com>
AuthorDate: Fri Dec 27 16:11:23 2019 +0100
Fix Javadoc comments in the pulsar-io-core module (#5884)
---
.../java/org/apache/pulsar/io/core/KeyValue.java | 2 +-
.../java/org/apache/pulsar/io/core/PushSource.java | 11 ++++----
.../main/java/org/apache/pulsar/io/core/Sink.java | 10 +++----
.../org/apache/pulsar/io/core/SinkContext.java | 4 +++
.../java/org/apache/pulsar/io/core/Source.java | 5 ++--
.../org/apache/pulsar/io/core/SourceContext.java | 33 ++++++++++++++--------
.../pulsar/io/core/annotations/FieldDoc.java | 3 +-
7 files changed, 43 insertions(+), 25 deletions(-)
diff --git a/pulsar-io/core/src/main/java/org/apache/pulsar/io/core/KeyValue.java b/pulsar-io/core/src/main/java/org/apache/pulsar/io/core/KeyValue.java
index ed34f04..e1eae68 100644
--- a/pulsar-io/core/src/main/java/org/apache/pulsar/io/core/KeyValue.java
+++ b/pulsar-io/core/src/main/java/org/apache/pulsar/io/core/KeyValue.java
@@ -19,7 +19,7 @@
package org.apache.pulsar.io.core;
/**
- * A simple KeyValue class
+ * A simple KeyValue class.
*/
public class KeyValue<K, V> {
private K key;
diff --git a/pulsar-io/core/src/main/java/org/apache/pulsar/io/core/PushSource.java b/pulsar-io/core/src/main/java/org/apache/pulsar/io/core/PushSource.java
index eb206ab..421e9f5 100644
--- a/pulsar-io/core/src/main/java/org/apache/pulsar/io/core/PushSource.java
+++ b/pulsar-io/core/src/main/java/org/apache/pulsar/io/core/PushSource.java
@@ -25,13 +25,13 @@ import org.apache.pulsar.functions.api.Record;
/**
* Pulsar's Push Source interface. PushSource read data from
- * external sources(database changes, twitter firehose, etc)
+ * external sources (database changes, twitter firehose, etc)
* and publish to a Pulsar topic. The reason its called Push is
* because PushSources get passed a consumer that they
* invoke whenever they have data to be published to Pulsar.
* The lifecycle of a PushSource is to open it passing any config needed
* by it to initialize(like open network connection, authenticate, etc).
- * A consumer is then to it which is invoked by the source whenever
+ * A consumer is then to it which is invoked by the source whenever
* there is data to be published. Once all data has been read, one can use close
* at the end of the session to do any cleanup
*/
@@ -50,10 +50,10 @@ public abstract class PushSource<T> implements Source<T> {
}
/**
- * Open connector with configuration
+ * Open connector with configuration.
*
* @param config initialization config
- * @param sourceContext
+ * @param sourceContext environment where the source connector is running
* @throws Exception IO type exceptions when opening a connector
*/
abstract public void open(Map<String, Object> config, SourceContext sourceContext) throws Exception;
@@ -61,7 +61,8 @@ public abstract class PushSource<T> implements Source<T> {
/**
* Attach a consumer function to this Source. This is invoked by the implementation
* to pass messages whenever there is data to be pushed to Pulsar.
- * @param consumer
+ *
+ * @param record next message from source which should be sent to a Pulsar topic
*/
public void consume(Record<T> record) {
try {
diff --git a/pulsar-io/core/src/main/java/org/apache/pulsar/io/core/Sink.java b/pulsar-io/core/src/main/java/org/apache/pulsar/io/core/Sink.java
index 16ed3c4..ed73e3a 100644
--- a/pulsar-io/core/src/main/java/org/apache/pulsar/io/core/Sink.java
+++ b/pulsar-io/core/src/main/java/org/apache/pulsar/io/core/Sink.java
@@ -23,21 +23,21 @@ import java.util.Map;
import org.apache.pulsar.functions.api.Record;
/**
- * Generic sink interface users can implement to run Sink on top of Pulsar Functions
+ * Generic sink interface users can implement to run Sink on top of Pulsar Functions.
*/
public interface Sink<T> extends AutoCloseable {
/**
- * Open connector with configuration
+ * Open connector with configuration.
*
* @param config initialization config
- * @param sinkContext
+ * @param sinkContext environment where the sink connector is running
* @throws Exception IO type exceptions when opening a connector
*/
void open(final Map<String, Object> config, SinkContext sinkContext) throws Exception;
/**
- * Write a message to Sink
- * @param inputRecordContext Context of input record from the source
+ * Write a message to Sink.
+ *
* @param record record to write to sink
* @throws Exception
*/
diff --git a/pulsar-io/core/src/main/java/org/apache/pulsar/io/core/SinkContext.java b/pulsar-io/core/src/main/java/org/apache/pulsar/io/core/SinkContext.java
index 1a8a859..f7e3b4d 100644
--- a/pulsar-io/core/src/main/java/org/apache/pulsar/io/core/SinkContext.java
+++ b/pulsar-io/core/src/main/java/org/apache/pulsar/io/core/SinkContext.java
@@ -24,6 +24,10 @@ import java.nio.ByteBuffer;
import java.util.Collection;
import java.util.concurrent.CompletableFuture;
+/**
+ * Interface for a sink connector providing information about environment where it is running.
+ * It also allows to propagate information, such as logs, metrics, states, back to the Pulsar environment.
+ */
public interface SinkContext {
/**
diff --git a/pulsar-io/core/src/main/java/org/apache/pulsar/io/core/Source.java b/pulsar-io/core/src/main/java/org/apache/pulsar/io/core/Source.java
index a343844..24502c3 100644
--- a/pulsar-io/core/src/main/java/org/apache/pulsar/io/core/Source.java
+++ b/pulsar-io/core/src/main/java/org/apache/pulsar/io/core/Source.java
@@ -23,11 +23,12 @@ import java.util.Map;
import org.apache.pulsar.functions.api.Record;
public interface Source<T> extends AutoCloseable {
+
/**
- * Open connector with configuration
+ * Open connector with configuration.
*
* @param config initialization config
- * @param sourceContext
+ * @param sourceContext environment where the source connector is running
* @throws Exception IO type exceptions when opening a connector
*/
void open(final Map<String, Object> config, SourceContext sourceContext) throws Exception;
diff --git a/pulsar-io/core/src/main/java/org/apache/pulsar/io/core/SourceContext.java b/pulsar-io/core/src/main/java/org/apache/pulsar/io/core/SourceContext.java
index a27d05f..e87a4bc 100644
--- a/pulsar-io/core/src/main/java/org/apache/pulsar/io/core/SourceContext.java
+++ b/pulsar-io/core/src/main/java/org/apache/pulsar/io/core/SourceContext.java
@@ -23,6 +23,10 @@ import org.slf4j.Logger;
import java.nio.ByteBuffer;
import java.util.concurrent.CompletableFuture;
+/**
+ * Interface for a source connector providing information about environment where it is running.
+ * It also allows to propagate information, such as logs, metrics, states, back to the Pulsar environment.
+ */
public interface SourceContext {
/**
@@ -40,44 +44,51 @@ public interface SourceContext {
int getNumInstances();
/**
- * Record a user defined metric
+ * Record a user defined metric.
+ *
* @param metricName The name of the metric
* @param value The value of the metric
*/
void recordMetric(String metricName, double value);
/**
- * Get the output topic of the source
+ * Get the output topic of the source.
+ *
* @return output topic name
*/
String getOutputTopic();
/**
- * The tenant this source belongs to
+ * The tenant this source belongs to.
+ *
* @return the tenant this source belongs to
*/
String getTenant();
/**
- * The namespace this source belongs to
+ * The namespace this source belongs to.
+ *
* @return the namespace this source belongs to
*/
String getNamespace();
/**
- * The name of the source that we are executing
+ * The name of the source that we are executing.
+ *
* @return The Source name
*/
String getSourceName();
/**
- * The logger object that can be used to log in a source
+ * The logger object that can be used to log in a source.
+ *
* @return the logger object
*/
Logger getLogger();
/**
- * Get the secret associated with this key
+ * Get the secret associated with this key.
+ *
* @param secretName The name of the secret
* @return The secret if anything was found or null
*/
@@ -94,7 +105,7 @@ public interface SourceContext {
/**
* Increment the builtin distributed counter referred by key
- * but dont wait for the completion of the increment operation
+ * but don't wait for the completion of the increment operation.
*
* @param key The name of the key
* @param amount The amount to be incremented
@@ -111,7 +122,7 @@ public interface SourceContext {
/**
* Retrieve the counter value for the key, but don't wait
- * for the operation to be completed
+ * for the operation to be completed.
*
* @param key name of the key
* @return the amount of the counter value for this key
@@ -127,7 +138,7 @@ public interface SourceContext {
void putState(String key, ByteBuffer value);
/**
- * Update the state value for the key, but don't wait for the operation to be completed
+ * Update the state value for the key, but don't wait for the operation to be completed.
*
* @param key name of the key
* @param value state value of the key
@@ -143,7 +154,7 @@ public interface SourceContext {
ByteBuffer getState(String key);
/**
- * Retrieve the state value for the key, but don't wait for the operation to be completed
+ * Retrieve the state value for the key, but don't wait for the operation to be completed.
*
* @param key name of the key
* @return the state value for the key.
diff --git a/pulsar-io/core/src/main/java/org/apache/pulsar/io/core/annotations/FieldDoc.java b/pulsar-io/core/src/main/java/org/apache/pulsar/io/core/annotations/FieldDoc.java
index beda53d..57cd742 100644
--- a/pulsar-io/core/src/main/java/org/apache/pulsar/io/core/annotations/FieldDoc.java
+++ b/pulsar-io/core/src/main/java/org/apache/pulsar/io/core/annotations/FieldDoc.java
@@ -46,7 +46,8 @@ public @interface FieldDoc {
/**
* Return if the field is a sensitive type or not.
- * usernames/password/accesstokensm etc are some example of sensitive fields
+ * User name, password, access token are some examples of sensitive fields.
+ *
* @return true if the field is sensitive, otherwise false
*/
boolean sensitive() default false;