E-mail
Use Cases
|
Usage of Petals CLI
usage: Petals JMX Command Line Interface [-d] [-y] [-h <host>] [-n <port>] [-u <user>] [-p <password>] [-H | -V | [--file ] <filename> | -c <command> <command-args> | -C] -c,--command Execute a command given on the command line after '--'. -C,--console Enable the mode 'console'. -d,--debug Print stack trace and debugging informations --file <filename> Enable the script file execution. If filename is '-', commands are read from the stdin. -H,--help Print this help message and exit. -h,--host <host> remote petals ESB host name. -n,--port <port> port number. -p,--password <password> password. -u,--user <user> username. -V,--version Print the version number and exit. To get help on a command, use the command 'help' on command-line: petals-cli.sh -c help <command> Available commands: - deploy: Deploy and start a JBI artifact in petals container. - start: Start a JBI artifact or the container. - stop: Stop a JBI artifact or the container. - undeploy: Stop and uninstall or undeploy JBI artifacts. - exit: Exit this shell. - help: Display this help message or help for a specific command. - list: List JBI artifacts name and current status. - registry-sync: Force a registry synchronization - registry-list: List the entries of the registry. - version: Print version informations about petals container. - show: Print informations about a JBI artifact. - load: Load properties from files. - print: Print a message. - pwd: Print the working directory. - set: Assign a value to the system property named key. Which evolution would you like on Petals? Share it! http://www.petalslink.com/feedback
Petals CLI: the Basis
Installing Petals-CLI
Make sure you have downloaded petals-cli.x.x.zip.
Unzip it wherever you want to install it.
Petals CLI capabilities about script and shell usages
Interactive console
Launching Petals CLI with the following command line starts an interactive console with a prompt where the user can enter commands.
> ./petals-cli.sh -C
Type 'help' for help.
------------------------------------------------------------------------------
petals-cli>
On Windows, to be able to launch Petals CLI by a double-click, this command is wrapped by another script: petals-cli-console.bat.
On Linux, there is no wrapper script but a shell alias can be created. Next, this alias will be automatically created by a RPM or debian package.
Execution of a Petals CLI command directly on the command line
Launching Petals CLI with the following command line executes the command specified on the command line.
> ./petals-cli.sh -c -- <command> <command-args>
Execution of a Petals script file
Launching Petals CLI with the following command line executes the commands from the specified Petals script.
> ./petals-cli.sh <filename> > ./petals-cli.sh --file <filename>
 | A Petals script is text file containing commands supported by Petals CLI. |
