sling-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From romb...@apache.org
Subject [sling-org-apache-sling-distribution-api] 02/07: SLING-5179 - expose package (builder) API
Date Tue, 07 Nov 2017 09:29:36 GMT
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 <tommaso@apache.org>
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
"commits@sling.apache.org" <commits@sling.apache.org>.

Mime
View raw message