Bug 804164 - Internal documentation in fix-bundle-deployment.js is not clear or sufficient to populate deploymentConfiguration object
Internal documentation in fix-bundle-deployment.js is not clear or sufficient...
Product: RHQ Project
Classification: Other
Component: CLI (Show other bugs)
Unspecified Unspecified
high Severity high (vote)
: ---
: JON 3.1.0
Assigned To: Lukas Krejci
Mike Foley
Depends On:
Blocks: jon310-sprint11/rhq44-sprint11
  Show dependency treegraph
Reported: 2012-03-16 13:28 EDT by Mike Foley
Modified: 2013-09-03 11:01 EDT (History)
2 users (show)

See Also:
Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of:
Last Closed: 2013-09-03 11:01:37 EDT
Type: ---
Regression: ---
Mount Type: ---
Documentation: ---
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---

Attachments (Terms of Use)
attaching fix-bundle-deployment.js to document the verification (14.74 KB, application/javascript)
2012-04-23 15:32 EDT, Mike Foley
no flags Details

  None (edit)
Description Mike Foley 2012-03-16 13:28:58 EDT
Description of problem:  Internal documentation in fix-bundle-deployment.js is not clear or sufficient to set 

Version-Release number of selected component (if applicable):  RHQ 4.4

 * A deployment of the bundle version may require configuration. Normally, this can be
 * provided as a simple javascript object (using the curly braces notation). Please see
 * the documentation of the <code>asConfiguration</code> function further down to understand
 * the limitations of this approach. Should the simple format using the javascript object
 * be not possible, you have to build up a full org.rhq.core.domain.configuration.Configuration
 * object.

var deploymentConfig

I am following the advice of the javascript documentation ... and am trying this ...

var deploymentConfig = {
    simple : "value",
    list : [ "value1", "value2"],
    listOfMaps : [ { k1 : "value", k2 : "value" }, { k1 : "value2", k2 : "value2" } ]

apparently it is incorrect.
Comment 1 Mike Foley 2012-03-16 13:50:30 EDT
Just documenting what my recipe looks like.  

<?xml version="1.0"?>
<project name="ant-bundle-recipe" default="main" xmlns:rhq="antlib:org.rhq.bundle">
    <rhq:bundle name="My Bundle 1297957137903"
        <rhq:deployment-unit name="jar">
            <rhq:file name="a.txt" destinationFile="a.txt" replace="false"></rhq:file>
    <target name="main"></target>

I have no idea how to represent this as a valid deploymentConfiguration object in Javascript with curly braces notation ... and no customer will know how to do this either with the supplied documentation.

Yes ... I have looked at this URL http://rhq-project.org/display/JOPR2/Ant+Bundles#AntBundles-rhq%3Ainputproperty
Comment 2 Mike Foley 2012-03-16 14:29:49 EDT
   list : [ "value1", "value2"],
    listOfMaps : [ { k1 : "value", k2 : "value" }, { k1 : "value2", k2 : "value2" } ]

The configuration object does not support lists or listOfMaps

we should remove this from the internal documentation as it just confuses things ...
Comment 3 Lukas Krejci 2012-04-02 11:18:47 EDT
Your recipe doesn't contain any rhq:input-property and therefore doesn't require any configuration.

But the idea is as follows:

in deploy.xml:

<rhq:input-property type="string" name="my-string-property" />
<rhq:input-property type="boolean" name="my-bool-property" />
<rhq:input-property type="integer" name="my-int-property" />

in the script, you'd define the values for the above properties as:

var deploymentConfig = {
    "my-string-property" : "value",
    "my-boolean-property" : false,
    "my-int-property" : 10

The documentation in the script should be enhanced to include these more specific instructions. I will update it.

With regards to the removal of "listOfMaps" - the function for converting the configuration from the javascript-friendly format to the RHQ-specific format is generic and supports (almost) complete mapping between the two. Even though the listOfMaps (and lists) are not supported by bundles, the function itself supports them.

Note that the whole fix-bundle-deployment.js script is a "composition" of several other scripts (and there are markers in the script that divide it into sections based on the original files of the individual functions - these files are part of the "samples" distributed with the remote CLI) - this is to overcome the current inability of RHQ to provide script inclusion or some other modularization approach to the CLI scripts (either in the standalone CLI or in the server for alert scripts).

So even though in this particular script, the documentation might mention more than absolutely necessary to be able to define the deployment configs of the bundles I am not in favor of creating yet another "fork" of those functions and make specialized versions of them just for this single script. That also means that the documentation of the functions should describe them fully, not just the minimum required features.

As a final note, as far as I know, we provide this script to the users as an example or sample which they can either use as-is or modify to their own liking. Therefore I do see some advantages in offering more generic functions to the user.
Comment 4 Lukas Krejci 2012-04-02 12:11:49 EDT
master http://git.fedorahosted.org/git/?p=rhq/rhq.git;a=commitdiff;h=fd154467a327b6e8f00e404448e6486442a37b80
Author: Lukas Krejci <lkrejci@redhat.com>
Date:   Mon Apr 2 18:07:47 2012 +0200

    [BZ 804164] - improve docs in "fix-bundle-deployment.js" sample script.
Comment 5 Mike Foley 2012-04-20 14:26:06 EDT
I have the latest build from master ... and after downloading and installing the CLI ... fix-bundle-deployment.js is not in the CLI/samples directory.  

The BZ is targetted for JON 3.1 ... and it is my understanding that JON 3.1 is based off of master.  So I think the file is missing in JON 3.1.

Marking failed to verify based on my observations and understanding of the branches.
Comment 6 Lukas Krejci 2012-04-23 04:40:04 EDT
This script is not included with the standalone CLI, because it is meant to be used as an alert script - i.e. only used on the server-side. It can be reached by accessing the Administration -> Downloads page.
Comment 7 Mike Foley 2012-04-23 15:31:56 EDT
documentation internal to the .js file was improved.  attaching file to document the verification.
Comment 8 Mike Foley 2012-04-23 15:32:48 EDT
Created attachment 579673 [details]
attaching fix-bundle-deployment.js to document the verification
Comment 9 Heiko W. Rupp 2013-09-03 11:01:37 EDT
Bulk closing of old issues in VERIFIED state.

Note You need to log in before you can comment on or make changes to this bug.