Document URL: https://access.redhat.com/documentation/en-US/Red_Hat_JBoss_Operations_Network/3.2/html/Installation_Guide/Agent_Installation.html#jre-agent

Section Number and Name: ⁠4.1.1. Setting up the JRE for the JBoss ON Agent

Describe the issue: 
Section is incomplete and RHEL specific in regards to Java and the use of JAVA_HOME and RHQ_JAVA_HOME.

> 2. Set the RHQ_JAVA_HOME environment variable to the installation directory.

Although this can be done, it is only necessary if the system installed JVM is insufficient -- such as the wrong version or incompatible vendor or not available on the users PATH. This step should be marked as optional or dependent on the system installed JVM. Furthermore, JAVA_HOME can be used and is more then sufficient if already defined. 


>  1. Open the .bashrc for the system user that will run JBoss ON. For example: 

This is Linux, and most importantly Bash, specific. As these instructions are necessary for all supported platforms regardless of command interpreter, they should be made more generic with examples that might pertain to a specific shell or operating system. Furthermore, .bashrc is not where Bash user specific environment variables belong. Instead, .bash_profile should be used when using Bash. On Windows these settings belong in the user's environment settings. This is actually a good reason why one should use the rhq-agent-env.sh|bat file as these are sourced on their appropriate operating systems when one of the agent's start scripts are invoked.


>  Add a line to set the RHQ_JAVA_HOME environment variable to the specific JRE directory. For example:
>
>   export RHQ_JAVA_HOME=/usr/lib/jvm/jre-1.6.0-openjdk/bin/java/

This again only applies on Linux and UNIX systems. Furthermore, as reported in bug 1164940, the example path is wrong. It should be

    /usr/lib/jvm/jre-1.7.0-openjdk.x86_64

The /bin/java/ at the end will prevent the agent from running altogether. Basically, the value used here should point to the JVM's base directory. This will be the directory above the JVM's bin directory.


> 3. Set the system to use the correct version of the JRE using the system alternatives command. The selected version has the *+ symbols by it. 

Although this may apply to Linux distributions that support alternatives, it would also seem to indicate that if set, JAVA_HOME and RHQ_JAVA_HOME are not necessary. JAVA_HOME and RHQ_JAVA_HOME are only necessary if the system provided JVM is not sufficient -- such as one that could be provided by alternatives -- and requires a different JVM to override the system default. 



Suggestions for improvement: 
Not sure how to address all of these issues. If it makes sense to add specific sub-sections for each supported platform and how to set the values or if that should be up to the user. After all, this is system and JVM specific and can not be easily pre-determined by JBoss ON. In general though what we need to communicate to the user is:

* If RHQ_JAVA_HOME or JAVA_HOME are not defined, the `java` or `java.exe` executable must be available on the user's PATH.
* If not available or the one available is not compatible, the user's environment variable JAVA_HOME or RHQ_JAVA_HOME must be set.
* RHQ_JAVA_HOME will override the value provided by JAVA_HOME.
* The environment variable can be defined in the user's profile or in the `rhq-agent-env.sh|bat` environment scripts.