From 9b0c45fd98a9c16ac3ed746cf246b2514a125132 Mon Sep 17 00:00:00 2001 From: serdaro Date: Sat, 14 Oct 2023 23:29:14 +0300 Subject: [PATCH] Creating CLC docs repo for the main branch. --- .github/workflows/build-docs.yml | 15 + .github/workflows/validate-docs.yml | 23 + .gitignore | 10 + README.adoc | 78 +++ antora-playbook-local.yml | 33 + antora-playbook.yml | 33 + check-links-playbook.yml | 38 ++ docs-tabs-library/tabs-block.js | 80 +++ docs/antora.yml | 22 + docs/modules/ROOT/nav.adoc | 55 ++ docs/modules/ROOT/pages/alias.adoc | 121 ++++ docs/modules/ROOT/pages/clc-atomic-long.adoc | 156 +++++ docs/modules/ROOT/pages/clc-commands.adoc | 64 ++ docs/modules/ROOT/pages/clc-completion.adoc | 30 + docs/modules/ROOT/pages/clc-config.adoc | 154 +++++ docs/modules/ROOT/pages/clc-demo.adoc | 105 +++ docs/modules/ROOT/pages/clc-home.adoc | 33 + docs/modules/ROOT/pages/clc-job.adoc | 278 ++++++++ docs/modules/ROOT/pages/clc-list.adoc | 316 +++++++++ docs/modules/ROOT/pages/clc-map.adoc | 631 ++++++++++++++++++ docs/modules/ROOT/pages/clc-multimap.adoc | 497 ++++++++++++++ docs/modules/ROOT/pages/clc-object.adoc | 76 +++ docs/modules/ROOT/pages/clc-platform.adoc | 0 docs/modules/ROOT/pages/clc-project.adoc | 152 +++++ docs/modules/ROOT/pages/clc-queue.adoc | 193 ++++++ docs/modules/ROOT/pages/clc-script.adoc | 208 ++++++ .../ROOT/pages/clc-serializer-generator.adoc | 142 ++++ docs/modules/ROOT/pages/clc-serializer.adoc | 143 ++++ docs/modules/ROOT/pages/clc-set.adoc | 225 +++++++ docs/modules/ROOT/pages/clc-snapshot.adoc | 231 +++++++ docs/modules/ROOT/pages/clc-sql.adoc | 74 ++ docs/modules/ROOT/pages/clc-template.adoc | 50 ++ docs/modules/ROOT/pages/clc-topic.adoc | 122 ++++ docs/modules/ROOT/pages/clc-version.adoc | 37 + docs/modules/ROOT/pages/clc-viridian.adoc | 414 ++++++++++++ docs/modules/ROOT/pages/clc.adoc | 127 ++++ docs/modules/ROOT/pages/config-wizard.adoc | 101 +++ .../ROOT/pages/configuration-format.adoc | 94 +++ docs/modules/ROOT/pages/configuration.adoc | 51 ++ .../ROOT/pages/connect-to-platform.adoc | 148 ++++ .../ROOT/pages/connect-to-viridian.adoc | 59 ++ .../ROOT/pages/environment-variables.adoc | 77 +++ docs/modules/ROOT/pages/get-started.adoc | 275 ++++++++ docs/modules/ROOT/pages/install-clc.adoc | 258 +++++++ .../ROOT/pages/jet-job-management.adoc | 198 ++++++ .../ROOT/pages/keyboard-shortcuts.adoc | 46 ++ .../pages/managing-viridian-clusters.adoc | 190 ++++++ docs/modules/ROOT/pages/overview.adoc | 108 +++ docs/modules/ROOT/pages/phone-homes.adoc | 25 + .../ROOT/pages/release-notes-5.2.0.adoc | 51 ++ .../ROOT/pages/release-notes-5.2.1.adoc | 16 + .../pages/release-notes-5.3.0-BETA-1.adoc | 16 + .../pages/release-notes-5.3.0-BETA-2.adoc | 25 + .../ROOT/pages/release-notes-5.3.0.adoc | 38 ++ .../ROOT/pages/release-notes-5.3.1.adoc | 11 + .../ROOT/pages/release-notes-5.3.2.adoc | 14 + .../ROOT/pages/release-notes-5.3.3.adoc | 26 + .../ROOT/pages/release-notes-5.3.4.adoc | 26 + .../ROOT/pages/release-notes-5.3.5.adoc | 36 + docs/modules/ROOT/pages/upgrade-clc.adoc | 5 + .../using-compact-serializer-generator.adoc | 193 ++++++ .../ROOT/partials/global-parameters.adoc | 77 +++ package.json | 23 + 63 files changed, 7153 insertions(+) create mode 100644 .github/workflows/build-docs.yml create mode 100644 .github/workflows/validate-docs.yml create mode 100644 .gitignore create mode 100644 README.adoc create mode 100644 antora-playbook-local.yml create mode 100644 antora-playbook.yml create mode 100644 check-links-playbook.yml create mode 100644 docs-tabs-library/tabs-block.js create mode 100644 docs/antora.yml create mode 100644 docs/modules/ROOT/nav.adoc create mode 100644 docs/modules/ROOT/pages/alias.adoc create mode 100644 docs/modules/ROOT/pages/clc-atomic-long.adoc create mode 100644 docs/modules/ROOT/pages/clc-commands.adoc create mode 100644 docs/modules/ROOT/pages/clc-completion.adoc create mode 100644 docs/modules/ROOT/pages/clc-config.adoc create mode 100644 docs/modules/ROOT/pages/clc-demo.adoc create mode 100644 docs/modules/ROOT/pages/clc-home.adoc create mode 100644 docs/modules/ROOT/pages/clc-job.adoc create mode 100644 docs/modules/ROOT/pages/clc-list.adoc create mode 100644 docs/modules/ROOT/pages/clc-map.adoc create mode 100644 docs/modules/ROOT/pages/clc-multimap.adoc create mode 100644 docs/modules/ROOT/pages/clc-object.adoc create mode 100644 docs/modules/ROOT/pages/clc-platform.adoc create mode 100644 docs/modules/ROOT/pages/clc-project.adoc create mode 100644 docs/modules/ROOT/pages/clc-queue.adoc create mode 100644 docs/modules/ROOT/pages/clc-script.adoc create mode 100644 docs/modules/ROOT/pages/clc-serializer-generator.adoc create mode 100644 docs/modules/ROOT/pages/clc-serializer.adoc create mode 100644 docs/modules/ROOT/pages/clc-set.adoc create mode 100644 docs/modules/ROOT/pages/clc-snapshot.adoc create mode 100644 docs/modules/ROOT/pages/clc-sql.adoc create mode 100644 docs/modules/ROOT/pages/clc-template.adoc create mode 100644 docs/modules/ROOT/pages/clc-topic.adoc create mode 100644 docs/modules/ROOT/pages/clc-version.adoc create mode 100644 docs/modules/ROOT/pages/clc-viridian.adoc create mode 100644 docs/modules/ROOT/pages/clc.adoc create mode 100644 docs/modules/ROOT/pages/config-wizard.adoc create mode 100644 docs/modules/ROOT/pages/configuration-format.adoc create mode 100644 docs/modules/ROOT/pages/configuration.adoc create mode 100644 docs/modules/ROOT/pages/connect-to-platform.adoc create mode 100644 docs/modules/ROOT/pages/connect-to-viridian.adoc create mode 100644 docs/modules/ROOT/pages/environment-variables.adoc create mode 100644 docs/modules/ROOT/pages/get-started.adoc create mode 100644 docs/modules/ROOT/pages/install-clc.adoc create mode 100644 docs/modules/ROOT/pages/jet-job-management.adoc create mode 100644 docs/modules/ROOT/pages/keyboard-shortcuts.adoc create mode 100644 docs/modules/ROOT/pages/managing-viridian-clusters.adoc create mode 100644 docs/modules/ROOT/pages/overview.adoc create mode 100644 docs/modules/ROOT/pages/phone-homes.adoc create mode 100644 docs/modules/ROOT/pages/release-notes-5.2.0.adoc create mode 100644 docs/modules/ROOT/pages/release-notes-5.2.1.adoc create mode 100644 docs/modules/ROOT/pages/release-notes-5.3.0-BETA-1.adoc create mode 100644 docs/modules/ROOT/pages/release-notes-5.3.0-BETA-2.adoc create mode 100644 docs/modules/ROOT/pages/release-notes-5.3.0.adoc create mode 100644 docs/modules/ROOT/pages/release-notes-5.3.1.adoc create mode 100644 docs/modules/ROOT/pages/release-notes-5.3.2.adoc create mode 100644 docs/modules/ROOT/pages/release-notes-5.3.3.adoc create mode 100644 docs/modules/ROOT/pages/release-notes-5.3.4.adoc create mode 100644 docs/modules/ROOT/pages/release-notes-5.3.5.adoc create mode 100644 docs/modules/ROOT/pages/upgrade-clc.adoc create mode 100644 docs/modules/ROOT/pages/using-compact-serializer-generator.adoc create mode 100644 docs/modules/ROOT/partials/global-parameters.adoc create mode 100644 package.json diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml new file mode 100644 index 0000000..cb8b7e5 --- /dev/null +++ b/.github/workflows/build-docs.yml @@ -0,0 +1,15 @@ +# This workflow triggers a build of the production documentation site +# if a commit is made to the listed branches + +name: Build production site + +on: + push: + branches: [ main, 'v/*' ] + +jobs: + dispatch: + runs-on: ubuntu-latest + steps: + - name: Trigger build + run: curl -X POST -d {} https://api.netlify.com/build_hooks/??? \ No newline at end of file diff --git a/.github/workflows/validate-docs.yml b/.github/workflows/validate-docs.yml new file mode 100644 index 0000000..04042f1 --- /dev/null +++ b/.github/workflows/validate-docs.yml @@ -0,0 +1,23 @@ +# This workflow will check if the incoming pull request includes any broken links + +name: Check for dead links + +on: + pull_request: + branches: [main, 'v/*'] + workflow_dispatch: + +jobs: + check-links: + + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v2 + - uses: actions/setup-node@v1 + with: + node-version: 16 + - name: Check for broken internal links + run: | + npm i + npm run-script check-links-local diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..8803ef7 --- /dev/null +++ b/.gitignore @@ -0,0 +1,10 @@ +/node_modules/ +/test/ +/build/ +.DS_Store +package-lock.json +.idea/ +*.iml +# Eclipse IDE +.project +.settings/ diff --git a/README.adoc b/README.adoc new file mode 100644 index 0000000..eb3a947 --- /dev/null +++ b/README.adoc @@ -0,0 +1,78 @@ += Hazelcast CLC Documentation +// Settings: +ifdef::env-github[] +:warning-caption: :warning: +endif::[] +// URLs: +:url-org: https://github.com/hazelcast +:url-contribute: https://github.com/hazelcast/hazelcast-docs/blob/develop/.github/CONTRIBUTING.adoc +:url-ui: {url-org}/hazelcast-docs-ui +:url-playbook: {url-org}/hazelcast-docs +:url-staging: +:url-cc: https://creativecommons.org/licenses/by-nc-sa/3.0/ +:url-hz-docs: {url-org}/hz-docs +:url-mc-docs: {url-org}/management-center-docs + +image:https://img.shields.io/badge/Build-Staging-yellow[link="{url-staging}"] + +This directory contains the Antora components for the Hazelcast CLC documentation. + +The documentation source files are marked up with AsciiDoc. + +== Docs Structure + +This section describes some important information about how this repository is structured: + +- The component name, version, and start page are configured in each branch's `antora.yml` file. +- The navigation for all modules is stored in the ROOT module's `nav.adoc` file. + +//// +== Release Workflow + +// Describe how versioning works for this project. + +=== Snapshot Releases + +// Describe the docs release process when a new snapshot version is released. + +=== Latest Releases + +// Describe the docs release process when a new major or minor version is released. + +=== Patch Releases + +// Describe the docs release process when a new patch version is released. + +=== Creating Release Branches + +// Describe the process for creating release branches. + +//// + +== GitHub Actions + +To automate some elements of the build process, this repository includes the following GitHub Actions: + +.GitHub Actions +[cols="m,a,a"] +|=== +|File |Description |Triggers + +|validate-site.yml +|Validates that all internal and external links are working +|On a pull request to the `main`, and `.z` maintenance branches + +|build-site.yml +|Builds the production documentation site by sending a build hook to Netlify (the hosting platform that we use) +|On a push to the `main` branch and any `.z` maintenance branches +|=== + +== Contributing + +If you want to add a change or contribute new content, see our link:.github/CONTRIBUTING.adoc[contributing guide]. + +To let us know about something that you'd like us to change, consider creating an issue. + +== License + +All documentation is available under the terms of a link:{url-cc}[Creative Commons License] diff --git a/antora-playbook-local.yml b/antora-playbook-local.yml new file mode 100644 index 0000000..ba8677e --- /dev/null +++ b/antora-playbook-local.yml @@ -0,0 +1,33 @@ +site: + title: Documentation + url: http:localhost:5000 + start_page: clc::overview.adoc + robots: disallow + keys: + docsearch_id: 'QK2EAH8GB0' + docsearch_api: 'ef7bd9485eafbd75d6e8425949eda1f5' + docsearch_index: 'prod_hazelcast_docs' +content: + sources: + - url: . + branches: HEAD + start_path: docs +ui: + bundle: + url: https://github.com/hazelcast/hazelcast-docs-ui/releases/latest/download/ui-bundle.zip #../hazelcast-docs-ui/build/ui-bundle.zip + snapshot: true +asciidoc: + attributes: + # Download images from kroki at build time (does not work for inline images) + kroki-fetch-diagram: true + # Inlude next and previous links on each page + page-pagination: true@ + idprefix: '' + # Separate anchor link names by dashes + idseparator: '-' + # Variables used in the docs + page-survey: https://www.surveymonkey.co.uk/r/NYGJNF9 + hazelcast-cloud: Viridian Cloud + extensions: + - ./docs-tabs-library/tabs-block.js + - asciidoctor-kroki diff --git a/antora-playbook.yml b/antora-playbook.yml new file mode 100644 index 0000000..d089065 --- /dev/null +++ b/antora-playbook.yml @@ -0,0 +1,33 @@ +site: + title: Documentation + url: https://eclectic-sawine-19fcf1.netlify.app + start_page: clc::overview.adoc + robots: disallow + keys: + docsearch_id: 'QK2EAH8GB0' + docsearch_api: 'ef7bd9485eafbd75d6e8425949eda1f5' + docsearch_index: 'prod_hazelcast_docs' +content: + sources: + - url: . + branches: HEAD + start_path: docs +ui: + bundle: + url: https://github.com/hazelcast/hazelcast-docs-ui/releases/latest/download/ui-bundle.zip #../hazelcast-docs-ui/build/ui-bundle.zip + snapshot: true +asciidoc: + attributes: + # Download images from kroki at build time (does not work for inline images) + kroki-fetch-diagram: true + # Inlude next and previous links on each page + page-pagination: true + idprefix: '' + # Separate anchor link names by dashes + idseparator: '-' + # Variables used in the docs + page-survey: https://www.surveymonkey.co.uk/r/NYGJNF9 + hazelcast-cloud: Viridian Cloud + extensions: + - ./docs-tabs-library/tabs-block.js + - asciidoctor-kroki diff --git a/check-links-playbook.yml b/check-links-playbook.yml new file mode 100644 index 0000000..6896892 --- /dev/null +++ b/check-links-playbook.yml @@ -0,0 +1,38 @@ +site: + title: Documentation + url: http:localhost:5000 +content: + sources: + - url: . + branches: HEAD + start_path: docs + - url: https://github.com/hazelcast/management-center-docs + branches: [main] + start_path: docs + - url: https://github.com/hazelcast/cloud-docs + branches: [main] + start_path: docs + - url: https://github.com/hazelcast/hazelcast-platform-operator-docs + branches: [main, v/*] + start_path: docs + - url: https://github.com/hazelcast/hz-docs + branches: [main, v/*] + start_path: docs +ui: + bundle: + url: https://github.com/hazelcast/hazelcast-docs-ui/releases/latest/download/ui-bundle.zip #../hazelcast-docs-ui/build/ui-bundle.zip + snapshot: true +asciidoc: + attributes: + # Download images from kroki at build time (does not work for inline images) + kroki-fetch-diagram: true + # Inlude next and previous links on each page + page-pagination: true + idprefix: '' + # Separate anchor link names by dashes + idseparator: '-' + page-survey: https://www.surveymonkey.co.uk/r/NYGJNF9 + hazelcast-cloud: Viridian Cloud + extensions: + - ./docs-tabs-library/tabs-block.js + - asciidoctor-kroki diff --git a/docs-tabs-library/tabs-block.js b/docs-tabs-library/tabs-block.js new file mode 100644 index 0000000..ae47e18 --- /dev/null +++ b/docs-tabs-library/tabs-block.js @@ -0,0 +1,80 @@ +/* Copyright (c) 2018 OpenDevise, Inc. + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ + +/** + * Extends the AsciiDoc syntax to support a tabset. The tabset is created from + * a dlist enclosed in an example block that is marked with the tabs style. + * + * Usage: + * + * [tabs] + * ==== + * Tab A:: + * + + * -- + * Contents of tab A. + * -- + * Tab B:: + * + + * -- + * Contents of tab B. + * -- + * ==== + * + * @author Dan Allen + */ +const IdSeparatorCh = '-' +const ExtraIdSeparatorsRx = /^-+|-+$|-(-)+/g +const InvalidIdCharsRx = /[^a-zA-Z0-9_]/g +const List = Opal.const_get_local(Opal.module(null, 'Asciidoctor'), 'List') +const ListItem = Opal.const_get_local(Opal.module(null, 'Asciidoctor'), 'ListItem') + +const generateId = (str, idx) => + `tabset${idx}_${str.toLowerCase().replace(InvalidIdCharsRx, IdSeparatorCh).replace(ExtraIdSeparatorsRx, '$1')}` + +function tabsBlock () { + this.onContext('example') + this.process((parent, reader, attrs) => { + const createHtmlFragment = (html) => this.createBlock(parent, 'pass', html) + const tabsetIdx = parent.getDocument().counter('idx-tabset') + const nodes = [] + nodes.push(createHtmlFragment('
')) + const container = this.parseContent(this.createBlock(parent, 'open'), reader) + const sourceTabs = container.getBlocks()[0] + if (!(sourceTabs && sourceTabs.getContext() === 'dlist' && sourceTabs.getItems().length)) return + const tabs = List.$new(parent, 'ulist') + tabs.addRole('tabs') + const panes = {} + sourceTabs.getItems().forEach(([[title], details]) => { + const tab = ListItem.$new(tabs) + tabs.$append(tab) + const id = generateId(title.getText(), tabsetIdx) + tab.text = `[[${id}]]${title.text}` + let blocks = details.getBlocks() + const numBlocks = blocks.length + if (numBlocks) { + if (blocks[0].context === 'open' && numBlocks === 1) blocks = blocks[0].getBlocks() + panes[id] = blocks.map((block) => (block.parent = parent) && block) + } + }) + nodes.push(tabs) + nodes.push(createHtmlFragment('
')) + Object.entries(panes).forEach(([id, blocks]) => { + nodes.push(createHtmlFragment(`
`)) + nodes.push(...blocks) + nodes.push(createHtmlFragment('
')) + }) + nodes.push(createHtmlFragment('
')) + nodes.push(createHtmlFragment('
')) + parent.blocks.push(...nodes) + }) +} + +function register (registry) { + registry.block('tabs', tabsBlock) +} + +module.exports.register = register diff --git a/docs/antora.yml b/docs/antora.yml new file mode 100644 index 0000000..bf9b38c --- /dev/null +++ b/docs/antora.yml @@ -0,0 +1,22 @@ +name: clc +title: Hazelcast CLC +start_page: overview.adoc +# Version in the URL +version: '5.3.6-snapshot' +# Version in the version selector (we display only the latest major.minor version) +display_version: '5.3.6-SNAPSHOT' +# Displays a banner to inform users that this is a prerelease version +prerelease: true +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.3.6-SNAPSHOT' + # Allows us to use UI macros. See https://docs.asciidoctor.org/asciidoc/latest/macros/ui-macros/ + experimental: true + snapshot: true + page-toclevels: 3@ + # Required Go version for build + go-version: 1.21 + page-latest-supported-mc: '5.4-snapshot' +nav: + - modules/ROOT/nav.adoc \ No newline at end of file diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc new file mode 100644 index 0000000..6391f15 --- /dev/null +++ b/docs/modules/ROOT/nav.adoc @@ -0,0 +1,55 @@ +.Get Started +* xref:overview.adoc[What is Hazelcast CLC?] +* xref:get-started.adoc[Get Started] +* Tutorials +** xref:managing-viridian-clusters.adoc[Manage {hazelcast-cloud} Clusters] +** xref:jet-job-management.adoc[Manage Jet Jobs] + + +.Manage +* xref:install-clc.adoc[Install] +* xref:configuration.adoc[Configure] +** xref:connect-to-viridian.adoc[Connect to {hazelcast-cloud}] +** xref:connect-to-platform.adoc[Connect to Platform] +** xref:using-compact-serializer-generator.adoc[Using Compact Serializer Generator] +//** xref:config-wizard.adoc[CLC Configuration Wizard ] +* xref:upgrade-clc.adoc[Upgrade] + +.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-set.adoc[] +** xref:clc-queue.adoc[] +** xref:clc-topic.adoc[] +** xref:clc-multimap.adoc[] +** xref:clc-script.adoc[] +** xref:clc-sql.adoc[] +** xref:clc-snapshot.adoc[] +** xref:clc-version.adoc[] +** xref:clc-viridian.adoc[] +** xref:clc-project.adoc[] +** xref:clc-template.adoc[] +** xref:alias.adoc[] +** xref:clc-serializer-generator.adoc[] +* xref:configuration-format.adoc[] +* xref:environment-variables.adoc[] +* xref:keyboard-shortcuts.adoc[] +* xref:phone-homes.adoc[] + +.Release Notes +* xref:release-notes-5.3.5.adoc[5.3.5] +* xref:release-notes-5.3.4.adoc[5.3.4] +* xref:release-notes-5.3.3.adoc[5.3.3] +* xref:release-notes-5.3.2.adoc[5.3.2] +* xref:release-notes-5.3.1.adoc[5.3.1] +* xref:release-notes-5.3.0.adoc[5.3.0] +* xref:release-notes-5.3.0-BETA-2.adoc[5.3.0-BETA-2] +* xref:release-notes-5.3.0-BETA-1.adoc[5.3.0-BETA-1] +* xref:release-notes-5.2.1.adoc[5.2.1] +* xref:release-notes-5.2.0.adoc[5.2.0] \ No newline at end of file diff --git a/docs/modules/ROOT/pages/alias.adoc b/docs/modules/ROOT/pages/alias.adoc new file mode 100644 index 0000000..07b8cd9 --- /dev/null +++ b/docs/modules/ROOT/pages/alias.adoc @@ -0,0 +1,121 @@ += User Defined Aliases + +Alias commands enable you to add and list user defined shortcuts. + +Alias commands can only be used in the interactive and scripting modes. +In order to persist the aliases you need to add `\alias add` statements in the `$CLC_HOME/shell.clc` script. `shell.clc` script is sourced when CLC starts in the interactive mode. + +Usage: + +[source,bash] +---- +clc alias [command] +---- + +== Commands + +* <> +* <> +* <> + +== clc alias add + +Add an alias with the given name and command. + +Usage: + +[source,bash] +---- +-- for command +\alias add {ALIAS-NAME} -- {\\COMMAND} + +-- for SQL +\alias add {ALIAS-NAME} -- {SQL} +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`name` +|Required +|Name of the alias. +| + +|`command` +|Required +| +| + +| +|=== + +Examples: + +- Adds an alias to list maps in the cluster: +[source,bash] +---- +clc alias add list-maps -- \\object list map +---- + +- Adds an alias to query SQL: +[source,bash] +---- +clc alias add first-five-desserts -- select name from desserts order by name limit 5; +---- + +== clc alias remove + +Remove an alias with the given name. + +Usage: + +[source,bash] +---- +clc alias remove [name] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`name` +|Required +|Name of the alias. +| + +| +|=== + +Example: + +[source,bash] +---- +clc alias remove my-alias +---- + +== clc alias list + +List existing aliases. + +Usage: + +[source,bash] +---- +clc alias list +---- + +Example: + +[source,bash] +---- +clc alias list +---- + +=== Alias Usage + +Aliases can be used in interactive and scripting modes with `@` prefix. Let's assume an alias named `my-alias` already created. it can be used as `@my-alias`. \ No newline at end of file diff --git a/docs/modules/ROOT/pages/clc-atomic-long.adoc b/docs/modules/ROOT/pages/clc-atomic-long.adoc new file mode 100644 index 0000000..3d7f8b1 --- /dev/null +++ b/docs/modules/ROOT/pages/clc-atomic-long.adoc @@ -0,0 +1,156 @@ += clc atomic-long + +atomic-long commands are a group of AtomicLong operations. + +Usage: + +[source,bash] +---- +clc atomic-long [command] [flags] +---- + +== Commands + +* <> +* <> +* <> +* <> + +== clc atomic-long get + +Get the value of the AtomicLong. + +Usage: + +[source,bash] +---- +clc atomic-long get [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--name`, `-n` +|Optional +|Name of the atomic-long. +|`default` + +|=== + +Example: + +[source,bash] +---- +clc atomic-long get --name transactionCount +---- + +== clc atomic-long set + +Sets the value of the AtomicLong. + +Usage: + +[source,bash] +---- +clc atomic-long set [value] [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--name`, `-n` +|Optional +|Name of the atomic-long. +|`default` + +|`value`, +|Required +|Value to set for the atomic long. +|N/A + +|=== + +Example: + +[source,bash] +---- +clc atomic-long set --name atomicSum 123 +---- + +== clc atomic-long increment-get + +Increment the AtomicLong by the given value. + +Usage: + +[source,bash] +---- +clc atomic-long increment-get [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--name`, `-n` +|Optional +|Name of the AtomicLong. +|`default` + +|`--by` +|Optional +|Value to increment by +|1 + +|=== + +Example: + +[source,bash] +---- +clc atomic-long increment-get --name atomicSum --by 10 +---- + +== clc atomic-long decrement-get + +Decrement the AtomicLong by the given value. + +Usage: + +[source,bash] +---- +clc atomic-long decrement-get [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--name`, `-n` +|Optional +|Name of the AtomicLong. +|`default` + +|`--by` +|Optional +|Value to decrement by +|1 + +|=== + +Example: + +[source,bash] +---- +clc atomic-long decrement-get --name atomicSum --by 10 +---- diff --git a/docs/modules/ROOT/pages/clc-commands.adoc b/docs/modules/ROOT/pages/clc-commands.adoc new file mode 100644 index 0000000..3d88cca --- /dev/null +++ b/docs/modules/ROOT/pages/clc-commands.adoc @@ -0,0 +1,64 @@ += clc +:description: pass:q[The `clc` command comes with subcommands for managing many aspects of a Hazelcast cluster.] + +{description} + +== Synopsis + +[source,bash] +---- +clc [command] [subcommand] [options] +---- + +You can use `clc [command] help` for information on a specific command. The synopsis for each command shows its parameters and their usage. + +== Global Options + +include::partial$global-parameters.adoc[] + +== Commands + +[cols="1m,2a"] +|=== +|Command|Description + +|xref:clc.adoc[clc shell] +|Start a Hazelcast CLC shell. + +|clc help +|Display help information for the `clc` command. + +|xref:clc-completion.adoc[clc completion] +|Generate shell autocompletion. + +|xref:clc-home.adoc[clc home] +|Print CLC home directory. + +|xref:clc-config.adoc[clc config] +|Manage the configuration used by the Hazelcast CLC. + +|xref:clc-map.adoc[clc map] +|Manage map data structures. + +|xref:clc-script.adoc[clc script] +|Execute CLC script. + +|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 snapshots. + +|xref:clc-viridian.adoc[clc viridian] +|{hazelcast-cloud} related operations. + +|xref:clc-object.adoc[clc object] +|Commands for generic distributed data structures. + +|xref:clc-version.adoc[clc version] +|Get version information. + +|=== diff --git a/docs/modules/ROOT/pages/clc-completion.adoc b/docs/modules/ROOT/pages/clc-completion.adoc new file mode 100644 index 0000000..40c7fd6 --- /dev/null +++ b/docs/modules/ROOT/pages/clc-completion.adoc @@ -0,0 +1,30 @@ += clc completion +:description: Generates the autocompletion script for the specified shell. See each sub-command's help for details on how to use the generated script. + +{description} + +Usage: + +[source,bash] +---- +clc completion [shell] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`shell` +|Required +|One of: + +* bash +* fish +* powershell +* zsh + +|N/A + +|=== diff --git a/docs/modules/ROOT/pages/clc-config.adoc b/docs/modules/ROOT/pages/clc-config.adoc new file mode 100644 index 0000000..34287b2 --- /dev/null +++ b/docs/modules/ROOT/pages/clc-config.adoc @@ -0,0 +1,154 @@ += clc config + +Configuration operations. + +Usage: + +[source,bash] +---- +clc config [command] [flags] +---- + +== Commands + +* <> +* <> + +== clc config add + +Adds a named configuration with the given values. Specify the configurations as `KEY=VALUE` pairs. + +It overwrites the previous configuration if it exists. + +Usage: + +[source,bash] +---- +clc config add [target] [source] [flags] [key=value...] +---- + +Configuration keys: + +[cols="1m,1a,1a,1"] +|=== +|Key|Value|Default Value|Note + +|cluster.name +|Any string +|dev +| + +|cluster.address +|HOST:PORT / HOST / :PORT +|localhost:5701 +| + +|cluster.user +|Any string +| +| Hazelcast Enterprise only + +|cluster.password +|Any string +| +| Hazelcast Enterprise only + +|cluster.discovery-token +|Any string +| +|{hazelcast-cloud} only + +|ssl.enabled +|true / false +|false +|{hazelcast-cloud} or Hazelcast Enterprise + +|ssl.server +|DOMAIN_NAME (must match SSL certificate) +| +|{hazelcast-cloud} (automatically set) or Hazelcast Enterprise + +|ssl.skip-verify +|true / false +|false +|{hazelcast-cloud} or Hazelcast Enterprise. Disables SSL host name and client-side verification. Never set to true in production. + +|ssl.ca-path +|An absolute or relative path +| +|{hazelcast-cloud} or Hazelcast Enterprise. Sets the path to the CA certificate. + +|ssl.key-path +|An absolute or relative path +| +|{hazelcast-cloud} or Hazelcast Enterprise. Sets the path to the certificate key. + +|ssl.key-password +|Any string +| +|{hazelcast-cloud} or Hazelcast Enterprise. Sets the password for the certificate key. + +|log.path +|An absolute or relative path or `stderr` to log to stderr. +|`$CLC_HOME/logs/YYYY-MM-DD.log` where the date is today. +| + +|log.level +|One of: + +. `error` +. `warn` +. `info` +. `debug` +| `info` +| + +|=== + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`target` +|Required +|Name of the configuration or its path. If a name is used, the configuration is saved to `$CLC_HOME/configs/NAME` +|N/A + +|`key=value` +|Optional +|Zero or more `config_item=value` pairs. +|N/A + +|=== + +Example output: + +[source,bash] +---- +clc config add dev cluster.name=dev cluster.address=localhost:5701 +---- + +== clc config list + +Lists the known configurations. + +A known configuration is a directory at `$CLC_HOME/configs` that contains config.yaml. +Directory names which start with dot (`.`) or underscore (`_`) are ignored. + +Usage: + +[source,bash] +---- +clc config list [flags] +---- + +Example output: + +[source,bash] +---- +clc config list +default +production +---- diff --git a/docs/modules/ROOT/pages/clc-demo.adoc b/docs/modules/ROOT/pages/clc-demo.adoc new file mode 100644 index 0000000..9e4257b --- /dev/null +++ b/docs/modules/ROOT/pages/clc-demo.adoc @@ -0,0 +1,105 @@ += clc demo + +This command group provides commands for creating and preparing demos. + +Usage: + +[source,bash] +---- +clc demo [command] [options] +---- + +== Commands + +* <> +* <> + +== clc demo generate data + +Generates stream events + +Generate data for given name, supported names are: + +- wikipedia-event-stream: Real-time Wikipedia event stream. Following key-value pairs can be set + - map=: generated stream items are written into the map + +Note that the data is streamed from Wikipedia changes. +Hazelcast has no control over the incoming data, + +Usage: + +[source,bash] +---- +clc demo generate-data [event-stream-name] [key=val, ...] [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`event-stream-name` +|Required +|Name for the event stream source. Supported sources are mentioned above. +| + +|`key=val` +|Optional +|Key value pairs used by event stream sources. +| + +|`--preview` +|Optional +|Print the generated data without interacting with the cluster. +| + +|`--max-values` +|Optional +|Number of events to create. +| + +|=== + +Example: + +[source,bash] +---- +clc demo generate-data wikipedia-event-stream map=wiki-events --preview +---- + +== clc demo map setmany + +Generates multiple map entries. + +Usage: + +[source,bash] +---- +clc demo map-setmany [entry-count] [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--name`, `-n` +|Optional +|Name of the map. +|`default` + +|`--size` +|Optional +|Size of the map value in bytes, the following suffixes can also be used: kb, mb, e.g., 42kb +|`1` + +|=== + +Example: + +[source,bash] +---- +clc demo map-setmany 10 --name myMap --size 1kb +---- \ No newline at end of file diff --git a/docs/modules/ROOT/pages/clc-home.adoc b/docs/modules/ROOT/pages/clc-home.adoc new file mode 100644 index 0000000..3a82039 --- /dev/null +++ b/docs/modules/ROOT/pages/clc-home.adoc @@ -0,0 +1,33 @@ += clc home +:description: Outputs the home directory of the Hazelcast CLC. + +The Hazelcast CLC stores all configuration, logs and other files in its home directory (`$CLC_HOME`). +This command outputs the CLC home directory. + +Usage: + +[source,bash] +---- +clc home [subdirectory ...] [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`subdirectory` +|Optional. +|If specified, the Hazelcast CLC joins the given subdirectories with `$CLC_HOME` +|N/A + +|=== + +Example output: + +[source,bash] +---- +clc home configs pr-3814 +/home/me/.hazelcast/configs/pr-3814 +---- diff --git a/docs/modules/ROOT/pages/clc-job.adoc b/docs/modules/ROOT/pages/clc-job.adoc new file mode 100644 index 0000000..b40bcdf --- /dev/null +++ b/docs/modules/ROOT/pages/clc-job.adoc @@ -0,0 +1,278 @@ += 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 Hazelcast {hazelcast-cloud} or Hazelcast Platform cluster of version 5.3.0 or above. + +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. +| + +|`--wait` +|Optional +|Waits for the job to be started. +|`false` + +|=== + +== clc job cancel + +Cancels the job with the given ID or name. + +Usage: + +[source,bash] +---- +clc job cancel [job-ID/name] [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`job-ID/name` +|Required +|Job ID (UUID or integer) or job name. +| + +|`--force` +|Optional +|Force cancelling the job. This is useful for cancelling suspended jobs. +|`false` + +|`--wait` +|Optional +|Waits for the job to be terminated. +|`false` + +|=== + +== clc job list + +Lists 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 the job with the given ID or name. + +Usage: + +[source,bash] +---- +clc job restart [job-ID/name] [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`job-ID/name` +|Required +|Job ID (UUID or integer) or job name. +| + +|`--force` +|Optional +|Force restart the job. +|`false` + +|`--wait` +|Optional +|Waits for the job to be restarted. +|`false` + +|=== + +== clc job resume + +Resumes a suspended 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. +| + +|`--wait` +|Optional +|Waits for the job to be resumed. +|`false` + +|=== + +== clc job suspend + +Suspends the job with the given ID or name. + +Usage: + +[source,bash] +---- +clc job suspend [job-ID/name] [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`job-ID/name` +|Required +|Job ID (UUID or integer) or job name. +| + +|`--force` +|Optional +|Force suspend the job. +|`false` + +|`--wait` +|Optional +|Waits for the job to be suspended. +|`false` + +|=== + +== clc job export-snapshot + +Exports a snapshot from a Jet job. This feature requires a Hazelcast {hazelcast-cloud} or Hazelcast Enterprise cluster. + +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-list.adoc b/docs/modules/ROOT/pages/clc-list.adoc new file mode 100644 index 0000000..37987e5 --- /dev/null +++ b/docs/modules/ROOT/pages/clc-list.adoc @@ -0,0 +1,316 @@ += clc list + +List commands are a group of list operations. + +Usage: + +[source,bash] +---- +clc list [command] [flags] +---- + +== Commands + +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> + +== clc list add + +Add a value in the given list. + +Usage: + +[source,bash] +---- +clc list add [value] [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--name`, `-n` +|Optional +|Name of the list. +|`default` + +|`value`, +|Required +|Value to set for the key. +|N/A + +|`--value-type`, `-v` +|Optional +|Data type of the value. One of: `string`, `bool`, `json`, `i8`, `i16`, `i32`, `i64`, `f32`, `f64` +|String + +|`--index` +|Optional +|Index for the value +|N/A + +|=== + +Example: + +[source,bash] +---- +clc list add --name example-list --value-type i16 10 --index 1 +---- + +== clc list contains + +Check if the value is present in the list. + +Usage: + +[source,bash] +---- +clc list contains [value] [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--name`, `-n` +|Optional +|Name of the list. +|`default` + +|`value`, +|Required +|Value to set for the key. +|N/A + +|`--value-type`, `-v` +|Optional +|Data type of the value. One of: `string`, `bool`, `json`, `i8`, `i16`, `i32`, `i64`, `f32`, `f64` +|String + +|=== + +Example: + +[source,bash] +---- +clc list contains --name example-list --value-type i16 10 +---- + +== clc list remove-value + +Remove a value from the list. + +Usage: + +[source,bash] +---- +clc list remove-value [value] [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--name`, `-n` +|Optional +|Name of the list. +|`default` + +|`value`, +|Required +|Value to set for the key. +|N/A + +|`--value-type`, `-v` +|Optional +|Data type of the value. One of: `string`, `bool`, `json`, `i8`, `i16`, `i32`, `i64`, `f32`, `f64` +|String + +|=== + +Example: + +[source,bash] +---- +clc list remove-value --name example-list --value-type i16 10 +---- + +== clc list remove-index + +Remove the value at given index from the list. + +Usage: + +[source,bash] +---- +clc list remove-index [index] [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--name`, `-n` +|Optional +|Name of the list. +|`default` + +|`--index` +|Required +|Index for the value +|N/A + +|=== + +Example: + +[source,bash] +---- +clc list remove-value --name example-list --value-type i16 10 +---- + +== clc list set + +Set a value at the given index in the list. + +Usage: + +[source,bash] +---- +clc list set [index] [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--name`, `-n` +|Optional +|Name of the list. +|`default` + +|`--index` +|Required +|Index for the value +|N/A + +|`value`, +|Required +|Value to set for the key. +|N/A + +|`--value-type`, `-v` +|Optional +|Data type of the value. One of: `string`, `bool`, `json`, `i8`, `i16`, `i32`, `i64`, `f32`, `f64` +|String + + +|=== + +Example: + +[source,bash] +---- +clc list set --name example-list 5 --value-type i16 10 +---- + +== clc list size + +Prints the size of the given the list. + +Usage: + +[source,bash] +---- +clc list size [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--name`, `-n` +|Optional +|Name of the map. +|`default` + +|=== + +== clc list clear + +Removes all entries from the list. + +Usage: + +[source,bash] +---- +clc list clear [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--name`, `-n` +|Optional +|Name of the map. +|`default` + +|`--yes` +|Optional +|Skip confirming the destroy operation. +|false + +|=== + +== clc list destroy + +Destroy a list + +This command will delete the list and the data in it will not be available anymore. + +Usage: + +[source,bash] +---- +clc list destroy [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--name`, `-n` +|Optional +|Name of the map. +|`default` + +|`--yes` +|Optional +|Skip confirming the destroy operation. +|false + +|=== \ No newline at end of file diff --git a/docs/modules/ROOT/pages/clc-map.adoc b/docs/modules/ROOT/pages/clc-map.adoc new file mode 100644 index 0000000..e7c3fda --- /dev/null +++ b/docs/modules/ROOT/pages/clc-map.adoc @@ -0,0 +1,631 @@ += clc map + +Map commands are a group of map operations. + +Usage: + +[source,bash] +---- +clc map [command] [flags] +---- + +== Commands + +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> + +== clc map clear + +Removes all entries from the map. + +Usage: + +[source,bash] +---- +clc map clear [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--name`, `-n` +|Optional +|Name of the map. +|`default` + +|=== + +== clc map get + +Prints a single entry from the map as a key-value pair. + +Usage: + +[source,bash] +---- +clc map get [key] [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--name`, `-n` +|Optional +|Name of the map. +|`default` + +|`key` +|Required +|Key of the map entry. +|N/A + +|`--key-type`, `-k` +|Optional +|Data type of the key. One of: `string`, `bool`, `json`, `i8`, `i16`, `i32`, `i64`, `f32`, `f64`. +|string + +|`--format`, `-f` +|Optional +|Output format. Supported formats: + +- `csv` +- `delimited` +- `json` +- `table` +|`delimited` in non-interactive mode, `table` in interactive mode. + +|=== + +Example: + +[source,bash] +---- +clc map get --name yearbook 2012 --key-type i16 +---- + +== clc map set + +Sets the given key-value entry pair in a map. + +Usage: + +[source,bash] +---- +clc map set [key] [value] [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--name`, `-n` +|Optional +|Name of the map. +|`default` + +|`key` +|Required +|Key of the map entry. +|N/A + +|`value`, +|Required +|Value to set for the key. +|N/A + +|`--key-type`, `-k` +|Optional +|Data type of the key. One of: `string`, `bool`, `json`, `i8`, `i16`, `i32`, `i64`, `f32`, `f64` +|string + +|`--value-type`, `-v` +|Optional +|Data type of the value. One of: `string`, `bool`, `json`, `i8`, `i16`, `i32`, `i64`, `f32`, `f64` +|string + +|`--ttl` +|Optional +|Duration in milliseconds after which the entry will expire and be evicted. It cannot be shorter than 1 second (1000 ms). +|N/A + +|`--max-idle` +|Optional +|Maximum time for this entry to stay idle in the map. It cannot be shorter than 1 second (1000 ms). +|N/A + +|=== + +Example: + +[source,bash] +---- +clc map set --key-type string hello --value-type f32 19.94 --name myMap --ttl 1300 +---- + +== clc map entry-set + +Gets all the entries of the specified map. + +Usage: + +[source,bash] +---- +clc map entry-set [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--name`, `-n` +|Optional +|Name of the map. +|`default` + +|`--format`, `-f` +|Optional +|Output format. Supported formats: + +- `csv` +- `delimited` +- `json` +- `table` +|`delimited` in non-interactive mode, `table` in interactive mode. + +|=== + +Example: + +[source,bash] +---- +clc map entry-set -n myMap +---- + +== clc map entry-view + +Returns a view of the entry with the given key. + +This command doesn't affect entry statistics, such as Hits and entry metadata such as Max Idle. + +See this documentation for information about per-entry statistics: +link:https://docs.hazelcast.com/hazelcast/5.3/data-structures/reading-map-metrics#getting-statistics-about-a-specific-map-entry[Getting Statistics about a Specific Map Entry]. + +The following information about the entry is returned: + +* Key +* Value +* Cost +* Creation Time +* Expiration Time +* Hits +* Last Access Time +* Last Stored Time +* Last Update Time +* Version +* TTL +* Max Idle + + +Usage: + +[source,bash] +---- +clc map entry-view [key] [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--name`, `-n` +|Optional +|Name of the map. +|`default` + +|`key` +|Required +|Key of the map entry. +|N/A + +|`--key-type`, `-k` +|Optional +|Data type of the key. One of: `string`, `bool`, `json`, `i8`, `i16`, `i32`, `i64`, `f32`, `f64` +|string + +|=== + +Example: + +[source,bash] +---- +clc map entry-view -n my-map my-key +---- + +== clc map key-set + +Gets all the keys of the specified map. + +Usage: + +[source,bash] +---- +clc map key-set [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--name`, `-n` +|Optional +|Name of the map. +|`default` + +|`--format`, `-f` +|Optional +|Output format. Supported formats: + +- `csv` +- `delimited` +- `json` +- `table` +|`delimited` in non-interactive mode, `table` in interactive mode. + +|=== + +Example: + +[source,bash] +---- +clc map key-set -n myMap +---- + +== clc map values + +Gets all the values of the given map. + +Usage: + +[source,bash] +---- +clc map values [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--name`, `-n` +|Optional +|Name of the map. +|`default` + +|`--format`, `-f` +|Optional +|Output format. Supported formats: + +- `csv` +- `delimited` +- `json` +- `table` +|`delimited` in non-interactive mode, `table` in interactive mode. + +|=== + +Example: + +[source,bash] +---- +clc map values -n myMap +---- + +== clc map lock + +Locks the key of the given the map. + +This command is only available in the interactive mode. + +Usage: + +[source,bash] +---- +clc map lock [key] [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--name`, `-n` +|Optional +|Name of the map. +|`default` + +|`key` +|Required +|Key of the map entry. +|N/A + +|`--key-type`, `-k` +|Optional +|Data type of the key. One of: `string`, `bool`, `json`, `i8`, `i16`, `i32`, `i64`, `f32`, `f64` +|String +|=== + +|`--ttl` +|Optional +|Duration in milliseconds after which the lock will expire. +|-1 + +Example: + +[source,bash] +---- +clc map lock -n my-map --key-type string key1 +---- + +== clc map try-lock + +Tries to lock the key of the given the map. Returns a result without waiting. + +This command is only available in the interactive mode. + +Usage: + +[source,bash] +---- +clc map try-lock [key] [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--name`, `-n` +|Optional +|Name of the map. +|`default` + +|`key` +|Required +|Key of the map entry. +|N/A + +|`--key-type`, `-k` +|Optional +|Data type of the key. One of: `string`, `bool`, `json`, `i8`, `i16`, `i32`, `i64`, `f32`, `f64` +|String + +|`--ttl` +|Optional +|Duration in milliseconds after which the lock will expire. +|-1 + +|=== + +Example: + +[source,bash] +---- +clc map try-lock -n my-map --key-type string key1 +---- + +== clc map unlock + +Unlocks the key of the given the map. + +This command is only available in the interactive mode. + +Usage: + +[source,bash] +---- +clc map unlock [key] [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--name`, `-n` +|Optional +|Name of the map. +|`default` + +|`key` +|Required +|Key of the map entry. +|N/A + +|`--key-type`, `-k` +|Optional +|Data type of the key. One of: `string`, `bool`, `json`, `i8`, `i16`, `i32`, `i64`, `f32`, `f64` +|String +|=== + +Example: + +[source,bash] +---- +clc map unlock -n my-map --key-type string key1 +---- + +== clc map size + +Prints the size of the given the map. + +Usage: + +[source,bash] +---- +clc map size [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--name`, `-n` +|Optional +|Name of the map. +|`default` + +|=== + +== clc map load-all + +Load keys from map-store into the map. If no key is given, all keys are loaded. + +Usage: + +[source,bash] +---- +clc map load-all [keys] [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--name`, `-n` +|Optional +|Name of the map. +|`default` + +|`keys` +|Required +|Keys of the map entries. +|N/A + +|`--key-type`, `-k` +|Optional +|Data type of the key. One of: `string`, `bool`, `json`, `i8`, `i16`, `i32`, `i64`, `f32`, `f64` +|string + +|=== + +Example: + +[source,bash] +---- +clc map load-all --key-type string key1 key2 --name myMap --replace +---- + +== clc map remove + +Deletes the value of a given key in a map and returns the key. + +Usage: + +[source,bash] +---- +clc map remove [flags] [key] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--name`, `-n` +|Optional +|Name of the map. +|`default` + +|`key` +|Required +|Key of the map entry. +|N/A + +|`--key-type`, `-k` +|Optional +|Data type of the key. One of: `string`, `bool`, `json`, `i8`, `i16`, `i32`, `i64`, `f32`, `f64` +|string + +|`--format`, `-f` +|Optional +|Output format. Supported formats: + +- `csv` +- `delimited` +- `json` +- `table` +|`delimited` in non-interactive mode, `table` in interactive mode. + +|=== + +Example: + +[source,bash] +---- +clc map remove --name myMap --key-type string k1 +k1 +---- + +== clc map destroy + +Deletes the map and all the data in it. + +Usage: + +[source,bash] +---- +clc map destroy [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--name`, `-n` +|Optional +|Name of the map. +|`default` + +|`--yes` +|Optional +|Skip confirming the destroy operation. +|`false` + +|=== \ No newline at end of file diff --git a/docs/modules/ROOT/pages/clc-multimap.adoc b/docs/modules/ROOT/pages/clc-multimap.adoc new file mode 100644 index 0000000..9122d0f --- /dev/null +++ b/docs/modules/ROOT/pages/clc-multimap.adoc @@ -0,0 +1,497 @@ += clc multi-map + +multi-map commands are a group of MultiMap operations. + +Usage: + +[source,bash] +---- +clc multi-map [command] [flags] +---- + +== Commands + +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> + +== clc multi-map put + +Put a value in the given MultiMap. + +Usage: + +[source,bash] +---- +clc multi-map put [key] [value] [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--name`, `-n` +|Optional +|Name of the MultiMap. +|`default` + +|`key` +|Required +|Key of the MultiMap entry. +|N/A + +|`value`, +|Required +|Value to set for the key. +|N/A + +|`--key-type`, `-k` +|Optional +|Data type of the key. One of: `string`, `bool`, `json`, `i8`, `i16`, `i32`, `i64`, `f32`, `f64` +|String + +|`--value-type`, `-v` +|Optional +|Data type of the value. One of: `string`, `bool`, `json`, `i8`, `i16`, `i32`, `i64`, `f32`, `f64` +|String + +|=== + +Example: + +[source,bash] +---- +clc multi-map put --key-type string hello --value-type f32 19.94 --name myMultiMap +---- + +== clc multi-map get + +Prints entries from the MultiMap. + +Usage: + +[source,bash] +---- +clc multi-map get [key] [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--name`, `-n` +|Optional +|Name of the MultiMap. +|`default` + +|`key` +|Required +|Key of the MultiMap entry. +|N/A + +|`--key-type`, `-k` +|Optional +|Data type of the key. One of: `string`, `bool`, `json`, `i8`, `i16`, `i32`, `i64`, `f32`, `f64`. +|string + +|`--format`, `-f` +|Optional +|Output format. Supported formats: + +- `csv` +- `delimited` +- `json` +- `table` +|`delimited` in non-interactive mode, `table` in interactive mode. + +|=== + +== clc multi-map remove + +Remove values from the given MultiMap. + +Usage: + +[source,bash] +---- +clc multi-map remove [key] [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--name`, `-n` +|Optional +|Name of the MultiMap. +|`default` + +|`key` +|Required +|Key of the MultiMap entries. +|N/A + +|`--key-type`, `-k` +|Optional +|Data type of the key. One of: `string`, `bool`, `json`, `i8`, `i16`, `i32`, `i64`, `f32`, `f64` +|String + +|`--format`, `-f` +|Optional +|Output format. Supported formats: + +- `csv` +- `delimited` +- `json` +- `table` +|`delimited` in non-interactive mode, `table` in interactive mode. + +|=== + +Example: + +[source,bash] +---- +clc multi-map remove --name mymulti-map --key-type string k1 +k1 +---- + +== clc multi-map size + +Prints the size of the given the MultiMap. + +Usage: + +[source,bash] +---- +clc multi-map size [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--name`, `-n` +|Optional +|Name of the MultiMap. +|`default` + +|=== + +== clc multi-map clear + +Removes all entries from the MultiMap. + +Usage: + +[source,bash] +---- +clc multi-map clear [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--name`, `-n` +|Optional +|Name of the MultiMap. +|`default` + +|`--yes` +|Optional +|Skip confirming the clear operation. +|`false` + +|=== + +== clc multi-map destroy + +Deletes the MultiMap and all the data in it. + +Usage: + +[source,bash] +---- +clc multi-map destroy [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--name`, `-n` +|Optional +|Name of the MultiMap. +|`default` + +|`--yes` +|Optional +|Skip confirming the destroy operation. +|`false` + +|=== + +Example: + +[source,bash] +---- +clc multi-map destroy -n myMultiMap +---- + +== clc multi-map key-set + +Gets all the keys of the specified MultiMap. + +Usage: + +[source,bash] +---- +clc multi-map key-set [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--name`, `-n` +|Optional +|Name of the MultiMap. +|`default` + +|`--format`, `-f` +|Optional +|Output format. Supported formats: + +- `csv` +- `delimited` +- `json` +- `table` +|`delimited` in non-interactive mode, `table` in interactive mode. + +|=== + +Example: + +[source,bash] +---- +clc multi-map key-set -n myMultiMap +---- + +== clc multi-map entry-set + +Gets all the entries of the specified MultiMap. + +Usage: + +[source,bash] +---- +clc multi-map entry-set [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--name`, `-n` +|Optional +|Name of the MultiMap. +|`default` + +|`--format`, `-f` +|Optional +|Output format. Supported formats: + +- `csv` +- `delimited` +- `json` +- `table` +|`delimited` in non-interactive mode, `table` in interactive mode. + +|=== + +Example: + +[source,bash] +---- +clc multi-map entry-set -n myMultiMap +---- + +== clc multi-map values + +Gets all values of the specified MultiMap. + +Usage: + +[source,bash] +---- +clc multi-map values [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--name`, `-n` +|Optional +|Name of the MultiMap. +|`default` + +|`--format`, `-f` +|Optional +|Output format. Supported formats: + +- `csv` +- `delimited` +- `json` +- `table` +|`delimited` in non-interactive mode, `table` in interactive mode. + +|=== + +Example: + +[source,bash] +---- +clc multi-map values -n myMultiMap +---- + +== clc multi-map lock + +Lock a key in the given MultiMap. + +This command is only available in the interactive mode. + +Usage: + +[source,bash] +---- +clc multi-map lock [key] [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--name`, `-n` +|Optional +|Name of the MultiMap. +|`default` + +|`--key-type`, `-k` +|Optional +|Data type of the key. One of: `string`, `bool`, `json`, `i8`, `i16`, `i32`, `i64`, `f32`, `f64` +|String + +|=== + +Example: + +[source,bash] +---- +clc multi-map lock 1 +---- + +== clc multi-map try-lock + +Tries to lock the key of the given the MultiMap. Returns a result without waiting. + +This command is only available in the interactive mode. + +Usage: + +[source,bash] +---- +clc multi-map try-lock [key] [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--name`, `-n` +|Optional +|Name of the MultiMap. +|`default` + +|`--key-type`, `-k` +|Optional +|Data type of the key. One of: `string`, `bool`, `json`, `i8`, `i16`, `i32`, `i64`, `f32`, `f64` +|String + +|=== + +Example: + +[source,bash] +---- +clc multi-map try-lock 1 +---- + +== clc multi-map unlock + +Unlock a key in the given MultiMap. + +This command is only available in the interactive mode. + +Usage: + +[source,bash] +---- +clc multi-map unlock [key] [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--name`, `-n` +|Optional +|Name of the MultiMap. +|`default` + +|`--key-type`, `-k` +|Optional +|Data type of the key. One of: `string`, `bool`, `json`, `i8`, `i16`, `i32`, `i64`, `f32`, `f64` +|String + +|=== + +Example: + +[source,bash] +---- +clc multi-map unlock 1 +---- \ No newline at end of file diff --git a/docs/modules/ROOT/pages/clc-object.adoc b/docs/modules/ROOT/pages/clc-object.adoc new file mode 100644 index 0000000..d8cfae6 --- /dev/null +++ b/docs/modules/ROOT/pages/clc-object.adoc @@ -0,0 +1,76 @@ += clc object + +Generic distributed data structure commands. + +Usage: + +[source,bash] +---- +clc object [command] [options] +---- + +== Commands + +* <> + +== clc object list + +Prints the distributed objects in the cluster as type-name pairs. + +Usage: + +[source,bash] +---- +clc object list [object-type] [flags] +---- + +Available object types (_case insensitive_): + + + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`type` +|Optional +|Type of the objects to be listed. If not specified, the command lists all the objects. Available types (_case insensitive_): + +* cache +* cardinalityEstimator +* countdownLatch +* eventJournal +* flakeIdGenerator +* list +* map +* multiMap +* pnCounter +* queue +* replicatedMap +* ringBuffer +* semaphore +* set +* topic + +Note that CP subsystem objects cannot be listed. + +|All types + +|`--show-hidden` +|Optional +|Lists the objects with names starting with "__" +|N/A + +|=== + +Example output: + +Assuming you have a map named `currency` in your cluster: + +[source,bash] +---- +clc object list +map currency +---- diff --git a/docs/modules/ROOT/pages/clc-platform.adoc b/docs/modules/ROOT/pages/clc-platform.adoc new file mode 100644 index 0000000..e69de29 diff --git a/docs/modules/ROOT/pages/clc-project.adoc b/docs/modules/ROOT/pages/clc-project.adoc new file mode 100644 index 0000000..ab0ec00 --- /dev/null +++ b/docs/modules/ROOT/pages/clc-project.adoc @@ -0,0 +1,152 @@ += clc project (Beta) + +Project commands are a group of project operations. + +Usage: + +[source,bash] +---- +clc project [command] [flags] +---- + +== Commands + +* <> + +== clc project create + +Creates a project from the given template. + +Usage: + +[source,bash] +---- +clc project create [template-name] [placeholder-values] [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--output-dir`, `-o` +|Optional +|Output directory for the project to be created. +|Template name + +|`--source` +|Optional +|The Github organization/user account to search for the templates. +|hazelcast-templates + +|`template-name` +|Required +|Name of the template. +| + +|`placeholder-values` +|Optional +|Template placeholder values can be specified as key-value pairs. You can use lowercase letters, numbers and the underscore character in keys. Example: `my_key1`=`value` + +| +|=== + +=== Creating and Using Your Own Templates + +Templates are located in https://github.com/hazelcast-templates. You can override it by using the `--source` flag. + +* Templates are in link:https://pkg.go.dev/text/template[Go template] format. +* You can create a "defaults.yaml" file for default values in template's root directory. +* Template files must have the ".template" extension. +* Files with "." and "_" prefixes are ignored unless they have the ".keep" extension. +* All files with ".keep" extension are copied by stripping the ".keep" extension. +* Other files are copied verbatim. +*Properties are read from the following resources in order: ++ +1. `defaults.yaml` (keys cannot contain punctuation) +2. `config.yaml` +3. User passed key-values in the "KEY=VALUE" format. The keys can only contain lowercase letters, numbers and the underscore character. + +==== Placeholders + +You can use the placeholders in "defaults.yaml" and the following configuration item placeholders: + +* clc_home +* cluster_name +* cluster_address +* cluster_user +* cluster_password +* cluster_discovery_token +* ssl_enabled +* ssl_server +* ssl_skip_verify +* ssl_ca_path +* ssl_key_path +* ssl_key_password +* log_path +* log_level + +==== Actions + +* `repeat COUNT`: Returns an integer array with number from `0` to `COUNT`. If `COUNT` is `0`, an array with `0` integers are returned. ++ +Template: ++ +[source] +----- +{{ range repeat 3 }} +Number {{.}} +{{ end -}} +----- ++ +Output: ++ +[source] +----- +Number 0 +Number 1 +Number 2 +----- + +* `each VALUE ...`: Returns an array with items having the `Index` and `Value`. ++ +Template: ++ +[source] +----- +{{ range each "foo" "bar" 38 }} +Item {{ .Index }} = {{ .Value }} +{{ end -}} +----- ++ +Output: ++ +[source] +----- +Item 0 = foo +Item 1 = bar +Item 2 = 38 +----- + +=== Usage + +Example (Linux and macOS): + +[source,bash] +---- +clc project create \ +simple-streaming-pipeline\ +--output-dir my-project\ +my_key1=my_value1 my_key2=my_value2 +---- + +Example (Windows): + +[source,bash] +---- +clc project create^ +simple-streaming-pipeline^ +--output-dir my-project^ +my_key1=my_value1 my_key2=my_value2 +---- diff --git a/docs/modules/ROOT/pages/clc-queue.adoc b/docs/modules/ROOT/pages/clc-queue.adoc new file mode 100644 index 0000000..e134e66 --- /dev/null +++ b/docs/modules/ROOT/pages/clc-queue.adoc @@ -0,0 +1,193 @@ += clc queue + +Queue commands are a group of queue operations. + +Usage: + +[source,bash] +---- +clc queue [command] [flags] +---- + +== Commands + +* <> +* <> +* <> +* <> +* <> + +== clc queue clear + +Delete all entries of a queue. + +Usage: + +[source,bash] +---- +clc queue clear [flags] +---- +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--name`, `-n` +|Optional +|Name of the queue. +|`default` + +|=== + +Example: + +[source,bash] +---- +clc queue clear --name my-queue +---- + +== clc queue offer + +Add a value to the given queue. + +Usage: + +[source,bash] +---- +clc queue offer [values] [flags] +---- +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`values` +|Required +|Values to add to the queue. +|N/A + +|`--name`, `-n` +|Optional +|Name of the queue. +|`default` + +|`--value-type`, `-v` +|Optional +|Data type of the value. One of: `string`, `bool`, `json`, `i8`, `i16`, `i32`, `i64`, `f32`, `f64` +|string + +|=== +Example: + +[source,bash] +---- +clc queue offer --value-type f32 19.94 19.92 --name my-queue +---- + +== clc queue poll + +Remove the given number of elements from the given queue. + +Usage: + +[source,bash] +---- +clc queue poll [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--name`, `-n` +|Optional +|Name of the queue. +|`default` + +|`--count` +|Optional +|Number of element to be removed from the given queue. +|1 + +|`--format`, `-f` +|Optional +|Output format. Supported formats: + +- `csv` +- `delimited` +- `json` +- `table` +|`delimited` in non-interactive mode, `table` in interactive mode. + +|=== + +Example: + +[source,bash] +---- +clc queue poll --count 2 --name my-queue 5 +---- + +== clc queue size + +Return the size of the given queue. + +Usage: + +[source,bash] +---- +clc queue size [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--name`, `-n` +|Optional +|Name of the queue. +|`default` + +|=== + +Example: + +[source,bash] +---- +clc queue size --name my-queue +---- + +== clc queue destroy + +Deletes the queue and all the data in it. + +Usage: + +[source,bash] +---- +clc queue destroy [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--name`, `-n` +|Optional +|Name of the queue. +|`default` + +|`--yes` +|Optional +|Skip confirming the destroy operation. +|`false` + +|=== \ No newline at end of file diff --git a/docs/modules/ROOT/pages/clc-script.adoc b/docs/modules/ROOT/pages/clc-script.adoc new file mode 100644 index 0000000..b237315 --- /dev/null +++ b/docs/modules/ROOT/pages/clc-script.adoc @@ -0,0 +1,208 @@ += clc script +:description: Runs the script in the given local or HTTP location. Advanced script currently only supports local files. + +{description} + +Runs the given script. + +Two kinds of scripts are supported: + +* Shell scripts: CLC commands or SQL +* Advanced scripts: a Python-like language + +The scripts may be in the following locations: + +* Filesystem path: The path may optionally have the file:// prefix. +* HTTP resource: The path should have the http:// or https:// prefix. + +== Shell Script + +The script can contain: + +1. SQL statements +2. CLC commands prefixed with backslash. +3. Comments starting with `--` (double dash) + +The script should have either `.clc` or `.sql` extension. +Files with one of these two extensions are interpreted equivalently. + +== Advanced Script (BETA) + +Advanced scripts are written in a Python-like language called Starlark. +See this document for the language reference: https://github.com/google/starlark-go/blob/master/doc/spec.md + +CLC commands are mapped to functions using a few straightforward rules: + +1. If the command is a top level command, it is mapped as is. E.g., `home` command is mapped to the `home()` function. +2. Positional arguments are mapped to positional arguments in the function signature. +3. Flags are mapped to keyword arguments in the function signature. + +Examples: + +* `clc map set -n mymap foo bar` => `map_set("foo", "bar", name="mymap")` + +The script should have the .star extension. +Only the filesystem is supported as a source for advanced scripts. + +The following values are available for advanced scripts: + +[cols="1m,1a"] +|=== +|Value|Description + +|`nanosecond` +|1 nanoscond. + +|`microsecond` +|1 microsecond in nanoseconds. + +|`millisecond` +|1 millisecond in nanoseconds. + +|`second` +|1 second in nanoseconds. + +|`minute` +|1 minute in nanoseconds. + +|`hour` +|1 hour in nanoseconds. + +|`day` +|1 day in nanoseconds. + +|=== + +The following functions are available for advanced scripts: + +[cols="1m,1a"] +|=== +|Function|Description + +|`ARGS_LIST = argv()` +|Returns the arguments passed to the script as a list. 0th item in the list is the script name. + +| `DATA_TYPE_NAME = `data_type(DATA_VALUE)` +|Returns the type name of the given data value. + +| `VALUE = `data_value(DATA_VALUE)` +|Attempts to convert the data value to the corresponding script value. + +|`ERROR = last_error()` +|Returns the last error or `None`. This function should be used together with the `--ignore-errors` flag. + +|`log_debug(STRING)` +|Adds a DEBUG message to the CLC log. + +|`log_error(STRING_OR_ERROR)` +|Adds an ERROR message to the CLC log. You can pass a `string` message or an `error`. + +|`log_warn(STRING)` +|Adds a WARN message to the CLC log. + +|`map_clear(name=MAP_NAME)` +|Clears the given Map. + +|`map_destroy(name=MAP_NAME)` +|Deletes the given Map. + +|`LIST_OF_KEY_VALUE_TUPLES = map_entry_set(name=MAP_NAME)` +|Returns a list of tuples that has the key in index 0 and the value in index 1. Keys and values are `data_value`s. + +|`ENTRY_VIEW = map_entry_view(KEY, name=MAP_NAME)` +|`ENTRY_VIEW` is a dictionary with the following fields: + +* `Key`: `data_value` +* `Value` `data_value` +* `Cost`: `integer` +* `Hits`: `integer` +* `Creation Time`: `integer` (UNIX time in milliseconds) +* `Expiration Time`: `integer` (UNIX time in milliseconds) +* `Last Access Time`: `integer` (UNIX time in milliseconds) +* `Last Stored Time`: `integer` (UNIX time in milliseconds) +* `Last Update Time`: `integer` (UNIX time in milliseconds) +* `Version`: `integer` +* `TTL`: `integer` (milliseconds) +* `Max Idle`: `integer` (milliseconds) + +|`VALUE = map_get(KEY, name=MAP_NAME)` +|Returns the `data_value` for the given key. + +|`KEYS_LIST = map_key_set(name=MAP_NAME)` +|Returns a list of keys as `data_value`. + +|`map_lock(KEY, name=MAP_NAME, ttl=NANOSECONDS)` +|Locks a key in the Map. + +|`map_load_all(name=MAP_NAME, replace=BOOL)` or map_load_all(KEY1, ..., name=MAP_NAME, replace=BOOL)` +|Loads the given keys or all keys in the MapStore if no key was specifed. + +|`VALUE = map_remove(KEY, name=MAP_NAME)` +|Deletes the given key from the Map and returns the corresponding value. + +|`map_set(KEY, VALUE, name=MAP_NAME)` +|Sets the given value for the given key. + +|`SIZE = map_size(name=MAP_NAME)` +|Returns the size of the Map. + +|`BOOL = map_try_lock(KEY, name=MAP_NAME, ttl=NANOSECONDS)` +|Attempts to lock the entry for the given key. Returns `True` if successful. + +|`map_unlock(KEY, name=MAP_NAME)` +|Unlocks the entry for the given key. + +|`VALUES_LIST = map_values(name=MAP_NAME)` +|Returns the values in the Map as a list. + +|`NANOSECONDS = now()` +|Returns the current time in nanoseconds. + +|`LIST_OF_SERVICE_OBJECT_PAIRS = object_list()` or `OBJECT = object_list(SERVICE)` +|Returns the data structure objects in the + +|`sleep(NANOSECONDS)` +|Sleeps for the given nanoseconds. For example, to sleep for 10 seconds: `sleep(10*second)`. + +|=== + +Usage: + +[source,bash] +---- +clc script [path/location] [flags] -- [parameter, ...] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`parameter` +|Optional +|Arguments to be passed to an advanced script. The arguments can be retrieved using the `argv()` function. +| + +|`--echo` +|Optional +|Print the executed command. Not used in advanced script. +|`false` + +|`--ignore-errors` +|Optional +|Ignore errors during script execution +|`false` + +|`--debug` +|Optional +|Enable the debug mode for advanced scripts. +|`false` + +|=== + +.Global parameters +[%collapsible] +==== +include::partial$global-parameters.adoc[] +==== diff --git a/docs/modules/ROOT/pages/clc-serializer-generator.adoc b/docs/modules/ROOT/pages/clc-serializer-generator.adoc new file mode 100644 index 0000000..a860070 --- /dev/null +++ b/docs/modules/ROOT/pages/clc-serializer-generator.adoc @@ -0,0 +1,142 @@ += clc serializer generator (Beta) + +Serializer commands are a group of serializer generator operations. + +For further information, see the link:https://docs.hazelcast.com/hazelcast/latest/serialization/compact-serialization[Compact Serialization] topic. + +Usage: + +[source,bash] +---- +clc serializer [command] [flags] +---- + +== Commands + +* <> + +== clc serializer generate + +Generates compact serialization code from the given schema for the target language. For further information, see the link:https://docs.hazelcast.com/hazelcast/latest/serialization/compact-serialization#implementing-compactserializer[Compact Serialization] section. + + + +Usage: + +[source, bash] +---- +clc serializer generate [schema] [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`output-dir`, `-o` +|Optional +|Output directory for the serialization files. +|Current working directory. + +|`language`, `-l` +|Required +|Programming language for which the serializer was created. +| +|=== + +Example: + +[source,bash] +---- +clc serializer generate my-schema.yaml --language java --output-dir my-dir +---- + +=== Schema Creation + +A schema allows you to: + +* Describe the content of a compact class using supported field types +* Import other schema +* Specify namespaces for schema files and reference other namespaces +* Define cyclic references between classes +* Reference classes that are not present in the given schemas + +A schema is written in YAML. The schema format is as follows: + +[source,yaml] +---- +namespace: +# note that other schema files can be imported with relative path to this YAML file +imports: + - someOtherSchema.yaml +# All objects in this file will share the same namespace. +classes: + - name: + fields: + - name: + type: + external: bool # to mark external types (external to this YAML file) +---- + +==== namespace + +Used for logical grouping of classes. Typically, there is a schema file for each namespace. Namespace is optional. If not provided, the classes are generated at the global namespace. When using the namespace, you must provide the language-specific best practice. The tool uses the namespace, if provided, while generating code. + +==== imports + +Used to import other schema files. The type definitions in the imported YAML schemas can be used within the current YAML schema. Any cyclic imports are checked and handled. An import is restricted to a single filename. The tool assumes that all imported YAML files are in the same directory as the schema file that imports them. + +==== classes + +Used to define classes in the schema. + +name: identifies the class being defined by name. + +fields: specifies the fields used by the class, as follows: + +* name: Identifies the field by name +* type: Identifies the field type. If referring to another class, use namespace.classname to identify it; if the class is defined in the same schema YAML file, you can use classname to identify it. You can specify only one type from the following: +** `boolean` +** `boolean[]` +** `int8` +** `int8[]` +** `int16` +** `int16[]` +** `int32` +** `int32[]` +** `int64` +** `int64[]` +** `float32` +** `float32[]` +** `float64` +** `float64[]` +** `string` +** `string[]` +** `date` +** `date[]` +** `time` +** `time[]` +** `timestamp` +** `timestamp[]` +** `timestampWithTimezone` +** `timestampWithTimezone[]` +** `nullableBoolean` +** `nullableBoolean[]` +** `nullableInt8` +** `nullableInt8[]` +** `nullableInt16` +** `nullableInt16[]` +** `nullableInt32` +** `nullableInt32[]` +** `nullableInt64` +** `nullableInt64[]` +** `nullableFloat32` +** `nullableFloat32[]` +** `nullableFloat64` +** `nullableFloat64[]` +** `` +* external: identifies the type as a user-defined implementation. +** The tool does not check whether external fields are imported and available. You are responsible for managing external types; they are not generated by the tool. +** Also identifies mixed use cases where the serializer of an external field is a user-written custom serializer, the zero-config serializer for Java and .NET, or was previously generated by the tool. +** In generated code, external types are imported according to the field `type`. For this reason, in languages such as Java, you must use the full package name with the class; for example, `type: com.app1.dto.Address`. \ No newline at end of file diff --git a/docs/modules/ROOT/pages/clc-serializer.adoc b/docs/modules/ROOT/pages/clc-serializer.adoc new file mode 100644 index 0000000..dbb47c2 --- /dev/null +++ b/docs/modules/ROOT/pages/clc-serializer.adoc @@ -0,0 +1,143 @@ += clc serializer generator (Beta) + +Serializer commands generate serializers for various serialization systems. + +Usage: + +[source,bash] +---- +clc serializer [command] [flags] +---- + +== Commands + +* <> + +== clc serializer generate + +Generates compact serialization code from the given schema for the target language. See https://docs.hazelcast.com/hazelcast/latest/serialization/compact-serialization#implementing-compactserializer[Compact Serialization] documentation for more information. + +Usage: + +[source, bash] +---- +clc serializer generate [schema] [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`output-dir`, `-o` +|Optional +|Output directory for the serialization files. +|Current working directory. + +|`language`, `-l` +|Required +|Programming language that the serializer created for. +| + +|`--yes` +|Optional +|Skip confirming the destroy operation. +|`false` + +|=== + +Example: + +[source,bash] +---- +clc serializer generate my-schema.yaml --language java --output-dir my-dir +---- + +=== Schema Creation + +A schema allows you to: + +* Describe the contents of a compact class using supported field types. +* Import other schema. +* Specify a namespaces for schema files and reference other namespaces. +* Define cyclic references between classes. +* Reference classes that are not present in the given schemas. + +A schema is written in YAML. Schema format is given below: + +[source,yaml] +---- +namespace: +# note that other schema files can be imported with relative path to this yaml file +imports: + - some-other-schema.yaml +# All objects in this file will share the same namespace. +classes: + - name: + fields: + - name: + type: + external: bool # to mark external types (external to this yaml file) +---- + +==== namespace + +Used for logical grouping of classes. Typically, for every namespace, you will have a schema file. Namespace is optional. If not provided, the classes will be generated at global namespace (no namespace). The user should provide the language specific best practice when using the namespace. The tool will use the namespace while generating code if provided. + +==== imports + +Used to import other schema files. The type definitions in the imported yaml schemas can be used within this yaml file. Cyclic imports will be checked and handled properly. For this version of the tool, an import can only be a single file name and the tool will assume all yaml files imported will be in the same directory as the importing schema file. + +==== classes + +Used to define classes in the schema. + +* name: Name of the class +* fields: Field specification of the class +** name: Name of the field +** type: Type of the field. Normally you should refer to another class as namespace.classname. You can use a class without namespace when the class is defined in the same schema yaml file. type can be one of the following: +*** `boolean` +*** `boolean[]` +*** `int8` +*** `int8[]` +*** `int16` +*** `int16[]` +*** `int32` +*** `int32[]` +*** `int64` +*** `int64[]` +*** `float32` +*** `float32[]` +*** `float64` +*** `float64[]` +*** `string` +*** `string[]` +*** `date` +*** `date[]` +*** `time` +*** `time[]` +*** `timestamp` +*** `timestamp[]` +*** `timestampWithTimezone` +*** `timestampWithTimezone[]` +*** `nullableBoolean` +*** `nullableBoolean[]` +*** `nullableInt8` +*** `nullableInt8[]` +*** `nullableInt16` +*** `nullableInt16[]` +*** `nullableInt32` +*** `nullableInt32[]` +*** `nullableInt64` +*** `nullableInt64[]` +*** `nullableFloat32` +*** `nullableFloat32[]` +*** `nullableFloat64` +*** `nullableFloat64[]` +*** `` +** external: +*** Used to mark if the type is external. If a field is external, the tool will not check if it is imported and available. External types are managed by the user and not generated by the tool. +*** The serializer of an external field can be a custom serializer which is handwritten, the zero-config serializer for Java and .NET, or previously genereated using the tool. This flag will enable such mixed use cases. +*** In generated code, external types are imported exactly what as the "type" of the field, hence for languages like Java the user should enter the full package name together with the class. E.g. type: `com.app1.dto.Address`. + diff --git a/docs/modules/ROOT/pages/clc-set.adoc b/docs/modules/ROOT/pages/clc-set.adoc new file mode 100644 index 0000000..cc803f6 --- /dev/null +++ b/docs/modules/ROOT/pages/clc-set.adoc @@ -0,0 +1,225 @@ += clc set + +Set commands are a group of set operations. + +Usage: + +[source,bash] +---- +clc set [command] [flags] +---- + +== Commands + +* <> +* <> +* <> +* <> +* <> +* <> + +== clc set clear + +Deletes all entries of a set. + +Usage: + +[source,bash] +---- +clc set clear [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--name`, `-n` +|Optional +|Name of the set. +|`default` + +|`--yes` +|Optional +|Skip confirming the destroy operation. +|`false` + +|=== + +Example: + +[source,bash] +---- +clc set clear --name my-set +---- + +== clc set add + +Adds values to the given set. + +Usage: + +[source,bash] +---- +clc set add [values] [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--name`, `-n` +|Optional +|Name of the set. +|`default` + +|`--value-type`, `-v` +|Optional +|Data type of the value. One of: `string`, `bool`, `json`, `i8`, `i16`, `i32`, `i64`, `f32`, `f64` +|string + +|=== + +Example: + +[source,bash] +---- +clc set add 1 2 3 4 --name my-set +---- + +== clc set get-all + +List all values in the given set. + +Usage: + +[source,bash] +---- +clc set get-all [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--name`, `-n` +|Optional +|Name of the set. +|`default` + +|=== + +Example: + +[source,bash] +---- +clc set get-all --name my-set +---- + +== clc set remove + +Removes values from the given set. + +Usage: + +[source,bash] +---- +clc set remove [values] [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--name`, `-n` +|Optional +|Name of the set. +|`default` + +|`--value-type`, `-v` +|Optional +|Data type of the value. One of: `string`, `bool`, `json`, `i8`, `i16`, `i32`, `i64`, `f32`, `f64` +|string + +|=== + +Example: + +[source,bash] +---- +clc set remove 1 2 3 4 --name my-set +---- + +== clc set size + +Returns the size of the given set. + +Usage: + +[source,bash] +---- +clc set size [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--name`, `-n` +|Optional +|Name of the set. +|`default` + +|=== + +Example: + +[source,bash] +---- +clc set size --name my-set +---- + +== clc set destroy + +Destroys a set. This command will delete the set and the data in it will not be available anymore. + +Usage: + +[source,bash] +---- +clc set destroy [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--name`, `-n` +|Optional +|Name of the set. +|`default` + +|`--yes` +|Optional +|Skip confirming the destroy operation. +|`false` + +|=== + +Example: + +[source,bash] +---- +clc set destroy --name my-set +---- \ No newline at end of file diff --git a/docs/modules/ROOT/pages/clc-snapshot.adoc b/docs/modules/ROOT/pages/clc-snapshot.adoc new file mode 100644 index 0000000..e76bb74 --- /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. This feature requires Hazelcast {hazelcast-cloud} 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-sql.adoc b/docs/modules/ROOT/pages/clc-sql.adoc new file mode 100644 index 0000000..287ce0f --- /dev/null +++ b/docs/modules/ROOT/pages/clc-sql.adoc @@ -0,0 +1,74 @@ += clc sql +:description: Executes a SQL statement. + +{description} + +Usage: + +[source,bash] +---- +clc sql [query] [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--format`, `-f` +|Optional +|Output format. Supported formats: + +- `csv` +- `delimited` +- `json` +- `table` +|`delimited` in non-interactive mode, `table` in interactive mode. + +|=== + +.Global parameters +[%collapsible] +==== +include::partial$global-parameters.adoc[] +==== + +== Querying with SQL using the Hazelcast CLC + +You can run SQL queries in both interactive and non-interactive mode of the Hazelcast CLC. + +[tabs] +==== +Non-Interactive mode:: ++ +-- +[source,bash] +---- +$ clc sql -c prod "SELECT * from cities" +1 United Kingdom London 9540576 +4 United States Los Angeles 3985520 +5 Turkey Ankara 5309690 +7 Brazil Sao Paulo 22429800 +---- +-- +Interactive mode:: ++ +-- +[source,bash] +---- +clc +> SELECT * FROM cities +--------------------------------------------------------------------------------- + __key | country | city | population +--------------------------------------------------------------------------------- + 1 | United Kingdom | London | 9540576 + 4 | United States | Los Angeles | 3985520 + 5 | Turkey | Ankara | 5309690 + 7 | Brazil | Sao Paulo | 22429800 +--------------------------------------------------------------------------------- +---- +-- +==== + + diff --git a/docs/modules/ROOT/pages/clc-template.adoc b/docs/modules/ROOT/pages/clc-template.adoc new file mode 100644 index 0000000..1033dbf --- /dev/null +++ b/docs/modules/ROOT/pages/clc-template.adoc @@ -0,0 +1,50 @@ += clc template + +Template commands. + +Usage: + +[source,bash] +---- +clc template [command] [flags] +---- + +== Commands + +* <> + +== clc template list + +Lists templates that can be used while creating projects. + +Usage: + +[source,bash] +---- +clc template list [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--source` +|Optional +|The Github organization/user account to search for the templates. +|hazelcast-templates + +|--local +|false +|When enabled, it only lists templates that exist in `/templates`. +| + +|--force +|false +|Templates are fetched and cached in a local data store. iIf you want to force CLC to fetch the latest templates from the remote repositories, you should set this parameter. +| + +|=== + +WARNING: --force and --local parameters cannot be set at the same time, because they serve for different purposes. --force is used for templates in remote repositories, while --local is used to list templates in local environment. diff --git a/docs/modules/ROOT/pages/clc-topic.adoc b/docs/modules/ROOT/pages/clc-topic.adoc new file mode 100644 index 0000000..36b9a6b --- /dev/null +++ b/docs/modules/ROOT/pages/clc-topic.adoc @@ -0,0 +1,122 @@ += clc topic + +Topic commands are a group of topic operations. + +Usage: + +[source,bash] +---- +clc topic [command] [flags] +---- + +== Commands + +* <> +* <> +* <> + +== clc topic publish + +Publish new messages for a topic. + +Usage: + +[source,bash] +---- +clc topic publish [values] [flags] +---- +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--name`, `-n` +|Optional +|Name of the topic. +|`default` + +|`values` +|Required +|Values to publish. +|N/A + +|`--value-type`, `-v` +|Optional +|Data type of the values. One of: `string`, `bool`, `json`, `i8`, `i16`, `i32`, `i64`, `f32`, `f64` +|string + +|=== + +Example: + +[source,bash] +---- +clc topic publish -v string string1 string2 --name topic1 +---- + +== clc topic subscribe + +Subscribe to a topic for new messages. + +Usage: + +[source,bash] +---- +clc topic subscribe [flags] +---- +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--name`, `-n` +|Optional +|Name of the topic. +|`default` + + +|=== +Example: + +[source,bash] +---- +clc topic subscribe --name topic1 +---- + + +== clc topic destroy + +This command will delete the topic and the data in it will not be available anymore. + +Usage: + +[source,bash] +---- +clc topic destroy [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--name`, `-n` +|Optional +|Name of the topic. +|`default` + +|`--yes` +|Optional +|Skip confirming the destroy operation. +|`false` + +|=== +Example: + +[source,bash] +---- +clc topic destroy --name topic1 --yes +---- \ No newline at end of file diff --git a/docs/modules/ROOT/pages/clc-version.adoc b/docs/modules/ROOT/pages/clc-version.adoc new file mode 100644 index 0000000..fe72571 --- /dev/null +++ b/docs/modules/ROOT/pages/clc-version.adoc @@ -0,0 +1,37 @@ += clc version +:description: Prints the version information about the Hazelcast CLC. + +{description} + +Without any flags, only the version of the Hazelcast CLC is printed. + +With the `--verbose` flag, the following are printed: + +* The Hazelcast CLC version +* Latest Git commit hash to the Hazelcast CLC +* Hazelcast Go client version +* Go Version + +Usage: + +[source,bash] +---- +clc version [flags] +---- + +Example: + +[source,bash] +---- +clc version --verbose +---- + +Example output: + +[source,bash] +---- +Hazelcast CLC: 5.2.0-beta3 +Latest Git Commit Hash: 1ff0a2d73326a266fcc829020cd77296ca9126f5 +Hazelcast Go Client Version: 1.4.0 +Go Version: go1.19.3 +---- diff --git a/docs/modules/ROOT/pages/clc-viridian.adoc b/docs/modules/ROOT/pages/clc-viridian.adoc new file mode 100644 index 0000000..10ff22d --- /dev/null +++ b/docs/modules/ROOT/pages/clc-viridian.adoc @@ -0,0 +1,414 @@ += clc viridian + +This command group provides commands for doing various operations on Hazelcast {hazelcast-cloud}, such as creating and managing clusters. + +All commands except `viridian login` require the generation of a token using an API key and secret, which you can retrieve from the {hazelcast-cloud} console. Running `viridian login` prompts you for this information, and creates and saves the token. + +Usage: + +[source,bash] +---- +clc viridian [command] [options] +---- + +== Commands + +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> + +== clc viridian login + +Logs in to {hazelcast-cloud} using the given API key and API secret and retrieves a token. +The token is cached to be used by other commands. +If not specified, the key and the secret will be asked in a prompt. + +Alternatively, you can use the following environment variables: + +* `CLC_VIRIDIAN_API_KEY` +* `CLC_VIRIDIAN_API_SECRET` + +Usage: + +[source,bash] +---- +clc viridian login [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--api-key` +|Optional +|Sets the API key. Overrides the `CLC_VIRIDIAN_API_KEY` environment variable. If not given, an input prompt is shown. +| + +|`--api-secret` +|Optional +|Sets the API secret. Overrides the `CLC_VIRIDIAN_API_SECRET` environment variable. If not given, an input prompt is shown. +| + +|=== + +== clc viridian create-cluster + +Creates a {hazelcast-cloud} cluster. + +Make sure you authenticate to the {hazelcast-cloud} API using `viridian login` before running this command. + +Usage: + +[source,bash] +---- +clc viridian create-cluster [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--api-key` +|Optional +|Sets the API key. Overrides the `CLC_VIRIDIAN_API_KEY` environment variable. If not given, one of the existing API keys will be used. +| + +|`--name` +|Optional +|Sets the name of the created cluster. If not given, an auto-generated name will be used. +| + +|`--development` +|Optional +|Creates a development cluster. +| + +|`--prerelease` +|Optional +|Creates the cluster with a prerelease image. +| + +|=== + +== clc viridian get-cluster + +Gets the information about the given {hazelcast-cloud} cluster. + +Make sure you authenticate to the {hazelcast-cloud} API using `viridian login` before running this command. + +Usage: + +[source,bash] +---- +clc viridian get-cluster [cluster-ID/name] [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--api-key` +|Optional +|Sets the API key. Overrides the `CLC_VIRIDIAN_API_KEY` environment variable. If not given, one of the existing API keys will be used. +| + +|=== + +== clc viridian list-clusters + +Lists all {hazelcast-cloud} clusters for the logged in API key. + +Make sure you authenticate to the {hazelcast-cloud} API using `viridian login` before running this command. + +Usage: + +[source,bash] +---- +clc viridian list-clusters [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--api-key` +|Optional +|Sets the API key. Overrides the `CLC_VIRIDIAN_API_KEY` environment variable. If not given, one of the existing API keys will be used. +| + +|=== + +== clc viridian stop-cluster + +Stops the given {hazelcast-cloud} cluster. + +Make sure you authenticate to the {hazelcast-cloud} API using `viridian login` before running this command. + +Usage: + +[source,bash] +---- +clc viridian stop-cluster [cluster-ID/name] [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--api-key` +|Optional +|Sets the API key. Overrides the `CLC_VIRIDIAN_API_KEY` environment variable. If not given, one of the existing API keys will be used. +| + +|=== + +== clc viridian resume-cluster + +Resumes the given {hazelcast-cloud} cluster. + +Make sure you authenticate to the {hazelcast-cloud} API using `viridian login` before running this command. + +Usage: + +[source,bash] +---- +clc viridian resume-cluster [cluster-ID/name] [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--api-key` +|Optional +|Sets the API key. Overrides the `CLC_VIRIDIAN_API_KEY` environment variable. If not given, one of the existing API keys will be used. +| + +|=== + +== clc viridian delete-cluster + +Deletes the given {hazelcast-cloud} cluster. All data in the cluster is deleted irreversibly. + +Make sure you authenticate to the {hazelcast-cloud} API using `viridian login` before running this command. + +Usage: + +[source,bash] +---- +clc viridian delete-cluster [cluster-ID/name] [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--api-key` +|Optional +|Sets the API key. Overrides the `CLC_VIRIDIAN_API_KEY` environment variable. If not given, one of the existing API keys will be used. +| + +|`--yes` +|Optional +|Skips confirming the delete operation. +| + +|=== + +== clc viridian download-logs + +Downloads the logs of the given {hazelcast-cloud} cluster. + +Make sure you authenticate to the {hazelcast-cloud} API using `viridian login` before running this command. + +Usage: + +[source,bash] +---- +clc viridian download-logs [cluster-ID/name] [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--api-key` +|Optional +|Sets the API key. Overrides the `CLC_VIRIDIAN_API_KEY` environment variable. If not given, one of the existing API keys will be used. +| + +|`--output-dir` `-o` +|Optional +|Output directory for the log files, if not given current directory is used. +| + +|=== + +== clc viridian stream-logs + +Outputs the logs of the given {hazelcast-cloud} cluster as a stream. + +Make sure you authenticate to the {hazelcast-cloud} API using `viridian login` before running this command. + +The log format may be one of: + +* minimal: Only the log message +* basic: Time, level and the log message +* detailed: Time, level, thread, logger and the log message +* free form template, see: https://pkg.go.dev/text/template for the format. +You can use the following placeholders: `msg`, `level`, `time`, `thread` and `logger`. +Usage: + +[source,bash] +---- +clc viridian stream-logs [cluster-ID/name] [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--api-key` +|Optional +|Sets the API key. Overrides the `CLC_VIRIDIAN_API_KEY` environment variable. If not given, one of the existing API keys will be used. +| + +|`--log-format` +|Optional +|Format of log lines. Either a predefined or free form format. +|`basic` + +|=== + +== clc viridian import-config + +Imports the connection configuration of the given {hazelcast-cloud} cluster. + +Make sure you authenticate to the {hazelcast-cloud} API using `viridian login` before running this command. + +Usage: + +[source,bash] +---- +clc import-config [cluster-name/cluster-ID] [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--api-key` +|Optional +|Sets the API key. Overrides the `CLC_VIRIDIAN_API_KEY` environment variable. If not given, one of the existing API keys will be used. +| +|=== + + +== clc viridian list-custom-classes + +Lists all custom classes in the {hazelcast-cloud} cluster. + +Make sure you authenticate to the {hazelcast-cloud} API using `viridian login` before running this command. + +Usage: + +[source,bash] +---- +clc viridian list-custom-classes [cluster-name/cluster-ID] [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--verbose` +|Optional +|Prints additional column `Temporary Custom Classes ID` +| + +|=== + +== clc viridian upload-custom-class + +Uploads a custom class to the {hazelcast-cloud} cluster. + +Make sure you authenticate to the {hazelcast-cloud} API using `viridian login` before running this command. + +Usage: + +[source,bash] +---- +clc viridian upload-custom-class [cluster-name/cluster-ID] [file-name] [flags] +---- + +== clc viridian download-custom-class + +Downloads a custom class from the {hazelcast-cloud} cluster. + +Make sure you authenticate to the {hazelcast-cloud} API using `viridian login` before running this command. + +Usage: + +[source,bash] +---- +clc viridian download-custom-class [cluster-name/cluster-ID] [file-name/artifact-ID] [flags] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`--output-path` +|Optional +|Output path for the downloaded artifact. The base directory of the path is created recursively if it doesn’t exist. +| + +|=== + +== clc viridian delete-custom-class + +Deletes a custom class from the {hazelcast-cloud} cluster. + +Make sure you authenticate to the {hazelcast-cloud} API using `viridian login` before running this command. + +Usage: + +[source,bash] +---- +clc viridian delete-custom-class [cluster-name/cluster-ID] [file-name/artifact-ID] [flags] +---- \ No newline at end of file diff --git a/docs/modules/ROOT/pages/clc.adoc b/docs/modules/ROOT/pages/clc.adoc new file mode 100644 index 0000000..d48a14d --- /dev/null +++ b/docs/modules/ROOT/pages/clc.adoc @@ -0,0 +1,127 @@ += clc +:description: The interactive shell of the Hazelcast CLC allows you to run SQL queries and CLC commands. + +Usage: + +[source,bash] +---- +clc +---- + +Starts the interactive shell for running SQL queries and Hazelcast CLC commands. + +The shell defaults to running SQL queries, which you can execute from a command prompt and get the result. The query should end with a semicolon: + +[source,clc] +---- +> select * from cities; +--------------------------------------------------------------------------------- + __key | country | city | population +--------------------------------------------------------------------------------- + 1 | United Kingdom | London | 9540576 + 5 | Turkey | Ankara | 5309690 + 4 | United States | Los Angeles | 3985520 +--------------------------------------------------------------------------------- +---- + +In order to run Hazelcast CLC commands, prefix them with a backslash (`\`): +[source,clc] +---- +> \object list --show-hidden +------------------------------------------------- + Service Name | Object Name +------------------------------------------------- + executor | hot-backup-executor + flakeidgenerator | __jet.ids + map | cities + replicatedmap | __sql.catalog +------------------------------------------------- +---- + +You can enter multiline commands by ending all lines except the last line with a backslash (`\`): +[source,clc] +---- +> \object list \ + ... --show-hidden +------------------------------------------------- + Service Name | Object Name +------------------------------------------------- + executor | hot-backup-executor + flakeidgenerator | __jet.ids + map | cities + replicatedmap | __sql.catalog +------------------------------------------------- +---- + +== Shortcut Commands + +* <> +* <> +* <> +* <> + +== exit +Exits the shell. + +Usage: + +[source,bash] +---- +exit +---- + +== help +Display help for CLC commands + +Usage: + +[source,bash] +---- +help +---- + +== di +Lists indexes. If you provide a mapping, it lists indexes to that specific mapping, otherwise it lists all the indexes. + +Usage: + +[source,bash] +---- +di [MAPPING] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`MAPPING` +|Optional +|Name of the mapping. +| + +|=== + +== dm(+) +If you don't provide the `MAPPING` parameter, it lists mappings. If you add `+` postfix, it describes the given mapping, otherwise it displays information about it. + +Usage: + +[source,bash] +---- +dm(+) [MAPPING] +---- + +Parameters: + +[cols="1m,1a,2a,1a"] +|=== +|Parameter|Required|Description|Default + +|`MAPPING` +|Optional +|Name of the mapping. +| + +|==== \ No newline at end of file diff --git a/docs/modules/ROOT/pages/config-wizard.adoc b/docs/modules/ROOT/pages/config-wizard.adoc new file mode 100644 index 0000000..12c766d --- /dev/null +++ b/docs/modules/ROOT/pages/config-wizard.adoc @@ -0,0 +1,101 @@ +== CLC Configuration Wizard + +:description: Hazelcast CLC provides a configuration wizard in interactive mode, which allows you to easily manage multiple cluster configurations. The configuration wizard runs when a client connection needs and asks for a single cluster configuration. + +:page-product: cloud + +{description} + +If you try to run an operation that requires a client connection before you have added any configuration, you are prompted to enter a configuration source with the target name. + +If you have already added one or more configurations to the Hazelcast CLC home directory, you are prompted to select one to create a client connection. + +TIP: If you have a configuration named `default`, a configuration YAML exists next to the executable or in the current working directory. CLC uses this instead of running configuration wizard. + +== Before you Begin + +You need the following: + +- Hazelcast CLC +- A {hazelcast-cloud} cluster + +== Connecting to {hazelcast-cloud} + +. Start the Hazelcast CLC in interactive mode. ++ +```bash +$ clc +``` ++ + +. Execute an operation that requires a client connection to cluster. ++ +```bash +> SHOW MAPPINGS; +``` ++ + +. CLC will scan the configurations and list them if there is any. If there is no configuration found, it will prompt an +input screen for you to import a new configuration. ++ +```bash +There is no configuration detected. You can register a new configuration to conn +You can connect to {hazelcast-cloud} cluster using curl request from `Dashboard -> Connec +Paste the link to source field below and it will download the config and TLS fil + +Configuration Name: default +Source: + +[ Submit ] +``` ++ + +. Specify the name of the configuration by chancing the configuration name field. The default value is `default` +If there is any default configuration, CLC will use it automatically. ++ +```bash +Configuration Name: default +``` ++ + +. Copy the Go Client sample url from {hazelcast-cloud} console. + +. Paste the Go client sample CURL request link to `Source:` in this screen. ++ +```bash +Source: curl https://api.viridian.hazelcast.com/client_samples/download/... +``` ++ +. Press `[ Submit ]` and it will automatically connect to your Viridian Cloud cluster. Notice that if you didn't specify the configuration name or leave it as default, it will automatically connect to this client unless you specify it with `--config` flag. + +== Multiple Configurations + +If you have multiple configurations in the CLC home directory, the configuration wizard will prompt you the list of +configuration to select. You can select by using your arrow keys. + +. Start the Hazelcast CLC in interactive mode. ++ +```bash +$ clc +``` ++ + +. Execute an operation that requires a client connection to cluster. ++ +```bash +> SHOW MAPPINGS; +``` ++ + +. CLC will scan the configurations and list them if there is any. ++ +```bash +1. viridian-prod-config +2. viridian-dev-config +3. remote-cluster-config +``` ++ + +. Move using arrow keys and press Enter for the configuration you want to use. + +NOTE: The Hazelcast CLC connects to the cluster on demand, that is when you issue a command that requires the connection, such as running a SQL query. \ No newline at end of file diff --git a/docs/modules/ROOT/pages/configuration-format.adoc b/docs/modules/ROOT/pages/configuration-format.adoc new file mode 100644 index 0000000..c57fb3c --- /dev/null +++ b/docs/modules/ROOT/pages/configuration-format.adoc @@ -0,0 +1,94 @@ += Configuration Format +:description: The Hazelcast CLC recognizes the following items in the configuration file. + +{description} + +* The configuration is in YAML format. +* It has the `cluster` and `ssl` sections. +* A typical configuration file looks as follows: + +```yaml +cluster: + discovery-token: "XXXXXXXDOr9CWUNhzoyXXXXXXwK9nfRV8Ro4XUc6XXXXX" + name: "pr-abcd123" +ssl: + ca-path: "ca.pem" + cert-path: "cert.pem" + key-path: "key.pem" + key-password: "766391XXXXX" +``` + +== cluster section + +[cols="1a,2a,1a"] +|=== +|Key|Description|Default + +|address +|Address of one of the members in the cluster. +|`localhost:5701` + +|name +|Cluster name. +|`dev` + +|discovery-token +|Viridian discovery token. +| + +|api-base +|Viridian API base URL or name. +| + +|viridian-id +|Viridian cluster ID. +| + +|user +|User name. +| + +|password +|Password. +| + +|=== + +== ssl section + +[cols="1a,2a,1a"] +|=== +|Key|Description|Default + +|enabled +|Set to `true` if SSL is enableed for this cluster. Automatically set to `true` if `cluster.discovery-token` is defined. +|`false` + +|ca-path +|CA path. +| + +|cert-path +|Certificate path. +| + +|key-path +|Key certificate path. +| + +|key-password +|Key certificate password. +| + +|server +|Server name if different from the host name in the certificate. +| + +|skip-verify +|Disables certificate verification. Never use in a production environment. +|`false` + +|=== + + + diff --git a/docs/modules/ROOT/pages/configuration.adoc b/docs/modules/ROOT/pages/configuration.adoc new file mode 100644 index 0000000..2077147 --- /dev/null +++ b/docs/modules/ROOT/pages/configuration.adoc @@ -0,0 +1,51 @@ += Configuration for Hazelcast CLC +:description: Hazelcast CLC allows you to configure settings for cluster connection credentials, using a configuration file. Some of those settings may be overriden using global command-line parameters. + +{description} + +CLC has a simple YAML configuration, usually named `config.yaml`. +This file can exist anywhere in the file system, and can be used with the `--config` (or `-c`) flag: +[source, bash] +---- +clc -c test/config.yaml +---- + +`configs` directory in `$CLC_HOME` is special, it contains all the configurations known to CLC. You can use the `clc home` command in order to see where `$CLC_HOME` is: +[source, bash] +---- +clc home +/home/me/.local/share/clc +---- + +Known configurations can be directly specified by their names, instead of the full path. +`clc config list` command lists the configurations known to CLC: +[source, bash] +---- +# List configurations +$ clc config list +default +pr-3066 + +# Start CLC shell with configuration named pr-3066 +$ clc -c pr-3066 +---- + +If no configuration is specified, the `default` configuration is used. +The name of the default configuration may be overriden using the `CLC_CONFIG` environment variable. + +If there's only a single named configuration, then it is used if the configuration is not specified with `-c`/`--config`. + +== CLC Configuration with Command-Line Parameters + +Command-line parameters are for overriding some configuration settings in the configuration file, such as the log settings. + +You can override the values in the configuration file by providing the following command-line parameters to any `clc` command: + +include::partial$global-parameters.adoc[] + +== Related Resources + +- xref:connect-to-viridian.adoc[Connecting to {hazelcast-cloud} with Hazelcast CLC]. + +- xref:connect-to-platform.adoc[Connecting to Hazelcast Platform with Hazelcast CLC]. + diff --git a/docs/modules/ROOT/pages/connect-to-platform.adoc b/docs/modules/ROOT/pages/connect-to-platform.adoc new file mode 100644 index 0000000..92a9cf0 --- /dev/null +++ b/docs/modules/ROOT/pages/connect-to-platform.adoc @@ -0,0 +1,148 @@ += Connecting to Hazelcast Platform with Hazelcast CLC +:description: To use the Hazelcast CLC with Hazelcast Platform, you need to configure it with the correct connection credentials. +:page-product: platform + +{description} + +The configuration examples in this topic use a xref:configuration.adoc[configuration file]. + +== Before you Begin + +You need the following: + +- Hazelcast CLC +- A Hazelcast Platform cluster +- Your cluster's connection credentials: + +** *Cluster name:* To find your cluster name, see xref:hazelcast:clusters:creating-clusters.adoc[`cluster-name` configuration]. +** *IP addresses:* If you're not connecting to a local member at localhost:5701 (default), you'll need the IP addresses of the members that you want to connect to. +** *Username and password:* If your cluster is configured with simple authentication, find the username and password in your member configuration file. See xref:hazelcast:security:simple-authentication.adoc[]. +** *Mutual TLS:* If your cluster is configured with mutual TLS authentication, you'll need your client TLS keys and certificates. See xref:hazelcast:security:tls-ssl.adoc#mutual-authentication[Mutual Authentication]. + +Hazelcast CLC supports the following TLS connections for Hazelcast Platform: + +- <> +- <> +- <> for self-signed certificates +- <> + +[[one-way]] +== Connecting to Clusters with One-Way Authentication + +. Add the following to your configuration file: ++ +[source,yaml] +---- +cluster: + name: "" + address: "" + user: "" + password: "" +ssl: + enabled: true + server: "" +---- + +. Start an interactive shell session. ++ +```bash +clc +``` + +The Hazelcast CLC starts in interactive mode at a command prompt. + +NOTE: The Hazelcast CLC connects to the cluster on demand, that is when you issue a command that requires the connection, such as running a SQL query. + +[[mutual]] +== Connecting to Clusters with Mutual TLS Authentication + +. Add the following to your configuration file: ++ +[source,yaml] +---- +cluster: + name: "" + address: "" +credentials: + user: "" + password: "" +ssl: + enabled: true + server: "" + ca-path: "//ca.pem" + cert-path: "//cert.pem" + key-path: "//key.pem" + key-password: "" +---- + +. Start an interactive shell session. ++ +```bash +clc +``` + +Hazelcast CLC starts in interactive mode at a command prompt. + +NOTE: Hazelcast CLC connects to the cluster on demand, that is when you issue a command that requires the connection, such as running a SQL query. + +[[no-verify]] +== Connecting to Clusters with Self-Signed TLS Certificates + +If your cluster members use self-signed TLS certificates, you can use the `skip-verify` setting to skip TLS verification and avoid connection errors. + +WARNING: Skipping TLS verification makes you vulnerable to man-in-the-middle attacks because any device can act as the intended cluster. + +. Add the following to your configuration file: ++ +[source,yaml] +---- +cluster: + name: "" + address: "" +credentials: + user: "" + password: "" +ssl: + enabled: true + skip-verify: true +---- + +. Start an interactive shell session. ++ +[source,bash] +---- +clc +---- + +CLC will start in the interactive mode, and you should see a command prompt. + +NOTE: Hazelcast CLC connects to the cluster on demand, that is when you issue a command that requires the connection, such as running a SQL query. + +[[none]] +== Connecting to Clusters with TLS Disabled + +. Add the following to your configuration file: ++ +[source,yaml] +---- +cluster: + name: "" + address: "" +credentials: + user: "" + password: "" +---- + +. Start an interactive shell session. ++ +```bash +clc +``` + +The Hazelcast CLC starts in the interactive mode at a command prompt. + +NOTE: Hazelcast CLC connects to the cluster on demand, that is when you issue a command that requires the connection, such as running a SQL query. + +== Next Steps + +See the xref:clc-commands.adoc[command reference] to learn what you can do with Hazelcast CLC. \ No newline at end of file diff --git a/docs/modules/ROOT/pages/connect-to-viridian.adoc b/docs/modules/ROOT/pages/connect-to-viridian.adoc new file mode 100644 index 0000000..09ae1e9 --- /dev/null +++ b/docs/modules/ROOT/pages/connect-to-viridian.adoc @@ -0,0 +1,59 @@ +== Connecting to Hazelcast {hazelcast-cloud} with Hazelcast CLC +:description: To use the Hazelcast CLC with Hazelcast {hazelcast-cloud}, you need to authenticate with {hazelcast-cloud} using your API secret and key. You can then import the configuration of the cluster that you want to connect to. No additional configuration is required. + +:page-product: cloud + +{description} + +== Before you Begin + +You need the following: + +- Hazelcast CLC +- A {hazelcast-cloud} cluster +- xref:cloud:ROOT:developer.adoc[{hazelcast-cloud} API key and secret] + +[[authenticating-with-viridian]] +== Authenticating with {hazelcast-cloud} + +To allow the Hazelcast CLC to do cluster operations, you must generate a {hazelcast-cloud} token. + +. Execute the following command to retrieve the token. ++ +```bash +clc viridian login +``` ++ +. When prompted, enter your API key and secret. If both are correct, the token is retrieved and saved. + +[[list-accessible-clusters]] +== List Accessible Clusters + +Run the following command to list the clusters linked to your {hazelcast-cloud} account: + +```bash +clc viridian list-clusters +``` + +For each cluster, the following attributes are displayed in order: Cluster ID, Cluster Name, Current Status, Hazelcast Version. + + +[[importing-the-cluster-configuration]] +== Importing the Cluster Configuration + +Import the configuration of the {hazelcast-cloud} cluster that you want to connect to. + +. Run the following command to save the cluster configuration with the name `dev`. Replace the `$CLUSTER_NAME` placeholder with the name of your cluster. ++ +```bash +clc viridian import-config $CLUSTER-NAME --name dev +``` +. Start an interactive shell session. ++ +```bash +clc -c dev +``` + +The Hazelcast CLC will start in interactive mode, and you should see a command prompt. You're ready to start managing xref:clc-viridian.adoc[{hazelcast-cloud} clusters]. + +NOTE: The Hazelcast CLC connects to the cluster on demand, that is when you issue a command that requires the connection, such as running a SQL query. \ No newline at end of file diff --git a/docs/modules/ROOT/pages/environment-variables.adoc b/docs/modules/ROOT/pages/environment-variables.adoc new file mode 100644 index 0000000..ebd2f7b --- /dev/null +++ b/docs/modules/ROOT/pages/environment-variables.adoc @@ -0,0 +1,77 @@ += Environment Variables +:description: The Hazelcast CLC recognizes the following environment variables. + +{description} + +[cols="1a,2a,1a"] +|=== +|Environment Variable|Description|Default + +|CLC_CLIENT_LABELS +|Sets the client labels. The labels must be separated by commas. This value is used in {hazelcast-cloud} and Management Center. See xref:{page-latest-supported-mc}@management-center:clusters:clients.adoc[Management Center documentation] for more information. +|`CLC,USER@HOST-TIMESTAMP` + +|CLC_CLIENT_NAME +|Set a custom client name. The client name appears in the {hazelcast-cloud} dashboard and in the cluster metrics of Management Center. +|`USER@HOST-TIMESTAMP` + +|CLC_HOME +|Overrides the CLC home directory. You can find out the current CLC home directory using xref:clc-home.adoc[clc home] command. +|`%HOMEDRIVE%:%HOMEPATH%\AppData\Roaming\Hazelcast` on Windows, `$HOME/.hazelcast` on other platforms. + +|CLC_MAX_COLS +|Sets the maximum width of a column in a table output. This is useful when the width cannot be determined. +| Terminal width. + +|CLC_SKIP_SERVER_VERSION_CHECK +|Some Hazelcast CLC features require the cluster to be of a certain version. If set to `1`, this variable disables the version check performed by the CLC. +|`0` (false) + +|CLC_VIRIDIAN_API_KEY +|Sets the {hazelcast-cloud} API key. +| + +|CLC_VIRIDIAN_API_SECRET +|Sets the {hazelcast-cloud} API secret. +| + +|CLC_CONFIG +|Sets the configuration CLC will use if `--config` flag is not specified. +| + +|HZ_PHONE_HOME_ENABLED +|Enables phone home collection for CLC usage statistics. Set 'false' to disable phone homes. +|true + +|=== + +The following environment variables are experimental and may be removed in a future version. + +[cols="1a,2a,1a"] +|=== +|Environment Variable|Description|Default + +|CLC_EXPERIMENTAL_FORMATTER +|Sets a formatter for the highlighting of SQL syntax, either: `terminal`, `terminal8`, `terminal16`, `terminal256`, or `terminal16m`. Only with the `gohxs` readline implementation. +| + +|CLC_EXPERIMENTAL_READLINE +|Sets the readline implementation, either `gohxs` or `ny`. +|`ny` for Windows, `gohxs` for other platforms. + +|CLC_EXPERIMENTAL_STYLER +|Sets a color theme for the highlighting of SQL syntax. See link:https://github.com/alecthomas/chroma/tree/master/styles[Chroma styles] for the options. Only with the `gohxs` readline implementation. +|`clc-default` + +|NO_COLOR +|Disables color output if set to `1`. +|`0` (false) + +|CLC_SKIP_UPDATE_CHECK +|Disables checking new version of CLC. +|`0` (false) + +|=== + + + diff --git a/docs/modules/ROOT/pages/get-started.adoc b/docs/modules/ROOT/pages/get-started.adoc new file mode 100644 index 0000000..958041d --- /dev/null +++ b/docs/modules/ROOT/pages/get-started.adoc @@ -0,0 +1,275 @@ += Get Started with the Hazelcast CLC +:description: In this tutorial, you'll learn how to use Hazelcast CLC commands to authenticate with Hazelcast {hazelcast-cloud} and create two production clusters. You'll connect to and switch between the clusters from the command line. Finally, you'll perform some basic operations on a cluster from both the command line and by running a script to automate the same actions. + +{description} + +== Before You Begin + +You need the following: + +- xref:install-clc.adoc[Hazelcast CLC] installed on your local machine. +- xref:cloud:ROOT:create-account.adoc[{hazelcast-cloud} account] +- xref:cloud:ROOT:developer.adoc[{hazelcast-cloud} API key and secret] + +== Step 1. Authenticating with {hazelcast-cloud} + +To allow the Hazelcast CLC to to interact with {hazelcast-cloud} clusters, you must generate a {hazelcast-cloud} token. + +. Execute the following command to retrieve the token. ++ +[source,shell] +---- +clc viridian login +---- + +. When prompted, enter your API key and secret. If both are correct, the token is retrieved and saved. + +== Step 2. Create Two Clusters on {hazelcast-cloud} + +In this step, you'll create two production clusters called Test1 and Test2 from the command line, and run some commands to check their status. + +. Execute the following command to create your first production cluster. ++ +[source,shell] +---- +clc viridian create-cluster --name Test1 +---- ++ +Wait while the cluster is created and the cluster configuration is imported into the Hazelcast CLC. + +. Create your second production cluster in the same way. + ++ +[source,shell] +---- +clc viridian create-cluster --name Test2 +---- + +. Try running the following command to check your clusters have been created: ++ +[source,shell] +---- +clc viridian list-clusters +---- ++ +The details of all clusters linked to your {hazelcast-cloud} account are returned, including the Cluster ID, Cluster Name, Current Status, Hazelcast Version. + + +[[step-2-prod-configure]] +== Step 3. Add Configuration to Connect to {hazelcast-cloud} + +To connect to each production cluster, you need to import additional cluster configuration from {hazelcast-cloud}. + +. Run the `clc config import` to update the cluster configuration on your local machine. + ++ +[source, shell] +---- +clc viridian import-config Test1 +---- + +. Run the following command to connect to your cluster using the Hazelcast CLC. + ++ +[source, shell] +---- +clc -c Test1 +---- + +. The Hazelcast CLC only connects to the cluster when necessary. Run a command that requires a connection to the cluster, such as `object list`: ++ +[source, shell] +---- +> \object list +Connected to cluster: pr- +---- ++ +As this is a new cluster, no objects are returned. ++ +NOTE: This command shows the cluster ID prefixed with `pr` instead of the cluster name. You can see the cluster ID in *Cluster Details* on the {hazelcast-cloud} console. + +. Press kbd:[Ctrl+D] or type `\exit` to shut down the Hazelcast CLC while you complete the configuration of your second production cluster. + +. Repeat steps 1 to 4 for Test2. + +[[step-3-cluster-switch]] +== Step 4. Switch Between Clusters + +Having separate local configurations for your two production clusters allows you to switch between them without leaving the command line. Make sure both clusters are running before you start. + +. Execute the following command to connect to your Test1 cluster. + ++ +[source, shell] +---- +clc -c Test1 +---- ++ +As before, the Hazelcast CLC connects to your Test1 cluster. + +. Type `\exit` to return to the command line. +. Execute the same command to connect to Test2. ++ +[source, shell] +---- +clc -c Test2 +---- +. Again, type `\exit` to return to the command line. + +[[step-4-write-data]] +== Step 5. Write Data to a Map + +Now that you've connected to both your clusters, try using the Hazelcast CLC to create a map on Test1, write some data to it, and query the data. You can use SQL to do this. + +. Start by creating a mapping to a new `currency` map. + ++ +[source,shell] +---- +clc sql -c Test1 "CREATE OR REPLACE MAPPING currency (__key INT, Code VARCHAR, Currency VARCHAR) TYPE IMap OPTIONS('keyFormat'='int', 'valueFormat'='json-flat');" +---- ++ +The SQL mapping statement does a number of things: + +** Adds column headings for currencies and codes +** Creates a SQL connection to the map +** Tells Hazelcast how to serialize and deserialize the keys and values. + +. Add some data to the map. ++ +[source,shell] +---- +clc sql -c Test1 "INSERT INTO currency VALUES (1, 'CAD','Canadian Dollar'),(2, 'INR','Indian Rupee'),(3, 'MXN', 'Mexican Peso'),(4, 'GBP', 'Pounds Sterling'),(5, 'TRY', 'Turkish Lira'),(6, 'USD', 'United States Dollar');" +---- + +. Try running some simple queries against the `currency` map. For example, this query returns all data in the map and orders it by the currency code. ++ +[source,shell] +---- +clc sql -c Test1 "SELECT * FROM currency ORDER BY Code" -f table +---- ++ +The results look like this: + ++ +[source,sql] +---- +-------------------------------------------------------------------------------- + __key | Code | Currency +-------------------------------------------------------------------------------- + 1 | CAD | Canadian Dollar + 4 | GBP | Pounds Sterling + 2 | INR | Indian Rupee + 3 | MXN | Mexican Peso + 5 | TRY | Turkish Lira + 6 | USD | United States Dollar +-------------------------------------------------------------------------------- +---- + +[[step-6-automate]] +== Step 6. Automate Actions + +When you're ready, combine the commands that you've learned about so far into a script and run them from the command line. + +The script writes the currency data to a new map called `currencydata` on a cluster and queries it. + +. Copy the following commands into a script. ++ +.myscript.sql +[source,sql] +---- + +CREATE OR REPLACE MAPPING currencydata ( + __key INT, + Code VARCHAR, + Currency VARCHAR +) TYPE IMap OPTIONS( + 'keyFormat'='int', + 'valueFormat'='json-flat' +); + +INSERT INTO currencydata VALUES + (1, 'CAD', 'Canadian Dollar'), + (2, 'INR', 'Indian Rupee'), + (3, 'MXN', 'Mexican Peso'), + (4, 'GBP', 'Pounds Sterling'), + (5, 'TRY', 'Turkish Lira'), + (6, 'USD', 'United States Dollar'); + +SELECT * FROM currencydata ORDER BY Code; +---- ++ +. Save your script as `myscript.sql`. + +[tabs] +==== +Linux and macOS:: ++ +-- +. To run the script on your Test1 cluster, execute the following command. ++ +[source,shell] +---- +cat myscript.sql | clc -c Test1 +---- ++ +. Then, to run the script on your Test2 cluster, execute the same command replacing the cluster name. ++ +[source,shell] +---- +cat myscript.sql | clc -c Test2 +---- + +-- +Windows:: ++ +-- +. To run the script on your Test1 cluster, execute the following command. ++ +[source,shell] +---- +type myscript.sql | clc -c Test1 +---- ++ +. Then, to run the script on your Test2 cluster, execute the same command replacing the cluster name. ++ +[source,shell] +---- +type myscript.sql | clc -c Test2 +---- + +-- +==== + +== Step 7. Clean Up + +To delete both test clusters from your account. + +. link:https://viridian.hazelcast.com/[Sign in to {hazelcast-cloud}] and select a test cluster. +. Click *Delete* and confirm your deletion. + +== Summary + +In this tutorial, you learned how to do the following: + +* Authenticate with {hazelcast-cloud}. +* Create a cluster and check its status. +* Connect to a {hazelcast-cloud} production cluster. +* Switch between clusters from the command line. +* Write data to a map and query the data using SQL. +* Automate commands by running a sequence of actions from a shell script. + +== Learn More + +Use these resources to continue learning: + +- xref:configuration.adoc[]. + +- xref:clc-commands.adoc[]. + +- xref:clc-sql.adoc[]. + +- xref:managing-viridian-clusters.adoc[] + +- xref:jet-job-management.adoc[] + diff --git a/docs/modules/ROOT/pages/install-clc.adoc b/docs/modules/ROOT/pages/install-clc.adoc new file mode 100644 index 0000000..5c8b5e3 --- /dev/null +++ b/docs/modules/ROOT/pages/install-clc.adoc @@ -0,0 +1,258 @@ += 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.3-snapshot/clients/clc#installing-the-hazelcast-clc + +{description} You can install the Hazelcast CLC, using one of the following: + +* Using an install script on Linux or macOS +* Windows installer +* Downloading a pre-built binary +* Building from source + +ifdef::snapshot[] +[NOTE] +Pre-release versions can only be built from source. + +== Build Pre-release from Source + +Supported OS: + +- Ubuntu 22.04 or later +- macOS 15 or later +- Windows 10 or later + +Requirements: + +- Go 1.21 or later +- Git +- For Linux and macOS, GNU Make +- Command prompt or Windows Powershell +- For Windows, https://github.com/tc-hib/go-winres[go-winres] + +To build from source, complete the following steps: + +. Clone the source from Git ++ +[source,shell] +---- +$ git clone https://github.com/hazelcast/hazelcast-commandline-client.git +---- + +. Navigate to your project ++ +[source,shell] +---- +$ cd hazelcast-commandline-client +---- + +. Build the project ++ +[source,shell] +---- +$ make +---- ++ +The ``clc``, or ``clc.exe``, binary is created in the ``build`` directory. + +. Run the project ++ +-- On Linux or macOS: ++ +[source,shell] +---- +./build/clc +---- ++ +-- On Windows: ++ +[source,shell] +---- +.\build\clc.exe +---- + +endif::[] +ifndef::snapshot[] +== Installing on macOS + +The Hazelcast CLC is supported on macOS 15 or newer versions. + +[tabs] +==== +Install Script (Intel):: ++ +. Run the following command to install CLC using the install script we provide: ++ +[source,shell,subs="attributes"] +---- +curl https://hazelcast.com/clc/install.sh | bash +---- + +Install Script (Apple Silicon):: ++ +. Run the following command to install CLC using the install script we provide: ++ +[source,shell,subs="attributes"] +---- +curl https://hazelcast.com/clc/install.sh | bash +---- + +Build from Source:: ++ +. Make sure the following are installed: +** GNU Make (check with the `make --version` command). If it is not already installed, you can install Xcode Command Line Tools Package. ++ +[source,shell] +---- +xcode-select --install +---- ++ +** https://go.dev/doc/install[Go {go-version}] or newer (check with the `go version` command) ++ +. Go to the https://github.com/hazelcast/hazelcast-commandline-client/releases[releases page], and locate the compressed source file (`v{full-version}.zip`). +. Download and unzip the file. +. Change into the `hazelcast-commandline-client-{full-version}` directory. ++ +[source,shell,subs="attributes"] +---- +cd hazelcast-commandline-client-{full-version} +---- +. Run the following command to build the Hazelcast CLC. ++ +[source,shell,subs="attributes"] +---- +CLC_VERSION=v{full-version} make +---- ++ +The `clc` binary is created in the `build` directory. +. Run the following command to start the Hazelcast CLC. ++ +[source,shell] +---- +./build/clc +---- ++ +. Optionally make `clc` available without using its full path. You can do that by moving `clc` to one of the directories in the `$PATH` environment variable. `/usr/local/bin` is a safe choice. ++ +[source,shell,subs="attributes"] +---- +sudo mv ./build/clc /usr/local/bin +---- + +==== + +== Installing on Linux + +The Hazelcast CLC runs on any recent Linux distribution. We test it on Ubuntu 22.04. + +[tabs] +==== +Install Script (AMD64):: ++ +. Run the following command to install CLC using the install script we provide: ++ +[source,shell,subs="attributes"] +---- +curl https://hazelcast.com/clc/install.sh | bash +---- + +Build from Source:: ++ +. Make sure the following are installed: +** GNU Make (check with the `make --version` command). It is installed by default on most Linux distributions. +** https://go.dev/doc/install[Go {go-version}] or newer (check with the `go version` command) ++ +. Go to the https://github.com/hazelcast/hazelcast-commandline-client/releases[releases page], and locate the source tarball (`v{full-version}.tar.gz`). +. Download and uncompress the file. ++ +[source,shell,subs="attributes"] +---- +tar xf v{full-version}.tar.gz +---- +. Change into the `hazelcast-commandline-client-{full-version}` directory. ++ +[source,shell,subs="attributes"] +---- +cd hazelcast-commandline-client-{full-version} +---- +. Run the following command to build the Hazelcast CLC. ++ +[source,shell,subs="attributes"] +---- +CLC_VERSION=v{full-version} make +---- ++ +The `clc` binary is created in the `build` directory. +. Run the following command to start the Hazelcast CLC. ++ +[source,shell] +---- +./build/clc +---- ++ +. Optionally make `clc` available without using its full path. You can do that by moving `clc` to one of the directories in the `$PATH` environment variable. `/usr/local/bin` is a safe choice. ++ +[source,shell,subs="attributes"] +---- +sudo mv ./build/clc /usr/local/bin +---- + +==== + +== Installing on Windows + +The Hazelcast CLC is supported on Windows 10 or newer versions. We provide pre-built binaries only for 64bit Intel/AMD architecture. + +[tabs] +==== +Installer:: ++ +. Go to the https://github.com/hazelcast/hazelcast-commandline-client/releases[releases page], and locate the Windows installer file (`hazelcast-clc-setup-v{full-version}.exe`). +. Download and the run the installer on your system to start the installation wizard. +. Follow the steps on the wizard; when you see the "Completing the Hazelcast CLC Setup Wizard" dialog, press kbd:[Finish] to complete the installation. +. `clc.exe` is automatically added to the `PATH` environment variable, so it can be started in the terminal without its full path. +. Start the Hazelcast CLC from the start menu or by running the following command. ++ +[source,shell] +---- +clc.exe +---- + +endif::[] +== Verifying the Hazelcast CLC Installation + +To check whether the Hazelcast CLC is installed properly, run the following command on a terminal. + +[source,shell] +---- +clc version +---- + +If installed, the Hazelcast CLC version information displays. + +== Uninstalling the Hazelcast CLC + +Choose the option that corresponds to your installation method. + +[tabs] +==== +Windows:: ++ +. Go to *Apps & Features* setting (*Start menu* -> *Windows Settings* -> *Apps*). +. Locate *Hazelcast CLC version {full-version}* under *Apps & Features* list. +. Right-click on it and select *Uninstall*. +. Press kbd:[Yes] on the uninstallation dialog. + +Install Script (Linux/macOS):: ++ +Delete the `$HOME/.hazelcast` directory. +==== + +== Next Steps + +In this section you've learnt how to install the Hazelcast CLC on the supported operating systems. +To start using the Hazelcast CLC, check the following resources: + +* See xref:get-started.adoc[Get Started] for a complete introduction to the Hazelcast CLC. +* See xref:configuration.adoc[Configuration] to configure the details of the connection between the Hazelcast CLC and a Hazelcast Platform cluster. +* See xref:clc-commands.adoc[Command Reference] for a complete list and descriptions of commands you can use with the Hazelcast CLC. diff --git a/docs/modules/ROOT/pages/jet-job-management.adoc b/docs/modules/ROOT/pages/jet-job-management.adoc new file mode 100644 index 0000000..cad6dc0 --- /dev/null +++ b/docs/modules/ROOT/pages/jet-job-management.adoc @@ -0,0 +1,198 @@ += Get Started With Hazelcast Jet Job Management +:description: In this tutorial, you'll learn the basics of how to manage stream processing pipelines using the Hazelcast CLC with Hazelcast {hazelcast-cloud}. You'll see how to connect to a cluster on {hazelcast-cloud}, and submit a sample Jet job that generates a stream of numbers. You'll also learn how to use simple commands to monitor and cancel jobs. + +{description} + +== Before You Begin + +You need the following: + +- xref:install-clc.adoc[Hazelcast CLC] installed on your local machine +- One running {hazelcast-cloud} cluster. You can create a xref:managing-viridian-clusters.adoc#creating-a-cluster-on-viridian[development cluster] using the Hazelcast CLC. +- xref:cloud:ROOT:developer.adoc[{hazelcast-cloud} API key and secret] +- JRE 8 or above. +- Gradle 8 or above. + +[[step-1-authenticating-with-viridian]] +== Step 1. Authenticating with {hazelcast-cloud} + +To allow the Hazelcast CLC to perform cluster operations, including submitting Jet jobs, you must generate a {hazelcast-cloud} token. + +. Execute the following command to retrieve the token. ++ +[source,shell] +---- +clc viridian login +---- + +. When prompted, enter your API key and secret. If both are correct, the token is retrieved and saved. + +[[step-2-list-cluster-details]] +== Step 2. List Cluster Details + +Next, check that the Hazelcast CLC can access your cluster by running the following command: + +[source,shell] +---- +clc viridian list-clusters +---- + +The details of all clusters linked to your {hazelcast-cloud} account are returned, including the Cluster ID, Cluster Name, Current Status, Hazelcast Version. + +[[step-3-dev-configure]] +== Step 3. Connect to Your Cluster + +For Hazelcast CLC to connect to your development cluster, you need to import the cluster's configuration, including its connection details. + +Run the following command to save the cluster configuration with the name `dev`. Replace the `$CLUSTER_NAME` placeholder with the name of your cluster, shown in the top-left corner of the dashboard. + +[source,shell] +---- +clc viridian import-config $CLUSTER_NAME --name dev +---- + +[[step-4-build-jet-job]] +== Step 4. Build the Jet Job + +Now you're ready to build the sample Jet job. + +. Clone the GitHub repository. ++ +[tabs] +==== +HTTPS:: ++ +-- +```bash +git clone https://github.com/hazelcast/hazelcast-commandline-client + +cd hazelcast-commandline-client/examples/platform/simple-streaming-pipeline +``` +-- +SSH:: ++ +-- +```bash +git clone git@github.com:hazelcast/hazelcast-commandline-client.git + +cd hazelcast-commandline-client/examples/platform/simple-streaming-pipeline +``` +-- +==== ++ +. Build the project with the following command: ++ + +[source,shell] +---- +gradle shadowJar +---- + +[[step-5-submit-jet-job]] +== Step 5. Submit and Monitor the Jet Job + +Submitting the sample Jet job generates a stream of numbers and creates a link:https://hashids.org/[hashid] for each number. The number and hashid pair are then saved to a Map called `my-map`, with the number as the key and hashid as the value. + +. Execute the following command to submit the Jet job: ++ +[source,shell] +---- +clc -c dev job submit build/libs/simple-streaming-pipeline-1.0-SNAPSHOT-all.jar --name simple-pipeline --wait +---- ++ +The Hazelcast CLC waits until the job starts to run. + +. Now, list the jobs in the cluster. You should see `simple-pipeline` in a `RUNNING` state. ++ +[source,shell] +---- +clc -c dev job list +---- ++ +. See how the size of `my-map` increases as entries are written to it. ++ +[tabs] +==== +Unix:: ++ +. Create a new shell script in your favorite text editor. For example: ++ +[source,shell] +---- +vi monitor.sh +---- +. Add the following: ++ +[source,shell] +---- +#! /bin/bash +while true; +do clc -c dev map size -n my-map; sleep 3; +done +---- + +. Run your script. ++ +[source,shell] +---- +./monitor.sh +---- +. Press kbd:[Ctrl + C] when you're ready to cancel the script. + +Windows:: ++ +. Create a new batch file in your favorite text editor. For example: ++ +[source,shell] +---- +notepad monitor.bat +---- +. Add the following: ++ +[source,shell] +---- +@echo off +:start +clc -c dev map size -n my-map +timeout 5 +goto start +---- +. Run the batch file. ++ +[source,shell] +---- +monitor +---- +. Press kbd:[Ctrl + C] when you're ready to cancel the script. +==== + +[[step-6-cancel-jet-job]] +== Step 6. Cancel the Jet job + +. Now, cancel the Jet job. ++ +[source,shell] +---- +clc -c dev job cancel simple-pipeline +---- + +. Run your script (from step 5) to see the size of `my-map` now. + +== Summary + +In this tutorial, you learned how to do the following: + +* Connect to a cluster on {hazelcast-cloud}. +* Build and submit a Hazelcast Jet job to create a data pipeline. +* Manage the lifecycle of a Jet job using list and cancel commands. + +== Learn More + +Use these resources to continue learning: + +- xref:configuration.adoc[]. + +- xref:clc-commands.adoc[]. + +- xref:clc-job.adoc[]. + diff --git a/docs/modules/ROOT/pages/keyboard-shortcuts.adoc b/docs/modules/ROOT/pages/keyboard-shortcuts.adoc new file mode 100644 index 0000000..e1dc762 --- /dev/null +++ b/docs/modules/ROOT/pages/keyboard-shortcuts.adoc @@ -0,0 +1,46 @@ += Keyboard Shortcuts +:description: The Hazelcast CLC supports the following keyboard shortcuts in the shell (interactive) mode. + +{description} + +[cols="1a,2a"] +|=== +|Key Binding|Description + +|kbd:[Ctrl + A] or kbd:[Home] +|Go to the beginning of the line. + +|kbd:[Ctrl + E] or kbd:[End] +|Go to the end of the line. + +|kbd:[Ctrl + P] or kbd:[Up] +|Previous command in history. + +|kbd:[Ctrl + N] or kbd:[Down] +|Next command in history. + +|kbd:[Ctrl + F] or kbd:[Right] +|Forward one character. + +|kbd:[Ctrl + B] or kbd:[Left] +|Backward one character. + +|kbd:[Ctrl + H] or kbd:[Backspace] +|Delete character before the cursor. + +|kbd:[Ctrl + W] +|Cut the word before the cursor to the clipboard. + +|kbd:[Ctrl + U] +|Cut the line before the cursor to the clipboard. + +|kbd:[Ctrl + C] +|Cancel running command. + +|kbd:[Alt + F] +|Go forward to the beginning of the next word. + +|kbd:[Alt + B] +|Go back to the beginning of the previous word. + +|=== \ No newline at end of file diff --git a/docs/modules/ROOT/pages/managing-viridian-clusters.adoc b/docs/modules/ROOT/pages/managing-viridian-clusters.adoc new file mode 100644 index 0000000..7840e3a --- /dev/null +++ b/docs/modules/ROOT/pages/managing-viridian-clusters.adoc @@ -0,0 +1,190 @@ += Managing Clusters on Hazelcast Viridian Cloud Using the Hazelcast CLC + +:description: In this tutorial, you'll learn the basics of managing clusters on Hazelcast {hazelcast-cloud} using the Hazelcast CLC. You'll see how to create, list, and delete clusters, and how to download their logs. You'll also learn how to perform pause/resume operations on the clusters using the Hazelcast CLC. + +{description} + +== Before You Begin + +You need the following: + +- xref:install-clc.adoc[Hazelcast CLC] installed on your local machine +- xref:cloud:ROOT:create-account.adoc[{hazelcast-cloud} account] +- xref:cloud:ROOT:developer.adoc[{hazelcast-cloud} API key and secret] + +[[step-1-authenticating-with-viridian]] +== Step 1. Authenticating with {hazelcast-cloud} + +To allow the Hazelcast CLC to perform cluster operations, you must generate a {hazelcast-cloud} token. + +. Execute the following command to retrieve the token. ++ +[source, bash] +---- +clc viridian login +---- + +. When prompted, enter your API key and secret. If both are correct, the output looks like this. ++ +[source, bash] +---- +Viridian token was fetched and saved. +OK +---- ++ +If an error is displayed, make sure that your API key and secret are correct and try again. + +== Step 2. Create a Cluster + +Next, execute the following command to create a development cluster called `my-cluster`. + +[source, bash] +---- +clc viridian create-cluster --name my-cluster +---- + +You should see the following output. + +[source, bash] +---- +Imported configuration: my-cluster +OK +---- + +[[step-3-list-cluster]] +== Step 3. List Your Cluster Details + +To check that the `my-cluster` is up and running, use the following command. + +[source, bash] +---- +clc viridian list-clusters +---- +The details of all clusters linked to your {hazelcast-cloud} account are returned, including the Cluster ID, Cluster Name, Current Status, Hazelcast Version. + +[source, bash, subs="attributes+"] +---- +x1qvpphn my-cluster RUNNING {full-version} +OK +---- + +== Step 4. Create Some Data on Your Cluster + +Next, write some data to a map on `my-cluster`. + +Creating your cluster using the Hazelcast CLC means that the connection details for the cluster, also called `my-cluster`, are made available to the CLC. If you created the cluster in the console, you would need to import the xref:configuration.adoc[cluster's configuration to connect to it]. + +. Let's add an entry to a map called `my-map` using a key of `my-key` and a value of `my-value`. ++ +[source, bash] +---- +clc -c my-cluster map set -n my-map my-key my-value +---- + +. Now, let's retrieve the value of the key that you just set. + ++ +[source, bash] +---- +clc -c my-cluster map get -n my-map my-key +---- ++ +You should see the following output. ++ +[source, bash] +---- +my-value +OK +---- + +== Step 5. Downloading the Cluster Logs + +You can download logs from your cluster to your local machine. Hazelcast CLC gives the cluster logs a standard name, which means that they are overwritten every time you download them to the same location. + +. Run the following command to download the logs of `my-cluster` to your working directory. ++ +[source, bash] +---- +clc viridian download-logs my-cluster +---- ++ +In this command `my-cluster` is the cluster name rather than the configuration name. ++ +. Use the following command to quickly check the location of your working directory. ++ +[source, bash] +---- +clc home +---- + +. Now, try downloading the logs to a directory of your choice by adding the `--output-dir` flag. Replace the placeholder `$DIRECTORY_PATH` with the absolute or relative path to your chosen directory. ++ +[source, bash] +---- +clc viridian download-logs my-cluster --output-dir $DIRECTORY_PATH +---- + +== Step 6. Stop/Resume Your Cluster + +To avoid charges accumulating in your account, you can xref:cloud:ROOT:stop-and-resume.adoc[stop a running cluster]. + +. Try pausing your cluster. You can use either the cluster name or ID. ++ +[source, bash] +---- +clc viridian stop-cluster my-cluster +---- + +. When you're ready to resume the cluster, run the following command. ++ +[source, bash] +---- +clc viridian resume-cluster my-cluster +---- + +== Step 7. Delete Your Cluster + +You can also xref:cloud:ROOT:deleting-a-cluster.adoc[delete an existing cluster] on {hazelcast-cloud} using its name or ID. + +. Run the following command to delete `my-cluster` replacing the placeholder `CLUSTER_ID`. See <>, for details of how to look up a cluster ID. ++ +[source, bash] +---- +clc viridian delete-cluster $CLUSTER_ID +---- ++ +A confirmation message is displayed. ++ +[source, bash] +---- +Cluster will be deleted irreversibly, proceed? (y/n) +---- + +. Type `y` to proceed with the deletion. + ++ +To avoid receiving a confirmation message on cluster deletion, add `--yes` to your command. This may be useful if you are scripting the deletion of multiple clusters. + ++ +[source, bash] +---- +clc viridian delete-cluster my-cluster --yes +---- + +== Summary + +In this tutorial, you learned how to do the following: + +* Authenticate with {hazelcast-cloud}. +* Create a cluster and check that it is running. +* Write and retrieve some data from a map. +* Download cluster logs for analysis. +* Pause, resume and delete a cluster. + +== Learn More + +Use these resources to continue learning: + +- xref:clc-viridian.adoc[]. + +- xref:configuration.adoc[]. diff --git a/docs/modules/ROOT/pages/overview.adoc b/docs/modules/ROOT/pages/overview.adoc new file mode 100644 index 0000000..73b36cf --- /dev/null +++ b/docs/modules/ROOT/pages/overview.adoc @@ -0,0 +1,108 @@ += Hazelcast Command-Line Client (CLC) +:url-github-clc: https://github.com/hazelcast/hazelcast-cloud-cli/blob/master/README.md +:description: You can use the Hazelcast Command Line Client (CLC) to connect to and interact with clusters on Hazelcast {hazelcast-cloud} and Hazelcast Platform direct from the command line or through scripts. + +{description} + +The Hazelcast CLC is a single binary with no dependencies. Within minutes of installation, you can start to perform common tasks on clusters. + +== Install + +See xref:install-clc.adoc[installation documentation]. + +== Use Cases + +Example use cases for the Hazelcast CLC. + +=== Run SQL Queries + +Run xref:clc-sql.adoc[SQL] queries against your cluster and display the output as a table or in a variety of text formats, such as JSON and CSV. + +=== Manage {hazelcast-cloud} Clusters + +xref:clc-viridian.adoc[Create and manage] {hazelcast-cloud} clusters, and the custom classes on those clusters. + +=== Create Data Pipelines + +xref:clc-job.adoc[Create and manage] data pipelines using the Hazelcast CLC. Check out the xref:hazelcast:pipelines:overview.adoc[Platform documentation] for more information about data pipelines. + +=== Access Data for Debugging + +Get xref:clc-map.adoc[direct access to map data] for quick debugging of prototypes or production applications. Easily read or query data on a cluster using SQL queries. + +=== Scripting for Automation + +Work in <> to script and execute repetitive administration, integration, or testing tasks. + +== Modes + +The Hazelcast CLC works in two modes: + +- Non-interactive +- Interactive + +You can easily switch between modes to suit the context in which you're working. + +[[non-interactive-mode]] +=== Non-Interactive Mode + +This is the default mode for the Hazelcast CLC. You need to manually enter and execute commands at the command line. This mode is useful for scripting. + +[source,bash,subs="attributes+"] +---- +clc map -c dev --name myMap set myKey myValue +---- + +[[interactive-mode]] +=== Interactive Mode + +Interactive mode presents a shell to you. This mode is useful for exploring CLC commands, and for manual tasks. + +To start the Hazelcast CLC in interactive mode, do the following: + +[source,bash,subs="attributes+"] +---- +clc +---- + +In the interactive mode, you can run SQL queries directly. Make sure to add a semicolumn (`;`) to the end of the query, otherwise it is assumed that you want to enter a multiline query. + +---- +> select * from cities; +--------------------------------------------------------------------------------- + __key | country | city | population +--------------------------------------------------------------------------------- + 1 | United Kingdom | London | 9540576 + 6 | Turkey | Istanbul | 15636243 + 4 | United States | Los Angeles | 3985520 +--------------------------------------------------------------------------------- +---- + +In order to run CLC commands, prefix them with a backslash `\`: +---- +> \object list +------------------------------------ + Service Name | Object Name +------------------------------------ + executor | hot-backup-executor + map | cities + map | currency + map | default +------------------------------------ +---- + +To return to non-interactive mode, use either of the following methods: + +- Press kbd:[Ctrl + D] +- Type `\exit`. + +== Limitations + +- *Client authentication:* The Hazelcast CLC supports only simple authentication (username and password) for Hazelcast Platform. The Hazelcast CLC does not currently support any other client authentication. If your Hazelcast Platform cluster uses other methods of client authentication, you cannot use Hazelcast CLC to connect to it. + +== Next Steps +Install, configure, and explore Hazelcast CLC: + +- xref:get-started.adoc[]. +- xref:configuration.adoc[]. +- xref:clc-commands.adoc[clc commands]. diff --git a/docs/modules/ROOT/pages/phone-homes.adoc b/docs/modules/ROOT/pages/phone-homes.adoc new file mode 100644 index 0000000..239fa09 --- /dev/null +++ b/docs/modules/ROOT/pages/phone-homes.adoc @@ -0,0 +1,25 @@ += Phone Homes + +CLC uses phone home data to learn about the usage of CLC. + +CLC instances collect usage metrics over a 24-hour period and send phone home data every 24 hours. + +== What is sent in? + +- ID for CLC Home installation +- Name of the operating system +- Name of the architecture +- CLC version +- Acquisition source (e.g Docker, Management Center) +- Connected Hazelcast Cluster ID +- Connected Viridian Cluster ID +- Number of times commands are run. Command runs are stored separately for each command type. +- Number of created CLC configurations + +== Disabling Phone Homes + +Phone homes can be disabled by setting the following environment variable. + +``` +export HZ_PHONE_HOME_ENABLED=false +``` diff --git a/docs/modules/ROOT/pages/release-notes-5.2.0.adoc b/docs/modules/ROOT/pages/release-notes-5.2.0.adoc new file mode 100644 index 0000000..3f47a2a --- /dev/null +++ b/docs/modules/ROOT/pages/release-notes-5.2.0.adoc @@ -0,0 +1,51 @@ += 5.2.0 Release Notes + +== New Features + +* Hazelcast CLC can now automatically read data serialized using compact and portable serialization. +* Added the ability to select a configuration from a list or import a {hazelcast-cloud} configuration when a configuration is not provided in the shell mode. +* Added the `--quite` (shorthand `-q`) flag which suppresses unnecessary outputs. Hazelcast CLC outputs can be sometimes noisy, such as success message logs; you can use this flag for a more quiet output. +* Added the `CLC_CLIENT_NAME` environment variable which allows overriding the default client name. +* Added the `CLC_CLIENT_LABELS` environment variable which allows overriding the default client labels with a comma separated list of labels. + +* Added support for link:https://hazelcast.com/products/viridian/[{hazelcast-cloud} Standard]. + +* Added the following commands: + +** `object list`: Lists the distributed data structures in the cluster. +** `completion`: Generates the autocompletion script for the specified shell, either Bash, Fish, Powershell or Zsh. Use `--help` for more information. +** `config add`: Adds configuration to the Hazelcast CLC. For example, to connect to a specific cluster. +** `config list`: Lists known configurations. +** `home`: Outputs the Hazelcast CLC home directory, which stores all configuration, logs and other files. + +* Added support for the following output formats, using the `--format` flag: + +** CSV +** Delimited. Outputs with tab characters between fields. This is the default format when working in non-interactive mode. +** JSON +** Table. This is the default format when working in interactive mode. + +* Added SQL shortcuts to the Hazelcast CLC shell: +** `\dm`: Lists mappings. +** `\dm MAPPING`: Displays information about a mapping. +** `\dm+ MAPPING`: Describes a mapping. + +* Added the `--show-type` flag for map commands, which outputs the type of key and value even if they can't be decoded. + +== Enhancements + +* Removed the SQL browser. +* The interactive mode defaults to running SQL queries. Prefix CLC commands with a backslash `\`. +* Simplified the configuration format. +* Map commands no longer use a flag for the key and value. They are passed as positional arguments: `$ map set -n my-map my-key my-value`. +* The Map name is optional and defaults to `default`. +* Removed `map get-all`, `map put` and `map put-all` commands. +* Added the `map set` command. +* Auto-completion is disabled in interactive mode. +* {hazelcast-cloud} Standard is the default cloud platform. +* The shell connects to the cluster on demand. + +== Known issues + +* Powershell autocompletion does not work. +* Ctrl+(left/right) key combinations don't work as expected in the interactive mode. You can set the `CLC_EXPERIMENTAL_READLINE` environment variable to ny to use an alternative readline implementation. diff --git a/docs/modules/ROOT/pages/release-notes-5.2.1.adoc b/docs/modules/ROOT/pages/release-notes-5.2.1.adoc new file mode 100644 index 0000000..e22fe2e --- /dev/null +++ b/docs/modules/ROOT/pages/release-notes-5.2.1.adoc @@ -0,0 +1,16 @@ += 5.2.1 Release Notes + +== Changes + +* Corrects the `--quite` flag to `--quiet`. +* Uses the experimental NY readline library on Windows by default. This update fixes arrow key related issues but disables syntax highlighting for SQL. +* Uses stderr for unnecessary output. + +== Improvements +* More consistent success messages when a list doesn't have any items. +* Added support for more compact serialization types. + +== Fixes +* Fixed a race in shell command. +* Fixed a bug that would cause a panic if the SQL command was interrupted. +* Powershell completion is fixed. diff --git a/docs/modules/ROOT/pages/release-notes-5.3.0-BETA-1.adoc b/docs/modules/ROOT/pages/release-notes-5.3.0-BETA-1.adoc new file mode 100644 index 0000000..7847b74 --- /dev/null +++ b/docs/modules/ROOT/pages/release-notes-5.3.0-BETA-1.adoc @@ -0,0 +1,16 @@ += 5.3.0-BETA-1 Release Notes + +== New Features + +* Hazelcast CLC can now submit Jet jobs and manage job snapshots. +* Added the following `job` commands: +** `submit`: Creates a job from the given jar file. +** `cancel`: Cancels a job. +** `list`: Lists jobs. +** `suspend`: Suspends a job. +** `resume`: Resumes a suspended job. +** `restart`: Restarts a job. +** `export-snapshot`: Exports a snapshot for a job. This feature requires a {hazelcast-cloud} or Hazelcast Enterprise cluster. +* Added the following `snapshot` commands: +** `list`: Lists the snapshots of a job. +** `delete`: Deletes a snapshot. diff --git a/docs/modules/ROOT/pages/release-notes-5.3.0-BETA-2.adoc b/docs/modules/ROOT/pages/release-notes-5.3.0-BETA-2.adoc new file mode 100644 index 0000000..4008a7b --- /dev/null +++ b/docs/modules/ROOT/pages/release-notes-5.3.0-BETA-2.adoc @@ -0,0 +1,25 @@ += 5.3.0-BETA-2 Release Notes + +== New Features + +* Support for Hazelcast {hazelcast-cloud}. The following commands were added: +** `viridian login` +** `viridian create-cluster` +** `viridian delete-cluster` +** `viridian get-cluster` +** `viridian list-clusters` +** `viridian stop-cluster` +** `viridian resume-cluster` +** `viridian download-logs` +** `viridian delete-custom-class` +** `viridian download-custom-class` +** `viridian list-custom-classes` +** `viridian upload-custom-class` +* Added the following new Map commands: +** `map key-set` +** `map destroy` +* Added `--wait` flag which makes CLC wait for the operation to complete. That flag was added to the following `job` commands: `submit`, `suspend`, `resume`, `cancel`, `restart` + +== Bug Fixes + +* `job submit` retries both sending the metadata and jar upload if there's an error. diff --git a/docs/modules/ROOT/pages/release-notes-5.3.0.adoc b/docs/modules/ROOT/pages/release-notes-5.3.0.adoc new file mode 100644 index 0000000..a3ea828 --- /dev/null +++ b/docs/modules/ROOT/pages/release-notes-5.3.0.adoc @@ -0,0 +1,38 @@ += 5.3.0 Release Notes + +== New Features +* Support for Hazelcast {hazelcast-cloud}. The following commands were added: +** `viridian login` +** `viridian create-cluster` +** `viridian delete-cluster` +** `viridian get-cluster` +** `viridian list-clusters` +** `viridian list-cluster-types` +** `viridian pause-cluster` +** `viridian resume-cluster` +** `viridian download-logs` +** `viridian import-config` +** `viridian delete-custom-class` +** `viridian download-custom-class` +** `viridian list-custom-classes` +** `viridian upload-custom-class` +* Hazelcast CLC can now submit Jet jobs and manage job snapshots. +* Added the following `job` commands: +** `submit`: Creates a job from the given jar file. +** `cancel`: Cancels a job. +** `list`: Lists jobs. +** `suspend`: Suspends a job. +** `resume`: Resumes a suspended job. +** `restart`: Restarts a job. +** `export-snapshot`: Exports a snapshot for a job. This feature requires a {hazelcast-cloud} or Hazelcast Enterprise cluster. +* Added the following `snapshot` commands: +** `list`: Lists the snapshots of a job. +** `delete`: Deletes a snapshot. +* Added the following new Map commands: +** `map key-set` +** `map destroy` + +== Improvements + +* {hazelcast-cloud} errors are revamped to be more user-friendly. +* Multiline columns are supported in table output. \ No newline at end of file diff --git a/docs/modules/ROOT/pages/release-notes-5.3.1.adoc b/docs/modules/ROOT/pages/release-notes-5.3.1.adoc new file mode 100644 index 0000000..53de998 --- /dev/null +++ b/docs/modules/ROOT/pages/release-notes-5.3.1.adoc @@ -0,0 +1,11 @@ += 5.3.1 Release Notes + +== New Features + +* Added the `--timeout` flag which causes Hazelcast CLC to exit with status code 2 if an operation cannot be completed in the given time. + +== Improvements + +* Added a workaround for a server side bug that causes an incorrect hash calculation error when certain type of Jet jars are submitted. See: https://github.com/hazelcast/hazelcast/pull/24674 +* Extended cluster information retrieved from 'clc viridian get-cluster' command. +* Improved error checking so a token error is displayed when a {hazelcast-cloud} command fails with an authentication error. diff --git a/docs/modules/ROOT/pages/release-notes-5.3.2.adoc b/docs/modules/ROOT/pages/release-notes-5.3.2.adoc new file mode 100644 index 0000000..dbc48d9 --- /dev/null +++ b/docs/modules/ROOT/pages/release-notes-5.3.2.adoc @@ -0,0 +1,14 @@ += 5.3.2 Release Notes + +== New Features + +* Added the `project create` command that can create a Hazelcast project from a template. Note that this features is currently BETA. +* Added the `script` command that runs an SQL or CLC script from a local file or HTTP resource. +* Added the following data structure commands: `atomic-long`, `list`, `multi-map`, `queue` and `topic`. +* Added more `map` commands: `values`, `load-all`, `lock`, `try-lock` and `unlock`. Note that lock related commands are only available in the interactive mode. +* Added the `CLC_CONFIG` environment variable which sets the default CLC configuration. If unset, the default is `default`. + +== Fixes + +* link:https://github.com/hazelcast/hazelcast-commandline-client/pull/290[#290] Refactored `job` commands to use coordinator for SQL jobs. +* link:https://github.com/hazelcast/hazelcast-commandline-client/pull/288[#288] Fix streaming timeout. diff --git a/docs/modules/ROOT/pages/release-notes-5.3.3.adoc b/docs/modules/ROOT/pages/release-notes-5.3.3.adoc new file mode 100644 index 0000000..f170192 --- /dev/null +++ b/docs/modules/ROOT/pages/release-notes-5.3.3.adoc @@ -0,0 +1,26 @@ += 5.3.3 Release Notes + +== New Features + +* Added the `demo generate-data` command that creates data from a Wikipedia event stream. +* Added the `demo map-setmany` command that generates multiple Map entries. +* Added the `project list-templates` command that lists templates that can be used with the `project create` command. +* Added the `\di` shortcut that lists all or some indexes. This command is available only in the interactive mode. +* Added `--prelease` and `--development` flags to `viridian create-cluster` command. + +== Improvements + +* The Viridian "CLI" bundle is used with `config import` and `viridian import-config` commands. The configuration bundle includes certificates for all supported Hazelcast client libraries. +* CLC configuration is saved as both `config.yaml` and `config.json` when `config import`, `viridian import-config` or `config add` commands are used. +* An installation script may be used to install CLC on Linux and macOS. +* Configuration menu is displayed in the non-interactive mode when the `default` configuration doesn't exist. +* `snapshot list` command provides more information. +* Configuration name is used in the CLC interactive prompt. +* "Invalid number of arguments" error is improved to display which positional arguments are missing. +* `project create` command updates the corresponding template if necessary when run. +* Updated command output. + +== Fixes + +* Full stack trace is shown on `job submit` errors. +* link:https://github.com/hazelcast/hazelcast-commandline-client/pull/288[#288] Fix streaming timeout. diff --git a/docs/modules/ROOT/pages/release-notes-5.3.4.adoc b/docs/modules/ROOT/pages/release-notes-5.3.4.adoc new file mode 100644 index 0000000..d243439 --- /dev/null +++ b/docs/modules/ROOT/pages/release-notes-5.3.4.adoc @@ -0,0 +1,26 @@ += 5.3.4 Release Notes + +== New Features + +* Added the `serializer generate` command that creates Java Compact Serialization classess from the given schema. +* Added an update checker which displays a notification in the interactive mode. You can disable it by setting the `CLC_SKIP_SERVER_VERSION_CHECK` to `1`. +* In order to make an informed decision about CLC improvements and features, we started to collect non-identifiable telemetry. You can disable this by setting `HZ_PHONE_HOME_ENABLED` environment variable to `false`. You can find more information in the xref:phone-homes.adoc[documentation]. +* CLC can now be installed using an install script on Linux and macOS systems. Just run `curl https://hazelcast.com/clc/install.sh | bash`. + +== Improvements + +* Improved configuration selector. +* If there's a single configuration, do not display the configuration selector and use that configuration automatically. +* Updated `job submit` command to deduce the job ID. + +== Changes + +* Confirmation is required from the user when `demo generate-data` command runs. + +== Fixes + +* CLC interactive prompt doesn't change after config wizard. +* Readline panic in the interactive mode if terminal width cannot be determined and left arrow is pressed. +* Map proxy is created when a `map` command is used. +* "connecting to cluster" prompt is not shown when `object list` command runs. +* Fixed `list add` command. diff --git a/docs/modules/ROOT/pages/release-notes-5.3.5.adoc b/docs/modules/ROOT/pages/release-notes-5.3.5.adoc new file mode 100644 index 0000000..393963d --- /dev/null +++ b/docs/modules/ROOT/pages/release-notes-5.3.5.adoc @@ -0,0 +1,36 @@ += 5.3.5 Release Notes + +== New Features + +* Added the Advanced Scripting as a BETA future. Advanced Scripting enables writing the scripts in a Python-like language. The following commands are available with this release: link:https://docs.hazelcast.com/clc/5.3.5/clc-script#advanced-script-beta[Advanced Script]. Check out the `scripts` directory for example scripts. +* CLC now supports loading the `shell.clc` script on startup in the interactive mode. `shell.clc` must be in `$CLC_HOME`. You can find the `$CLC_HGME` using `clc home` command. +* Added the ability to define "aliases" in the interactive or script modes. An alias, like the shell aliases, enable you to create shortcuts for your CLC commands. For example: `\alias maps -- \\object list map` creates an alias to list Maps in the cluster. In order to make the aliases permanent, you can put them in the `shell.clc` file. Check out the link:https://docs.hazelcast.com/clc/5.3.5/alias[Alias documentation]. +* Added the `map entry-view` command. Check out the link:https://docs.hazelcast.com/clc/5.3.5/clc-map#clc-map-entry-view[entry-view documentation], + +== Improvements + +* Improved configuration selector. +* If there's a single configuration, do not display the configuration selector and use that configuration automatically. +* Updated `job submit` command to deduce the job ID. +* `clc template list` can show all repositories in an organization. +* Added the `--source` flag to `clc project create` and `clc template list` commands. This flag enables using templates outside of the `hazelcast-templates` organiation. +* Added `clc_home` placeholder to Project Creator templates. +* Added `repeat` and `each` actions to the Project Creator templates. +* Compact Serializer does not overwrite generated files and displays a prompt. Use the `--yes` flag to aloways overwrite generated fiels. +* Compact Serializer does not produce code that dependes on the `Notnull` annotation. +* Compact Serializer respects the `namespace` field when generating the path. The final path is derived from the value of `--output-dir` flag and the namespace. + + + +== Changes + +* Table format is the default format for all commands except `version` and `home`. In order to use the delimited mode, you can append `-f delimited` flag to your command line. +* Moved `clc project list-templates` command to `clc template list`. The behaviour of the command didn't change. +* Compact serializer creates only the serializer classes. +* We've changed our logging implementation, so CLC logs appear slighlty different. You can find your log directory using `clc home logs`. + +== Fixes + +* Fixed Project Creator template update. +* Fixed copying hidden directories with the `.keep` suffix in the Project Creator. +* Fixed Compect Serializer generated files should not have their execute bits set. diff --git a/docs/modules/ROOT/pages/upgrade-clc.adoc b/docs/modules/ROOT/pages/upgrade-clc.adoc new file mode 100644 index 0000000..faa63ec --- /dev/null +++ b/docs/modules/ROOT/pages/upgrade-clc.adoc @@ -0,0 +1,5 @@ += Upgrading the Hazelcast CLC + +To upgrade to the latest version, reinstall the Hazelcast CLC after each new release. + +For installation options, see xref:install-clc.adoc#installing-hazelcast-clc[Installing the Hazelcast CLC]. \ No newline at end of file diff --git a/docs/modules/ROOT/pages/using-compact-serializer-generator.adoc b/docs/modules/ROOT/pages/using-compact-serializer-generator.adoc new file mode 100644 index 0000000..2973172 --- /dev/null +++ b/docs/modules/ROOT/pages/using-compact-serializer-generator.adoc @@ -0,0 +1,193 @@ += Using Compact Serializer Generator + +:description: Allows you to generate compact classes for your POJOs. +{description} + +== Before you Begin + +You need the following: + +- Hazelcast CLC +- Hazelcast cluster + +== Creating Schemas for Business Objects +Let's assume we have the following entities in our application: + +* Student +** ID +** Name +* Classroom +** ID +** Students +* School +** ID +** Classrooms + +The relationships between these entities are as follows: + +* School has classrooms (1->n classrooms) +* Classrooms have students (n->n students) + +The schema definitions are as follows: + +[source,yaml] +---- +namespace: "org.example" +classes: + - name: Student + fields: + - name: id + type: int32 + - name: name + type: string +---- + +[source,yaml] +---- +namespace: "org.example" +imports: + - people.yaml +classes: + - name: Classroom + fields: + - name: id + type: int32 + - name: students + type: com.people.Student[] +---- + +[source,yaml] +---- +namespace: "org.example" +imports: + - classroom.yaml +classes: + - name: School + fields: + - name: id + type: int32 + - name: classrooms + type: com.rooms.Classroom[] +---- + +Schema definitions contain following information: + +* A description of the content of the `Student`, `Classroom`, and `School` compact classes. +* Any imported schemas, identified using `imports`. +* The namespaces for the schema files, identified using `namespace`. + +== Generating Compact Classes from Schemas + +To generate compact classes, use the following command: + +[source,bash] +---- +clc serializer generate school.yaml -l java +---- + +This generates the classes in the current working directory. To save them to a different directory, use the following command, where `` identifies the directory in which you want to generate the classes: + +[source,bash] +---- +clc serializer generate school.yaml -l java -o +---- + +The following classes are generated: + +* `StudentSerializer.java` +* `SchoolSerializer.java` +* `ClassroomSerializer.java` + +in `com/education` directory. + +== Creating Compact Serialization Configuration + +The `generate` command lists the configuration options. You can configure the configuration options in any of the following ways: + +* Java Configuration +* XML Configuration +* YAML Configuration + +In the following code, we use the Java configuration to register the generated compact classes: + +[source,java] +---- +ClientConfig clientConfig = new ClientConfig(); +clientConfig.getSerializationConfig() + .getCompactSerializationConfig() + .setSerializers(new com.education.ClassroomSerializer(), + new com.education.StudentSerializer(), + new com.education.SchoolSerializer()); +---- + +== Using SQL Support + +To use SQL support, you must create a mapping, write to the map, and write to the map using a Java client. You can then check the type of the created records and query the map using the Java client. + +These steps are described in the following sections. + +=== Creating Mapping + +If the keys or values in a map use the Compact format, provide the following options when creating the mapping: + +* `keyCompactTypeName` +* `valueCompactTypeName` + +[source,sql] +---- +CREATE OR REPLACE MAPPING students( + id INT EXTERNAL NAME "__key.id", + name VARCHAR +) TYPE IMap +OPTIONS ( + 'keyFormat' = 'compact', + 'keyCompactTypeName' = 'studentId', + 'valueFormat' = 'compact', + 'valueCompactTypeName' = 'student' +); +---- + +You can execute the SQL either using CLC or the Java Client. + +=== Writing to a Map using a Java Client + +You can write to a Map using a Java Client as follows: + +[source,java] +---- +IMap studentsMap = client.getMap("students"); +students.set("joe", new Student(1, "Joe Dalton")); +students.set("william", new Student(2, "William Dalton")); +students.set("jack", new Student(3, "Jack Dalton")); +students.set("Averell", new Student(4, "Averell Dalton")); +---- + +=== Checking the Created Records' Type + +As we used the `Compact` format when creating the map, we must check whether the format uses the correct `type`. We do this as follows: + +[source,bash] +---- +clc map entry-set --name students --show-type -f table + __key | __key_type | this | this_type | id | name + joe | STRING | > | COMPACT | 1 | Joe Dalton + william | STRING | > | COMPACT | 2 | William Dalton + Averell | STRING | > | COMPACT | 4 | Averell Dalton + jack | STRING | > | COMPACT | 3 | Jack Dalton +---- + +As you can see, all records are defined as `COMPACT` in the `this_type` column. + +=== Querying the Map using Java Client + +You can now query the `Compact` values from the map and assign them to Java object as follows: + +[source, java] +---- +SqlResult result = sqlService.execute(String.format("SELECT this FROM students WHERE name = '%s'", "Joe Dalton")) +for (SqlRow row : result) { + Student s = row.getObject("this"); + System.out.println(s.getId()) + System.out.println(s.getName()) +} +---- \ No newline at end of file diff --git a/docs/modules/ROOT/partials/global-parameters.adoc b/docs/modules/ROOT/partials/global-parameters.adoc new file mode 100644 index 0000000..a1ccd56 --- /dev/null +++ b/docs/modules/ROOT/partials/global-parameters.adoc @@ -0,0 +1,77 @@ +[cols="1m,2a,1m"] +|=== +|Parameter|Description|Default + +|`--config`, `-c` +|Path to the configuration file in YAML format. +a|The following locations are tried in order for the existence of `config.yaml` + +1. Current working directory +2. The parent directory of the `clc` executable +3. `$CLC_HOME/default` directory + +|`--format`, `-f` +a|Set the output format + +* `csv` +* `delimited`: By tab characters +* `json` +* `table` + +a| + +* Interactive mode: `table` +* Non-interactive mode: `delimited` + +|`--log.level` +a|Set the log level, one of: + +* `debug` +* `info` +* `warning` +* `error` + +|`info` + +|`--log.path` +|Set the log path. Use `stderr` to log to the screen (stderr). +|`$CLC_HOME/logs/YYYY-MM-DD.log` where `YYYY-MM-DD` is today's date. + +|`--quiet`, `-q` +|Prevent displaying unnecessary output. +|false + + +|--verbose +|Enable output with more information. +|false + +|--timeout +|Timeout for operation to complete. + +The duration is a string in the form of `AMOUNTunit` where `AMOUNT` is an `integer`, and `unit` is one of the following: + +- `ms: milliseconds` + +- `s: seconds` + +- `m: minutes` + +- `h: hours` + +Underscore (_) character is ignored in the `AMOUNT`. `unit` is optional and defaults to `s` if not specified. + +The following are a few of the valid DURATIONs: + +- `5: 5 seconds` + +- `5s: 5 seconds` + +- `10000ms: 10000 milliseconds` + +- `10_000_000ms: 10000000 milliseconds` + +WARNING: This is a client-side timeout, the operation you started maybe in progress on the server-side even if the given timeout is exceeded. +| + +|=== \ No newline at end of file diff --git a/package.json b/package.json new file mode 100644 index 0000000..8489e34 --- /dev/null +++ b/package.json @@ -0,0 +1,23 @@ +{ + "name": "hazelcast-docs-playbook", + "version": "1.0.0", + "description": "Hazelcast Antora project.", + "author": "Serdar Ozmen", + "license": "ISC", + "scripts": { + "build": "antora --to-dir docs --fetch antora-playbook.yml", + "build-local": "antora --to-dir test --fetch antora-playbook-local.yml", + "check-links-local": "antora --fetch --to-dir test --log-level=error --log-failure-level=error --extension=@jcahills/antora-link-checker check-links-playbook.yml", + "serve": "serve test", + "expose": "ngrok http 5000" + }, + "devDependencies": { + "@antora/cli": "^3.1.1", + "@antora/site-generator": "^3.1.1", + "@jcahills/antora-link-checker": "^1.0.1", + "ngrok": "^3.3.0", + "serve": "^11.3.2", + "@asciidoctor/core": "^2.0.0", + "asciidoctor-kroki": "^0.10.0" + } +}