001    package org.apache.fulcrum.factory;
002    
003    
004    /*
005     * Licensed to the Apache Software Foundation (ASF) under one
006     * or more contributor license agreements.  See the NOTICE file
007     * distributed with this work for additional information
008     * regarding copyright ownership.  The ASF licenses this file
009     * to you under the Apache License, Version 2.0 (the
010     * "License"); you may not use this file except in compliance
011     * with the License.  You may obtain a copy of the License at
012     *
013     *   http://www.apache.org/licenses/LICENSE-2.0
014     *
015     * Unless required by applicable law or agreed to in writing,
016     * software distributed under the License is distributed on an
017     * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
018     * KIND, either express or implied.  See the License for the
019     * specific language governing permissions and limitations
020     * under the License.
021     */
022    
023    
024    
025    /**
026     * Factory is an interface for object factories. Object factories
027     * can be registered with the Factory Service to support customized
028     * functionality during instantiation of specific classes that
029     * the service itself cannot provide. Examples include
030     * instantiation of XML parsers and secure sockets requiring
031     * provider specific initializations before instantiation.
032     *
033     * @author <a href="mailto:ilkka.priha@simsoft.fi">Ilkka Priha</a>
034     * @author <a href="mailto:mcconnell@apache.org">Stephen McConnell</a>
035     * @version $Id: Factory.java 535465 2007-05-05 06:58:06Z tv $
036     */
037    public interface Factory
038    {
039        /**
040         * Initializes the factory. This method is called by
041         * the Factory Service before the factory is used.
042         *
043         * @param className the name of the production class
044         * @throws FactoryException if initialization fails.
045         */
046        public void init(String className)
047            throws FactoryException;
048    
049        /**
050         * Gets an instance of a class.
051         *
052         * @return the instance.
053         * @throws FactoryException if instantiation fails.
054         */
055        public Object getInstance()
056            throws FactoryException;
057    
058        /**
059         * Gets an instance of a class using a specified class loader.
060         *
061         * <p>Class loaders are supported only if the isLoaderSupported
062         * method returns true. Otherwise the loader parameter is ignored.
063         *
064         * @param loader the class loader.
065         * @return the instance.
066         * @throws FactoryException if instantiation fails.
067         */
068        public Object getInstance(ClassLoader loader)
069            throws FactoryException;
070    
071        /**
072         * Gets an instance of a named class.
073         * Parameters for its constructor are given as an array of objects,
074         * primitive types must be wrapped with a corresponding class.
075         *
076         * @param params an array containing the parameters of the constructor.
077         * @param signature an array containing the signature of the constructor.
078         * @return the instance.
079         * @throws FactoryException if instantiation fails.
080         */
081        public Object getInstance(Object[] params,
082                                  String[] signature)
083            throws FactoryException;
084    
085        /**
086         * Gets an instance of a named class using a specified class loader.
087         * Parameters for its constructor are given as an array of objects,
088         * primitive types must be wrapped with a corresponding class.
089         *
090         * <p>Class loaders are supported only if the isLoaderSupported
091         * method returns true. Otherwise the loader parameter is ignored.
092         *
093         * @param loader the class loader.
094         * @param params an array containing the parameters of the constructor.
095         * @param signature an array containing the signature of the constructor.
096         * @return the instance.
097         * @throws FactoryException if instantiation fails.
098         */
099        public Object getInstance(ClassLoader loader,
100                                  Object[] params,
101                                  String[] signature)
102            throws FactoryException;
103    
104        /**
105         * Tests if this object factory supports specified class loaders.
106         *
107         * @return true if class loaders are supported, false otherwise.
108         */
109        public boolean isLoaderSupported();
110    }