oakpal:scan-many

Full name:

net.adamcin.oakpal:oakpal-maven-plugin:2.2.2:scan-many

Description:

Scans a list of artifacts by simulating package installation and listening for violations reported by the configured checks. This goal supports the use of ProgressChecks that must evaluate the side effects of installing packages in combination, such as for detection of workspace filter overlap. More simply, this goal can be used in a sidecar project to scan multiple artifacts produced by previous builds using a common library of checklists.

Attributes:

  • Requires a Maven project to be executed.
  • Requires dependency resolution of artifacts in scope: test.
  • Since version: 0.3.0.
  • Binds by default to the lifecycle phase: integration-test.

Required Parameters

Name Type Since Description
<summaryFile> File 0.3.0 The summary file to read integration test results from.
Default value is: ${project.build.directory}/oakpal-plugin/reports/oakpal-summary.json.

Optional Parameters

Name Type Since Description
<blobStorePath> String 1.4.0 Specify a different blob store path.
Default value is: ${project.build.directory}/oakpal-plugin/blobs.
<checklists> List 0.6.0 Specify a list of checklist ids [module/]name to enforce.
<checks> List 0.5.0 Specify a list of Checks to locate and load as ProgressChecks.

Minimally, there are two ways to define a CheckSpec. To load a check from the project's test output directory, you must specify the impl value as a classPath-relative resource name for script checks, or as a fully-qualified class name for Java ProgressCheck implementations.

For example, if your script check source is located at src/test/resources/OAKPAL-INF/scripts/acme-vault-enforcer.js:

<checks>
  <check>
    <impl>OAKPAL-INF/scripts/acme-vault-enforcer.js</impl>
  </check>
</checks>

If your impl represents a script check or a ProgressCheckFactory, you can also provide a config element that will be translated to a JsonObject by the JsonConverter via the OakpalComponentConfigurator:

<checks>
  <check>
    <impl>OAKPAL-INF/scripts/acme-vault-enforcer.js</impl>
    <config>
      <apples>
        <apple>Granny Smith</apple>
        <apple>Red Delicious</apple>
        <apple>IIe</apple>
      </apples>
      <requirePolicyNode>true</requirePolicyNode>
    </config>
  </check>
</checks>

To reference a check from a specific checklist, available on the plugin or project test-scope classpath, you should not specify the impl property, but instead reference it by name, in one of the following formats, in order of increasing specificity,

  1. name
  2. checklistName/name
  3. module/checklistName/name

For example, the oakpal core library provides some useful checks in the basic checklist, like echo, which prints progress events to System.out:

<checks>
  <check>
    <name>net.adamcin.oakpal.core/basic/echo</name>
  </check>
</checks>

It can also be referenced by shorter forms:

<checks>
  <check>
    <name>basic/echo</name>
  </check>
</checks>

<checks>
  <check>
    <name>echo</name>
  </check>
</checks>

You can also override the configs defined by a checklist for a given check:

<checks>
  <check>
    <name>basic/paths</name>
    <config>
      <rules>
        <rule>
          <pattern>/etc/tags(/.*)?</pattern>
          <type>deny</type>
        </rule>
        <rule>
          <pattern>/etc/tags/acme(/.*)?</pattern>
          <type>allow</type>
        </rule>
      </rules>
      <denyAllDeletes>true</denyAllDeletes>
    </config>
  </check>
</checks>

<cndNames> List 0.4.0 Specify a list of Compact NodeType Definition (CND) resource names (to discover in the test-scope classpath) to import before any packages are installed during the scan. This is usually necessary for proprietary CRX applications like AEM. Use "Tools - Export Node Type" in CRX/de lite to export all nodetypes and save it to a file in your project code base on the test-scope class path (i.e. in src/main/resources of a common test-scoped dependency, or under src/test/resources of the referencing module).
<deferBuildFailure> boolean 1.1.0 If violations are reported, defer the build failure until a subsequent verify goal. Set this to true when build has more than one scan execution, so that all errors can be reported. Otherwise, the first execution with failure-level violations will fail the build before the subsequent scan executions have a chance to run.

If this is set to true, be sure the verify goal has been activated for the build, otherwise violations will not be printed and failure-level violations will be implicitly ignored.
<enablePreInstallHooks> boolean 1.4.0 If this is set to true, InstallHooks in pre-install packages will be enabled.
<failOnSeverity> Severity 0.1.0 Specify the minimum violation severity level that will trigger plugin execution failure. Valid options are Severity.MINOR, Severity.MAJOR, and Severity.SEVERE.

