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    }