struts-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From mr...@apache.org
Subject svn commit: r586892 - in /struts/sandbox/trunk/struts2-rest-plugin/src/main/java/org/apache/struts2/rest: ./ handler/
Date Sun, 21 Oct 2007 13:01:38 GMT
Author: mrdon
Date: Sun Oct 21 06:01:37 2007
New Revision: 586892

URL: http://svn.apache.org/viewvc?rev=586892&view=rev
Log:
Adding javadocs

Modified:
    struts/sandbox/trunk/struts2-rest-plugin/src/main/java/org/apache/struts2/rest/ContentTypeHandlerManager.java
    struts/sandbox/trunk/struts2-rest-plugin/src/main/java/org/apache/struts2/rest/ContentTypeInterceptor.java
    struts/sandbox/trunk/struts2-rest-plugin/src/main/java/org/apache/struts2/rest/DefaultRestInfo.java
    struts/sandbox/trunk/struts2-rest-plugin/src/main/java/org/apache/struts2/rest/RestActionInvocation.java
    struts/sandbox/trunk/struts2-rest-plugin/src/main/java/org/apache/struts2/rest/RestActionMapper.java
    struts/sandbox/trunk/struts2-rest-plugin/src/main/java/org/apache/struts2/rest/RestActionProxyFactory.java
    struts/sandbox/trunk/struts2-rest-plugin/src/main/java/org/apache/struts2/rest/RestInfo.java
    struts/sandbox/trunk/struts2-rest-plugin/src/main/java/org/apache/struts2/rest/RestWorkflowInterceptor.java
    struts/sandbox/trunk/struts2-rest-plugin/src/main/java/org/apache/struts2/rest/handler/ContentTypeHandler.java
    struts/sandbox/trunk/struts2-rest-plugin/src/main/java/org/apache/struts2/rest/handler/HtmlHandler.java
    struts/sandbox/trunk/struts2-rest-plugin/src/main/java/org/apache/struts2/rest/handler/XStreamHandler.java
    struts/sandbox/trunk/struts2-rest-plugin/src/main/java/org/apache/struts2/rest/handler/XStreamJsonHandler.java

Modified: struts/sandbox/trunk/struts2-rest-plugin/src/main/java/org/apache/struts2/rest/ContentTypeHandlerManager.java
URL: http://svn.apache.org/viewvc/struts/sandbox/trunk/struts2-rest-plugin/src/main/java/org/apache/struts2/rest/ContentTypeHandlerManager.java?rev=586892&r1=586891&r2=586892&view=diff
==============================================================================
--- struts/sandbox/trunk/struts2-rest-plugin/src/main/java/org/apache/struts2/rest/ContentTypeHandlerManager.java
(original)
+++ struts/sandbox/trunk/struts2-rest-plugin/src/main/java/org/apache/struts2/rest/ContentTypeHandlerManager.java
Sun Oct 21 06:01:37 2007
@@ -38,6 +38,10 @@
 import com.opensymphony.xwork2.inject.Container;
 import com.opensymphony.xwork2.inject.Inject;
 
+/**
+ * Manages {@link ContentTypeHandler} instances and uses them to
+ * process results
+ */
 public class ContentTypeHandlerManager {
 
     private Map<String,ContentTypeHandler> handlers = new HashMap<String,ContentTypeHandler>();
@@ -57,6 +61,11 @@
         }
     }
     
