improved javadocs

git-svn-id: svn+ssh://dev.eclipse.org/svnroot/rt/org.eclipse.jetty/jetty/trunk@41 7e9141cc-0065-0410-87d8-b60c137991c4

jetty-eclipse-codetemplates.xml

@@ -1,4 +1,50 @@
-<?xml version="1.0" encoding="UTF-8" standalone="no"?><templates><template autoinsert="false" context="constructorcomment_context" deleted="false" description="Comment for created constructors" enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.constructorcomment" name="constructorcomment">/* ------------------------------------------------------------ */
+<?xml version="1.0" encoding="UTF-8" standalone="no"?><templates><template autoinsert="false" context="gettercomment_context" deleted="false" description="Comment for getter method" enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.gettercomment" name="gettercomment">/* ------------------------------------------------------------ */
+/** Get the ${bare_field_name}.
+ * @return the ${bare_field_name}
+ */</template><template autoinsert="false" context="settercomment_context" deleted="false" description="Comment for setter method" enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.settercomment" name="settercomment">/* ------------------------------------------------------------ */
+/** Set the ${bare_field_name}.
+ * @param ${param} the ${bare_field_name} to set
+ */</template><template autoinsert="false" context="constructorcomment_context" deleted="false" description="Comment for created constructors" enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.constructorcomment" name="constructorcomment">/* ------------------------------------------------------------ */
 /**
  * ${tags}
- */</template></templates>
+ */</template><template autoinsert="false" context="filecomment_context" deleted="false" description="Comment for created Java files" enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.filecomment" name="filecomment">// ========================================================================
+// Copyright (c) 2009-2009 Mort Bay Consulting Pty. Ltd.
+// ------------------------------------------------------------------------
+// All rights reserved. This program and the accompanying materials
+// are made available under the terms of the Eclipse Public License v1.0
+// and Apache License v2.0 which accompanies this distribution.
+// The Eclipse Public License is available at 
+// http://www.eclipse.org/legal/epl-v10.html
+// The Apache License v2.0 is available at
+// http://www.opensource.org/licenses/apache2.0.php
+// You may elect to redistribute this code under either of these licenses. 
+// ========================================================================
+
+</template><template autoinsert="false" context="typecomment_context" deleted="false" description="Comment for created types" enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.typecomment" name="typecomment">
+/* ------------------------------------------------------------ */
+/**
+ * ${tags}
+ */</template><template autoinsert="true" context="fieldcomment_context" deleted="false" description="Comment for fields" enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.fieldcomment" name="fieldcomment">/**
+ * 
+ */</template><template autoinsert="false" context="methodcomment_context" deleted="false" description="Comment for non-overriding methods" enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.methodcomment" name="methodcomment">/* ------------------------------------------------------------ */
+/**
+ * ${tags}
+ */</template><template autoinsert="false" context="overridecomment_context" deleted="false" description="Comment for overriding methods" enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.overridecomment" name="overridecomment">/* ------------------------------------------------------------ */
+/**
+ * ${see_to_overridden}
+ */</template><template autoinsert="false" context="delegatecomment_context" deleted="false" description="Comment for delegate methods" enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.delegatecomment" name="delegatecomment">/* ------------------------------------------------------------ */
+/**
+ * ${tags}
+ * ${see_to_target}
+ */</template><template autoinsert="true" context="newtype_context" deleted="false" description="Newly created files" enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.newtype" name="newtype">${filecomment}
+${package_declaration}
+
+${typecomment}
+${type_declaration}</template><template autoinsert="true" context="classbody_context" deleted="false" description="Code in new class type bodies" enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.classbody" name="classbody">
+</template><template autoinsert="true" context="interfacebody_context" deleted="false" description="Code in new interface type bodies" enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.interfacebody" name="interfacebody">
+</template><template autoinsert="true" context="enumbody_context" deleted="false" description="Code in new enum type bodies" enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.enumbody" name="enumbody">
+</template><template autoinsert="true" context="annotationbody_context" deleted="false" description="Code in new annotation type bodies" enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.annotationbody" name="annotationbody">
+</template><template autoinsert="true" context="catchblock_context" deleted="false" description="Code in new catch blocks" enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.catchblock" name="catchblock">// ${todo} Auto-generated catch block
+${exception_var}.printStackTrace();</template><template autoinsert="true" context="methodbody_context" deleted="false" description="Code in created method stubs" enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.methodbody" name="methodbody">// ${todo} Auto-generated method stub
+${body_statement}</template><template autoinsert="true" context="constructorbody_context" deleted="false" description="Code in created constructor stubs" enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.constructorbody" name="constructorbody">${body_statement}
+// ${todo} Auto-generated constructor stub</template><template autoinsert="true" context="getterbody_context" deleted="false" description="Code in created getters" enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.getterbody" name="getterbody">return ${field};</template><template autoinsert="true" context="setterbody_context" deleted="false" description="Code in created setters" enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.setterbody" name="setterbody">${field} = ${param};</template></templates>

