You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@samza.apache.org by pm...@apache.org on 2018/10/31 20:36:58 UTC
samza git commit: Javadoc cleanup for new Application, Descriptor,
Context and Table APIs - Part 2
Repository: samza
Updated Branches:
refs/heads/master d16861831 -> 9f60e96b1
Javadoc cleanup for new Application, Descriptor, Context and Table APIs - Part 2
Currently, we don't allow imports for use only in javadocs. This requires using FQNs in link tags, which is not very readable. Checkstyle's UnusedImport rule has an option to allow imports for use in javadoc comments (processJavadocs=true, should be read as "check javadocs for import usage == true").
AFAICT, there's no good way to change the check's properties within a submodule. This PR adds both versions (strict and relaxed) to the checkstyle, and disables the strict validation for samza-api only.
This PR also updates the javadocs to use the class names with imports.
Author: Prateek Maheshwari <pm...@apache.org>
Reviewers: Cameron Lee <ca...@linkedin.com>
Closes #760 from prateekm/javadoc-cleanup
Project: http://git-wip-us.apache.org/repos/asf/samza/repo
Commit: http://git-wip-us.apache.org/repos/asf/samza/commit/9f60e96b
Tree: http://git-wip-us.apache.org/repos/asf/samza/tree/9f60e96b
Diff: http://git-wip-us.apache.org/repos/asf/samza/diff/9f60e96b
Branch: refs/heads/master
Commit: 9f60e96b1628fe395f771aaccaba077fdce3558e
Parents: d168618
Author: Prateek Maheshwari <pm...@apache.org>
Authored: Wed Oct 31 13:36:54 2018 -0700
Committer: Prateek Maheshwari <pm...@apache.org>
Committed: Wed Oct 31 13:36:54 2018 -0700
----------------------------------------------------------------------
checkstyle/checkstyle-suppressions.xml | 13 ++--
checkstyle/checkstyle.xml | 9 ++-
.../samza/application/SamzaApplication.java | 25 ++++----
.../samza/application/StreamApplication.java | 52 +++++++++-------
.../samza/application/TaskApplication.java | 27 +++++----
.../descriptors/ApplicationDescriptor.java | 63 +++++++++++---------
.../StreamApplicationDescriptor.java | 13 ++--
.../descriptors/TaskApplicationDescriptor.java | 22 ++++---
.../context/ApplicationContainerContext.java | 28 +++++----
.../ApplicationContainerContextFactory.java | 12 ++--
.../samza/context/ApplicationTaskContext.java | 19 +++---
.../context/ApplicationTaskContextFactory.java | 12 ++--
.../apache/samza/context/ContainerContext.java | 4 +-
.../java/org/apache/samza/context/Context.java | 10 ++--
.../org/apache/samza/context/TaskContext.java | 11 ++--
.../system/descriptors/StreamExpander.java | 7 ++-
.../TransformingInputDescriptorProvider.java | 10 ++--
.../main/java/org/apache/samza/table/Table.java | 36 +++++------
.../table/descriptors/TableDescriptor.java | 28 +++++----
19 files changed, 222 insertions(+), 179 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/samza/blob/9f60e96b/checkstyle/checkstyle-suppressions.xml
----------------------------------------------------------------------
diff --git a/checkstyle/checkstyle-suppressions.xml b/checkstyle/checkstyle-suppressions.xml
index d227929..5109c7e 100644
--- a/checkstyle/checkstyle-suppressions.xml
+++ b/checkstyle/checkstyle-suppressions.xml
@@ -1,8 +1,8 @@
<?xml version="1.0"?>
<!DOCTYPE suppressions PUBLIC
- "-//Puppy Crawl//DTD Suppressions 1.0//EN"
- "http://www.puppycrawl.com/dtds/suppressions_1_0.dtd">
+ "-//Checkstyle//DTD SuppressionFilter Configuration 1.2//EN"
+ "https://checkstyle.org/dtds/suppressions_1_2.dtd">
<!--
// Licensed to the Apache Software Foundation (ASF) under one or more
@@ -22,15 +22,10 @@
-->
<suppressions>
-<!-- example
- <suppress checks="Indentation"
- files="TestZkProcessorLatch.java"
- lines="91-275"/>
- -->
<suppress checks="ConstantName"
files="ApplicationStatus.java"
lines="26-29"/>
- <suppress checks="UnusedImports"
- files="StreamApplication.java"/>
+ <suppress id="preventJavadocUnusedImports"
+ files=".*samza-api.*"/>
</suppressions>
http://git-wip-us.apache.org/repos/asf/samza/blob/9f60e96b/checkstyle/checkstyle.xml
----------------------------------------------------------------------
diff --git a/checkstyle/checkstyle.xml b/checkstyle/checkstyle.xml
index 479896e..e6d789c 100644
--- a/checkstyle/checkstyle.xml
+++ b/checkstyle/checkstyle.xml
@@ -34,7 +34,14 @@
<module name="TreeWalker">
<!-- code cleanup -->
- <module name="UnusedImports"/>
+ <module name="UnusedImports">
+ <property name="id" value="allowJavadocUnusedImports"/>
+ <property name="processJavadoc" value="true"/>
+ </module>
+ <module name="UnusedImports"> <!-- suppressed for samza-api -->
+ <property name="id" value="preventJavadocUnusedImports"/>
+ <property name="processJavadoc" value="false"/>
+ </module>
<module name="FileContentsHolder"/>
<module name="RedundantImport"/>
<module name="IllegalImport" />
http://git-wip-us.apache.org/repos/asf/samza/blob/9f60e96b/samza-api/src/main/java/org/apache/samza/application/SamzaApplication.java
----------------------------------------------------------------------
diff --git a/samza-api/src/main/java/org/apache/samza/application/SamzaApplication.java b/samza-api/src/main/java/org/apache/samza/application/SamzaApplication.java
index 849b2b3..a70c1de 100644
--- a/samza-api/src/main/java/org/apache/samza/application/SamzaApplication.java
+++ b/samza-api/src/main/java/org/apache/samza/application/SamzaApplication.java
@@ -20,24 +20,25 @@ package org.apache.samza.application;
import org.apache.samza.annotation.InterfaceStability;
import org.apache.samza.application.descriptors.ApplicationDescriptor;
+import org.apache.samza.context.ApplicationContainerContext;
+import org.apache.samza.context.ApplicationTaskContext;
+import org.apache.samza.operators.MessageStream;
/**
- * A {@link SamzaApplication} describes the inputs, outputs, state, configuration and the logic
- * for processing data from one or more streaming sources.
+ * A {@link SamzaApplication} describes the inputs, outputs, state, configuration and the logic for processing data from
+ * one or more streaming sources.
* <p>
- * This is the base {@link SamzaApplication}. Implement a {@link StreamApplication} to describe the
- * processing logic using Samza's High Level API in terms of {@link org.apache.samza.operators.MessageStream}
- * operators, or a {@link TaskApplication} to describe it using Samza's Low Level API in terms of per-message
- * processing logic.
+ * This is the base {@link SamzaApplication}. Implement a {@link StreamApplication} to describe the processing logic
+ * using Samza's High Level API in terms of {@link MessageStream} operators, or a {@link TaskApplication} to describe it
+ * using Samza's Low Level API in terms of per-message processing logic.
* <p>
- * A {@link SamzaApplication} implementation must have a no-argument constructor, which will be used by the framework
- * to create new instances and call {@link #describe(ApplicationDescriptor)}.
+ * A {@link SamzaApplication} implementation must have a no-argument constructor, which will be used by the framework to
+ * create new instances and call {@link SamzaApplication#describe(ApplicationDescriptor)}.
* <p>
- * Per container context may be managed using {@link org.apache.samza.context.ApplicationContainerContext} and
- * set using {@link ApplicationDescriptor#withApplicationContainerContextFactory}. Similarly, per task context
- * may be managed using {@link org.apache.samza.context.ApplicationTaskContext} and set using
- * {@link ApplicationDescriptor#withApplicationTaskContextFactory}.
+ * Per container context may be managed using {@link ApplicationContainerContext} and set using
+ * {@link ApplicationDescriptor#withApplicationContainerContextFactory}. Similarly, per task context may be managed
+ * using {@link ApplicationTaskContext} and set using {@link ApplicationDescriptor#withApplicationTaskContextFactory}.
*/
@InterfaceStability.Evolving
public interface SamzaApplication<S extends ApplicationDescriptor> {
http://git-wip-us.apache.org/repos/asf/samza/blob/9f60e96b/samza-api/src/main/java/org/apache/samza/application/StreamApplication.java
----------------------------------------------------------------------
diff --git a/samza-api/src/main/java/org/apache/samza/application/StreamApplication.java b/samza-api/src/main/java/org/apache/samza/application/StreamApplication.java
index 3749b58..f41a239 100644
--- a/samza-api/src/main/java/org/apache/samza/application/StreamApplication.java
+++ b/samza-api/src/main/java/org/apache/samza/application/StreamApplication.java
@@ -18,27 +18,35 @@
*/
package org.apache.samza.application;
+import java.io.Serializable;
import org.apache.samza.annotation.InterfaceStability;
import org.apache.samza.application.descriptors.StreamApplicationDescriptor;
+import org.apache.samza.operators.MessageStream;
+import org.apache.samza.operators.OutputStream;
+import org.apache.samza.operators.functions.ClosableFunction;
+import org.apache.samza.operators.functions.FilterFunction;
+import org.apache.samza.operators.functions.InitableFunction;
+import org.apache.samza.operators.functions.ScheduledFunction;
+import org.apache.samza.system.descriptors.InputDescriptor;
+import org.apache.samza.system.descriptors.OutputDescriptor;
+import org.apache.samza.system.descriptors.SystemDescriptor;
+import org.apache.samza.table.Table;
+import org.apache.samza.table.descriptors.TableDescriptor;
+import org.apache.samza.task.StreamTask;
/**
- * A {@link StreamApplication} describes the inputs, outputs, state, configuration and the processing logic
- * in Samza's High Level API.
+ * A {@link StreamApplication} describes the inputs, outputs, state, configuration and the processing logic for the
+ * application in Samza's High Level API.
* <p>
* A typical {@link StreamApplication} implementation consists of the following stages:
* <ol>
- * <li>Configuring the inputs, outputs and state (tables) using the appropriate
- * {@link org.apache.samza.system.descriptors.SystemDescriptor}s,
- * {@link org.apache.samza.system.descriptors.InputDescriptor}s,
- * {@link org.apache.samza.system.descriptors.OutputDescriptor}s and
- * {@link org.apache.samza.table.descriptors.TableDescriptor}s
- * <li>Obtaining the corresponding
- * {@link org.apache.samza.operators.MessageStream}s,
- * {@link org.apache.samza.operators.OutputStream}s and
- * {@link org.apache.samza.table.Table}s from the provided {@link StreamApplicationDescriptor}.
+ * <li>Configuring the inputs, outputs and state (tables) using the appropriate {@link SystemDescriptor}s,
+ * {@link InputDescriptor}s, {@link OutputDescriptor}s and {@link TableDescriptor}s
+ * <li>Obtaining the corresponding {@link MessageStream}s, {@link OutputStream}s and {@link Table}s from the
+ * provided {@link StreamApplicationDescriptor}.
* <li>Defining the processing logic using operators and functions on the streams and tables thus obtained.
- * E.g., {@link org.apache.samza.operators.MessageStream#filter(org.apache.samza.operators.functions.FilterFunction)}
+ * E.g., {@link MessageStream#filter(FilterFunction)}
* </ol>
* <p>
* The following example {@link StreamApplication} removes page views older than 1 hour from the input stream:
@@ -61,19 +69,17 @@ import org.apache.samza.application.descriptors.StreamApplicationDescriptor;
* }
* }</pre>
* <p>
- * All operator function implementations used in a {@link StreamApplication} must be {@link java.io.Serializable}. Any
- * context required within an operator function may be managed by implementing the
- * {@link org.apache.samza.operators.functions.InitableFunction#init} and
- * {@link org.apache.samza.operators.functions.ClosableFunction#close} methods in the function implementation.
+ * All operator function implementations used in a {@link StreamApplication} must be {@link Serializable}. Any
+ * context required within an operator function may be managed by implementing the {@link InitableFunction#init} and
+ * {@link ClosableFunction#close} methods in the function implementation.
* <p>
- * Functions may implement the {@link org.apache.samza.operators.functions.ScheduledFunction} interface
- * to schedule and receive periodic callbacks from the Samza framework.
+ * Functions may implement the {@link ScheduledFunction} interface to schedule and receive periodic callbacks from the
+ * Samza framework.
* <p>
- * Implementation Notes: Currently {@link StreamApplication}s are wrapped in a {@link org.apache.samza.task.StreamTask}
- * during execution. The execution planner will generate a serialized DAG which will be deserialized in each
- * {@link org.apache.samza.task.StreamTask} instance used for processing incoming messages. Execution is synchronous
- * and thread-safe within each {@link org.apache.samza.task.StreamTask}. Multiple tasks may process their
- * messages concurrently depending on the job parallelism configuration.
+ * Implementation Notes: Currently {@link StreamApplication}s are wrapped in a {@link StreamTask} during execution. The
+ * execution planner will generate a serialized DAG which will be deserialized in each {@link StreamTask} instance used
+ * for processing incoming messages. Execution is synchronous and thread-safe within each {@link StreamTask}. Multiple
+ * tasks may process their messages concurrently depending on the job parallelism configuration.
*/
@InterfaceStability.Evolving
public interface StreamApplication extends SamzaApplication<StreamApplicationDescriptor> {
http://git-wip-us.apache.org/repos/asf/samza/blob/9f60e96b/samza-api/src/main/java/org/apache/samza/application/TaskApplication.java
----------------------------------------------------------------------
diff --git a/samza-api/src/main/java/org/apache/samza/application/TaskApplication.java b/samza-api/src/main/java/org/apache/samza/application/TaskApplication.java
index 2f7088e..8d2bc08 100644
--- a/samza-api/src/main/java/org/apache/samza/application/TaskApplication.java
+++ b/samza-api/src/main/java/org/apache/samza/application/TaskApplication.java
@@ -18,26 +18,31 @@
*/
package org.apache.samza.application;
+import java.io.Serializable;
import org.apache.samza.annotation.InterfaceStability;
import org.apache.samza.application.descriptors.TaskApplicationDescriptor;
+import org.apache.samza.system.IncomingMessageEnvelope;
+import org.apache.samza.system.descriptors.StreamDescriptor;
+import org.apache.samza.system.descriptors.SystemDescriptor;
+import org.apache.samza.table.descriptors.TableDescriptor;
+import org.apache.samza.task.AsyncStreamTask;
+import org.apache.samza.task.StreamTask;
+import org.apache.samza.task.TaskFactory;
/**
- * A {@link TaskApplication} describes the inputs, outputs, state, configuration and the processing logic
- * in Samza's Low Level API.
+ * A {@link TaskApplication} describes the inputs, outputs, state, configuration and the processing logic for the
+ * application in Samza's Low Level API.
+ * <p>
* A typical {@link TaskApplication} implementation consists of the following stages:
* <ol>
* <li>Configuring the inputs, outputs and state (tables) using the appropriate
- * {@link org.apache.samza.system.descriptors.SystemDescriptor}s,
- * {@link org.apache.samza.system.descriptors.StreamDescriptor}s and
- * {@link org.apache.samza.table.descriptors.TableDescriptor}s
+ * {@link SystemDescriptor}s, {@link StreamDescriptor}s and {@link TableDescriptor}s
* <li>Adding these descriptors to the provided {@link TaskApplicationDescriptor}.
- * <li>Defining the processing logic by implementing a {@link org.apache.samza.task.StreamTask} or
- * {@link org.apache.samza.task.AsyncStreamTask} that operates on each
- * {@link org.apache.samza.system.IncomingMessageEnvelope} one at a time.
- * <li>Setting a {@link org.apache.samza.task.TaskFactory} using
- * {@link TaskApplicationDescriptor#withTaskFactory(org.apache.samza.task.TaskFactory)} that creates instances of the
- * task above. The {@link org.apache.samza.task.TaskFactory} implementation must be {@link java.io.Serializable}.
+ * <li>Defining the processing logic by implementing a {@link StreamTask} or {@link AsyncStreamTask} that operates
+ * on each {@link IncomingMessageEnvelope} one at a time.
+ * <li>Setting a {@link TaskFactory} using {@link TaskApplicationDescriptor#withTaskFactory} that creates
+ * instances of the task above. The {@link TaskFactory} implementation must be {@link Serializable}.
* </ol>
* <p>
* The following example {@link TaskApplication} removes page views older than 1 hour from the input stream:
http://git-wip-us.apache.org/repos/asf/samza/blob/9f60e96b/samza-api/src/main/java/org/apache/samza/application/descriptors/ApplicationDescriptor.java
----------------------------------------------------------------------
diff --git a/samza-api/src/main/java/org/apache/samza/application/descriptors/ApplicationDescriptor.java b/samza-api/src/main/java/org/apache/samza/application/descriptors/ApplicationDescriptor.java
index 6a4c9fd..2aaa5c9 100644
--- a/samza-api/src/main/java/org/apache/samza/application/descriptors/ApplicationDescriptor.java
+++ b/samza-api/src/main/java/org/apache/samza/application/descriptors/ApplicationDescriptor.java
@@ -18,37 +18,46 @@
*/
package org.apache.samza.application.descriptors;
+import java.io.Serializable;
import java.util.Map;
import org.apache.samza.annotation.InterfaceStability;
+import org.apache.samza.application.SamzaApplication;
+import org.apache.samza.application.StreamApplication;
+import org.apache.samza.application.TaskApplication;
import org.apache.samza.config.Config;
+import org.apache.samza.context.ApplicationContainerContext;
import org.apache.samza.context.ApplicationContainerContextFactory;
+import org.apache.samza.context.ApplicationTaskContext;
import org.apache.samza.context.ApplicationTaskContextFactory;
+import org.apache.samza.context.Context;
+import org.apache.samza.metrics.MetricsReporter;
import org.apache.samza.metrics.MetricsReporterFactory;
+import org.apache.samza.operators.MessageStream;
import org.apache.samza.runtime.ProcessorLifecycleListenerFactory;
import org.apache.samza.system.descriptors.SystemDescriptor;
/**
- * An {@link ApplicationDescriptor} contains the description of inputs, outputs, state, configuration and the
- * processing logic for a {@link org.apache.samza.application.SamzaApplication}.
+ * An {@link ApplicationDescriptor} contains the description of inputs, outputs, state, configuration and the processing
+ * logic for a {@link SamzaApplication}.
* <p>
- * This is the base {@link ApplicationDescriptor} and provides functionality common to all
- * {@link org.apache.samza.application.SamzaApplication}.
- * {@link org.apache.samza.application.StreamApplication#describe} will provide access to a
- * {@link StreamApplicationDescriptor} with additional functionality for describing High Level API applications.
- * Similarly, {@link org.apache.samza.application.TaskApplication#describe} will provide access to a
- * {@link TaskApplicationDescriptor} with additional functionality for describing Low Level API applications.
+ * This is the base {@link ApplicationDescriptor} and provides functionality common to all {@link SamzaApplication}.
+ * {@link StreamApplication#describe} will provide access to a {@link StreamApplicationDescriptor} with additional
+ * functionality for describing High Level API applications. Similarly, {@link TaskApplication#describe} will provide
+ * access to a {@link TaskApplicationDescriptor} with additional functionality for describing Low Level API
+ * applications.
* <p>
* Use the {@link ApplicationDescriptor} to set the container scope context factory using
* {@link ApplicationDescriptor#withApplicationContainerContextFactory}, and task scope context factory using
- * {@link ApplicationDescriptor#withApplicationTaskContextFactory}. Please note that the terms {@code container}
- * and {@code task} here refer to the units of physical and logical parallelism, not the programming API.
+ * {@link ApplicationDescriptor#withApplicationTaskContextFactory}. Please note that the terms {@code container} and
+ * {@code task} here refer to the units of physical and logical parallelism, not the programming API.
*/
@InterfaceStability.Evolving
public interface ApplicationDescriptor<S extends ApplicationDescriptor> {
/**
* Get the configuration for the application.
+ *
* @return config for the application
*/
Config getConfig();
@@ -57,11 +66,11 @@ public interface ApplicationDescriptor<S extends ApplicationDescriptor> {
* Sets the {@link SystemDescriptor} for the default system for the application.
* <p>
* The default system is used by the framework for creating any internal (e.g., coordinator, changelog, checkpoint)
- * streams. In an {@link org.apache.samza.application.StreamApplication}, it is also used for creating any
- * intermediate streams; e.g., those created by the {@link org.apache.samza.operators.MessageStream#partitionBy} and
- * {@link org.apache.samza.operators.MessageStream#broadcast} operators.
+ * streams. In an {@link StreamApplication}, it is also used for creating any intermediate streams; e.g., those
+ * created by the {@link MessageStream#partitionBy} and {@link MessageStream#broadcast} operators.
* <p>
- * If the default system descriptor is set, it must be set <b>before</b> creating any input/output/intermediate streams.
+ * If the default system descriptor is set, it must be set <b>before</b> creating any input/output/intermediate
+ * streams.
*
* @param defaultSystemDescriptor the {@link SystemDescriptor} for the default system for the application
* @return this {@link ApplicationDescriptor}
@@ -70,12 +79,12 @@ public interface ApplicationDescriptor<S extends ApplicationDescriptor> {
/**
* Sets the {@link ApplicationContainerContextFactory} for this application. Each task will be given access to a
- * different instance of the {@link org.apache.samza.context.ApplicationContainerContext} that this creates. The
- * context can be accessed through the {@link org.apache.samza.context.Context}.
+ * different instance of the {@link ApplicationContainerContext} that this creates. The context can be accessed
+ * through the {@link Context}.
* <p>
* Setting this is optional.
* <p>
- * The provided {@code factory} instance must be {@link java.io.Serializable}.
+ * The provided {@code factory} instance must be {@link Serializable}.
*
* @param factory the {@link ApplicationContainerContextFactory} for this application
* @return this {@link ApplicationDescriptor}
@@ -84,8 +93,8 @@ public interface ApplicationDescriptor<S extends ApplicationDescriptor> {
/**
* Sets the {@link ApplicationTaskContextFactory} for this application. Each task will be given access to a different
- * instance of the {@link org.apache.samza.context.ApplicationTaskContext} that this creates. The context can be
- * accessed through the {@link org.apache.samza.context.Context}.
+ * instance of the {@link ApplicationTaskContext} that this creates. The context can be accessed through the
+ * {@link Context}.
* <p>
* Setting this is optional.
* <p>
@@ -99,25 +108,25 @@ public interface ApplicationDescriptor<S extends ApplicationDescriptor> {
/**
* Sets the {@link ProcessorLifecycleListenerFactory} for this application.
* <p>
- * Setting a {@link ProcessorLifecycleListenerFactory} is optional to a user application. It allows users to
- * plug in optional code to be invoked in different stages before/after the main processing logic is started/stopped in
- * the application.
+ * Setting a {@link ProcessorLifecycleListenerFactory} is optional to a user application. It allows users to plug in
+ * optional code to be invoked in different stages before/after the main processing logic is started/stopped in the
+ * application.
* <p>
* The provided {@code factory} instance must be {@link java.io.Serializable}.
*
- * @param listenerFactory the user implemented {@link ProcessorLifecycleListenerFactory} that creates lifecycle listener
- * with callback methods before and after the start/stop of each StreamProcessor in the application
+ * @param listenerFactory the user implemented {@link ProcessorLifecycleListenerFactory} that creates lifecycle
+ * listener with callback methods before and after the start/stop of each StreamProcessor in
+ * the application
* @return this {@link ApplicationDescriptor}
*/
S withProcessorLifecycleListenerFactory(ProcessorLifecycleListenerFactory listenerFactory);
/**
- * Sets the {@link org.apache.samza.metrics.MetricsReporterFactory}s for creating the
- * {@link org.apache.samza.metrics.MetricsReporter}s to use for the application.
+ * Sets the {@link MetricsReporterFactory}s for creating the {@link MetricsReporter}s to use for the application.
* <p>
* The provided {@link MetricsReporterFactory} instances must be {@link java.io.Serializable}.
*
- * @param reporterFactories a map of {@link org.apache.samza.metrics.MetricsReporter} names to their factories.
+ * @param reporterFactories a map of {@link MetricsReporter} names to their factories.
* @return this {@link ApplicationDescriptor}
*/
S withMetricsReporterFactories(Map<String, MetricsReporterFactory> reporterFactories);
http://git-wip-us.apache.org/repos/asf/samza/blob/9f60e96b/samza-api/src/main/java/org/apache/samza/application/descriptors/StreamApplicationDescriptor.java
----------------------------------------------------------------------
diff --git a/samza-api/src/main/java/org/apache/samza/application/descriptors/StreamApplicationDescriptor.java b/samza-api/src/main/java/org/apache/samza/application/descriptors/StreamApplicationDescriptor.java
index 4a77c6c..8b9765e 100644
--- a/samza-api/src/main/java/org/apache/samza/application/descriptors/StreamApplicationDescriptor.java
+++ b/samza-api/src/main/java/org/apache/samza/application/descriptors/StreamApplicationDescriptor.java
@@ -19,6 +19,7 @@
package org.apache.samza.application.descriptors;
import org.apache.samza.annotation.InterfaceStability;
+import org.apache.samza.application.StreamApplication;
import org.apache.samza.system.descriptors.InputDescriptor;
import org.apache.samza.system.descriptors.OutputDescriptor;
import org.apache.samza.operators.KV;
@@ -30,15 +31,13 @@ import org.apache.samza.table.Table;
/**
* A {@link StreamApplicationDescriptor} contains the description of inputs, outputs, state, configuration and the
- * processing logic for a Samza High Level API {@link org.apache.samza.application.StreamApplication}.
+ * processing logic for a Samza High Level API {@link StreamApplication}.
* <p>
- * Use the {@link StreamApplicationDescriptor} obtained from
- * {@link org.apache.samza.application.StreamApplication#describe} to get the {@link MessageStream}s,
- * {@link OutputStream}s and {@link Table}s corresponding to their respective {@link InputDescriptor}s,
- * {@link OutputDescriptor}s and {@link TableDescriptor}s.
+ * Use the {@link StreamApplicationDescriptor} obtained from {@link StreamApplication#describe} to get the
+ * {@link MessageStream}s, {@link OutputStream}s and {@link Table}s corresponding to their respective
+ * {@link InputDescriptor}s, {@link OutputDescriptor}s and {@link TableDescriptor}s.
* <p>
- * Use the {@link MessageStream} API operators to describe the processing logic for the
- * {@link org.apache.samza.application.StreamApplication}.
+ * Use the {@link MessageStream} API operators to describe the processing logic for the {@link StreamApplication}.
*/
@InterfaceStability.Evolving
public interface StreamApplicationDescriptor extends ApplicationDescriptor<StreamApplicationDescriptor> {
http://git-wip-us.apache.org/repos/asf/samza/blob/9f60e96b/samza-api/src/main/java/org/apache/samza/application/descriptors/TaskApplicationDescriptor.java
----------------------------------------------------------------------
diff --git a/samza-api/src/main/java/org/apache/samza/application/descriptors/TaskApplicationDescriptor.java b/samza-api/src/main/java/org/apache/samza/application/descriptors/TaskApplicationDescriptor.java
index 384f5da..4921839 100644
--- a/samza-api/src/main/java/org/apache/samza/application/descriptors/TaskApplicationDescriptor.java
+++ b/samza-api/src/main/java/org/apache/samza/application/descriptors/TaskApplicationDescriptor.java
@@ -18,34 +18,38 @@
*/
package org.apache.samza.application.descriptors;
+import java.io.Serializable;
import org.apache.samza.annotation.InterfaceStability;
+import org.apache.samza.application.TaskApplication;
import org.apache.samza.system.descriptors.InputDescriptor;
import org.apache.samza.system.descriptors.OutputDescriptor;
import org.apache.samza.table.descriptors.TableDescriptor;
+import org.apache.samza.task.AsyncStreamTask;
+import org.apache.samza.task.AsyncStreamTaskFactory;
+import org.apache.samza.task.StreamTask;
+import org.apache.samza.task.StreamTaskFactory;
import org.apache.samza.task.TaskFactory;
/**
* A {@link TaskApplicationDescriptor} contains the description of inputs, outputs, state, configuration and the
- * processing logic for a Samza Low Level API {@link org.apache.samza.application.TaskApplication}.
+ * processing logic for a Samza Low Level API {@link TaskApplication}.
* <p>
- * Use the {@link TaskApplicationDescriptor} obtained from {@link org.apache.samza.application.TaskApplication#describe}
+ * Use the {@link TaskApplicationDescriptor} obtained from {@link TaskApplication#describe}
* to add the {@link InputDescriptor}s, {@link OutputDescriptor}s and {@link TableDescriptor}s for streams and
* tables to be used in the task implementation.
* <p>
- * Use {@link #withTaskFactory} to set the factory for the {@link org.apache.samza.task.StreamTask} or
- * {@link org.apache.samza.task.AsyncStreamTask} implementation that contains the processing logic for
- * the {@link org.apache.samza.application.TaskApplication}.
+ * Use {@link TaskApplicationDescriptor#withTaskFactory} to set the factory for the {@link StreamTask} or
+ * {@link AsyncStreamTask} implementation that contains the processing logic for the {@link TaskApplication}.
*/
@InterfaceStability.Evolving
public interface TaskApplicationDescriptor extends ApplicationDescriptor<TaskApplicationDescriptor> {
/**
- * Sets the {@link org.apache.samza.task.StreamTaskFactory} or {@link org.apache.samza.task.AsyncStreamTaskFactory}
- * for the {@link org.apache.samza.task.StreamTask} or {@link org.apache.samza.task.AsyncStreamTask} implementation
- * that contains the processing logic for the {@link org.apache.samza.application.TaskApplication}.
+ * Sets the {@link StreamTaskFactory} or {@link AsyncStreamTaskFactory} for the {@link StreamTask} or
+ * {@link AsyncStreamTask} implementation that contains the processing logic for the {@link TaskApplication}.
* <p>
- * The provided {@code taskFactory} instance must be serializable.
+ * The provided {@code taskFactory} instance must be {@link Serializable}.
*
* @param factory the {@link TaskFactory} for the Low Level API Task implementation
* @return this {@link TaskApplicationDescriptor}
http://git-wip-us.apache.org/repos/asf/samza/blob/9f60e96b/samza-api/src/main/java/org/apache/samza/context/ApplicationContainerContext.java
----------------------------------------------------------------------
diff --git a/samza-api/src/main/java/org/apache/samza/context/ApplicationContainerContext.java b/samza-api/src/main/java/org/apache/samza/context/ApplicationContainerContext.java
index 8ac34a5..7c5f755 100644
--- a/samza-api/src/main/java/org/apache/samza/context/ApplicationContainerContext.java
+++ b/samza-api/src/main/java/org/apache/samza/context/ApplicationContainerContext.java
@@ -19,26 +19,28 @@
package org.apache.samza.context;
+import java.io.Serializable;
+import org.apache.samza.application.descriptors.ApplicationDescriptor;
+
/**
- * An {@link ApplicationContainerContext} instance can be used for holding per-container runtime state and objects
- * and managing their lifecycle. This context is shared across all tasks in the container.
+ * An {@link ApplicationContainerContext} instance can be used for holding per-container runtime state and objects and
+ * managing their lifecycle. This context is shared across all tasks in the container.
* <p>
- * Use {@link org.apache.samza.application.descriptors.ApplicationDescriptor#withApplicationContainerContextFactory}
- * to provide the {@link ApplicationContainerContextFactory}. Use {@link Context#getApplicationContainerContext()} to
- * get the created {@link ApplicationContainerContext} instance for the current container.
+ * Use {@link ApplicationDescriptor#withApplicationContainerContextFactory} to provide the
+ * {@link ApplicationContainerContextFactory}. Use {@link Context#getApplicationContainerContext()} to get the created
+ * {@link ApplicationContainerContext} instance for the current container.
* <p>
- * A unique instance of {@link ApplicationContainerContext} is created in each container. If the
- * container moves or the container model changes (e.g. due to failure or re-balancing), a new instance is created.
+ * A unique instance of {@link ApplicationContainerContext} is created in each container. If the container moves or the
+ * container model changes (e.g. due to failure or re-balancing), a new instance is created.
* <p>
* Use the {@link ApplicationContainerContextFactory} to create any runtime state and objects, and the
- * {@link ApplicationContainerContext#start()} and {@link ApplicationContainerContext#stop()} methods to
- * manage their lifecycle.
+ * {@link ApplicationContainerContext#start()} and {@link ApplicationContainerContext#stop()} methods to manage their
+ * lifecycle.
* <p>
- * Use {@link ApplicationTaskContext} to hold unique runtime state and objects for each task within a container.
- * Use {@link ContainerContext} to access framework-provided context for a container.
+ * Use {@link ApplicationTaskContext} to hold unique runtime state and objects for each task within a container. Use
+ * {@link ContainerContext} to access framework-provided context for a container.
* <p>
- * Unlike its {@link ApplicationContainerContextFactory}, an implementation does not need to be
- * {@link java.io.Serializable}.
+ * Unlike its {@link ApplicationContainerContextFactory}, an implementation does not need to be {@link Serializable}.
*/
public interface ApplicationContainerContext {
/**
http://git-wip-us.apache.org/repos/asf/samza/blob/9f60e96b/samza-api/src/main/java/org/apache/samza/context/ApplicationContainerContextFactory.java
----------------------------------------------------------------------
diff --git a/samza-api/src/main/java/org/apache/samza/context/ApplicationContainerContextFactory.java b/samza-api/src/main/java/org/apache/samza/context/ApplicationContainerContextFactory.java
index a8c9f7c..7f2c6a4 100644
--- a/samza-api/src/main/java/org/apache/samza/context/ApplicationContainerContextFactory.java
+++ b/samza-api/src/main/java/org/apache/samza/context/ApplicationContainerContextFactory.java
@@ -19,15 +19,17 @@
package org.apache.samza.context;
import java.io.Serializable;
+import org.apache.samza.application.SamzaApplication;
+import org.apache.samza.application.descriptors.ApplicationDescriptor;
/**
- * The factory for creating {@link ApplicationContainerContext} instances for a
- * {@link org.apache.samza.application.SamzaApplication} during container initialization.
+ * The factory for creating {@link ApplicationContainerContext} instances for a {@link SamzaApplication} during
+ * container initialization.
* <p>
- * Use {@link org.apache.samza.application.descriptors.ApplicationDescriptor#withApplicationContainerContextFactory} to
- * provide the {@link ApplicationContainerContextFactory}. Use {@link Context#getApplicationContainerContext()} to
- * get the created {@link ApplicationContainerContext} instance for the current container.
+ * Use {@link ApplicationDescriptor#withApplicationContainerContextFactory} to provide the
+ * {@link ApplicationContainerContextFactory}. Use {@link Context#getApplicationContainerContext()} to get the created
+ * {@link ApplicationContainerContext} instance for the current container.
* <p>
* The {@link ApplicationContainerContextFactory} implementation must be {@link Serializable}.
*
http://git-wip-us.apache.org/repos/asf/samza/blob/9f60e96b/samza-api/src/main/java/org/apache/samza/context/ApplicationTaskContext.java
----------------------------------------------------------------------
diff --git a/samza-api/src/main/java/org/apache/samza/context/ApplicationTaskContext.java b/samza-api/src/main/java/org/apache/samza/context/ApplicationTaskContext.java
index a4236bf..21cb181 100644
--- a/samza-api/src/main/java/org/apache/samza/context/ApplicationTaskContext.java
+++ b/samza-api/src/main/java/org/apache/samza/context/ApplicationTaskContext.java
@@ -19,23 +19,26 @@
package org.apache.samza.context;
+import java.io.Serializable;
+import org.apache.samza.application.SamzaApplication;
+import org.apache.samza.application.descriptors.ApplicationDescriptor;
+
/**
* An {@link ApplicationTaskContext} instance can be used for holding per-task runtime state and objects and managing
- * their lifecycle in an {@link org.apache.samza.application.SamzaApplication}
+ * their lifecycle in an {@link SamzaApplication}
* <p>
- * Use {@link org.apache.samza.application.descriptors.ApplicationDescriptor#withApplicationTaskContextFactory}
- * to provide the {@link ApplicationTaskContextFactory}. Use {@link Context#getApplicationTaskContext()} to get
- * the created {@link ApplicationTaskContext} instance for the current task.
+ * Use {@link ApplicationDescriptor#withApplicationTaskContextFactory} to provide the
+ * {@link ApplicationTaskContextFactory}. Use {@link Context#getApplicationTaskContext()} to get the created
+ * {@link ApplicationTaskContext} instance for the current task.
* <p>
- * A unique instance of {@link ApplicationTaskContext} is created for each task in a container.
- * Use the {@link ApplicationTaskContextFactory} to create any runtime state and objects, and the
+ * A unique instance of {@link ApplicationTaskContext} is created for each task in a container. Use the
+ * {@link ApplicationTaskContextFactory} to create any runtime state and objects, and the
* {@link ApplicationTaskContext#start()} and {@link ApplicationTaskContext#stop()} methods to manage their lifecycle.
* <p>
* Use {@link ApplicationContainerContext} to hold runtime state and objects shared across all tasks within a container.
* Use {@link TaskContext} to access framework-provided context for a task.
* <p>
- * Unlike its {@link ApplicationTaskContextFactory}, an implementation does not need to be
- * {@link java.io.Serializable}.
+ * Unlike its {@link ApplicationTaskContextFactory}, an implementation does not need to be {@link Serializable}.
*/
public interface ApplicationTaskContext {
http://git-wip-us.apache.org/repos/asf/samza/blob/9f60e96b/samza-api/src/main/java/org/apache/samza/context/ApplicationTaskContextFactory.java
----------------------------------------------------------------------
diff --git a/samza-api/src/main/java/org/apache/samza/context/ApplicationTaskContextFactory.java b/samza-api/src/main/java/org/apache/samza/context/ApplicationTaskContextFactory.java
index c00935f..873a2d1 100644
--- a/samza-api/src/main/java/org/apache/samza/context/ApplicationTaskContextFactory.java
+++ b/samza-api/src/main/java/org/apache/samza/context/ApplicationTaskContextFactory.java
@@ -19,15 +19,17 @@
package org.apache.samza.context;
import java.io.Serializable;
+import org.apache.samza.application.SamzaApplication;
+import org.apache.samza.application.descriptors.ApplicationDescriptor;
/**
- * The factory for creating {@link ApplicationTaskContext} instances for a
- * {@link org.apache.samza.application.SamzaApplication}during task initialization.
+ * The factory for creating {@link ApplicationTaskContext} instances for a {@link SamzaApplication}during task
+ * initialization.
* <p>
- * Use {@link org.apache.samza.application.descriptors.ApplicationDescriptor#withApplicationTaskContextFactory} to
- * provide the {@link ApplicationTaskContextFactory}. Use {@link Context#getApplicationTaskContext()} to
- * get the created {@link ApplicationTaskContext} instance for the current task.
+ * Use {@link ApplicationDescriptor#withApplicationTaskContextFactory} to provide the
+ * {@link ApplicationTaskContextFactory}. Use {@link Context#getApplicationTaskContext()} to get the created
+ * {@link ApplicationTaskContext} instance for the current task.
* <p>
* The {@link ApplicationTaskContextFactory} implementation must be {@link Serializable}.
*
http://git-wip-us.apache.org/repos/asf/samza/blob/9f60e96b/samza-api/src/main/java/org/apache/samza/context/ContainerContext.java
----------------------------------------------------------------------
diff --git a/samza-api/src/main/java/org/apache/samza/context/ContainerContext.java b/samza-api/src/main/java/org/apache/samza/context/ContainerContext.java
index 97c5f53..3778adb 100644
--- a/samza-api/src/main/java/org/apache/samza/context/ContainerContext.java
+++ b/samza-api/src/main/java/org/apache/samza/context/ContainerContext.java
@@ -19,6 +19,7 @@
package org.apache.samza.context;
import org.apache.samza.job.model.ContainerModel;
+import org.apache.samza.job.model.TaskModel;
import org.apache.samza.metrics.MetricsRegistry;
@@ -30,8 +31,7 @@ import org.apache.samza.metrics.MetricsRegistry;
public interface ContainerContext {
/**
- * Gets the {@link ContainerModel} for this container, which contains this container's id and
- * its {@link org.apache.samza.job.model.TaskModel}.
+ * Gets the {@link ContainerModel} for this container, which contains this container's id and its {@link TaskModel}.
*
* @return the {@link ContainerModel} for this container
*/
http://git-wip-us.apache.org/repos/asf/samza/blob/9f60e96b/samza-api/src/main/java/org/apache/samza/context/Context.java
----------------------------------------------------------------------
diff --git a/samza-api/src/main/java/org/apache/samza/context/Context.java b/samza-api/src/main/java/org/apache/samza/context/Context.java
index e111127..44c8a05 100644
--- a/samza-api/src/main/java/org/apache/samza/context/Context.java
+++ b/samza-api/src/main/java/org/apache/samza/context/Context.java
@@ -18,6 +18,8 @@
*/
package org.apache.samza.context;
+import org.apache.samza.application.descriptors.ApplicationDescriptor;
+
/**
* A holder for all framework and application defined contexts at runtime.
*/
@@ -52,8 +54,8 @@ public interface Context {
* Gets the application-defined context for the current container. This context is shared by all tasks within
* the container.
* <p>
- * Use {@link org.apache.samza.application.descriptors.ApplicationDescriptor#withApplicationContainerContextFactory}
- * to provide a factory for this context. Cast the returned context to the concrete implementation type to use it.
+ * Use {@link ApplicationDescriptor#withApplicationContainerContextFactory} to provide a factory for this context.
+ * Cast the returned context to the concrete implementation type to use it.
* <p>
* Use {@link #getContainerContext()} to get the framework-provided container context.
*
@@ -65,8 +67,8 @@ public interface Context {
/**
* Gets the application-defined task context for the current task. This context is unique to this task.
* <p>
- * Use {@link org.apache.samza.application.descriptors.ApplicationDescriptor#withApplicationTaskContextFactory}
- * to provide a factory for this context. Cast the returned context to the concrete implementation type to use it.
+ * Use {@link ApplicationDescriptor#withApplicationTaskContextFactory} to provide a factory for this context.
+ * Cast the returned context to the concrete implementation type to use it.
* <p>
* Use {@link Context#getTaskContext()} to get the framework-provided task context.
*
http://git-wip-us.apache.org/repos/asf/samza/blob/9f60e96b/samza-api/src/main/java/org/apache/samza/context/TaskContext.java
----------------------------------------------------------------------
diff --git a/samza-api/src/main/java/org/apache/samza/context/TaskContext.java b/samza-api/src/main/java/org/apache/samza/context/TaskContext.java
index 3a5333c..cdf7404 100644
--- a/samza-api/src/main/java/org/apache/samza/context/TaskContext.java
+++ b/samza-api/src/main/java/org/apache/samza/context/TaskContext.java
@@ -24,6 +24,8 @@ import org.apache.samza.metrics.MetricsRegistry;
import org.apache.samza.scheduler.CallbackScheduler;
import org.apache.samza.storage.kv.KeyValueStore;
import org.apache.samza.system.SystemStreamPartition;
+import org.apache.samza.table.ReadWriteTable;
+import org.apache.samza.table.ReadableTable;
import org.apache.samza.table.Table;
@@ -64,9 +66,8 @@ public interface TaskContext {
* Gets the {@link Table} corresponding to the {@code tableId} for this task.
*
* The returned table should be cast with the concrete type parameters based on the configured table serdes, and
- * whether it is {@link org.apache.samza.table.ReadWriteTable} or {@link org.apache.samza.table.ReadableTable}.
- * E.g., if using string key and integer value serde for a writable table, it should be cast to a
- * {@code ReadWriteTable<String, Integer>}.
+ * whether it is {@link ReadWriteTable} or {@link ReadableTable}. E.g., if using string key and integer value
+ * serde for a writable table, it should be cast to a {@code ReadWriteTable<String, Integer>}.
*
* @param tableId id of the {@link Table} to get
* @return the {@link Table} associated with {@code tableId} for this task
@@ -91,8 +92,8 @@ public interface TaskContext {
*
* NOTE: this feature is experimental, and the API may change in a future release.
*
- * @param systemStreamPartition {@link org.apache.samza.system.SystemStreamPartition} whose offset should be set
- * @param offset to set for the given {@link org.apache.samza.system.SystemStreamPartition}
+ * @param systemStreamPartition {@link SystemStreamPartition} whose offset should be set
+ * @param offset to set for the given {@link SystemStreamPartition}
*/
@InterfaceStability.Evolving
void setStartingOffset(SystemStreamPartition systemStreamPartition, String offset);
http://git-wip-us.apache.org/repos/asf/samza/blob/9f60e96b/samza-api/src/main/java/org/apache/samza/system/descriptors/StreamExpander.java
----------------------------------------------------------------------
diff --git a/samza-api/src/main/java/org/apache/samza/system/descriptors/StreamExpander.java b/samza-api/src/main/java/org/apache/samza/system/descriptors/StreamExpander.java
index 4b8e6f0..c28a03b 100644
--- a/samza-api/src/main/java/org/apache/samza/system/descriptors/StreamExpander.java
+++ b/samza-api/src/main/java/org/apache/samza/system/descriptors/StreamExpander.java
@@ -23,9 +23,10 @@ import org.apache.samza.application.descriptors.StreamApplicationDescriptor;
import org.apache.samza.operators.MessageStream;
/**
- * Expands the provided {@link InputDescriptor} to a sub-DAG of one or more operators on the {@link StreamApplicationDescriptor},
- * and returns a new {@link MessageStream} with the combined results. Called when {@link StreamApplicationDescriptor#getInputStream}
- * is being used to get a {@link MessageStream} using an {@link InputDescriptor} from an expanding system descriptor.
+ * Expands the provided {@link InputDescriptor} to a sub-DAG of one or more operators on the
+ * {@link StreamApplicationDescriptor}, and returns a new {@link MessageStream} with the combined results.
+ * Called when {@link StreamApplicationDescriptor#getInputStream} is being used to get a {@link MessageStream} using an
+ * {@link InputDescriptor} from an expanding system descriptor.
* <p>
* This is provided by default by expanding system descriptor implementations and can not be overridden
* or set on a per stream level.
http://git-wip-us.apache.org/repos/asf/samza/blob/9f60e96b/samza-api/src/main/java/org/apache/samza/system/descriptors/TransformingInputDescriptorProvider.java
----------------------------------------------------------------------
diff --git a/samza-api/src/main/java/org/apache/samza/system/descriptors/TransformingInputDescriptorProvider.java b/samza-api/src/main/java/org/apache/samza/system/descriptors/TransformingInputDescriptorProvider.java
index e626efd..e44f361 100644
--- a/samza-api/src/main/java/org/apache/samza/system/descriptors/TransformingInputDescriptorProvider.java
+++ b/samza-api/src/main/java/org/apache/samza/system/descriptors/TransformingInputDescriptorProvider.java
@@ -21,19 +21,19 @@ package org.apache.samza.system.descriptors;
import org.apache.samza.serializers.Serde;
/**
- * Interface for advanced {@code SystemDescriptor}s that constrain the type of returned {@code InputDescriptor}s to
- * their own {@code InputTransformer} function result types.
+ * Interface for advanced {@link SystemDescriptor}s that constrain the type of returned {@link InputDescriptor}s to
+ * their own {@link InputTransformer} function result types.
*
- * @param <InputTransformerType> type of the system level {@code InputTransformer} results
+ * @param <InputTransformerType> type of the system level {@link InputTransformer} results
*/
public interface TransformingInputDescriptorProvider<InputTransformerType> {
/**
* Gets a {@link InputDescriptor} for an input stream on this system. The stream has the provided
- * stream level serde, and the default system level {@code InputTransformer}.
+ * stream level serde, and the default system level {@link InputTransformer}.
* <p>
* The type of messages in the stream is the type of messages returned by the default system level
- * {@code InputTransformer}
+ * {@link InputTransformer}
*
* @param streamId id of the input stream
* @param serde stream level serde for the input stream
http://git-wip-us.apache.org/repos/asf/samza/blob/9f60e96b/samza-api/src/main/java/org/apache/samza/table/Table.java
----------------------------------------------------------------------
diff --git a/samza-api/src/main/java/org/apache/samza/table/Table.java b/samza-api/src/main/java/org/apache/samza/table/Table.java
index 76ad460..234d15b 100644
--- a/samza-api/src/main/java/org/apache/samza/table/Table.java
+++ b/samza-api/src/main/java/org/apache/samza/table/Table.java
@@ -19,29 +19,31 @@
package org.apache.samza.table;
import org.apache.samza.annotation.InterfaceStability;
+import org.apache.samza.application.StreamApplication;
+import org.apache.samza.application.TaskApplication;
+import org.apache.samza.application.descriptors.StreamApplicationDescriptor;
+import org.apache.samza.context.TaskContext;
+import org.apache.samza.operators.MessageStream;
+import org.apache.samza.operators.functions.InitableFunction;
+import org.apache.samza.storage.kv.KeyValueStore;
+import org.apache.samza.table.descriptors.TableDescriptor;
+import org.apache.samza.task.InitableTask;
/**
- *
- * A {@link Table} is an abstraction for data sources that support random access by key. It is an
- * evolution of the existing {@link org.apache.samza.storage.kv.KeyValueStore} API. It offers support for
- * both local and remote data sources and composition through hybrid tables. For remote data sources,
- * a {@code RemoteTable} provides optimized access with caching, rate-limiting, and retry support.
+ * A {@link Table} is an abstraction for data sources that support random access by key. It is an evolution of the
+ * existing {@link KeyValueStore} API. It offers support for both local and remote data sources and composition through
+ * hybrid tables. For remote data sources, a {@code RemoteTable} provides optimized access with caching, rate-limiting,
+ * and retry support.
* <p>
* Depending on the implementation, a {@link Table} can be a {@link ReadableTable} or a {@link ReadWriteTable}.
* <p>
- * Use a {@link org.apache.samza.table.descriptors.TableDescriptor} to specify the properties of a {@link Table}.
- * For High Level API {@link org.apache.samza.application.StreamApplication}s, use
- * {@link org.apache.samza.application.descriptors.StreamApplicationDescriptor#getTable} to obtain
- * the {@link org.apache.samza.table.Table} instance for the descriptor that can be used with the
- * {@link org.apache.samza.operators.MessageStream} operators like
- * {@link org.apache.samza.operators.MessageStream#sendTo(Table)}.
- * Alternatively, use {@link org.apache.samza.context.TaskContext#getTable(String)} in
- * {@link org.apache.samza.operators.functions.InitableFunction#init} to get the table instance for use within
- * operator functions.
- * For Low Level API {@link org.apache.samza.application.TaskApplication}s, use
- * {@link org.apache.samza.context.TaskContext#getTable(String)} in
- * {@link org.apache.samza.task.InitableTask#init} to get the table instance for use within the Task.
+ * Use a {@link TableDescriptor} to specify the properties of a {@link Table}. For High Level API
+ * {@link StreamApplication}s, use {@link StreamApplicationDescriptor#getTable} to obtain the {@link Table} instance for
+ * the descriptor that can be used with the {@link MessageStream} operators like {@link MessageStream#sendTo(Table)}.
+ * Alternatively, use {@link TaskContext#getTable(String)} in {@link InitableFunction#init} to get the table instance
+ * for use within operator functions. For Low Level API {@link TaskApplication}s, use {@link TaskContext#getTable}
+ * in {@link InitableTask#init} to get the table instance for use within the Task.
*
* @param <R> the type of records in the table
*/
http://git-wip-us.apache.org/repos/asf/samza/blob/9f60e96b/samza-api/src/main/java/org/apache/samza/table/descriptors/TableDescriptor.java
----------------------------------------------------------------------
diff --git a/samza-api/src/main/java/org/apache/samza/table/descriptors/TableDescriptor.java b/samza-api/src/main/java/org/apache/samza/table/descriptors/TableDescriptor.java
index f1118eb..9798091 100644
--- a/samza-api/src/main/java/org/apache/samza/table/descriptors/TableDescriptor.java
+++ b/samza-api/src/main/java/org/apache/samza/table/descriptors/TableDescriptor.java
@@ -19,11 +19,18 @@
package org.apache.samza.table.descriptors;
import org.apache.samza.annotation.InterfaceStability;
+import org.apache.samza.application.StreamApplication;
+import org.apache.samza.application.TaskApplication;
+import org.apache.samza.application.descriptors.StreamApplicationDescriptor;
+import org.apache.samza.context.TaskContext;
+import org.apache.samza.operators.MessageStream;
+import org.apache.samza.operators.functions.InitableFunction;
+import org.apache.samza.table.Table;
+import org.apache.samza.task.InitableTask;
/**
- * A {@link TableDescriptor} can be used for specifying Samza and implementation-specific properties of a
- * {@link org.apache.samza.table.Table}.
+ * A {@link TableDescriptor} can be used for specifying Samza and implementation-specific properties of a {@link Table}.
* <p>
* Table properties provided in configuration override corresponding properties specified using a descriptor.
* <p>
@@ -36,17 +43,12 @@ import org.apache.samza.annotation.InterfaceStability;
* .withConfig("some-key", "some-value");
* }
* </pre>
- * For High Level API {@link org.apache.samza.application.StreamApplication}s, use
- * {@link org.apache.samza.application.descriptors.StreamApplicationDescriptor#getTable(TableDescriptor)} to obtain
- * the corresponding {@link org.apache.samza.table.Table} instance that can be used with the
- * {@link org.apache.samza.operators.MessageStream} operators like
- * {@link org.apache.samza.operators.MessageStream#sendTo(org.apache.samza.table.Table)}.
- * Alternatively, use {@link org.apache.samza.context.TaskContext#getTable(String)} in
- * {@link org.apache.samza.operators.functions.InitableFunction#init} to get the table instance for use within
- * operator functions.
- * For Low Level API {@link org.apache.samza.application.TaskApplication}s, use
- * {@link org.apache.samza.context.TaskContext#getTable(String)} in
- * {@link org.apache.samza.task.InitableTask#init} to get the table instance for use within the Task.
+ * For High Level API {@link StreamApplication}s, use {@link StreamApplicationDescriptor#getTable(TableDescriptor)} to
+ * obtain the corresponding {@link Table} instance that can be used with the {@link MessageStream} operators like
+ * {@link MessageStream#sendTo(Table)}. Alternatively, use {@link TaskContext#getTable(String)} in
+ * {@link InitableFunction#init} to get the table instance for use within operator functions. For Low Level API
+ * {@link TaskApplication}s, use {@link TaskContext#getTable(String)} in {@link InitableTask#init} to get the
+ * table instance for use within the Task.
*
* @param <K> the type of the key in this table
* @param <V> the type of the value in this table