FYI: FileVault Importer errors are reported as MAJOR by default.


Default value is: MAJOR.
<forcedRoots> List 0.2.0 Specify a list of paths with associated primaryType and mixinTypes values to create in the repository before installing any packages for the scan. This should only be necessary for packages that you are pre-installing and do not have the ability to adjust to ensure that they contain the necessary DocView XML files to ensure content structure nodetype dependencies are self-contained in the package that depends on them.

For example, to ensure that /home/users/system is created as a rep:AuthorizableFolder, you would add a forcedRoot element with a path of "/home/users/system" and a primaryType of "rep:AuthorizableFolder".

<forcedRoots>
  <forcedRoot>
    <path>/home/users/system</path>
    <primaryType>rep:AuthorizableFolder</primaryType>
    <mixinTypes>
      <mixinType>rep:AccessControllable</mixinType>
    </mixinTypes>
  </forcedRoot>
</forcedRoots>

<installHookPolicy> InstallHookPolicy 1.4.0 Specify a policy for InstallHooks in scanned packages. The possible values are:
PROHIBIT
Report a violation if any hook is registered successfully. Implies REPORT, and SKIP, insofar as the hook will not be executed after registration. Use this level if your policy is to disallow install hooks in your content packages.
REPORT
Report a violation if any hook fails to register. This is likely a class loading issue, or an issue with Jar or Vault packaging. Similar to ABORT, except scan will proceed.
ABORT
Abort the scan if any hook fails to register. This is likely a class loading issue, or an issue with Jar or Vault packaging.
SKIP
Disable install hook processing for scanned packages.
DEFAULT (= REPORT)
Explicitly request the default policy be used.
<jcrNamespaces> List 0.2.0 Specify a list of additional JCR namespaces to register before installing any packages for the scan.

For example:

<jcrNamespaces>
  <jcrNamespace>
    <prefix>crx</prefix>
    <uri>http://www.day.com/crx/1.0</uri>
  </jcrNamespace>
</jcrNamespaces>

<jcrPrivileges> List 0.2.0 Specify a list of additional JCR privileges to register before installing any packages for the scan.

For example:

<jcrPrivileges>
  <jcrPrivilege>crx:replicate</jcrPrivilege>
</jcrPrivileges>

<preInstallArtifacts> List 0.2.0 Specify a list of content-package artifacts to download and pre-install before the scanned packages.

For example:

<preInstallArtifacts>
  <preInstallArtifact>
    <groupId>com.adobe.acs</groupId>
    <artifactId>acs-aem-commons-content</artifactId>
    <version>3.9.0</version>
    <type>zip</type>
  </preInstallArtifact>
</preInstallArtifacts>

<preInstallFiles> List 0.2.0 Specify a list of content package files by path to pre-install, which have already been built or downloaded in a previous phase.
<repoInit> String 2.1.0 Specify an inline repoinit script. This will be applied after all other state initialization parameters, including repoInitFiles. See https://sling.apache.org/documentation/bundles/repository-initialization.html .

Examples:

<repoInit>
  create path /apps
  create path (sling:Folder) /content/dam
</repoInit>

<repoInit>
  <![CDATA[
    register nodetypes
    <<===
    <'sling'='http://sling.apache.org/jcr/sling/1.0'>
    [sling:Folder] > nt:folder, nt:unstructured
    ===>>
  ]]>
</repoInit>

User property is: repoInit.
<repoInitFiles> List 2.1.0 Specify a list of file paths to repoinit scripts. These will be applied in the configured order prior to any instructions specified in the inline repoInit parameter, but only after applying all the other state initialization parameters like jcrNamespaces, jcrPrivileges, preInstallArtifacts, etc. See https://sling.apache.org/documentation/bundles/repository-initialization.html .
User property is: repoInitFiles.
<runModes> List 2.2.0 Specify a list of Sling run modes to simulate for installation of embedded filevault packages and RepositoryInitializer factory configs that provide repoinit scripts. See https://sling.apache.org/documentation/bundles/repository-initialization.html . See https://sling.apache.org/documentation/bundles/repository-initialization.html .
User property is: runModes.
<scanArtifacts> List 0.3.0 Specify a list of content-package artifacts to download and scan in sequence.

For example:

