This is an automated email from the ASF dual-hosted git repository. joerghoh pushed a commit to branch bugfix/SLING-10442-fix-javadoc in repository https://gitbox.apache.org/repos/asf/sling-org-apache-sling-servlets-post.git
commit 40da86fc8c17068ccaacce96db533bc89fa5813a Author: Joerg Hoh <[email protected]> AuthorDate: Fri Jun 4 11:11:43 2021 +0200 fix javadoc warnings and errors --- .../sling/servlets/post/AbstractPostOperation.java | 23 ++++++++------- .../sling/servlets/post/AbstractPostResponse.java | 34 ++++++++++++---------- .../servlets/post/AbstractSlingPostOperation.java | 8 ++--- .../apache/sling/servlets/post/Modification.java | 6 ++++ .../apache/sling/servlets/post/PostOperation.java | 12 +++++--- .../apache/sling/servlets/post/PostResponse.java | 15 +++++++++- .../sling/servlets/post/SlingPostOperation.java | 2 +- .../sling/servlets/post/impl/helper/Chunk.java | 6 ++++ .../servlets/post/impl/helper/DateParser.java | 2 -- .../servlets/post/impl/helper/JCRSupport.java | 9 +++++- .../servlets/post/impl/helper/JCRSupportImpl.java | 27 ++++++++--------- .../servlets/post/impl/helper/ReferenceParser.java | 9 +++--- .../servlets/post/impl/helper/RequestProperty.java | 18 ++++++++---- .../post/impl/helper/SlingFileUploadHandler.java | 22 ++++++++------ .../impl/helper/SlingPropertyValueHandler.java | 7 +++-- .../servlets/post/impl/helper/StreamedChunk.java | 2 +- .../impl/operations/AbstractCopyMoveOperation.java | 6 ++-- .../impl/operations/AbstractCreateOperation.java | 12 ++++++++ .../post/impl/operations/DeleteOperation.java | 2 ++ 19 files changed, 144 insertions(+), 78 deletions(-) diff --git a/src/main/java/org/apache/sling/servlets/post/AbstractPostOperation.java b/src/main/java/org/apache/sling/servlets/post/AbstractPostOperation.java index ded1d04..e62e275 100644 --- a/src/main/java/org/apache/sling/servlets/post/AbstractPostOperation.java +++ b/src/main/java/org/apache/sling/servlets/post/AbstractPostOperation.java @@ -214,8 +214,9 @@ public abstract class AbstractPostOperation implements PostOperation { * representing the operations done. * @throws RepositoryException Maybe thrown if any error occurrs while * accessing the repository. - * @throws TemporaryPersistenceException - * @throws PreconditionViolatedPersistenceException + * @throws TemporaryPersistenceException if a retry could help + * @throws PreconditionViolatedPersistenceException if a retry doesn't make sense + * and some preconditions should be changed. */ protected abstract void doRun(SlingHttpServletRequest request, PostResponse response, @@ -255,7 +256,7 @@ public abstract class AbstractPostOperation implements PostOperation { * @param session The JCR session * @param request The http request * @return {@code true} if a save is required. - * @throws RepositoryException + * @throws RepositoryException a repository exception */ protected boolean isSessionSaveRequired(Session session, SlingHttpServletRequest request) throws RepositoryException { @@ -268,7 +269,7 @@ public abstract class AbstractPostOperation implements PostOperation { * @param path The path * @param session The JCR session * @return The path without the workspace - * @throws RepositoryException + * @throws RepositoryException a repository exception */ protected String removeAndValidateWorkspace(String path, Session session) throws RepositoryException { final int wsSepPos = path.indexOf(":/"); @@ -363,11 +364,11 @@ public abstract class AbstractPostOperation implements PostOperation { /** * Returns true if any of the request parameters starts with - * {@link SlingPostConstants#ITEM_PREFIX_RELATIVE_CURRENT <code>./</code>}. + * {@link SlingPostConstants#ITEM_PREFIX_RELATIVE_CURRENT ./}. * In this case only parameters starting with either of the prefixes - * {@link SlingPostConstants#ITEM_PREFIX_RELATIVE_CURRENT <code>./</code>}, - * {@link SlingPostConstants#ITEM_PREFIX_RELATIVE_PARENT <code>../</code>} - * and {@link SlingPostConstants#ITEM_PREFIX_ABSOLUTE <code>/</code>} are + * {@link SlingPostConstants#ITEM_PREFIX_RELATIVE_CURRENT ./}, + * {@link SlingPostConstants#ITEM_PREFIX_RELATIVE_PARENT ../} + * and {@link SlingPostConstants#ITEM_PREFIX_ABSOLUTE /} are * considered as providing content to be stored. Otherwise all parameters * not starting with the command prefix <code>:</code> are considered as * parameters to be stored. @@ -392,9 +393,9 @@ public abstract class AbstractPostOperation implements PostOperation { /** * Returns <code>true</code> if the <code>name</code> starts with either * of the prefixes - * {@link SlingPostConstants#ITEM_PREFIX_RELATIVE_CURRENT <code>./</code>}, - * {@link SlingPostConstants#ITEM_PREFIX_RELATIVE_PARENT <code>../</code>} - * and {@link SlingPostConstants#ITEM_PREFIX_ABSOLUTE <code>/</code>}. + * {@link SlingPostConstants#ITEM_PREFIX_RELATIVE_CURRENT ./}, + * {@link SlingPostConstants#ITEM_PREFIX_RELATIVE_PARENT ../} + * and {@link SlingPostConstants#ITEM_PREFIX_ABSOLUTE /}. * * @param name The name * @return {@code true} if the name has a prefix diff --git a/src/main/java/org/apache/sling/servlets/post/AbstractPostResponse.java b/src/main/java/org/apache/sling/servlets/post/AbstractPostResponse.java index 57e6336..f6b0dfa 100644 --- a/src/main/java/org/apache/sling/servlets/post/AbstractPostResponse.java +++ b/src/main/java/org/apache/sling/servlets/post/AbstractPostResponse.java @@ -82,41 +82,35 @@ public abstract class AbstractPostResponse implements PostResponse { // ---------- Settings for the response ------------------------------------ /** - * Returns the referer as from the 'referer' request header. + * {@inheritDoc} */ public String getReferer() { return getProperty(PN_REFERER, String.class); } /** - * Sets the referer property + * {@inheritDoc} */ public void setReferer(String referer) { setProperty(PN_REFERER, referer); } /** - * Returns the absolute path of the item upon which the request operated. - * <p> - * If the {@link #setPath(String)} method has not been called yet, this - * method returns <code>null</code>. + * {@inheritDoc} */ public String getPath() { return getProperty(PN_PATH, String.class); } /** - * Sets the absolute path of the item upon which the request operated. + * {@inheritDoc} */ public void setPath(String path) { setProperty(PN_PATH, path); } /** - * Returns <code>true</code> if this was a create request. - * <p> - * Before calling the {@link #setCreateRequest(boolean)} method, this method - * always returns <code>false</code>. + * {@inheritDoc} */ public boolean isCreateRequest() { final Boolean isCreateRequest = getProperty(PN_IS_CREATED, @@ -127,17 +121,14 @@ public abstract class AbstractPostResponse implements PostResponse { } /** - * Sets whether the request was a create request or not. + * {@inheritDoc} */ public void setCreateRequest(boolean isCreateRequest) { setProperty(PN_IS_CREATED, isCreateRequest); } /** - * Returns the location of the modification. this is the externalized form - * of the current path. - * - * @return the location of the modification. + * {@inheritDoc} */ public String getLocation() { return getProperty(PN_LOCATION, String.class); @@ -340,6 +331,11 @@ public abstract class AbstractPostResponse implements PostResponse { * Returns the generic response property with the given name and type or * <code>null</code> if no such property exists or the property is not of * the requested type. + * @param name the name of the requetested property + * @param type the type of the parameter which should be returned + * @param <Type> the return type + * @return the property as the requested type or null if not available at all or not + * in the requested type */ @SuppressWarnings("unchecked") protected <Type> Type getProperty(String name, Class<Type> type) { @@ -354,11 +350,17 @@ public abstract class AbstractPostResponse implements PostResponse { /** * Returns the generic response property with the given name and type or * <code>null</code> if no such property exists. + * @param name the name of the response property + * @return the requested property (might be null) */ protected Object getProperty(String name) { return properties.get(name); } + /** + * determines if the referer has a proper referer including protocol + * @return true if HTTP or HTTPS protocol information is available in the referer + */ protected boolean isSafeReferer(){ String referer = getReferer(); if (referer.startsWith("http://";) || referer.startsWith("https://";)) { diff --git a/src/main/java/org/apache/sling/servlets/post/AbstractSlingPostOperation.java b/src/main/java/org/apache/sling/servlets/post/AbstractSlingPostOperation.java index 28b55a8..69c1320 100644 --- a/src/main/java/org/apache/sling/servlets/post/AbstractSlingPostOperation.java +++ b/src/main/java/org/apache/sling/servlets/post/AbstractSlingPostOperation.java @@ -43,10 +43,10 @@ public abstract class AbstractSlingPostOperation extends AbstractPostOperation /** * - * @param request - * @param response - * @param changes - * @throws RepositoryException + * @param request the request + * @param response the response + * @param changes all changes + * @throws RepositoryException in case of problems */ protected abstract void doRun(SlingHttpServletRequest request, HtmlResponse response, List<Modification> changes) diff --git a/src/main/java/org/apache/sling/servlets/post/Modification.java b/src/main/java/org/apache/sling/servlets/post/Modification.java index 7c01471..5d2891b 100644 --- a/src/main/java/org/apache/sling/servlets/post/Modification.java +++ b/src/main/java/org/apache/sling/servlets/post/Modification.java @@ -49,6 +49,7 @@ public class Modification { * Records a 'modified' change * * @param path path of the item that was modified + * @return the modification */ public static Modification onModified(String path) { return onChange(ModificationType.MODIFY, path); @@ -58,6 +59,7 @@ public class Modification { * Records a 'created' change * * @param path path of the item that was created + * @return the modification */ public static Modification onCreated(String path) { return onChange(ModificationType.CREATE, path); @@ -67,6 +69,7 @@ public class Modification { * Records a 'deleted' change * * @param path path of the item that was deleted + * @return the modification */ public static Modification onDeleted(String path) { return onChange(ModificationType.DELETE, path); @@ -80,6 +83,7 @@ public class Modification { * * @param srcPath source path of the node that was moved * @param dstPath destination path of the node that was moved. + * @return the modification */ public static Modification onMoved(String srcPath, String dstPath) { return onChange(ModificationType.MOVE, srcPath, dstPath); @@ -93,6 +97,7 @@ public class Modification { * * @param srcPath source path of the node that was copied * @param dstPath destination path of the node that was copied. + * @return the modification */ public static Modification onCopied(String srcPath, String dstPath) { return onChange(ModificationType.COPY, srcPath, dstPath); @@ -104,6 +109,7 @@ public class Modification { * @param orderedPath Path of the node that was reordered * @param beforeSibling Name of the sibling node before which the source node has * been inserted. + * @return the modification */ public static Modification onOrder(String orderedPath, String beforeSibling) { return onChange(ModificationType.ORDER, orderedPath, beforeSibling); diff --git a/src/main/java/org/apache/sling/servlets/post/PostOperation.java b/src/main/java/org/apache/sling/servlets/post/PostOperation.java index 76a7131..e09811b 100644 --- a/src/main/java/org/apache/sling/servlets/post/PostOperation.java +++ b/src/main/java/org/apache/sling/servlets/post/PostOperation.java @@ -33,7 +33,7 @@ import org.apache.sling.servlets.post.exceptions.TemporaryPersistenceException; * {@link #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 {@link SlingPostConstants#RP_OPERATION - * <code>:operation</code>} request parameter. + * :operation} request parameter. * <p> * The Sling POST servlet itself provides various operations (see the * <code>OPERATION_</code> constants in the {@link SlingPostConstants} @@ -45,7 +45,7 @@ import org.apache.sling.servlets.post.exceptions.TemporaryPersistenceException; * interface as well as operation postprocessing. * <p> * Implementors of this interface are advised to extend the - * {@link AbstractPostOperation} class to benefit from various precossings + * {@link AbstractPostOperation} class to benefit from various processings * implemented by that abstract class. */ public interface PostOperation { @@ -75,14 +75,18 @@ public interface PostOperation { * @param processors The {@link SlingPostProcessor} services to be called * after applying the operation. This may be <code>null</code> if * there are none. - * @throws PersistenceException + * @throws PersistenceException when the commit fails * @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 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. + * Occurs running the operation. + * @throws PreconditionViolatedPersistenceException when a necessary precondition failed, + * and a retry without further changes doesn't make sense. + * @throws TemporaryPersistenceException when a commit failed, but a retry could make + * the operation work successfully. */ void run(SlingHttpServletRequest request, PostResponse response, SlingPostProcessor[] processors) throws PreconditionViolatedPersistenceException, TemporaryPersistenceException, PersistenceException; diff --git a/src/main/java/org/apache/sling/servlets/post/PostResponse.java b/src/main/java/org/apache/sling/servlets/post/PostResponse.java index 5c8d370..b4d0bcc 100644 --- a/src/main/java/org/apache/sling/servlets/post/PostResponse.java +++ b/src/main/java/org/apache/sling/servlets/post/PostResponse.java @@ -36,16 +36,19 @@ public interface PostResponse { /** * Sets the referer property + * @param referer the referer */ public void setReferer(String referer); /** * Returns the referer previously set by {@link #setReferer(String)} + * @return the referer */ public String getReferer(); /** * Sets the absolute path of the item upon which the request operated. + * @param path the path */ public void setPath(String path); @@ -54,11 +57,13 @@ public interface PostResponse { * <p> * If the {@link #setPath(String)} method has not been called yet, this * method returns <code>null</code>. + * @return the path (might be null) */ public String getPath(); /** * Sets whether the request was a create request or not. + * @param isCreateRequest true if the request was a create request */ public void setCreateRequest(boolean isCreateRequest); @@ -67,6 +72,7 @@ public interface PostResponse { * <p> * Before calling the {@link #setCreateRequest(boolean)} method, this method * always returns <code>false</code>. + * @return if this was a create request */ public boolean isCreateRequest(); @@ -74,7 +80,7 @@ public interface PostResponse { * Sets the location of this modification. This is the externalized form of * the {@link #getPath() current path}. * - * @param location + * @param location the location */ public void setLocation(String location); @@ -83,12 +89,14 @@ public interface PostResponse { * <p> * If the {@link #setLocation(String)} method has not been called yet, this * method returns <code>null</code>. + * @return the location */ public String getLocation(); /** * Sets the parent location of the modification. This is the externalized * form of the parent node of the {@link #getPath() current path}. + * @param parentLocation the parent location of the modification */ public void setParentLocation(String parentLocation); @@ -97,6 +105,7 @@ public interface PostResponse { * <p> * If the {@link #setParentLocation(String)} method has not been called yet, * this method returns <code>null</code>. + * @return the parent location */ public String getParentLocation(); @@ -122,17 +131,20 @@ public interface PostResponse { * an error, the response is assumed to be unsuccessful and 500 is returned. * If there is no error, the response is assumed to be successful and 200 is * returned. + * @return the status code */ public int getStatusCode(); /** * Returns the status message or <code>null</code> if no has been set with * the {@link #setStatus(int, String)} method. + * @return the status message (might be null) */ public String getStatusMessage(); /** * Sets the recorded error causing the operation to fail. + * @param error the throwable */ public void setError(Throwable error); @@ -146,6 +158,7 @@ public interface PostResponse { /** * Returns <code>true</code> if no {@link #getError() error} is set and if * the {@link #getStatusCode() status code} is one of the 2xx codes. + * @return true if the status code is 2xx */ public boolean isSuccessful(); diff --git a/src/main/java/org/apache/sling/servlets/post/SlingPostOperation.java b/src/main/java/org/apache/sling/servlets/post/SlingPostOperation.java index 3aa490b..cf681dd 100644 --- a/src/main/java/org/apache/sling/servlets/post/SlingPostOperation.java +++ b/src/main/java/org/apache/sling/servlets/post/SlingPostOperation.java @@ -33,7 +33,7 @@ import org.apache.sling.servlets.post.exceptions.TemporaryPersistenceException; * {@link #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 {@link SlingPostConstants#RP_OPERATION - * <code>:operation</code>} request parameter. + * :operation} 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 diff --git a/src/main/java/org/apache/sling/servlets/post/impl/helper/Chunk.java b/src/main/java/org/apache/sling/servlets/post/impl/helper/Chunk.java index b95e079..60b5d41 100644 --- a/src/main/java/org/apache/sling/servlets/post/impl/helper/Chunk.java +++ b/src/main/java/org/apache/sling/servlets/post/impl/helper/Chunk.java @@ -31,6 +31,7 @@ public class Chunk { /** * Return offset of the chunk. + * @return the offset */ public long getOffset() { return offset; @@ -38,6 +39,7 @@ public class Chunk { /** * Set offset value. + * @param offset the offset */ public void setOffsetValue(long offset) { this.offset = offset; @@ -45,6 +47,7 @@ public class Chunk { /** * Return length of the file parameter. + * @return the length */ public long getLength() { return length; @@ -52,6 +55,7 @@ public class Chunk { /** * Set length of file parameter. + * @param length the length */ public void setLength(long length) { this.length = length; @@ -61,6 +65,7 @@ public class Chunk { * Return true if request contains last chunk as a result upload should be * finished. It is useful in scenarios where file streaming where file size * is not known in advance. + * @return if the chunk is completed */ public boolean isCompleted() { return completed; @@ -68,6 +73,7 @@ public class Chunk { /** * Set complete flag + * @param complete the complete flag */ public void setCompleted(boolean complete) { this.completed = complete; diff --git a/src/main/java/org/apache/sling/servlets/post/impl/helper/DateParser.java b/src/main/java/org/apache/sling/servlets/post/impl/helper/DateParser.java index 2268b1c..d2cea2e 100644 --- a/src/main/java/org/apache/sling/servlets/post/impl/helper/DateParser.java +++ b/src/main/java/org/apache/sling/servlets/post/impl/helper/DateParser.java @@ -63,7 +63,6 @@ public class DateParser { /** * Parses the given source string and returns the respective calendar * instance. If no format matches returns <code>null</code>. - * <p/> * * @param source date time source string * @return calendar representation of the source or <code>null</code> @@ -90,7 +89,6 @@ public class DateParser { * Parses the given source strings and returns the respective calendar * instances. If no format matches for any of the sources * returns <code>null</code>. - * <p/> * * @param sources date time source strings * @return calendar representations of the source or <code>null</code> diff --git a/src/main/java/org/apache/sling/servlets/post/impl/helper/JCRSupport.java b/src/main/java/org/apache/sling/servlets/post/impl/helper/JCRSupport.java index c09cf04..ef0c5b6 100644 --- a/src/main/java/org/apache/sling/servlets/post/impl/helper/JCRSupport.java +++ b/src/main/java/org/apache/sling/servlets/post/impl/helper/JCRSupport.java @@ -151,8 +151,15 @@ public class JCRSupport { /** * Stores property value(s) as reference(s). Will parse the reference(s) from the string * value(s) in the {@link RequestProperty}. - * + * + * @param resource resource + * @param node the node + * @param name the name + * @param values the value + * @param type the type + * @param multiValued if multiValued * @return true only if parsing was successful and the property was actually changed + * @throws PersistenceException if the operation cannot be executed */ public Modification storeAsReference( final Resource resource, diff --git a/src/main/java/org/apache/sling/servlets/post/impl/helper/JCRSupportImpl.java b/src/main/java/org/apache/sling/servlets/post/impl/helper/JCRSupportImpl.java index 07179f2..7d0eb3d 100644 --- a/src/main/java/org/apache/sling/servlets/post/impl/helper/JCRSupportImpl.java +++ b/src/main/java/org/apache/sling/servlets/post/impl/helper/JCRSupportImpl.java @@ -69,11 +69,9 @@ public class JCRSupportImpl { * nodes | N | at a specific position, N being an integer </xmp> * * @param request The http request - * @param item node to order - * @param changes The list of modifications - * @throws RepositoryException if an error occurs - * @throws PreconditionViolatedPersistenceException - * @throws TemporaryPersistenceException + * @param resource the resource to order + * @param changes the list of modifications + * @throws PersistenceException in case the operation is not successful */ public void orderNode(final SlingHttpServletRequest request, final Resource resource, @@ -371,10 +369,7 @@ public class JCRSupportImpl { } /** - * Stores property value(s) as reference(s). Will parse the reference(s) from the string - * value(s) in the {@link RequestProperty}. - * - * @return A modification only if parsing was successful and the property was actually changed + * {@inheritDoc} */ public Modification storeAsReference( final Object n, @@ -483,10 +478,10 @@ public class JCRSupportImpl { * @param name The name of the newly created item. If this is * <code>null</code> the new item gets the same name as the * <code>src</code> item. + * @return the name of the newly created object * @throws PersistenceException May be thrown in case of any problem copying * the content. - * @throws PreconditionViolatedPersistenceException - * @throws TemporaryPersistenceException + * @throws PersistenceException in case something fails * @see #copy(Node, Node, String) * @see #copy(Property, Node, String) */ @@ -565,8 +560,14 @@ public class JCRSupportImpl { return dst; } - /** @return true if src is an ancestor node of dest, or if - * both are the same node */ + /** + * determines if the 2 nodes are in ancestor relationship or identical + * @param src one node + * @param dest the other node + * @return true if src is an ancestor node of dest, or if + * both are the same node + * @throws RepositoryException if something goes wrong + **/ public static boolean isAncestorOrSameNode(Node src, Node dest) throws RepositoryException { if(src.getPath().equals("/")) { return true; diff --git a/src/main/java/org/apache/sling/servlets/post/impl/helper/ReferenceParser.java b/src/main/java/org/apache/sling/servlets/post/impl/helper/ReferenceParser.java index aa0690c..635db53 100644 --- a/src/main/java/org/apache/sling/servlets/post/impl/helper/ReferenceParser.java +++ b/src/main/java/org/apache/sling/servlets/post/impl/helper/ReferenceParser.java @@ -31,12 +31,12 @@ public class ReferenceParser { /** * Parses the given source string and returns the correct Value object. * If no node matches returns <code>null</code>. - * <p/> * + * @param session the session * @param value a path or UUID * @param weak true to create a WeakReference value * @return the value or <code>null</code> - * @throws RepositoryException + * @throws RepositoryException in case of problems */ public static Value parse(Session session, String value, boolean weak) throws RepositoryException { Node n = parse(session, value); @@ -50,13 +50,12 @@ public class ReferenceParser { * Parses the given source strings and returns the respective reference value * instances. If no node matches for any of the sources * returns <code>null</code>. - * <p/> * + * @param session the session * @param values path or UUID strings - * @param factory the value factory * @param weak true to create a WeakReference value * @return the values or <code>null</code> - * @throws RepositoryException + * @throws RepositoryException in case of problems */ public static Value[] parse(Session session, String[] values, boolean weak) throws RepositoryException { Value ret[] = new Value[values.length]; diff --git a/src/main/java/org/apache/sling/servlets/post/impl/helper/RequestProperty.java b/src/main/java/org/apache/sling/servlets/post/impl/helper/RequestProperty.java index a8b2d13..4aaccf9 100644 --- a/src/main/java/org/apache/sling/servlets/post/impl/helper/RequestProperty.java +++ b/src/main/java/org/apache/sling/servlets/post/impl/helper/RequestProperty.java @@ -221,7 +221,8 @@ public class RequestProperty { } /** - * Returns <code>true</code> if the repository item described by this is + * Determine the deletion status of this item + * @return <code>true</code> if the repository item described by this is * to be deleted before setting new content to it. */ public boolean isDelete() { @@ -251,7 +252,8 @@ public class RequestProperty { } /** - * Returns <code>true</code> if the content of this property is to be set + * If this is a target of a move operation + * @return <code>true</code> if the content of this property is to be set * by moving content from another repository item. * * @see #getRepositorySource() @@ -261,7 +263,8 @@ public class RequestProperty { } /** - * Returns <code>true</code> if the content of this property is to be set + * if this is the source of a copy action + * @return <code>true</code> if the content of this property is to be set * by copying content from another repository item. * * @see #getRepositorySource() @@ -271,7 +274,8 @@ public class RequestProperty { } /** - * Returns the absolute path of the repository item from which the content + * get the source of a copy or move operation + * @return the absolute path of the repository item from which the content * for this property is to be copied or moved. * * @see #hasRepositoryCopySource() @@ -295,7 +299,8 @@ public class RequestProperty { } /** - * Returns whether this property is to be handled as a multi-value property + * determines if this property is handled as multi-value property + * @return whether this property is to be handled as a multi-value property * seen as set. */ public boolean isPatch() { @@ -303,7 +308,8 @@ public class RequestProperty { } /** - * Return true if request is chunk upload. + * it this is a chunk upload? + * @return true if request is chunk upload. */ public boolean isChunkUpload() { return chunk != null; diff --git a/src/main/java/org/apache/sling/servlets/post/impl/helper/SlingFileUploadHandler.java b/src/main/java/org/apache/sling/servlets/post/impl/helper/SlingFileUploadHandler.java index 470b580..d1ee4ff 100644 --- a/src/main/java/org/apache/sling/servlets/post/impl/helper/SlingFileUploadHandler.java +++ b/src/main/java/org/apache/sling/servlets/post/impl/helper/SlingFileUploadHandler.java @@ -53,37 +53,38 @@ import org.slf4j.LoggerFactory; /** * Handles file uploads. - * <p/> + * <p> * * Simple example: - * <xmp> + * + * {@code * <form action="/home/admin" method="POST" enctype="multipart/form-data"> * <input type="file" name="./portrait" /> * </form> - * </xmp> + * } * * this will create a nt:file node below "/home/admin" if the node type of * "admin" is (derived from) nt:folder, a nt:resource node otherwise. - * <p/> + * <p> * * Filename example: - * <xmp> + * {@code * <form action="/home/admin" method="POST" enctype="multipart/form-data"> * <input type="file" name="./*" /> * </form> - * </xmp> + * } * * same as above, but uses the filename of the uploaded file as name for the * new node. - * <p/> + * <p> * * Type hint example: - * <xmp> + * {@code * <form action="/home/admin" method="POST" enctype="multipart/form-data"> * <input type="file" name="./portrait" /> * <input type="hidden" name="./portrait@TypeHint" value="my:file" /> * </form> - * </xmp> + * } * * this will create a new node with the type my:file below admin. if the hinted * type extends from nt:file an intermediate file node is created otherwise @@ -417,6 +418,8 @@ public class SlingFileUploadHandler { /** * Delete all chunks saved within a resource. If no chunks exist, it is no-op. + * @param rsrc the resource + * @throws PersistenceException in case of problems */ public void deleteChunks(final Resource rsrc) throws PersistenceException { final Resource chunkParent = getChunkParent(rsrc); @@ -511,6 +514,7 @@ public class SlingFileUploadHandler { * * @param parent the parent node * @param prop the assembled property info + * @param changes the changes * @throws PersistenceException if an error occurs */ public void setFile(final Resource parent, final RequestProperty prop, final List<Modification> changes) diff --git a/src/main/java/org/apache/sling/servlets/post/impl/helper/SlingPropertyValueHandler.java b/src/main/java/org/apache/sling/servlets/post/impl/helper/SlingPropertyValueHandler.java index 50abeb8..0ac27d9 100644 --- a/src/main/java/org/apache/sling/servlets/post/impl/helper/SlingPropertyValueHandler.java +++ b/src/main/java/org/apache/sling/servlets/post/impl/helper/SlingPropertyValueHandler.java @@ -73,6 +73,9 @@ public class SlingPropertyValueHandler { /** * Constructs a property value handler + * @param dateParser the dateParser + * @param jcrSupport the jcrSupport + * @param changes the changes */ public SlingPropertyValueHandler(final DateParser dateParser, final JCRSupport jcrSupport, @@ -94,12 +97,12 @@ public class SlingPropertyValueHandler { * the field name but no value. * * html example for testing: - * <xmp> + * {@code * <input type="hidden" name="created"/> * <input type="hidden" name="lastModified"/> * <input type="hidden" name="createdBy" /> * <input type="hidden" name="lastModifiedBy"/> - * </xmp> + * } * * @param parent the parent node * @param prop the request property diff --git a/src/main/java/org/apache/sling/servlets/post/impl/helper/StreamedChunk.java b/src/main/java/org/apache/sling/servlets/post/impl/helper/StreamedChunk.java index 1283acb..1129040 100644 --- a/src/main/java/org/apache/sling/servlets/post/impl/helper/StreamedChunk.java +++ b/src/main/java/org/apache/sling/servlets/post/impl/helper/StreamedChunk.java @@ -141,7 +141,7 @@ public class StreamedChunk { * @param fileResource the file request. * @param changes changes that were made. * @return the jcr:content sub node. - * @throws PersistenceException + * @throws PersistenceException in case of persistence issues */ public Resource store(Resource fileResource, List<Modification> changes) throws PersistenceException { Resource result = fileResource.getChild(JcrConstants.JCR_CONTENT); diff --git a/src/main/java/org/apache/sling/servlets/post/impl/operations/AbstractCopyMoveOperation.java b/src/main/java/org/apache/sling/servlets/post/impl/operations/AbstractCopyMoveOperation.java index f6574b0..e650508 100644 --- a/src/main/java/org/apache/sling/servlets/post/impl/operations/AbstractCopyMoveOperation.java +++ b/src/main/java/org/apache/sling/servlets/post/impl/operations/AbstractCopyMoveOperation.java @@ -140,19 +140,21 @@ abstract class AbstractCopyMoveOperation extends AbstractPostOperation { /** * Returns a short name to be used in log and status messages. + * @return the name of the operation */ protected abstract String getOperationName(); /** * Actually executes the operation. * - * @param response The <code>HtmlResponse</code> used to record success of - * the operation. + * @param changes the changes to execute * @param source The source item to act upon. * @param destParent The absolute path of the parent of the target item. * @param destName The name of the target item inside the * <code>destParent</code>. If <code>null</code> the name of * the <code>source</code> is used as the target item name. + * @param versioningConfiguration the configuration for versioning + * @return the resource which results of this operation * @throws PersistenceException May be thrown if an error occurs executing * the operation. */ diff --git a/src/main/java/org/apache/sling/servlets/post/impl/operations/AbstractCreateOperation.java b/src/main/java/org/apache/sling/servlets/post/impl/operations/AbstractCreateOperation.java index 036de5b..851c743 100644 --- a/src/main/java/org/apache/sling/servlets/post/impl/operations/AbstractCreateOperation.java +++ b/src/main/java/org/apache/sling/servlets/post/impl/operations/AbstractCreateOperation.java @@ -130,6 +130,11 @@ abstract class AbstractCreateOperation extends AbstractPostOperation { /** * Create resource(s) according to current request * + * @param resolver the resourceResolver to use + * @param reqProperties required properties + * @param response the response + * @param changes the changes to apply + * @param versioningConfiguration versioning configuration * @throws PersistenceException if a resource error occurs */ protected void processCreate(final ResourceResolver resolver, @@ -216,6 +221,9 @@ abstract class AbstractCreateOperation extends AbstractPostOperation { /** * Collects the properties that form the content to be written back to the * resource tree. + * @param request the request + * @param response the response + * @return the collected properties */ protected Map<String, RequestProperty> collectContent( final SlingHttpServletRequest request, @@ -512,7 +520,11 @@ abstract class AbstractCreateOperation extends AbstractPostOperation { * Deep gets or creates a resource, parent-padding with default resources. If * the path is empty, the given parent resource is returned. * + * @param resolver the resource resolver to use * @param path path to resources that needs to be deep-created + * @param reqProperties the properties to add + * @param changes the changes to apply + * @param versioningConfiguration the versioning configuration * @return Resource at path * @throws PersistenceException if an error occurs * @throws IllegalArgumentException if the path is relative and parent is diff --git a/src/main/java/org/apache/sling/servlets/post/impl/operations/DeleteOperation.java b/src/main/java/org/apache/sling/servlets/post/impl/operations/DeleteOperation.java index 78c9847..37f5dc6 100644 --- a/src/main/java/org/apache/sling/servlets/post/impl/operations/DeleteOperation.java +++ b/src/main/java/org/apache/sling/servlets/post/impl/operations/DeleteOperation.java @@ -106,6 +106,8 @@ public class DeleteOperation extends AbstractPostOperation { /** * Return true if request is to delete chunks. To return true, request will * should parameter ":applyToChunks" and it should be true. + * @param request the request + * @return is the request is to delete chunks */ protected boolean isDeleteChunkRequest(SlingHttpServletRequest request) {
