Review checked exceptions softening in layout module

Author: yulian-gaponenko

layout/findbugs-filter.xml

@@ -32,15 +32,34 @@
         <Or>
             <And>
                 <Class name="com.itextpdf.layout.font.FontProvider"/>
+                <!-- 
+                    FontProvider is usually used in highlevel API, which requests fonts in deep underlying logic.
+                    IOException would mean that font is chosen and it is supposed to exist, however it cannot be read.
+                    Using fallbacks in such situations would make FontProvider less intuitive.
+                                    
+                    Even though softening of checked exceptions can be handled at higher levels in order to let
+                    the caller of this method know that font creation failed, we prefer to avoid bloating highlevel API
+                    and avoid making higher level code depend on low-level code because of the exceptions handling.
+                 -->
                 <Method name="getPdfFont"  params="com.itextpdf.layout.font.FontInfo, com.itextpdf.layout.font.FontSet" returns="com.itextpdf.kernel.font.PdfFont"/>
             </And>
             <And>
+                <!-- 
+                    Here creating of specific XMLReader is requested for processing patterns in hyphenation. 
+                    If it fails, hyphenation processing cannot be recovered.
+                 -->
                 <Class name="com.itextpdf.layout.hyphenation.PatternParser"/>
                 <Method name="createParser"/>
             </And>
             <And>
                 <Class name="com.itextpdf.layout.renderer.TypographyUtils"/>
                 <Or>
+                    <!--
+                        If typography utils throws an exception at this point, we consider it as unrecoverable situation for
+                        its callers (layouting methods). Presence of typography module in class path is checked before.
+                        It's might be more suitable to wrap checked exceptions at a bit higher level, but we do it here for
+                        the sake of convenience.
+                     -->
                     <Method name="callConstructor"/>
                     <Method name="callMethod" params="java.lang.String, java.lang.String, java.lang.Object, java.lang.Class[], java.lang.Object[]" returns="java.lang.Object"/>
                 </Or>

layout/src/main/java/com/itextpdf/layout/font/FontProvider.java

@@ -353,6 +353,15 @@ public PdfFont getPdfFont(FontInfo fontInfo, FontSet tempFonts) {
                 pdfFont = PdfFontFactory.createFont(fontProgram, encoding, getDefaultEmbeddingFlag());
 
             } catch (IOException e) {
+                // Converting checked exceptions to unchecked RuntimeException (java-specific comment).
+                //
+                // FontProvider is usually used in highlevel API, which requests fonts in deep underlying logic.
+                // IOException would mean that font is chosen and it is supposed to exist, however it cannot be read.
+                // Using fallbacks in such situations would make FontProvider less intuitive.
+                //
+                // Even though softening of checked exceptions can be handled at higher levels in order to let
+                // the caller of this method know that font creation failed, we prefer to avoid bloating highlevel API
+                // and avoid making higher level code depend on low-level code because of the exceptions handling.
                 throw new PdfException(PdfException.IoExceptionWhileCreatingFont, e);
             }
 

layout/src/main/java/com/itextpdf/layout/hyphenation/PatternParser.java

@@ -119,6 +119,10 @@ static XMLReader createParser() {
             factory.setFeature("http://apache.org/xml/features/nonvalidating/load-external-dtd", false);
             return factory.newSAXParser().getXMLReader();
         } catch (Exception e) {
+            // Converting checked exceptions to unchecked RuntimeException (java-specific comment).
+            //
+            // Here creating of specific XMLReader is requested for processing patterns in hyphenation.
+            // If it fails, hyphenation processing cannot be recovered.
             throw new RuntimeException("Couldn't create XMLReader: " + e.getMessage());
         }
     }

layout/src/main/java/com/itextpdf/layout/renderer/TypographyUtils.java

@@ -266,6 +266,15 @@ private static Object callMethod(String className, String methodName, Object tar
         } catch (IllegalArgumentException e) {
             logger.warn(MessageFormatUtil.format("Illegal arguments passed to {0}#{1} method call: {2}", className, methodName, e.getMessage()));
         } catch (Exception e) {
+            // Converting checked exceptions to unchecked RuntimeException (java-specific comment).
+            //
+            // If typography utils throws an exception at this point, we consider it as unrecoverable situation for
+            // its callers (layouting methods). Presence of typography module in class path is checked before.
+            // It's might be more suitable to wrap checked exceptions at a bit higher level, but we do it here for
+            // the sake of convenience.
+            //
+            // The RuntimeException exception is used instead of, for example, PdfException, because failure here is
+            // unexpected and is not connected to PDF documents processing.
             throw new RuntimeException(e.toString(), e);
         }
         return null;
@@ -280,6 +289,15 @@ private static Object callConstructor(String className, Class[] parameterTypes,
         } catch (ClassNotFoundException e) {
             logger.warn(MessageFormatUtil.format("Cannot find class {0}", className));
         } catch (Exception exc) {
+            // Converting checked exceptions to unchecked RuntimeException (java-specific comment).
+            //
+            // If typography utils throws an exception at this point, we consider it as unrecoverable situation for
+            // its callers (layouting methods). Presence of typography module in class path is checked before.
+            // It's might be more suitable to wrap checked exceptions at a bit higher level, but we do it here for
+            // the sake of convenience.
+            //
+            // The RuntimeException exception is used instead of, for example, PdfException, because failure here is
+            // unexpected and is not connected to PDF documents processing.
             throw new RuntimeException(exc.toString(), exc);
         }
         return null;