    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
    015    package 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     */
    024    public 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    }