This is an automated email from the ASF dual-hosted git repository.
rombert pushed a commit to annotated tag org.apache.sling.pipes-1.0.0
in repository
https://gitbox.apache.org/repos/asf/sling-org-apache-sling-pipes.git
commit cc06f5ec3cd6f1b5b7e3f6e90a652cdb9106a3c3
Author: Nicolas Peltier <npelt...@apache.org>
AuthorDate: Thu Jul 6 19:38:20 2017 +0000
Fix javadoc error
git-svn-id:
https://svn.apache.org/repos/asf/sling/trunk/contrib/extensions/sling-pipes@1801100
13f79535-47bb-0310-9956-ffa450edef68
---
.../java/org/apache/sling/pipes/OutputWriter.java | 14 ++--
src/main/java/org/apache/sling/pipes/Pipe.java | 7 +-
.../java/org/apache/sling/pipes/PipeBuilder.java | 85 +++++++++++++---------
src/main/java/org/apache/sling/pipes/Plumber.java | 19 ++---
.../sling/pipes/internal/PipeBuilderImpl.java | 14 ++--
.../apache/sling/pipes/internal/PlumberImpl.java | 16 ++--
.../sling/pipes/internal/PlumberServlet.java | 20 ++++-
7 files changed, 102 insertions(+), 73 deletions(-)
diff --git a/src/main/java/org/apache/sling/pipes/OutputWriter.java
b/src/main/java/org/apache/sling/pipes/OutputWriter.java
index 6893202..26d4386 100644
--- a/src/main/java/org/apache/sling/pipes/OutputWriter.java
+++ b/src/main/java/org/apache/sling/pipes/OutputWriter.java
@@ -55,7 +55,7 @@ public abstract class OutputWriter {
* @param request request from which writer will output
* @param response response on which writer will output
* @throws IOException error handling streams
- * @throws JSONException in case invalid json is written
+ * @throws JsonException in case invalid json is written
*/
public void init(SlingHttpServletRequest request, SlingHttpServletResponse
response) throws IOException, JsonException {
max = request.getParameter(PARAM_SIZE) != null ?
Integer.parseInt(request.getParameter(PARAM_SIZE)) : NB_MAX;
@@ -70,14 +70,14 @@ public abstract class OutputWriter {
* @param request request from which writer will output
* @param response response on which writer will output
* @throws IOException error handling streams
- * @throws JSONException in case invalid json is written
+ * @throws JsonException in case invalid json is written
*/
protected abstract void initInternal(SlingHttpServletRequest request,
SlingHttpServletResponse response) throws IOException, JsonException;
/**
* Write a given resource
* @param resource resource that will be written
- * @throws JSONException in case write fails
+ * @throws JsonException in case write fails
*/
public void write(Resource resource) throws JsonException {
if (size++ < max) {
@@ -88,20 +88,20 @@ public abstract class OutputWriter {
/**
* Write a given resource
* @param resource resource that will be written
- * @throws JSONException in case write fails
+ * @throws JsonException in case write fails
*/
protected abstract void writeItem(Resource resource) throws JsonException;
/**
* writes the end of the output
- * @throws JSONException in case invalid json is written
+ * @throws JsonException in case invalid json is written
*/
public abstract void ends() throws JsonException;
/**
- *
- * @param pipe
+ * Setter
+ * @param pipe pipe this writer should be associated with
*/
public void setPipe(Pipe pipe) {
this.pipe = pipe;
diff --git a/src/main/java/org/apache/sling/pipes/Pipe.java
b/src/main/java/org/apache/sling/pipes/Pipe.java
index 2c912db..a823043 100644
--- a/src/main/java/org/apache/sling/pipes/Pipe.java
+++ b/src/main/java/org/apache/sling/pipes/Pipe.java
@@ -44,10 +44,13 @@ public interface Pipe {
*/
String NN_CONF = "conf";
+ /**
+ * Distribution agent (for distributing output resources)
+ */
String PN_DISTRIBUTION_AGENT = "distribution.agent";
/**
- * returns true if that pipe will modify content during its execution
+ * returns true if that pipe modifies content during its execution
* @return true for write / false for read
*/
boolean modifiesContent();
@@ -92,7 +95,7 @@ public interface Pipe {
/**
* get the pipe configuration resource
- * @return
+ * @return Pipe configruation root resource
*/
Resource getResource();
diff --git a/src/main/java/org/apache/sling/pipes/PipeBuilder.java
b/src/main/java/org/apache/sling/pipes/PipeBuilder.java
index 684256e..f5aaab9 100644
--- a/src/main/java/org/apache/sling/pipes/PipeBuilder.java
+++ b/src/main/java/org/apache/sling/pipes/PipeBuilder.java
@@ -21,138 +21,151 @@ import org.apache.sling.api.resource.PersistenceException;
import java.util.Set;
/**
- * Builder & Runner of a pipe, based on a fluent API, for script & java usage.
+ * Builder and Runner of a pipe, based on a fluent API, for script and java
usage.
*/
public interface PipeBuilder {
/**
* attach a new pipe to the current context
- * @param type
- * @return
+ * @param type resource type (should be registered by the plumber)
+ * @return updated instance of PipeBuilder
*/
PipeBuilder pipe(String type);
/**
* attach a move pipe to the current context
- * @param expr
- * @return
+ * @param expr target of the resource to move
+ * @return updated instance of PipeBuilder
*/
PipeBuilder mv(String expr);
/**
* attach a write pipe to the current context
* @param conf configuration parameters
- * @return
+ * @return updated instance of PipeBuilder
+ * @throws IllegalAccessException in case it's called in a bad time
*/
PipeBuilder write(Object... conf) throws IllegalAccessException;
/**
* attach a filter pipe to the current context
* @param conf configuration parameters
- * @return
+ * @return updated instance of PipeBuilder
+ * @throws IllegalAccessException in case it's called in a bad time
*/
PipeBuilder filter(Object... conf) throws IllegalAccessException;
/**
* attach an authorizable pipe to the current context
- * @param conf
- * @return
+ * @param conf configuration key value pairs for authorizable (see pipe's
doc)
+ * @return updated instance of PipeBuilder
+ * @throws IllegalAccessException in case it's called in a bad time
*/
PipeBuilder auth(Object... conf) throws IllegalAccessException;
/**
* attach a xpath pipe to the current context
* @param expr xpath expression
- * @return
+ * @return updated instance of PipeBuilder
+ * @throws IllegalAccessException in case it's called in a bad time
*/
PipeBuilder xpath(String expr) throws IllegalAccessException;
/**
* attach a sling query pipe to the current context
* @param expr sling query expression
- * @return
+ * @return updated instance of PipeBuilder
+ * @throws IllegalAccessException in case it's called in a bad time
*/
PipeBuilder $(String expr) throws IllegalAccessException;
/**
* attach a rm pipe to the current context
- * @return
+ * @return updated instance of PipeBuilder
*/
PipeBuilder rm();
/**
* attach a json pipe to the current context
* @param expr json expr or URL
- * @return
+ * @return updated instance of PipeBuilder
+ * @throws IllegalAccessException in case it's called in a bad time
*/
PipeBuilder json(String expr) throws IllegalAccessException;
/**
* Attach a path pipe to the current context
- * @param expr
- * @return
+ * @param expr path to create
+ * @return updated instance of PipeBuilder
+ * @throws IllegalAccessException in case it's called in a bad time
*/
PipeBuilder mkdir(String expr) throws IllegalAccessException;
/**
* attach a base pipe to the current context
* @param path pipe path
- * @return
+ * @return updated instance of PipeBuilder
+ * @throws IllegalAccessException in case it's called in a bad time
*/
PipeBuilder echo(String path) throws IllegalAccessException;
/**
- * attach a new pipe to the current context
- * @return
+ * attach a parent pipe to the current context
+ * @return updated instance of PipeBuilder
*/
PipeBuilder parent();
/**
* parameterized current pipe in the context
- * @param param
- * @param value
- * @return
+ * @param param key (property name) of the property
+ * @param value value of te property
+ * @return updated instance of PipeBuilder
+ * @throws IllegalAccessException in case it's called in a bad time
*/
PipeBuilder with(String param, String value) throws IllegalAccessException;
/**
- * add an expr configuration to the current pipe in the context
- * @param value
- * @return
+ * set an expr configuration to the current pipe in the context
+ * @param value expression value
+ * @return updated instance of PipeBuilder
+ * @throws IllegalAccessException in case it's called in a bad time
*/
PipeBuilder expr(String value) throws IllegalAccessException;
/**
* sets a pipe name, important in case you want to reuse it in another
expression
- * @param name
- * @return
- * @throws IllegalAccessException
+ * @param name to overwrite default binding name (otherwise it will be
"one", "two", ...)
+ * @return updated instance of PipeBuilder
+ * @throws IllegalAccessException in case it's called in a bad time
*/
PipeBuilder name(String name) throws IllegalAccessException;
/**
- * add a path configuration to the current pipe in the context
- * @param value
- * @return
+ * set a path configuration to the current pipe in the context
+ * @param value path value
+ * @return updated instance of PipeBuilder
+ * @throws IllegalAccessException in case it's called in a bad time
*/
PipeBuilder path(String value) throws IllegalAccessException;
/**
* Building up a set of configurations for the current pipe
- * @param properties
- * @return
+ * @param properties configuration key value pairs (must be an even number
of arguments)
+ * @return updated instance of PipeBuilder
+ * @throws IllegalAccessException in case it's called in a bad time
*/
PipeBuilder conf(Object... properties) throws IllegalAccessException;
/**
* builds a configured pipe
- * @return
+ * @return Created (not executed) Pipe instance
+ * @throws PersistenceException error occuring when saving the pipe
configuration
*/
Pipe build() throws PersistenceException;
/**
- * builds & run configured pipe
- * @return
- * @throws Exception
+ * builds and run configured pipe
+ * @return set of resource path, output of the pipe execution
+ * @throws Exception exceptions thrown by the build or the pipe execution
itself
*/
Set<String> run() throws Exception;
}
diff --git a/src/main/java/org/apache/sling/pipes/Plumber.java
b/src/main/java/org/apache/sling/pipes/Plumber.java
index 026a5b2..67bdcbd 100644
--- a/src/main/java/org/apache/sling/pipes/Plumber.java
+++ b/src/main/java/org/apache/sling/pipes/Plumber.java
@@ -40,9 +40,9 @@ public interface Plumber {
/**
* executes in a background thread
- * @param resolver
- * @param path
- * @param bindings
+ * @param resolver resolver used for registering the execution (id will be
checked against the configuration)
+ * @param path path of the pipe to execute
+ * @param bindings additional bindings to use when executing
* @return Job if registered, null otherwise
*/
Job executeAsync(ResourceResolver resolver, String path, Map bindings);
@@ -81,28 +81,29 @@ public interface Plumber {
/**
* returns wether or not a pipe type is registered
- * @param type
- * @return
+ * @param type resource type tested
+ * @return true if the type is registered, false if not
*/
boolean isTypeRegistered(String type);
/**
* status of the pipe
* @param pipeResource resource corresponding to the pipe
- * @return
+ * @return status of the pipe, can be blank, 'started' or 'finished'
*/
String getStatus(Resource pipeResource);
/**
- * Provides a builder helping quickly build & execute a pipe
- * @return
+ * Provides a builder helping quickly build and execute a pipe
+ * @param resolver resource resolver that will be used for building the
pipe
+ * @return instance of PipeBuilder
*/
PipeBuilder getBuilder(ResourceResolver resolver);
/**
* returns true if the pipe is considered to be running
* @param pipeResource resource corresponding to the pipe
- * @return
+ * @return true if still running
*/
boolean isRunning(Resource pipeResource);
}
diff --git a/src/main/java/org/apache/sling/pipes/internal/PipeBuilderImpl.java
b/src/main/java/org/apache/sling/pipes/internal/PipeBuilderImpl.java
index d78708b..09e8321 100644
--- a/src/main/java/org/apache/sling/pipes/internal/PipeBuilderImpl.java
+++ b/src/main/java/org/apache/sling/pipes/internal/PipeBuilderImpl.java
@@ -51,8 +51,8 @@ public class PipeBuilderImpl implements PipeBuilder {
/**
* protected constructor (to only allow internal classes to build it out)
- * @param resolver
- * @param plumber
+ * @param resolver resolver with which the pipe will be built and executed
+ * @param plumber instance of the plumber
*/
protected PipeBuilderImpl(ResourceResolver resolver, Plumber plumber){
this.plumber = plumber;
@@ -129,7 +129,7 @@ public class PipeBuilderImpl implements PipeBuilder {
/**
* check of presence of a current step, fails loudly if it's not the case
- * @throws IllegalAccessException
+ * @throws IllegalAccessException exception thrown if current step is not
present
*/
protected void checkCurrentStep() throws IllegalAccessException {
if (currentStep == null){
@@ -175,7 +175,7 @@ public class PipeBuilderImpl implements PipeBuilder {
/**
* build a time + random based path under /var/pipes
- * @return
+ * @return full path of future Pipe
*/
protected String buildPipePath() {
final Calendar now = Calendar.getInstance();
@@ -204,11 +204,7 @@ public class PipeBuilderImpl implements PipeBuilder {
return plumber.getPipe(pipeResource);
}
- /**
- * builds & run configured pipe
- * @return
- * @throws Exception
- */
+ @Override
public Set<String> run() throws Exception {
Pipe pipe = this.build();
return plumber.execute(resolver, pipe, null, new NopWriter(), true);
diff --git a/src/main/java/org/apache/sling/pipes/internal/PlumberImpl.java
b/src/main/java/org/apache/sling/pipes/internal/PlumberImpl.java
index ce8a876..8f160cd 100644
--- a/src/main/java/org/apache/sling/pipes/internal/PlumberImpl.java
+++ b/src/main/java/org/apache/sling/pipes/internal/PlumberImpl.java
@@ -118,7 +118,6 @@ public class PlumberImpl implements Plumber, JobConsumer {
registerPipe(PathPipe.RESOURCE_TYPE, PathPipe.class);
registerPipe(FilterPipe.RESOURCE_TYPE, FilterPipe.class);
registerPipe(NotPipe.RESOURCE_TYPE, NotPipe.class);
-
}
@Reference(policy= ReferencePolicy.DYNAMIC, cardinality=
ReferenceCardinality.OPTIONAL)
@@ -210,11 +209,11 @@ public class PlumberImpl implements Plumber, JobConsumer {
/**
* Persists pipe change if big enough, or ended, and eventually distribute
changes
- * @param resolver
- * @param pipe
- * @param paths
+ * @param resolver resolver to use
+ * @param pipe pipe at the origin of the changes,
+ * @param paths paths that have been changed,
* @param currentResource if running, null if ended
- * @throws PersistenceException
+ * @throws PersistenceException in case save fails
*/
protected void persist(ResourceResolver resolver, Pipe pipe, Set<String>
paths, Resource currentResource) throws Exception {
if (pipe.modifiesContent() && resolver.hasChanges() &&
!pipe.isDryRun()){
@@ -243,9 +242,10 @@ public class PlumberImpl implements Plumber, JobConsumer {
}
/**
- * writes the status of the pipe
- * @param pipe
- * @param status
+ * writes the status of the pipe, also update
<code>PN_STATUS_MODIFIED</code> date
+ * @param pipe target pipe
+ * @param status status to write
+ * @throws RepositoryException in case write goes wrong
*/
protected void writeStatus(Pipe pipe, String status) throws
RepositoryException {
if (StringUtils.isNotBlank(status)){
diff --git a/src/main/java/org/apache/sling/pipes/internal/PlumberServlet.java
b/src/main/java/org/apache/sling/pipes/internal/PlumberServlet.java
index 6a33bc5..69c150b 100644
--- a/src/main/java/org/apache/sling/pipes/internal/PlumberServlet.java
+++ b/src/main/java/org/apache/sling/pipes/internal/PlumberServlet.java
@@ -82,6 +82,13 @@ public class PlumberServlet extends SlingAllMethodsServlet {
execute(request, response, true);
}
+ /**
+ * Execution of a pipe corresponding to a request
+ * @param request original request
+ * @param response given response
+ * @param writeAllowed should we consider this execution is about to
modify content
+ * @throws ServletException in case something is wrong...
+ */
protected void execute(SlingHttpServletRequest request,
SlingHttpServletResponse response, boolean writeAllowed) throws
ServletException {
String path =
request.getResource().getResourceType().equals(Plumber.RESOURCE_TYPE) ?
request.getParameter(PARAM_PATH) : request.getResource().getPath();
try {
@@ -109,8 +116,9 @@ public class PlumberServlet extends SlingAllMethodsServlet {
/**
* Converts request into pipe bindings
- * @param request
- * @return
+ * @param request from where to extract bindings
+ * @param writeAllowed should we consider this execution is about to
modify content
+ * @return map of bindings
*/
protected Map getBindingsFromRequest(SlingHttpServletRequest request,
boolean writeAllowed){
Map bindings = new HashMap<>();
@@ -130,6 +138,14 @@ public class PlumberServlet extends SlingAllMethodsServlet
{
return bindings;
}
+ /**
+ * Retrieve an output writer depending on the request
+ * @param request original request against which writers will be tested
+ * @param response response writers will point to
+ * @return instance of the created writer
+ * @throws IOException bad handling of I/O streams,
+ * @throws JsonException bad handling of json output
+ */
OutputWriter getWriter(SlingHttpServletRequest request,
SlingHttpServletResponse response) throws IOException, JsonException {
OutputWriter[] candidates = new OutputWriter[]{new CustomJsonWriter(),
new CustomWriter(), new DefaultOutputWriter()};
for (OutputWriter candidate : candidates) {
--
To stop receiving notification emails like this one, please contact
"commits@sling.apache.org" <commits@sling.apache.org>.
