Bug 790146 - JON 3.01 RC3, CLI Documentation issues re: updateBackingContent and retrieveBackingContent
JON 3.01 RC3, CLI Documentation issues re: updateBackingContent and retrieveB...
Status: CLOSED CURRENTRELEASE
Product: RHQ Project
Classification: Other
Component: Documentation (Show other bugs)
3.0.1
Unspecified Unspecified
high Severity high (vote)
: ---
: JON 3.0.1
Assigned To: Deon Ballard
Mike Foley
:
Depends On: 767393 788773
Blocks: 788629
  Show dependency treegraph
 
Reported: 2012-02-13 13:42 EST by Mike Foley
Modified: 2012-06-21 19:14 EDT (History)
3 users (show)

See Also:
Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of: 788773
Environment:
Last Closed: 2012-06-21 19:14:14 EDT
Type: ---
Regression: ---
Mount Type: ---
Documentation: ---
CRM:
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---


Attachments (Terms of Use)

  None (edit)
Description Mike Foley 2012-02-13 13:42:10 EST
+++ This bug was initially created as a clone of Bug #788773 +++ 
This is a documentation issue.  Objects and methods in the valid repro steps are not contained in the CLI documentation, as follows:

1) ProxyFactory object is not documented
2) updateBackingContent is not documented 
3) retriveBackingContent

These methods should be in the API documentation.  Also, they would make great examples to document as well.





+++ This bug was initially created as a clone of Bug #767393 +++

Description of problem:
For the JBoss AS5 plugin, the SHA256 is not returned correctly by the plugin
during discovery. Also, the SHA256 is not saved properly if the deployment does
not have a manifest file.

How reproducible:
Every time.

Steps to Reproduce:
1. Inventory an AS5 (EAP5) server.
2. Prepare a sample war file without a manifest file and folder.
2. Update an existing exploded webapp through the CLI using the sample war.
3. Browse and view the content of the manifest file for the deployed app (look
into the server deployment folder).
4. Wait for the discovery process to take place and notice that the SHA256 is
not returned correctly to the server.

Actual results:
There is no manifest file. The SHA256 returned to the server is null.

Expected results:
The manifest file is present and the RHQ-Sha256 attribute is present in the
main section. The SHA256 returned to the server is the one computed during
deployment.

Additional info:
There are several problems with saving the manifest file as well in the
discovery process. This plugin should behave like the corrected and enhanced
Tomcat plugin.

--- Additional comment from mfoley@redhat.com on 2012-01-23 15:25:34 EST ---

Verification steps for QE



Setup:
1) RHQ server started, RHQ agent running, CLI connected to RHQ server
2) Inventoried Tomcat Server, JBoss AS4 or JBoss EAP5.1
3) Need the ID of a content backed resource, eg. an application resource. The ID can be retrieved from the UI http://localhost:7080/coregui/#Resource/14932, the last portion of the url is the ID of the resource.
4) A sample war application to be deployed to the application server
5) A folder to backup applications from the server

Stimulate:
1) Navigate in the UI to the selected application resource, content tab, history subtab.
2) From the CLI run the following commands:
3) applicationResource = ProxyFactory.getResource(14932)
4) applicationResource.retrieveBackingContent("/resources/backup/original.war")
5) applicationResource.updateBackingContent("/resources/new/newcontent.war", "1.2")
6) applicationResource.retrieveBackingContent("/resources/backup/updated.war")
7) Navigate in the UI to the resource that was just updated to the Content tab

Verification steps:
1) Verify that after Step 1, the Full Package Audit Trail table, version column has either a normal number (eg. 1.2.3) or sha256. The version field should not be empty.
2) Verify that the archive retrieved in Step 3 is the exact archive that was deployed on the server before running the test
3) Verify that after Step 4 the new application has been actually deployed on the application server. Check the file system where the application server deploys content.
4) Verify that after Step 4 the new application has RHQ-Sha256 attribute in the manifest.
5) Verify that after Step 5 the archive downloaded is the application deployed in Step 4
6) Verify the content tab, history subtab has the following:
  a) Full Package Audit Trail table has the correct package information marked as Discovered, including correct version.
  b) Completed Requests table has information regarding the request submitted from the CLI, including submitted version.

