Updated documentation and introduced shade plugin for embedding bndlib

classes.
adamcin · Jun 5, 2019 · ca423ec · ca423ec
1 parent 2664495
commit ca423ec
Show file tree

Hide file tree

Showing 11 changed files with 173 additions and 88 deletions.
diff --git a/aem/interactive-apps/src/site/xdoc/index.xml b/aem/interactive-apps/src/site/xdoc/index.xml
@@ -19,7 +19,7 @@
         <title>OakPAL Interactive - apps Package</title>
     </properties>
     <body>
-        <section name="oakpal-aem-interactive-apps">
+        <section name="oakpal-interactive-apps">
             <p>
                 OakPAL Interactive - apps Package
             </p>

diff --git a/...mcin.oakpal.interactive/src/main/java/net/adamcin/oakpal/interactive/OakpalScanInput.java b/...mcin.oakpal.interactive/src/main/java/net/adamcin/oakpal/interactive/OakpalScanInput.java
@@ -33,14 +33,30 @@ public interface OakpalScanInput {
     List<String> getChecklists();
 
     /**
+     * Get the list of repository paths for packages to preinstall.
      *
-     * @return
+     * @return the list of repository paths for packages to preinstall
      */
     List<String> getPreInstallPackagePaths();
 
+    /**
+     * Get the list of repository paths to packages to scan.
+     *
+     * @return the list of repository paths to packages to scan
+     */
     List<String> getPackagePaths();
 
+    /**
+     * Get the list of check specs.
+     *
+     * @return the list of check specs
+     */
     List<CheckSpec> getChecks();
 
+    /**
+     * return true to install the platform nodetypes prior to scan.
+     *
+     * @return true to install the platform nodetypes prior to scan
+     */
     boolean isInstallPlatformNodetypes();
 }
diff --git a/core/pom.xml b/core/pom.xml
@@ -15,7 +15,8 @@
   ~ limitations under the License.
   -->
 
-<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
     <modelVersion>4.0.0</modelVersion>
 
     <parent>
@@ -57,6 +58,7 @@
         </testResources>
 
         <plugins>
+
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-dependency-plugin</artifactId>
@@ -100,20 +102,8 @@
                                 Automatic-Module-Name: net.adamcin.oakpal.core
                                 Oakpal-Checklist: OAKPAL-INF/checklists/basic.json
                                 Export-Package: net.adamcin.oakpal.core,net.adamcin.oakpal.core.checks
-                                Private-Package: net.adamcin.oakpal.core.jcrfacade.*,\
-                                    aQute.bnd.osgi,aQute.bnd.header,aQute.lib.base64,aQute.lib.collections,\
-                                    aQute.lib.converter,aQute.libg.generics,aQute.libg.qtokens,\
-                                    aQute.service.reporter
+                                Private-Package: net.adamcin.oakpal.core.jcrfacade.*
                                 Import-Package: org.json;version="[${json.min.version},20180813]",!aQute.*,*
