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 }