<scanArtifacts>
  <scanArtifact>
    <groupId>com.acmecorp</groupId>
    <artifactId>acmecorp-common-ui.apps</artifactId>
    <version>0.1.0-SNAPSHOT</version>
    <type>zip</type>
  </scanArtifact>
  <scanArtifact>
    <groupId>com.acmecorp</groupId>
    <artifactId>national-site-ui.apps</artifactId>
    <version>0.1.0-SNAPSHOT</version>
    <type>zip</type>
  </scanArtifact>
  <scanArtifact>
    <groupId>com.acmecorp</groupId>
    <artifactId>northwest-region-ui.apps</artifactId>
    <version>0.1.0-SNAPSHOT</version>
    <type>zip</type>
  </scanArtifact>
</scanArtifacts>

<scanFiles> List 0.3.0 Specify a list of local package files to add to the list to scan. These will be installed after those listed in scanArtifacts.

For example:

<scanFiles>
  <scanFile>target/myPackages/firstPackage.zip</scanFile>
  <scanFile>target/myPackages/secondPackage.zip</scanFile>
</scanFiles>

<silenceAllSubpackages> boolean 1.5.0 Set to true to suppress progress check events generated by subpackage installation (and the resulting violations) during the scan. Subpackages will still be installed, and fatal package exceptions will still fail the scan.
<skip> boolean 0.3.0 Specifically skip this plugin's execution.
User property is: oakpal.scan-many.skip.
<skipITs> boolean 0.3.0 Conventional switch to skip integration-test phase goals.
User property is: skipITs.
<skipTests> boolean 0.3.0 Conventional switch to skip test and integration-test phase goals.
User property is: skipTests.
<slingNodeTypes> boolean 0.4.0 Enable automatic discovery and installation of CND files referenced in Sling-Nodetypes Manifest headers in the plugin dependencies or the project's test-scope dependencies.
<storeBlobs> boolean 1.4.1 Set to true to disable the blob store configured by blobStorePath. This forces the blobs to exist in the memory node store, which should run faster, but can more easily exhaust heap with larger packages.
User property is: storeBlobs.

Parameter Details

<blobStorePath>

Specify a different blob store path.
  • Type: java.lang.String
  • Since: 1.4.0
  • Required: No
  • Default: ${project.build.directory}/oakpal-plugin/blobs

<checklists>

Specify a list of checklist ids [module/]name to enforce.
  • Type: java.util.List
  • Since: 0.6.0
  • Required: No

<checks>

Specify a list of Checks to locate and load as ProgressChecks.

Minimally, there are two ways to define a CheckSpec. To load a check from the project's test output directory, you must specify the impl value as a classPath-relative resource name for script checks, or as a fully-qualified class name for Java ProgressCheck implementations.

For example, if your script check source is located at src/test/resources/OAKPAL-INF/scripts/acme-vault-enforcer.js:

<checks>
  <check>
    <impl>OAKPAL-INF/scripts/acme-vault-enforcer.js</impl>
  </check>
</checks>

If your impl represents a script check or a ProgressCheckFactory, you can also provide a config element that will be translated to a JsonObject by the JsonConverter via the OakpalComponentConfigurator:

<checks>
  <check>
    <impl>OAKPAL-INF/scripts/acme-vault-enforcer.js</impl>
    <config>
      <apples>
        <apple>Granny Smith</apple>
        <apple>Red Delicious</apple>
        <apple>IIe</apple>
      </apples>
      <requirePolicyNode>true</requirePolicyNode>
    </config>
  </check>
</checks>

To reference a check from a specific checklist, available on the plugin or project test-scope classpath, you should not specify the impl property, but instead reference it by name, in one of the following formats, in order of increasing specificity,

  1. name
  2. checklistName/name
  3. module/checklistName/name

For example, the oakpal core library provides some useful checks in the basic checklist, like echo, which prints progress events to System.out:

<checks>
  <check>
    <name>net.adamcin.oakpal.core/basic/echo</name>
  </check>
</checks>

It can also be referenced by shorter forms:

<checks>
  <check>
    <name>basic/echo</name>
  </check>
</checks>

<checks>
  <check>
    <name>echo</name>
  </check>
</checks>

You can also override the configs defined by a checklist for a given check:

<checks>
  <check>
    <name>basic/paths</name>
    <config>
      <rules>
        <rule>
          <pattern>/etc/tags(/.*)?</pattern>
          <type>deny</type>
        </rule>
        <rule>
          <pattern>/etc/tags/acme(/.*)?</pattern>
          <type>allow</type>
        </rule>
      </rules>
      <denyAllDeletes>true</denyAllDeletes>
    </config>
  </check>
