Skip to content

Commit

Permalink
documentation updates
Browse files Browse the repository at this point in the history
  • Loading branch information
@adamcin
adamcin committed Sep 13, 2020
1 parent a6615ab commit bcc9da2
Show file tree
Hide file tree
Showing 4 changed files with 181 additions and 15 deletions.
4 changes: 2 additions & 2 deletions api/src/main/java/net/adamcin/oakpal/api/ProgressCheck.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -162,7 +162,7 @@ default void afterExtract(PackageId packageId, Session inspectSession) throws Re
* Override this method to accept an {@link SlingSimulator} to request installation of JCR resources like
* FileVault packages and RepositoryInitializer factory configs, as if running within a Sling repository instance.
* <p>
* Also provied are the set of simulated Sling Run Modes. These are intended to drive construction of JCR path
* Also provided are the set of simulated Sling Run Modes. These are intended to drive construction of JCR path
* patterns to select embedded resources for installation upon receiving a matching
* {@link ProgressCheck#importedPath(PackageId, String, Node, PathAction)} event, but these run modes may also be
* used as a global configuration hint for progress checks that support modal behavior outside of their explicit
Expand Down Expand Up @@ -210,7 +210,7 @@ default void identifyEmbeddedPackage(PackageId packageId, PackageId parentId,


/**
* Provides an opportunity to inspect repository state after installing a resource submitted to the
* Provides an opportunity to inspect repository state after installing a RepoInit scripts resource submitted to the
* {@link SlingSimulator}.
*
* @param scanPackageId the last preinstall or scan package
Expand Down
2 changes: 1 addition & 1 deletion core/src/main/java/net/adamcin/oakpal/core/ScriptProgressCheck.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -87,7 +87,7 @@
* <dd>{@link ProgressCheck#identifySubpackage(PackageId, PackageId)}</dd>
* <dt>beforeSlingInstall(scanPackageId, slingInstallable, inspectSession)</dt>
* <dd>{@link ProgressCheck#beforeSlingInstall(PackageId, SlingInstallable, Session)}</dd>
* <dt>identifyEmbeddedPackage(packageId, parentPackageId, jcrPath)</dt>
* <dt>identifyEmbeddedPackage(packageId, parentPackageId, slingInstallable)</dt>
* <dd>{@link ProgressCheck#identifyEmbeddedPackage(PackageId, PackageId, EmbeddedPackageInstallable)}</dd>
* <dt>appliedRepoInitScripts(scanPackageId, scripts, slingInstallable, inspectSession)</dt>
* <dd>{@link ProgressCheck#appliedRepoInitScripts(PackageId, List, SlingInstallable, Session)}</dd>
Expand Down
90 changes: 86 additions & 4 deletions maven/src/site/resources/exampleCheck.js
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
/*
* Copyright 2018 Mark Adamcin
* Copyright 2020 Mark Adamcin
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
Expand Down Expand Up @@ -36,10 +36,13 @@
* import org.apache.jackrabbit.vault.packaging.PackageProperties;
* import org.apache.jackrabbit.vault.fs.config.MetaInf;
* import java.io.File;
* import java.util.jar.Manifest
* import java.util.jar.Manifest;
* import javax.jcr.Node;
* import javax.jcr.Session;
* import net.adamcin.oakpal.api.PathAction;
* import net.adamcin.oakpal.api.SlingSimulator;
* import net.adamcin.oakpal.api.SlingInstallable;
* import net.adamcin.oakpal.api.EmbeddedPackageInstallable;
*/

/***
Expand All @@ -52,6 +55,32 @@ function getCheckName() {
}
*/

/**
* Override this method to accept a SlingSimulator to request installation of JCR resources like
* FileVault packages and RepositoryInitializer factory configs, as if running within a Sling repository instance.
* <p>
* Also provided are the set of simulated Sling Run Modes. These are intended to drive construction of JCR path
* patterns to select embedded resources for installation upon receiving a matching
* importedPath(PackageId, String, Node, PathAction) event, but these run modes may also be
* used as a global configuration hint for progress checks that support modal behavior outside of their explicit
* JSON config format. NOTE: this set will always be empty by default, and must be populated in the plan or
* overridden at runtime in the execution layer.
*
* @param slingSimulator the sling simulator
* @param runModes the simulated sling run modes
* @since 2.2.0
*/
function simulateSling(slingSimulator /* SlingSimulator */, runModes /* String[] */) {

}

/**
* Called once at the beginning of the scan.
*/
function startedScan() {

}

/**
* Called after the package is uploaded to the package manager at the beginning of the scan. Track subsequent
* events using the package ID provided to this method.
Expand Down Expand Up @@ -133,9 +162,62 @@ function afterExtract(packageId /* PackageId */, inspectSession /* Session */) {
}

/**
* Called once at the beginning of the scan.
* Provides an opportunity to inspect repository state before installing a resource submitted to the
* SlingSimulator.
*
* @param scanPackageId the last preinstall or scan package
* @param slingInstallable the sling installable
* @param inspectSession session providing access to repository state
* @since 2.2.0
*/
function startedScan() {
function beforeSlingInstall(scanPackageId /* PackageId */, slingInstallable /* SlingInstallable */,
inspectSession /* Session */) {

}

/**
* Called after each embedded package is opened, if it has been submitted to the SlingSimulator. Track
* subsequent events using the package ID provided to this method. Conceptually, at least for the purposes of
* enforcing acceptance criteria against packaged JCR content, this is analogous to
* identifySubpackage(packageId, parentId).
*
* @param packageId the embedded package id
* @param parentPackageId the parent packageId
* @param slingInstallable the embedded package slingInstallable that was previously provided to the
* beforeSlingInstall() event.
* @since 2.2.0
*/
function identifyEmbeddedPackage(packageId /* PackageId */, parentPackageId /* PackageId */,
slingInstallable /* EmbeddedPackageInstallable */) {

}

/**
* Provides an opportunity to inspect repository state after installing a RepoInit scripts resource submitted to the
* SlingSimulator.
*
* @param scanPackageId the last preinstall or scan package
* @param scripts the repoinit scripts that were applied
* @param slingInstallable the associated SlingInstallable identifying the source JCR event that provided
* the repo init scripts
* @param inspectSession session providing access to repository state
* @since 2.2.0
*/
function appliedRepoInitScripts(scanPackageId /* PackageId */, scripts /* String[] */,
slingInstallable /* SlingInstallable */, inspectSession /* Session */) {

}

/**
* Provides an opportunity to inspect repository state after complete installation (including its content,
* subpackages, and Sling installable paths) of a package explicitly listed for scanning. This method is NOT called
* for any of its subpackages or embedded packages.
*
* @param scanPackageId the scanned package id
* @param inspectSession session providing access to repository state
* @since 2.2.0
*/
function afterScanPackage(scanPackageId /* PackageId */, inspectSession /* Session */) {

}

Expand Down
100 changes: 92 additions & 8 deletions maven/src/site/xdoc/writing-a-script-check.xml.vm
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,9 +11,9 @@
<a href="exampleCheck.js">the example script</a> as a starting point:
</p>
<div class="source">
<pre>
<pre><![CDATA[
/*
* Copyright 2017 Mark Adamcin
* Copyright 2020 Mark Adamcin
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
Expand Down Expand Up @@ -54,17 +54,47 @@
* import javax.jcr.Node;
* import javax.jcr.Session;
* import net.adamcin.oakpal.api.PathAction;
* import net.adamcin.oakpal.api.SlingSimulator;
* import net.adamcin.oakpal.api.SlingInstallable;
* import net.adamcin.oakpal.api.EmbeddedPackageInstallable;
*/
/***
* Optionally implement this function to return a label for your check.
*/
/*
function getCheckName() {
return "ACME Example Check";
}
*/
/**
* Override this method to accept a SlingSimulator to request installation of JCR resources like
* FileVault packages and RepositoryInitializer factory configs, as if running within a Sling repository instance.
* <p>
* Also provided are the set of simulated Sling Run Modes. These are intended to drive construction of JCR path
* patterns to select embedded resources for installation upon receiving a matching
* importedPath(PackageId, String, Node, PathAction) event, but these run modes may also be
* used as a global configuration hint for progress checks that support modal behavior outside of their explicit
* JSON config format. NOTE: this set will always be empty by default, and must be populated in the plan or
* overridden at runtime in the execution layer.
*
* @param slingSimulator the sling simulator
* @param runModes the simulated sling run modes
* @since 2.2.0
*/
function simulateSling(slingSimulator /* SlingSimulator */, runModes /* String[] */) {
}
/**
* Called once at the beginning of the scan.
*/
function startedScan() {
}
/**
* Called after the package is uploaded to the package manager at the beginning of the scan. Track subsequent
* events using the package ID provided to this method.
Expand All @@ -82,9 +112,9 @@ function identifyPackage(packageId /* PackageId */, file /* File */) {
* @param packageId the package ID of the newly opened subpackage
* @param parentId the package ID of the parent package.
*/
function identifySubpackage(packageId /* PackageId */, parentId /* PackageId */) {
function identifySubpackage(packageId /* PackageId */, parentId /* PackageId */) {
}
}
/**
* Called when a package has a jar manifest that can be read for additional metadata, like Export-Package.
Expand Down Expand Up @@ -131,7 +161,7 @@ function importedPath(packageId /* PackageId */, path /* String */, node /* Node
* @param path deleted path
* @param inspectSession session providing access to repository state
*/
function deletedPath(packageId /* PackageId */, path /* String */) {
function deletedPath(packageId /* PackageId */, path /* String */, inspectSession /* Session */) {
}
Expand All @@ -146,9 +176,62 @@ function afterExtract(packageId /* PackageId */, inspectSession /* Session */) {
}
/**
* Called once at the beginning of the scan.
* Provides an opportunity to inspect repository state before installing a resource submitted to the
* SlingSimulator.
*
* @param scanPackageId the last preinstall or scan package
* @param slingInstallable the sling installable
* @param inspectSession session providing access to repository state
* @since 2.2.0
*/
function startedScan() {
function beforeSlingInstall(scanPackageId /* PackageId */, slingInstallable /* SlingInstallable */,
inspectSession /* Session */) {
}
/**
* Called after each embedded package is opened, if it has been submitted to the SlingSimulator. Track
* subsequent events using the package ID provided to this method. Conceptually, at least for the purposes of
* enforcing acceptance criteria against packaged JCR content, this is analogous to
* identifySubpackage(packageId, parentId).
*
* @param packageId the embedded package id
* @param parentPackageId the parent packageId
* @param slingInstallable the embedded package slingInstallable that was previously provided to the
* beforeSlingInstall() event.
* @since 2.2.0
*/
function identifyEmbeddedPackage(packageId /* PackageId */, parentPackageId /* PackageId */,
slingInstallable /* EmbeddedPackageInstallable */) {
}
/**
* Provides an opportunity to inspect repository state after installing a RepoInit scripts resource submitted to the
* SlingSimulator.
*
* @param scanPackageId the last preinstall or scan package
* @param scripts the repoinit scripts that were applied
* @param slingInstallable the associated SlingInstallable identifying the source JCR event that provided
* the repo init scripts
* @param inspectSession session providing access to repository state
* @since 2.2.0
*/
function appliedRepoInitScripts(scanPackageId /* PackageId */, scripts /* String[] */,
slingInstallable /* SlingInstallable */, inspectSession /* Session */) {
}
/**
* Provides an opportunity to inspect repository state after complete installation (including its content,
* subpackages, and Sling installable paths) of a package explicitly listed for scanning. This method is NOT called
* for any of its subpackages or embedded packages.
*
* @param scanPackageId the scanned package id
* @param inspectSession session providing access to repository state
* @since 2.2.0
*/
function afterScanPackage(scanPackageId /* PackageId */, inspectSession /* Session */) {
}
Expand All @@ -158,7 +241,8 @@ function startedScan() {
function finishedScan() {
}
</pre>
]]></pre>
</div>
</section>
<section name="Add the check to the plugin configuration">
Expand Down

0 comments on commit bcc9da2

Please sign in to comment.