You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@struts.apache.org by mr...@apache.org on 2007/10/21 15:01:38 UTC
svn commit: r586892 - in
/struts/sandbox/trunk/struts2-rest-plugin/src/main/java/org/apache/struts2/rest:
./ handler/
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>
- * <action name="movie/*" className="app.MovieAction">
- * <param name="id">{0}</param>
- * ...
- * </action>
- * </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