+    /**
+     * Gets the handler for the request by looking at the extension
+     * @param req The request
+     * @return The appropriate handler
+     */
     public ContentTypeHandler getHandlerForRequest(HttpServletRequest req) {
         String extension = findExtension(req.getRequestURI());
         if (extension == null) {
@@ -65,6 +74,15 @@
         return handlers.get(extension);
     }
     
+    /**
+     * Handles the result using handlers to generate content type-specific content
+     * 
+     * @param actionConfig The action config for the current request
+     * @param methodResult The object returned from the action method
+     * @param target The object to return, usually the action object
+     * @return The new result code to process
+     * @throws IOException If unable to write to the response
+     */
     public String handleResult(ActionConfig actionConfig, Object methodResult, Object target)
             throws IOException {
         String resultCode = null;
@@ -109,6 +127,12 @@
         
     }
     
+    /**
+     * Finds the extension in the url
+     * 
+     * @param url The url
+     * @return The extension
+     */
     protected String findExtension(String url) {
         int dotPos = url.lastIndexOf('.');
         int slashPos = url.lastIndexOf('/');

Modified: struts/sandbox/trunk/struts2-rest-plugin/src/main/java/org/apache/struts2/rest/ContentTypeInterceptor.java
URL: http://svn.apache.org/viewvc/struts/sandbox/trunk/struts2-rest-plugin/src/main/java/org/apache/struts2/rest/ContentTypeInterceptor.java?rev=586892&r1=586891&r2=586892&view=diff
==============================================================================
--- struts/sandbox/trunk/struts2-rest-plugin/src/main/java/org/apache/struts2/rest/ContentTypeInterceptor.java
(original)
+++ struts/sandbox/trunk/struts2-rest-plugin/src/main/java/org/apache/struts2/rest/ContentTypeInterceptor.java
Sun Oct 21 06:01:37 2007
@@ -30,8 +30,12 @@
 import com.opensymphony.xwork2.inject.Inject;
 import com.opensymphony.xwork2.interceptor.Interceptor;
 
+/**
+ * Uses the content handler to apply the request body to the action
+ */
 public class ContentTypeInterceptor implements Interceptor {
 
+    private static final long serialVersionUID = 1L;
     ContentTypeHandlerManager selector;
     
     @Inject

Modified: struts/sandbox/trunk/struts2-rest-plugin/src/main/java/org/apache/struts2/rest/DefaultRestInfo.java
URL: http://svn.apache.org/viewvc/struts/sandbox/trunk/struts2-rest-plugin/src/main/java/org/apache/struts2/rest/DefaultRestInfo.java?rev=586892&r1=586891&r2=586892&view=diff
==============================================================================
--- struts/sandbox/trunk/struts2-rest-plugin/src/main/java/org/apache/struts2/rest/DefaultRestInfo.java
(original)
+++ struts/sandbox/trunk/struts2-rest-plugin/src/main/java/org/apache/struts2/rest/DefaultRestInfo.java
Sun Oct 21 06:01:37 2007
@@ -27,6 +27,9 @@
 import javax.servlet.http.HttpServletRequest;
 import javax.servlet.http.HttpServletResponse;
 
+/**
+ * Default implementation of rest info that uses fluent-style construction
+ */
 public class DefaultRestInfo implements RestInfo {
     String resultCode;
     int status = SC_OK;

Modified: struts/sandbox/trunk/struts2-rest-plugin/src/main/java/org/apache/struts2/rest/RestActionInvocation.java
URL: http://svn.apache.org/viewvc/struts/sandbox/trunk/struts2-rest-plugin/src/main/java/org/apache/struts2/rest/RestActionInvocation.java?rev=586892&r1=586891&r2=586892&view=diff
==============================================================================
--- struts/sandbox/trunk/struts2-rest-plugin/src/main/java/org/apache/struts2/rest/RestActionInvocation.java
(original)
+++ struts/sandbox/trunk/struts2-rest-plugin/src/main/java/org/apache/struts2/rest/RestActionInvocation.java
Sun Oct 21 06:01:37 2007
@@ -66,14 +66,9 @@
 
 
 /**
- * The Default ActionInvocation implementation
- *
- * @author Rainer Hermanns
- * @author tmjee
- * 
- * @version $Date: 2007-04-26 23:36:51 +1000 (Thu, 26 Apr 2007) $ $Id: DefaultActionInvocation.java
1499 2007-04-26 13:36:51Z mrdon $
- * 
- * @see com.opensymphony.xwork2.DefaultActionProxy
+ * Extends the usual {@link ActionInvocation} to add support for processing the object returned
+ * from the action execution.  This allows us to support methods that return {@link RestInfo}
+ * as well as apply content type-specific operations to the result.
  */
 public class RestActionInvocation extends DefaultActionInvocation {
     

Modified: struts/sandbox/trunk/struts2-rest-plugin/src/main/java/org/apache/struts2/rest/RestActionMapper.java
URL: http://svn.apache.org/viewvc/struts/sandbox/trunk/struts2-rest-plugin/src/main/java/org/apache/struts2/rest/RestActionMapper.java?rev=586892&r1=586891&r2=586892&view=diff
==============================================================================
--- struts/sandbox/trunk/struts2-rest-plugin/src/main/java/org/apache/struts2/rest/RestActionMapper.java
(original)
+++ struts/sandbox/trunk/struts2-rest-plugin/src/main/java/org/apache/struts2/rest/RestActionMapper.java
Sun Oct 21 06:01:37 2007
@@ -39,60 +39,38 @@
 /**
  * <!-- START SNIPPET: description -->
  *
- * Improved restful action mapper that adds several ReST-style improvements to
- * action mapping, but supports fully-customized URL's via XML.  The two primary
- * ReST enhancements are:
- * <ul>
- *  <li>If the method is not specified (via '!' or 'method:' prefix), the method is
- *      "guessed" at using ReST-style conventions that examine the URL and the HTTP
- *      method.</li>
- *  <li>Parameters are extracted from the action name, if parameter name/value pairs
- *      are specified using PARAM_NAME/PARAM_VALUE syntax.
- * </ul>
- * <p>
- * These two improvements allow a GET request for 'category/action/movie/Thrillers' to
- * be mapped to the action name 'movie' with an id of 'Thrillers' with an extra parameter
- * named 'category' with a value of 'action'.  A single action mapping can then handle
- * all CRUD operations using wildcards, e.g.
- * </p>
- * <pre>
- *   &lt;action name="movie/*" className="app.MovieAction"&gt;
- *     &lt;param name="id"&gt;{0}&lt;/param&gt;
- *     ...
- *   &lt;/action&gt;
- * </pre>
+ * Restful action mapper that enforces Ruby-On-Rails Rest-style mappings.If the method 
+ * is not specified (via '!' or 'method:' prefix), the method is "guessed" at using 
+ * ReST-style conventions that examine the URL and the HTTP method.  Special care has
+ * been given to ensure this mapper works correctly with the codebehind plugin so that
+ * XML configuration is unnecessary.
+ *  
  * <p>
  *   This mapper supports the following parameters:
  * </p>
  * <ul>
  *   <li><code>struts.mapper.idParameterName</code> - If set, this value
will be the name
  *       of the parameter under which the id is stored.  The id will then be removed
- *       from the action name.  This allows restful actions to not require wildcards.
+ *       from the action name.  Whether or not the method is specified, the mapper will 
+ *       try to truncate the identifier from the url and store it as a parameter.
  *   </li>
  * </ul>
  * <p>
  * The following URL's will invoke its methods:
  * </p>
  * <ul> 
- *  <li><code>GET:    /movie/               => method="index"</code></li>
- *  <li><code>GET:    /movie/Thrillers      => method="show", id="Thrillers"</code></li>
- *  <li><code>GET:    /movie/Thrillers;edit => method="input", id="Thrillers"</code></li>
- *  <li><code>GET:    /movie/new            => method="input"</code></li>
- *  <li><code>POST:   /movie/               => method="create"</code></li>
- *  <li><code>PUT:    /movie/Thrillers      => method="update", id="Thrillers"</code></li>
- *  <li><code>DELETE: /movie/Thrillers      => method="destroy", id="Thrillers"</code></li>
+ *  <li><code>GET:    /movies                => method="index"</code></li>
+ *  <li><code>GET:    /movies/Thrillers      => method="show", id="Thrillers"</code></li>
+ *  <li><code>GET:    /movies/Thrillers;edit => method="edit", id="Thrillers"</code></li>
+ *  <li><code>GET:    /movies/new            => method="editNew"</code></li>
+ *  <li><code>POST:   /movies                => method="create"</code></li>
+ *  <li><code>PUT:    /movies/Thrillers      => method="update", id="Thrillers"</code></li>
+ *  <li><code>DELETE: /movies/Thrillers      => method="destroy", id="Thrillers"</code></li>
  * </ul>
  * <p>
  * To simulate the HTTP methods PUT and DELETE, since they aren't supported by HTML,
- * the HTTP parameter "__http_method" will be used.
- * </p>
- * <p>
- * The syntax and design for this feature was inspired by the ReST support in Ruby on Rails.
- * See <a href="http://ryandaigle.com/articles/2006/08/01/whats-new-in-edge-rails-simply-restful-support-and-how-to-use-it">
- * http://ryandaigle.com/articles/2006/08/01/whats-new-in-edge-rails-simply-restful-support-and-how-to-use-it
- * </a>
+ * the HTTP parameter "_method" will be used.
  * </p>
- *
  * <!-- END SNIPPET: description -->
  */
 public class RestActionMapper extends DefaultActionMapper {
@@ -208,7 +186,8 @@
     }
     
     /**
-     * Parses the name and namespace from the uri.  Doesn't allow slashes in name.
+     * Parses the name and namespace from the uri.  Uses the configured package 
+     * namespaces to determine the name and id parameter, to be parsed later.
      *
      * @param uri
      *            The uri

Modified: struts/sandbox/trunk/struts2-rest-plugin/src/main/java/org/apache/struts2/rest/RestActionProxyFactory.java
URL: http://svn.apache.org/viewvc/struts/sandbox/trunk/struts2-rest-plugin/src/main/java/org/apache/struts2/rest/RestActionProxyFactory.java?rev=586892&r1=586891&r2=586892&view=diff
==============================================================================
--- struts/sandbox/trunk/struts2-rest-plugin/src/main/java/org/apache/struts2/rest/RestActionProxyFactory.java
(original)
+++ struts/sandbox/trunk/struts2-rest-plugin/src/main/java/org/apache/struts2/rest/RestActionProxyFactory.java
Sun Oct 21 06:01:37 2007
@@ -31,7 +31,7 @@
 
 
 /**
- * 
+ * Factory that creates the {@link RestActionInvocation}
  */
 public class RestActionProxyFactory extends DefaultActionProxyFactory {
 

Modified: struts/sandbox/trunk/struts2-rest-plugin/src/main/java/org/apache/struts2/rest/RestInfo.java
URL: http://svn.apache.org/viewvc/struts/sandbox/trunk/struts2-rest-plugin/src/main/java/org/apache/struts2/rest/RestInfo.java?rev=586892&r1=586891&r2=586892&view=diff
==============================================================================
--- struts/sandbox/trunk/struts2-rest-plugin/src/main/java/org/apache/struts2/rest/RestInfo.java
(original)
+++ struts/sandbox/trunk/struts2-rest-plugin/src/main/java/org/apache/struts2/rest/RestInfo.java
Sun Oct 21 06:01:37 2007
@@ -23,10 +23,23 @@
 import javax.servlet.http.HttpServletRequest;
 import javax.servlet.http.HttpServletResponse;
 
+/**
+ * Type-safe rest-related information to apply to a response
+ */
 public interface RestInfo {
 
+    /**
+     * Applies the configured information to the response
+     * @param request The request
+     * @param response The response
+     * @param target The target object, usually the action
+     * @return The result code to process
+     */
     String apply(HttpServletRequest request,
             HttpServletResponse response, Object target);
     
+    /**
+     * The HTTP status code
+     */
     int getStatus();
 }

Modified: struts/sandbox/trunk/struts2-rest-plugin/src/main/java/org/apache/struts2/rest/RestWorkflowInterceptor.java
URL: http://svn.apache.org/viewvc/struts/sandbox/trunk/struts2-rest-plugin/src/main/java/org/apache/struts2/rest/RestWorkflowInterceptor.java?rev=586892&r1=586891&r2=586892&view=diff
==============================================================================
--- struts/sandbox/trunk/struts2-rest-plugin/src/main/java/org/apache/struts2/rest/RestWorkflowInterceptor.java
(original)
+++ struts/sandbox/trunk/struts2-rest-plugin/src/main/java/org/apache/struts2/rest/RestWorkflowInterceptor.java
Sun Oct 21 06:01:37 2007
@@ -42,6 +42,10 @@
  *
  * An interceptor that makes sure there are not validation errors before allowing the interceptor
chain to continue.
  * <b>This interceptor does not perform any validation</b>.
+ * 
+ * <p>Copied from the {@link DefaultWorkflowInterceptor}, this interceptor adds support
for error handling of Restful
+ * operations.  For example, if an validation error is discovered, a map of errors is created
and processed to be
+ * returned, using the appropriate content handler for rendering the body.</p>
  *
  * <p/>This interceptor does nothing if the name of the method being invoked is specified
in the <b>excludeMethods</b>
  * parameter. <b>excludeMethods</b> accepts a comma-delimited list of method
names. For example, requests to
@@ -153,8 +157,8 @@
 	}
 	
 	/**
-	 * Intercept {@link ActionInvocation} and returns a <code>inputResultName</code>
-	 * when action / field errors is found registered.
+	 * Intercept {@link ActionInvocation} and processes the errors using the {@link ContentTypeHandler}
+	 * appropriate for the request.  
 	 * 
 	 * @return String result name
 	 */

Modified: struts/sandbox/trunk/struts2-rest-plugin/src/main/java/org/apache/struts2/rest/handler/ContentTypeHandler.java
URL: http://svn.apache.org/viewvc/struts/sandbox/trunk/struts2-rest-plugin/src/main/java/org/apache/struts2/rest/handler/ContentTypeHandler.java?rev=586892&r1=586891&r2=586892&view=diff
==============================================================================
--- struts/sandbox/trunk/struts2-rest-plugin/src/main/java/org/apache/struts2/rest/handler/ContentTypeHandler.java
(original)
+++ struts/sandbox/trunk/struts2-rest-plugin/src/main/java/org/apache/struts2/rest/handler/ContentTypeHandler.java
Sun Oct 21 06:01:37 2007
@@ -26,12 +26,40 @@
 
 import com.opensymphony.xwork2.ActionInvocation;
 
+/**
+ * Handles transferring content to and from objects for a specific content type
+ */
 public interface ContentTypeHandler {
+    
+    /**
+     * Populates an object using data from the input stream
+     * @param in The input stream, usually the body of the request
+     * @param target The target, usually the action class
+     */
     void toObject(InputStream in, Object target);
     
+    /**
+     * Writes content to the stream
+     * 
+     * @param obj The object to write to the stream, usually the Action class
+     * @param resultCode The original result code
+     * @param stream The output stream, usually the response
+     * @return The new result code
+     * @throws IOException If unable to write to the output stream
+     */
     String fromObject(Object obj, String resultCode, OutputStream stream) throws IOException;
     
+    /**
+     * Gets the content type for this handler
+     * 
+     * @return The mime type
+     */
     String getContentType();
     
+    /**
+     * Gets the extension this handler supports
+     * 
+     * @return The extension
+     */
     String getExtension();
 }

Modified: struts/sandbox/trunk/struts2-rest-plugin/src/main/java/org/apache/struts2/rest/handler/HtmlHandler.java
URL: http://svn.apache.org/viewvc/struts/sandbox/trunk/struts2-rest-plugin/src/main/java/org/apache/struts2/rest/handler/HtmlHandler.java?rev=586892&r1=586891&r2=586892&view=diff
==============================================================================
--- struts/sandbox/trunk/struts2-rest-plugin/src/main/java/org/apache/struts2/rest/handler/HtmlHandler.java
(original)
+++ struts/sandbox/trunk/struts2-rest-plugin/src/main/java/org/apache/struts2/rest/handler/HtmlHandler.java
Sun Oct 21 06:01:37 2007
@@ -28,6 +28,9 @@
 import com.opensymphony.xwork2.Action;
 import com.opensymphony.xwork2.ActionInvocation;
 
+/**
+ * Handles HTML content, usually just a simple passthrough to the framework
+ */
 public class HtmlHandler implements ContentTypeHandler {
 
     public String fromObject(Object obj, String resultCode, OutputStream out) throws IOException
{

Modified: struts/sandbox/trunk/struts2-rest-plugin/src/main/java/org/apache/struts2/rest/handler/XStreamHandler.java
URL: http://svn.apache.org/viewvc/struts/sandbox/trunk/struts2-rest-plugin/src/main/java/org/apache/struts2/rest/handler/XStreamHandler.java?rev=586892&r1=586891&r2=586892&view=diff
==============================================================================
--- struts/sandbox/trunk/struts2-rest-plugin/src/main/java/org/apache/struts2/rest/handler/XStreamHandler.java
(original)
+++ struts/sandbox/trunk/struts2-rest-plugin/src/main/java/org/apache/struts2/rest/handler/XStreamHandler.java
Sun Oct 21 06:01:37 2007
@@ -26,6 +26,9 @@
 
 import com.thoughtworks.xstream.XStream;
 
+/**
+ * Handles XML content
+ */
 public class XStreamHandler implements ContentTypeHandler {
 
     public String fromObject(Object obj, String resultCode, OutputStream out) throws IOException
{

Modified: struts/sandbox/trunk/struts2-rest-plugin/src/main/java/org/apache/struts2/rest/handler/XStreamJsonHandler.java
URL: http://svn.apache.org/viewvc/struts/sandbox/trunk/struts2-rest-plugin/src/main/java/org/apache/struts2/rest/handler/XStreamJsonHandler.java?rev=586892&r1=586891&r2=586892&view=diff
==============================================================================
--- struts/sandbox/trunk/struts2-rest-plugin/src/main/java/org/apache/struts2/rest/handler/XStreamJsonHandler.java
(original)
+++ struts/sandbox/trunk/struts2-rest-plugin/src/main/java/org/apache/struts2/rest/handler/XStreamJsonHandler.java
Sun Oct 21 06:01:37 2007
@@ -23,6 +23,9 @@
 import com.thoughtworks.xstream.XStream;
 import com.thoughtworks.xstream.io.json.JettisonMappedXmlDriver;
 
+/**
+ * Handles JSON content using XStream
+ */
 public class XStreamJsonHandler extends XStreamHandler {
 
     @Override



Mime
View raw message