416453 Add comments to embedded SecuredHelloHandler example

examples/embedded/src/main/java/org/eclipse/jetty/embedded/SecuredHelloHandler.java

@@ -34,32 +34,57 @@ public class SecuredHelloHandler
 {
     public static void main(String[] args) throws Exception
     {
+        // Create a basic jetty server object that will listen on port 8080.  Note that if you set this to port 0
+        // then a randomly available port will be assigned that you can either look in the logs for the port,
+        // or programmatically obtain it for use in test cases.
         Server server = new Server(8080);
-        
+
+        // Since this example is for our test webapp, we need to setup a LoginService so this shows how to create a
+        // very simple hashmap based one.  The name of the LoginService needs to correspond to what is configured a
+        // webapp's web.xml and since it has a lifecycle of its own we register it as a bean with the Jetty server
+        // object so it can be started and stopped according to the lifecycle of the server itself. In this example
+        // the name can be whatever you like since we are not dealing with webapp realms.
         LoginService loginService = new HashLoginService("MyRealm","src/test/resources/realm.properties");
         server.addBean(loginService); 
 
+        // A security handler is a jetty handler that secures content behind a particular portion of a url space. The
+        // ConstraintSecurityHandler is a more specialized handler that allows matching of urls to different
+        // constraints. The server sets this as the first handler in the chain,
+        // effectively applying these constraints to all subsequent handlers in the chain.
         ConstraintSecurityHandler security = new ConstraintSecurityHandler();
         server.setHandler(security);
 
+        // This constraint requires authentication and in addition that an authenticated user be a member of a given
+        // set of roles for authorization purposes.
         Constraint constraint = new Constraint();
         constraint.setName("auth");
         constraint.setAuthenticate( true );
         constraint.setRoles(new String[]{"user", "admin"});
 
+        // Binds a url pattern with the previously created constraint. The roles for this constraing mapping are
+        // mined from the Constraint itself although methods exist to declare and bind roles separately as well.
         ConstraintMapping mapping = new ConstraintMapping();
         mapping.setPathSpec( "/*" );
         mapping.setConstraint( constraint );
 
+        // First you see the constraint mapping being applied to the handler as a singleton list,
+        // however you can passing in as many security constraint mappings as you like so long as they follow the
+        // mapping requirements of the servlet api. Next we set a BasicAuthenticator instance which is the object
+        // that actually checks the credentials followed by the LoginService which is the store of known users, etc.
         security.setConstraintMappings(Collections.singletonList(mapping));
         security.setAuthenticator(new BasicAuthenticator());
         security.setLoginService(loginService);
         security.setStrict(false);
-        
+
+        // The Hello Handler is the handler we are securing so we create one, and then set it as the handler on the
+        // security handler to complain the simple handler chain.
         HelloHandler hh = new HelloHandler();
-        
+
+        // chain the hello handler into the security handler
         security.setHandler(hh);
-        
+
+        // Start things up! By using the server.join() the server thread will join with the current thread.
+        // See "http://docs.oracle.com/javase/1.5.0/docs/api/java/lang/Thread.html#join()" for more details.
         server.start();
         server.join();
     }