-                                -includeresource: \
-                                    @${project.build.directory}/jar/bndlib.jar!/aQute/bnd/osgi/*,\
-                                    @${project.build.directory}/jar/bndlib.jar!/aQute/bnd/header/*,\
-                                    @${project.build.directory}/jar/bndlib.jar!/aQute/lib/base64/*,\
-                                    @${project.build.directory}/jar/bndlib.jar!/aQute/lib/collections/*,\
-                                    @${project.build.directory}/jar/bndlib.jar!/aQute/lib/converter/*,\
-                                    @${project.build.directory}/jar/bndlib.jar!/aQute/libg/generics/*,\
-                                    @${project.build.directory}/jar/bndlib.jar!/aQute/libg/qtokens/*,\
-                                    @${project.build.directory}/jar/bndlib.jar!/aQute/service/reporter/*
                             ]]></bnd>
                         </configuration>
                     </execution>
@@ -128,6 +118,47 @@
                     </archive>
                 </configuration>
             </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-shade-plugin</artifactId>
+                <version>3.2.1</version>
+                <executions>
+                    <execution>
+                        <phase>package</phase>
+                        <goals>
+                            <goal>shade</goal>
+                        </goals>
+                        <configuration>
+                            <artifactSet>
+                                <includes>
+                                    <include>biz.aQute.bnd:bndlib</include>
+                                </includes>
+                            </artifactSet>
+                            <filters>
+                                <filter>
+                                    <artifact>biz.aQute.bnd:bndlib</artifact>
+                                    <includes>
+                                        <include>aQute/bnd/osgi/**</include>
+                                        <include>aQute/bnd/header/**</include>
+                                        <include>aQute/lib/base64/**</include>
+                                        <include>aQute/lib/collections/**</include>
+                                        <include>aQute/lib/converter/**</include>
+                                        <include>aQute/libg/generics/**</include>
+                                        <include>aQute/libg/qtokens/**</include>
+                                        <include>aQute/service/reporter/**</include>
+                                    </includes>
+                                </filter>
+                            </filters>
+                            <relocations>
+                                <relocation>
+                                    <pattern>aQute</pattern>
+                                    <shadedPattern>net.adamcin.oakpal.shaded.aQute</shadedPattern>
+                                </relocation>
+                            </relocations>
+                        </configuration>
+                    </execution>
+                </executions>
+            </plugin>
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-failsafe-plugin</artifactId>
@@ -192,7 +223,7 @@
         <dependency>
             <groupId>biz.aQute.bnd</groupId>
             <artifactId>bndlib</artifactId>
-            <scope>provided</scope>
+            <scope>compile</scope>
         </dependency>
         <dependency>
             <groupId>junit</groupId>

diff --git a/core/src/main/java/net/adamcin/oakpal/core/CheckSpec.java b/core/src/main/java/net/adamcin/oakpal/core/CheckSpec.java
@@ -234,7 +234,8 @@ static CheckSpec fromJson(final JsonObject json) {
 
     /**
      * Override to ensure subtype details are retained in JSON.
-     * @param builder
+     *
+     * @param builder the json object builder that should be edited by subclasses
      */
     protected void editJson(final JsonObjectBuilder builder) {
         // for overriding classes.

diff --git a/core/src/main/java/net/adamcin/oakpal/core/JsonCnd.java b/core/src/main/java/net/adamcin/oakpal/core/JsonCnd.java
@@ -211,6 +211,23 @@ static Fun.ThrowingFunction<String, Name> qNameOrResidual(@NotNull final NamePat
         };
     }
 
+    /**
+     * a String comparator with a check for residual tokens to push them to the end of a list.
+     */
+    private static final transient Comparator<String> COMPARATOR_PUSH_RESIDUALS;
+    static {
+        final Comparator<String> keyComparator = Comparator.comparing(String::toString);
+        COMPARATOR_PUSH_RESIDUALS = (s1, s2) -> {
+            if (TOKEN_RESIDUAL.equals(s2)) {
+                return -1;
+            } else if (TOKEN_RESIDUAL.equals(s1)) {
+                return 1;
+            } else {
+                return keyComparator.compare(s1, s2);
+            }
+        };
+    }
+
     /**
      * Returns a throwing bi-function that maps a JSON key and associated JSON Object value to a constructed node type definition.
      *
@@ -469,7 +486,7 @@ enum NodeTypeDefinitionKey implements KeyDefinitionToken<QNodeTypeDefinitionBuil
                         .map(pDef -> toEntry(pDef, PropertyDefinitionKey.writeAllJson(pDef, resolver)))
                         .filter(testValue(JsonCnd::nonEmptyValue))
                         .map(mapKey(uncheck1(jcrNameOrResidual(resolver)).compose(QItemDefinition::getName)))
-                        .sorted(Map.Entry.comparingByKey())
+                        .sorted(Map.Entry.comparingByKey(COMPARATOR_PUSH_RESIDUALS))
                         .collect(JsonCollectors.toJsonObject()),
                 // read definition
                 resolver -> (def, value) -> def.setPropertyDefs(value.asJsonObject().entrySet().stream()
@@ -493,7 +510,7 @@ enum NodeTypeDefinitionKey implements KeyDefinitionToken<QNodeTypeDefinitionBuil
                         .map(nDef -> toEntry(nDef, ChildNodeDefinitionKey.writeAllJson(nDef, resolver)))
                         .filter(testValue(JsonCnd::nonEmptyValue))
                         .map(mapKey(uncheck1(jcrNameOrResidual(resolver)).compose(QItemDefinition::getName)))
-                        .sorted(Map.Entry.comparingByKey())
+                        .sorted(Map.Entry.comparingByKey(COMPARATOR_PUSH_RESIDUALS))
                         .collect(JsonCollectors.toJsonObject()),
                 // read definition
                 resolver -> (def, value) -> def.setChildNodeDefs(value.asJsonObject().entrySet().stream()

diff --git a/core/src/main/java/net/adamcin/oakpal/core/QName.java b/core/src/main/java/net/adamcin/oakpal/core/QName.java
@@ -23,6 +23,8 @@
 import org.apache.jackrabbit.oak.spi.namespace.NamespaceConstants;
 import org.apache.jackrabbit.spi.Name;
 import org.apache.jackrabbit.spi.commons.namespace.NamespaceMapping;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
@@ -68,15 +70,15 @@ public final class QName {
     /**
      * Create a new QName.
      *
-     * @param type
-     * @param prefix
-     * @param localName
-     * @param uri
+     * @param type      namespace or nodetype
+     * @param prefix    the associated namespace prefix
+     * @param localName the unqualified local name
+     * @param uri       the namespace URI
      */
