Jet Docs (#219)

Added job and snapshot docs
hazelcast · Apr 20, 2023 · 3f9bbc6 · 3f9bbc6
1 parent e077cb2
commit 3f9bbc6
Show file tree

Hide file tree

Showing 11 changed files with 506 additions and 12 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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, clc job submit>>
+* <<clc-job-cancel, clc job cancel>>
+* <<clc-job-list, clc job list>>
+* <<clc-job-restart, clc job restart>>
+* <<clc-job-resume, clc job resume>>
+* <<clc-job-suspend, clc job suspend>>
+* <<clc-job-export-snapshot, clc job export-snapshot>>
+
+== 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
+
+|===