Execution of an inlined Petals script
Launching Petals CLI with the following command line executes commands provided through the standard input ("stdin").
> cat <filename> | ./petals-cli.sh - > cat <filename> | ./petals-cli.sh --file - > ./petals-cli.sh - << EOF <command1> <command1-args> <command2> <command2-args> EOF > ./petals-cli.sh --file - << EOF <command1> <command1-args> <command2> <command2-args> EOF
Getting help
Getting help on command line options and arguments
The help on command line options and arguments is available through the '-H' option. A text containing options, arguments and available commands is displayed according to the usage defined above.
> ./petals-cli.sh -H
Getting help on commands from the command line
The help on a command is available by using the command 'help'. A usage and a description of the command is displayed:
> ./petals-cli.sh -c -- help <command> usage: <command> <command-arguments> <command description> >
where:
- <command> is the command for which we want to get help.
- <command-arguments> is the list of arguments for the command.
- <command-description is a description of the command.
Getting help on available commands and on a command in interactive mode
The list of available commands is available by using the command 'help' without argument.
Help about a command is available by using the 'help' command. Command's usage and description are then displayed.
> ./petals-cli.sh -C Type 'help' for help. ------------------------------------------------------------------------------ petals-cli> help Available commands: deploy Deploy and start a JBI artifact in petals container. exit Exit this shell. help Display this help message or help for a specific command. ... For help on a specific command type: help <command> petals-cli> help <command> usage: <command> <command-arguments> <command description> petals-cli>
where:
- <command> is the command for which we want to get help.
- <command-arguments> is the list of arguments for the command.
- <command-description is a description of the command.
Getting the version of Petals CLI
To get the version of Petals CLI, the version of the JVM running Petals CLI, and its operating system, use the '-V' option:
> ./petals-cli.sh -V Petals JMX Command Line Interface 1.1.0-SNAPSHOT Java(TM) SE Runtime Environment 1.6.0_26-b03 Linux 3.0.0-16-generic-pae
Return codes of Petals CLI
Return code on successful result
When there is no error about options and arguments on the command line, the return code of Petals CLI is 0.
Return code on error about options or arguments on the command line
When there is an error about options or arguments on the command line, the return code of Petals CLI is 1.
Return code on error about options and arguments of a command
When there is an error about options and arguments of a command, the return code of Petals CLI is 1.
Return code when executing a system command in Petals CLI
When a system command is executed in Petals CLI, the return code is the one of the system command.
Error Management
Options and Arguments parsing
When using the script mode or inlined mode, parsing errors (invalid options and/or arguments) result in an interruption of Petals CLI.
The right return code is then pushed back.
Error management of a command set on the command line
If an error occurs during the execution of a command set on the command line:
- The command is interrupted.
- Petals CLI is interrupted with the return code 2.
Error management of a command in interactive mode
If an error occurs during the execution of a command entered in interactive mode:
- The error message is displayed.
- Petals CLI is not interrupted, the user can enter other commands.
Error management of a command read from stdin or a file
If an error occurs during the execution of a flow of commands:
- The command that has thrown the error is interrupted.
- The return code of the command can be checked using the commands isParsingErrorReturned, isExecutionErrorReturned, isNoErrorReturned, the ternary conditional operator, and the lastErrorCode attribute.
> ./petals-cli.sh - << EOF deploy <artifact-url> isNoErrorReturned ? listartefacts : exit lastErrorCode EOF
Note:
- The return values of command isParsingErrorReturned, isExecutionErrorReturned and isNoErrorReturned are reset when invoking another command. Only the error of the last command execution can be checked.
- The attribute lastErrorCode is an argument of the command exit to return the return code of the last executed command.
Exit from the Console mode
To exit the console mode, use the 'exit' command.
If a number is set as an argument, it is used as return code. Otherwise, the 0 is returned.
> ./petals-cli.sh -C Type 'help' for help. ------------------------------------------------------------------------------ petals-cli> exit > echo $? 0 > ./petals-cli.sh -C Type 'help' for help. ------------------------------------------------------------------------------ petals-cli> exit 1 > echo $? 1
Petals CLI Preferences
It is possible to define preferences in Petals CLI.
The preferences are defined a properties file, as key/value pairs.
By default, this file is located at $PETALS_CLI_HOME/conf/preferences.properties.
However, it is possible to move this file somewhere else thanks to an environment variable.
$PETALS_CLI_PREFS is the variable environment that points to the location of the preferences file.
This file contains a set of keys in several sections:
- section 'Global preferences':
- alias.default: the default alias to use (required).
- user.lang: the language to use in Petals CLI.
- This property is optional. If not set, OS settings are used. If the OS language setting is not supported, then English is used.
- If the value is specified and not supported, then English is picked up.
- French and English are the two languages that must be supported. Others are optional (but contributions are welcome).
- section defining aliases. An alias identifies all the properties of a connection. An alias is defined as following:
- <alias>.host: the host of the default Petals node (required).
- <alias>.port: the JMX port of the default Petals node (required).
- <alias>.user: the JMX user name for the default Petals node (optional).
- <alias>.password: the JMX password for the default Petals node (optional).
When optional keys are not defined, Petals CLI will ask for their values manually (or you will have to use the right options with the commands).
If the file does not exist, or that $PETALS_CLI_PREFS points to an invalid location, Petals CLI will use default settings when possible. Otherwise, it will display an error message.
For a server, the user and password must both be set or both be absent.
An error message is displayed if only one of them is specified.
The server alias must be unique in the properties file.
If a server alias is used twice, an error message will be displayed.
Initial content of the file:
- The default server / connection
alias.default = default
- The connection properties of the 1st server
default.host = localhost
default.port = 7700
default.user = petals
default.password = petals
Connection to a Petals node
Connection options from the command line
All the required parameters for a JMX connection must be configurable on the command line as options:
> ./petals-cli.sh -h <host> -n <port> -u <user> -p <password> -c -- <command> > ./petals-cli.sh -h <host> -n <port> -u <user> -p <password> -C petals-cli@<host1>:<port1>>
An alias can also be used.
> ./petals-cli.sh -a <alias> -c -- <command> > ./petals-cli.sh -a <alias> -C petals-cli@<host1>:<port1>>
Interacting with several Petals nodes without exiting Petals CLI
In interactive mode or script mode, we should be able to close a connection and open another one without leaving Petals CLI. This is achieved with the 'connect' and 'disconnect' commands. If no argument is set on the 'connect' command, default values are used. These default values are specified in the preferences file. If a connection already exists, the 'connect' command will realize a disconnection before to establish the new connection.
> ./petals-cli.sh -C Type 'help' for help. ------------------------------------------------------------------------------ petals-cli> connect -h <host1> -n <port1> -u <user1> -p <password1> Connected on <host1>:<port1> with '<user1>' petals-cli@<host1>:<port1>> disconnect petals-cli> connect -a <alias> Connected on <host1>:<port1> with '<user1>' petals-cli@<host1>:<port1>> disconnect petals-cli> connect -h <host2> -n <port2> -u <user2> -p <password2> Connected on <host2>:<port2> with '<user2>' petals-cli@<host2>:<port2>> connect petals-cli@<host2>:<port2>> Would you like to connect to <default-user>:*****@<default-host>:<default-port>? (y/n) y petals-cli@<default-host>:<default-port>>
Default connection
By default (if no argument or option is set).
In console mode, the connection is established with the values given in the preferences file.
> ./petals-cli.sh -C Type 'help' for help. ------------------------------------------------------------------------------ petals-cli> connect petals-cli> Would you like to connect to <default-user>:*****@<default-host>:<default-port>? (y/n) y petals-cli@<default-host>:<default-port>>
The confirmation can be skipped by adding the 'yes' argument to the command.
> ./petals-cli.sh -C Type 'help' for help. ------------------------------------------------------------------------------ petals-cli> connect -y petals-cli@<default-host>:<default-port>>
In command line mode, if no argument or option is set, a connection is established with the values defined in the preferences file.
> ./petals-cli.sh -c -- stop
 | This is necessary to easily stop a local container |
