/*
 * The contents of this file are subject to the Mozilla Public License Version 1.1
 * (the "License"); you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at <http://www.mozilla.org/MPL/>.
 * 
 * Software distributed under the License is distributed on an "AS IS" basis, WITHOUT
 * WARRANTY OF ANY KIND, either express or implied. See the License for the specific
 * language governing rights and limitations under the License.
 * 
 * The Original Code is the Venice Web Communities System.
 * 
 * The Initial Developer of the Original Code is Eric J. Bowersox <erbo@silcom.com>,
 * for Silverwrist Design Studios.  Portions created by Eric J. Bowersox are
 * Copyright (C) 2003 Eric J. Bowersox/Silverwrist Design Studios.  All Rights Reserved.
 * 
 * Contributor(s): 
 */
package com.silverwrist.dynamo.iface;

import com.silverwrist.dynamo.htmlcheck.MarkupData;
import com.silverwrist.dynamo.util.QualifiedNameKey;

/**
 * An interface implemented by HTML Checker <EM>rewriters</EM>, which rewrite specific sequences of text in the HTML
 * Checker's input.
 *
 * @author Eric J. Bowersox &lt;erbo@silcom.com&gt;
 * @version X
 */
public interface HTMLRewriter
{
  /**
   * Returns the name of this rewriter.  If this returns a value other than <CODE>null</CODE>, the HTML Checker will
   * create a counter with this name, which will count the number of times the rewriter chooses to rewrite the text.
   *
   * @return The namespace and name of this rewriter as a
   *         {@link com.silverwrist.dynamo.util.QualifiedNameKey QualifiedNameKey}, or <CODE>null</CODE>.
   */
  public QualifiedNameKey getName();

  /**
   * Determines whether to rewrite the specified text, and rewrites it if necessary.  The
   * {@link com.silverwrist.dynamo.htmlcheck.MarkupData MarkupData} object provides for beginning and ending markup
   * and text surrounding the text in question.
   *
   * @param data The text to be checked and possibly rewritten.
   * @param prefix A string to be used as a prefix for the result; may be <CODE>null</CODE>.
   * @param suffix A string to be used as a suffix for the result; may be <CODE>null</CODE>.
   * @param site Provides an interface for the rewriter to interact with the HTML Checker's context and attributes.
   * @return <CODE>null</CODE> if the text should not be rewritten, or a
   *         {@link com.silverwrist.dynamo.htmlcheck.MarkupData MarkupData} object containing the rewritten text.
   */
  public MarkupData rewrite(String data, String prefix, String suffix, HTMLRewriterSite site);

} // end interface HTMLRewriter