From 475e015661d8cb309f9104e77120e6e162b35497 Mon Sep 17 00:00:00 2001 From: Michael Berry Date: Sun, 30 Sep 2018 19:10:38 +0100 Subject: [PATCH] Update and rename README to README.md Move README file into a markdown format for much clearer formatting. --- README => README.md | 129 ++++++++++++++++++++++---------------------- 1 file changed, 64 insertions(+), 65 deletions(-) rename README => README.md (50%) diff --git a/README b/README.md similarity index 50% rename from README rename to README.md index a8a7aa6..1f4f700 100644 --- a/README +++ b/README.md @@ -1,85 +1,86 @@ -/** - * Copyright (c) Microsoft Corporation - * - * Licensed under the Apache License, Version 2.0 (the "License"); you may not use - * this file except in compliance with the License. You may obtain a copy of the - * License at http://www.apache.org/licenses/LICENSE-2.0. - * - * THIS CODE IS PROVIDED *AS IS* BASIS, WITHOUT WARRANTIES OR CONDITIONS - * OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION - * ANY IMPLIED WARRANTIES OR CONDITIONS OF TITLE, FITNESS FOR A PARTICULAR PURPOSE, - * MERCHANTABLITY OR NON-INFRINGEMENT. - * - * See the Apache Version 2.0 License for specific language governing - * permissions and limitations under the License. - */ - -1. Overview +# Overview + BeanSpy is an open source technology provided by Microsoft for exposing JMX information from Java EE application servers through HTTP queries. It currently supports the following Java EE application servers and web containers: - Tomcat 5.5, 6, 7 - JBoss 4.2, 5.1, 6 - WebSphere 6.1, 7 - WebLogic 10gR3, 11gR1 +- Tomcat 5.5, 6, 7 +- JBoss 4.2, 5.1, 6 +- WebSphere 6.1, 7 +- WebLogic 10gR3, 11gR1 The binary package contains 4 BeanSpy files digitally signed by Microsoft: - BeanSpy.ear - BeanSpy.war - BeanSpy.HTTP.NoAuth.ear - BeanSpy.HTTP.NoAuth.war +- BeanSpy.ear +- BeanSpy.war +- BeanSpy.HTTP.NoAuth.ear +- BeanSpy.HTTP.NoAuth.war BeanSpy.ear and BeanSpy.war are used in cases where the Java EE application server or web container is using HTTPs transport with basic auth servlet authentication. The HTTP.NoAuth version is used in HTTP transport without servlet authentication. -2. How to deploy BeanSpy -If your Java EE application server or web container is using HTTPs with basic auth, deploy BeanSpy.ear to JBoss/WebSphere/WebLogic; deploy BeanSpy.war to Tomcat. For Tomcat/JBoss/WebSphere, BeanSpy requires a user role "monitoring" for querying JVM and MBeans, and a user role "invoke" for invoking methods on MBeans, for WebLogic, BeanSpy requires "monitors" role for quering JVM and MBeans and "operators" role for invoking methods on MBeans. +# How to deploy BeanSpy + +If your Java EE application server or web container is using HTTPs with basic auth: + + - Deploy `BeanSpy.ear` to `JBoss/WebSphere/WebLogic` + - Deploy `BeanSpy.war` to Tomcat. *For Tomcat/JBoss/WebSphere, BeanSpy requires a user role "monitoring" for querying JVM and MBeans, and a user role "invoke" for invoking methods on MBeans, for WebLogic, BeanSpy requires "monitors" role for quering JVM and MBeans and "operators" role for invoking methods on MBeans.* + +If your Java EE application server or web container is using HTTP without authentication: + + - Rename `BeanSpy.HTTP.NoAuth.ear` to `BeanSpy.ear` + - Deploy the above file to `JBoss/WebSphere/WebLogic` + - Rename `BeanSpy.HTTP.NoAuth.war` to `BeanSpy.war` + - Deploy the above file to Tomcat. -If your Java EE application server or web container is using HTTP without authentication, rename BeanSpy.HTTP.NoAuth.ear to BeanSpy.ear and deploy it to JBoss/WebSphere/WebLogic; rename BeanSpy.HTTP.NoAuth.war to BeanSpy.war and deploy it to Tomcat. +# How to query BeanSpy -3. How to query BeanSpy Once BeanSpy is deployed, you can query it through the browser or invoke method on MBeans using HTTP POST. The following are a few examples. For complete schema, please refer to the schema file in the source package. - a) To query JVM stats for memory, Garbage Collection, class loading, and threads, use: - http:///BeanSpy/Stats - b) To query configuration and version info about the Java EE application server or web container, use: - http:///BeanSpy/Stats/Info - c) To query specific MBeans, use: - http:///BeanSpy/MBeans?JMXQuery= - Here, BeanObjectName conforms to JMX standard, for example, com.contoso:Type=J2EEApplication,* - d) To invoke a method on a MBean, use HTTP POST: - http:///BeanSpy/MBeans/Invoke - The HTTP post body should look like this: - - com.contoso:name=CustomMBeanName - - 400 - bar - - - Only primitive parameters are supported. Composite data types are not supported. - -4. Additional parameters for BeanSpy queries + +1. To query JVM stats for memory, Garbage Collection, class loading, and threads, use: + `http:///BeanSpy/Stats` +2. To query configuration and version info about the Java EE application server or web container, use: + `http:///BeanSpy/Stats/Info` +3. To query specific MBeans, use: + `http:///BeanSpy/MBeans?JMXQuery=` +Here, BeanObjectName conforms to JMX standard, for example, `com.contoso:Type=J2EEApplication,*` +4. To invoke a method on a MBean, use HTTP POST: + http:///BeanSpy/MBeans/Invoke +The HTTP post body should look like this: + +``` + + com.contoso:name=CustomMBeanName + + 400 + bar + + +``` + +Only primitive parameters are supported. Composite data types are not supported. + +# Additional parameters for BeanSpy queries + There are a few parameters you can add to the URL to control the performance of your BeanSpy query. ________________________________________ -MaxDepth +`MaxDepth` Default maximum recursion depth when parsing MBeans Default value: 10 -Modification: can be modified by adding parameters “MaxDepth” (case sensitive) in the URL. -For example: “/MBeans?JMXQuery=com.microsoft.scx:jmxType=operationCall&MaxDepth=12”. +Modification: can be modified by adding parameters “MaxDepth” (case sensitive) in the URL. +For example: `/MBeans?JMXQuery=com.microsoft.scx:jmxType=operationCall&MaxDepth=12`. ________________________________________ -MaxCount +`MaxCount` Default maximum number of properties to process when parsing MBeans Default value: 500 -Modification: can be modified by adding parameters “MaxCount” (case sensitive) in the URL. -For example: “/MBeans?JMXQuery=com.microsoft.scx:jmxType=operationCall&MaxCount=200”. +Modification: can be modified by adding parameters “MaxCount” (case sensitive) in the URL. +For example: `/MBeans?JMXQuery=com.microsoft.scx:jmxType=operationCall&MaxCount=200`. ________________________________________ -MaxSize +`MaxSize` Default maximum size of the output XML when parsing MBeans. If the size of a XML file exceeds this value but does not exceed the absolute maximum XML file size (ABS_MAX_XML_SIZE), BeanSpy continues to proceed. However, it will reset the MaxDepth to the minimum which is 0. The same value is used as the default maximum size for the resultant XML when an Invoke POST call is processed. Default value: 2097152 (2MB) -Modification: can be modified by adding parameters “MaxSize” (case sensitive) in the URL. -For example: “/MBeans?JMXQuery=com.microsoft.scx:jmxType=operationCall&MaxSize=20000”. +Modification: can be modified by adding parameters “MaxSize” (case sensitive) in the URL. +For example: `/MBeans?JMXQuery=com.microsoft.scx:jmxType=operationCall&MaxSize=20000`. ________________________________________ -ABS_MAX_XML_SIZE +`ABS_MAX_XML_SIZE` The absolute maximum size for the output. If the size of the output XML file exceeds this value, BeanSpy throws an exception and terminates. If the value is missing in the configuration file, use the default value which is 4M. Default value: 4184304 (4MB) @@ -87,9 +88,8 @@ Default value: 4184304 (4MB) Modification: can be modified by the end user in resources.configuration.config file. ________________________________________ -5. How to build BeanSpy -Pre-requisites -________________________________________ +# How to build BeanSpy +## Pre-requisites To build the BeanSpy servlet application the following external files are required, download the respective packages and copy the files to the required locations. @@ -104,8 +104,7 @@ To include the build and execution of the unit tests the following junit jar fil these files are available from http://www.junit.org/ -To build the BeanSpy project -________________________________________ +## To build the BeanSpy project Ant and java is used to build and package the java code into WAR and EAR files as well as build and execute the unit tests. Ant is available from http://ant.apache.org/ @@ -118,4 +117,4 @@ ant, the default build is for release purposes to build the debug version run an "-Ddebug=true" i.e. "ant clean ears testrun -Ddebug=true". There are other build switches that can be used to control, java version, product version, verbosity -and javadocs. \ No newline at end of file +and javadocs.