Uploaded image for project: 'OpenDJ'
  1. OpenDJ
  2. OPENDJ-6652

Prevent configuration properties syntax details to be duplicated in the description

    Details

    • Type: Task
    • Status: Dev backlog
    • Priority: Major
    • Resolution: Unresolved
    • Affects Version/s: 7.0.0
    • Fix Version/s: None
    • Component/s: config, tools
    • Labels:
      None

      Description

      About affected version

      Tagged 7.0 but previous versions are probably affected as well.

      The problem

      Today, when we define a property with a non trivial syntax, we have to help the user understanding the syntax so that he can enter valid values, see the second paragraph in the dsconfig output example below:

      >>>> Configuring the "bootstrap-replication-server" property
      
          The addresses of one or more replication servers within the topology which
          this server should connect to and discover the rest of the topology.
      
          Addresses must be specified using the replication port of the remote
          replication servers using the syntax "hostname:port". When using an IPv6
          address as the hostname, put brackets around the address as in
          "[IPv6Address]:port".
      
          Syntax:  HOST:PORT
      
      Do you want to modify the "bootstrap-replication-server" property?
      
          1)  Keep the default behavior: Adding a replication server or a replication
              domain requires this to be filled.
          2)  Add one or more values
      
          q)  quit
          ?)  help
      
      Enter choice [1]: 
      

      In order to have the syntax detail printed, we must add the text into the description of the associated property, e.g:

        <adm:property name="bootstrap-replication-server" multi-valued="true">
          [...]
          <adm:description>
            Addresses must be specified using the replication port of the remote replication servers
            using the syntax "hostname:port".
            When using an IPv6 address as the hostname, put brackets around the address as in "[IPv6Address]:port".
          </adm:description>
          [...]
        </adm:property>
      

      This becomes a problem when we have multiple properties using the same complex syntax, since we have to duplicate the syntax detail in each property description (for example in StaticServiceDiscoveryMechanismConfiguration.xml:

        <adm:property name="primary-server" multi-valued="true">
          [...]
          <adm:description>
            When using an IPv6 address as the hostname, put brackets around the address as in "[IPv6Address]:port".
          </adm:description>
        </adm:property>
      <adm:property name="secondary-server" multi-valued="true">
          [...]
          <adm:description>
            When using an IPv6 address as the hostname, put brackets around the address as in "[IPv6Address]:port".
          </adm:description>\
          [...]
        </adm:property>
      

      Possible solutions

      We cannot enhance the syntax usage (HOST:PORT) because it must stay very short as it is displayed in help usage tables:

      Property                            Options  Syntax
      ------------------------------------------------------------
      accept-backlog                      rw-sa    INTEGER
      advertised-listen-address           rwm--    HOST_NAME
      bootstrap-replication-server         rwm--   HOST:PORT
      buffer-size                         rw-s-    SIZE
      

      So adding more details to the syntax usage would make the output reading much more difficult, e.g:

      Property                            Options  Syntax
      ------------------------------------------------------------
      accept-backlog                      rw-sa    INTEGER
      advertised-listen-address           rwm--    HOST_NAME
      bootstrap-replication-server         rwm--   HOST:PORT (or [HOST]:PORT for 
      IPv6 addresses), where 1 <= PORT <= 6553
      buffer-size                         rw-s-    SIZE
      

      To prevent the duplication, a possible solution would be to display the syntax description (contributed in admin.xsd) alongside the syntax usage when the user creates or modifies a property (today we display only the syntax usage).

      Acceptance criteria

      This issue can be closed once we have found and clearly defined a solution to prevent syntax usage to be duplicated in property description.
      Solution can be the suggested above or any better thoughts discussed in the comments below.

        Attachments

          Issue Links

            Activity

              People

              • Assignee:
                Unassigned
                Reporter:
                gaetan Gaetan Boismal [X] (Inactive)
              • Votes:
                0 Vote for this issue
                Watchers:
                1 Start watching this issue

                Dates

                • Created:
                  Updated: