[jboss-dev-forums] [JBoss AS7 Development] - Command Line Interface

[Alexey Loubyansky]

Alexey Loubyansky [http://community.jboss.org/people/aloubyansky] modified the document:

"Command Line Interface"

To view the document, visit: http://community.jboss.org/docs/DOC-16581

--------------------------------------------------------------
The AS7 Command Line Interface (CLI) is a command line management tool for the AS 7 domain or a standalone server. It allows a user to connect to the AS7 domain controller or a standalone server and execute management operations available through the  http://community.jboss.org/docs/DOC-16317 AS7 detyped management model. Depending on the operation system, the CLI is launched using jboss-admin.sh or jboss-admin.bat located in the AS7 bin directory.

h2. Features

The CLI features include:
* connect to the specific controller or server instance by specifying the host and the port;
* send operation requests (providing the managed component's address, attribute or operation name and parameters) following the  http://community.jboss.org/docs/DOC-16317 AS7 detyped management model;
* view the available managed components, their attributes and operations;
* tab-completion for commands and operation requests;
* history of the executed commands and operation requests.


h2. Commands

There are commands and operations. Commands don't trigger server management actions, they are performed locally and may affect only the command line session settings. Operations, on the other hand, are actually translated into the operation requests and sent for the execution to the server.

To see all the commands and their description, enter command +help+. Another way to list all the supported commands is to press the tab key at the command line prompt which will trigger the tab-completion for the commands.

h3. Connection

The first thing to do after the CLI has started is to connect to a managed AS7 instance. This is done using the command +connect+, e.g.

+connect+

which is equivalent to

+connect localhost:9999+

localhost:9999 is the default host and port combination for the AS7 model controller client. Both, the host and the port, are optional parameters and can be specified together or separately.

h3. Quit

To terminate the session type +quit+.

h2. Operation requests

The format for the operation requests is

[node-type=node-name (,node-type=node-name)*] : operation-name [( [parameter-name=parameter-value (,parameter-name=parameter-value)*] )]

e.g.

profile=production,subsystem=threads,bounded-queue-thread-pool=pool1:write-core-threads (count=0, per-cpu=20)

It's a lot of typing but tab-completion is supported for all the composing parts, i.e. node-types and node-names, operation names and parameter names. We are also looking into adding custom commands/aliases that would be less verbose for the user but would translate into the corresponding operation requests on the background.

Whitespaces between the separators in the operation request strings are not significant.

Operation requests might not always have the address part or the parameters. E.g.

+:read-resource+

which will list all the node types for the current node.

To syntactically disambiguate between the commands and operations, operations require one of the following prefixes:

* +:+ - to execute an operation against the current node, e.g.

+[subsystem=web] :read-resource(recursive="true")+
+
+
* +./+ - to execute an operation against a child node of the current node, e.g.

+[subsystem=web] ./connector=http:read-resource+

i.e. the full address of the operation will be +subsystem=web,connector=http+.

* +/+ - to execute an operation against the root node, e.g.

+[subsystem=web] /:read-resource+

or its child, e.g.

+[subsystem=web] /subsystem=logging:read-resource+


h3. How the tab-completion works

Suppose, the cursor is positioned at the beginning of an empty line. If you type in +'./'+ and press the tab key, you will get a list of all the available node types. After selecting the node type you want and adding '=', pressing the tab key again will result in a list of all the node names available for the chosen node type. If, after selecting the node name from the list, you want to continue with the node path then add ',' after the selected node name and press the tab key again. This will print all the available node types for the previously select node.

After you are done with the node path, adding ':' at the end of the node path and pressing the tab key will print all the available operation names for the selected node.

To see all the parameters of the operation, add '(' after the operation name and press the tab key. Choose the parameter you want and specify its value after '='. Tab-completion for parameter values is not supported (yet?). If you want to add more parameters, add ',' and press the tab key to see the rest of the available parameter names.

Finally, when all the parameters have been specified, add ')' and press enter.

In the node path you can use the following strings for navigations:
* .. - parent node, e.g.

+[/] ./subsystem=web/../subsystem=transactions+

is equivalent to

+[/] ./subsystem=transactions+


* +.type+ - the type of the current node, e.g.

+[/] ./subsystem=web/.type/transactions+

is equivalent to the same

+[/] ./subsystem=transactions+



h2. Node path prefix

If you want to execute a series of operations against the same node, to avoid typing the same node path for every operation request you can set the current node path prefix to the target node using command +cn+ (change node) or its alias ++  +cd+, e.g.

+[/]cd subsystem=web+

After that the command line prompt will change to

+[subsystem=web]+

and every operation entered w/o the node path will be executed against the node subsystem=web. If you do specify a node path for the operation, it will be considered relative to subsystem=web.

The prefix might not necessarily end on a node name. It might be just

+[/] cd subsystem+
+[subsystem]+

Then to execute an operation against the logging subsystem you would type in

+[subsystem] logging:read-resource+

To reset the current prefix type in

+[subsystem] cd /+
+[/]+

You can also navigate to the parent node

+[subsystem=web,connector=http] cd ..+
+[subsystem=web]+

or the node type

+[subsystem=web] cd .type+
+[subsystem]+


h2. 
TODOs
* the node path tab-completion isn't supported for the argument of '/to' at the moment.

h2. 
Ideas for features and improvements
* custom aliases/commands for existing commands and operations (too avoid verbosity)
* command/operation output redirection, e.g. operation > file, operation < file
* report operation results nicer (success shorter, failure with more details)
* an easy way to get an operation description, e.g. 'help operation-name'
--------------------------------------------------------------

Comment by going to Community
[http://community.jboss.org/docs/DOC-16581]

Create a new document in JBoss AS7 Development at Community
[http://community.jboss.org/choose-container!input.jspa?contentType=102&containerType=14&container=2225]
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.jboss.org/pipermail/jboss-dev-forums/attachments/20110311/6bb2bc61/attachment.html