-    public QName(final Type type,
-                 final String prefix,
-                 final String localName,
-                 final String uri) {
+    public QName(@NotNull final Type type,
+                 @Nullable final String prefix,
+                 @NotNull final String localName,
+                 @Nullable final String uri) {
         this.type = type;
         this.prefix = prefix;
         this.localName = localName;

diff --git a/core/src/main/java/net/adamcin/oakpal/shaded/package-info.java b/core/src/main/java/net/adamcin/oakpal/shaded/package-info.java
@@ -0,0 +1,17 @@
+/*
+ * Copyright 2019 Mark Adamcin
+ *
+ * Licensed 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 net.adamcin.oakpal.shaded;
diff --git a/...in/oakpal/webster/ForcedRootExporter.java → ...cin/oakpal/webster/ChecklistExporter.java b/...in/oakpal/webster/ForcedRootExporter.java → ...cin/oakpal/webster/ChecklistExporter.java
@@ -77,13 +77,13 @@
 import org.slf4j.LoggerFactory;
 
 /**
- * Exports {@link ForcedRoot}s from a JCR session to assist with project checklist management.
+ * Exports namespaces, node types, and {@link ForcedRoot}s from a JCR session to assist with project checklist management.
  */
-public final class ForcedRootExporter {
-    private static final Logger LOGGER = LoggerFactory.getLogger(ForcedRootExporter.class);
+public final class ChecklistExporter {
+    private static final Logger LOGGER = LoggerFactory.getLogger(ChecklistExporter.class);
 
     /**
-     * Builder for a {@link ForcedRootExporter}, which is otherwise immutable.
+     * Builder for a {@link ChecklistExporter}, which is otherwise immutable.
      */
     public static class Builder {
         private List<Op> operations = new ArrayList<>();
@@ -138,7 +138,7 @@ public Builder byNodeType(final String... nodeTypes) {
          * Limit the scope of exported forced root paths using a list of {@link Rule} patterns. Paths which last-match
          * an "INCLUDE" pattern are considered to be "in scope", which means they can be returned by the specified
          * operations and/or replaced in existing checklists. Use EXCLUDE patterns to protect existing forced roots from
-         * being overwritten by a particular instance of {@link ForcedRootExporter}.
+         * being overwritten by a particular instance of {@link ChecklistExporter}.
          *
          * @param pathScopes the list of include/exclude patterns
          * @return this builder
@@ -193,10 +193,10 @@ public Builder withExportNodeTypes(final List<String> exportNodeTypes) {
         /**
          * Create the new exporter instance.
          *
-         * @return the new {@link ForcedRootExporter} instance
+         * @return the new {@link ChecklistExporter} instance
          */
-        public ForcedRootExporter build() {
-            return new ForcedRootExporter(this.operations, this.exportTypeDefs, this.pathScopes, this.nodeTypeScopes,
+        public ChecklistExporter build() {
+            return new ChecklistExporter(this.operations, this.exportTypeDefs, this.pathScopes, this.nodeTypeScopes,
                     this.nsMapping);
         }
     }
@@ -241,19 +241,19 @@ public String toString() {
     private final List<Rule> nodeTypeScopes;
     private final List<JcrNs> jcrNamespaces;
 
-    private ForcedRootExporter(final List<Op> operations,
-                               final List<String> exportTypeDefs,
-                               final List<Rule> pathScopes,
-                               final List<Rule> nodeTypeScopes,
-                               final List<JcrNs> jcrNamespaces) {
+    private ChecklistExporter(final List<Op> operations,
+                              final List<String> exportTypeDefs,
+                              final List<Rule> pathScopes,
+                              final List<Rule> nodeTypeScopes,
+                              final List<JcrNs> jcrNamespaces) {
         this.operations = operations;
         this.exportTypeDefs = exportTypeDefs;
         this.pathScopes = pathScopes;
         this.nodeTypeScopes = nodeTypeScopes;
         this.jcrNamespaces = jcrNamespaces;
     }
 
-    public enum ChecklistUpdatePolicy {
+    public enum ForcedRootUpdatePolicy {
 
         /**
          * Remove all existing forced roots from the checklist before exporting new ones.
@@ -271,8 +271,8 @@ public enum ChecklistUpdatePolicy {
          */
         MERGE;
 
-        public static ChecklistUpdatePolicy byName(final String name) {
-            for (ChecklistUpdatePolicy value : values()) {
+        public static ForcedRootUpdatePolicy byName(final String name) {
+            for (ForcedRootUpdatePolicy value : values()) {
                 if (value.name().equalsIgnoreCase(name)) {
                     return value;
                 }
@@ -281,7 +281,7 @@ public static ChecklistUpdatePolicy byName(final String name) {
         }
     }
 
-    public static final ChecklistUpdatePolicy DEFAULT_UPDATE_POLICY = ChecklistUpdatePolicy.REPLACE;
+    public static final ForcedRootUpdatePolicy DEFAULT_UPDATE_POLICY = ForcedRootUpdatePolicy.REPLACE;
     public static final String COVARIANT_PREFIX = "+";
 
     static final Predicate<String> COVARIANT_FILTER = name -> name.startsWith(COVARIANT_PREFIX);
@@ -311,13 +311,13 @@ static Set<String> findJcrPrefixesInForcedRoot(final Set<String> acc, final Forc
         Optional.ofNullable(forcedRoot.getPath()).ifPresent(path ->
                 Stream.of(path.split("/"))
                         .filter(name -> !name.isEmpty())
-                        .map(ForcedRootExporter::getNsPrefix)
+                        .map(ChecklistExporter::getNsPrefix)
                         .filter(Objects::nonNull)
                         .forEach(acc::add));
-        Optional.ofNullable(forcedRoot.getPrimaryType()).map(ForcedRootExporter::getNsPrefix).ifPresent(acc::add);
+        Optional.ofNullable(forcedRoot.getPrimaryType()).map(ChecklistExporter::getNsPrefix).ifPresent(acc::add);
         Optional.ofNullable(forcedRoot.getMixinTypes()).map(mixins ->
                 mixins.stream()
-                        .map(ForcedRootExporter::getNsPrefix)
+                        .map(ChecklistExporter::getNsPrefix)
                         .filter(Objects::nonNull)
                         .collect(Collectors.toList()))
                 .ifPresent(acc::addAll);
@@ -373,7 +373,7 @@ public interface WriterOpener {
         @NotNull Writer open() throws IOException;
     }
 
-    Predicate<ForcedRoot> getRetainFilter(final ChecklistUpdatePolicy updatePolicy) {
+    Predicate<ForcedRoot> getRetainFilter(final ForcedRootUpdatePolicy updatePolicy) {
         switch (updatePolicy != null ? updatePolicy : DEFAULT_UPDATE_POLICY) {
             case TRUNCATE:
                 // retain nothing
@@ -412,12 +412,13 @@ BiPredicate<NamePathResolver, NodeType> exportTypeDefSelector() {
      * @param session      the JCR session to export roots from
      * @param checklist    the checklist to update, or null to start from scratch
      * @param updatePolicy specify behavior for retaining existing forced roots
+     * @throws IOException         if an error occurs when writing the checklist
      * @throws RepositoryException if an error occurs when exporting the new forced roots
      */
     public void updateChecklist(final WriterOpener writerOpener,
                                 final Session session,
                                 final Checklist checklist,
-                                final ChecklistUpdatePolicy updatePolicy)
+                                final ForcedRootUpdatePolicy updatePolicy)
             throws IOException, RepositoryException {
 
         final List<JcrNs> chkNs = new ArrayList<>();
@@ -460,7 +461,7 @@ public void updateChecklist(final WriterOpener writerOpener,
         final Set<String> finalPrefixes = new HashSet<>();
         if (!privileges.isEmpty()) {
             builder.add(Checklist.KEY_JCR_PRIVILEGES, JavaxJson.wrap(privileges));
-            privileges.stream().map(ForcedRootExporter::getNsPrefix).forEachOrdered(finalPrefixes::add);
+            privileges.stream().map(ChecklistExporter::getNsPrefix).forEachOrdered(finalPrefixes::add);
         }
 
         newRoots.forEach(root -> existing.put(root.getPath(), root));
@@ -484,7 +485,7 @@ public void updateChecklist(final WriterOpener writerOpener,
 
         final List<Name> foundNodeTypes = forcedRoots.stream()
                 .reduce(new HashSet<>(),
-                        ForcedRootExporter::findNodeTypesInForcedRoot,
+                        ChecklistExporter::findNodeTypesInForcedRoot,
                         (left, right) -> {
                             left.addAll(right);
                             return left;
@@ -523,7 +524,7 @@ public void updateChecklist(final WriterOpener writerOpener,
         // begin namespace handling
         final Set<String> forcedRootPrefixes = forcedRoots.stream()
                 .reduce(new HashSet<>(),
-                        ForcedRootExporter::findJcrPrefixesInForcedRoot,
+                        ChecklistExporter::findJcrPrefixesInForcedRoot,
                         (left, right) -> {
                             left.addAll(right);
                             return left;