From c5d089dc7219f632d908953c87363c82ae212091 Mon Sep 17 00:00:00 2001
From: Peter Gafert <peter.gafert@tngtech.com>
Date: Sun, 10 Mar 2019 21:12:53 +0100
Subject: [PATCH] Adjust user guide to explain the extended API

Signed-off-by: Peter Gafert <peter.gafert@tngtech.com>
---
 docs/userguide/008_The_Library_API.adoc | 33 ++++++++++++++++++++++++
 docs/userguide/html/000_Index.html      | 34 +++++++++++++++++++++++++
 2 files changed, 67 insertions(+)

diff --git a/docs/userguide/008_The_Library_API.adoc b/docs/userguide/008_The_Library_API.adoc
index 4adc249fa0..0d75300d60 100644
--- a/docs/userguide/008_The_Library_API.adoc
+++ b/docs/userguide/008_The_Library_API.adoc
@@ -44,6 +44,39 @@ SlicesRuleDefinition.slices().matching("..myapp.(**)").should().notDependOnEachO
 SlicesRuleDefinition.slices().matching("..myapp.(**).service..").should().notDependOnEachOther()
 ----
 
+If this constraint is too rigid, e.g. in legacy applications where the package structure is rather
+inconsistent, it is possible to further customize the slice creation. This can be done by specifying
+a mapping of `JavaClass` to `SliceIdentifier` where classes with the same `SliceIdentifier` will
+be sorted into the same slice. Consider this example:
+
+[source,java,options="nowrap"]
+----
+SliceAssignment legacyPackageStructure = new SliceAssignment() {
+    // this will specify which classes belong together in the same slice
+    @Override
+    public SliceIdentifier getIdentifierOf(JavaClass javaClass) {
+        if (javaClass.getPackageName().startsWith("com.oldapp")) {
+            return SliceIdentifier.of("Legacy");
+        }
+        if (javaClass.getName().contains(".esb.")) {
+            return SliceIdentifier.of("ESB");
+        }
+        // ... further custom mappings
+
+        // if the class does not match anything, we ignore it
+        return SliceIdentifier.ignore();
+    }
+
+    // this will be part of the rule description if the test fails
+    @Override
+    public String getDescription() {
+        return "legacy package structure";
+    }
+};
+
+SlicesRuleDefinition.slices().assignedFrom(legacyPackageStructure).should().beFreeOfCycles()
+----
+
 === General Coding Rules
 
 The Library API also offers a small set of coding rules that might be useful in various projects.
diff --git a/docs/userguide/html/000_Index.html b/docs/userguide/html/000_Index.html
index 763f0f9b08..6363b55724 100644
--- a/docs/userguide/html/000_Index.html
+++ b/docs/userguide/html/000_Index.html
@@ -1763,6 +1763,40 @@ <h3 id="_slices"><a class="anchor" href="#_slices"></a>8.2. Slices</h3>
 SlicesRuleDefinition.slices().matching("..myapp.(**).service..").should().notDependOnEachOther()</code></pre>
 </div>
 </div>
+<div class="paragraph">
+<p>If this constraint is too rigid, e.g. in legacy applications where the package structure is rather
+inconsistent, it is possible to further customize the slice creation. This can be done by specifying
+a mapping of <code>JavaClass</code> to <code>SliceIdentifier</code> where classes with the same <code>SliceIdentifier</code> will
+be sorted into the same slice. Consider this example:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlightjs highlight nowrap"><code class="language-java hljs" data-lang="java">SliceAssignment legacyPackageStructure = new SliceAssignment() {
+    // this will specify which classes belong together in the same slice
+    @Override
+    public SliceIdentifier getIdentifierOf(JavaClass javaClass) {
+        if (javaClass.getPackageName().startsWith("com.oldapp")) {
+            return SliceIdentifier.of("Legacy");
+        }
+        if (javaClass.getName().contains(".esb.")) {
+            return SliceIdentifier.of("ESB");
+        }
+        // ... further custom mappings
+
+        // if the class does not match anything, we ignore it
+        return SliceIdentifier.ignore();
+    }
+
+    // this will be part of the rule description if the test fails
+    @Override
+    public String getDescription() {
+        return "legacy package structure";
+    }
+};
+
+SlicesRuleDefinition.slices().assignedFrom(legacyPackageStructure).should().beFreeOfCycles()</code></pre>
+</div>
+</div>
 </div>
 <div class="sect2">
 <h3 id="_general_coding_rules"><a class="anchor" href="#_general_coding_rules"></a>8.3. General Coding Rules</h3>