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 '<') into corresponding entities (such as
028         * <).
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 '<') into corresponding entities (such as <). 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    }