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.3.0 in repository https://gitbox.apache.org/repos/asf/sling-org-apache-sling-distribution-api.git
commit 7216c227c886e84b3416977e6f72b61d240f98a4 Author: Tommaso Teofili <[email protected]> AuthorDate: Thu Oct 22 10:00:55 2015 +0000 SLING-5179 - expose package (builder) API git-svn-id: https://svn.apache.org/repos/asf/sling/trunk/contrib/extensions/distribution/api@1709974 13f79535-47bb-0310-9956-ffa450edef68 --- ...ackage-info.java => DistributionException.java} | 17 ++- .../apache/sling/distribution/package-info.java | 2 +- .../serialization/DistributionPackage.java | 79 +++++++++++ .../serialization/DistributionPackageBuilder.java | 83 ++++++++++++ .../serialization/DistributionPackageInfo.java | 144 +++++++++++++++++++++ .../{ => serialization}/package-info.java | 4 +- 6 files changed, 324 insertions(+), 5 deletions(-) diff --git a/src/main/java/org/apache/sling/distribution/package-info.java b/src/main/java/org/apache/sling/distribution/DistributionException.java similarity index 69% copy from src/main/java/org/apache/sling/distribution/package-info.java copy to src/main/java/org/apache/sling/distribution/DistributionException.java index a7da64d..5b599ad 100644 --- a/src/main/java/org/apache/sling/distribution/package-info.java +++ b/src/main/java/org/apache/sling/distribution/DistributionException.java @@ -17,8 +17,21 @@ * under the License. */ -@Version("0.2.0") package org.apache.sling.distribution; -import aQute.bnd.annotation.Version; +/** + * Generic checked exception for distribution + */ +public class DistributionException extends Exception { + public DistributionException(Throwable e) { + super(e); + } + + public DistributionException(String string) { + super(string); + } + public DistributionException(String string, Throwable cause) { + super(string, cause); + } +} diff --git a/src/main/java/org/apache/sling/distribution/package-info.java b/src/main/java/org/apache/sling/distribution/package-info.java index a7da64d..f91d309 100644 --- a/src/main/java/org/apache/sling/distribution/package-info.java +++ b/src/main/java/org/apache/sling/distribution/package-info.java @@ -17,7 +17,7 @@ * under the License. */ -@Version("0.2.0") +@Version("0.3.0") package org.apache.sling.distribution; import aQute.bnd.annotation.Version; diff --git a/src/main/java/org/apache/sling/distribution/serialization/DistributionPackage.java b/src/main/java/org/apache/sling/distribution/serialization/DistributionPackage.java new file mode 100644 index 0000000..ecbd5ab --- /dev/null +++ b/src/main/java/org/apache/sling/distribution/serialization/DistributionPackage.java @@ -0,0 +1,79 @@ +/* + * 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.serialization; + +import javax.annotation.Nonnull; +import java.io.IOException; +import java.io.InputStream; + +import aQute.bnd.annotation.ConsumerType; + +/** + * A distribution package + */ +@ConsumerType +public interface DistributionPackage { + + /** + * get package id. the id is a unique string that can be used to identify the package + * + * @return the package id + */ + @Nonnull + String getId(); + + /** + * get the type of package + * + * @return the package type + */ + @Nonnull + String getType(); + + /** + * creates a package stream. + * a new stream is created for each call and it is the caller's obligation to close the stream. + * + * @return an {@link InputStream} + * @throws IOException + */ + @Nonnull + InputStream createInputStream() throws IOException; + + /** + * closes all resources associated with this instance + */ + void close(); + + /** + * releases all resources associated with this package + */ + void delete(); + + /** + * gets an additional info holder for this package. + * The additional info object contains control information rather than content information. + * For example info.origin can be used to skip distributing back to the originating endpoint. + * + * @return the associated metadata to this package + */ + @Nonnull + DistributionPackageInfo getInfo(); + +} diff --git a/src/main/java/org/apache/sling/distribution/serialization/DistributionPackageBuilder.java b/src/main/java/org/apache/sling/distribution/serialization/DistributionPackageBuilder.java new file mode 100644 index 0000000..b782e30 --- /dev/null +++ b/src/main/java/org/apache/sling/distribution/serialization/DistributionPackageBuilder.java @@ -0,0 +1,83 @@ +/* + * 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.serialization; + +import javax.annotation.CheckForNull; +import javax.annotation.Nonnull; +import java.io.InputStream; + +import org.apache.sling.api.resource.ResourceResolver; +import org.apache.sling.distribution.DistributionException; +import org.apache.sling.distribution.DistributionRequest; + +/** + * A builder for {@link DistributionPackage}s + */ +public interface DistributionPackageBuilder { + + /** + * returns the type of a package. Only packages of this type will be accepted by the package builder. + * @return the package type. + */ + String getType(); + + /** + * creates a {@link DistributionPackage} for a specific {@link org.apache.sling.distribution.DistributionRequest} + * + * @param resourceResolver the resource resolver used to access the resources to be packaged + * @param request the {@link org.apache.sling.distribution.DistributionRequest} to create the package for + * @return a {@link DistributionPackage} or <code>null</code> if it could not be created + * @throws DistributionException if any error occurs while creating the package, or if the resource resolver is not authorized to do that + */ + @Nonnull + DistributionPackage createPackage(@Nonnull ResourceResolver resourceResolver, @Nonnull DistributionRequest request) throws DistributionException; + + /** + * reads a stream and tries to convert it to a {@link DistributionPackage} this provider can read and install + * + * @param resourceResolver resource resolver used to store the eventually created package + * @param stream the {@link InputStream} of the package to read + * @return a {@link DistributionPackage} if it can read it from the stream + * @throws DistributionException when the stream cannot be read as a {@link DistributionPackage} + */ + @Nonnull + DistributionPackage readPackage(@Nonnull ResourceResolver resourceResolver, @Nonnull InputStream stream) throws DistributionException; + + /** + * get an already created (and saved into the repository) {@link DistributionPackage} by its id + * + * @param resourceResolver resource resolver used to access the package with the given id + * @param id the unique identifier of an already created {@link DistributionPackage} + * @return a {@link DistributionPackage} if one with such an id exists, <code>null</code> otherwise + * @throws DistributionException when the stream the package with that id cannot be retrieved + */ + @CheckForNull + DistributionPackage getPackage(@Nonnull ResourceResolver resourceResolver, @Nonnull String id) throws DistributionException; + + /** + * Installs the given distributionPackage into the repository + * + * @param resourceResolver the resource resolver used to install the packaged resources + * @param distributionPackage the distribution package to install + * @return <code>true</code> if the package was installed successfully + * @throws DistributionException + */ + boolean installPackage(@Nonnull ResourceResolver resourceResolver, @Nonnull DistributionPackage distributionPackage) throws DistributionException; + +} diff --git a/src/main/java/org/apache/sling/distribution/serialization/DistributionPackageInfo.java b/src/main/java/org/apache/sling/distribution/serialization/DistributionPackageInfo.java new file mode 100644 index 0000000..fcdc0a0 --- /dev/null +++ b/src/main/java/org/apache/sling/distribution/serialization/DistributionPackageInfo.java @@ -0,0 +1,144 @@ +/* + * 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.serialization; + +import javax.annotation.CheckForNull; +import javax.annotation.Nonnull; +import java.net.URI; +import java.util.Arrays; +import java.util.HashMap; +import java.util.Map; + +import org.apache.sling.api.resource.ValueMap; +import org.apache.sling.api.wrappers.ValueMapDecorator; +import org.apache.sling.distribution.DistributionRequestType; + +/** + * Additional information about a package. + * Additional information is optional and components should expect every piece of it to be null. + */ +public final class DistributionPackageInfo extends ValueMapDecorator implements ValueMap { + + /** + * distribution package type + */ + public static String PROPERTY_PACKAGE_TYPE = "package.type"; + + /** + * distribution request paths + */ + public static String PROPERTY_REQUEST_PATHS = "request.paths"; + + /** + * distribution request type + */ + public static String PROPERTY_REQUEST_TYPE = "request.type"; + + /** + * distribution package origin uri + */ + public static String PROPERTY_ORIGIN_URI = "package.origin.uri"; + + /** + * distribution package origin queue + */ + public static String PROPERTY_ORIGIN_QUEUE = "origin.queue"; + + + /** + * Creates a new wrapper around a given map. + * + * @param base wrapped object + */ + public DistributionPackageInfo(Map<String, Object> base) { + super(init(null, base)); + } + + /** + * Creates a new wrapper around a given map. + * + */ + public DistributionPackageInfo(String type) { + super(init(type, null)); + } + + + private static Map<String, Object> init(String type, Map<String, Object> base) { + Map<String, Object> result = new HashMap<String, Object>(); + + if (base != null) { + type = (String) base.get(PROPERTY_PACKAGE_TYPE); + + result = new HashMap<String, Object>(base); + } + + result.put(PROPERTY_PACKAGE_TYPE, type); + + return result; + } + + @Nonnull + public String getType() { + return get(PROPERTY_PACKAGE_TYPE, String.class); + } + + /** + * get the paths covered by the package holding this info + * + * @return an array of paths + */ + @CheckForNull + public String[] getPaths() { + return get(PROPERTY_REQUEST_PATHS, String[].class); + } + + /** + * get the request type associated to the package holding this info + * + * @return the request type + */ + @CheckForNull + public DistributionRequestType getRequestType() { + return get(PROPERTY_REQUEST_TYPE, DistributionRequestType.class); + } + + /** + * retrieves the origin of the package holding this info + * + * @return the package origin + */ + @CheckForNull + public URI getOrigin() { + return get(PROPERTY_ORIGIN_URI, URI.class); + } + + @CheckForNull + public String getQueue() { + return get(PROPERTY_ORIGIN_QUEUE, String.class); + } + + + @Override + public String toString() { + return "DistributionPackageInfo{" + + " requestType=" + getRequestType() + + ", paths=" + Arrays.toString(getPaths()) + + '}'; + } +} diff --git a/src/main/java/org/apache/sling/distribution/package-info.java b/src/main/java/org/apache/sling/distribution/serialization/package-info.java similarity index 92% copy from src/main/java/org/apache/sling/distribution/package-info.java copy to src/main/java/org/apache/sling/distribution/serialization/package-info.java index a7da64d..8759b0e 100644 --- a/src/main/java/org/apache/sling/distribution/package-info.java +++ b/src/main/java/org/apache/sling/distribution/serialization/package-info.java @@ -17,8 +17,8 @@ * under the License. */ -@Version("0.2.0") -package org.apache.sling.distribution; +@Version("0.1.0") +package org.apache.sling.distribution.serialization; import aQute.bnd.annotation.Version; -- To stop receiving notification emails like this one, please contact "[email protected]" <[email protected]>.
