Log a message in case getNextRenderer is not overridden in an extended class. Improve its javadoc

DEVSIX-5277

Author: ars18wrw

io/src/main/java/com/itextpdf/io/LogMessageConstant.java

@@ -122,6 +122,10 @@ public final class LogMessageConstant {
     public static final String FONT_SUBSET_ISSUE = "Font subset issue. Full font will be embedded.";
     public static final String FORBID_RELEASE_IS_SET = "ForbidRelease flag is set and release is called. Releasing will not be performed.";
     public static final String FORM_FIELD_WAS_FLUSHED = "A form field was flushed. There's no way to create this field in the AcroForm dictionary.";
+    public static final String GET_NEXT_RENDERER_SHOULD_BE_OVERRIDDEN = "If a renderer overflows, "
+            + "iText uses this method to create another renderer for the overflow part. So if one wants "
+            + "to extend the renderer, one should override this method: otherwise the default method "
+            + "will be used and thus the default rather than the custom renderer will be created.";
     public static final String GPOS_LOOKUP_SUBTABLE_FORMAT_NOT_SUPPORTED =
             "Subtable format {0} of GPOS Lookup Type {1} is not supported yet";
     public static final String GRAPHICS_STATE_WAS_DELETED = "Graphics state is always deleted after event dispatching. If you want to preserve it in renderer info, use preserveGraphicsState method after receiving renderer info.";

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

@@ -2735,6 +2735,16 @@ void setThisAsParent(Collection<IRenderer> children) {
         }
     }
 
+    boolean logWarningIfGetNextRendererNotOverridden(Class<?> baseClass, Class<?> rendererClass) {
+        if (baseClass != rendererClass) {
+            final Logger logger = LoggerFactory.getLogger(baseClass);
+            logger.warn(MessageFormatUtil.format(LogMessageConstant.GET_NEXT_RENDERER_SHOULD_BE_OVERRIDDEN));
+            return false;
+        } else {
+            return true;
+        }
+    }
+
     private void removeThisFromParent(IRenderer toRemove) {
         // we need to be sure that the removed element has no other entries in child renderers list
         if (toRemove != null && this == toRemove.getParent() && !this.childRenderers.contains(toRemove)) {

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

@@ -52,6 +52,7 @@ This file is part of the iText (R) project.
 import com.itextpdf.layout.IPropertyContainer;
 import com.itextpdf.layout.borders.Border;
 import com.itextpdf.layout.element.Cell;
+import com.itextpdf.layout.layout.LayoutContext;
 import com.itextpdf.layout.property.BorderCollapsePropertyValue;
 import com.itextpdf.layout.property.Property;
 import com.itextpdf.layout.property.UnitValue;
@@ -201,10 +202,19 @@ protected Rectangle applySpacings(Rectangle rect, float[] spacings, boolean reve
     }
 
     /**
-     * {@inheritDoc}
+     * Gets a new instance of this class to be used as a next renderer, after this renderer is used, if
+     * {@link #layout(LayoutContext)} is called more than once.
+     *
+     * <p>
+     * If a renderer overflows to the next area, iText uses this method to create a renderer
+     * for the overflow part. So if one wants to extend {@link CellRenderer}, one should override
+     * this method: otherwise the default method will be used and thus the default rather than the custom
+     * renderer will be created.
+     * @return new renderer instance
      */
     @Override
     public IRenderer getNextRenderer() {
+        logWarningIfGetNextRendererNotOverridden(CellRenderer.class, this.getClass());
         return new CellRenderer((Cell) getModelElement());
     }
 }

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

@@ -44,6 +44,7 @@ This file is part of the iText (R) project.
 package com.itextpdf.layout.renderer;
 
 import com.itextpdf.layout.element.Div;
+import com.itextpdf.layout.layout.LayoutContext;
 
 public class DivRenderer extends BlockRenderer {
 
@@ -57,10 +58,19 @@ public DivRenderer(Div modelElement) {
     }
 
     /**
-     * {@inheritDoc}
+     * Gets a new instance of this class to be used as a next renderer, after this renderer is used, if
+     * {@link #layout(LayoutContext)} is called more than once.
+     *
+     * <p>
+     * If a renderer overflows to the next area, iText uses this method to create a renderer
+     * for the overflow part. So if one wants to extend {@link DivRenderer}, one should override
+     * this method: otherwise the default method will be used and thus the default rather than the custom
+     * renderer will be created.
+     * @return new renderer instance
      */
     @Override
     public IRenderer getNextRenderer() {
+        logWarningIfGetNextRendererNotOverridden(DivRenderer.class, this.getClass());
         return new DivRenderer((Div) modelElement);
     }
 }

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

@@ -75,10 +75,19 @@ public FlexContainerRenderer(Div modelElement) {
     }
 
     /**
-     * {@inheritDoc}
+     * Gets a new instance of this class to be used as a next renderer, after this renderer is used, if
+     * {@link #layout(LayoutContext)} is called more than once.
+     *
+     * <p>
+     * If a renderer overflows to the next area, iText uses this method to create a renderer
+     * for the overflow part. So if one wants to extend {@link FlexContainerRenderer}, one should override
+     * this method: otherwise the default method will be used and thus the default rather than the custom
+     * renderer will be created.
+     * @return new renderer instance
      */
     @Override
     public IRenderer getNextRenderer() {
+        logWarningIfGetNextRendererNotOverridden(FlexContainerRenderer.class, this.getClass());
         return new FlexContainerRenderer((Div) modelElement);
     }
 

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

@@ -49,6 +49,7 @@ This file is part of the iText (R) project.
 import org.slf4j.LoggerFactory;
 
 import com.itextpdf.io.util.MessageFormatUtil;
+import com.itextpdf.layout.layout.LayoutContext;
 
 public class LinkRenderer extends TextRenderer {
 
@@ -88,8 +89,20 @@ public void draw(DrawContext drawContext) {
 
     }
 
+    /**
+     * Gets a new instance of this class to be used as a next renderer, after this renderer is used, if
+     * {@link #layout(LayoutContext)} is called more than once.
+     *
+     * <p>
+     * If a renderer overflows to the next area, iText uses this method to create a renderer
+     * for the overflow part. So if one wants to extend {@link LinkRenderer}, one should override
+     * this method: otherwise the default method will be used and thus the default rather than the custom
+     * renderer will be created.
+     * @return new renderer instance
+     */
     @Override
     public IRenderer getNextRenderer() {
+        logWarningIfGetNextRendererNotOverridden(LinkRenderer.class, this.getClass());
         return new LinkRenderer((Link) modelElement);
     }
 }

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

@@ -103,8 +103,20 @@ public LayoutResult layout(LayoutContext layoutContext) {
         return result;
     }
 
+    /**
+     * Gets a new instance of this class to be used as a next renderer, after this renderer is used, if
+     * {@link #layout(LayoutContext)} is called more than once.
+     *
+     * <p>
+     * If a renderer overflows to the next area, iText uses this method to create a renderer
+     * for the overflow part. So if one wants to extend {@link ListRenderer}, one should override
+     * this method: otherwise the default method will be used and thus the default rather than the custom
+     * renderer will be created.
+     * @return new renderer instance
+     */
     @Override
     public IRenderer getNextRenderer() {
+        logWarningIfGetNextRendererNotOverridden(ListRenderer.class, this.getClass());
         return new ListRenderer((com.itextpdf.layout.element.List) modelElement);
     }
 

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

@@ -67,6 +67,7 @@ This file is part of the iText (R) project.
 import com.itextpdf.layout.property.RenderingMode;
 import com.itextpdf.layout.property.TextAlignment;
 import com.itextpdf.layout.property.UnitValue;
+
 import org.slf4j.LoggerFactory;
 
 import java.util.ArrayList;
@@ -501,10 +502,19 @@ protected LayoutResult directLayout(LayoutContext layoutContext) {
     }
 
     /**
-     * {@inheritDoc}
+     * Gets a new instance of this class to be used as a next renderer, after this renderer is used, if
+     * {@link #layout(LayoutContext)} is called more than once.
+     *
+     * <p>
+     * If a renderer overflows to the next area, iText uses this method to create a renderer
+     * for the overflow part. So if one wants to extend {@link ParagraphRenderer}, one should override
+     * this method: otherwise the default method will be used and thus the default rather than the custom
+     * renderer will be created.
+     * @return new renderer instance
      */
     @Override
     public IRenderer getNextRenderer() {
+        logWarningIfGetNextRendererNotOverridden(ParagraphRenderer.class, this.getClass());
         return new ParagraphRenderer((Paragraph) modelElement);
     }
 

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

@@ -106,8 +106,20 @@ public void draw(DrawContext drawContext) {
         }
     }
 
