/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (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.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */
package freemarker.core;

import freemarker.template.Configuration;
import freemarker.template.utility.ClassUtil;
import freemarker.template.utility.StringUtil;

Represents an output format. If you need auto-escaping, see its subclass, MarkupOutputFormat. 
See Also:
Configuration.setOutputFormat(OutputFormat)
Configuration.setRegisteredCustomOutputFormats(Collection<? extends OutputFormat>)
MarkupOutputFormat
Since:
2.3.24/**
 * Represents an output format. If you need auto-escaping, see its subclass, {@link MarkupOutputFormat}. 
 * 
 * @see Configuration#setOutputFormat(OutputFormat)
 * @see Configuration#setRegisteredCustomOutputFormats(java.util.Collection)
 * @see MarkupOutputFormat
 * 
 * @since 2.3.24
 */
public abstract class OutputFormat {

    
The short name used to refer to this format (like in the #ftl header). /**
     * The short name used to refer to this format (like in the {@code #ftl} header).
     */
    public abstract String getName();
    
    
Returns the MIME type of the output format. This might comes handy when generating a HTTP response. null null if this output format doesn't clearly corresponds to a specific MIME type. /**
     * Returns the MIME type of the output format. This might comes handy when generating a HTTP response. {@code null}
     * {@code null} if this output format doesn't clearly corresponds to a specific MIME type.
     */
    public abstract String getMimeType();

    
Tells if this output format allows inserting TemplateMarkupOutputModel-s of another output formats into it. If true, the foreign TemplateMarkupOutputModel will be inserted into the output as is (like if the surrounding output format was the same). This is usually a bad idea to allow, as such an event could indicate application bugs. If this method returns false (recommended), then FreeMarker will try to assimilate the inserted value by converting its format to this format, which will currently (2.3.24) cause exception, unless the inserted value is made by escaping plain text and the target format is non-escaping, in which case format conversion is trivially possible. (It's not impossible that conversions will be extended beyond this, if there will be demand for that.) 
 true value is used by UndefinedOutputFormat. /**
     * Tells if this output format allows inserting {@link TemplateMarkupOutputModel}-s of another output formats into
     * it. If {@code true}, the foreign {@link TemplateMarkupOutputModel} will be inserted into the output as is (like
     * if the surrounding output format was the same). This is usually a bad idea to allow, as such an event could
     * indicate application bugs. If this method returns {@code false} (recommended), then FreeMarker will try to
     * assimilate the inserted value by converting its format to this format, which will currently (2.3.24) cause
     * exception, unless the inserted value is made by escaping plain text and the target format is non-escaping, in
     * which case format conversion is trivially possible. (It's not impossible that conversions will be extended beyond
     * this, if there will be demand for that.)
     * 
     * <p>
     * {@code true} value is used by {@link UndefinedOutputFormat}.
     */
    public abstract boolean isOutputFormatMixingAllowed();

    
Returns the short description of this format, to be used in error messages. Override toStringExtraProperties() to customize this. /**
     * Returns the short description of this format, to be used in error messages.
     * Override {@link #toStringExtraProperties()} to customize this.
     */
    @Override
    public final String toString() {
        String extras = toStringExtraProperties();
        return getName() + "("
                + "mimeType=" + StringUtil.jQuote(getMimeType()) + ", "
                + "class=" + ClassUtil.getShortClassNameOfObject(this, true)
                + (extras.length() != 0 ? ", " : "") + extras
                + ")";
    }
    
    
Should be like "foo=\"something\", bar=123"; this will be inserted inside the parentheses in toString(). Shouldn't return null; should return "" if there are no extra properties. /**
     * Should be like {@code "foo=\"something\", bar=123"}; this will be inserted inside the parentheses in
     * {@link #toString()}. Shouldn't return {@code null}; should return {@code ""} if there are no extra properties.  
     */
    protected String toStringExtraProperties() {
        return "";
    }

}