move functionality from pdfAutoSweep to kernel. RegexBasedLocationExtractionStrategy offers users the possibility of defining a regular expression and having all locations where it occurs returned to them

Author: joris.schellekens

kernel/src/main/java/com/itextpdf/kernel/pdf/canvas/parser/listener/CharacterRenderInfo.java

@@ -0,0 +1,89 @@
+package com.itextpdf.kernel.pdf.canvas.parser.listener;
+
+import com.itextpdf.kernel.geom.LineSegment;
+import com.itextpdf.kernel.geom.Rectangle;
+import com.itextpdf.kernel.pdf.canvas.parser.data.TextRenderInfo;
+
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * This class represents a single character and its bounding box
+ */
+public class CharacterRenderInfo extends LocationTextExtractionStrategy.TextChunk {
+
+    private Rectangle boundingBox;
+
+    /**
+     * This method converts a List<CharacterRenderInfo>
+     * The datastructure that gets returned contains both the plaintext,
+     * as well as the mapping of indices (from the list to the string).
+     * These indices can differ; if there is sufficient spacing between two CharacterRenderInfo
+     * objects, this algorithm will decide to insert space. The inserted space will cause
+     * the indices to differ by at least 1.
+     *
+     * @param cris
+     * @return
+     */
+    static StringConversionInfo mapString(List<CharacterRenderInfo> cris) {
+        Map<Integer, Integer> indexMap = new HashMap<>();
+        StringBuilder sb = new StringBuilder();
+        CharacterRenderInfo lastChunk = null;
+        for (int i = 0; i < cris.size(); i++) {
+            CharacterRenderInfo chunk = cris.get(i);
+            if (lastChunk == null) {
+                indexMap.put(sb.length(), i);
+                sb.append(chunk.getText());
+            } else {
+                if (chunk.sameLine(lastChunk)) {
+                    // we only insert a blank space if the trailing character of the previous string wasn't a space, and the leading character of the current string isn't a space
+                    if (chunk.getLocation().isAtWordBoundary(lastChunk.getLocation()) && !chunk.getText().startsWith(" ") && !chunk.getText().endsWith(" ")) {
+                        sb.append(' ');
+                    }
+                    indexMap.put(sb.length(), i);
+                    sb.append(chunk.getText());
+                } else {
+                    indexMap.put(sb.length(), i);
+                    sb.append(chunk.getText());
+                }
+            }
+            lastChunk = chunk;
+        }
+        CharacterRenderInfo.StringConversionInfo ret = new StringConversionInfo();
+        ret.indexMap = indexMap;
+        ret.text = sb.toString();
+        return ret;
+    }
+
+    public CharacterRenderInfo(TextRenderInfo tri) {
+        super(tri == null ? "" : tri.getText(), tri == null ? null : getLocation(tri));
+        if (tri == null)
+            throw new IllegalArgumentException("TextRenderInfo argument is not nullable.");
+        if (tri.getText().length() != 1)
+            throw new IllegalArgumentException("CharacterRenderInfo objects represent a single character. They should not be made from TextRenderInfo objects containing more than a single character of text.");
+
+        // determine bounding box
+        float x0 = tri.getDescentLine().getStartPoint().get(0);
+        float y0 = tri.getDescentLine().getStartPoint().get(1);
+        float h = tri.getAscentLine().getStartPoint().get(1) - tri.getDescentLine().getStartPoint().get(1);
+        float w = Math.abs(tri.getBaseline().getStartPoint().get(0) - tri.getBaseline().getEndPoint().get(0));
+        this.boundingBox = new Rectangle(x0, y0, w, h);
+    }
+
+    public Rectangle getBoundingBox() {
+        return boundingBox;
+    }
+
+    private static LocationTextExtractionStrategy.ITextChunkLocation getLocation(TextRenderInfo tri) {
+        LineSegment baseline = tri.getBaseline();
+        return new LocationTextExtractionStrategy.TextChunkLocationDefaultImp(baseline.getStartPoint(),
+                baseline.getEndPoint(),
+                tri.getSingleSpaceWidth());
+    }
+
+    static class StringConversionInfo {
+        Map<Integer, Integer> indexMap;
+        String text;
+    }
+}

kernel/src/main/java/com/itextpdf/kernel/pdf/canvas/parser/listener/DefaultPdfTextLocation.java

