Merge branch 'jetty-9.3.x' into jetty-9.4.x

README.md

@@ -18,19 +18,15 @@ Project description
 -------------------
 
 Jetty is a lightweight highly scalable java based web server and servlet engine.
-Our goal is to support web protocols like HTTP, HTTP/2 and WebSocket in a high
-volume low latency way that provides maximum performance while retaining the ease
-of use and compatibility with years of servlet development. Jetty is a modern
-fully async web server that has a long history as a component oriented technology
-easily embedded into applications while still offering a solid traditional
-distribution for webapp deployment.
+Our goal is to support web protocols like HTTP, HTTP/2 and WebSocket in a high volume low latency way that provides maximum performance while retaining the ease of use and compatibility with years of servlet development. 
+Jetty is a modern fully async web server that has a long history as a component oriented technology easily embedded into applications while still offering a solid traditional distribution for webapp deployment.
 
 - [https://projects.eclipse.org/projects/rt.jetty](https://projects.eclipse.org/projects/rt.jetty)
 
 Documentation
 -------------
 
-Project documentation is located on our Eclipse website.
+Project documentation is available on the Jetty Eclipse website.
 
 - [http://www.eclipse.org/jetty/documentation](http://www.eclipse.org/jetty/documentation)
 
@@ -42,13 +38,13 @@ To build, use:
   mvn clean install
 ```
 
-The jetty distribution will be built in `jetty-distribution/target/distribution`
+The Jetty distribution will be built in `jetty-distribution/target/distribution`.
 
-The first build may take a long time as Maven downloads all the dependencies.
+The first build may take a longer than expected as Maven downloads all the dependencies.
 
-The tests do a lot of stress testing, and on some machines it is necessary to set the file descriptor limit to greater than 2048 for the tests to all pass successfully.
+The build tests do a lot of stress testing, and on some machines it is necessary to set the file descriptor limit to greater than 2048 for the tests to all pass successfully.
 
-Bypass tests by building with `mvn -Dmaven.test.skip=true install` but note that this will not produce some test jars that are leveraged in other places in the build.
+It is possible to bypass tests by building with `mvn -Dmaven.test.skip=true install` but note that this will not produce some of the test jars that are leveraged in other places in the build.
 
 Professional Services
 ---------------------

jetty-documentation/src/main/asciidoc/administration/jmx/chapter.adoc

@@ -15,8 +15,19 @@
 //  ========================================================================
 
 [[jmx-chapter]]
-== JMX
+== Java Management Extensions (JMX)
+
+
+The http://java.sun.com/products/JavaManagement/[Java Management Extensions (JMX) API] is a standard API for managing and monitoring resources such as applications, devices, services, and the Java virtual machine.
+
+Typical uses of the JMX technology include:
+
+* Consulting and changing application configuration
+* Accumulating and making available statistics about application behavior
+* Notifying of state changes and erroneous conditions
+
+The JMX API includes remote access, so a remote management program can interact with a running application for these purposes.
 
 include::using-jmx.adoc[]
+include::jetty-jmx-annotations.adoc[]
 include::jetty-jconsole.adoc[]
-include::jetty-jmx-annotations.adoc[]

jetty-documentation/src/main/asciidoc/administration/jmx/jetty-jconsole.adoc

@@ -15,31 +15,26 @@
 //  ========================================================================
 
 [[jetty-jconsole]]
-=== Jetty JConsole
+=== Managing Jetty with JConsole and JMC
 
-JConsole is a graphical tool; it allows you to remotely manage and monitor your server and web application status using JMX. 
-When following the instructions given below, please also ensure that you make any necessary changes to any anti-virus software you may be using which may prevent jconsole from running.
-
-[[jetty-jconsole-monitoring]]
-==== Monitoring Jetty with JConsole
-
-To monitor Jetty's server status with JConsole, make sure JConsole is running, and start Jetty with a special system property.
+JConsole and the Java Mission Control (JMX) are graphical tools; they allow you to remotely manage and monitor your server and web application status using JMX.
+When following the instructions given below, please also ensure that you make any necessary changes to any anti-virus software you may be using which may prevent JConsole or JMC from running.
 
 ===== Starting Jetty Standalone
 
-The simplest way to enable support is to add the jmx support module to your $\{jetty.base}.
+The simplest way to enable support is to add the JMX-Remote support module to your `{$jetty.base}`.
 
 [source, screen, subs="{sub-order}"]
 ....
-[mybase]$ java /opt/jetty-dist/start.jar --add-to-start=jmx
-INFO: jmx-remote      initialised in ${jetty.base}/start.ini (appended)
-INFO: jmx             initialised transitively
+[mybase]$ java /opt/jetty-dist/start.jar --add-to-start=jmx-remote, jmx
+INFO: jmx-remote      initialised in ${jetty.base}/start.ini
+INFO: jmx             initialised in ${jetty.base}/start.ini
 ....
 
-Then open the $\{jetty.base}/start.ini file and edit the properties to suit your needs:
+Then open the `{$jetty.base}/start.ini` (or `{$jetty.base}/start.d/jmx-remote.ini`) file and edit the properties to suit your needs:
 
+[source, screen, subs="{sub-order}"]
 ....
-
 #
 # Initialize module jmx-remote
 #
@@ -48,53 +43,74 @@ Then open the $\{jetty.base}/start.ini file and edit the properties to suit your
 ## Enable for an open port accessible by remote machines
 jetty.jmxrmihost=localhost
 jetty.jmxrmiport=1099
-## Strictly speaking you shouldn't need --exec to use this in most environments.
-## If this isn't working, make sure you enable --exec as well
--Dcom.sun.management.jmxremote
-    
 ....
 
-===== Starting the Jetty Maven Plugin
-
-If you are running the Jetty Maven Plugin, you must set the system property com.sun.management.jmxremote on Maven before running the plugin. 
-The way to do this is to set your MAVEN_OPTS environment variable (if you're not sure how to do this, consult the  Maven documentation).
-
-Here is an example that sets the system property on the fly in a BASH shell, before starting Jetty via the plugin:
-
-[source, screen, subs="{sub-order}"]
-....
+[[jetty-jconsole-monitoring]]
+==== Monitoring Jetty with JConsole
 
-$ export MAVEN_OPTS=-Dcom.sun.management.jmxremote
-$ mvn jetty:run
-$ jconsole &        # runs jconsole in the background 
-      
-....
+To monitor Jetty's server status with JConsole, start Jetty and then start JConsole by typing `jconsole` on the command line.
 
 ===== Connecting to your server process
 
-When you start Jetty, you see a dialog box from JConsole with a list of running processes to which you can connect. It should look something like so:
+After you start Jetty, you will see a dialog box in JConsole with a list of running processes to which you can connect.
+It should look something like so:
 
 image:images/jconsole1.jpg[image,width=576]
 
 ____
 [IMPORTANT]
-If you don't see your Jetty process in the list of processes you can
-connect to, quickly switch tabs, or close and reopen a new "New
-Connection" dialog window. This forces JConsole to refresh the list, and
-recognize your newly-started Jetty process.
+If you don't see your Jetty process in the list of processes you can connect to, quickly switch tabs, or close and reopen a new "New Connection" dialog window.
+This forces JConsole to refresh the list, and recognize your newly-started Jetty process.
 ____
 
-Select the start.jar entry and click the "Connect" button. 
+Select the start.jar entry and click the "Connect" button.
 A new JConsole window opens:
 
 image:images/jconsole2.jpg[image,width=576]
 
-From this window you can monitor memory usage, thread usage, classloading and VM statistics. 
-You can also perform operations such as a manual garbage collect. 
+From this window you can monitor memory usage, thread usage, classloading and VM statistics.
+You can also perform operations such as a manual garbage collect.
 JConsole is an extremely powerful and useful tool.
 
 ==== Managing Jetty Objects with JConsole
 
-The MBean tab of JConsole allows access to managed objects within the Java application, including MBeans the JVM provides. 
-If you also want to interact with the Jetty JMX implementation via JConsole, you need to start Jetty JMX in a form that JConsole can access. 
+The MBean tab of JConsole allows access to managed objects within the Java application, including MBeans the JVM provides.
+If you also want to interact with the Jetty JMX implementation via JConsole, you need to start Jetty JMX in a form that JConsole can access.
 See xref:using-jmx[] for more information.
+
+image:images/jconsole3.png[image,width=576]
+
+[[jetty-jmc-monitoring]]
+==== Monitoring Jetty with JMC
+
+To monitor Jetty's server status with JMC, start Jetty and then start JMC by typing `jmc` on the command line.
+
+===== Connecting to your server process
+
+After you start Jetty, you will see a dialog box in JMC with a list of running processes to which you can connect.
+It should look something like so:
+
+image:images/jmc1.png[image,width=576]
+
+____
+[IMPORTANT]
+If you don't see your Jetty process in the list of processes you can connect to, quickly switch tabs, or close and reopen a new "New Connection" dialog window.
+This forces JMC to refresh the list, and recognize your newly-started Jetty process.
+____
+
+Double-click the start.jar entry or right-click the start.jar entry and select "Start JMX Console".
+A new JMC window opens on the right:
+
+image:images/jmc2.png[image,width=576]
+
+From this window you can monitor memory usage, thread usage, classloading and VM statistics.
+You can also perform operations such as a manual garbage collect.
+JMC is an extremely powerful and useful tool.
+
+==== Managing Jetty Objects with JConsole
+
+The MBean tab of JMC allows access to managed objects within the Java application, including MBeans the JVM provides.
+If you also want to interact with the Jetty JMX implementation via JMC, you need to start Jetty JMX in a form that JMC can access.
+See xref:using-jmx[] for more information.
+
+image:images/jmc3.png[image,width=576]

jetty-documentation/src/main/asciidoc/administration/jmx/jetty-jmx-annotations.adoc

@@ -17,28 +17,30 @@
 [[jetty-jmx-annotations]]
 === Jetty JMX Annotations
 
-When the jetty-jmx libraries are present on startup and the wiring is enabled for exposing jetty mbeans to jmx, there are three annotations that govern when and how mbeans are created and exposed.
+When the `jetty-jmx` libraries are present on startup and the wiring is enabled for exposing Jetty MBeans to JMX, there are three annotations that govern when and how MBeans are created and exposed.
 
 [[jmx-annotation-introspection]]
 ==== Annotation Introspection
 
-When jmx is configured and enabled in jetty any time an object is registered with the Server it is introspected as a potential mbean to be exposed. 
+When JMX is configured and enabled in Jetty, any time an object is registered with the Server it is introspected as a potential MBean to be exposed.
 This introspection proceeds as follows assuming the class is named `com.acme.Foo`:
 
-1.  All influences for `com.acme.Foo` determined. These include each class in the chain of super classes, and by convention each of these classes following a form of `com.acme.jmx.FooMBean`. 
+1.  All influences for `com.acme.Foo` determined.
+These include each class in the chain of super classes, and by convention each of these classes following a form of `com.acme.jmx.FooMBean`.
 All super classes and their corresponding MBean representations are then used in the next step.
-2.  Each potential influencing class is checked for the @ManagedObject annotation, should this annotation exist at any point in the chain of influencers then a mbean is created with the description of the version @ManageObject discovered.
-3.  Once an mbean has been created for an object then each potential influencing object is introspected for @ManagedAttribute and @ManagedOperation annotations and the corresponding type is exposed to the mbean.
+2.  Each potential influencing class is checked for the `@ManagedObject` annotation.
+Should this annotation exist at any point in the chain of influencers then an MBran is created with the description of the version `@ManagedObject` discovered.
+3.  Once a MBean has been created for an object then each potential influencing object is introspected for `@ManagedAttribute` and `@ManagedOperation` annotations and the corresponding type is exposed to the MBean.
 
-The convention of looking for @ManageObject annotations on `.jmx.ClassMBean` allows for a normal POJO to be wrapped in an mbean without itself without requiring it being marked up with annotations.
-Since the pojo is passed to these wrapped derived Mbean instances and is an internal variable then the MBean can be used to better expose a set of attributes and operations that may not have been anticipated when the original object was created.
+The convention of looking for `@ManagedObject` annotations on `.jmx.ClassMBean` allows for a normal POJOs to be wrapped in an MBean without itself without requiring it being marked up with annotations.
+Since the POJO is passed to these wrapped derived Mbean instances and is an internal variable then the MBean can be used to better expose a set of attributes and operations that may not have been anticipated when the original object was created.
 
 [[jmx-managed-object]]
 ==== @ManagedObject
 
-The @ManagedObject annotation is used on a class at the top level to indicate that it should be exposed as an mbean. 
-It has only one attribute to it which is used as the description of the MBean. 
-Should multiple @ManagedObject annotations be found in the chain of influence then the first description is used.
+The `@ManagedObject` annotation is used on a class at the top level to indicate that it should be exposed as an MBean.
+It has only one attribute to it which is used as the description of the MBean.
+Should multiple `@ManagedObject` annotations be found in the chain of influence then the first description is used.
 
 The list of attributes available are:
 
@@ -48,9 +50,10 @@ value::
 [[jmx-managed-attribute]]
 ==== @ManagedAttribute
 
-The @ManagedAttribute annotation is used to indicate that a given method exposes a JMX attribute. This annotation is placed always on the reader method of a given attribute. 
-Unless it is marked as read-only in the configuration of the annotation a corresponding setter is looked for following normal naming conventions. 
-For example if this annotation is on a method called getFoo() then a method called setFoo() would be looked for and if found wired automatically into the jmx attribute.
+The `@ManagedAttribute` annotation is used to indicate that a given method exposes a JMX attribute.
+This annotation is placed always on the reader method of a given attribute.
+Unless it is marked as read-only in the configuration of the annotation a corresponding setter is looked for following normal naming conventions.
+For example if this annotation is on a method called `getFoo()` then a method called `setFoo()` would be looked for and if found wired automatically into the JMX attribute.
 
 The list of attributes available are:
 
@@ -59,33 +62,33 @@ value::
 name::
   The name of the Managed Attribute.
 proxied::
-  Value is true if the corresponding mbean for this object contains the method of this JMX attribute in question.
+  Value is true if the corresponding MBean for this object contains the method of this JMX attribute in question.
 readonly::
-  By default this value is false which means that a corresponding setter will be looked for an wired into the attribute should one be found.  
-  Setting this to true make the jmx attribute read only.
+  By default this value is false which means that a corresponding setter will be looked for an wired into the attribute should one be found.
+  Setting this to true make the JMX attribute read only.
 setter::
   This attribute can be used when the corresponding setter for a JMX attribute follows a non-standard naming convention and it should still be exposed as the setter for the attribute.
 
 [[jmx-managed-operation]]
 ==== @ManagedOperation
 
-The @ManagedOperation annotation is used to indicate that a given method should be considered a JMX operation.
+The `@ManagedOperation` annotation is used to indicate that a given method should be considered a JMX operation.
 
 The list of attributes available are:
 
 value::
   The description of the Managed Operation.
 impact::
-  The impact of an operation. 
+  The impact of an operation.
   By default this value is "UNKNOWN" and acceptable values are "ACTION", "INFO", "ACTION_INFO" and should be used according to their definitions with JMX.
 proxied::
-  Value is true if the corresponding mbean for this object contains the method of this JMX operation in question.
+  Value is true if the corresponding MBean for this object contains the method of this JMX operation in question.
 
 [[jmx-name-annotation]]
 ==== @Name
 
-A fourth annotation is often used in conjunction with the JMX annotations mentioned above. 
-This annotation is used to describe variables in method signatures so that when rendered into tools like JConsole it is clear what the parameters are. 
+A fourth annotation is often used in conjunction with the JMX annotations mentioned above.
+This annotation is used to describe variables in method signatures so that when rendered into tools like JConsole it is clear what the parameters are.
 For example:
 
 The list of attributes available are:
@@ -132,7 +135,4 @@ public class Derived extends Base implements Signature
         System.err.println("doodle "+doodle);
     }
 }
-
-
-      
 ----