Bug 804164 - Internal documentation in fix-bundle-deployment.js is not clear or sufficient to populate deploymentConfiguration object
Summary: Internal documentation in fix-bundle-deployment.js is not clear or sufficient...
Keywords:
Status: CLOSED CURRENTRELEASE
Alias: None
Product: RHQ Project
Classification: Other
Component: CLI
Version: 4.4
Hardware: Unspecified
OS: Unspecified
high
high
Target Milestone: ---
: JON 3.1.0
Assignee: Lukas Krejci
QA Contact: Mike Foley
URL:
Whiteboard:
Depends On:
Blocks: jon310-sprint11, rhq44-sprint11
TreeView+ depends on / blocked
 
Reported: 2012-03-16 17:28 UTC by Mike Foley
Modified: 2013-09-03 15:01 UTC (History)
2 users (show)

Fixed In Version:
Clone Of:
Environment:
Last Closed: 2013-09-03 15:01:37 UTC
Embargoed:


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

Description Mike Foley 2012-03-16 17:28:58 UTC
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 17:50:30 UTC
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"
                version="1.0"
                description="desc">
        <rhq:deployment-unit name="jar">
            <rhq:file name="a.txt" destinationFile="a.txt" replace="false"></rhq:file>
        </rhq:deployment-unit>
    </rhq:bundle>
    <target name="main"></target>
</project>



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 18:29:49 UTC
   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 15:18:47 UTC
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 16:11:49 UTC
master http://git.fedorahosted.org/git/?p=rhq/rhq.git;a=commitdiff;h=fd154467a327b6e8f00e404448e6486442a37b80
Author: Lukas Krejci <lkrejci>
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 18:26:06 UTC
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 08:40:04 UTC
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 19:31:56 UTC
documentation internal to the .js file was improved.  attaching file to document the verification.

Comment 8 Mike Foley 2012-04-23 19:32:48 UTC
Created attachment 579673 [details]
attaching fix-bundle-deployment.js to document the verification

Comment 9 Heiko W. Rupp 2013-09-03 15:01:37 UTC
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.