Issue 979 - enhanced help (add bean descriptions, att descriptions, and interactive mode)

[tbarnes-us]

Enhance WDT help to:

• Expand help for a folder:
  -- Show the bean help for a folder, when available, at the end of the folder help.
  -- Append the "alias offline" default value, when available, for each attribute listed in a folder.
  -- Append a "+" at the end of an attribute line when detailed help is available for the attribute.

• Provide help for particular attributes:
  -- Instead of generating a 'not a folder' error when specifying a path that ends in an attribute:
  -- Show bean help and the "alias offline" default value for the attribute.
  -- List the legal values for the attribute if it is an enumerated type.

• Support an interactive mode.
  -- Get the help for multiple attributes and folders using commands like "cd", "ls", "help", and "top".

Examples:

Show known defaults for each attribute listed in a folder:

(Note that this also appends a "+" if full help is available for a particular att.)

$ modelHelp.sh resources:/JMSServer

Attributes and sub-folders for resources:/JMSServer

resources:
    JMSServer:
        'JMSServer-1':
            AllowsPersistentDowngrade:         # boolean           (default=false) +
            BlockingSendPolicy:                # string            +
            BytesMaximum:                      # long              (default=-1) +
            BytesPagingEnabled:                # boolean           (default=false) +
            ... snip ...

            JmsMessageLogFile:
                # see /JMSServer/JmsMessageLogFile

            JmsSessionPool:
                'JmsSessionPool-1':
                    # see /JMSServer/JmsSessionPool

This class represents a JMS server. A JMS server manages connections 
and message requests on behalf of clients.

Show help for a particular attribute of a folder:

modelHelp.sh topology:/Server/Log/StdoutSeverity

Attributes and sub-folders for topology:/Server/Log/StdoutSeverity

topology:
    Server:
        'Server-1':
            Log:
                StdoutSeverity: # string

Default=Notice
Legal values: 
   'Trace'
   'Debug'
   'Info'
   'Warning'
   'Error'
   'Notice'
   'Critical'
   'Alert'
   'Emergency'
   'Off'


The minimum severity of log messages going to the standard out. 
Messages with a lower severity than the specified value will 
not be published to standard out.

Access interactive help starting at directory 'top':

modelHelp.sh -interactive top

In interactive mode! Type 'help' for help.
[top] --> help

Commands:

  ls                      - list contents of current location
  top, cd, cd /, cd top   - go to "top"
  cd x[/[...]]            - relative change (go to child location x...)
  cd section[:/[...]]     - absolute change (go to exact section and location)
  cd /folder[/...]        - find section that contains the folder and go there
  cd ..                   - go up
  history                 - history of visited locations
  exit                    - exit

Sections:

  domainInfo, topology, resources, appDeployments, kubernetes

Examples:

  cd topology
  cd topology:/Server/Log/StdoutSeverity
  cd /Server/Log/StdoutSeverity

[top] --> 

[robertpatrick]

I still want to play with it to see what the output looks like but, in general, the changes look fine to me (other than the specific comments I left).

The one philosophical question we as a team need to decide is do we like setting online_mbean to unknown explicitly or should we just omit the attribute entirely when it is unknown/not relevant? In general, we have tended to omit attributes rather than setting them when they aren't providing useful information. It seems like unknown just means there is no information so that same thing could be achieved by simply omitting the attribute.

[robertpatrick]

Just a general comment but I think we try to keep the class organized so that methods of the same visibility and scope are grouped together. For example:

• public static
• static
• private static

All utility classes should generally have a private constructor to prevent developers from accidentally trying to instantiate it. I suspect Sonar will flag some of these issues...

[tbarnes-us]

Fixed

[robertpatrick]

Kudos, SonarCloud Quality Gate passed!   

0 Bugs 0 Vulnerabilities 0 Security Hotspots 110 Code Smells

20.6% Coverage 0.0% Duplication

[robertpatrick]

The 110 new code smells in Sonar also need to be cleaned up as much as is possible.

Edit: Fixed.

[robertpatrick]

@ddsharpe can we decide if we want to explicitly set the value to unknown or omit the attribute to indicate that the value is unknown? It seems like omitting it is more consistent with the approach we take in the aliases so I think it is worth a quick discussion.

[tbarnes-us]

In my opinion, "unknown" is easier to search for. Useful for finding entries that perhaps can be fixed with a bit more manual research. We could also put in "NotApplicable" or some-such for those that are known to have no corresponding mbean...

[tbarnes-us]

Derek and Richard both agree with you. So by popular demand:

• replaced a few of the unknowns with their bean after a bit of research
• removed the remaining unknown unknowns

Fixed

[ddsharpe]

The following command prints the attributes and folders for the Server MBean:
modelHelp.sh /Server
The following command leaves the interactive code in an unknown state where commands like ls fail:
modelHelp.sh -interactive /Server

[ddsharpe]

interactive and the normal command model path should work the same.

[tbarnes-us]

The following command prints the attributes and folders for the Server MBean:
modelHelp.sh /Server
The following command leaves the interactive code in an unknown state where commands like ls fail:
modelHelp.sh -interactive /Server
interactive and the normal command model path should work the same.

@ddsharpe Good catch.

Fixed.

[sonarqubecloud]

Kudos, SonarCloud Quality Gate passed!   

0 Bugs
0 Vulnerabilities
0 Security Hotspots
0 Code Smells

21.6% Coverage
0.0% Duplication