Improved documentation & fixed stupidity

javaparser · Dec 4, 2018 · bb4ada8 · bb4ada8
1 parent 26498c2
commit bb4ada8
Show file tree

Hide file tree

Showing 2 changed files with 34 additions and 21 deletions.
diff --git a/...in/java/com/github/javaparser/symbolsolver/resolution/typesolvers/CombinedTypeSolver.java b/...in/java/com/github/javaparser/symbolsolver/resolution/typesolvers/CombinedTypeSolver.java
@@ -35,27 +35,37 @@ public class CombinedTypeSolver implements TypeSolver {
 
     private TypeSolver parent;
     private List<TypeSolver> elements = new ArrayList<>();
-    private Predicate<Exception> errorFilter;
+
+    /**
+     * A predicate which determines what to do if an exception is raised during the parsing process.
+     * If it returns <code>true</code> the exception will be ignored, and solving will continue using the next solver in line.
+     * If it returns <code>false</code> the exception will be thrown, stopping the solving process.
+     * 
+     * Main use case for this is to circumvent bugs or missing functionality in some type solvers.
+     * If for example solver A has a bug resulting in a {@link NullPointerException}, you could use a {@link ExceptionHandlers#getTypeBasedWhitelist(Class...) whitelist} to ignore that type of exception.
+     * A secondary solver would then be able to step in when such an error occurs.
+     * 
+     * @see #CombinedTypeSolver(Predicate, TypeSolver...)
+     * @see #setExceptionHandler(Predicate)
+     */
+    private Predicate<Exception> exceptionHandler;
 
     public CombinedTypeSolver(TypeSolver... elements) {
-        this(ExceptionFilters.IGNORE_ALL, elements);
+        this(ExceptionHandlers.IGNORE_NONE, elements);
     }
 
-    /** @see #setFilter(Predicate) */
-    public CombinedTypeSolver(Predicate<Exception> errorFilter, TypeSolver... elements) {
-        setFilter(errorFilter);
+    /** @see #exceptionHandler */
+    public CombinedTypeSolver(Predicate<Exception> exceptionHandler, TypeSolver... elements) {
+        setExceptionHandler(exceptionHandler);
 
         for (TypeSolver el : elements) {
             add(el);
         }
     }
 
-    /**
-     * @param errorFilter A filter which determines if an exception raised while solving should be ignored.
-     *            Should return <code>true</code> when the exception must be <b>ignored</b>.
-     */
-    public void setFilter(Predicate<Exception> errorFilter) {
-        this.errorFilter = errorFilter;
+    /** @see #exceptionHandler */
+    public void setExceptionHandler(Predicate<Exception> exceptionHandler) {
+        this.exceptionHandler = exceptionHandler;
     }
 
     @Override
@@ -82,7 +92,7 @@ public SymbolReference<ResolvedReferenceTypeDeclaration> tryToSolveType(String n
                     return res;
                 }
             } catch (Exception e) {
-                if (!errorFilter.test(e)) { // we shouldn't ignore this exception
+                if (!exceptionHandler.test(e)) { // we shouldn't ignore this exception
                     throw e;
                 }
             }
@@ -100,8 +110,11 @@ public ResolvedReferenceTypeDeclaration solveType(String name) throws UnsolvedSy
         }
     }
 
-    /** Provides some convenience filter implementations */
-    public static class ExceptionFilters {
+    /**
+     * Provides some convenience exception handler implementations
+     * @see CombinedTypeSolver#setExceptionHandler(Predicate)
+     */
+    public static class ExceptionHandlers {
 
         /** Doesn't ignore any exceptions (default) */
         public static final Predicate<Exception> IGNORE_NONE = e -> false;
@@ -139,7 +152,7 @@ public static class ExceptionFilters {
                 UnsupportedOperationException.class, UnsolvedSymbolException.class);
 
         /**
-         * @see CombinedTypeSolver#setFilter(Predicate)
+         * @see CombinedTypeSolver#setExceptionHandler(Predicate)
          * @see #getTypeBasedWhitelist(Class...)
          * 
          * @return A filter that ignores an exception if <b>none</b> of the listed classes are
@@ -158,7 +171,7 @@ public static Predicate<Exception> getTypeBasedBlacklist(Class<? extends Excepti
         }
 
         /**
-         * @see CombinedTypeSolver#setFilter(Predicate)
+         * @see CombinedTypeSolver#setExceptionHandler(Predicate)
          * @see #getTypeBasedBlacklist(Class...)
          * 
          * @return A filter that ignores an exception if <b>any</b> of the listed classes are

diff --git a/...ava/com/github/javaparser/symbolsolver/resolution/typesolvers/CombinedTypeSolverTest.java b/...ava/com/github/javaparser/symbolsolver/resolution/typesolvers/CombinedTypeSolverTest.java
@@ -33,22 +33,22 @@
 import com.github.javaparser.resolution.declarations.ResolvedReferenceTypeDeclaration;
 import com.github.javaparser.symbolsolver.model.resolution.SymbolReference;
 import com.github.javaparser.symbolsolver.model.resolution.TypeSolver;
-import com.github.javaparser.symbolsolver.resolution.typesolvers.CombinedTypeSolver.ExceptionFilters;
+import com.github.javaparser.symbolsolver.resolution.typesolvers.CombinedTypeSolver.ExceptionHandlers;
 
 @RunWith(Parameterized.class)
 public class CombinedTypeSolverTest {
 
     @Parameters
     public static List<Object[]> parameters() {
         // Why these classes? NFE is a subclass, IOOBE is a superclass and ISE is a class without children (by default)
-        Predicate<Exception> whitelistTestFilter = ExceptionFilters.getTypeBasedWhitelist(NumberFormatException.class,
+        Predicate<Exception> whitelistTestFilter = ExceptionHandlers.getTypeBasedWhitelist(NumberFormatException.class,
                 IndexOutOfBoundsException.class, IllegalStateException.class);
-        Predicate<Exception> blacklistTestFilter = ExceptionFilters.getTypeBasedBlacklist(NumberFormatException.class,
+        Predicate<Exception> blacklistTestFilter = ExceptionHandlers.getTypeBasedBlacklist(NumberFormatException.class,
                 IndexOutOfBoundsException.class, IllegalStateException.class);
 
         return Arrays.asList(new Object[][] {
-                { new RuntimeException(), ExceptionFilters.IGNORE_ALL, true }, // 0
-                { new RuntimeException(), ExceptionFilters.IGNORE_NONE, false }, // 1
+                { new RuntimeException(), ExceptionHandlers.IGNORE_ALL, true }, // 0
+                { new RuntimeException(), ExceptionHandlers.IGNORE_NONE, false }, // 1
 
                 { new RuntimeException(), whitelistTestFilter, false }, // 2
                 { new IllegalStateException(), whitelistTestFilter, true }, // 3