In script mode, the connection is established with the values defined in the preferences file.
> ./petals-cli.sh - << EOF connect EOF
If the preferences file does not exist and that connect was invoked without an argument, the command returns the error code 2.
Security
For security reasons, a Petals CLI user may decide that there should be no default connection.
In that case, he may decide to delete the preference file, so that any user will have to type in the right information.
If the preference (properties file) does not exist, Petals CLI displays an error message.
> ./petals-cli.sh -C Type 'help' for help. ------------------------------------------------------------------------------ petals-cli> connect No default connection is available. Use 'help connect' for more information.
Another possibility is that the user allows to record a default host and port but not the credentials.
In that case, Petals CLI will ask the user to type in the credentials.
> ./petals-cli.sh -C Type 'help' for help. ------------------------------------------------------------------------------ petals-cli> connect petals-cli> Would you like to connect to <default-host>:<-default-port>? (y/n) y petals-cli> Username: wrong-username petals-cli> Password: right-pwd Invalid credentials. petals-cli> Retry? (y/n) y petals-cli> Username: right-username petals-cli> Password: wrong-pwd Invalid credentials. petals-cli> Retry? (y/n) y petals-cli> Username: right-username petals-cli> Password: right-pwd petals-cli@<default-host>:<-default-port>>
Error Messages
| Error messages should be written in active form. Negative forms should be avoided. |
The preferences file does not exist.
The connect command results in the following error message.
No default connection is available. Use 'help connect' for more information.
The preferences file is invalid (missing property, or duplicate alias...).
The connect command results in the following error message.
The preferences file contains <N> error(s).
- Error 1
- Error2
Duplicate Alias.
The alias '<alias>' can only be used once.
Missing property.
The property '<property>' is missing.
Only user was specified for a server.
The credentials for '<alias>' are invalid: add the password or remove the user.
Only password was specified for a server.
The credentials for '<alias>' are invalid: add the user or remove the password.
Administration Commands
Working with JBI artifacts
Deploying and Starting an Artifact at once
Petals CLI is able to deploy and start a JBI artifact without distinction between shared-library, component and service assembly using the following command:
deploy -u <artifact-file> [-f,--file <configuration-file> | -D<configuration-properties>]
where:
- <artifact-file> is the local file name or the URL of the artifact to install or deploy and start
- <configuration-file> is the local file name or the URL of the properties file used to configure the artifact. This argument is used only if the artifact is a component. It has no sense for other artifacts. This argument is exclusive with <configuration-properties>.
- <configuration-properties> is a list of '<property-name>=<property-value>', separated by a comma, where <property-name> is the name of the property to configure with <property-value>. This argument is used only if the artifact is a component. It has no sense for other artifacts. This argument is exclusive with <configuration-file>.
| Auto-completion is available on artifacts IDs and artifact file names. |
Deployment of an Artifact located in a Maven repository
Petals CLI is able to deploy and start a JBI artifact located into a Maven repository by using the following command:
deploy <maven-artifact> [<configuration-file> | <configuration-properties>]
where:
- <maven-artifact> is the Maven identifiers of the artifact to install: group-id:artifact-id:version[:classifier]. If required, the Maven repository can be defined in the Maven configuration file ($HOME/.m2/settings.xml)
- <configuration-file> is the local file name or the URL of the properties file used to configure the artifact. This argument is used only if the artifact is a component. It has no sense for other artifacts. This argument is exclusive with <configuration-properties>.
- <configuration-properties> is a list of '<property-name>=<property-value>', separated by a white character, where <property-name> is the name of the property to configure with <property-value>. This argument is used only if the artifact is a component. It has no sense for other artifacts. This argument is exclusive with <configuration-file>.
Bulk Deployment and Start
To deploy and start several artifacts in one command, just put them in a local directory and execute the command 'deploy':
deploy -b,--bulk <directory>
> ./petals-cli.sh -y - << EOF
deploy -b /tmp
EOF
> ./petals-cli.sh -C
Type 'help' for help.
------------------------------------------------------------------------------
petals-cli> deploy -b /tmp
If the argument <artifact-file> of the 'deploy' command is a local directory, all artifacts of the directory are deployed.
Starting an Artifact
An artifact can be started by using the 'start-artifact' command:
> ./petals-cli.sh -c -- start-artifact [ -u <artifact-file> | -a <artifact-id> [<artifact-type>] ]
where:
- <artifact-file> is the local file name or the URL of the artifact to start.
- <artifact-type> is the nature (SL, component, SA) of the artifact to start.
- <artifact-id> is the JBI identifier of the artifact to start.
| Auto-completion is available on artifacts IDs and artifact file names. |
Stopping an artifact
An artifact can be stopped by using the command 'stop-artifact':
> ./petals-cli.sh -c -- stop-artifact [ -u <artifact-file> | -a <artifact-id> [<artifact-type>] ]
where:
- <artifact-file> is the local file name or the URL of the artifact to stop.
- <artifact-type> is the nature (SL, component, SA) of the artifact to stop.
- <artifact-id> is the JBI identifier of the artifact to stop.
| Auto-completion is available on artifacts IDs and artifact file names. |
Undeploying and Stopping an Artifact at once
Petals CLI is able to stop and uninstall/undeploy a JBI artifact without distinction between shared-library, component and service assembly using the following command:
undeploy [ -u <artifact-file> | -a <artifact-id> [<artifact-type>] ]
where:
- <artifact-file> is the local file name or the URL of the artifact to undeploy.
- <artifact-type> is the nature (SL, component, SA) of the artifact to undeploy.
- <artifact-id> is the JBI identifier of the artifact to undeploy.
| Auto-completion is available on artifacts IDs and artifact file names. |
Bulk Undeployment and Stop
To undeploy several artifacts in one command, just put them in a local directory and execute the 'undeploy' command:
> ./petals-cli.sh -y - << EOF
undeploy -b
EOF
> ./petals-cli.sh -C
Type 'help' for help.
------------------------------------------------------------------------------
petals-cli> undeploy -b
Showing installed JBI artifacts
All the installed JBI artefacts can be listed using the command 'list [-p <artifact-pattern> ] [-t artifact-type]':
> ./petals-cli.sh -c -- list petals-sl-mysql Installed SL petals-bc-soap Started BC petals-se-bpel Started SE soap-consume-provide Started SA su-SOAP-EchoService-consume SU su-SOAP-EchoService-provide SU
where:
- <artifact-pattern> is an optional RegExp pattern to filter the content of the returned list. All the returned JBI artifacts must have a JBI identifier matching the pattern. If no pattern is defined, all the installed artifacts are returned.
- <artifact-type> is one of the following values: SL, BC, SE, SA, SU, used to restrict the returned list.
The returned list is ordered:
- firstly, according to the artifact type: SL, BC, SE, SA, SU,
- and secondly the alphabetical order is applied.
For each artifact, the command displays (caution to the padding):
- Its JBI identifier.
- Its current status.
- Its type (SL, BC, SE, SA, SU).
| As the SU lifecycke can't b emodified through the JMX API, there is no interest to display the SU status (it's the same as the status of its SA). |
Getting information about an Artifact
Information about a JBI artifact can be got with the 'show' command:
> ./petals-cli.sh -c -- show [-e] [ -u <artifact-file> | -a <artifact-id> [<artifact-type>] ]
where:
- <artifact-file> is the local file name or the URL of the artifact to show.
- <artifact-type> is the nature (SL, component, SA) of the artifact to show.
- <artifact-id> is the JBI identifier of the artifact to show.
The '-e' option displays extended information.
Displayed information includes:
- For a shared library:
- Its JBI identifier
- The version of the shared library if available, extracted from its JBI descriptor
- If the shared library was built with Maven, its Maven version extracted from Maven metadata
- Extended information:
- List of embedded libraries (coming next)
- For a component (BC or SE):
- Its JBI identifier
- Its type: binding component or service engine
- If the component was built with Maven, its Maven version extracted from Maven metadata
- Its state (not-loaded, loaded, installed, started, stopped, shutdown)
- Extended information:
- List of embedded libraries of the boostrap classpath(coming next)
- List of embedded libraries of the runtime classpath(coming next)
- List of needed shared-libraries, for each shared-library(coming next):
- Its JBI identifier
- The version of the shared library if available, extracted from its JBI descriptor
- For a service assembly:
- Its JBI identifier
- If the service-assembly was built with Maven, its Maven version extracted from Maven metadata
- Its state (not-deployed, deployed, started, stopped, shutdown)
- List of embedded service-units (displayed using their JBI identifiers)
- Extended information (replace the previous list of embedded service-units):
- For each service unit embedded:
- Its JBI identifier
- Its target component (displayed using its JBI identifier)
| Auto-completion is available on artifacts IDs and artifact file names. |
Interrupting a flow of commands
A flow of commands can be interrupted by using the 'exit' command. If a number is set as argument, it is used as return code. The argument 'lastErrorCode' is used as return code value of the last executed command. Otherwise, 0 is returned to the shell.
> ./petals-cli.sh -y - << EOF deploy /tmp/my-artifact.zip exit lastErrorCode EOF
Ending a flow of commands
When the end of a flow of commands is reached, if the last command is not 'exit', the 'exit lastErrorCode' command is implicitly executed.
> ./petals-cli.sh -y - << EOF deploy /tmp/my-artifact.zip EOF echo $? 0
Working with the Container
Getting the versions related to a Petals node
To get the version of a Petals node, the version of the JVM running Petals node, and its operating system, use the 'version' command:
> ./petals-cli.sh -c version Petals JBI Container 3.1.4-SNAPSHOT Java(TM) SE Runtime Environment 1.6.0_26-b03 Linux 3.0.0-16-generic-pae
Stopping the container
The container can be stopped by using the 'stop' command with the argument 'container':
> ./petals-cli.sh -c -- stop container
Shutdowning the container
The container can be shutdowned by using the command 'stop' with the argument 'container' and the parameter '--shutdown'.
> ./petals-cli.sh -c -- stop container --shutdown Are you sure you want to shutdown the container? (y/n)
A confirmation is expected, except if the 'yes' flag is set on the command line. A confirmation message is displayed in the console mode, except if the 'yes' flag is set on the command line.
Getting the topology
When connected to a container, it is possible to get information about the topology this node is part of.
petals-cli@host:port> topology-list Domain: Domain 1 Subdomain: SubDomain 1 * Container: Node1 ** information * Container: Node2 ** information Subdomain: SubDomain 2 ...
This command shows a set of Petals nodes, sorted by domain and sub-domains, each node having the following information:
- Container name
- Node type (master or slave)
- Host
- Node ports
Getting the server properties
When connected to a container, it is possible to get all the values defined in its server.properties file.
petals-cli@host:port> properties-list Key1: value1 Key2: value2 ...
where "keyN" and "valueN" are the keys and values defined in the server.properties file of this container.
Changing logger levels
On a container, it is possible to change the level of a logger.
petals-cli@host:port> logger-set -n <logger-name> -l <level> The log level was succesfully changed.
In case of error, the error message is "The log level could not be changed.", followed by a detailed message (e.g. "FINER is not a valid log level").
To get all the available loggers, use loggers without any argument.
petals-cli@host:port> loggers logger1 logger2 ...
You can also use a regular expression to filter the candidate results.
petals-cli@host:port> loggers -p <regular expression> logger1 logger2 ...
| Auto-completion is available on logger names and log levels. |
Working with the Service Registry
 | Qualified names, like service and interface names, are written as follows:{namespace-uri}local-part. |
