Bug 738063

Summary: CLI Documentation example doesn't show full usage() method
Product: [Other] RHQ Project Reporter: Nabeel Saad <nsaad>
Component: DocumentationAssignee: Deon Ballard <dlackey>
Status: CLOSED CURRENTRELEASE QA Contact: Mike Foley <mfoley>
Severity: low Docs Contact:
Priority: high    
Version: unspecifiedCC: gcooper, hrupp, jsanda, mfoley
Target Milestone: ---   
Target Release: ---   
Hardware: All   
OS: All   
Whiteboard:
Fixed In Version: Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of: Environment:
Last Closed: 2013-09-01 15:20:28 EDT Type: ---
Regression: --- Mount Type: ---
Documentation: --- CRM:
Verified Versions: Category: ---
oVirt Team: --- RHEL 7.3 requirements from Atomic Host:
Bug Depends On:    
Bug Blocks: 625146    
Attachments:
Description Flags
copy of script referenced in the bug none

Description Nabeel Saad 2011-09-13 14:50:56 EDT
Description of problem:
In the documentation (http://docs.redhat.com/docs/en-US/JBoss_Operations_Network/2.4/html-single/CLI_Guide/index.html), under section "4.1. Creating the Script", there is reference to a JavaScript function called usage(), but we never get to see the code of this function.

I am not explicitly interested in the code that will specify do a println or something, but in the code that actual "quits" the JavaScript script/function.  As I have tried putting the following in my script unsuccessfully:
 - quit;: ScriptException: "quit" is not defined
 - return;: ScriptException: invalid return (when in the body of the script)
 - return;: works when in a function, but how do you get it to completely exit if the result of the current function is an error or a scenario to quit
 - throw("text");: works, but I don't want to show a stack trace to my users

Version-Release number of selected component (if applicable):
JON 2.4.1

How reproducible:
Everytime - in the documentation

Steps to Reproduce:
1. Go to http://docs.redhat.com/docs/en-US/JBoss_Operations_Network/2.4/html-single/CLI_Guide/index.html
2. Find section "4.1. Creating the Script"
3. Notice the function usage () specified, if you search through the entire document, you will not find a definition of the usage () function.  [Note: There is a usage () function defined under section "5.1. Creating the Wrapper Script", but that is a shell script function, not a JavaScript function]
  
Actual results:
No definition of usage()

Expected results:
Would like to see the code in the usage() function

Additional info:
Comment 1 Deon Ballard 2011-10-18 23:03:27 EDT
I am pretty certain that this example was originally on the RHQ wiki -- but I can't find it there. The only community procedure I see like this is on the jboss.org wiki: 
http://community.jboss.org/wiki/JON23ScriptedGroupDeploymentsUsingTheCLIAPI

Which references this section in the 2.3 docs (which does *not* contain the usage() thing):
http://docs.redhat.com/docs/en-US/JBoss_Operations_Network/2.3/html/Installation_Guide/Installation_Guide-Working_with_the_CLI-Script_Arguments.html

So, I don't have a clue what usage() is doing. 

Sanda, do you know 1) what the usage() function is doing in this example and 2) if this is the right function to use?
Comment 2 John Sanda 2011-10-19 00:44:51 EDT
I will try to track down that script, but I am almost certain it is a function defined within that script. There is no usage function or API of which I am aware that we support.

If I understand the bug description correctly, Nabeel is asking for a way to terminate a script other than throwing an exception. This can be accomplished simply by calling java.lang.System.exit which takes an integer argument.

For more information about regarding integration with the underlying Java platform, take a look at the docs at http://www.mozilla.org/rhino/doc.html. 

Lastly, it would be great if questions like these could be directed to the rhq mailing lists and/or the community forums so that they reach a wider audience.
Comment 3 John Sanda 2011-10-19 09:21:46 EDT
Created attachment 529002 [details]
copy of script referenced in the bug

I believe that this is the script being referenced. Please note that I did not write this script so I may not be able to answer all questions about it. You will find that the script does define a usage function.

I just checked and the RHQ CLI does provide a quit command from the interactive shell, but I am almost certain that the quit command is not available in non-interactive mode. Please feel free to file a separate bug for that if you would like to see that added. Until then, you can use java.lang.System.exit as I stated previously.
Comment 4 Nabeel Saad 2011-10-19 12:14:31 EDT
Thank you John, yes I believe the java.lang.System.exit should provide what's needed.

I did also find that by creating functions within my JS scripts, I could have them do a "return" and then handle things from there so that I do not throw errors, but informative text with steps to fix the problem.

Many thanks, you can feel free to close this bug.  Is there any way the script that you attached can be added into some example files provided with JON or somehow referenced in the docs or put in the docs as an appendix, I prove it can be quite useful for people starting out.

Cheers,
Nabeel
Comment 5 Deon Ballard 2011-10-24 11:03:23 EDT
*** Bug 744004 has been marked as a duplicate of this bug. ***
Comment 6 Deon Ballard 2012-06-28 13:33:02 EDT
Hopefully, this is clarified in the intro to the chapter here:
http://docs.redhat.com/docs/en-US/JBoss_Operations_Network/3.1/html/Dev_Writing_JON_Command-Line_Scripts/Control_Grouped_Servers_via_the_CLI.html
Comment 7 Heiko W. Rupp 2013-09-01 15:20:28 EDT
Bulk closing of BZs that have no target version set, but which are ON_QA for more than a year and thus are in production for a long time.