From 3f9bbc670f76b4afcc8a5c0b06ee9b424335b833 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Y=C3=BCce=20Tekol?= Date: Thu, 20 Apr 2023 12:17:18 +0300 Subject: [PATCH] Jet Docs (#219) Added job and snapshot docs --- base/commands/job/job_export_snapshot.go | 2 +- base/commands/job/job_resume.go | 2 +- base/commands/job/job_submit.go | 6 +- base/commands/job/job_terminate.go | 2 +- base/commands/snapshot/snapshot_delete.go | 2 +- docs/antora.yml | 6 +- docs/modules/ROOT/nav.adoc | 4 +- docs/modules/ROOT/pages/clc-commands.adoc | 6 + docs/modules/ROOT/pages/clc-job.adoc | 255 ++++++++++++++++++++++ docs/modules/ROOT/pages/clc-snapshot.adoc | 231 ++++++++++++++++++++ docs/modules/ROOT/pages/install-clc.adoc | 2 +- 11 files changed, 506 insertions(+), 12 deletions(-) create mode 100644 docs/modules/ROOT/pages/clc-job.adoc create mode 100644 docs/modules/ROOT/pages/clc-snapshot.adoc diff --git a/base/commands/job/job_export_snapshot.go b/base/commands/job/job_export_snapshot.go index a0b741ee..bf3e93d3 100644 --- a/base/commands/job/job_export_snapshot.go +++ b/base/commands/job/job_export_snapshot.go @@ -15,7 +15,7 @@ import ( type ExportSnapshotCmd struct{} func (cm ExportSnapshotCmd) Init(cc plug.InitContext) error { - cc.SetCommandUsage("export-snapshot [job ID/name]") + cc.SetCommandUsage("export-snapshot [job-ID/name]") help := "Exports a snapshot for a job" cc.SetCommandHelp(help, help) cc.SetPositionalArgCount(1, 1) diff --git a/base/commands/job/job_resume.go b/base/commands/job/job_resume.go index 49b0a35b..034490a3 100644 --- a/base/commands/job/job_resume.go +++ b/base/commands/job/job_resume.go @@ -13,7 +13,7 @@ import ( type ResumeCmd struct{} func (cm ResumeCmd) Init(cc plug.InitContext) error { - cc.SetCommandUsage("resume [job ID/name]") + cc.SetCommandUsage("resume [job-ID/name]") help := "Resumes a suspended job" cc.SetCommandHelp(help, help) cc.SetPositionalArgCount(1, 1) diff --git a/base/commands/job/job_submit.go b/base/commands/job/job_submit.go index c86a0345..c7927e8e 100644 --- a/base/commands/job/job_submit.go +++ b/base/commands/job/job_submit.go @@ -36,13 +36,13 @@ const ( type SubmitCmd struct{} func (cm SubmitCmd) Init(cc plug.InitContext) error { - cc.SetCommandUsage("submit [jar file] [arg, ...]") - long := fmt.Sprintf(`Submit a jar file and create a Jet job + cc.SetCommandUsage("submit [jar-file] [arg, ...]") + long := fmt.Sprintf(`Submits a jar file to create a Jet job This command requires a Viridian or a Hazelcast cluster having version %s or better. `, minServerVersion) - short := "Submit a jar file and create a Jet job" + short := "Submits a jar file to create a Jet job" cc.SetCommandHelp(long, short) cc.AddStringFlag(flagName, "", "", false, "override the job name") cc.AddStringFlag(flagSnapshot, "", "", false, "initial snapshot to start the job from") diff --git a/base/commands/job/job_terminate.go b/base/commands/job/job_terminate.go index 4c2afbe0..e1ffb634 100644 --- a/base/commands/job/job_terminate.go +++ b/base/commands/job/job_terminate.go @@ -20,7 +20,7 @@ type TerminateCmd struct { } func (cm TerminateCmd) Init(cc plug.InitContext) error { - cc.SetCommandUsage(fmt.Sprintf("%s [job ID/name, ...]", cm.name)) + cc.SetCommandUsage(fmt.Sprintf("%s [job-ID/name, ...]", cm.name)) cc.SetCommandHelp(cm.longHelp, cm.shortHelp) cc.SetPositionalArgCount(1, math.MaxInt) cc.AddBoolFlag(flagForce, "", false, false, fmt.Sprintf("force %s the job", cm.name)) diff --git a/base/commands/snapshot/snapshot_delete.go b/base/commands/snapshot/snapshot_delete.go index ed3559a7..40a57dac 100644 --- a/base/commands/snapshot/snapshot_delete.go +++ b/base/commands/snapshot/snapshot_delete.go @@ -11,7 +11,7 @@ import ( type DeleteCmd struct{} func (cm DeleteCmd) Init(cc plug.InitContext) error { - cc.SetCommandUsage("delete [snapshot ID") + cc.SetCommandUsage("delete [snapshot-name]") help := "Delete a snapshot" cc.SetCommandHelp(help, help) cc.SetPositionalArgCount(1, 1) diff --git a/docs/antora.yml b/docs/antora.yml index 7930b39e..10bebc58 100644 --- a/docs/antora.yml +++ b/docs/antora.yml @@ -2,15 +2,15 @@ name: clc title: Hazelcast CLC start_page: overview.adoc # Version in the URL -version: '5.2' +version: '5.3' # Version in the version selector (we display only the latest major.minor version) -display_version: '5.2.1' +display_version: '5.3.0-BETA-1' # Displays a banner to inform users that this is a prerelease version prerelease: false asciidoc: attributes: # The full major.minor.patch version, which is used as a variable in the docs for things like download links - full-version: '5.2.1' + full-version: '5.3.0-BETA-1' # Allows us to use UI macros. See https://docs.asciidoctor.org/asciidoc/latest/macros/ui-macros/ experimental: true snapshot: true diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index daf95b71..4cc42673 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/docs/modules/ROOT/nav.adoc @@ -12,13 +12,15 @@ .Reference * xref:clc-commands.adoc[Command Reference] +** xref:clc.adoc[] ** xref:clc-completion.adoc[] ** xref:clc-config.adoc[] ** xref:clc-home.adoc[] +** xref:clc-job.adoc[] ** xref:clc-object.adoc[] ** xref:clc-map.adoc[] -** xref:clc.adoc[] ** xref:clc-sql.adoc[] +** xref:clc-snapshot.adoc[] ** xref:clc-version.adoc[] * xref:keyboard-shortcuts.adoc[] diff --git a/docs/modules/ROOT/pages/clc-commands.adoc b/docs/modules/ROOT/pages/clc-commands.adoc index 76293ed1..8520a9be 100644 --- a/docs/modules/ROOT/pages/clc-commands.adoc +++ b/docs/modules/ROOT/pages/clc-commands.adoc @@ -43,6 +43,12 @@ include::partial$global-parameters.adoc[] |xref:clc-sql.adoc[clc sql] |Execute SQL queries. +|xref:clc-job.adoc[clc job] +|Create and manage Jet jobs. + +|xref:clc-snapshot.adoc[clc snapshot] +|Manage Jet job snapshotss. + |xref:clc-object.adoc[clc object] |Commands for generic distributed data structures. diff --git a/docs/modules/ROOT/pages/clc-job.adoc b/docs/modules/ROOT/pages/clc-job.adoc new file mode 100644 index 00000000..256559a7 --- /dev/null +++ b/docs/modules/ROOT/pages/clc-job.adoc @@ -0,0 +1,255 @@ += clc job + +This command group provides commands for creating and operating on Jet jobs. + +Check out the documentation for https://docs.hazelcast.com/hazelcast/latest/pipelines/overview[Data Pipelines] for more information about the Jet engine. + +Usage: + +[source,bash] +---- +clc job [command] [options] +---- + +== Commands + +* <> +* <> +* <> +* <> +* <> +* <> +* <> + +== clc job submit + +Creates a Jet job using the provided Jar file. + +This command requires a Viridian or a Hazelcast cluster +having version 5.3.0-BETA-2 or better. + +Usage: + +[source,bash] +---- +clc job submit [jar-file] [arg, ...] [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`jar-file` +|Required +|The jar file that contains the data pipeline code. +| + +|`arg` +|Optional +|Zero or more arguments to pass to the `main` method of the data pipeline class. +| + +|`--class` +|Optional +|Fully qualified name of the class that contains the `main` method that creates the data pipeline. +Must include the package name, such as: `com.example.JetJob`. +|Main class in the Jar manifest + +|`--name` +|Optional +|Name of the Jet job. Job names must be unique across running and suspended jobs. +|The name given while creating the data pipeline. + +|`--retries` +|Optional +|Number of times to retry a failed submission. +|`3` + +|`--snapshot` +|Optional +|Name of the snapshot to initialize the job with. +| + +|=== + +== clc job cancel + +Cancels one or more Jet jobs. + +Usage: + +[source,bash] +---- +clc job cancel [job-ID/name, ...] [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`job-ID/name` +|Required +|One or more Job IDs (UUID or integer) or job names. +| + +|`--force` +|Optional +|Force cancelling the job. This is useful for cancelling suspended jobs. +|`false` + +|=== + +== clc job list + +Lists Jet jobs. + +Usage: + +[source,bash] +---- +clc job list [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--include-sql` +|Optional +|Running SQL queries creates Jet jobs. This flags enables showing them in the list. +|`false` + +|`--include-user-cancelled` +|Optional +|This flags enables showing user cancelled jobs in the list. +|`false` + +|=== + +Example output: + +[source,bash] +---- +clc job list +09bb-6718-4902-0001 sample2 RUNNING 2023-04-20 06:06:52 - +09bb-6718-4900-0001 sample1 SUSPENDED 2023-04-20 06:06:45 - +---- + + +== clc job restart + +Restarts one or more Jet jobs. + +Usage: + +[source,bash] +---- +clc job restart [job-ID/name, ...] [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`job-ID/name` +|Required +|One or more Job IDs (UUID or integer) or job names. +| + +|`--force` +|Optional +|Force restart the job. +|`false` + +|=== + +== clc job resume + +Resumes a suspended a Jet job. + +Usage: + +[source,bash] +---- +clc job resume [job-ID/name] [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`job-ID/name` +|Required +|The Job with ID (UUID or integer) or with name to resume. +| + +|=== + + +== clc job suspend + +Suspends one or more Jet jobs. + +Usage: + +[source,bash] +---- +clc job suspend [job-ID/name, ...] [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`job-ID/name` +|Required +|One or more Job IDs (UUID or integer) or job names. +| + +|`--force` +|Optional +|Force suspend the job. +|`false` + +|=== + +== clc job export-snapshot + +Exports a snapshot from a Jet job. Note that this feature requires Viridian or Hazelcast Enterprise. + +Usage: + +[source,bash] +---- +clc job export-snapshot [job-ID/name] [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--cancel` +|Optional +|If true, the job is cancelled after taking a snapshot. +|`false` + +|`--name` +|Optional +|Name of the snapshot. If not given, an auto-generated snapshot name is used. +|Auto-generated name + +|=== diff --git a/docs/modules/ROOT/pages/clc-snapshot.adoc b/docs/modules/ROOT/pages/clc-snapshot.adoc new file mode 100644 index 00000000..d7cd049e --- /dev/null +++ b/docs/modules/ROOT/pages/clc-snapshot.adoc @@ -0,0 +1,231 @@ += clc snapshot + +This command manages Jet job snapshots. + +Usage: + +[source,bash] +---- +clc snapshot [command] [flags] +---- + +== Commands + +* <> +* <> + +== clc snapshot list + +Lists Jet job snapshots. + +Usage: + +[source,bash] +---- +clc snapshot list [flags] +---- + +== clc snapshot delete + +Deletes the given Jet job snapshot. + +Usage: + +[source,bash] +---- +clc snapshot delete [snapshot-name] [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`snapshot-name` +|Required +|The snapshot to delete. +| + +|=== + + +== clc job cancel + +Cancels one or more Jet jobs. + +Usage: + +[source,bash] +---- +clc job cancel [job-ID/name, ...] [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`job-ID/name` +|Required +|One or more Job IDs (UUID or integer) or job names. +| + +|`--force` +|Optional +|Force cancelling the job. This is useful for cancelling suspended jobs. +|`false` + +|=== + +== clc job list + +Lists Jet jobs. + +Usage: + +[source,bash] +---- +clc job list [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--include-sql` +|Optional +|Running SQL queries creates Jet jobs. This flags enables showing them in the list. +|`false` + +|`--include-user-cancelled` +|Optional +|This flags enables showing user cancelled jobs in the list. +|`false` + +|=== + +Example output: + +[source,bash] +---- +clc job list +09bb-6718-4902-0001 sample2 RUNNING 2023-04-20 06:06:52 - +09bb-6718-4900-0001 sample1 SUSPENDED 2023-04-20 06:06:45 - +---- + + +== clc job restart + +Restarts one or more Jet jobs. + +Usage: + +[source,bash] +---- +clc job restart [job-ID/name, ...] [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`job-ID/name` +|Required +|One or more Job IDs (UUID or integer) or job names. +| + +|`--force` +|Optional +|Force restart the job. +|`false` + +|=== + +== clc job resume + +Resumes a suspended a Jet job. + +Usage: + +[source,bash] +---- +clc job resume [job-ID/name] [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`job-ID/name` +|Required +|The Job with ID (UUID or integer) or with name to resume. +| + +|=== + + +== clc job suspend + +Suspends one or more Jet jobs. + +Usage: + +[source,bash] +---- +clc job suspend [job-ID/name, ...] [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`job-ID/name` +|Required +|One or more Job IDs (UUID or integer) or job names. +| + +|`--force` +|Optional +|Force suspend the job. +|`false` + +|=== + +== clc job export-snapshot + +Exports a snapshot from a Jet job. Note that this feature requires Viridian or Hazelcast Enterprise. + +Usage: + +[source,bash] +---- +clc job export-snapshot [job-ID/name] [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--cancel` +|Optional +|If true, the job is cancelled after taking a snapshot. +|`false` + +|`--name` +|Optional +|Name of the snapshot. If not given, an auto-generated snapshot name is used. +|Auto-generated name + +|=== diff --git a/docs/modules/ROOT/pages/install-clc.adoc b/docs/modules/ROOT/pages/install-clc.adoc index 998a65c9..27a7ca2c 100644 --- a/docs/modules/ROOT/pages/install-clc.adoc +++ b/docs/modules/ROOT/pages/install-clc.adoc @@ -1,7 +1,7 @@ = Installing the Hazelcast CLC :description: The Hazelcast Command-Line Client (CLC) is available to install in macOS, Linux, and Windows environments. -// See https://docs.hazelcast.com/hazelcast/5.2-snapshot/clients/clc#installing-the-hazelcast-clc +// See https://docs.hazelcast.com/hazelcast/5.3-snapshot/clients/clc#installing-the-hazelcast-clc {description} You can install the Hazelcast CLC, using one of the following: