This is an automated email from the ASF dual-hosted git repository. rombert pushed a commit to annotated tag org.apache.sling.distribution.api-0.1.0 in repository https://gitbox.apache.org/repos/asf/sling-org-apache-sling-distribution-api.git
commit 51130fd0c14caa8b981ba08fbb70bfc678505ace Author: Tommaso Teofili <[email protected]> AuthorDate: Fri Nov 21 14:51:51 2014 +0000 SLING-4153 - improve javadoc, added distribution request state, minor fixes git-svn-id: https://svn.apache.org/repos/asf/sling/trunk/contrib/extensions/distribution/api@1640924 13f79535-47bb-0310-9956-ffa450edef68 --- .../distribution/agent/DistributionAgent.java | 17 +++++-- .../communication/DistributionActionType.java | 52 ++++++++------------ .../communication/DistributionRequest.java | 19 ++++---- .../communication/DistributionRequestState.java | 55 ++++++++++++++++++++++ .../communication/DistributionResponse.java | 29 +++++++----- .../component/DistributionComponentFactory.java | 2 +- .../component/DistributionComponentProvider.java | 4 +- .../packaging/DistributionPackage.java | 3 +- .../packaging/DistributionPackageExporter.java | 4 +- .../packaging/DistributionPackageImporter.java | 2 +- .../packaging/DistributionPackageInfo.java | 11 +++-- .../packaging/SharedDistributionPackage.java | 2 +- .../distribution/queue/DistributionQueue.java | 14 +++--- .../queue/DistributionQueueProcessor.java | 8 ++-- .../TransportAuthenticationProvider.java | 2 +- .../distribution/trigger/DistributionTrigger.java | 2 +- 16 files changed, 141 insertions(+), 85 deletions(-) diff --git a/src/main/java/org/apache/sling/distribution/agent/DistributionAgent.java b/src/main/java/org/apache/sling/distribution/agent/DistributionAgent.java index 16b5da2..15a0d6b 100644 --- a/src/main/java/org/apache/sling/distribution/agent/DistributionAgent.java +++ b/src/main/java/org/apache/sling/distribution/agent/DistributionAgent.java @@ -20,7 +20,6 @@ package org.apache.sling.distribution.agent; import javax.annotation.CheckForNull; import javax.annotation.Nonnull; -import javax.annotation.Nullable; import aQute.bnd.annotation.ProviderType; import org.apache.sling.api.resource.ResourceResolver; @@ -39,9 +38,9 @@ import org.apache.sling.distribution.queue.DistributionQueue; @ProviderType public interface DistributionAgent extends DistributionComponent { - /** * retrieves the names of the queues for this agent. + * * @return the list of queue names */ @Nonnull @@ -51,17 +50,25 @@ public interface DistributionAgent extends DistributionComponent { * get the agent queue with the given name * * @param name a queue name - * @return a {@link org.apache.sling.distribution.queue.DistributionQueue} with the given name bound to this agent, if it exists, <code>null</code> otherwise + * @return a {@link org.apache.sling.distribution.queue.DistributionQueue} with the given name bound to this agent, if it exists, + * {@code null} otherwise * @throws DistributionAgentException if an error occurs in retrieving the queue */ @CheckForNull DistributionQueue getQueue(@Nonnull String name) throws DistributionAgentException; /** - * executes a {@link org.apache.sling.distribution.communication.DistributionRequest} + * Perform a {@link org.apache.sling.distribution.communication.DistributionRequest} to distribute content from a source + * instance to a target instance. + * The content to be sent will be assembled according to the information contained in the request. + * A {@link org.apache.sling.distribution.communication.DistributionResponse} holding the {@link org.apache.sling.distribution.communication.DistributionRequestState} + * of the provided request will be returned. + * Synchronous {@link org.apache.sling.distribution.agent.DistributionAgent}s will usally block until the execution has finished + * while asynchronous agents will usually return the response as soon as the content to be distributed has been assembled + * and scheduled for distribution. * * @param distributionRequest the distribution request - * @param resourceResolver the resource resolver used for authenticating the request, + * @param resourceResolver the resource resolver used for authenticating the request, * @return a {@link org.apache.sling.distribution.communication.DistributionResponse} * @throws DistributionAgentException if any error happens during the execution of the request or if the authentication fails */ diff --git a/src/main/java/org/apache/sling/distribution/communication/DistributionActionType.java b/src/main/java/org/apache/sling/distribution/communication/DistributionActionType.java index 98d1ea4..ddf02be 100644 --- a/src/main/java/org/apache/sling/distribution/communication/DistributionActionType.java +++ b/src/main/java/org/apache/sling/distribution/communication/DistributionActionType.java @@ -18,57 +18,43 @@ */ package org.apache.sling.distribution.communication; +import javax.annotation.CheckForNull; + /** - * The type of a specific distribution action, used to decide what to do with specific distribution - * items / requests. + * The action type tied to a specific {@link org.apache.sling.distribution.communication.DistributionRequest}, used to decide how + * the distribution content should be aggregated. + * <p/> + * {@code ADD} requests can for example lead to the creation of a package of resources to be persisted on the target instance. + * {@code DELETE} requests can for example lead to the creation of a "command package" to be sent to the target instance + * to actually remove the resources specified in {@link DistributionRequest#getPaths()}. + * {@code PULL} requests can for example lead to the creation of a "command package" that will trigger fetching of content + * from the target instance. */ public enum DistributionActionType { /** - * Content is added - */ - ADD("Add"), - - /** - * Content is deleted - */ - DELETE("Delete"), - - /** - * Content is polled + * Action type for adding content */ - POLL("Poll"); + ADD, /** - * internal human readable name + * Action type for deleting content */ - private final String name; + DELETE, /** - * Create a type - * - * @param name name + * Action type for pulling content */ - private DistributionActionType(String name) { - this.name = name; - } - - /** - * Returns the human readable type name of this type. - * - * @return the name - */ - public String getName() { - return name; - } + PULL; /** * Creates an action type for the given name. if the name cannot be mapped to a enum type or if - * it's <code>null</code>, <code>null</code> is returned. + * it's {@code null}, {@code null} is returned. * * @param n the name - * @return the type or <code>null</code> + * @return the type or {@code null} */ + @CheckForNull public static DistributionActionType fromName(String n) { if (n == null) { return null; diff --git a/src/main/java/org/apache/sling/distribution/communication/DistributionRequest.java b/src/main/java/org/apache/sling/distribution/communication/DistributionRequest.java index 878b633..14c2dc9 100644 --- a/src/main/java/org/apache/sling/distribution/communication/DistributionRequest.java +++ b/src/main/java/org/apache/sling/distribution/communication/DistributionRequest.java @@ -22,24 +22,25 @@ import javax.annotation.Nonnull; import java.util.Arrays; /** - * A distribution request + * A {@link org.apache.sling.distribution.communication.DistributionRequest} represents the need from the caller to have + * some content being distributed from a source instance to a target instance. */ -public class DistributionRequest { +public final class DistributionRequest { private final long time; - private final DistributionActionType action; + private final DistributionActionType actionType; private final String[] paths; - public DistributionRequest(@Nonnull DistributionActionType action, @Nonnull String... paths) { + public DistributionRequest(@Nonnull DistributionActionType actionType, @Nonnull String... paths) { this.time = System.currentTimeMillis(); - this.action = action; + this.actionType = actionType; this.paths = paths; } /** - * get the time this distribution request was created + * get the time this distribution request was created as a {@code long} returned by {@code System#currentTimeMillis}. * * @return the distribution request creation time as returned by {@code System#currentTimeMillis} */ @@ -50,10 +51,10 @@ public class DistributionRequest { /** * get the {@link DistributionActionType} associated with this request * - * @return the action as a {@link org.apache.sling.distribution.communication.DistributionActionType} + * @return the type of actionType for request as a {@link DistributionActionType} */ public DistributionActionType getActionType() { - return action; + return actionType; } /** @@ -69,7 +70,7 @@ public class DistributionRequest { public String toString() { return "DistributionRequest{" + "time=" + time + - ", action=" + action + + ", actionType=" + actionType + ", paths=" + Arrays.toString(paths) + '}'; } diff --git a/src/main/java/org/apache/sling/distribution/communication/DistributionRequestState.java b/src/main/java/org/apache/sling/distribution/communication/DistributionRequestState.java new file mode 100644 index 0000000..6c2c751 --- /dev/null +++ b/src/main/java/org/apache/sling/distribution/communication/DistributionRequestState.java @@ -0,0 +1,55 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.sling.distribution.communication; + +/** + * The different states a {@link org.apache.sling.distribution.communication.DistributionRequest} can have during its lifecycle. + * Allowed transitions of {@link org.apache.sling.distribution.communication.DistributionRequestState} for a certain + * {@link org.apache.sling.distribution.communication.DistributionRequest} are: + * {@code #SUCCEEDED} -> ø + * {@code #FAILED} -> ø + * {@code #ACCEPTED} -> {@code #FAILED} + * {@code #ACCEPTED} -> {@code #SUCCEEDED} + * <p/> + * {@link org.apache.sling.distribution.communication.DistributionRequest}s against synchronous {@link org.apache.sling.distribution.agent.DistributionAgent}s + * will only results in {@code #SUCCEEDED} or {@code #FAILED} {@link org.apache.sling.distribution.communication.DistributionRequestState}s + * while requests against asynchronous agents can result in any of {@code #SUCCEEDED}, {@code #FAILED} or {@code #ACCEPTED} states. + */ +public enum DistributionRequestState { + + /** + * A {@link org.apache.sling.distribution.communication.DistributionRequest} has succeeded when the content has been + * successfully distributed (created, transported and persisted) from the source instance to the target instance. + */ + SUCCEEDED, + + /** + * A {@link org.apache.sling.distribution.communication.DistributionRequest} has failed when the content cannot be + * successfully distributed from the source instance to target instance, this means the request execution failed during + * one of: creation, transport, persistence. + */ + FAILED, + + /** + * A {@link org.apache.sling.distribution.communication.DistributionRequest} has been accepted when the content to be + * distributed has been successfully created, but not yet either transported or persisted correctly to the target instance. + */ + ACCEPTED + +} diff --git a/src/main/java/org/apache/sling/distribution/communication/DistributionResponse.java b/src/main/java/org/apache/sling/distribution/communication/DistributionResponse.java index 61ba84d..3282e48 100644 --- a/src/main/java/org/apache/sling/distribution/communication/DistributionResponse.java +++ b/src/main/java/org/apache/sling/distribution/communication/DistributionResponse.java @@ -18,32 +18,37 @@ */ package org.apache.sling.distribution.communication; -import com.sun.istack.internal.Nullable; +import javax.annotation.Nonnull; +import javax.annotation.Nullable; /** - * A distribution response + * A {@link org.apache.sling.distribution.communication.DistributionResponse} represents the outcome of a + * {@link org.apache.sling.distribution.communication.DistributionRequest} as handled by a certain {@link org.apache.sling.distribution.agent.DistributionAgent}. + * Such a response will include the {@link org.apache.sling.distribution.communication.DistributionRequestState state} of + * the {@link org.apache.sling.distribution.communication.DistributionRequest request} and optionally a message for more + * verbose information about the outcome of the request. */ public class DistributionResponse { + private final DistributionRequestState state; private final String message; - private final boolean successful; - public DistributionResponse(boolean successful, @Nullable String message) { - this.successful = successful; + public DistributionResponse(@Nonnull DistributionRequestState state, @Nullable String message) { + this.state = state; this.message = message; } - public boolean isSuccessful() { - return successful; + public DistributionRequestState getState() { + return state; } - @Override - public String toString() { - return "{\"success\":" + isSuccessful() + ", \"message\":\"" + getMessage() + "\"}"; + public String getMessage() { + return message != null ? message : ""; } - public String getMessage() { - return message != null ? message : "done nothing"; + @Override + public String toString() { + return "{\"state\":" + state + ", \"message\":\"" + message + "\"}"; } } diff --git a/src/main/java/org/apache/sling/distribution/component/DistributionComponentFactory.java b/src/main/java/org/apache/sling/distribution/component/DistributionComponentFactory.java index bb18225..bddb97e 100644 --- a/src/main/java/org/apache/sling/distribution/component/DistributionComponentFactory.java +++ b/src/main/java/org/apache/sling/distribution/component/DistributionComponentFactory.java @@ -43,7 +43,7 @@ public interface DistributionComponentFactory { * @param <ComponentType> the actual type of the {@link DistributionComponent} * to be created * @param subComponentFactory the factory to be called for creating sub components - * @return a {@link DistributionComponent} of the specified type initialized with given properties or <code>null</code> + * @return a {@link DistributionComponent} of the specified type initialized with given properties or {@code null} * if that could not be created */ @CheckForNull diff --git a/src/main/java/org/apache/sling/distribution/component/DistributionComponentProvider.java b/src/main/java/org/apache/sling/distribution/component/DistributionComponentProvider.java index 2286c36..5f9218e 100644 --- a/src/main/java/org/apache/sling/distribution/component/DistributionComponentProvider.java +++ b/src/main/java/org/apache/sling/distribution/component/DistributionComponentProvider.java @@ -32,14 +32,14 @@ public interface DistributionComponentProvider { /** * Retrieves an already existing component by name. - * If <code>null</code> is passed as componentName then a default component is returned. + * If {@code null} is passed as componentName then a default component is returned. * * @param type the {@link java.lang.Class} of the component to be retrieved * @param componentName the component name * @param <ComponentType> the actual type of the {@link DistributionComponent} * to be retrieved * @return the {@link DistributionComponent} of the specified type, - * with the specified name, or <code>null</code> if such a {@link DistributionComponent} + * with the specified name, or {@code null} if such a {@link DistributionComponent} * doesn't exist */ @CheckForNull diff --git a/src/main/java/org/apache/sling/distribution/packaging/DistributionPackage.java b/src/main/java/org/apache/sling/distribution/packaging/DistributionPackage.java index c04085b..620723c 100644 --- a/src/main/java/org/apache/sling/distribution/packaging/DistributionPackage.java +++ b/src/main/java/org/apache/sling/distribution/packaging/DistributionPackage.java @@ -53,7 +53,7 @@ public interface DistributionPackage { * @return the action */ @Nonnull - String getAction(); + String getActionType(); /** * get the type of package @@ -85,7 +85,6 @@ public interface DistributionPackage { */ void delete(); - /** * gets an additional info holder for this package. * The additional info object contains control information rather than content information. diff --git a/src/main/java/org/apache/sling/distribution/packaging/DistributionPackageExporter.java b/src/main/java/org/apache/sling/distribution/packaging/DistributionPackageExporter.java index dc2bfd0..25ec006 100644 --- a/src/main/java/org/apache/sling/distribution/packaging/DistributionPackageExporter.java +++ b/src/main/java/org/apache/sling/distribution/packaging/DistributionPackageExporter.java @@ -42,7 +42,7 @@ public interface DistributionPackageExporter extends DistributionComponent { * * @param resourceResolver - the resource resolver used to export the packages * @param distributionRequest - the request containing the information about which content is to be exported - * @return a <code>List</code> of {@link DistributionPackage}s + * @return a {@link java.util.List} of {@link DistributionPackage}s */ @Nonnull List<DistributionPackage> exportPackages(@Nonnull ResourceResolver resourceResolver, @Nonnull DistributionRequest distributionRequest) throws DistributionPackageExportException; @@ -52,7 +52,7 @@ public interface DistributionPackageExporter extends DistributionComponent { * * @param resourceResolver - the resource resolver use to obtain the package. * @param distributionPackageId - the id of the package to be retrieved - * @return a {@link DistributionPackage} if available, <code>null</code> otherwise + * @return a {@link DistributionPackage} if available, {@code null} otherwise */ @CheckForNull DistributionPackage getPackage(@Nonnull ResourceResolver resourceResolver, @Nonnull String distributionPackageId); diff --git a/src/main/java/org/apache/sling/distribution/packaging/DistributionPackageImporter.java b/src/main/java/org/apache/sling/distribution/packaging/DistributionPackageImporter.java index a175198..9dfafba 100644 --- a/src/main/java/org/apache/sling/distribution/packaging/DistributionPackageImporter.java +++ b/src/main/java/org/apache/sling/distribution/packaging/DistributionPackageImporter.java @@ -38,7 +38,7 @@ public interface DistributionPackageImporter extends DistributionComponent { * * @param resourceResolver - the resource resolver used to import the resources * @param distributionPackage - the package to be imported - * @return <code>true</code> if the import succeeded, <code>false</code> otherwise + * @return {@code true} if the import succeeded, {@code false} otherwise * @throws DistributionPackageImportException if any error occurs during import */ boolean importPackage(@Nonnull ResourceResolver resourceResolver, @Nonnull DistributionPackage distributionPackage) throws DistributionPackageImportException; diff --git a/src/main/java/org/apache/sling/distribution/packaging/DistributionPackageInfo.java b/src/main/java/org/apache/sling/distribution/packaging/DistributionPackageInfo.java index 326ed8e..300c245 100644 --- a/src/main/java/org/apache/sling/distribution/packaging/DistributionPackageInfo.java +++ b/src/main/java/org/apache/sling/distribution/packaging/DistributionPackageInfo.java @@ -19,20 +19,23 @@ package org.apache.sling.distribution.packaging; +import javax.annotation.CheckForNull; +import java.net.URI; /** * Additional information about a package. * Additional information is optional and components should expect every piece of it to be null. */ -public class DistributionPackageInfo { +public final class DistributionPackageInfo { - private String origin; + private URI origin; /** * retrieves the origin of the package. * @return the package origin */ - public String getOrigin() { + @CheckForNull + public URI getOrigin() { return origin; } @@ -40,7 +43,7 @@ public class DistributionPackageInfo { * sets the origin of the package. * @param origin the originating instance of this package */ - public void setOrigin(String origin) { + public void setOrigin(URI origin) { this.origin = origin; } diff --git a/src/main/java/org/apache/sling/distribution/packaging/SharedDistributionPackage.java b/src/main/java/org/apache/sling/distribution/packaging/SharedDistributionPackage.java index 8bc2130..647f89d 100644 --- a/src/main/java/org/apache/sling/distribution/packaging/SharedDistributionPackage.java +++ b/src/main/java/org/apache/sling/distribution/packaging/SharedDistributionPackage.java @@ -36,7 +36,7 @@ public interface SharedDistributionPackage extends DistributionPackage { /** * release a reference to this package and decrease the reference count. - * when no more references are hold the package <code>delete</code> method is called. + * when no more references are hold the package {@code DistributionPackage#delete} method is called. */ void release(@Nonnull String holderName); diff --git a/src/main/java/org/apache/sling/distribution/queue/DistributionQueue.java b/src/main/java/org/apache/sling/distribution/queue/DistributionQueue.java index 8999408..7e62c1c 100644 --- a/src/main/java/org/apache/sling/distribution/queue/DistributionQueue.java +++ b/src/main/java/org/apache/sling/distribution/queue/DistributionQueue.java @@ -33,7 +33,7 @@ public interface DistributionQueue { /** * get this queue name * - * @return queue name as a <code>String</code> + * @return the queue name */ @Nonnull String getName(); @@ -42,8 +42,8 @@ public interface DistributionQueue { * add a distribution item to this queue * * @param item a distribution item representing the package to distribute - * @return <code>true</code> if the distribution item was added correctly to the queue, - * <code>false</code otherwise + * @return {@code true} if the distribution item was added correctly to the queue, + * {@code false} otherwise */ boolean add(@Nonnull DistributionQueueItem item); @@ -61,7 +61,7 @@ public interface DistributionQueue { /** * get the first item (FIFO wise, the next to be processed) into the queue * - * @return the first item into the queue or <code>null</code> if the queue is empty + * @return the first item into the queue or {@code null} if the queue is empty */ @CheckForNull DistributionQueueItem getHead(); @@ -69,7 +69,7 @@ public interface DistributionQueue { /** * check if the queue is empty * - * @return <code>true</code> if the queue is empty, <code>false</code> otherwise + * @return {@code true} if the queue is empty, {@code false} otherwise */ boolean isEmpty(); @@ -78,7 +78,7 @@ public interface DistributionQueue { * * @param queueItemSelector represents the criteria to filter queue items. * if null is passed then all items are returned. - * @return a <code>Iterable</code> of {@link DistributionQueueItem}s + * @return a {@link java.lang.Iterable} of {@link DistributionQueueItem}s */ @Nonnull Iterable<DistributionQueueItem> getItems(@Nullable DistributionQueueItemSelector queueItemSelector); @@ -86,7 +86,7 @@ public interface DistributionQueue { /** * remove an item from the queue by specifying its id * - * @param id <code>String</code> representing an item's identifier + * @param id an item's identifier */ void remove(@Nonnull String id); } diff --git a/src/main/java/org/apache/sling/distribution/queue/DistributionQueueProcessor.java b/src/main/java/org/apache/sling/distribution/queue/DistributionQueueProcessor.java index dff45c8..3bc874d 100644 --- a/src/main/java/org/apache/sling/distribution/queue/DistributionQueueProcessor.java +++ b/src/main/java/org/apache/sling/distribution/queue/DistributionQueueProcessor.java @@ -29,11 +29,11 @@ import aQute.bnd.annotation.ConsumerType; public interface DistributionQueueProcessor { /** - * Process an item from a certain <code>distributionQueue</code> + * Process an item from a certain {@link org.apache.sling.distribution.queue.DistributionQueue} * - * @param queueName the name of the <code>distributionQueue</code> to be processed - * @param distributionQueueItem the <code>distributionQueueItem</code> to be processed - * @return <code>true</code> if the item was successfully processed, <code>false</code> otherwise + * @param queueName the name of the {@link org.apache.sling.distribution.queue.DistributionQueue} to be processed + * @param distributionQueueItem the {@link org.apache.sling.distribution.queue.DistributionQueueItem} to be processed + * @return {@code true} if the item was successfully processed, {@code false} otherwise */ public boolean process(@Nonnull String queueName, @Nonnull DistributionQueueItem distributionQueueItem); } diff --git a/src/main/java/org/apache/sling/distribution/transport/authentication/TransportAuthenticationProvider.java b/src/main/java/org/apache/sling/distribution/transport/authentication/TransportAuthenticationProvider.java index 6df2d29..5225a1f 100644 --- a/src/main/java/org/apache/sling/distribution/transport/authentication/TransportAuthenticationProvider.java +++ b/src/main/java/org/apache/sling/distribution/transport/authentication/TransportAuthenticationProvider.java @@ -35,7 +35,7 @@ public interface TransportAuthenticationProvider<A, T> extends DistributionCompo * Check if this provider is able to authenticate objects belonging to given 'authenticable' class. * * @param authenticable class of objects to be authenticated - * @return <code>true</code> if this provider can check authentication on instances of this class, <code>false</code> + * @return {@code true} if this provider can check authentication on instances of this class, {@code false} * otherwise */ boolean canAuthenticate(Class<A> authenticable); diff --git a/src/main/java/org/apache/sling/distribution/trigger/DistributionTrigger.java b/src/main/java/org/apache/sling/distribution/trigger/DistributionTrigger.java index 694afa2..f24dca2 100644 --- a/src/main/java/org/apache/sling/distribution/trigger/DistributionTrigger.java +++ b/src/main/java/org/apache/sling/distribution/trigger/DistributionTrigger.java @@ -26,7 +26,7 @@ import org.apache.sling.distribution.component.DistributionComponent; /** * A {@link DistributionTrigger} is responsible to trigger * {@link org.apache.sling.distribution.communication.DistributionRequest}s upon certain 'events' (e.g. Sling / Jcr events, - * periodic polling, etc.). + * periodic pulling, etc.). * A {@link DistributionTrigger} is meant to be stateless so that more than one * {@link DistributionRequestHandler} can be registered into the same trigger. */ -- To stop receiving notification emails like this one, please contact "[email protected]" <[email protected]>.