@@ -0,0 +1,49 @@
+package com.itextpdf.kernel.pdf.canvas.parser.listener;
+
+import com.itextpdf.kernel.geom.Rectangle;
+
+/**
+ * This class acts as a default implementation of IPdfTextLocation
+ */
+public class DefaultPdfTextLocation implements IPdfTextLocation {
+
+    private int pageNr;
+    private Rectangle rectangle;
+    private String text;
+
+    public DefaultPdfTextLocation(int pageNr, Rectangle rect, String text) {
+        this.pageNr = pageNr;
+        this.rectangle = rect;
+        this.text = text;
+    }
+
+    @Override
+    public Rectangle getRectangle() {
+        return rectangle;
+    }
+
+    public DefaultPdfTextLocation setRectangle(Rectangle rectangle) {
+        this.rectangle = rectangle;
+        return this;
+    }
+
+    @Override
+    public String getText() {
+        return text;
+    }
+
+    public DefaultPdfTextLocation setText(String text) {
+        this.text = text;
+        return this;
+    }
+
+    @Override
+    public int getPageNumber() {
+        return pageNr;
+    }
+
+    public DefaultPdfTextLocation setPageNr(int pageNr) {
+        this.pageNr = pageNr;
+        return this;
+    }
+}

kernel/src/main/java/com/itextpdf/kernel/pdf/canvas/parser/listener/ILocationExtractionStrategy.java

@@ -0,0 +1,20 @@
+package com.itextpdf.kernel.pdf.canvas.parser.listener;
+
+import com.itextpdf.kernel.geom.Rectangle;
+import com.itextpdf.kernel.pdf.canvas.parser.filter.IEventFilter;
+
+import java.util.Collection;
+
+/**
+ * This is a special interface for {@link IEventFilter} that returns a collection of rectangles as result of its work.
+ */
+public interface ILocationExtractionStrategy extends IEventListener {
+
+    /**
+     * Returns the rectangles that have been processed so far.
+     *
+     * @return {@link Collection<IPdfTextLocation>} instance with the current resultant IPdfTextLocations
+     */
+    Collection<IPdfTextLocation> getResultantLocations();
+
+}

kernel/src/main/java/com/itextpdf/kernel/pdf/canvas/parser/listener/IPdfTextLocation.java

@@ -0,0 +1,32 @@
+package com.itextpdf.kernel.pdf.canvas.parser.listener;
+
+import com.itextpdf.kernel.geom.Rectangle;
+
+/**
+ * Instances of this interface represent a piece of text,
+ * somewhere on a page in a pdf document.
+ */
+public interface IPdfTextLocation {
+
+    /**
+     * Get the visual rectangle in which the text is located
+     *
+     * @return
+     */
+    Rectangle getRectangle();
+
+    /**
+     * Get the text
+     *
+     * @return
+     */
+    String getText();
+
+    /**
+     * Get the page number of the page on which the text is located
+     *
+     * @return the page number, or 0 if no page number was set
+     */
+    int getPageNumber();
+
+}

kernel/src/main/java/com/itextpdf/kernel/pdf/canvas/parser/listener/ITextExtractionStrategy.java

