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 '<') 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}