</checks>
  • Type: java.util.List
  • Since: 0.5.0
  • Required: No

<cndNames>

Specify a list of Compact NodeType Definition (CND) resource names (to discover in the test-scope classpath) to import before any packages are installed during the scan. This is usually necessary for proprietary CRX applications like AEM. Use "Tools - Export Node Type" in CRX/de lite to export all nodetypes and save it to a file in your project code base on the test-scope class path (i.e. in src/main/resources of a common test-scoped dependency, or under src/test/resources of the referencing module).
  • Type: java.util.List
  • Since: 0.4.0
  • Required: No

<deferBuildFailure>

If violations are reported, defer the build failure until a subsequent verify goal. Set this to true when build has more than one scan execution, so that all errors can be reported. Otherwise, the first execution with failure-level violations will fail the build before the subsequent scan executions have a chance to run.

If this is set to true, be sure the verify goal has been activated for the build, otherwise violations will not be printed and failure-level violations will be implicitly ignored.

  • Type: boolean
  • Since: 1.1.0
  • Required: No

<enablePreInstallHooks>

If this is set to true, InstallHooks in pre-install packages will be enabled.
  • Type: boolean
  • Since: 1.4.0
  • Required: No

<failOnSeverity>

Specify the minimum violation severity level that will trigger plugin execution failure. Valid options are Severity.MINOR, Severity.MAJOR, and Severity.SEVERE.

FYI: FileVault Importer errors are reported as MAJOR by default.

  • Type: net.adamcin.oakpal.api.Severity
  • Since: 0.1.0
  • Required: No
  • Default: MAJOR

<forcedRoots>

Specify a list of paths with associated primaryType and mixinTypes values to create in the repository before installing any packages for the scan. This should only be necessary for packages that you are pre-installing and do not have the ability to adjust to ensure that they contain the necessary DocView XML files to ensure content structure nodetype dependencies are self-contained in the package that depends on them.

For example, to ensure that /home/users/system is created as a rep:AuthorizableFolder, you would add a forcedRoot element with a path of "/home/users/system" and a primaryType of "rep:AuthorizableFolder".

<forcedRoots>
  <forcedRoot>
    <path>/home/users/system</path>
    <primaryType>rep:AuthorizableFolder</primaryType>
    <mixinTypes>
      <mixinType>rep:AccessControllable</mixinType>
    </mixinTypes>
  </forcedRoot>
</forcedRoots>
  • Type: java.util.List
  • Since: 0.2.0
  • Required: No

<installHookPolicy>

Specify a policy for InstallHooks in scanned packages. The possible values are:
PROHIBIT
Report a violation if any hook is registered successfully. Implies REPORT, and SKIP, insofar as the hook will not be executed after registration. Use this level if your policy is to disallow install hooks in your content packages.
REPORT
Report a violation if any hook fails to register. This is likely a class loading issue, or an issue with Jar or Vault packaging. Similar to ABORT, except scan will proceed.
ABORT
Abort the scan if any hook fails to register. This is likely a class loading issue, or an issue with Jar or Vault packaging.
SKIP
Disable install hook processing for scanned packages.
DEFAULT (= REPORT)
Explicitly request the default policy be used.
  • Type: net.adamcin.oakpal.core.InstallHookPolicy
  • Since: 1.4.0
  • Required: No

<jcrNamespaces>

Specify a list of additional JCR namespaces to register before installing any packages for the scan.

For example:

<jcrNamespaces>
  <jcrNamespace>
    <prefix>crx</prefix>
    <uri>http://www.day.com/crx/1.0</uri>
  </jcrNamespace>
</jcrNamespaces>
  • Type: java.util.List
  • Since: 0.2.0
  • Required: No

<jcrPrivileges>

Specify a list of additional JCR privileges to register before installing any packages for the scan.

For example:

<jcrPrivileges>
  <jcrPrivilege>crx:replicate</jcrPrivilege>
</jcrPrivileges>
  • Type: java.util.List
  • Since: 0.2.0
  • Required: No

<preInstallArtifacts>

Specify a list of content-package artifacts to download and pre-install before the scanned packages.

For example:

<preInstallArtifacts>
  <preInstallArtifact>
    <groupId>com.adobe.acs</groupId>
    <artifactId>acs-aem-commons-content</artifactId>
    <version>3.9.0</version>
    <type>zip</type>
  </preInstallArtifact>
</preInstallArtifacts>
  • Type: java.util.List
  • Since: 0.2.0
  • Required: No

<preInstallFiles>

