Implemented filterer pattern

filterer/README.MD

@@ -0,0 +1,45 @@
+--- # this is so called 'Yaml Front Matter', read up on it here: http://jekyllrb.com/docs/frontmatter/
+layout: pattern
+title: Filterer Pattern
+folder: filterer
+permalink: /patterns/filterer/
+description: Design pattern that helps container-like objects to return filtered version of themselves.# short meta description that shows in Google search results
+categories:
+ - Functional
+tags:
+ - Extensibility
+---
+
+## Name / classification
+Filterer Pattern
+
+## Intent
+The intent of this design pattern is to to introduce a functional interface that will add a functionality for container-like objects to easily return filtered versions of themselves.
+
+## Explanation
+The container-like object needs to have a method that returns an instance of `Filterer`. This helper interface gives 
+ability to covariantly specify a lower bound of contravariant `Predicate` in the subinterfaces of interfaces representing the container-like objects.
+
+## Class diagram
+![Filterer](./etc/filterer.png "Filterer")
+
+## Applicability
+Pattern can be used when working with container-like objects that use subtyping, instead of parametrizing(generics) for extensible class structure.
+It enables you to easily extend filtering ability of container-like objects as business requirements change.
+
+## Tutorials
+* [Article about Filterer pattern posted on it's author's blog](https://blog.tlinkowski.pl/2018/filterer-pattern/)
+* [Application of Filterer pattern in domain of text analysis](https://www.javacodegeeks.com/2019/02/filterer-pattern-10-steps.html)
+
+## Known uses
+One of the uses is present on the blog presented in this link. It presents how to use `Filterer` pattern to create text issue anaylyzer with support for test cases used for unit testing.
+
+## Consequences (the good and the bad, add criticism here)
+Good :
+ * you can easily introduce new subtypes for container-like objects and subtypes for objects that are contained within them and still be able to filter easily be new properties of those new subtypes.
+
+Bad :
+ * covariant return types mixed with generics can be sometimes tricky
+
+## Credits
+* Author of the pattern : [Tomasz Linkowski](https://tlinkowski.pl/)

filterer/etc/filterer.urm.puml

@@ -0,0 +1,132 @@
+@startuml
+package com.iluwatar.filterer.domain {
+  interface Filterer<G, E> {
+    + by(Predicate<? super E>) : G {abstract}
+  }
+}
+package com.iluwatar.filterer.issue {
+  interface Issue {
+    + endOffset() : int {abstract}
+    + startOffset() : int {abstract}
+    + type() : IssueType {abstract}
+  }
+  interface IssueAwareText {
+    + filtered() : Filterer<? extends IssueAwareText, ? extends Issue> {abstract}
+    + issues() : List<? extends Issue> {abstract}
+    + text() : String {abstract}
+  }
+  class IssuePosition {
+    - endOffset : int
+    - startOffset : int
+    - IssuePosition(startOffset : int, endOffset : int)
+    ~ endOffset() : int
+    + equals(o : Object) : boolean
+    + hashCode() : int
+    + of(startOffset : int, endOffset : int) : IssuePosition {static}
+    ~ startOffset() : int
+  }
+  ~enum IssueType {
+    + GRAMMAR {static}
+    + SPELLING {static}
+    + valueOf(name : String) : IssueType {static}
+    + values() : IssueType[] {static}
+  }
+  interface IssueWiseText {
+    + filtered() : Filterer<? extends IssueWiseText, ? extends Issue> {abstract}
+    + issues() : List<? extends Issue> {abstract}
+    + text() : String {abstract}
+  }
+  interface ProbabilisticIssueAwareText {
+    + filtered() : Filterer<? extends ProbabilisticIssueAwareText, ? extends ProbableIssue> {abstract}
+    + issues() : List<? extends ProbableIssue> {abstract}
+  }
+  interface ProbabilisticIssueWiseText {
+    + filtered() : Filterer<? extends ProbabilisticIssueWiseText, ? extends ProbableIssue> {abstract}
+    + issues() : List<? extends ProbableIssue> {abstract}
+  }
+  interface ProbableIssue {
+    + probability() : double {abstract}
+  }
+  class SimpleIssue {
+    - issuePosition : IssuePosition
+    - issueType : IssueType
+    ~ SimpleIssue(issuePosition : IssuePosition, issueType : IssueType)
+    + endOffset() : int
+    + equals(o : Object) : boolean
+    + hashCode() : int
+    + startOffset() : int
+    + type() : IssueType
+  }
+  class SimpleIssueAwareText {
+    - issues : ImmutableList<Issue>
+    - text : String
+    ~ SimpleIssueAwareText(text : String, issues : List<Issue>)
+    + equals(o : Object) : boolean
+    + filtered() : Filterer<? extends IssueAwareText, ? extends Issue>
+    - filteredGroup(predicate : Predicate<? super Issue>) : IssueAwareText
+    - filteredItems(predicate : Predicate<? super Issue>) : ImmutableList<Issue>
+    + hashCode() : int
+    + issues() : List<? extends Issue>
+    + text() : String
+  }
+  class SimpleIssueWiseText {
+    - issues : ImmutableList<Issue>
+    - text : String
+    + SimpleIssueWiseText(text : String, issues : List<Issue>)
+    + equals(o : Object) : boolean
+    + filtered() : Filterer<? extends IssueWiseText, ? extends Issue>
+    - filteredGroup(predicate : Predicate<? super Issue>) : IssueWiseText
+    - filteredItems(predicate : Predicate<? super Issue>) : ImmutableList<Issue>
+    + hashCode() : int
+    + issues() : List<? extends Issue>
+    + text() : String
+  }
+  class SimpleProbabilisticIssueAwareText {
+    - issues : ImmutableList<ProbableIssue>
+    - text : String
+    ~ SimpleProbabilisticIssueAwareText(text : String, issues : List<ProbableIssue>)
+    + equals(o : Object) : boolean
+    + filtered() : Filterer<? extends ProbabilisticIssueAwareText, ? extends ProbableIssue>
+    - filteredGroup(predicate : Predicate<? super ProbableIssue>) : ProbabilisticIssueAwareText
+    - filteredItems(predicate : Predicate<? super ProbableIssue>) : ImmutableList<ProbableIssue>
+    + hashCode() : int
+    + issues() : List<? extends ProbableIssue>
+    + text() : String
+  }
+  class SimpleProbabilisticIssueWiseText {
+    - issues : ImmutableList<ProbableIssue>
+    - text : String
+    + SimpleProbabilisticIssueWiseText(text : String, issues : List<ProbableIssue>)
+    + equals(o : Object) : boolean
+    + filtered() : Filterer<? extends ProbabilisticIssueWiseText, ? extends ProbableIssue>
+    - filteredGroup(predicate : Predicate<? super ProbableIssue>) : ProbabilisticIssueWiseText
+    - filteredItems(predicate : Predicate<? super ProbableIssue>) : ImmutableList<ProbableIssue>
+    + hashCode() : int
+    + issues() : List<? extends ProbableIssue>
+    + text() : String
+  }
+  class SimpleProbableIssue {
+    - probability : double
+    ~ SimpleProbableIssue(issuePosition : IssuePosition, issueType : IssueType, probability : double)
+    + equals(o : Object) : boolean
+    + hashCode() : int
+    + probability() : double
+  }
+}
+SimpleIssueWiseText -->  "-issues" Issue
+SimpleProbabilisticIssueAwareText -->  "-issues" ProbableIssue
+SimpleIssue -->  "-issueType" IssueType
+SimpleIssueAwareText -->  "-issues" Issue
+SimpleProbabilisticIssueWiseText -->  "-issues" ProbableIssue
+SimpleIssue -->  "-issuePosition" IssuePosition
+ProbabilisticIssueAwareText --|> IssueAwareText 
+ProbabilisticIssueWiseText --|> IssueWiseText 
+ProbableIssue --|> Issue 
+SimpleIssue ..|> Issue 
+SimpleIssueAwareText ..|> IssueAwareText 
+SimpleIssueWiseText ..|> IssueWiseText 
+SimpleProbabilisticIssueAwareText ..|> ProbabilisticIssueAwareText 
+SimpleProbabilisticIssueWiseText ..|> ProbabilisticIssueWiseText 
+SimpleProbableIssue ..|> ProbableIssue 
+SimpleProbableIssue --|> SimpleIssue 
+@enduml

filterer/pom.xml

@@ -0,0 +1,76 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+
+    The MIT License
+    Copyright © 2014-2019 Ilkka Seppälä
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to deal
+    in the Software without restriction, including without limitation the rights
+    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in
+    all copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+    THE SOFTWARE.
+
+-->
+<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">
+    <parent>
+        <artifactId>java-design-patterns</artifactId>
+        <groupId>com.iluwatar</groupId>
+        <version>1.23.0-SNAPSHOT</version>
+    </parent>
+    <modelVersion>4.0.0</modelVersion>
+
+    <artifactId>filterer</artifactId>
+
+    <dependencies>
+        <dependency>
+            <groupId>com.google.guava</groupId>
+            <artifactId>guava</artifactId>
+            <version>29.0-jre</version>
+        </dependency>
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter-api</artifactId>
+            <version>5.6.2</version>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter-engine</artifactId>
+            <version>5.6.2</version>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.assertj</groupId>
+            <artifactId>assertj-core</artifactId>
+            <version>3.16.1</version>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <plugins>
+            <plugin>
+                <artifactId>maven-surefire-plugin</artifactId>
+                <version>2.22.2</version>
+            </plugin>
+            <plugin>
+                <artifactId>maven-failsafe-plugin</artifactId>
+                <version>2.22.2</version>
+            </plugin>
+        </plugins>
+    </build>
+</project>

filterer/src/main/java/com/iluwatar/filterer/domain/Filterer.java

@@ -0,0 +1,36 @@
+/*
+ * The MIT License
+ * Copyright © 2014-2019 Ilkka Seppälä
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+
+package com.iluwatar.filterer.domain;
+
+import java.util.function.Predicate;
+
+/**
+ * Filterer helper interface.
+ * @param <G> type of the container-like object.
+ * @param <E> type of the elements contained within this container-like object.
+ */
+@FunctionalInterface
+public interface Filterer<G, E> {
+  G by(Predicate<? super E> predicate);
+}

filterer/src/main/java/com/iluwatar/filterer/issue/Issue.java

@@ -0,0 +1,49 @@
+/*
+ * The MIT License
+ * Copyright © 2014-2019 Ilkka Seppälä
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+
+package com.iluwatar.filterer.issue;
+
+/**
+ * Represents an issue that can be detected in given text.
+ */
+public interface Issue {
+  /**
+   * Returns starting position where the issue begins.
+   *
+   * @return value representing starting position of the issue.
+   */
+  int startOffset();
+
+  /**
+   * Returns ending position where the issue ends.
+   *
+   * @return value representing ending position of the issue.
+   */
+  int endOffset();
+
+  /**
+   * Returns issue type.
+   * @return {@link IssueType}
+   */
+  IssueType type();
+}