src/org/apache/xml/serialize/SerializerFactory.java

/*
 * 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 org.apache.xml.serialize;

import java.io.OutputStream;
import java.io.UnsupportedEncodingException;
import java.io.Writer;
import java.util.Hashtable;
import java.util.StringTokenizer;

/**
 * @deprecated This class was deprecated in Xerces 2.9.0. It is recommended 
 * that new applications use the DOM Level 3 LSSerializer or JAXP's Transformation 
 * API for XML (TrAX) for serializing XML and HTML. See the Xerces documentation for more 
 * information.
 * @version $Revision$ $Date$
 * @author <a href="mailto:Scott_Boag/CAM/Lotus@lotus.com">Scott Boag</a>
 * @author <a href="mailto:arkin@intalio.com">Assaf Arkin</a>
 */
@Deprecated
public abstract class SerializerFactory {

    /**
     * The system property for registering additional implementations of SerializerFactory.
     * <p>
     *     Multiple factories can be registered by using a delimiter between the values. Any of the following are supported:
     * </p>
     * <ul>
     *     <li><i>a single space</i></li>
     *     <li><strong>;</strong> semicolon</li>
     *     <li><strong>,</strong> comma</li>
     *     <li><strong>:</strong> colon</li>
     * </ul>
     */
    public static final String FactoriesProperty = "org.apache.xml.serialize.factories";

    private static Hashtable  _factories = new Hashtable();

    static
    {
        SerializerFactory factory;
        String            list;
        StringTokenizer   token;
        String            className;

        // The default factories are always registered first,
        // any factory specified in the properties file and supporting
        // the same method will override the default factory.
        factory =  new SerializerFactoryImpl( Method.XML );
        registerSerializerFactory( factory );
        factory =  new SerializerFactoryImpl( Method.HTML );
        registerSerializerFactory( factory );
        factory =  new SerializerFactoryImpl( Method.XHTML );
        registerSerializerFactory( factory );
        factory =  new SerializerFactoryImpl( Method.TEXT );
        registerSerializerFactory( factory );

        list = SecuritySupport.getSystemProperty( FactoriesProperty );
        if ( list != null ) {
            token = new StringTokenizer( list, " ;,:" );
            while ( token.hasMoreTokens() ) {
                className = token.nextToken();
                try {
                    factory = (SerializerFactory) ObjectFactory.newInstance( className,
                        SerializerFactory.class.getClassLoader(), true);
                    if ( _factories.containsKey( factory.getSupportedMethod() ) )
                        _factories.put( factory.getSupportedMethod(), factory );
                } catch ( Exception except ) { }
            }
        }
    }


    /**
     * Register a serializer factory, keyed by the given method string.
     * <p>Xerces registers default serializer factories for</p>
     * <ul>
     *     <li>{@link Method#XML}</li>
     *     <li>{@link Method#HTML}</li>
     *     <li>{@link Method#XHTML}</li>
     *     <li>{@link Method#TEXT}</li>
     * </ul>
     *
     * @param factory the serializer factory to be registered
     */
    public static void registerSerializerFactory( SerializerFactory factory )
    {
        String method;

        synchronized ( _factories ) {
            method = factory.getSupportedMethod();
            _factories.put( method, factory );
        }
    }


    /**
     * Retrieve a serializer factory, keyed by the given method string.
     * <p>Xerces registers default serializer factories for</p>
     * <ul>
     *     <li>{@link Method#XML}</li>
     *     <li>{@link Method#HTML}</li>
     *     <li>{@link Method#XHTML}</li>
     *     <li>{@link Method#TEXT}</li>
     * </ul>
     *
     * @param method the method string to retrieve the SerializerFactory by
     * @return the serializer factory registered with the given method string
     * @see Method
     */
    public static SerializerFactory getSerializerFactory( String method )
    {
        return (SerializerFactory) _factories.get( method );
    }


    /**
     * Returns the method supported by this factory and used to register
     * the factory. This call is required so factories can be added from
     * a properties file by knowing only the class name. This method is
     * protected, it is only required by this class but must be implemented
     * in derived classes.
     *
     * @return the method supported by this factory
     */
    protected abstract String getSupportedMethod();


    /**
     * Create a new serializer based on the {@link OutputFormat}.
     * If this method is used to create the serializer, the {@link
     * Serializer#setOutputByteStream} or {@link Serializer#setOutputCharStream}
     * methods must be called before serializing a document.
     *
     * @param format the output format to use
     * @return a new serializer for the given output format
     */
    public abstract Serializer makeSerializer(OutputFormat format);


    /**
     * Create a new serializer, based on the {@link OutputFormat} and
     * using the writer as the output character stream.  If this
     * method is used, the encoding property will be ignored.
     *
     * @param writer an output char stream that will be written to
     * @param format the output format to use
     * @return a new serializer for the given output format
     */
    public abstract Serializer makeSerializer( Writer writer,
                                               OutputFormat format );


    /**
     * Create a new serializer, based on the {@link OutputFormat} and using the
     * output stream and the encoding specified in the output format.
     *
     * @param output an output stream that will be written to
     * @param format the output format to use
     * @return a new serializer for the given output format
     * @throws UnsupportedEncodingException if the specified encoding is not supported
     */
    public abstract Serializer makeSerializer( OutputStream output,
                                               OutputFormat format )
        throws UnsupportedEncodingException;


}