--- Additional comment from mfoley@redhat.com on 2012-01-23 15:30:43 EST ---

2nd verification step for QE



UI Test (applicable to BZ 761593, 767247, 767393, 769986)

Setup:
1) RHQ server started, RHQ agent running
2) Inventoried Tomcat Server, JBoss AS4 or JBoss EAP5.1
3) A sample war application to be deployed to the application server

Stimulate:
1) Navigate in the UI to the selected application resource, content tab, history subtab.
2) Navigate to the New subtab.
3) Upload a new war package for the resource. Follow the guided UI but do change the version field to something unique.
4) Navigate in the UI to the resource that was just updated to the Content tab

Verification steps:
1)  Verify that after Step 1, the Full Package Audit Trail table, version  column has either a normal number (eg. 1.2.3) or sha256. The version  field should not be empty.
2)  Verify after Step 4 the new application has been actually deployed  on the application server. Check the file system where the application  server deploys content.
3) Verify after Step 4 the new application has RHQ-Sha256 attribute in the manifest.
4) Verify after Step 4 the content tab, history subtab has the following:
  a) Full Package Audit Trail table has the correct package information marked as Discovered, including correct version.
  b) Completed Requests table has information regarding the request submitted from the CLI, including submitted version.

--- Additional comment from snegrea@redhat.com on 2012-02-08 18:55:48 EST ---

Some negative test cases:

1) Step 4, point to an existing file
2) Step 5, point to a non-existing file
3) Step 6, retrieve content twice in two separate files and then compare the
results
4) Step 5, repeat the step with a different version. Observe in the UI that
that version is from the last call and two entries in the deployment log.

--- Additional comment from snegrea@redhat.com on 2012-02-08 19:02:02 EST ---

release/jon3.0.x branch commits:

http://git.fedorahosted.org/git/?p=rhq/rhq.git;a=commit;h=c106f6031294e8993525c1b6d368784409b4221f

http://git.fedorahosted.org/git/?p=rhq/rhq.git;a=commit;h=872270d1ce3a95158da1fcc169f0c220d2984d79

http://git.fedorahosted.org/git/?p=rhq/rhq.git;a=commit;h=f1b429a6165c74c7ca65b180c51c6cdebadffde3

http://git.fedorahosted.org/git/?p=rhq/rhq.git;a=commit;h=bbb418f3f1e09c0397d7b8eedaf57e9e0c8bf948

--- Additional comment from spinder@redhat.com on 2012-02-10 17:44:49 EST ---

Moving to ON_QA as new RC 4 available to test in:
https://brewweb.devel.redhat.com//buildinfo?buildID=198384

--- Additional comment from mfoley@redhat.com on 2012-02-13 13:29:51 EST ---

uploading image and text to document the verification described

--- Additional comment from mfoley@redhat.com on 2012-02-13 13:30:26 EST ---

Created attachment 561626 [details]
verification image

--- Additional comment from mfoley@redhat.com on 2012-02-13 13:30:57 EST ---

Created attachment 561627 [details]
verification text from CLI

--- Additional comment from mfoley@redhat.com on 2012-02-13 13:32:56 EST ---

performed additional negative and edge cases as described.
Comment 1 Deon Ballard 2012-02-13 19:31:36 EST
I finally located updateBackingContent and retrieveBackingContent in modules/enterprise/binding/src/main/java/org/rhq/bindings/client/ResourceClientProxy.java. These both seem to be public. However, as far as I can tell, only files in a client-api/ directory get pulled into the javadoc when the javadoc build is run, and the binding/ module doesn't have a client-api directory. So, none of those resources are included in the API.

