Bug 790146
| Summary: | JON 3.01 RC3, CLI Documentation issues re: updateBackingContent and retrieveBackingContent | ||
|---|---|---|---|
| Product: | [Other] RHQ Project | Reporter: | Mike Foley <mfoley> |
| Component: | Documentation | Assignee: | Deon Ballard <dlackey> |
| Status: | CLOSED CURRENTRELEASE | QA Contact: | Mike Foley <mfoley> |
| Severity: | high | Docs Contact: | |
| Priority: | high | ||
| Version: | 3.0.1 | CC: | hrupp, lkrejci, snegrea |
| Target Milestone: | --- | ||
| Target Release: | JON 3.0.1 | ||
| Hardware: | Unspecified | ||
| OS: | Unspecified | ||
| Whiteboard: | |||
| Fixed In Version: | Doc Type: | Bug Fix | |
| Doc Text: | Story Points: | --- | |
| Clone Of: | 788773 | Environment: | |
| Last Closed: | 2012-06-21 23:14:14 UTC | Type: | --- |
| Regression: | --- | Mount Type: | --- |
| Documentation: | --- | CRM: | |
| Verified Versions: | Category: | --- | |
| oVirt Team: | --- | RHEL 7.3 requirements from Atomic Host: | |
| Cloudforms Team: | --- | Target Upstream Version: | |
| Embargoed: | |||
| Bug Depends On: | 767393, 788773 | ||
| Bug Blocks: | 788629 | ||
|
Description
Mike Foley
2012-02-13 18:42:10 UTC
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? 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. 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. Exactly. If you have any difficulties creating that table, just fire an email my way. 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. Closing. |