1 package org.apache.fulcrum.factory;
2
3 /*
4 * Licensed to the Apache Software Foundation (ASF) under one
5 * or more contributor license agreements. See the NOTICE file
6 * distributed with this work for additional information
7 * regarding copyright ownership. The ASF licenses this file
8 * to you under the Apache License, Version 2.0 (the
9 * "License"); you may not use this file except in compliance
10 * with the License. You may obtain a copy of the License at
11 *
12 * http://www.apache.org/licenses/LICENSE-2.0
13 *
14 * Unless required by applicable law or agreed to in writing,
15 * software distributed under the License is distributed on an
16 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17 * KIND, either express or implied. See the License for the
18 * specific language governing permissions and limitations
19 * under the License.
20 */
21
22 /**
23 * Factory is an interface for object factories. Object factories
24 * can be registered with the Factory Service to support customized
25 * functionality during instantiation of specific classes that
26 * the service itself cannot provide. Examples include
27 * instantiation of XML parsers and secure sockets requiring
28 * provider specific initializations before instantiation.
29 *
30 * @author <a href="mailto:ilkka.priha@simsoft.fi">Ilkka Priha</a>
31 * @author <a href="mailto:mcconnell@apache.org">Stephen McConnell</a>
32 * @version $Id$
33 */
34 public interface Factory<T>
35 {
36 /**
37 * Initializes the factory. This method is called by
38 * the Factory Service before the factory is used.
39 *
40 * @param className the name of the production class
41 * @throws FactoryException if initialization fails.
42 */
43 void init(String className) throws FactoryException;
44
45 /**
46 * Gets an instance of a class.
47 *
48 * @return the instance.
49 * @throws FactoryException if instantiation fails.
50 */
51 T getInstance() throws FactoryException;
52
53 /**
54 * Gets an instance of a class using a specified class loader.
55 *
56 * <p>Class loaders are supported only if the isLoaderSupported
57 * method returns true. Otherwise the loader parameter is ignored.
58 *
59 * @param loader the class loader.
60 * @return the instance.
61 * @throws FactoryException if instantiation fails.
62 */
63 T getInstance(ClassLoader loader) throws FactoryException;
64
65 /**
66 * Gets an instance of a named class.
67 * Parameters for its constructor are given as an array of objects,
68 * primitive types must be wrapped with a corresponding class.
69 *
70 * @param params an array containing the parameters of the constructor.
71 * @param signature an array containing the signature of the constructor.
72 * @return the instance.
73 * @throws FactoryException if instantiation fails.
74 */
75 T getInstance(Object[] params, String[] signature)
76 throws FactoryException;
77
78 /**
79 * Gets an instance of a named class using a specified class loader.
80 * Parameters for its constructor are given as an array of objects,
81 * primitive types must be wrapped with a corresponding class.
82 *
83 * <p>Class loaders are supported only if the isLoaderSupported
84 * method returns true. Otherwise the loader parameter is ignored.
85 *
86 * @param loader the class loader.
87 * @param params an array containing the parameters of the constructor.
88 * @param signature an array containing the signature of the constructor.
89 * @return the instance.
90 * @throws FactoryException if instantiation fails.
91 */
92 T getInstance(ClassLoader loader, Object[] params, String[] signature)
93 throws FactoryException;
94
95 /**
96 * Tests if this object factory supports specified class loaders.
97 *
98 * @return true if class loaders are supported, false otherwise.
99 */
100 boolean isLoaderSupported();
101 }