Pattern Replacement Utility #494

Support class that can handle the regex replace/restore operations for a
codec's encoding process.

Author: jeremiahjstacey

src/main/java/org/owasp/esapi/codecs/ref/EncodingPatternPreservation.java

@@ -0,0 +1,112 @@
+package org.owasp.esapi.codecs.ref;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
+/**
+ * String mutation utility which can be used to replace all occurrences of a
+ * defined regular expression with a marker string, and also restore the
+ * original string content.
+ *
+ */
+public class EncodingPatternPreservation {
+	/** Default replacement marker. */
+	private static final String REPLACEMENT_MARKER = EncodingPatternPreservation.class.getSimpleName();
+	/** Pattern that is used to identify which content should be replaced. */
+	private final Pattern noEncodeContent;
+	/** The Marker used to replace found Pattern references. */
+	private String replacementMarker = REPLACEMENT_MARKER;
+
+	/**
+	 * The ordered-list of elements that were replaced in the last call to
+	 * {@link #captureAndReplaceMatches(String)}, and that will be used to replace
+	 * the {@link #replacementMarker} on the next call to
+	 * {@link #restoreOriginalContent(String)}
+	 */
+	private final List<String> replacedContentList = new ArrayList<>();
+
+	/**
+	 * Constructor.
+	 * 
+	 * @param pattern Pattern identifying content being replaced.
+	 */
+	public EncodingPatternPreservation(Pattern pattern) {
+		noEncodeContent = pattern;
+	}
+
+	/**
+	 * Replaces each matching instance of this instance's Pattern with an
+	 * identifiable replacement marker. <br>
+	 * 
+	 * <br>
+	 * After the encoding process is complete, use
+	 * {@link #restoreOriginalContent(String)} to re-insert the original data.
+	 * 
+	 * @param input String to adjust
+	 * @return The adjusted String
+	 */
+	public String captureAndReplaceMatches(String input) {
+		if (!replacedContentList.isEmpty()) {
+			// This may seem odd, but this will prevent programmer error that would result
+			// in being unable to restore a previously tokenized String.
+			String message = "Previously captured state is still present in instance. Call PatternContentPreservation.reset() to clear out preserved state and to reuse the reference.";
+			throw new IllegalStateException(message);
+		}
+		String inputCpy = input;
+		Matcher matcher = noEncodeContent.matcher(input);
+
+		while (matcher.find()) {
+			int groups = matcher.groupCount();
+			for (int x = 0; x < groups; x++) {
+				String replaceContent = matcher.group(x);
+				replacedContentList.add(replaceContent);
+				inputCpy = inputCpy.replaceFirst(noEncodeContent.pattern(), replacementMarker);
+			}
+		}
+
+		return inputCpy;
+	}
+
+	/**
+	 * Replaces each instance of the {@link #replacementMarker} with the original
+	 * content, as captured by {@link #captureAndReplaceMatches(String)}
+	 * 
+	 * @param input String to restore.
+	 * @return String reference with all values replaced.
+	 */
+	public String restoreOriginalContent(String input) {
+		String result = input;
+		while (replacedContentList.size() > 0) {
+			String origValue = replacedContentList.remove(0);
+			result = result.replaceFirst(replacementMarker, origValue);
+		}
+
+		return result;
+
+	}
+
+	/**
+	 * Allows the marker used as a replacement to be altered.
+	 * 
+	 * @param marker String replacment to use for regex matches.
+	 */
+	public void setReplacementMarker(String marker) {
+		if (!replacedContentList.isEmpty()) {
+			// This may seem odd, but this will prevent programmer error that would result
+			// in being unable to restore a previously tokenized String.
+			String message = "Previously captured state is still present in instance. Call PatternContentPreservation.reset() to clear out preserved state and to alter the marker.";
+			throw new IllegalStateException(message);
+		}
+		this.replacementMarker = marker;
+	}
+
+	/**
+	 * Clears any stored replacement values out of the instance.
+	 */
+	public void reset() {
+		replacedContentList.clear();
+	}
+
+}

src/test/java/org/owasp/esapi/codecs/ref/EncodingPatternPreservationTest.java

@@ -0,0 +1,66 @@
+package org.owasp.esapi.codecs.ref;
+
+import java.util.regex.Pattern;
+
+import org.junit.Test;
+
+import static org.junit.Assert.*;
+
+public class EncodingPatternPreservationTest {
+	
+	@Test
+	public void testReplaceAndRestore() {
+		Pattern numberRegex = Pattern.compile("(ABC)");
+		EncodingPatternPreservation epp = new EncodingPatternPreservation(numberRegex);
+		String origStr = "12 ABC 34 DEF 56 G 7";
+		String replacedStr = epp.captureAndReplaceMatches(origStr);
+		
+		assertEquals("12 EncodingPatternPreservation 34 DEF 56 G 7", replacedStr);
+		
+		String restored = epp.restoreOriginalContent(replacedStr);
+		assertEquals(origStr, restored);
+	}
+	
+	@Test
+	public void testSetMarker() {
+		Pattern numberRegex = Pattern.compile("(ABC)");
+		EncodingPatternPreservation epp = new EncodingPatternPreservation(numberRegex);
+		epp.setReplacementMarker(EncodingPatternPreservationTest.class.getSimpleName());
+		
+		String origStr = "12 ABC 34 DEF 56 G 7";
+		String replacedStr = epp.captureAndReplaceMatches(origStr);
+		
+		assertEquals("12 EncodingPatternPreservationTest 34 DEF 56 G 7", replacedStr);
+		
+		String restored = epp.restoreOriginalContent(replacedStr);
+		assertEquals(origStr, restored);
+	}
+	
+	@Test (expected = IllegalStateException.class)
+	public void testSetMarkerExceptionNoReset() {
+		Pattern numberRegex = Pattern.compile("(ABC)");
+		EncodingPatternPreservation epp = new EncodingPatternPreservation(numberRegex);
+		String origStr = "12 ABC 34 DEF 56 G 7";
+		epp.captureAndReplaceMatches(origStr);
+		//This allows the + case to be illustrated
+		epp.reset();
+		
+		//And the exception case.
+		epp.captureAndReplaceMatches(origStr);
+		epp.setReplacementMarker(EncodingPatternPreservationTest.class.getSimpleName());
+	}
+	
+	@Test (expected = IllegalStateException.class)
+	public void testReplaceExceptionNoReset() {
+		Pattern numberRegex = Pattern.compile("(ABC)");
+		EncodingPatternPreservation epp = new EncodingPatternPreservation(numberRegex);
+		String origStr = "12 ABC 34 DEF 56 G 7";
+		epp.captureAndReplaceMatches(origStr);
+		//This allows the + case to be illustrated
+		epp.reset();
+		
+		//And the exception case.
+		epp.captureAndReplaceMatches(origStr);
+		epp.captureAndReplaceMatches(origStr);
+	}
+}