@@ -52,6 +52,7 @@ public interface ITextExtractionStrategy extends IEventListener {
 
     /**
      * Returns the text that has been processed so far.
+     *
      * @return {@link String} instance with the current resultant text
      */
     String getResultantText();

kernel/src/main/java/com/itextpdf/kernel/pdf/canvas/parser/listener/RegexBasedLocationExtractionStrategy.java

@@ -0,0 +1,138 @@
+package com.itextpdf.kernel.pdf.canvas.parser.listener;
+
+import com.itextpdf.kernel.geom.Rectangle;
+import com.itextpdf.kernel.pdf.canvas.parser.EventType;
+import com.itextpdf.kernel.pdf.canvas.parser.data.IEventData;
+import com.itextpdf.kernel.pdf.canvas.parser.data.TextRenderInfo;
+
+import javax.xml.soap.Text;
+import java.util.*;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
+/**
+ * This class is designed to search for the occurrences of a regular expression and return the resultant rectangles.
+ */
+public class RegexBasedLocationExtractionStrategy implements ILocationExtractionStrategy {
+
+    private Pattern pattern;
+    private List<CharacterRenderInfo> parseResult = new ArrayList<>();
+
+    public RegexBasedLocationExtractionStrategy(String regex) {
+        this.pattern = Pattern.compile(regex);
+    }
+
+    public RegexBasedLocationExtractionStrategy(Pattern pattern) {
+        this.pattern = pattern;
+    }
+
+    @Override
+    public Collection<IPdfTextLocation> getResultantLocations() {
+
+        // align characters in "logical" order
+        Collections.sort(parseResult);
+
+        // process parse results
+        List<IPdfTextLocation> retval = new ArrayList<>();
+
+        CharacterRenderInfo.StringConversionInfo txt = CharacterRenderInfo.mapString(parseResult);
+
+        Matcher mat = pattern.matcher(txt.text);
+        while (mat.find()) {
+            int startIndex = txt.indexMap.get(mat.start());
+            int endIndex = txt.indexMap.get(mat.end());
+            for (Rectangle r : toRectangles(parseResult.subList(startIndex, endIndex))) {
+                retval.add(new DefaultPdfTextLocation(0, r, mat.group(0)));
+            }
+        }
+
+        /* sort
+         * even though the return type is Collection<Rectangle>, we apply a sorting algorithm here
+         * This is to ensure that tests that use this functionality (for instance to generate pdf with
+         * areas of interest highlighted) will not break when compared.
+         */
+        java.util.Collections.sort(retval, new Comparator<IPdfTextLocation>() {
+            @Override
+            public int compare(IPdfTextLocation l1, IPdfTextLocation l2) {
+                Rectangle o1 = l1.getRectangle();
+                Rectangle o2 = l2.getRectangle();
+                if (o1.getY() == o2.getY()) {
+                    return o1.getX() == o2.getX() ? 0 : (o1.getX() < o2.getX() ? -1 : 1);
+                } else {
+                    return o1.getY() < o2.getY() ? -1 : 1;
+                }
+            }
+        });
+
+        return retval;
+    }
+
+    @Override
+    public void eventOccurred(IEventData data, EventType type) {
+        if (data instanceof TextRenderInfo) {
+            parseResult.addAll(toCRI((TextRenderInfo) data));
+        }
+    }
+
+    @Override
+    public Set<EventType> getSupportedEvents() {
+        return null;
+    }
+
+    /**
+     * Convert {@code TextRenderInfo} to {@code CharacterRenderInfo}
+     * This method is public and not final so that custom implementations can choose to override it.
+     * Other implementations of {@code CharacterRenderInfo} may choose to store different properties than
+     * merely the {@code Rectangle} describing the bounding box. E.g. a custom implementation might choose to
+     * store {@code Color} information as well, to better match the content surrounding the redaction {@code Rectangle}.
+     *
+     * @param tri
+     * @return
+     */
+    protected List<CharacterRenderInfo> toCRI(TextRenderInfo tri) {
+        List<CharacterRenderInfo> cris = new ArrayList<>();
+        for (TextRenderInfo subTri : tri.getCharacterRenderInfos()) {
+            cris.add(new CharacterRenderInfo(subTri));
+        }
+        return cris;
+    }
+
+    /**
+     * Converts {@code CharacterRenderInfo} objects to {@code Rectangles}
+     * This method is protected and not final so that custom implementations can choose to override it.
+     * E.g. other implementations may choose to add padding/margin to the Rectangles.
+     * This method also offers a convenient access point to the mapping of {@code CharacterRenderInfo} to {@code Rectangle}.
+     * This mapping enables (custom implementations) to match color of text in redacted Rectangles,
+     * or match color of background, by the mere virtue of offering access to the {@code CharacterRenderInfo} objects
+     * that generated the {@code Rectangle}.
+     *
+     * @param cris
+     * @return
+     */
+    protected List<Rectangle> toRectangles(List<CharacterRenderInfo> cris) {
+        List<Rectangle> retval = new ArrayList<>();
+        if (cris.isEmpty())
+            return retval;
+
+        int prev = 0;
+        int curr = 0;
+        while (curr < cris.size()) {
+            while (curr < cris.size() && cris.get(curr).sameLine(cris.get(prev))) {
+                curr++;
+            }
+            float x = cris.get(prev).getBoundingBox().getX();
+            float y = cris.get(prev).getBoundingBox().getY();
+            float w = cris.get(curr - 1).getBoundingBox().getX() - cris.get(prev).getBoundingBox().getX() + cris.get(curr - 1).getBoundingBox().getWidth();
+            float h = 0f;
+            for (CharacterRenderInfo cri : cris.subList(prev, curr)) {
+                h = Math.max(h, cri.getBoundingBox().getHeight());
+            }
+            retval.add(new Rectangle(x, y, w, h));
+            prev = curr;
+        }
+
+        // return
+        return retval;
+    }
+
+}