JMXAccessorTask (Apache Tomcat 8.5.89 API Documentation)

Package org.apache.catalina.ant.jmx

## Class JMXAccessorTask

- java.lang.Object
- - org.apache.tools.ant.ProjectComponent
  - - org.apache.tools.ant.Task
    - - org.apache.catalina.ant.BaseRedirectorHelperTask
      - - org.apache.catalina.ant.jmx.JMXAccessorTask

- All Implemented Interfaces:
    `java.lang.Cloneable`
  Direct Known Subclasses:
    `JMXAccessorCreateTask`, `JMXAccessorGetTask`, `JMXAccessorInvokeTask`, `JMXAccessorQueryTask`, `JMXAccessorSetTask`, `JMXAccessorUnregisterTask`

      public class JMXAccessorTask
      extends BaseRedirectorHelperTask

  Access JMX JSR 160 MBeans Server.
  - open more then one JSR 160 rmi connection
  - Get/Set Mbeans attributes
  - Call Mbean Operation with arguments
  - Argument values can be converted from string to int,long,float,double,boolean,ObjectName or InetAddress
  - Query Mbeans
  - Show Get, Call, Query result at Ant console log
  - Bind Get, Call, Query result at Ant properties
  Examples: open server with reference and authorisation

          <jmxOpen
                  host="127.0.0.1"
                  port="9014"
                  username="monitorRole"
                  password="mysecret"
                  ref="jmx.myserver"
              />

  All calls after opening with same refid reuse the connection.

  First call to a remote MBeanserver save the JMXConnection a referenz jmx.server

  All JMXAccessorXXXTask support the attribute if and unless. With if the task is only execute when property exist and with unless when property not exists.
  NOTE : These tasks require Ant 1.6 or later interface.
  Since:
    5.5.10
  Author:
    Peter Rossbach

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static java.lang.String` | `JMX_SERVICE_PREFIX` |
    `static java.lang.String` | `JMX_SERVICE_SUFFIX` |

    - ### Fields inherited from class org.apache.catalina.ant.BaseRedirectorHelperTask

      `alwaysLog, failOnError, redirectErrStream, redirector, redirectorConfigured, redirectorElement, redirectOutput, redirectOutStream`

    - ### Fields inherited from class org.apache.tools.ant.Task

      `target, taskName, taskType, wrapper`

    - ### Fields inherited from class org.apache.tools.ant.ProjectComponent

      `description, location, project`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `JMXAccessorTask()` |

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static javax.management.MBeanServerConnection` | `accessJMXConnection​(org.apache.tools.ant.Project project, java.lang.String url, java.lang.String host, java.lang.String port, java.lang.String username, java.lang.String password, java.lang.String refId)` | Get Current Connection from ref parameter or create a new one!
    `protected java.lang.Object` | `convertStringToType​(java.lang.String value, java.lang.String valueType)` | Convert string to datatype FIXME How we can transfer values from ant project reference store (ref)?
    `static javax.management.MBeanServerConnection` | `createJMXConnection​(java.lang.String url, java.lang.String host, java.lang.String port, java.lang.String username, java.lang.String password)` | Create a new JMX Connection with auth when username and password is set.
    `protected void` | `createProperty​(java.lang.Object result)` | create result as property with name from attribute resultproperty
    `protected void` | `createProperty​(java.lang.String propertyPrefix, java.lang.Object result)` | create result as property with name from property prefix When result is an array and isSeparateArrayResults is true, resultproperty used as prefix (`resultproperty.0-array.length` and store the result array length at `resultproperty.length`.
    `protected void` | `echoResult​(java.lang.String name, java.lang.Object result)` |
    `void` | `execute()` | Execute the specified command.
    `java.lang.String` | `getDelimiter()` |
    `java.lang.String` | `getHost()` |
    `java.lang.String` | `getIf()` |
    `protected javax.management.MBeanServerConnection` | `getJMXConnection()` | get JMXConnection
    `java.lang.String` | `getName()` | Get the name used at remote MbeanServer.
    `java.lang.String` | `getPassword()` |
    `java.lang.String` | `getPort()` |
    `java.lang.String` | `getProperty​(java.lang.String property)` | Get Property
    `java.lang.String` | `getRef()` |
    `java.lang.String` | `getResultproperty()` |
    `java.lang.String` | `getUnless()` |
    `java.lang.String` | `getUrl()` |
    `java.lang.String` | `getUsername()` |
    `boolean` | `isEcho()` |
    `boolean` | `isSeparatearrayresults()` |
    `boolean` | `isUseRef()` |
    `java.lang.String` | `jmxExecute​(javax.management.MBeanServerConnection jmxServerConnection)` | Execute the specified command, based on the configured properties.
    `void` | `setDelimiter​(java.lang.String separator)` |
    `void` | `setEcho​(boolean echo)` |
    `void` | `setHost​(java.lang.String host)` |
    `void` | `setIf​(java.lang.String c)` | Only execute if a property of the given name exists in the current project.
    `void` | `setName​(java.lang.String objectName)` |
    `void` | `setPassword​(java.lang.String password)` |
    `void` | `setPort​(java.lang.String port)` |
    `boolean` | `setProperty​(java.lang.String property, java.lang.Object value)` |
    `void` | `setRef​(java.lang.String refId)` |
    `void` | `setResultproperty​(java.lang.String propertyName)` |
    `void` | `setSeparatearrayresults​(boolean separateArrayResults)` |
    `void` | `setUnless​(java.lang.String c)` | Only execute if a property of the given name does not exist in the current project.
    `void` | `setUrl​(java.lang.String url)` |
    `void` | `setUsername​(java.lang.String username)` |
    `protected boolean` | `testIfCondition()` | test the if condition
    `protected boolean` | `testUnlessCondition()` | test the unless condition

    - ### Methods inherited from class org.apache.catalina.ant.BaseRedirectorHelperTask

      `addConfiguredRedirector, closeRedirector, handleErrorFlush, handleErrorOutput, handleFlush, handleOutput, handleOutput, isFailOnError, openRedirector, setAlwaysLog, setAppend, setCreateEmptyFiles, setError, setErrorProperty, setFailonerror, setLogError, setOutput, setOutputproperty`

    - ### Methods inherited from class org.apache.tools.ant.Task

      `bindToOwner, getOwningTarget, getRuntimeConfigurableWrapper, getTaskName, getTaskType, getWrapper, handleInput, init, isInvalid, log, log, log, log, maybeConfigure, perform, reconfigure, setOwningTarget, setRuntimeConfigurableWrapper, setTaskName, setTaskType`

    - ### Methods inherited from class org.apache.tools.ant.ProjectComponent

      `clone, getDescription, getLocation, getProject, setDescription, setLocation, setProject`

    - ### Methods inherited from class java.lang.Object

      `equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### JMX_SERVICE_PREFIX

          public static final java.lang.String JMX_SERVICE_PREFIX

      See Also:
        Constant Field Values

    - #### JMX_SERVICE_SUFFIX

          public static final java.lang.String JMX_SERVICE_SUFFIX

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### JMXAccessorTask

          public JMXAccessorTask()

  - ### Method Detail

    - #### getName

          public java.lang.String getName()

      Get the name used at remote MbeanServer.
      Returns:
        the name used at remote MbeanServer

    - #### setName

          public void setName​(java.lang.String objectName)

    - #### getResultproperty

          public java.lang.String getResultproperty()

      Returns:
        Returns the resultproperty.

    - #### setResultproperty

          public void setResultproperty​(java.lang.String propertyName)

      Parameters:
        `propertyName` - The resultproperty to set.

    - #### getDelimiter

          public java.lang.String getDelimiter()

      Returns:
        Returns the delimiter.

    - #### setDelimiter

          public void setDelimiter​(java.lang.String separator)

      Parameters:
        `separator` - The delimiter to set.

    - #### isEcho

          public boolean isEcho()

      Returns:
        Returns the echo.

    - #### setEcho

          public void setEcho​(boolean echo)

      Parameters:
        `echo` - The echo to set.

    - #### isSeparatearrayresults

          public boolean isSeparatearrayresults()

      Returns:
        Returns the separatearrayresults.

    - #### setSeparatearrayresults

          public void setSeparatearrayresults​(boolean separateArrayResults)

      Parameters:
        `separateArrayResults` - The separatearrayresults to set.

    - #### getPassword

          public java.lang.String getPassword()

      Returns:
        The login password for the `Manager` application.

    - #### setPassword

          public void setPassword​(java.lang.String password)

    - #### getUsername

          public java.lang.String getUsername()

      Returns:
        The login username for the `JMX` MBeanServer.

    - #### setUsername

          public void setUsername​(java.lang.String username)

    - #### getUrl

          public java.lang.String getUrl()

      Returns:
        The URL of the `JMX JSR 160` MBeanServer to be used.

    - #### setUrl

          public void setUrl​(java.lang.String url)

    - #### getHost

          public java.lang.String getHost()

      Returns:
        The Host of the `JMX JSR 160` MBeanServer to be used.

    - #### setHost

          public void setHost​(java.lang.String host)

    - #### getPort

          public java.lang.String getPort()

      Returns:
        The Port of the `JMX JSR 160` MBeanServer to be used.

    - #### setPort

          public void setPort​(java.lang.String port)

    - #### isUseRef

          public boolean isUseRef()

      Returns:
        Returns the useRef.

    - #### getRef

          public java.lang.String getRef()

      Returns:
        Returns the ref.

    - #### setRef

          public void setRef​(java.lang.String refId)

      Parameters:
        `refId` - The ref to set.

    - #### getIf

          public java.lang.String getIf()

      Returns:
        Returns the ifCondition.

    - #### setIf

          public void setIf​(java.lang.String c)

      Only execute if a property of the given name exists in the current project.
      Parameters:
        `c` - property name

    - #### getUnless

          public java.lang.String getUnless()

      Returns:
        Returns the unlessCondition.

    - #### setUnless

          public void setUnless​(java.lang.String c)

      Only execute if a property of the given name does not exist in the current project.
      Parameters:
        `c` - property name

    - #### execute

          public void execute()
                       throws org.apache.tools.ant.BuildException

      Execute the specified command. This logic only performs the common attribute validation required by all subclasses; it does not perform any functional logic directly.
      Overrides:
        `execute` in class `org.apache.tools.ant.Task`
      Throws:
        `org.apache.tools.ant.BuildException` - if a validation error occurs

    - #### createJMXConnection

          public static javax.management.MBeanServerConnection createJMXConnection​(java.lang.String url,
                                                                                   java.lang.String host,
                                                                                   java.lang.String port,
                                                                                   java.lang.String username,
                                                                                   java.lang.String password)
                                                                            throws java.net.MalformedURLException,
                                                                                   java.io.IOException

      Create a new JMX Connection with auth when username and password is set.
      Parameters:
        `url` - URL to be used for the JMX connection (if specified, it is a complete URL so host and port will not be used)
        `host` - Host name of the JMX server
        `port` - Port number for the JMX server
        `username` - User name for the connection
        `password` - Credentials corresponding to the specified user
      Returns:
        the JMX connection
      Throws:
        `java.net.MalformedURLException` - Invalid URL specified
        `java.io.IOException` - Other connection error

    - #### testIfCondition

          protected boolean testIfCondition()

      test the if condition
      Returns:
        true if there is no if condition, or the named property exists

    - #### testUnlessCondition

          protected boolean testUnlessCondition()

      test the unless condition
      Returns:
        true if there is no unless condition, or there is a named property but it doesn't exist

    - #### accessJMXConnection

          public static javax.management.MBeanServerConnection accessJMXConnection​(org.apache.tools.ant.Project project,
                                                                                   java.lang.String url,
                                                                                   java.lang.String host,
                                                                                   java.lang.String port,
                                                                                   java.lang.String username,
                                                                                   java.lang.String password,
                                                                                   java.lang.String refId)
                                                                            throws java.net.MalformedURLException,
                                                                                   java.io.IOException

      Get Current Connection from ref parameter or create a new one!
      Parameters:
        `project` - The Ant project
        `url` - URL to be used for the JMX connection (if specified, it is a complete URL so host and port will not be used)
        `host` - Host name of the JMX server
        `port` - Port number for the JMX server
        `username` - User name for the connection
        `password` - Credentials corresponding to the specified user
        `refId` - The Id of the reference to retrieve in the project
      Returns:
        the JMX connection
      Throws:
        `java.net.MalformedURLException` - Invalid URL specified
        `java.io.IOException` - Other connection error

    - #### getJMXConnection

          protected javax.management.MBeanServerConnection getJMXConnection()
                                                                     throws java.net.MalformedURLException,
                                                                            java.io.IOException

      get JMXConnection
      Returns:
        the JMX connection
      Throws:
        `java.net.MalformedURLException` - Invalid URL specified
        `java.io.IOException` - Other connection error

    - #### jmxExecute

          public java.lang.String jmxExecute​(javax.management.MBeanServerConnection jmxServerConnection)
                                      throws java.lang.Exception

      Execute the specified command, based on the configured properties. The input stream will be closed upon completion of this task, whether it was executed successfully or not.
      Parameters:
        `jmxServerConnection` - The JMX connection that should be used
      Returns:
        An error message string in some situations
      Throws:
        `java.lang.Exception` - if an error occurs

    - #### convertStringToType

          protected java.lang.Object convertStringToType​(java.lang.String value,
                                                         java.lang.String valueType)

      Convert string to datatype FIXME How we can transfer values from ant project reference store (ref)?
      Parameters:
        `value` - The value
        `valueType` - The type
      Returns:
        The converted object

    - #### echoResult

          protected void echoResult​(java.lang.String name,
                                    java.lang.Object result)

      Parameters:
        `name` - context of result
        `result` - The result

    - #### createProperty

          protected void createProperty​(java.lang.Object result)

      create result as property with name from attribute resultproperty
      Parameters:
        `result` - The result
      See Also:
        `createProperty(String, Object)`

    - #### createProperty

          protected void createProperty​(java.lang.String propertyPrefix,
                                        java.lang.Object result)

      create result as property with name from property prefix When result is an array and isSeparateArrayResults is true, resultproperty used as prefix (`resultproperty.0-array.length` and store the result array length at `resultproperty.length`. Other option is that you delimit your result with a delimiter (java.util.StringTokenizer is used).
      Parameters:
        `propertyPrefix` - Prefix for the property
        `result` - The result

    - #### getProperty

          public java.lang.String getProperty​(java.lang.String property)

      Get Property
      Parameters:
        `property` - name
      Returns:
        The property value

    - #### setProperty

          public boolean setProperty​(java.lang.String property,
                                     java.lang.Object value)

      Parameters:
        `property` - The property
        `value` - The value
      Returns:
        True if successful