    001// Copyright 2006, 2007, 2008, 2009 The Apache Software Foundation
    002//
    003// Licensed under the Apache License, Version 2.0 (the "License");
    004// you may not use this file except in compliance with the License.
    005// You may obtain a copy of the License at
    006//
    007//     http://www.apache.org/licenses/LICENSE-2.0
    008//
    009// Unless required by applicable law or agreed to in writing, software
    010// distributed under the License is distributed on an "AS IS" BASIS,
    011// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    012// See the License for the specific language governing permissions and
    013// limitations under the License.
    014
    015package org.apache.tapestry5.dom;
    016
    017/**
    018 * Used by a the DOM to determine how to produce markup. Delegates details about converted entities and some formatting
    019 * details.  This exists to handle the differences between traditional HTML output (which is SGML based, meaning there
    020 * can be elements that are valid without a close tag) and "modern" XML, such as XHTML.  Generally speaking, for XHTML
    021 * it is vital that a !DOCTYPE be included in the rendered response, or the browser will be unable to display the result
    022 * properly.
    023 */
    024public interface MarkupModel
    025{
    026    /**
    027     * Encodes the characters, converting control characters (such as '&lt;') into corresponding entities (such as
    028     * &amp;lt;).
    029     *
    030     * @param content to be filtered
    031     * @return the filtered content
    032     */
    033    String encode(String content);
    034
    035    /**
    036     * Encodes the characters into the buffer for use in a quoted value (that is, an attribute value), converting
    037     * control characters (such as '&lt;') into corresponding entities (such as &amp;lt;). In addition, double quotes
    038     * must be quoted or otherwise escaped.
    039     *
    040     * @param content to be filtered
    041     * @param buffer  to receive the filtered content
    042     */
    043    void encodeQuoted(String content, StringBuilder buffer);
    044
    045    /**
    046     * For a given element, determines how the end tag for the element should be rendered.
    047     */
    048    EndTagStyle getEndTagStyle(String element);
    049
    050    /**
    051     * Returns true if the document markup is XML, which is used to determine the need for an XML declaration at the
    052     * start of the document, and whether CDATA sections are supported.
    053     *
    054     * @return true for XML output, false for HTML output
    055     */
    056    boolean isXML();
    057
    058    /**
    059     * What character is used when generating quotes around attribute values? This will be either a single or double
    060     * quote.
    061     *
    062     * @return single (') or double (") quote
    063     * @since 5.1.0.0
    064     */
    065    char getAttributeQuote();
    066}