Synchronizing the registry
A synchronization of the registry on a specific node can be done with the 'registry-sync' command:
> registry-sync Synchronization is done
A synchronization of all the topology nodes can be done with the same command and the '-a' argument.
> registry-sync -a <Progress Report (as a percentage)> Synchronization is done
| Global synchronization is done in two passes:
|
The response message is displayed in console mode only.
Showing the registry's full content
The full content of the registry can be dumped by using the 'registry-list' command:
petals-cli> registry-list Endpoints: <endpoint-name-1>: <endpoint-1-characteristics> <endpoint-name-2>: <endpoint-2-characteristics> Services: <service-name-1>: <endpoints-list> <service-name-2>: <endpoints-list> Interfaces: <interface-name-1>: <endpoints-list> <interface-name-2>: <endpoints-list>
where:
- <endpoint-name-x> is an endpoint name.
- <endpoint-x-characteristics> is the attributes of the endpoint, separated by comma: container identifier, component identifier, endpoint type.
- <service-name-x> is a service name.
- <interface-name-x> is an interface name.
- <endpoints-list> is the list of endpoint name implementing the interface or service.
Filtering the registry's full content
The content of the registry can be dumped by using the 'registry-list' command.
It is however possible to filter the dumped result.
petals-cli> registry-list \[-e <endpoint-name-regexp>\] \[-s <service-name-regexp>\] \[-i <interface-name-regexp>\] Endpoints: <endpoint-name>: <endpoint-characteristics> Services: <service-name-1>: <endpoint-name> <service-name-2>: <endpoint-name> Interfaces: <interface-name-1>: <endpoint-name> <interface-name-2>: <endpoint-name>
where:
- <endpoint-name-regexp> is a regular expression used as filter on the full end-point name.
- <service-name-regexp> is a regular expression used as filter on the full service name.
- <interface-name-regexp> is a regular expression used as filter on the full interface name.
In the result:
- <endpoint-name> is the endpoint name.
- <endpoint-characteristics> is the attributes of the endpoint, separated by comma: container identifier, component identifier, endpoint type.
- <service-name-x> is the services associated to the specified endpoint.
- <interface-name-x> is the interface names associated with the specified endpoint.
The parameter order (endpoint, service, interface) does not matter.
All are optional. If none is specified, the entire regitry content is dumped.
System Commands
Petals CLI can directly execute system commands.
To achieve it, the system command is an argument of the 'system' command.
petals-cli> system <system-command>
As an example,
petals-cli> system pwd
displays the directory in which Petals CLI runs.
The return code of the wrapping command is the return code of the system command.