View Javadoc

1   package org.apache.turbine.services.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  import org.apache.turbine.services.Service;
23  import org.apache.turbine.util.TurbineException;
24  
25  /***
26   * The Factory Service instantiates objects using either default
27   * class loaders or a specified one. Whether specified class
28   * loaders are supported for a class depends on implementation
29   * and can be tested with the isLoaderSupported method.
30   *
31   * @author <a href="mailto:ilkka.priha@simsoft.fi">Ilkka Priha</a>
32   * @version $Id: FactoryService.java 534527 2007-05-02 16:10:59Z tv $
33   */
34  public interface FactoryService
35          extends Service
36  {
37      /***
38       * The key under which this service is stored in TurbineServices.
39       */
40      String SERVICE_NAME = "FactoryService";
41  
42      /***
43       * Gets an instance of a named class.
44       *
45       * @param className the name of the class.
46       * @return the instance.
47       * @throws TurbineException if instantiation fails.
48       */
49      Object getInstance(String className)
50              throws TurbineException;
51  
52      /***
53       * Gets an instance of a named class using a specified class loader.
54       *
55       * <p>Class loaders are supported only if the isLoaderSupported
56       * method returns true. Otherwise the loader parameter is ignored.
57       *
58       * @param className the name of the class.
59       * @param loader the class loader.
60       * @return the instance.
61       * @throws TurbineException if instantiation fails.
62       */
63      Object getInstance(String className,
64              ClassLoader loader)
65              throws TurbineException;
66  
67      /***
68       * Gets an instance of a named class.
69       * Parameters for its constructor are given as an array of objects,
70       * primitive types must be wrapped with a corresponding class.
71       *
72       * @param className the name of the class.
73       * @param params an array containing the parameters of the constructor.
74       * @param signature an array containing the signature of the constructor.
75       * @return the instance.
76       * @throws TurbineException if instantiation fails.
77       */
78      Object getInstance(String className,
79              Object[] params,
80              String[] signature)
81              throws TurbineException;
82  
83      /***
84       * Gets an instance of a named class using a specified class loader.
85       * Parameters for its constructor are given as an array of objects,
86       * primitive types must be wrapped with a corresponding class.
87       *
88       * <p>Class loaders are supported only if the isLoaderSupported
89       * method returns true. Otherwise the loader parameter is ignored.
90       *
91       * @param className the name of the class.
92       * @param loader the class loader.
93       * @param params an array containing the parameters of the constructor.
94       * @param signature an array containing the signature of the constructor.
95       * @return the instance.
96       * @throws TurbineException if instantiation fails.
97       */
98      Object getInstance(String className,
99              ClassLoader loader,
100             Object[] params,
101             String[] signature)
102             throws TurbineException;
103 
104     /***
105      * Tests if specified class loaders are supported for a named class.
106      *
107      * @param className the name of the class.
108      * @return true if class loaders are supported, false otherwise.
109      * @throws TurbineException if test fails.
110      */
111     boolean isLoaderSupported(String className)
112             throws TurbineException;
113 
114     /***
115      * Gets the signature classes for parameters of a method of a class.
116      *
117      * @param clazz the class.
118      * @param params an array containing the parameters of the method.
119      * @param signature an array containing the signature of the method.
120      * @return an array of signature classes. Note that in some cases
121      * objects in the parameter array can be switched to the context
122      * of a different class loader.
123      * @throws ClassNotFoundException if any of the classes is not found.
124      */
125     Class[] getSignature(Class clazz,
126             Object params[],
127             String signature[])
128             throws ClassNotFoundException;
129 }