The only reference I could find to proxyFactory was in ResourceClientFactory.java, and that seems to be a private class. So, even if binding/ got added to the API, proxyFactory wouldn't be included.

I think.

Lukas, I have a couple of questions.

1) Should the bindings/ classes be added to the RHQ API javadoc?

2) Is proxyFactory a private class?
Comment 2 Lukas Krejci 2012-02-14 08:34:22 EST
This is a tricky question to answer.

As for the names of the standard variables in the CLI and their types, you can consult the StandardBindings class in the bindings module. The CLI commandline defines 2 more variables that provide login/logout functionality and interactive configuration editing - see the initBindings() method in the ScriptCommand class in the rhq-remoting-cli module.

So coming from that direction, the ResourceClientFactory class is public because the "ProxyFactory" variable in the CLI is an instance of that class. On the other hand, the only user-facing method in that class is the getResource() method - other methods are there for various internal reasons and have little use by the scripts.

As for the (retrieve|update)BackingContent - the ResourceClientProxy is a tad esoteric. In the ResourceClientFactory.getResource() method we obtain the resource and based on the "qualities" of the resource type we generate a custom class at runtime that inherits from the ResourceClientProxy which defines the basic set of methods and properties and additionally this dynamically created class will implement other interfaces (backed by the ResourceClientProxy.ClientProxyMethodHandler). So for example if a resource type of the resource supports content subsystem, the dynamic class will implement the ResourceClientProxy.ContentBackedResource interface (and thus have the above mentioned methods available). If the resource type supports resource configuration, the dynamic class will implement the ResourceConfigurable interface. If there is any plugin configuration available on the resource type, the dynamic class will implement the PluginConfigurable interface.

In addition to all that, the dynamic class will have properties corresponding to all the measurements that the resource type defines and will have methods corresponding to the individual operations defined on the resource type.

I am really not sure if the user would make sense of that information if we made it public only through javadoc, because javadoc would need to remain very generic in its description (as I did in the above paragraphs and I am pretty sure the text above is nearly incomprehensible).

Maybe we should be more descriptive and just describe this situation as:
* if the resource type of the resource supports content subsystem, the resource proxy is going to have these methods available.
* if there is a plugin configuration on the resource type, the resource proxy is going to have these methods, etc.

All that said, all these classes are intended as support for the CLI "API". In that sense, none of them is meant to be used from Java code directly.
Comment 3 Deon Ballard 2012-02-14 11:21:23 EST
Thanks, Lukas. That makes sense. A little. ;)

There is a section on resource proxies in the docs:
http://docs.redhat.com/docs/en-US/JBoss_Operations_Network/100/html/Running_JON_Command-Line_Scripts/Running_the_CLI-Proxy.html

I *think* the intent of that section is to describe what you're describing here. Instead of updating the javadoc, it is probably much more appropriate to rewrite that section and clarify what the proxy classess bring and what the methods are, like maybe in a little table.
Comment 4 Lukas Krejci 2012-02-14 11:38:22 EST
Exactly.

If you have any difficulties creating that table, just fire an email my way.
Comment 5 Deon Ballard 2012-02-23 15:57:33 EST
Updated the section on using proxies:
http://documentation-stage.bne.redhat.com/docs/en-US/JBoss_Operations_Network/100/html/Running_JON_Command-Line_Scripts/Running_the_CLI-Running_the_JON_CLI.html#Running_the_CLI-Proxy

And added this table on proxy methods:
http://documentation-stage.bne.redhat.com/docs/en-US/JBoss_Operations_Network/100/html/Running_JON_Command-Line_Scripts/cli-ref-api.html#ref-proxyobjects

For the last link, I only added tables for three resource types: platform, JBoss AS, and EAR (as a content source). I try to make it clear that it is not a comprehensive section and that I was only hitting some common resource types. I can add more, if necessary.
Comment 6 Deon Ballard 2012-06-21 19:14:14 EDT
Closing.

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