Opened 50 years ago

Last modified 9 years ago

#870 new task

IZ313: improve output of usage >> options for commands using table output

Reported by: zwierzak Owned by:
Priority: normal Milestone:
Component: hedeby Version: 1.0
Severity: Keywords: Sun cli
Cc:

Description

[Imported from gridengine issuezilla http://gridengine.sunsource.net/issues/show_bug.cgi?id=313]

        Issue #:      313          Platform:     Sun         Reporter: zwierzak (zwierzak)
       Component:     hedeby          OS:        All
     Subcomponent:    cli          Version:      1.0            CC:    None defined
        Status:       NEW          Priority:     P3
      Resolution:                 Issue type:    TASK
                               Target milestone: 1.0u5next
      Assigned to:    adoerr (adoerr)
      QA Contact:     adoerr
          URL:
       * Summary:     improve output of usage >> options for commands using table output
   Status whiteboard:
      Attachments:


     Issue 313 blocks:
   Votes for issue 313:     Vote for this issue


   Opened: Thu Jan 17 09:50:00 -0700 2008 
------------------------


   when I look at usage output for commands that are using table output

   >> Usage: sdmadm [global_options] remove_service|rs [-dupval] [-noheader]
   [-force] [-sort
   >> columns] [-coldel char] [-headerdel char] [-h host_name] [-s service_name] [-hlp]
   >>

   I hardly see important options.... we should somehow group those options first
   "funcional" options like -s service name -h hostname and in the end ....table
   formatting options
               ------- Additional comments from adoerr Thu May 1 12:42:40 -0700 2008 -------
   Does not affect proper functioning of the system. Changed issue type to "TASK".

               ------- Additional comments from rhierlmeier Tue Aug 5 04:02:13 -0700 2008 -------
   This issues is still valid and easys to fix. We should fixed it.
               ------- Additional comments from afisch Tue Aug 12 09:40:32 -0700 2008 -------
   Description:
   The usage output for commands that are using table output is not sorted
   properly. A grouping of options would be helpful.

        Usage: sdmadm [global_options] remove_service|rs [-dupval]
   [-noheader][-force] [-sort columns] [-coldel char] [-headerdel char] [-h
   host_name] [-s service_name] [-hlp]


   Evaluation:
   This issue is considered to be a p3 task because it just addresses usability and
   does not alter any function.


   Suggested Fix/Work Around:
   A reasonable grouping would be:

       [global_options] <command name>|<command short cut> [primary command
   options] [table options][-hlp]
   eg:

       Usage: sdmadm [global_options] remove_service|rs [-h host_name] [-s
   service_name] [-force] [-sort columns] [-coldel char] [-headerdel char]
   [-dupval] [-noheader] [-hlp]

   The problem would be subdivided into sorting of options of one class and sorting
   of the option groups per class.


   Analysis:
   The problem is located in the class
   com.sun.grid.grm.cli.AbstractCli:getCommandUsageText()

           List<Field> fields = getAnnotatedFields(commandClass);

   Here all annotated fields that represent options are extracted. It seems that
   there is no explicit order to extract the options. In the example in the
   description -force is listed in between of -noheader and -sort. However,
   although there might be a sorting rule present it might be useful to arrange the
   sorting in an explict manner. Three solutions would be feasable to solve the
   problem:

   1.) A very simple solution would be to define a reference order for all commands
   as a hard coded list and sort the fields list according to this order. This
   would imply that every option (later added option) has to be sorted into the
   reference list.  The extraction of all options could be done automatically. The
   advantage of this solution would be that there is a central location to address
   the order issue, the suborder within a class level could be addressed and the
   list might provide a nice overview to check for naming collisions.

   2.) To separate the table options from the rest it would be sufficient to
   extract the com.sun.grid.grm.cli.table.AbstractTableCliCommand options in a
   separate list and remove the intersection from the fileds list. Then all options
   could be shown separated.
   To apply this idea more generally this could be done by iterating through the
   inheritance hierarchy, starting with the most general super class and constantly
   adding fields not added jet. Finally the -hlp option should be moved to the end
   of the list if present. This approach would be very generic but it would not
   allow to sort the commands defined on a separate class level.


   3.) Another solution would be to extend the the
   com.sun.grid.grm.cli.CliOptionDescriptor with method:

       /**
        * the set of available command options are sorted according to their
   optionPositions
        */
       int optionPosition() default -1;

   The option position should be set as follows:
       The -hlp option should have the optionPosition 0;
       AbstractTable command options should have a low value range (e.g. 10-50)
       normal command options should have a medium range (e.g. 51-100)
   This would allow to sort the fields list according to this optionPosition in
   descending order. The options order with no explict optionPosition specified
   would remain as all command have the default optionPosition -1.
   If the optionPositions are specified in the above manner the order would be
   <global options> command <specific options> <tale options> <hlp option> and
   within their specific range according to their value. Commands with no explicit
   range would be appended to the set of sorted options in arbritrary order.
   However, the solution would require to change all existing command classes and
   the order aspect would be spread over all commands.

   How to test:
   A jUnit test should be written that instanciate a remove_service_command object.
   The usage promt should be compared with a hard coded reference usage message for
   the command that ha s a sorted option list.

   If solution 1.) or 3.) is implemented, a second JUnit test should be written
   that gathers the field variables from the complete project.
   In case of solution 1.) The list should be compared with the reference list for
   completenes.
   In case of solution 3.) The list should be used to find out whether all
   optionPosition fields are explicitly set (!=-1).


   ETC:
   2 PD
               ------- Additional comments from afisch Wed Aug 13 05:48:11 -0700 2008 -------
   @Analysis
   The current sorting of the options is done in
   com.sun.grid.grm.cli.AbstractCli.buildOptionLine first according to the  option
   type classification (optionalBool, nonOptional and optional) and then within the
   class alphanumerically.

   The alphanumerical sorting is done in line 969  with:

       return o1.name().compareTo(o2.name());

   Here it would be better to sort it with the following line as the names of the
   fields are translated with the corresponding resource bundle:

       return getName(fieldMap.get(o1)).compareTo(getName(fieldMap.get(o2)));

   This should be kept in mind when an alphanumerical subsorting is considered.
               ------- Additional comments from rhierlmeier Wed Nov 25 07:21:10 -0700 2009 -------
   Milestone changed

Change History (0)

Note: See TracTickets for help on using tickets.