#74, #75, #76, #62, #47, #8 - updates documentation. Also

also
- changes package for ErrorReportingForJira module
- fixes generic type for ActionDomainEvent in userimpersonate module
- updates SecurityModule, ServletApiModule so that they inherit from ModuleAbstract

adocs/documentation/src/main/asciidoc/modules/lib/lib.adoc

@@ -102,6 +102,13 @@ Note that this module is only available through the Wicket viewer, not the REST
 | (none)
 | (none)
 
+| xref:slack/lib-slack.adoc#[Slack Library]
+| Provides the ability to post to a Slack channel.
+
+| (none)
+| (none)
+| link:https://github.com/Ullink/simple-slack-api[Simple Slack API]
+
 | xref:stringinterpolator/lib-stringinterpolator.adoc#[String Interpolator (OGNL) Library]
 |Provides a mechanism to interpolate string templates with either Isis system properties or values obtained from a domain object, using _OGNL_ library.
 
@@ -121,6 +128,13 @@ Note that this module is only available through the Wicket viewer, not the REST
 | (none)
 | link:https://github.com/opensagres/xdocreport[XDocReport]
 
+| xref:zip/lib-zip.adoc#[Zip Library]
+| Zips up a collection of files.
+
+| (none)
+| (none)
+| (none)
+
 |===
 
 

adocs/documentation/src/main/asciidoc/modules/lib/pdfbox/lib-pdfbox.adoc