+    /**
+     * Gets a new instance of this class to be used as a next renderer, after this renderer is used, if
+     * {@link #layout(LayoutContext)} is called more than once.
+     *
+     * <p>
+     * If a renderer overflows to the next area, iText uses this method to create a renderer
+     * for the overflow part. So if one wants to extend {@link TabRenderer}, one should override
+     * this method: otherwise the default method will be used and thus the default rather than the custom
+     * renderer will be created.
+     * @return new renderer instance
+     */
     @Override
     public IRenderer getNextRenderer() {
+        logWarningIfGetNextRendererNotOverridden(TabRenderer.class, this.getClass());
         return new TabRenderer((Tab) modelElement);
     }
 }

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

@@ -1194,10 +1194,19 @@ public void drawBackground(DrawContext drawContext) {
     }
 
     /**
-     * {@inheritDoc}
+     * Gets a new instance of this class to be used as a next renderer, after this renderer is used, if
+     * {@link #layout(LayoutContext)} is called more than once.
+     *
+     * <p>
+     * If a renderer overflows to the next area, iText uses this method to create a renderer
+     * for the overflow part. So if one wants to extend {@link TableRenderer}, one should override
+     * this method: otherwise the default method will be used and thus the default rather than the custom
+     * renderer will be created.
+     * @return new renderer instance
      */
     @Override
     public IRenderer getNextRenderer() {
+        logWarningIfGetNextRendererNotOverridden(TableRenderer.class, this.getClass());
         TableRenderer nextTable = new TableRenderer();
         nextTable.modelElement = modelElement;
         return nextTable;