com.topologi.diffx.xml.esc.XMLEscape Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of docx4j Show documentation

docx4j is a library which helps you to work with the Office Open XML file format as used in docx documents, pptx presentations, and xlsx spreadsheets.

There is a newer version: 6.1.2

Show newest version

/*
 * This file is part of the DiffX library.
 *
 * For licensing information please see the file license.txt included in the release.
 * A copy of this licence can also be found at
 *   http://www.opensource.org/licenses/artistic-license-2.0.php
 */
package com.topologi.diffx.xml.esc;

/**
 * An interface to escape XML character data.
 * 
 * This interface assumes that the values to be escapes do not orignate from
 * XML text, in order words, there should not be already any entity or markup
 * in the document. If it is the case the methods in this class should also
 * escapes them. Thus "&amp;" would be represented as "&amp;amp;".
 * 
 * 
Also the method will not try to escape characters that cannot be escaped.
 * 
 * 
This interface is based on the paragraph 2.4 of the XML 1.0 Specifications.
 *
 * @author  Christophe Lauret
 * @version 7 March 2005
 */
public interface XMLEscape {

  /**
   * Returns a well-formed attribute value.
   * 
   * 
This method must replace any character in the specified
   * value by the corresponding numeric character reference or the
   * predefined XML general entities, if the character is not allowed
   * or not in the encoding range.
   * 
   * 
Attribute values must not contain '&' or '<. Quotes
   * and apostrophes must also be escaped by "&quot;" and
   * "&apos;" respectively.
   *
   * @param ch  The value that needs to be attribute-escaped.
   * @param off The start (offset) of the characters.
   * @param len The length of characters to.
   * 
   * @return A well-formed value for the attribute.
   */
  String toAttributeValue(char[] ch, int off, int len);

  /**
   * Returns a well-formed attribute value.
   * 
   * 
Method provided for convenience, using the same specifications as
   * {@link #toAttributeValue(char[], int, int)}.
   *
   * 
This method should return null if the given
   * value is null.
   * 
   * @param value The value that needs to be attribute-escaped.
   * 
   * @return A well-formed value for the attribute.
   */
  String toAttributeValue(String value);

  /**
   * Returns a well-formed text value for the element.
   *
   * 
This method must replace any character in the specified
   * value by the corresponding numeric character reference or the
   * predefined XML general entities, if the character is not allowed
   * or not in the encoding range.
   * 
   * 
The text of an element must not contain '&' or '<.
   * 
   * @param ch  The value that needs to be attribute-escaped.
   * @param off The start (offset) of the characters.
   * @param len The length of characters to.
   * 
   * @return A well-formed value for the text node.
   */
  String toElementText(char[] ch, int off, int len);

  /**
   * Returns a well-formed text value for the element.
   *
   * 
Method provided for convenience, using the same specifications as
   * {@link #toElementText(char[], int, int)}.
   * 
   * This method should return null if the given
   * value is null.
   * 
   * @param value The value that needs to be text-escaped.
   * 
   * @return A well-formed value for the text node.
   */
  String toElementText(String value);

  /**
   * Returns the encoding used by the implementing class.
   * 
   * @return The encoding used by the implementing class.
   */
  String getEncoding();

}