Specify a list of content package files by path to pre-install, which have already been built or downloaded in a previous phase.
  • Type: java.util.List
  • Since: 0.2.0
  • Required: No

<repoInit>

Specify an inline repoinit script. This will be applied after all other state initialization parameters, including repoInitFiles. See https://sling.apache.org/documentation/bundles/repository-initialization.html .

Examples:

<repoInit>
  create path /apps
  create path (sling:Folder) /content/dam
</repoInit>

<repoInit>
  <![CDATA[
    register nodetypes
    <<===
    <'sling'='http://sling.apache.org/jcr/sling/1.0'>
    [sling:Folder] > nt:folder, nt:unstructured
    ===>>
  ]]>
</repoInit>
  • Type: java.lang.String
  • Since: 2.1.0
  • Required: No
  • User Property: repoInit

<repoInitFiles>

Specify a list of file paths to repoinit scripts. These will be applied in the configured order prior to any instructions specified in the inline repoInit parameter, but only after applying all the other state initialization parameters like jcrNamespaces, jcrPrivileges, preInstallArtifacts, etc. See https://sling.apache.org/documentation/bundles/repository-initialization.html .
  • Type: java.util.List
  • Since: 2.1.0
  • Required: No
  • User Property: repoInitFiles

<runModes>

Specify a list of Sling run modes to simulate for installation of embedded filevault packages and RepositoryInitializer factory configs that provide repoinit scripts. See https://sling.apache.org/documentation/bundles/repository-initialization.html . See https://sling.apache.org/documentation/bundles/repository-initialization.html .
  • Type: java.util.List
  • Since: 2.2.0
  • Required: No
  • User Property: runModes

<scanArtifacts>

Specify a list of content-package artifacts to download and scan in sequence.

For example:

<scanArtifacts>
  <scanArtifact>
    <groupId>com.acmecorp</groupId>
    <artifactId>acmecorp-common-ui.apps</artifactId>
    <version>0.1.0-SNAPSHOT</version>
    <type>zip</type>
  </scanArtifact>
  <scanArtifact>
    <groupId>com.acmecorp</groupId>
    <artifactId>national-site-ui.apps</artifactId>
    <version>0.1.0-SNAPSHOT</version>
    <type>zip</type>
  </scanArtifact>
  <scanArtifact>
    <groupId>com.acmecorp</groupId>
    <artifactId>northwest-region-ui.apps</artifactId>
    <version>0.1.0-SNAPSHOT</version>
    <type>zip</type>
  </scanArtifact>
</scanArtifacts>
  • Type: java.util.List
  • Since: 0.3.0
  • Required: No

<scanFiles>

Specify a list of local package files to add to the list to scan. These will be installed after those listed in scanArtifacts.

For example:

<scanFiles>
  <scanFile>target/myPackages/firstPackage.zip</scanFile>
  <scanFile>target/myPackages/secondPackage.zip</scanFile>
</scanFiles>
  • Type: java.util.List
  • Since: 0.3.0
  • Required: No

<silenceAllSubpackages>

Set to true to suppress progress check events generated by subpackage installation (and the resulting violations) during the scan. Subpackages will still be installed, and fatal package exceptions will still fail the scan.
  • Type: boolean
  • Since: 1.5.0
  • Required: No

<skip>

Specifically skip this plugin's execution.
  • Type: boolean
  • Since: 0.3.0
  • Required: No
  • User Property: oakpal.scan-many.skip

<skipITs>

Conventional switch to skip integration-test phase goals.
  • Type: boolean
  • Since: 0.3.0
  • Required: No
  • User Property: skipITs

<skipTests>

Conventional switch to skip test and integration-test phase goals.
  • Type: boolean
  • Since: 0.3.0
  • Required: No
  • User Property: skipTests

<slingNodeTypes>

Enable automatic discovery and installation of CND files referenced in Sling-Nodetypes Manifest headers in the plugin dependencies or the project's test-scope dependencies.
  • Type: boolean
  • Since: 0.4.0
  • Required: No

<storeBlobs>

Set to true to disable the blob store configured by blobStorePath. This forces the blobs to exist in the memory node store, which should run faster, but can more easily exhaust heap with larger packages.
  • Type: boolean
  • Since: 1.4.1
  • Required: No
  • User Property: storeBlobs

<summaryFile>

The summary file to read integration test results from.
  • Type: java.io.File
  • Since: 0.3.0
  • Required: Yes
  • Default: ${project.build.directory}/oakpal-plugin/reports/oakpal-summary.json