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 * The Factory Service instantiates objects using either default
027 * class loaders or a specified one. Whether specified class
028 * loaders are supported for a class depends on implementation
029 * and can be tested with the isLoaderSupported method.
030 *
031 * @author <a href="mailto:epugh@upstate.com">Eric Pugh</a>
032 * @author <a href="mailto:ilkka.priha@simsoft.fi">Ilkka Priha</a>
033 * @version $Id: FactoryService.java 535465 2007-05-05 06:58:06Z tv $
034 */
035 public interface FactoryService
036 {
037 /**
038 * The key under which this component is known by an avalon container.
039 */
040 String ROLE = FactoryService.class.getName();
041
042
043 /**
044 * Gets an instance of a class.
045 *
046 * @param clazz the name of the class.
047 * @return the instance.
048 * @throws ServiceException if instantiation fails.
049 */
050 public Object getInstance(Class clazz)
051 throws FactoryException;
052
053 /**
054 * Gets an instance of a named class.
055 *
056 * @param className the name of the class.
057 * @return the instance.
058 * @throws ServiceException if instantiation fails.
059 */
060 public Object getInstance(String className)
061 throws FactoryException;
062
063 /**
064 * Gets an instance of a named class using a specified class loader.
065 *
066 * <p>Class loaders are supported only if the isLoaderSupported
067 * method returns true. Otherwise the loader parameter is ignored.
068 *
069 * @param className the name of the class.
070 * @param loader the class loader.
071 * @return the instance.
072 * @throws ServiceException if instantiation fails.
073 */
074 public Object getInstance(String className,
075 ClassLoader loader)
076 throws FactoryException;
077
078 /**
079 * Gets an instance of a named class.
080 * Parameters for its constructor are given as an array of objects,
081 * primitive types must be wrapped with a corresponding class.
082 *
083 * @param className the name of the class.
084 * @param params an array containing the parameters of the constructor.
085 * @param signature an array containing the signature of the constructor.
086 * @return the instance.
087 * @throws ServiceException if instantiation fails.
088 */
089 public Object getInstance(String className,
090 Object[] params,
091 String[] signature)
092 throws FactoryException;
093
094 /**
095 * Gets an instance of a named class using a specified class loader.
096 * Parameters for its constructor are given as an array of objects,
097 * primitive types must be wrapped with a corresponding class.
098 *
099 * <p>Class loaders are supported only if the isLoaderSupported
100 * method returns true. Otherwise the loader parameter is ignored.
101 *
102 * @param className the name of the class.
103 * @param loader the class loader.
104 * @param params an array containing the parameters of the constructor.
105 * @param signature an array containing the signature of the constructor.
106 * @return the instance.
107 * @throws ServiceException if instantiation fails.
108 */
109 public Object getInstance(String className,
110 ClassLoader loader,
111 Object[] params,
112 String[] signature)
113 throws FactoryException;
114
115 /**
116 * Tests if specified class loaders are supported for a named class.
117 *
118 * @param className the name of the class.
119 * @return true if class loaders are supported, false otherwise.
120 * @throws ServiceException if test fails.
121 */
122 public boolean isLoaderSupported(String className)
123 throws FactoryException;
124
125 /**
126 * Gets the signature classes for parameters of a method of a class.
127 *
128 * @param clazz the class.
129 * @param params an array containing the parameters of the method.
130 * @param signature an array containing the signature of the method.
131 * @return an array of signature classes. Note that in some cases
132 * objects in the parameter array can be switched to the context
133 * of a different class loader.
134 * @throws ClassNotFoundException if any of the classes is not found.
135 */
136 Class[] getSignature(Class clazz,
137 Object params[],
138 String signature[])
139 throws ClassNotFoundException;
140 }