com.sun.syndication.propono.atom.server.AtomHandlerFactory Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of rome-propono Show documentation

The ROME Propono subproject is a Java class library that supports publishing protocols, specifically the Atom Publishing Protocol and the legacy MetaWeblog API. Propono includes an Atom client library, Atom server framework and a Blog client that supports both Atom protocol and the MetaWeblog API.

The newest version!

/*   
 * Copyright 2007 Sun Microsystems, Inc.
 * 
 * Licensed 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 com.sun.syndication.propono.atom.server;

import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;

/**
 * Defines a factory that enables the 
 * {@link com.sun.syndication.propono.atom.server.AtomServlet} to obtain an 
 * {@link com.sun.syndication.propono.atom.server.AtomHandler} that handles an Atom request.
 *
 * To create your own Atom protocol implementation you must sub-class this
 * class with your own factory that is capable of creating instances of your
 * {@link com.sun.syndication.propono.atom.server.AtomHandler} impementation.
 */
public abstract class AtomHandlerFactory {

    private static Log log =
            LogFactory.getFactory().getInstance(AtomHandlerFactory.class);
    
    private static final String DEFAULT_PROPERTY_NAME = 
        "com.sun.syndication.propono.atom.server.AtomHandlerFactory";
    
    private static final String FALLBACK_IMPL_NAME =
         "com.sun.syndication.propono.atom.server.impl.FileBasedAtomHandlerFactory";
            
    /*
     * Protected constructor to prevent instantiation.
     * Use {@link #newInstance()}.
     */
    protected AtomHandlerFactory() {
    }

    /**
     * Obtain a new instance of a AtomHandlerFactory. This static 
     * method creates a new factory instance. This method uses the following 
     * ordered lookup procedure to determine the AtomHandlerFactory 
     * implementation class to load:
     * 
     *    
     *       Use the com.sun.syndication.propono.atom.server.AtomHandlerFactory 
     *       system property.
     *    
     *    
     *       Use the properties file "/propono.properties" in the classpath. 
     *       This configuration file is in standard java.util.Properties 
     *       format and contains the fully qualified name of the implementation 
     *       class with the key being the system property defined above.
     *
     *       The propono.properties file is read only once by Propono and it's 
     *       values are then cached for future use.  If the file does not exist
     *       when the first attempt is made to read from it, no further attempts 
     *       are made to check for its existence.  It is not possible to change 
     *       the value of any property in propono.properties after it has been 
     *       read for the first time.
     *    
     *    
     *       If not available, to determine the classname. The Services API will look
     *       for a classname in the file: 
     *       META-INF/services/com.sun.syndication.AtomHandlerFactory
     *       in jars available to the runtime.
     *    
     *    
     *       Platform default AtomHandlerFactory instance.
     *    
     * 
     *
     * Once an application has obtained a reference to a AtomHandlerFactory 
     * it can use the factory to configure and obtain parser instances.
     *
     * @return New instance of a AtomHandlerFactory
     *
     * @throws FactoryConfigurationError if the implementation is not available 
     * or cannot be instantiated.
     */
    public static AtomHandlerFactory newInstance() {
        try {
            return (AtomHandlerFactory)
                FactoryFinder.find(DEFAULT_PROPERTY_NAME, FALLBACK_IMPL_NAME);
        } catch (FactoryFinder.ConfigurationError e) {
            log.error("ERROR: finding factory", e);
            throw new FactoryConfigurationError(e.getException(), e.getMessage());
        }
    }

    /**
     * Creates a new instance of a {@link com.sun.syndication.propono.atom.server.AtomHandler}
     * using the currently configured parameters.
     *
     * @return A new instance of a AtomHandler.
     *
     * @throws AtomConfigurationException if a AtomHandler cannot be created 
     * which satisfies the configuration requested.
     */
    public abstract AtomHandler newAtomHandler(
            HttpServletRequest req, HttpServletResponse res);
}