jetty-embedded-examples/src/main/java/org/eclipse/jetty/embedded/ManyConnectors.java

@@ -20,8 +20,6 @@ import javax.servlet.http.HttpServletRequest;
 import javax.servlet.http.HttpServletResponse;
 
 import org.eclipse.jetty.server.Connector;
-import org.eclipse.jetty.server.Handler;
-import org.eclipse.jetty.server.HttpConnection;
 import org.eclipse.jetty.server.Request;
 import org.eclipse.jetty.server.Server;
 import org.eclipse.jetty.server.bio.SocketConnector;
@@ -29,6 +27,12 @@ import org.eclipse.jetty.server.handler.AbstractHandler;
 import org.eclipse.jetty.server.nio.SelectChannelConnector;
 import org.eclipse.jetty.util.thread.QueuedThreadPool;
 
+
+/* ------------------------------------------------------------ */
+/**
+ * A Jetty server can have multiple connectors.
+ * 
+ */
 public class ManyConnectors
 {
     public static void main(String[] args)

jetty-embedded-examples/src/main/java/org/eclipse/jetty/embedded/ManyContexts.java

@@ -31,6 +31,14 @@ import org.eclipse.jetty.server.handler.DefaultHandler;
 import org.eclipse.jetty.server.handler.HandlerCollection;
 import org.eclipse.jetty.server.nio.SelectChannelConnector;
 
+
+/* ------------------------------------------------------------ */
+/**
+ * A {@link ContextHandlerCollection} handler may be used to
+ * direct a request to a specific Context. The URI path prefix
+ * and optional virtual host is used to select the context.
+ *
+ */
 public class ManyContexts
 {
     public static void main(String[] args)
@@ -42,22 +50,25 @@ public class ManyContexts
         server.setConnectors(new Connector[]{connector});
         
         ContextHandler context0 = new ContextHandler();
-        context0.setContextPath("/zero");
+        context0.setContextPath("/");
-        Handler handler0=new HelloHandler();
+        Handler handler0=new HelloHandler("Root Context");
         context0.setHandler(handler0);
 
         ContextHandler context1 = new ContextHandler();
-        context1.setContextPath("/one");
+        context1.setContextPath("/context");
-        Handler handler1=new HelloHandler();
+        Handler handler1=new HelloHandler("A Context");
         context1.setHandler(handler1);   
 
+        ContextHandler context2 = new ContextHandler();
+        context2.setContextPath("/context");
+        context2.setVirtualHosts(new String[]{"127.0.0.2"});
+        Handler handler2=new HelloHandler("A Virtual Context");
+        context2.setHandler(handler2);   
+        
         ContextHandlerCollection contexts = new ContextHandlerCollection();
-        contexts.setHandlers(new Handler[]{context0,context1});
+        contexts.setHandlers(new Handler[]{context0,context1,context2});
         
-        HandlerCollection handlers = new HandlerCollection();
+        server.setHandler(contexts);
-        handlers.setHandlers(new Handler[]{contexts,new DefaultHandler()});
-        
-        server.setHandler(handlers);
         
         server.start();
         server.join();
@@ -65,16 +76,23 @@ public class ManyContexts
 
     public static class HelloHandler extends AbstractHandler
     {
-        static int h=0;
+        String _welcome;
-        int hello=h++;
+        
+        HelloHandler(String welcome)
+        {
+            _welcome=welcome;
+        }
         
         public void handle(String target, HttpServletRequest request, HttpServletResponse response) throws IOException, ServletException
         {
-            Request base_request = (request instanceof Request) ? (Request)request:HttpConnection.getCurrentConnection().getRequest();
+            ((Request)request).setHandled(true);
-            base_request.setHandled(true);
             response.setStatus(HttpServletResponse.SC_OK);
             response.setContentType("text/html");
-            response.getWriter().println("<h1>Hello OneContext "+hello+"</h1>");
+            response.getWriter().println("<h1>"+_welcome+" "+request.getContextPath()+"</h1>");
+            response.getWriter().println("<a href='/'>root context</a><br/>");
+            response.getWriter().println("<a href='http://127.0.0.1:8080/context'>normal context</a><br/>");
+            response.getWriter().println("<a href='http://127.0.0.2:8080/context'>virtual context</a><br/>");
+            
         }
     }
     

jetty-embedded-examples/src/main/java/org/eclipse/jetty/embedded/ManyHandlers.java

@@ -13,47 +13,105 @@
 
 package org.eclipse.jetty.embedded;
 
+import java.io.File;
 import java.io.IOException;
+import java.util.Map;
 
 import javax.servlet.ServletException;
 import javax.servlet.http.HttpServletRequest;
 import javax.servlet.http.HttpServletResponse;
 
-import org.eclipse.jetty.server.Connector;
 import org.eclipse.jetty.server.Handler;
-import org.eclipse.jetty.server.HttpConnection;
+import org.eclipse.jetty.server.NCSARequestLog;
 import org.eclipse.jetty.server.Request;
 import org.eclipse.jetty.server.Server;
 import org.eclipse.jetty.server.handler.AbstractHandler;
+import org.eclipse.jetty.server.handler.DefaultHandler;
 import org.eclipse.jetty.server.handler.HandlerCollection;
-import org.eclipse.jetty.server.nio.SelectChannelConnector;
+import org.eclipse.jetty.server.handler.HandlerList;
+import org.eclipse.jetty.server.handler.HandlerWrapper;
+import org.eclipse.jetty.server.handler.RequestLogHandler;
+import org.eclipse.jetty.util.ajax.JSON;
 
+
+/* ------------------------------------------------------------ */
+/**
+ * Frequently many handlers are combined together to handle
+ * different aspects of a request.  A handler may:<ul>
+ * <li>handle the request and completely generate the response
+ * <li>partially handle the request, but defer response generation
+ * to another handler.
+ * <li>select another handler to pass the request to.
+ * <li>use business logic to decide to do one of the above.
+ * </ul>
+ * 
+ * Multiple handlers may be combined with:<ul>
+ * <li>{@link HandlerWrapper} which will nest one handler inside another. 
+ * In this example, the HelloHandler is nested inside a HandlerWrapper
+ * that sets the greeting as a request attribute.
+ * <li>{@link ListHandler} which will call a collection of handlers
+ * until the request is marked as handled.  In this example, a list
+ * is used to combine the param handler (which only handles the 
+ * request if there are parameters) and the wrapper handler. 
+ * Frequently handler lists are terminated with the {@link DefaultHandler},
+ * which will generate a suitable 404 response if the request has
+ * not been handled.
+ * <li>{@link HandlerCollection} which will call each handler
+ * regardless if the request has been handled or not. Typically
+ * this is used to always pass a request to the logging handler.
+ * </ul>
+ */
 public class ManyHandlers
 {
     public static void main(String[] args)
         throws Exception
     {
-        Server server = new Server();
+        Server server = new Server(8080);
-        Connector connector=new SelectChannelConnector();
-        connector.setPort(8080);
-        server.setConnectors(new Connector[]{connector});
         
+        // create the handlers
         Handler param=new ParamHandler();
+        HandlerWrapper wrapper = new HandlerWrapper()
+        {
+            public void handle(String target, HttpServletRequest request, HttpServletResponse response) throws IOException, ServletException
+            {
+                request.setAttribute("welcome","Hello");
+                super.handle(target,request,response);
+            }
+        };
         Handler hello=new HelloHandler();
+        Handler dft=new DefaultHandler();
+        RequestLogHandler log=new RequestLogHandler();
         
+        // configure logs
+        log.setRequestLog(new NCSARequestLog(File.createTempFile("demo","log").getAbsolutePath()));
+        
+        // create the handler collections
         HandlerCollection handlers = new HandlerCollection();
-        handlers.setHandlers(new Handler[]{param,hello});
+        HandlerList list = new HandlerList();
+        
+        // link them all together
+        wrapper.addHandler(hello);
+        list.setHandlers(new Handler[]{param,wrapper,dft});
+        handlers.setHandlers(new Handler[]{list,log});
+        
         server.setHandler(handlers);
         
         server.start();
         server.join();
     }
 
+    
     public static class ParamHandler extends AbstractHandler
     {
         public void handle(String target, HttpServletRequest request, HttpServletResponse response) throws IOException, ServletException
         {
-            System.err.println(request.getParameterMap());
+            Map params = request.getParameterMap();
+            if (params.size()>0)
+            {
+                response.setContentType("text/plain");
+                response.getWriter().println(JSON.toString(params));
+                ((Request)request).setHandled(true);
+            }
         }
     }
     
@@ -61,11 +119,10 @@ public class ManyHandlers
     {
         public void handle(String target, HttpServletRequest request, HttpServletResponse response) throws IOException, ServletException
         {
-            Request base_request = (request instanceof Request) ? (Request)request:HttpConnection.getCurrentConnection().getRequest();
-            base_request.setHandled(true);
             response.setContentType("text/html");
             response.setStatus(HttpServletResponse.SC_OK);
-            response.getWriter().println("<h1>Hello ManyHandler</h1>");
+            response.getWriter().println("<h1>"+request.getAttribute("welcome") +" ManyHandler</h1>");
+            ((Request)request).setHandled(true);
         }
     }
 }

jetty-embedded-examples/src/main/java/org/eclipse/jetty/embedded/OneContext.java

@@ -19,15 +19,21 @@ import javax.servlet.ServletException;
 import javax.servlet.http.HttpServletRequest;
 import javax.servlet.http.HttpServletResponse;
 
-import org.eclipse.jetty.server.Connector;
-import org.eclipse.jetty.server.Handler;
-import org.eclipse.jetty.server.HttpConnection;
 import org.eclipse.jetty.server.Request;
 import org.eclipse.jetty.server.Server;
 import org.eclipse.jetty.server.handler.AbstractHandler;
 import org.eclipse.jetty.server.handler.ContextHandler;
-import org.eclipse.jetty.server.nio.SelectChannelConnector;
 
+
+/* ------------------------------------------------------------ */
+/**
+ * A {@link ContextHandler} provides a common environment for
+ * multiple Handlers, such as: URI context path, class loader,
+ * static resource base.
+ *
+ * Typically a ContextHandler is used only when multiple contexts
+ * are likely.
+ */
 public class OneContext
 {
     public static void main(String[] args)

jetty-server/src/main/java/org/eclipse/jetty/server/handler/HandlerCollection.java

@@ -27,13 +27,12 @@ import org.eclipse.jetty.util.MultiException;
 /* ------------------------------------------------------------ */
 /** A collection of handlers.  
  * <p>
- * For derived HandlerCollections, the order or manner of calling
+ * The default implementations  calls all handlers in list order, 
- * the contained handlers is not defined. The default implementations
+ * regardless of the response status or exceptions. Derived implementation
- * calls all handlers in list order, regardless of 
+ * may alter the order or the conditions of calling the contained 
- * the response status or exceptions.
+ * handlers.
  * <p>
  * 
- * 
  * @org.apache.xbean.XBean
  */
 public class HandlerCollection extends AbstractHandlerContainer