This is an automated email from the ASF dual-hosted git repository. rombert pushed a commit to annotated tag org.apache.sling.pipes-0.0.10 in repository https://gitbox.apache.org/repos/asf/sling-org-apache-sling-pipes.git
commit c1911c4c2b31bdcec5ed2aac013c225fa750eb79 Author: Oliver Lietz <[email protected]> AuthorDate: Mon Oct 10 07:23:33 2016 +0000 SLING-6122 Sling Pipes javadoc fails patch from Nicolas Peltier git-svn-id: https://svn.apache.org/repos/asf/sling/trunk/contrib/extensions/sling-pipes@1764022 13f79535-47bb-0310-9956-ffa450edef68 --- src/main/java/org/apache/sling/pipes/BasePipe.java | 28 +++++++--- .../java/org/apache/sling/pipes/ContainerPipe.java | 26 +++++++--- .../java/org/apache/sling/pipes/OutputWriter.java | 22 +++++--- src/main/java/org/apache/sling/pipes/Pipe.java | 27 +++++----- .../java/org/apache/sling/pipes/PipeBindings.java | 59 ++++++++++++++-------- src/main/java/org/apache/sling/pipes/Plumber.java | 20 ++++---- .../sling/pipes/internal/AuthorizablePipe.java | 16 +++--- .../org/apache/sling/pipes/internal/JsonPipe.java | 7 +-- .../org/apache/sling/pipes/internal/WritePipe.java | 28 ++++++---- 9 files changed, 155 insertions(+), 78 deletions(-) diff --git a/src/main/java/org/apache/sling/pipes/BasePipe.java b/src/main/java/org/apache/sling/pipes/BasePipe.java index 6c26789..afaad61 100644 --- a/src/main/java/org/apache/sling/pipes/BasePipe.java +++ b/src/main/java/org/apache/sling/pipes/BasePipe.java @@ -29,7 +29,7 @@ import org.slf4j.Logger; import org.slf4j.LoggerFactory; /** - * provides generic utilities for a pipe + * provides generic utilities for a pipe, is also a dummy pipe (outputs its input, without changing anything) */ public class BasePipe implements Pipe { @@ -67,6 +67,12 @@ public class BasePipe implements Pipe { private String name; + /** + * Pipe Constructor + * @param plumber plumber + * @param resource configuration resource + * @throws Exception in case configuration is not working + */ public BasePipe(Plumber plumber, Resource resource) throws Exception { this.resource = resource; properties = resource.adaptTo(ValueMap.class); @@ -77,6 +83,7 @@ public class BasePipe implements Pipe { bindings = new PipeBindings(resource); } + @Override public boolean isDryRun() { if (dryRunObject == null) { Object run = bindings.isBindingDefined(DRYRUN_KEY) ? bindings.instantiateObject(DRYRUN_EXPR) : false; @@ -86,6 +93,7 @@ public class BasePipe implements Pipe { return dryRun; } + @Override public String toString() { return name + " " + "(path: " + resource.getPath() + ", dryRun: " + isDryRun() + ", modifiesContent: " + modifiesContent() + ")"; } @@ -95,13 +103,14 @@ public class BasePipe implements Pipe { return false; } + @Override public String getName(){ return name; } /** * Get pipe's expression, instanciated or not - * @return + * @return configured expression */ public String getExpr(){ String rawExpression = properties.get(PN_EXPR, ""); @@ -110,7 +119,7 @@ public class BasePipe implements Pipe { /** * Get pipe's path, instanciated or not - * @return + * @return configured path (can be empty) */ public String getPath() { String rawPath = properties.get(PN_PATH, ""); @@ -130,8 +139,12 @@ public class BasePipe implements Pipe { return configuredInput; } + /** + * Retrieves previous pipe if contained by a parent, or referrer's + * @return pipe before this one or the referrer's can be null in case there is no parent + */ protected Pipe getPreviousPipe(){ - return referrer == null ? parent.getPreviousPipe(this) : referrer.getPreviousPipe(); + return referrer == null ? (parent != null ? parent.getPreviousPipe(this) : null) : referrer.getPreviousPipe(); } @Override @@ -170,7 +183,7 @@ public class BasePipe implements Pipe { /** * default execution, just returns current resource - * @return + * @return output of this pipe, which is here the input resource */ public Iterator<Resource> getOutput(){ Resource resource = getInput(); @@ -182,7 +195,7 @@ public class BasePipe implements Pipe { /** * Get configuration node - * @return + * @return configuration node if any */ public Resource getConfiguration() { return resource.getChild(NN_CONF); @@ -198,5 +211,8 @@ public class BasePipe implements Pipe { referrer = pipe; } + /** + * Empty resource iterator + */ public static final Iterator<Resource> EMPTY_ITERATOR = Collections.emptyIterator(); } diff --git a/src/main/java/org/apache/sling/pipes/ContainerPipe.java b/src/main/java/org/apache/sling/pipes/ContainerPipe.java index 64aa072..051abc6 100644 --- a/src/main/java/org/apache/sling/pipes/ContainerPipe.java +++ b/src/main/java/org/apache/sling/pipes/ContainerPipe.java @@ -42,6 +42,12 @@ public class ContainerPipe extends BasePipe { List<Pipe> reversePipeList = new ArrayList<>(); + /** + * Constructor + * @param plumber plumber + * @param resource container's configuration resource + * @throws Exception bad configuration handling + */ public ContainerPipe(Plumber plumber, Resource resource) throws Exception{ super(plumber, resource); for (Iterator<Resource> childPipeResources = getConfiguration().listChildren(); childPipeResources.hasNext();){ @@ -77,8 +83,8 @@ public class ContainerPipe extends BasePipe { /** * Returns the pipe immediately before the given pipe, null if it's the first - * @param pipe - * @return + * @param pipe given pipe + * @return previous pipe of the param */ public Pipe getPreviousPipe(Pipe pipe){ Pipe previousPipe = null; @@ -93,7 +99,7 @@ public class ContainerPipe extends BasePipe { /** * Return the first pipe in the container - * @return + * @return first pipe of the container */ public Pipe getFirstPipe() { return pipeList.iterator().next(); @@ -101,13 +107,17 @@ public class ContainerPipe extends BasePipe { /** * Return the last pipe in the container - * @return + * @return pipe in the last position of the container's pipes */ public Pipe getLastPipe() { return reversePipeList.iterator().next(); } - public Resource getOuputResource() { + /** + * output resource of the container pipe + * @return output resource of the last pipe of the container + */ + public Resource getOutputResource() { return bindings.getExecutedResource(getLastPipe().getName()); } @@ -132,6 +142,10 @@ public class ContainerPipe extends BasePipe { boolean hasNext = false; int cursor = 0; + /** + * Constructor + * @param containerPipe corresponding container pipe + */ ContainerResourceIterator(ContainerPipe containerPipe) { container = containerPipe; bindings = container.bindings; @@ -144,7 +158,7 @@ public class ContainerPipe extends BasePipe { /** * go up and down the container iterators until cursor is at 0 (first pipe) with no * more resources, or at length - 1 (last pipe) with a next one - * @return + * @return true if cursor has been updated */ private boolean updateCursor(){ Pipe currentPipe = container.pipeList.get(cursor); diff --git a/src/main/java/org/apache/sling/pipes/OutputWriter.java b/src/main/java/org/apache/sling/pipes/OutputWriter.java index fe0dabd..3825b2a 100644 --- a/src/main/java/org/apache/sling/pipes/OutputWriter.java +++ b/src/main/java/org/apache/sling/pipes/OutputWriter.java @@ -34,25 +34,33 @@ public interface OutputWriter { /** * - * @param request - * @return + * @param request current request + * @return true if this writer handles that request */ boolean handleRequest(SlingHttpServletRequest request); /** - * Init the writer - * @param response + * Init the writer, writes beginning of the output + * @param request request from which writer will output + * @param response response on which writer will output + * @param pipe pipe whose output will be written + * @throws IOException error handling streams + * @throws JSONException in case invalid json is written */ void init(SlingHttpServletRequest request, SlingHttpServletResponse response, Pipe pipe) throws IOException, JSONException; /** * Write a given resource - * @param resource + * @param resource resource that will be written + * @throws JSONException in case write fails */ void writeItem(Resource resource) throws JSONException; /** - * ends write + * writes the end of the output + * @param size size of the overall result + * @throws JSONException in case invalid json is written */ + void ends(int size) throws JSONException; -} \ No newline at end of file +} diff --git a/src/main/java/org/apache/sling/pipes/Pipe.java b/src/main/java/org/apache/sling/pipes/Pipe.java index bc97e94..30ceace 100644 --- a/src/main/java/org/apache/sling/pipes/Pipe.java +++ b/src/main/java/org/apache/sling/pipes/Pipe.java @@ -48,77 +48,80 @@ public interface Pipe { /** * returns true if that pipe will modify content during its execution - * @return + * @return true for write / false for read */ boolean modifiesContent(); /** * returns true if that pipe is set not to write content - * @return + * @return true if dry run, false otherwise */ boolean isDryRun(); /** * Return the name of that pipe - * @return + * @return name of the pipe */ String getName(); /** - * Set parent + * set the pipe parent + * @param parent container pipe */ void setParent(ContainerPipe parent); /** * Return parent's pipe (can be null) - * @return + * @return pipe's container parent */ ContainerPipe getParent(); /** * Get the pipe's optional configured resource or null - * @return + * @return input if configured */ Resource getConfiguredInput(); /** * Get pipe current's resource *before* next execution, meaning either the * configured resource, either previous' pipe output resource - * @return + * @return input, configured or previous pipe */ Resource getInput(); /** * returns the binding output used in container pipe's expression - * @return + * @return object, either value map or something else, that will be used in nashorn for computing expressions */ Object getOutputBinding(); /** * returns the pipe's bindings - * @return + * @return PipeBindings instance containing all bindings of that pipe */ PipeBindings getBindings(); /** * set the pipe's bindings + * @param bindings bindings to set */ void setBindings(PipeBindings bindings); /** * Executes the pipe, can be contained in a parent or not - * @return + * @return iterator of resource resulting from execution of this pipe */ Iterator<Resource> getOutput(); /** * Get Distribution agent + * @return configured distribution agent */ String getDistributionAgent(); /** * sets the reference pipe this pipe is referred by - * @param pipe + * @param pipe referrer that refers to this instance */ void setReferrer(ReferencePipe pipe); -} \ No newline at end of file +} diff --git a/src/main/java/org/apache/sling/pipes/PipeBindings.java b/src/main/java/org/apache/sling/pipes/PipeBindings.java index 4925b83..a898e72 100644 --- a/src/main/java/org/apache/sling/pipes/PipeBindings.java +++ b/src/main/java/org/apache/sling/pipes/PipeBindings.java @@ -41,7 +41,7 @@ import java.util.regex.Matcher; import java.util.regex.Pattern; /** - * Execution bindings of a pipe + * Execution bindings of a pipe, and all expression related */ public class PipeBindings { private static final Logger log = LoggerFactory.getLogger(PipeBindings.class); @@ -63,7 +63,8 @@ public class PipeBindings { private static final Pattern INJECTED_SCRIPT = Pattern.compile("\\$\\{(([^\\{^\\}]*(\\{[0-9,]+\\})?)*)\\}"); /** - * public constructor + * public constructor, built from pipe's resource + * @param resource pipe's configuration resource */ public PipeBindings(Resource resource){ engine.setContext(scriptContext); @@ -93,8 +94,8 @@ public class PipeBindings { /** * add a script file to the engine - * @param resolver - * @param path + * @param resolver resolver with which the file should be read + * @param path path of the script file */ public void addScript(ResourceResolver resolver, String path) { InputStream is = null; @@ -126,21 +127,25 @@ public class PipeBindings { /** * adds additional bindings (global variables to use in child pipes expressions) - * @param bindings + * @param bindings key/values bindings to add to the existing bindings */ public void addBindings(Map bindings) { log.info("Adding bindings {}", bindings); getBindings().putAll(bindings); } + /** + * copy bindings + * @param original original bindings to copy + */ public void copyBindings(PipeBindings original){ getBindings().putAll(original.getBindings()); } /** * Update current resource of a given pipe, and appropriate binding - * @param pipe - * @param resource + * @param pipe pipe we'll extract the output binding from + * @param resource current resource in the pipe execution */ public void updateBindings(Pipe pipe, Resource resource) { outputResources.put(pipe.getName(), resource); @@ -150,23 +155,37 @@ public class PipeBindings { addBinding(pipe.getName(), pipe.getOutputBinding()); } + /** + * add a binding + * @param name binding's name + * @param value binding's value + */ public void addBinding(String name, Object value){ log.debug("Adding binding {}={}", name, value); getBindings().put(name, value); } + /** + * check if a given bindings is defined or not + * @param name name of the binding + * @return true if <code>name</code> is registered + */ public boolean isBindingDefined(String name){ return getBindings().containsKey(name); } + /** + * return registered bindings + * @return bindings + */ public Bindings getBindings() { return scriptContext.getBindings(ScriptContext.ENGINE_SCOPE); } /** * Doesn't look like nashorn likes template strings :-( - * @param expr - * @return + * @param expr ECMA like expression <code>blah${'some' + 'ecma' + 'expression'}</code> + * @return computed expression */ protected String computeECMA5Expression(String expr){ Matcher matcher = INJECTED_SCRIPT.matcher(expr); @@ -198,10 +217,10 @@ public class PipeBindings { } /** - * - * @param expr - * @return - * @throws ScriptException + * evaluate a given expression + * @param expr ecma like expression + * @return object that is the result of the expression + * @throws ScriptException in case the script fails, an exception is thrown (to let call code the opportunity to stop the execution) */ protected Object evaluate(String expr) throws ScriptException { String computed = computeECMA5Expression(expr); @@ -215,8 +234,8 @@ public class PipeBindings { /** * Expression is a function of variables from execution context, that * we implement here as a String - * @param expr - * @return + * @param expr ecma like expression + * @return String that is the result of the expression */ public String instantiateExpression(String expr){ try { @@ -229,8 +248,8 @@ public class PipeBindings { /** * Instantiate object from expression - * @param expr - * @return + * @param expr ecma expression + * @return instantiated object */ public Object instantiateObject(String expr){ try { @@ -254,9 +273,9 @@ public class PipeBindings { } /** - * - * @param name - * @return + * return Pipe <code>name</code>'s output binding + * @param name name of the pipe + * @return resource corresponding to that pipe output */ public Resource getExecutedResource(String name) { return outputResources.get(name); diff --git a/src/main/java/org/apache/sling/pipes/Plumber.java b/src/main/java/org/apache/sling/pipes/Plumber.java index 5438164..12ec4eb 100644 --- a/src/main/java/org/apache/sling/pipes/Plumber.java +++ b/src/main/java/org/apache/sling/pipes/Plumber.java @@ -32,8 +32,8 @@ public interface Plumber { /** * Instantiate a pipe from the given resource and returns it - * @param resource - * @return + * @param resource configuration resource + * @return pipe instantiated from the resource, null otherwise */ Pipe getPipe(Resource resource); @@ -43,8 +43,8 @@ public interface Plumber { * @param path path of a valid pipe configuration * @param bindings bindings to add to the execution of the pipe, can be null * @param save in case that pipe writes anything, wether the plumber should save changes or not - * - * @return + * @throws Exception in case execution fails + * @return set of paths of output resources */ Set<String> execute(ResourceResolver resolver, String path, Map bindings, boolean save) throws Exception; @@ -54,23 +54,25 @@ public interface Plumber { * @param pipe pipe to execute * @param bindings bindings to add to the execution of the pipe, can be null * @param save in case that pipe writes anything, wether the plumber should save changes or not - * - * @return + * @throws Exception in case execution fails + * @return set of paths of output resources */ Set<String> execute(ResourceResolver resolver, Pipe pipe, Map bindings, boolean save) throws Exception; /** * Persist some pipe changes, and eventually distribute changes - * @param resolver + * @param resolver resolver with which changes will be persisted * @param pipe pipe from which the change occurred * @param paths set of changed paths + * @throws PersistenceException in case persisting fails */ + void persist(ResourceResolver resolver, Pipe pipe, Set<String> paths) throws PersistenceException; /** * Registers - * @param type - * @param pipeClass + * @param type resource type of the pipe to register + * @param pipeClass class of the pipe to register */ void registerPipe(String type, Class<? extends BasePipe> pipeClass); diff --git a/src/main/java/org/apache/sling/pipes/internal/AuthorizablePipe.java b/src/main/java/org/apache/sling/pipes/internal/AuthorizablePipe.java index 2f06b65..20c2ad6 100644 --- a/src/main/java/org/apache/sling/pipes/internal/AuthorizablePipe.java +++ b/src/main/java/org/apache/sling/pipes/internal/AuthorizablePipe.java @@ -29,7 +29,6 @@ import org.apache.sling.pipes.Plumber; import org.slf4j.Logger; import org.slf4j.LoggerFactory; -import javax.jcr.RepositoryException; import java.util.Collections; import java.util.Iterator; @@ -65,6 +64,12 @@ public class AuthorizablePipe extends BasePipe { return autoCreateGroup || StringUtils.isNotBlank(addToGroup) || StringUtils.isNotBlank(addMembers); } + /** + * public constructor + * @param plumber plumber instance + * @param resource configuration resource + * @throws Exception bad configuration handling + */ public AuthorizablePipe(Plumber plumber, Resource resource) throws Exception { super(plumber, resource); resolver = resource.getResourceResolver(); @@ -105,8 +110,7 @@ public class AuthorizablePipe extends BasePipe { * Returns the authorizable configured by its expression, creating it if * not present and if <code>autoCreateGroup</code> is set to true, or, if * no expression, tries to resolve getInput() as an authorizable - * @return - * @throws RepositoryException + * @return corresponding authorizable */ protected Authorizable getAuthorizable() { Authorizable auth = null; @@ -133,7 +137,7 @@ public class AuthorizablePipe extends BasePipe { /** * Add current authorizable to configured addToGroup expression (should resolve as a group id) - * @param auth + * @param auth authorizable to add to the group */ protected void addToGroup(Authorizable auth){ try { @@ -154,7 +158,7 @@ public class AuthorizablePipe extends BasePipe { /** * Add to current authorizable (that should be a group) the configured members in addMembers expression - * @param auth + * @param auth group to which members should be added */ protected void addMembers(Authorizable auth) { try { @@ -184,7 +188,7 @@ public class AuthorizablePipe extends BasePipe { /** * add current group's members to the bindings - * @param auth + * @param auth group whose members should be bound in the pipe bindings */ protected void bindMembers(Authorizable auth){ try { diff --git a/src/main/java/org/apache/sling/pipes/internal/JsonPipe.java b/src/main/java/org/apache/sling/pipes/internal/JsonPipe.java index 2411651..5be05d2 100644 --- a/src/main/java/org/apache/sling/pipes/internal/JsonPipe.java +++ b/src/main/java/org/apache/sling/pipes/internal/JsonPipe.java @@ -76,8 +76,8 @@ public class JsonPipe extends BasePipe { } /** - * Retrieve remote JSON String, or null if any problem occurs - * @return + * Retrieve remote / expression JSON String, or null if any problem occurs + * @return JSON serialization of the result */ private String retrieveJSONString() { String json = null; @@ -119,7 +119,8 @@ public class JsonPipe extends BasePipe { /** * in case there is no successful retrieval of some JSON data, we cut the pipe here - * @return + * @return input resource of the pipe, can be reouputed N times in case output json binding is an array of + * N element (output binding would be here each time the Nth element of the array) */ public Iterator<Resource> getOutput() { Iterator<Resource> output = EMPTY_ITERATOR; diff --git a/src/main/java/org/apache/sling/pipes/internal/WritePipe.java b/src/main/java/org/apache/sling/pipes/internal/WritePipe.java index 06f395c..a03f3ba 100644 --- a/src/main/java/org/apache/sling/pipes/internal/WritePipe.java +++ b/src/main/java/org/apache/sling/pipes/internal/WritePipe.java @@ -49,6 +49,12 @@ public class WritePipe extends BasePipe { Pattern addPatch = Pattern.compile("\\+\\[(.*)\\]"); Pattern multi = Pattern.compile("\\[(.*)\\]"); + /** + * public constructor + * @param plumber plumber instance + * @param resource configuration resource + * @throws Exception bad configuration handling + */ public WritePipe(Plumber plumber, Resource resource) throws Exception { super(plumber, resource); if (getConfiguration() == null){ @@ -59,9 +65,13 @@ public class WritePipe extends BasePipe { } /** - * convert the configured value in an actual one - * @param expression - * @return + * convert the configured value (can be an expression) in a value that can be written in a resource. + * also handles patch for multivalue properties like <code>+[value]</code> in which case <code>value</code> + * is added to the MV property + * @param resource resource to which value will be written + * @param key property to which value will be written + * @param expression configured value to write + * @return actual value to write to the resource */ protected Object computeValue(Resource resource, String key, Object expression) { if (expression instanceof String) { @@ -98,9 +108,9 @@ public class WritePipe extends BasePipe { * Write properties from the configuration to the target resource, * instantiating both property names & values * - * @param conf - * @param target - * @throws RepositoryException + * @param conf configured resource that holds all properties to write (and children) + * @param target target resource on which configured values will be written + * @throws RepositoryException issues occuring when traversing nodes */ private void copyProperties(Resource conf, Resource target) throws RepositoryException { ValueMap writeMap = conf.adaptTo(ValueMap.class); @@ -129,7 +139,7 @@ public class WritePipe extends BasePipe { /** * we store all property to remove for very last moment (in order to potentially reuse their value) - * @param property + * @param property property resource that should be removed */ private void addPropertyToRemove(Resource property){ if (property != null) { @@ -142,8 +152,8 @@ public class WritePipe extends BasePipe { /** * write the configured tree at the target resource, creating each node if needed, copying values. - * @param conf - * @return + * @param conf configuration JCR tree to write to target resource + * @param target target resource to write */ private void writeTree(Node conf, Resource target) throws RepositoryException { copyProperties(resolver.getResource(conf.getPath()), target); -- To stop receiving notification emails like this one, please contact "[email protected]" <[email protected]>.
