SPInterface


1   /*
2    * $Header$
3    * $Revision$
4    * $Date$
5    *
6    * ====================================================================
7    *
8    * The Apache Software License, Version 1.1
9    *
10   * Copyright (c) 1999-2002 The Apache Software Foundation.  All rights
11   * reserved.
12   *
13   * Redistribution and use in source and binary forms, with or without
14   * modification, are permitted provided that the following conditions
15   * are met:
16   *
17   * 1. Redistributions of source code must retain the above copyright
18   *    notice, this list of conditions and the following disclaimer.
19   *
20   * 2. Redistributions in binary form must reproduce the above copyright
21   *    notice, this list of conditions and the following disclaimer in
22   *    the documentation and/or other materials provided with the
23   *    distribution.
24   *
25   * 3. The end-user documentation included with the redistribution, if
26   *    any, must include the following acknowlegement:
27   *       "This product includes software developed by the
28   *        Apache Software Foundation (http://www.apache.org/)."
29   *    Alternately, this acknowlegement may appear in the software itself,
30   *    if and wherever such third-party acknowlegements normally appear.
31   *
32   * 4. The names "The Jakarta Project", "Commons", and "Apache Software
33   *    Foundation" must not be used to endorse or promote products derived
34   *    from this software without prior written permission. For written
35   *    permission, please contact apache@apache.org.
36   *
37   * 5. Products derived from this software may not be called "Apache"
38   *    nor may "Apache" appear in their names without prior written
39   *    permission of the Apache Group.
40   *
41   * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
42   * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
43   * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
44   * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
45   * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
46   * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
47   * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
48   * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
49   * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
50   * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
51   * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
52   * SUCH DAMAGE.
53   * ====================================================================
54   *
55   * This software consists of voluntary contributions made by many
56   * individuals on behalf of the Apache Software Foundation.  For more
57   * information on the Apache Software Foundation, please see
58   * <http://www.apache.org/>.
59   *
60   */
61  
62  package org.apache.commons.discovery.tools;
63  
64  import java.lang.reflect.Constructor  ;
65  import java.lang.reflect.InvocationTargetException  ;
66  
67  import org.apache.commons.discovery.DiscoveryException;
68  
69  
70  /**
71   * Represents a Service Programming Interface (spi).
72   * - SPI's name
73   * - SPI's (provider) class
74   * - SPI's (alternate) override property name
75   * 
76   * In addition, while there are many cases where this is NOT
77   * usefull, for those in which it is:
78   * 
79   * - expected constructor argument types and parameters values.
80   * 
81   * @author Richard A. Sitze
82   */
83  public class SPInterface {
84      /**
85       * The service programming interface: intended to be
86       * an interface or abstract class, but not limited
87       * to those two.
88       */        
89      private final Class   spi;
90      
91      /**
92       * The property name to be used for finding the name of
93       * the SPI implementation class.
94       */
95      private final String   propertyName;
96      
97      
98      private Class    paramClasses[] = null;
99      private Object   params[] = null;
100 
101 
102     /**
103      * Construct object representing Class <code>provider</code>.
104      * 
105      * @param provider The SPI class
106      */
107     public SPInterface(Class   provider) {
108         this(provider, provider.getName());
109     }
110     
111     /**
112      * Construct object representing Class <code>provider</code>.
113      * 
114      * @param provider The SPI class
115      * 
116      * @param propertyName when looking for the name of a class implementing
117      *        the provider class, a discovery strategy may involve looking for
118      *        (system or other) properties having either the name of the class
119      *        (provider) or the <code>propertyName</code>.
120      */
121     public SPInterface(Class   spi, String   propertyName) {
122         this.spi = spi;
123         this.propertyName = propertyName;
124     }
125 
126     /**
127      * Construct object representing Class <code>provider</code>.
128      * 
129      * @param provider The SPI class
130      * 
131      * @param constructorParamClasses classes representing the
132      *        constructor argument types.
133      * 
134      * @param constructorParams objects representing the
135      *        constructor arguments.
136      */
137     public SPInterface(Class   provider,
138                        Class   constructorParamClasses[],
139                        Object   constructorParams[])
140     {
141         this(provider,
142              provider.getName(),
143              constructorParamClasses,
144              constructorParams);
145     }
146     
147     /**
148      * Construct object representing Class <code>provider</code>.
149      * 
150      * @param provider The SPI class
151      * 
152      * @param propertyName when looking for the name of a class implementing
153      *        the provider class, a discovery strategy may involve looking for
154      *        (system or other) properties having either the name of the class
155      *        (provider) or the <code>propertyName</code>.
156      * 
157      * @param constructorParamClasses classes representing the
158      *        constructor argument types.
159      * 
160      * @param constructorParams objects representing the
161      *        constructor arguments.
162      */
163     public SPInterface(Class   spi,
164                        String   propertyName,
165                        Class   constructorParamClasses[],
166                        Object   constructorParams[])
167     {
168         this.spi = spi;
169         this.propertyName = propertyName;
170         this.paramClasses = constructorParamClasses;
171         this.params = constructorParams;
172     }
173 
174     public String   getSPName() {
175         return spi.getName();
176     }
177 
178     public Class   getSPClass() {
179         return spi;
180     }
181     
182     public String   getPropertyName() {
183         return propertyName;
184     }
185 
186     /**
187      * Instantiate a new 
188      */    
189     public Object   newInstance(Class   impl)
190         throws DiscoveryException,
191                InstantiationException  ,
192                IllegalAccessException  ,
193                NoSuchMethodException  ,
194                InvocationTargetException  
195     {
196         if (impl == null) {
197             throw new DiscoveryException("No implementation defined for " + getSPName());
198         }
199 
200         verifyAncestory(impl);            
201 
202         if (paramClasses == null || params == null) {
203             return impl.newInstance();
204         } else {
205             Constructor   constructor = impl.getConstructor(paramClasses);
206             return constructor.newInstance(params);
207         }
208     }
209     
210     /**
211      * Throws exception if <code>impl</code> does not
212      * implement or extend the SPI.
213      */
214     public void verifyAncestory(Class   impl) {
215         if (!getSPClass().isAssignableFrom(impl)) {
216             throw new DiscoveryException("Class " + impl.getName() +
217                                          " does not implement " + getSPName());
218         }
219     }
220 }
221
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags