You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@pulsar.apache.org by GitBox <gi...@apache.org> on 2018/04/05 00:05:43 UTC
[GitHub] merlimat closed pull request #1497: Update pulsar-admin functions help language
merlimat closed pull request #1497: Update pulsar-admin functions help language
URL: https://github.com/apache/incubator-pulsar/pull/1497
This is a PR merged from a forked repository.
As GitHub hides the original diff on merge, it is displayed below for
the sake of provenance:
As this is a foreign pull request (from a fork), the diff is supplied
below (as it won't show otherwise due to GitHub magic):
diff --git a/pulsar-client-tools/src/main/java/org/apache/pulsar/admin/cli/CmdFunctions.java b/pulsar-client-tools/src/main/java/org/apache/pulsar/admin/cli/CmdFunctions.java
index eb7fed74a..12b5060c7 100644
--- a/pulsar-client-tools/src/main/java/org/apache/pulsar/admin/cli/CmdFunctions.java
+++ b/pulsar-client-tools/src/main/java/org/apache/pulsar/admin/cli/CmdFunctions.java
@@ -65,7 +65,7 @@
import org.apache.pulsar.functions.utils.Utils;
@Slf4j
-@Parameters(commandDescription = "Operations for managing Pulsar Functions")
+@Parameters(commandDescription = "Interface for managing Pulsar Functions (lightweight, Lambda-style compute processes that work with Pulsar)")
public class CmdFunctions extends CmdBase {
private final PulsarAdminWithFunctions fnAdmin;
@@ -100,10 +100,10 @@ void processArguments() throws Exception {}
*/
@Getter
abstract class NamespaceCommand extends BaseCommand {
- @Parameter(names = "--tenant", description = "Tenant name", required = true)
+ @Parameter(names = "--tenant", description = "The function's tenant", required = true)
protected String tenant;
- @Parameter(names = "--namespace", description = "Namespace name", required = true)
+ @Parameter(names = "--namespace", description = "The function's namespace", required = true)
protected String namespace;
}
@@ -112,7 +112,7 @@ void processArguments() throws Exception {}
*/
@Getter
abstract class FunctionCommand extends NamespaceCommand {
- @Parameter(names = "--name", description = "Function name", required = true)
+ @Parameter(names = "--name", description = "The function's name", required = true)
protected String functionName;
}
@@ -121,39 +121,39 @@ void processArguments() throws Exception {}
*/
@Getter
abstract class FunctionConfigCommand extends BaseCommand {
- @Parameter(names = "--tenant", description = "Tenant name")
+ @Parameter(names = "--tenant", description = "The function's tenant")
protected String tenant;
- @Parameter(names = "--namespace", description = "Namespace name")
+ @Parameter(names = "--namespace", description = "The function's namespace")
protected String namespace;
- @Parameter(names = "--name", description = "Function name")
+ @Parameter(names = "--name", description = "The function's name")
protected String functionName;
- @Parameter(names = "--className", description = "Function class name", required = true)
+ @Parameter(names = "--className", description = "The function's class name", required = true)
protected String className;
@Parameter(
names = "--jar",
- description = "Path to the Java JAR file",
+ description = "Path to the jar file for the function (if the function is written in Java)",
listConverter = StringConverter.class)
protected String jarFile;
@Parameter(
names = "--py",
- description = "Path to the main Python file",
+ description = "Path to the main Python file for the function (if the function is written in Python)",
listConverter = StringConverter.class)
protected String pyFile;
- @Parameter(names = "--inputs", description = "Input topic name")
+ @Parameter(names = "--inputs", description = "The function's input topic or topics (multiple topics can be specified as a comma-separated list)")
protected String inputs;
- @Parameter(names = "--output", description = "Output topic name")
+ @Parameter(names = "--output", description = "The function's output topic")
protected String output;
- @Parameter(names = "--logTopic", description = "Log topic")
+ @Parameter(names = "--logTopic", description = "The topic to which the function's logs are produced")
protected String logTopic;
- @Parameter(names = "--customSerdeInputs", description = "Map of input topic to SerDe class name")
+ @Parameter(names = "--customSerdeInputs", description = "The map of input topics to SerDe class names (as a JSON string)")
protected String customSerdeInputString;
- @Parameter(names = "--outputSerdeClassName", description = "Output SerDe")
+ @Parameter(names = "--outputSerdeClassName", description = "The SerDe class to be used for messages output by the function")
protected String outputSerdeClassName;
- @Parameter(names = "--functionConfigFile", description = "Path to a YAML config file for the function")
+ @Parameter(names = "--functionConfigFile", description = "The path to a YAML config file specifying the function's configuration")
protected String fnConfigFile;
- @Parameter(names = "--processingGuarantees", description = "Processing guarantees applied to the function")
+ @Parameter(names = "--processingGuarantees", description = "The processing guarantees (aka delivery semantics) applied to the function")
protected FunctionConfig.ProcessingGuarantees processingGuarantees;
- @Parameter(names = "--subscriptionType", description = "The type of subscription used by the function as a consumer")
+ @Parameter(names = "--subscriptionType", description = "The type of subscription used by the function when consuming messages from the input topic(s)")
protected FunctionConfig.SubscriptionType subscriptionType;
@Parameter(names = "--userConfig", description = "User-defined config key/values")
protected String userConfigString;
@@ -224,11 +224,11 @@ void processArguments() throws Exception {
functionConfigBuilder.setRuntime(FunctionConfig.Runtime.PYTHON);
userCodeFile = pyFile;
} else {
- throw new RuntimeException("Either jar name or python file need to be specified");
+ throw new RuntimeException("Either a Java jar or a Python file needs to be specified for the function");
}
if (functionConfigBuilder.getInputsCount() == 0 && functionConfigBuilder.getCustomSerdeInputsCount() == 0) {
- throw new RuntimeException("No input topics specified");
+ throw new RuntimeException("No input topic(s) specified for the function");
}
if (parallelism == null) {
@@ -238,7 +238,7 @@ void processArguments() throws Exception {
} else {
int num = Integer.parseInt(parallelism);
if (num <= 0) {
- throw new IllegalArgumentException("Parallelism must be positive");
+ throw new IllegalArgumentException("The parallelism factor (the number of instances) for the function must be positive");
}
functionConfigBuilder.setParallelism(num);
}
@@ -256,7 +256,7 @@ private void doJavaSubmitChecks(FunctionConfig.Builder functionConfigBuilder) {
functionConfigBuilder.getClassName(), jarFile));
} else if (!Reflections.classInJarImplementsIface(file, functionConfigBuilder.getClassName(), Function.class)
&& !Reflections.classInJarImplementsIface(file, functionConfigBuilder.getClassName(), java.util.function.Function.class)) {
- throw new IllegalArgumentException(String.format("Pulsar function class %s in jar %s implements neither org.apache.pulsar.functions.api.Function nor java.util.function.Function",
+ throw new IllegalArgumentException(String.format("The Pulsar function class %s in jar %s implements neither org.apache.pulsar.functions.api.Function nor java.util.function.Function",
functionConfigBuilder.getClassName(), jarFile));
}
@@ -272,14 +272,14 @@ private void doJavaSubmitChecks(FunctionConfig.Builder functionConfigBuilder) {
if (userClass instanceof Function) {
Function pulsarFunction = (Function) userClass;
if (pulsarFunction == null) {
- throw new IllegalArgumentException(String.format("Pulsar function class %s could not be instantiated from jar %s",
+ throw new IllegalArgumentException(String.format("The Pulsar function class %s could not be instantiated from jar %s",
functionConfigBuilder.getClassName(), jarFile));
}
typeArgs = TypeResolver.resolveRawArguments(Function.class, pulsarFunction.getClass());
} else {
java.util.function.Function function = (java.util.function.Function) userClass;
if (function == null) {
- throw new IllegalArgumentException(String.format("Java Util function class %s could not be instantiated from jar %s",
+ throw new IllegalArgumentException(String.format("The Java util function class %s could not be instantiated from jar %s",
functionConfigBuilder.getClassName(), jarFile));
}
typeArgs = TypeResolver.resolveRawArguments(java.util.function.Function.class, function.getClass());
@@ -291,27 +291,27 @@ private void doJavaSubmitChecks(FunctionConfig.Builder functionConfigBuilder) {
if (!Reflections.classExists(inputSerializer)
&& !Reflections.classExistsInJar(new File(jarFile), inputSerializer)) {
throw new IllegalArgumentException(
- String.format("Input serialization/deserialization class %s does not exist",
+ String.format("The input serialization/deserialization class %s does not exist",
inputSerializer));
} else if (Reflections.classExists(inputSerializer)) {
if (!Reflections.classImplementsIface(inputSerializer, SerDe.class)) {
- throw new IllegalArgumentException(String.format("Input serialization/deserialization class %s does not not implement %s",
+ throw new IllegalArgumentException(String.format("The input serialization/deserialization class %s does not not implement %s",
inputSerializer, SerDe.class.getCanonicalName()));
}
} else if (Reflections.classExistsInJar(new File(jarFile), inputSerializer)) {
if (!Reflections.classInJarImplementsIface(new File(jarFile), inputSerializer, SerDe.class)) {
- throw new IllegalArgumentException(String.format("Input serialization/deserialization class %s does not not implement %s",
+ throw new IllegalArgumentException(String.format("The input serialization/deserialization class %s does not not implement %s",
inputSerializer, SerDe.class.getCanonicalName()));
}
}
if (inputSerializer.equals(DefaultSerDe.class.getName())) {
if (!DefaultSerDe.IsSupportedType(typeArgs[0])) {
- throw new RuntimeException("Default Serializer does not support type " + typeArgs[0]);
+ throw new RuntimeException("The default Serializer does not support type " + typeArgs[0]);
}
} else {
SerDe serDe = (SerDe) Reflections.createInstance(inputSerializer, file);
if (serDe == null) {
- throw new IllegalArgumentException(String.format("SerDe class %s does not exist in jar %s",
+ throw new IllegalArgumentException(String.format("The SerDe class %s does not exist in jar %s",
inputSerializer, jarFile));
}
Class<?>[] serDeTypes = TypeResolver.resolveRawArguments(SerDe.class, serDe.getClass());
@@ -372,7 +372,7 @@ private void doJavaSubmitChecks(FunctionConfig.Builder functionConfigBuilder) {
private void doPythonSubmitChecks(FunctionConfig.Builder functionConfigBuilder) {
if (functionConfigBuilder.getProcessingGuarantees() == FunctionConfig.ProcessingGuarantees.EFFECTIVELY_ONCE) {
- throw new RuntimeException("Effectively once not yet supported in python");
+ throw new RuntimeException("Effectively-once processing guarantees not yet supported in Python");
}
}
@@ -405,7 +405,7 @@ private void inferMissingTenant(FunctionConfig.Builder builder) {
String inputTopic = getUniqueInput(builder);
builder.setTenant(TopicName.get(inputTopic).getProperty());
} catch (IllegalArgumentException ex) {
- throw new RuntimeException("Missing tenant", ex);
+ throw new RuntimeException("You need to specify a tenant for the function", ex);
}
}
@@ -414,7 +414,7 @@ private void inferMissingNamespace(FunctionConfig.Builder builder) {
String inputTopic = getUniqueInput(builder);
builder.setNamespace(TopicName.get(inputTopic).getNamespacePortion());
} catch (IllegalArgumentException ex) {
- throw new RuntimeException("Missing Namespace");
+ throw new RuntimeException("You need to specify a namespace for the function");
}
}
@@ -440,14 +440,14 @@ private String getUniqueInput(FunctionConfig.Builder builder) {
}
}
- @Parameters(commandDescription = "Run function locally")
+ @Parameters(commandDescription = "Run the Pulsar Function locally (rather than deploying it to the Pulsar cluster)")
class LocalRunner extends FunctionConfigCommand {
// TODO: this should become bookkeeper url and it should be fetched from pulsar client.
- @Parameter(names = "--stateStorageServiceUrl", description = "State storage service URL")
+ @Parameter(names = "--stateStorageServiceUrl", description = "The URL for the state storage service (by default Apache BookKeeper)")
protected String stateStorageServiceUrl;
- @Parameter(names = "--brokerServiceUrl", description = "The Pulsar broker URL")
+ @Parameter(names = "--brokerServiceUrl", description = "The URL for the Pulsar broker")
protected String brokerServiceUrl;
@Override
@@ -499,7 +499,7 @@ public void run() {
}
}
- @Parameters(commandDescription = "Create function")
+ @Parameters(commandDescription = "Create a Pulsar Function in cluster mode (i.e. deploy it on a Pulsar cluster)")
class CreateFunction extends FunctionConfigCommand {
@Override
void runCmd() throws Exception {
@@ -511,7 +511,7 @@ void runCmd() throws Exception {
}
}
- @Parameters(commandDescription = "Get function")
+ @Parameters(commandDescription = "Fetch information about a Pulsar Function")
class GetFunction extends FunctionCommand {
@Override
void runCmd() throws Exception {
@@ -521,7 +521,7 @@ void runCmd() throws Exception {
}
}
- @Parameters(commandDescription = "GetStatus function")
+ @Parameters(commandDescription = "Check the current status of a Pulsar Function")
class GetFunctionStatus extends FunctionCommand {
@Override
void runCmd() throws Exception {
@@ -531,7 +531,7 @@ void runCmd() throws Exception {
}
}
- @Parameters(commandDescription = "Delete function")
+ @Parameters(commandDescription = "Delete a Pulsar Function that's running on a Pulsar cluster")
class DeleteFunction extends FunctionCommand {
@Override
void runCmd() throws Exception {
@@ -540,7 +540,7 @@ void runCmd() throws Exception {
}
}
- @Parameters(commandDescription = "Update function")
+ @Parameters(commandDescription = "Update a Pulsar Function that's been deployed to a Pulsar cluster")
class UpdateFunction extends FunctionConfigCommand {
@Override
void runCmd() throws Exception {
@@ -552,7 +552,7 @@ void runCmd() throws Exception {
}
}
- @Parameters(commandDescription = "List function")
+ @Parameters(commandDescription = "List all of the Pulsar Functions running under a specific tenant and namespace")
class ListFunctions extends NamespaceCommand {
@Override
void runCmd() throws Exception {
@@ -560,22 +560,22 @@ void runCmd() throws Exception {
}
}
- @Parameters(commandDescription = "Query Function State")
+ @Parameters(commandDescription = "Fetch the current state associated with a Pulsar Function running in cluster mode")
class StateGetter extends FunctionCommand {
@Parameter(names = { "-k", "--key" }, description = "key")
private String key = null;
// TODO: this url should be fetched along with bookkeeper location from pulsar admin
- @Parameter(names = { "-u", "--storage-service-url" }, description = "storage service url")
+ @Parameter(names = { "-u", "--storage-service-url" }, description = "The URL for the storage service used by the function")
private String stateStorageServiceUrl = null;
- @Parameter(names = { "-w", "--watch" }, description = "watch the value changes of a key")
+ @Parameter(names = { "-w", "--watch" }, description = "Watch for changes in the value associated with a key for a Pulsar Function")
private boolean watch = false;
@Override
void runCmd() throws Exception {
- checkNotNull(stateStorageServiceUrl, "State storage service url is missing");
+ checkNotNull(stateStorageServiceUrl, "The state storage service URL is missing");
String tableNs = String.format(
"%s_%s",
@@ -627,7 +627,7 @@ void runCmd() throws Exception {
@Override
void runCmd() throws Exception {
if (triggerFile == null && triggerValue == null) {
- throw new RuntimeException("Either a trigger value or a trigger filepath needs to be present");
+ throw new RuntimeException("Either a trigger value or a trigger filepath needs to be specified");
}
String retval = fnAdmin.functions().triggerFunction(tenant, namespace, functionName, triggerValue, triggerFile);
System.out.println(retval);
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
With regards,
Apache Git Services