@@ -91,16 +91,18 @@ It has the following API:
 public class PdfBoxService {
 
     public byte[] merge(byte[]... pdfByteArrays) throws IOException { }     // <1>
+    public byte[] merge(List<File> fileList) throws IOException { ... }     // <2>
+    public byte[] merge(File... files) throws IOException { ... }
 
-    public void merge(                                                      // <2>
+    public void merge(                                                      // <3>
             OutputStream outputStream,
             InputStream... inputStreams
         ) throws IOException { }
 }
 ----
 <1> merge an arbitrary number of PDFs, represented as arrays of bytes, to another byte array
-<2> merge an arbitrary number of PDFs, represented as an input stream, to an output stream
-
+<2> merge a list of files (to avoid memory issues)
+<3> merge an arbitrary number of PDFs, represented as an input stream, to an output stream
 
 
 

adocs/documentation/src/main/asciidoc/modules/lib/servletapi/lib-servletapi.adoc

@@ -101,7 +101,7 @@ public class HttpServletRequestProvider {
 }
 ----
 
-And finally the `HttpServletResponseProvider` defines the following API:
+The `HttpServletResponseProvider` defines the following API:
 
 [source,java]
 ----
@@ -110,6 +110,20 @@ public class HttpServletResponseProvider {
 }
 ----
 
+And finally, the `HttpSessionProvider` defines the following API:
+
+[source,java]
+----
+@DomainService(nature = NatureOfService.DOMAIN)
+public class HttpSessionProvider {
+    public Optional<HttpSession> getHttpSession() { ... }
+    public <T> Optional<T> getAttribute(String key, Class<T> clazz) { ... } // <1>
+    public <T> void setAttribute( String key, T value) { ... }
+    public void removeAttribute(String key) { ... }
+}
+----
+<1> obtains an attribute (previous set) by key, cast to the specified class
+
 These actions are all programmatic and do not appear in the UI.
 
 

adocs/documentation/src/main/asciidoc/modules/lib/slack/lib-slack.adoc

@@ -0,0 +1,135 @@
+[[dom-slack]]
+= Slack Library
+:_basedir: ../../../
+:_imagesdir: images/
+:generate_pdf:
+:toc:
+
+This module (`incode-module-slack-dom`) provides the ability to post to a Slack channel (with Slack running on the Cloud).
+
+
+
+== API & Implementation
+
+The `SlackService` defines the following API:
+
+[source,java]
+----
+public class SlackService {
+    public boolean isConfigured() { ... }                       // <1>
+    public boolean channelExists(String channelName) { ... }    // <2>
+
+    public void sendMessage(                                    // <3>
+            String channelName,
+            String message) { ... }
+    public SlackMessageHandle<SlackMessageReply> sendMessage(   // <4>
+            String channelName,
+            SlackPreparedMessage preparedMessage) { ... }
+}
+----
+<1> whether the service is available for use.
+If not configured, then the `sendMessage(...)` methods will silently no-op.
+<2> allows consumers to check whether a channel exists (before attempting to use it in the `sendMessage(...)`.
+If the servicew is not configured, then returns `false`.
+<3> Sends a message to the specified channel.
+If no such channel exists, then an `IllegalArgumentException` will be thrown.
+<4> Allows more sophisticated messages to be sent (using the API of the underlying implementation library, link:https://github.com/Ullink/simple-slack-api[Simple Slack API].
+
+These actions are all programmatic and do not appear in the UI.
+
+
+
+== How to configure/use
+
+=== Classpath
+
+Update your classpath by adding this dependency in your `dom` project's `pom.xml`:
+
+[source,xml]
+----
+<dependency>
+    <groupId>org.incode.module.slack</groupId>
+    <artifactId>incode-module-slack-dom</artifactId>
+    <version>1.16.1</version>
+</dependency>
+----
+
+Check for later releases by searching link:http://search.maven.org/#search|ga|1|incode-module-slack-dom[Maven Central Repo].
+
+For instructions on how to use the latest `-SNAPSHOT`, see the xref:../../../pages/contributors-guide/contributors-guide.adoc#[contributors guide].
+
+
+=== Configuration Properties
+
+There is one mandatory configuration property.
+
+[source,properties]
+----
+isis.service.slack.authToken=xxxxx
+----
+
+The `authToken` can be obtained by logging into your http://slack.com[slack.com] account, on the settings page for bots.
+This token represents the credentials of the bot posting to the channel, so obviously should be kept private and not be shared around.
+
+
+=== System Properties
+
+Optionally, an http/s proxy can be set, by setting two system properties:
+
+[source,properties]
+----
+-Dhttp.proxyPort=...
+-Dhttp.proxyHost=...
+----
+
+[NOTE]
+====
+Note that the system properties for SSL (`https.proxyHost` and `https.proxyPort`) are *NOT* checked.
+====
+
+
+=== Bootstrapping
+
+In the `AppManifest`, update its `getDependencies()` method, eg:
+
+[source,java]
+----
+@Override
+public Set<Module> getDependencies() {
+    return Sets.newHashSet(
+            ...
+            new org.incode.module.slack.SlackModule(),
+            ...
+    );
+}
+----
+
+
+
+
+== Known issues
+
+None known at this time.
+
+
+
+
+== Dependencies
+
+
+Maven can report modules dependencies using:
+
+
+
+[source,bash]
+----
+mvn dependency:list -o -pl modules/lib/slack/impl -D excludeTransitive=true
+----
+
+which, excluding Apache Isis itself, returns these compile/runtime dependencies:
+
+[source,bash]
+----
+com.ullink.slack:simpleslackapi:jar:1.2.0
+----
+

adocs/documentation/src/main/asciidoc/modules/lib/zip/lib-zip.adoc

@@ -0,0 +1,94 @@
+[[dom-zip]]
+= Zip Library
+:_basedir: ../../../
+:_imagesdir: images/
+:generate_pdf:
+:toc:
+
+This module (`incode-module-zip-dom`) allows a zip to be created from a collection of files.
+
+
+== API & Implementation
+
+The `ZipService` defines the following API:
+
+[source,java]
+----
+public class ZipService {
+
+    @lombok.Data                                                        // <1>
+    public static class FileAndName {
+        private final String name;
+        private final File file;
+    }
+
+    public byte[] zip(final List<FileAndName> fileAndNameList) { ... }  // <2>
+    public byte[] zipFiles(final List<File> fileList) { ... }           // <3>
+}
+----
+<1> immutable value type
+<2> Returns a byte array which is a zip of the collection of files.
+Rather than use the name of the file (which might be temporary files, for example), the name of each file to use (in its zip "entry") is provided.
+<3> Similar to `zip(...)`, but uses each file's name as the zip entry (rather than providing it explicitly).
+
+These actions are all programmatic and do not appear in the UI.
+
+
+
+== How to configure/use
+
+=== Classpath
+
+Update your classpath by adding this dependency in your `dom` project's `pom.xml`:
+
+[source,xml]
+----
+<dependency>
+    <groupId>org.incode.module.zip</groupId>
+    <artifactId>incode-module-zip-dom</artifactId>
+    <version>1.16.1</version>
+</dependency>
+----
+
+Check for later releases by searching link:http://search.maven.org/#search|ga|1|incode-module-zip-dom[Maven Central Repo].
+
+For instructions on how to use the latest `-SNAPSHOT`, see the xref:../../../pages/contributors-guide/contributors-guide.adoc#[contributors guide].
+
+
+
+=== Bootstrapping
+
+In the `AppManifest`, update its `getDependencies()` method, eg:
+
+[source,java]
+----
+@Override
+public Set<Module> getDependencies() {
+    return Sets.newHashSet(
+            ...
+            new org.incode.module.zip.ZipModule(),
+            ...
+    );
+}
+----
+
+
+
+
+== Known issues
+
+None known at this time.
+
+
+
+
+== Dependencies
+
+Maven can report modules dependencies using:
+
+[source,bash]
+----
+mvn dependency:list -o -pl modules/lib/zip/impl -D excludeTransitive=true
+----
+
+This shows no additional compile/runtime dependencies (other than Apache Isis itself).

adocs/documentation/src/main/asciidoc/modules/spi/command/spi-command-replay.adoc

@@ -455,6 +455,6 @@ org.isisaddons.module.quartz:isis-module-quartz-dom
 
 For further details on these dependencies, see:
 
-* xref:../../lib/lib-jaxrsclient.adoc#[JAX-RS Client library]
-* xref:../../ext/ext-quartz.adoc#[Quartz extension]
+* xref:../../lib/jaxrsclient/lib-jaxrsclient.adoc#[JAX-RS Client library]
+* xref:../../ext/quartz/ext-quartz.adoc#[Quartz extension]