Author: fmeschbe
Date: Wed May 14 11:28:57 2008
New Revision: 656351
URL: http://svn.apache.org/viewvc?rev=656351&view=rev
Log:
SLING-422 Add JavaDoc
Modified:
incubator/sling/trunk/servlets/post/src/main/java/org/apache/sling/servlets/post/AbstractSlingPostOperation.java
incubator/sling/trunk/servlets/post/src/main/java/org/apache/sling/servlets/post/SlingPostOperation.java
incubator/sling/trunk/servlets/post/src/main/java/org/apache/sling/servlets/post/impl/operations/AbstractCopyMoveOperation.java
incubator/sling/trunk/servlets/post/src/main/java/org/apache/sling/servlets/post/impl/operations/CopyOperation.java
incubator/sling/trunk/servlets/post/src/main/java/org/apache/sling/servlets/post/impl/operations/DeleteOperation.java
incubator/sling/trunk/servlets/post/src/main/java/org/apache/sling/servlets/post/impl/operations/ModifyOperation.java
incubator/sling/trunk/servlets/post/src/main/java/org/apache/sling/servlets/post/impl/operations/MoveOperation.java
Modified:
incubator/sling/trunk/servlets/post/src/main/java/org/apache/sling/servlets/post/AbstractSlingPostOperation.java
URL:
http://svn.apache.org/viewvc/incubator/sling/trunk/servlets/post/src/main/java/org/apache/sling/servlets/post/AbstractSlingPostOperation.java?rev=656351&r1=656350&r2=656351&view=diff
==============================================================================
---
incubator/sling/trunk/servlets/post/src/main/java/org/apache/sling/servlets/post/AbstractSlingPostOperation.java
(original)
+++
incubator/sling/trunk/servlets/post/src/main/java/org/apache/sling/servlets/post/AbstractSlingPostOperation.java
Wed May 14 11:28:57 2008
@@ -43,14 +43,17 @@
private final Logger log = LoggerFactory.getLogger(getClass());
/**
- * Creates a new post processor
+ * Prepares and finalizes the actual operation. Preparation encompasses
+ * getting the absolute path of the item to operate on by calling the
+ * [EMAIL PROTECTED] #getItemPath(SlingHttpServletRequest)} method and
setting the
+ * location and parent location on the response. After the operation has
+ * been done in the [EMAIL PROTECTED] #doRun(SlingHttpServletRequest,
HtmlResponse)}
+ * method the session is saved if there are unsaved modifications. In case
+ * of errorrs, the unsaved changes in the session are rolled back.
*
* @param request the request to operate on
- * @param session jcr session to operate on
- * @param nodeNameGenerator the node name generator. use a servlet scoped
- * one, so that it can hold states.
- * @param dateParser helper for parsing date strings
- * @param servletContext The ServletContext to use for file upload
+ * @param response The <code>HtmlResponse</code> to record execution
+ * progress.
*/
public final void run(SlingHttpServletRequest request, HtmlResponse
response) {
@@ -96,14 +99,14 @@
/**
* Returns the path of the resource of the request as the item path.
* <p>
- * This method may be overwritten by extension if the operation has
different
- * requirements on path processing.
+ * This method may be overwritten by extension if the operation has
+ * different requirements on path processing.
*/
protected String getItemPath(SlingHttpServletRequest request) {
return request.getResource().getPath();
}
-
- public abstract void doRun(SlingHttpServletRequest request,
+
+ protected abstract void doRun(SlingHttpServletRequest request,
HtmlResponse response) throws RepositoryException;
/**
@@ -197,7 +200,7 @@
if (!item.isNode()) {
return;
}
-
+
Node parent = item.getParent();
String next = null;
Modified:
incubator/sling/trunk/servlets/post/src/main/java/org/apache/sling/servlets/post/SlingPostOperation.java
URL:
http://svn.apache.org/viewvc/incubator/sling/trunk/servlets/post/src/main/java/org/apache/sling/servlets/post/SlingPostOperation.java?rev=656351&r1=656350&r2=656351&view=diff
==============================================================================
---
incubator/sling/trunk/servlets/post/src/main/java/org/apache/sling/servlets/post/SlingPostOperation.java
(original)
+++
incubator/sling/trunk/servlets/post/src/main/java/org/apache/sling/servlets/post/SlingPostOperation.java
Wed May 14 11:28:57 2008
@@ -21,13 +21,57 @@
import org.apache.sling.api.SlingHttpServletRequest;
import org.apache.sling.api.servlets.HtmlResponse;
+/**
+ * The <code>SlingPostOperation</code> interface defines the service API to be
+ * implemented by service providers extending the Sling default POST servlet.
+ * Service providers may register OSGi services of this type to be used by the
+ * Sling default POST servlet to handle specific operations.
+ * <p>
+ * The <code>SlingPostOperation</code> service must be registered with a
+ * [EMAIL PROTECTED] #PROP_OPERATION_NAME} registration property giving the
name(s) of the
+ * operations supported by the service. The names will be used to find the
+ * actual operation from the
+ * [EMAIL PROTECTED] SlingPostConstants#RP_OPERATION <code>:operation</code>}
request
+ * parameter.
+ * <p>
+ * The Sling default POST servlet defines the <code>copy</code>,
+ * <code>move</code> and <code>delete</code> operation names. These names
+ * should not be used by <code>SlingPostOperation</code> service providers.
+ */
public interface SlingPostOperation {
/**
- * @param request
- * @param response
+ * The name of the Sling POST operation service (value is
+ * "org.apache.sling.servlets.post.SlingPostOperation").
+ */
+ public static final String SERVICE_NAME =
SlingPostOperation.class.getName();
+
+ /**
+ * The name of the service registration property indicating the name(s) of
+ * the operation provided by the operation implementation (value is
+ * "sling.post.operation"). The value of this service property must be a
+ * single String or an array or <code>java.util.Vector</code> of Strings.
+ * If multiple strings are defined, the service is registered for all
+ * operation names.
+ */
+ public static final String PROP_OPERATION_NAME = "sling.post.operation";
+
+ /**
+ * Executes the operation provided by this service implementation. This
+ * method is called by the Sling default POST servlet.
+ *
+ * @param request The <code>SlingHttpServletRequest</code> object
+ * providing the request input for the operation.
+ * @param response The <code>HtmlResponse</code> into which the operation
+ * steps should be recorded.
+ * @throws org.apache.sling.api.resource.ResourceNotFoundException May be
+ * thrown if the operation requires an existing request
+ * resource. If this exception is thrown the Sling default POST
+ * servlet sends back a <code>404/NOT FOUND</code> response to
+ * the client.
* @throws org.apache.sling.api.SlingException May be thrown if an error
* occurrs running the operation.
*/
void run(SlingHttpServletRequest request, HtmlResponse response);
+
}
Modified:
incubator/sling/trunk/servlets/post/src/main/java/org/apache/sling/servlets/post/impl/operations/AbstractCopyMoveOperation.java
URL:
http://svn.apache.org/viewvc/incubator/sling/trunk/servlets/post/src/main/java/org/apache/sling/servlets/post/impl/operations/AbstractCopyMoveOperation.java?rev=656351&r1=656350&r2=656351&view=diff
==============================================================================
---
incubator/sling/trunk/servlets/post/src/main/java/org/apache/sling/servlets/post/impl/operations/AbstractCopyMoveOperation.java
(original)
+++
incubator/sling/trunk/servlets/post/src/main/java/org/apache/sling/servlets/post/impl/operations/AbstractCopyMoveOperation.java
Wed May 14 11:28:57 2008
@@ -30,18 +30,19 @@
import org.apache.sling.servlets.post.SlingPostConstants;
/**
- * Holds various states and encapsulates methods that are needed to handle a
- * post request.
+ * The <code>AbstractCopyMoveOperation</code> is the abstract base close for
+ * the [EMAIL PROTECTED] CopyOperation} and [EMAIL PROTECTED] MoveOperation}
classes implementing
+ * commong behaviour.
*/
abstract class AbstractCopyMoveOperation extends AbstractSlingPostOperation {
@Override
- public final void doRun(SlingHttpServletRequest request, HtmlResponse
response)
- throws RepositoryException {
+ protected final void doRun(SlingHttpServletRequest request,
+ HtmlResponse response) throws RepositoryException {
Resource resource = request.getResource();
String source = resource.getPath();
-
+
// ensure we have an item underlying the request's resource
Item item = resource.adaptTo(Item.class);
if (item == null) {
@@ -54,11 +55,12 @@
if (dest == null || dest.length() == 0) {
throw new IllegalArgumentException("Unable to process "
+ getOperationName() + ". Missing destination");
- } if (!dest.startsWith("/")) {
+ }
+ if (!dest.startsWith("/")) {
dest = ResourceUtil.getParent(source) + "/" + dest;
dest = ResourceUtil.normalize(dest);
}
-
+
Session session = item.getSession();
// delete destination if already exists
@@ -92,8 +94,23 @@
orderNode(request, session.getItem(dest));
}
+ /**
+ * Returns a short name to be used in log and status messages.
+ */
protected abstract String getOperationName();
+ /**
+ * Actually executes the operation.
+ *
+ * @param response The <code>HtmlResponse</code> used to record success of
+ * the operation.
+ * @param session The JCR <code>Session</code> used to execute the
+ * operation.
+ * @param source The absolute path of the source item act upon.
+ * @param dest The absolute path of the target item.
+ * @throws RepositoryException May be thrown if an error occurrs executing
+ * the operation.
+ */
protected abstract void execute(HtmlResponse response, Session session,
String source, String dest) throws RepositoryException;
Modified:
incubator/sling/trunk/servlets/post/src/main/java/org/apache/sling/servlets/post/impl/operations/CopyOperation.java
URL:
http://svn.apache.org/viewvc/incubator/sling/trunk/servlets/post/src/main/java/org/apache/sling/servlets/post/impl/operations/CopyOperation.java?rev=656351&r1=656350&r2=656351&view=diff
==============================================================================
---
incubator/sling/trunk/servlets/post/src/main/java/org/apache/sling/servlets/post/impl/operations/CopyOperation.java
(original)
+++
incubator/sling/trunk/servlets/post/src/main/java/org/apache/sling/servlets/post/impl/operations/CopyOperation.java
Wed May 14 11:28:57 2008
@@ -30,8 +30,9 @@
import org.slf4j.LoggerFactory;
/**
- * Holds various states and encapsulates methods that are needed to handle a
- * post request.
+ * The <code>CopyOperation</code> class implements the
+ * [EMAIL PROTECTED]
org.apache.sling.servlets.post.SlingPostConstants#OPERATION_COPY copy}
+ * operation for the Sling default POST servlet.
*/
public class CopyOperation extends AbstractCopyMoveOperation {
@@ -44,10 +45,10 @@
protected String getOperationName() {
return "copy";
}
-
+
@Override
- protected void execute(HtmlResponse response, Session session, String
source, String dest)
- throws RepositoryException {
+ protected void execute(HtmlResponse response, Session session,
+ String source, String dest) throws RepositoryException {
copyNode((Node) session.getItem(source),
(Node) session.getItem(ResourceUtil.getParent(dest)),
ResourceUtil.getName(dest));
Modified:
incubator/sling/trunk/servlets/post/src/main/java/org/apache/sling/servlets/post/impl/operations/DeleteOperation.java
URL:
http://svn.apache.org/viewvc/incubator/sling/trunk/servlets/post/src/main/java/org/apache/sling/servlets/post/impl/operations/DeleteOperation.java?rev=656351&r1=656350&r2=656351&view=diff
==============================================================================
---
incubator/sling/trunk/servlets/post/src/main/java/org/apache/sling/servlets/post/impl/operations/DeleteOperation.java
(original)
+++
incubator/sling/trunk/servlets/post/src/main/java/org/apache/sling/servlets/post/impl/operations/DeleteOperation.java
Wed May 14 11:28:57 2008
@@ -26,13 +26,14 @@
import org.apache.sling.servlets.post.AbstractSlingPostOperation;
/**
- * Holds various states and encapsulates methods that are needed to handle a
- * post request.
+ * The <code>DeleteOperation</code> class implements the
+ * [EMAIL PROTECTED]
org.apache.sling.servlets.post.SlingPostConstants#OPERATION_DELETE delete}
+ * operation for the Sling default POST servlet.
*/
public class DeleteOperation extends AbstractSlingPostOperation {
@Override
- public void doRun(SlingHttpServletRequest request, HtmlResponse response)
+ protected void doRun(SlingHttpServletRequest request, HtmlResponse
response)
throws RepositoryException {
Resource resource = request.getResource();
Modified:
incubator/sling/trunk/servlets/post/src/main/java/org/apache/sling/servlets/post/impl/operations/ModifyOperation.java
URL:
http://svn.apache.org/viewvc/incubator/sling/trunk/servlets/post/src/main/java/org/apache/sling/servlets/post/impl/operations/ModifyOperation.java?rev=656351&r1=656350&r2=656351&view=diff
==============================================================================
---
incubator/sling/trunk/servlets/post/src/main/java/org/apache/sling/servlets/post/impl/operations/ModifyOperation.java
(original)
+++
incubator/sling/trunk/servlets/post/src/main/java/org/apache/sling/servlets/post/impl/operations/ModifyOperation.java
Wed May 14 11:28:57 2008
@@ -42,6 +42,11 @@
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
+/**
+ * The <code>ModifyOperation</code> class implements the default operation
+ * called by the Sling default POST servlet if no operation is requested by the
+ * client. This operation is able to create and/or modify content.
+ */
public class ModifyOperation extends AbstractSlingPostOperation {
/** default log */
@@ -67,7 +72,7 @@
}
@Override
- public void doRun(SlingHttpServletRequest request, HtmlResponse response)
+ protected void doRun(SlingHttpServletRequest request, HtmlResponse
response)
throws RepositoryException {
Map<String, RequestProperty> reqProperties = collectContent(request,
Modified:
incubator/sling/trunk/servlets/post/src/main/java/org/apache/sling/servlets/post/impl/operations/MoveOperation.java
URL:
http://svn.apache.org/viewvc/incubator/sling/trunk/servlets/post/src/main/java/org/apache/sling/servlets/post/impl/operations/MoveOperation.java?rev=656351&r1=656350&r2=656351&view=diff
==============================================================================
---
incubator/sling/trunk/servlets/post/src/main/java/org/apache/sling/servlets/post/impl/operations/MoveOperation.java
(original)
+++
incubator/sling/trunk/servlets/post/src/main/java/org/apache/sling/servlets/post/impl/operations/MoveOperation.java
Wed May 14 11:28:57 2008
@@ -24,8 +24,9 @@
import org.slf4j.LoggerFactory;
/**
- * Holds various states and encapsulates methods that are needed to handle a
- * post request.
+ * The <code>MoveOperation</code> class implements the
+ * [EMAIL PROTECTED]
org.apache.sling.servlets.post.SlingPostConstants#OPERATION_MOVE move}
+ * operation for the Sling default POST servlet.
*/
public class MoveOperation extends AbstractCopyMoveOperation {
@@ -38,11 +39,11 @@
protected String getOperationName() {
return "move";
}
-
+
@Override
protected void execute(HtmlResponse response, Session session,
String source, String dest) throws RepositoryException {
-
+
session.move(source, dest);
response.onMoved(source, dest);
log.debug("moved {} to {}", source, dest);
