Version 2
Created by aloubyansky on Jul 1, 2011 9:50 AM. Last modified by aloubyansky on Nov 10, 2011 5:29 PM.

    A type generic command is a command that is assigned to a specific node type and which allows to perform any operation and/or modify any of the properties exposed by the type on any existing instance of that type.

     

    For example, suppose there is a generic type command assigned to type /subsystem=datasources/data-source and is named data-source. Now using data-source command we can invoke any operation available for children of /subsystem=datasources/data-source and modify any of their properties (that have access-type read-write). The only thing left is to identify the target datasource instance. The way the target is identified depends on a specific command but can be either:

    - by choosing one of the read-only properties exposed by the type to be the identifying property;

    - by using the name if the instance, i.e. the last node name in the complete node path of the target instance.

     

    In case of the data-source, let's say we decided to use the jndi-name property as the identifying property.

     

    Now you can invoke operations on data sources like this

    {code}
    [standalone@localhost:9999 /] data-source flush-all-connection-in-pool --jndi-name=myds{code}

     

    flush-all-connection-in-pool is an operation name which is exposed by the management model for all datasources and jndi-name argument identifies the datasource flush-all-connection-in-pool should be performed on.

     

    (If we didn't choose jndi-name or any other property as the identifying one then we would have to use the name, i.e. the second way of the identification

    {code}
    [standalone@localhost:9999 /] data-source flush-all-connection-in-pool --name=myds{code}

    )

     

    If the operation we want to perform requires properties, the properties can be added as command line arguments, i.e. here is an example of adding a new datasource

    {code}
    [standalone@localhost:9999 /] data-source add --jndi-name=myds --driver-name=h2 --pool-name=myds-pool --connection-url=curl{code}

     

    add is an operation name and the argument names match the operation property names prefixed with '--'.

     

    Node properties can be modified in a similar way. Property names prefixed with '--' become arguments names. Except here we don't need an operation name, just the identifying property, i.e. the jndi-name in our case (which is a read-only property). E.g.

     

    {code}[standalone@localhost:9999 /] data-source --jndi-name=myds --min-pool-size=11 --max-pool-size=22{code}

     

    The examples above are actually for standalone mode. Commands that handle resources whose node paths don't depend on a specific mode (standalone or domain) will also have no differences in either mode. But if the target resource's node path, like the data-source's, will require the profile part in the domain mode, the command will require one more argument - --profile. E.g.

     

    {code}[domain@localhost:9999 /] data-source --profile=default --jndi-name=myds --min-pool-size=11 --max-pool-size=22{code}

     

    Getting help

     

    Generic type commands support --help option. The help content is generated for each command with data pulled from the management model and is based on the descriptions of the node type, operations and properties it exposes. E.g.

    {code}
    [domain@localhost:9999 /] data-source --help
     
    SYNOPSIS
     
    data-source --help [--properties | --commands] |
                --jndi-name=<value> --<property>=<value> (--<property>=<value>)* |
                <command> --jndi-name=<value> (--<parameter>=<value>)*
     
    DESCRIPTION
     
    The command is used to manage resources of type /subsystem=datasources/data-source.
     
    RESOURCE DESCRIPTION
     
    (Execute 'data-source --profile=<profile_name> --help' to include the resource description here.)
     
    ARGUMENTS
     
    --help                - prints this content.
    --help --properties   - prints the list of the resource properties including their access-type
                            (read/write/metric), value type, and the description.
    --help --commands     - prints the list of the commands available for the resource.
                            To get the complete description of a specific command (including its parameters,
                            their types and descriptions), execute data-source <command> --help.
     
    --jndi-name   - corresponds to a property of the resourse which 
                    is used to identify the resourse against which the command should be executed.
     
    <property>   - property name of the resourse whose value should be updated.
                   For a complete list of available property names, their types and descriptions,
                   execute data-source --help --properties.
     
    <command>    - command name provided by the resourse. For a complete list of available commands,
                   execute data-source --help --commands.
     
    <parameter>  - parameter name of the <command> provided by the resourse.
                   For a complete list of available parameter names of a specific <command>,
                   their types and descriptions, execute data-source <command> --help.
    {code}

     

    Note, since the command was executed in the domain mode, the resource type description is missing. It couldn't be fetched since the resourc'e path requires the profile specification. If you add --profile argument with the target profile name the description will be complete.

    In the standalone mode, the description will appear complete by default.

     

    The following wil list all the properties and their descriptions (datasources hava lots of properties, so I'll paste only an exerpt here)

    {code}[standalone@localhost:9999 /] data-source --help --properties
     --jndi-name             - (STRING,read-write) Specifies the JNDI name for the datasource. Required argument in commands which identifies the instance to execute the command against.
     --connection-url        - (STRING,read-write) The JDBC driver connection URL
     --driver-name           - (STRING,read-write) Defines the JDBC driver the datasource should use. It is a symbolic name matching the the name of installed driver. In case the driver is deployed as jar, the name is the name of deployment unit
     --pool-name             - (STRING,read-write) Specifies the pool name for the datasource used for management
     --driver-class          - (STRING,read-write) The fully qualifed name of the JDBC driver class.
    {code}

     

    And this is how to list the operations that can be invoked on an instance of the type (btw, this list excludes some operations like

    read-attribute, read-children-names, read-children-resources, read-children-types, read-operation-description, read-operation-names, read-resource, read-resource-description, validate-address, write-attribute)

    {code}
    [standalone@localhost:9999 /] data-source --help --commands
    add
    disable
    enable
    flush-all-connection-in-pool
    flush-idle-connection-in-pool
    remove
    test-connection-in-pool
    To read the description of a specific command execute 'data-source command_name --help'.{code}

     

    Here is an example of the add operation description (again, it accepts a lot of properties, most of which are optional, so I paste only an exerpt of the complete description here)

    {code}
    DESCRIPTION:
     
    Adds a new data-source
     
     
    REQUIRED ARGUMENTS:
     
     --jndi-name                 - (STRING) Specifies the JNDI name for the datasource. Required argument in commands which identifies the instance to execute the command against.
     --connection-url            - (STRING) The JDBC driver connection URL
     --driver-name               - (STRING) Defines the JDBC driver the datasource should use. It is a symbolic name matching the the name of installed driver. In case the driver is deployed as jar, the name is the name of deployment unit
     --pool-name                 - (STRING) Specifies the pool name for the datasource used for management
     
     
    OPTIONAL ARGUMENTS:
     
     --driver-class              - (STRING) The fully qualifed name of the JDBC driver class
     --datasource-class          - (STRING) The fully qualifed name of the JDBC datasource class
     --new-connection-sql        - (STRING) Specifies an SQL statement to execute whenever a connection is added to the connection pool.
    {code}

    Managing commands

     

    Generic type commands can be added and removed at runtime. There is a command called 'command' which can add new, list and remove existing generic type commands (but not other commands). For example

    {code}
    [standalone@localhost:9999 /] command list
    jms-queue            data-source          connection-factory   xa-data-source       jms-topic
    {code}

     

    To add a new command, you need to identify the node type, choose the identifying property and the name for the command. E.g.

    {code}
    [standalone@localhost:9999 /] command add --node-type=subsystem=resource-adapters/resource-adapter --property-id=archive --command-name=resource-adapter
    [standalone@localhost:9999 /] command list
    jms-queue            data-source          connection-factory   xa-data-source       jms-topic        resource-adapter{code}

     

    Now there is resource-adapter command which can be used as any other CLI command, e.g.

    {code}
    [standalone@localhost:9999 /] resource-adapter --help --commands
    add
    flush-all-connection-in-pool
    flush-idle-connection-in-pool
    remove
    test-connection-in-pool
    To read the description of a specific command execute 'resource-adapter command_name --help'.{code}

     

    The command can be remove like this

     

    {code}
    [standalone@localhost:9999 /] command remove --command-name=resource-adapter
    [standalone@localhost:9999 /] command list                                  
    data-source{code}

     

    NOTE: chnages made to generic type commands don't survive CLI restart yet.