Java > Open Source Codes > java > lang > reflect > Proxy


1 /*
2  * @(#)Proxy.java 1.21 05/09/15
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */
7
8 package java.lang.reflect;
9
10 import java.lang.ref.Reference ;
11 import java.lang.ref.WeakReference ;
12 import java.util.Arrays ;
13 import java.util.Collections ;
14 import java.util.HashMap ;
15 import java.util.HashSet ;
16 import java.util.Map ;
17 import java.util.Set ;
18 import java.util.WeakHashMap ;
19 import sun.misc.ProxyGenerator;
20
21 /**
22  * <code>Proxy</code> provides static methods for creating dynamic proxy
23  * classes and instances, and it is also the superclass of all
24  * dynamic proxy classes created by those methods.
25  *
26  * <p>To create a proxy for some interface <code>Foo</code>:
27  * <pre>
28  * InvocationHandler handler = new MyInvocationHandler(...);
29  * Class proxyClass = Proxy.getProxyClass(
30  * Foo.class.getClassLoader(), new Class[] { Foo.class });
31  * Foo f = (Foo) proxyClass.
32  * getConstructor(new Class[] { InvocationHandler.class }).
33  * newInstance(new Object[] { handler });
34  * </pre>
35  * or more simply:
36  * <pre>
37  * Foo f = (Foo) Proxy.newProxyInstance(Foo.class.getClassLoader(),
38  * new Class[] { Foo.class },
39  * handler);
40  * </pre>
41  *
42  * <p>A <i>dynamic proxy class</i> (simply referred to as a <i>proxy
43  * class</i> below) is a class that implements a list of interfaces
44  * specified at runtime when the class is created, with behavior as
45  * described below.
46  *
47  * A <i>proxy interface</i> is such an interface that is implemented
48  * by a proxy class.
49  *
50  * A <i>proxy instance</i> is an instance of a proxy class.
51  *
52  * Each proxy instance has an associated <i>invocation handler</i>
53  * object, which implements the interface {@link InvocationHandler}.
54  * A method invocation on a proxy instance through one of its proxy
55  * interfaces will be dispatched to the {@link InvocationHandler#invoke
56  * invoke} method of the instance's invocation handler, passing the proxy
57  * instance, a <code>java.lang.reflect.Method</code> object identifying
58  * the method that was invoked, and an array of type <code>Object</code>
59  * containing the arguments. The invocation handler processes the
60  * encoded method invocation as appropriate and the result that it
61  * returns will be returned as the result of the method invocation on
62  * the proxy instance.
63  *
64  * <p>A proxy class has the following properties:
65  *
66  * <ul>
67  * <li>Proxy classes are public, final, and not abstract.
68  *
69  * <li>The unqualified name of a proxy class is unspecified. The space
70  * of class names that begin with the string <code>"$Proxy"</code>
71  * should be, however, reserved for proxy classes.
72  *
73  * <li>A proxy class extends <code>java.lang.reflect.Proxy</code>.
74  *
75  * <li>A proxy class implements exactly the interfaces specified at its
76  * creation, in the same order.
77  *
78  * <li>If a proxy class implements a non-public interface, then it will
79  * be defined in the same package as that interface. Otherwise, the
80  * package of a proxy class is also unspecified. Note that package
81  * sealing will not prevent a proxy class from being successfully defined
82  * in a particular package at runtime, and neither will classes already
83  * defined by the same class loader and the same package with particular
84  * signers.
85  *
86  * <li>Since a proxy class implements all of the interfaces specified at
87  * its creation, invoking <code>getInterfaces</code> on its
88  * <code>Class</code> object will return an array containing the same
89  * list of interfaces (in the order specified at its creation), invoking
90  * <code>getMethods</code> on its <code>Class</code> object will return
91  * an array of <code>Method</code> objects that include all of the
92  * methods in those interfaces, and invoking <code>getMethod</code> will
93  * find methods in the proxy interfaces as would be expected.
94  *
95  * <li>The {@link Proxy#isProxyClass Proxy.isProxyClass} method will
96  * return true if it is passed a proxy class-- a class returned by
97  * <code>Proxy.getProxyClass</code> or the class of an object returned by
98  * <code>Proxy.newProxyInstance</code>-- and false otherwise.
99  *
100  * <li>The <code>java.security.ProtectionDomain</code> of a proxy class
101  * is the same as that of system classes loaded by the bootstrap class
102  * loader, such as <code>java.lang.Object</code>, because the code for a
103  * proxy class is generated by trusted system code. This protection
104  * domain will typically be granted
105  * <code>java.security.AllPermission</code>.
106  *
107  * <li>Each proxy class has one public constructor that takes one argument,
108  * an implementation of the interface {@link InvocationHandler}, to set
109  * the invocation handler for a proxy instance. Rather than having to use
110  * the reflection API to access the public constructor, a proxy instance
111  * can be also be created by calling the {@link Proxy#newProxyInstance
112  * Proxy.newInstance} method, which combines the actions of calling
113  * {@link Proxy#getProxyClass Proxy.getProxyClass} with invoking the
114  * constructor with an invocation handler.
115  * </ul>
116  *
117  * <p>A proxy instance has the following properties:
118  *
119  * <ul>
120  * <li>Given a proxy instance <code>proxy</code> and one of the
121  * interfaces implemented by its proxy class <code>Foo</code>, the
122  * following expression will return true:
123  * <pre>
124  * <code>proxy instanceof Foo</code>
125  * </pre>
126  * and the following cast operation will succeed (rather than throwing
127  * a <code>ClassCastException</code>):
128  * <pre>
129  * <code>(Foo) proxy</code>
130  * </pre>
131  *
132  * <li>Each proxy instance has an associated invocation handler, the one
133  * that was passed to its constructor. The static
134  * {@link Proxy#getInvocationHandler Proxy.getInvocationHandler} method
135  * will return the invocation handler associated with the proxy instance
136  * passed as its argument.
137  *
138  * <li>An interface method invocation on a proxy instance will be
139  * encoded and dispatched to the invocation handler's {@link
140  * InvocationHandler#invoke invoke} method as described in the
141  * documentation for that method.
142  *
143  * <li>An invocation of the <code>hashCode</code>,
144  * <code>equals</code>, or <code>toString</code> methods declared in
145  * <code>java.lang.Object</code> on a proxy instance will be encoded and
146  * dispatched to the invocation handler's <code>invoke</code> method in
147  * the same manner as interface method invocations are encoded and
148  * dispatched, as described above. The declaring class of the
149  * <code>Method</code> object passed to <code>invoke</code> will be
150  * <code>java.lang.Object</code>. Other public methods of a proxy
151  * instance inherited from <code>java.lang.Object</code> are not
152  * overridden by a proxy class, so invocations of those methods behave
153  * like they do for instances of <code>java.lang.Object</code>.
154  * </ul>
155  *
156  * <h3>Methods Duplicated in Multiple Proxy Interfaces</h3>
157  *
158  * <p>When two or more interfaces of a proxy class contain a method with
159  * the same name and parameter signature, the order of the proxy class's
160  * interfaces becomes significant. When such a <i>duplicate method</i>
161  * is invoked on a proxy instance, the <code>Method</code> object passed
162  * to the invocation handler will not necessarily be the one whose
163  * declaring class is assignable from the reference type of the interface
164  * that the proxy's method was invoked through. This limitation exists
165  * because the corresponding method implementation in the generated proxy
166  * class cannot determine which interface it was invoked through.
167  * Therefore, when a duplicate method is invoked on a proxy instance,
168  * the <code>Method</code> object for the method in the foremost interface
169  * that contains the method (either directly or inherited through a
170  * superinterface) in the proxy class's list of interfaces is passed to
171  * the invocation handler's <code>invoke</code> method, regardless of the
172  * reference type through which the method invocation occurred.
173  *
174  * <p>If a proxy interface contains a method with the same name and
175  * parameter signature as the <code>hashCode</code>, <code>equals</code>,
176  * or <code>toString</code> methods of <code>java.lang.Object</code>,
177  * when such a method is invoked on a proxy instance, the
178  * <code>Method</code> object passed to the invocation handler will have
179  * <code>java.lang.Object</code> as its declaring class. In other words,
180  * the public, non-final methods of <code>java.lang.Object</code>
181  * logically precede all of the proxy interfaces for the determination of
182  * which <code>Method</code> object to pass to the invocation handler.
183  *
184  * <p>Note also that when a duplicate method is dispatched to an
185  * invocation handler, the <code>invoke</code> method may only throw
186  * checked exception types that are assignable to one of the exception
187  * types in the <code>throws</code> clause of the method in <i>all</i> of
188  * the proxy interfaces that it can be invoked through. If the
189  * <code>invoke</code> method throws a checked exception that is not
190  * assignable to any of the exception types declared by the method in one
191  * of the proxy interfaces that it can be invoked through, then an
192  * unchecked <code>UndeclaredThrowableException</code> will be thrown by
193  * the invocation on the proxy instance. This restriction means that not
194  * all of the exception types returned by invoking
195  * <code>getExceptionTypes</code> on the <code>Method</code> object
196  * passed to the <code>invoke</code> method can necessarily be thrown
197  * successfully by the <code>invoke</code> method.
198  *
199  * @author Peter Jones
200  * @version 1.21, 05/09/15
201  * @see InvocationHandler
202  * @since 1.3
203  */
204 public class Proxy implements java.io.Serializable {
205
206     private static final long serialVersionUID = -2222568056686623797L;
207
208     /** prefix for all proxy class names */
209     private final static String proxyClassNamePrefix = "$Proxy";
210
211     /** parameter types of a proxy class constructor */
212     private final static Class [] constructorParams =
213     { InvocationHandler .class };
214
215     /** maps a class loader to the proxy class cache for that loader */
216     private static Map loaderToCache = new WeakHashMap ();
217
218     /** marks that a particular proxy class is currently being generated */
219     private static Object pendingGenerationMarker = new Object ();
220
221     /** next number to use for generation of unique proxy class names */
222     private static long nextUniqueNumber = 0;
223     private static Object nextUniqueNumberLock = new Object ();
224
225     /** set of all generated proxy classes, for isProxyClass implementation */
226     private static Map proxyClasses =
227     Collections.synchronizedMap(new WeakHashMap ());
228
229     /**
230      * the invocation handler for this proxy instance.
231      * @serial
232      */
233     protected InvocationHandler h;
234
235     /**
236      * Prohibits instantiation.
237      */
238     private Proxy() {
239     }
240
241     /**
242      * Constructs a new <code>Proxy</code> instance from a subclass
243      * (typically, a dynamic proxy class) with the specified value
244      * for its invocation handler.
245      *
246      * @param h the invocation handler for this proxy instance
247      */
248     protected Proxy(InvocationHandler h) {
249     this.h = h;
250     }
251
252     /**
253      * Returns the <code>java.lang.Class</code> object for a proxy class
254      * given a class loader and an array of interfaces. The proxy class
255      * will be defined by the specified class loader and will implement
256      * all of the supplied interfaces. If a proxy class for the same
257      * permutation of interfaces has already been defined by the class
258      * loader, then the existing proxy class will be returned; otherwise,
259      * a proxy class for those interfaces will be generated dynamically
260      * and defined by the class loader.
261      *
262      * <p>There are several restrictions on the parameters that may be
263      * passed to <code>Proxy.getProxyClass</code>:
264      *
265      * <ul>
266      * <li>All of the <code>Class</code> objects in the
267      * <code>interfaces</code> array must represent interfaces, not
268      * classes or primitive types.
269      *
270      * <li>No two elements in the <code>interfaces</code> array may
271      * refer to identical <code>Class</code> objects.
272      *
273      * <li>All of the interface types must be visible by name through the
274      * specified class loader. In other words, for class loader
275      * <code>cl</code> and every interface <code>i</code>, the following
276      * expression must be true:
277      * <pre>
278      * Class.forName(i.getName(), false, cl) == i
279      * </pre>
280      *
281      * <li>All non-public interfaces must be in the same package;
282      * otherwise, it would not be possible for the proxy class to
283      * implement all of the interfaces, regardless of what package it is
284      * defined in.
285      *
286      * <li>For any set of member methods of the specified interfaces
287      * that have the same signature:
288      * <ul>
289      * <li>If the return type of any of the methods is a primitive
290      * type or void, then all of the methods must have that same
291      * return type.
292      * <li>Otherwise, one of the methods must have a return type that
293      * is assignable to all of the return types of the rest of the
294      * methods.
295      * </ul>
296      *
297      * <li>The resulting proxy class must not exceed any limits imposed
298      * on classes by the virtual machine. For example, the VM may limit
299      * the number of interfaces that a class may implement to 65535; in
300      * that case, the size of the <code>interfaces</code> array must not
301      * exceed 65535.
302      * </ul>
303      *
304      * <p>If any of these restrictions are violated,
305      * <code>Proxy.getProxyClass</code> will throw an
306      * <code>IllegalArgumentException</code>. If the <code>interfaces</code>
307      * array argument or any of its elements are <code>null</code>, a
308      * <code>NullPointerException</code> will be thrown.
309      *
310      * <p>Note that the order of the specified proxy interfaces is
311      * significant: two requests for a proxy class with the same combination
312      * of interfaces but in a different order will result in two distinct
313      * proxy classes.
314      *
315      * @param loader the class loader to define the proxy class
316      * @param interfaces the list of interfaces for the proxy class
317      * to implement
318      * @return a proxy class that is defined in the specified class loader
319      * and that implements the specified interfaces
320      * @throws IllegalArgumentException if any of the restrictions on the
321      * parameters that may be passed to <code>getProxyClass</code>
322      * are violated
323      * @throws NullPointerException if the <code>interfaces</code> array
324      * argument or any of its elements are <code>null</code>
325      */
326     public static Class <?> getProxyClass(ClassLoader loader,
327                                          Class <?>... interfaces)
328     throws IllegalArgumentException
329     {
330     if (interfaces.length > 65535) {
331         throw new IllegalArgumentException ("interface limit exceeded");
332     }
333
334     Class proxyClass = null;
335
336     /* collect interface names to use as key for proxy class cache */
337     String [] interfaceNames = new String [interfaces.length];
338
339     Set interfaceSet = new HashSet (); // for detecting duplicates
340
341     for (int i = 0; i < interfaces.length; i++) {
342         /*
343          * Verify that the class loader resolves the name of this
344          * interface to the same Class object.
345          */
346         String interfaceName = interfaces[i].getName();
347         Class interfaceClass = null;
348         try {
349         interfaceClass = Class.forName(interfaceName, false, loader);
350         } catch (ClassNotFoundException e) {
351         }
352         if (interfaceClass != interfaces[i]) {
353         throw new IllegalArgumentException (
354             interfaces[i] + " is not visible from class loader");
355         }
356
357         /*
358          * Verify that the Class object actually represents an
359          * interface.
360          */
361         if (!interfaceClass.isInterface()) {
362         throw new IllegalArgumentException (
363             interfaceClass.getName() + " is not an interface");
364         }
365
366         /*
367          * Verify that this interface is not a duplicate.
368          */
369         if (interfaceSet.contains(interfaceClass)) {
370         throw new IllegalArgumentException (
371             "repeated interface: " + interfaceClass.getName());
372         }
373         interfaceSet.add(interfaceClass);
374
375         interfaceNames[i] = interfaceName;
376     }
377
378     /*
379      * Using string representations of the proxy interfaces as
380      * keys in the proxy class cache (instead of their Class
381      * objects) is sufficient because we require the proxy
382      * interfaces to be resolvable by name through the supplied
383      * class loader, and it has the advantage that using a string
384      * representation of a class makes for an implicit weak
385      * reference to the class.
386      */
387     Object key = Arrays.asList(interfaceNames);
388
389     /*
390      * Find or create the proxy class cache for the class loader.
391      */
392     Map cache;
393     synchronized (loaderToCache) {
394         cache = (Map ) loaderToCache.get(loader);
395         if (cache == null) {
396         cache = new HashMap ();
397         loaderToCache.put(loader, cache);
398         }
399         /*
400          * This mapping will remain valid for the duration of this
401          * method, without further synchronization, because the mapping
402          * will only be removed if the class loader becomes unreachable.
403          */
404     }
405
406     /*
407      * Look up the list of interfaces in the proxy class cache using
408      * the key. This lookup will result in one of three possible
409      * kinds of values:
410      * null, if there is currently no proxy class for the list of
411      * interfaces in the class loader,
412      * the pendingGenerationMarker object, if a proxy class for the
413      * list of interfaces is currently being generated,
414      * or a weak reference to a Class object, if a proxy class for
415      * the list of interfaces has already been generated.
416      */
417     synchronized (cache) {
418         /*
419          * Note that we need not worry about reaping the cache for
420          * entries with cleared weak references because if a proxy class
421          * has been garbage collected, its class loader will have been
422          * garbage collected as well, so the entire cache will be reaped
423          * from the loaderToCache map.
424          */
425         do {
426         Object value = cache.get(key);
427         if (value instanceof Reference ) {
428             proxyClass = (Class ) ((Reference ) value).get();
429         }
430         if (proxyClass != null) {
431             // proxy class already generated: return it
432 return proxyClass;
433         } else if (value == pendingGenerationMarker) {
434             // proxy class being generated: wait for it
435 try {
436             cache.wait();
437             } catch (InterruptedException e) {
438             /*
439              * The class generation that we are waiting for should
440              * take a small, bounded time, so we can safely ignore
441              * thread interrupts here.
442              */
443             }
444             continue;
445         } else {
446             /*
447              * No proxy class for this list of interfaces has been
448              * generated or is being generated, so we will go and
449              * generate it now. Mark it as pending generation.
450              */
451             cache.put(key, pendingGenerationMarker);
452             break;
453         }
454         } while (true);
455     }
456
457     try {
458         String proxyPkg = null; // package to define proxy class in
459
460         /*
461          * Record the package of a non-public proxy interface so that the
462          * proxy class will be defined in the same package. Verify that
463          * all non-public proxy interfaces are in the same package.
464          */
465         for (int i = 0; i < interfaces.length; i++) {
466         int flags = interfaces[i].getModifiers();
467         if (!Modifier.isPublic(flags)) {
468             String name = interfaces[i].getName();
469             int n = name.lastIndexOf('.');
470             String pkg = ((n == -1) ? "" : name.substring(0, n + 1));
471             if (proxyPkg == null) {
472             proxyPkg = pkg;
473             } else if (!pkg.equals(proxyPkg)) {
474             throw new IllegalArgumentException (
475                 "non-public interfaces from different packages");
476             }
477         }
478         }
479
480         if (proxyPkg == null) { // if no non-public proxy interfaces,
481 proxyPkg = ""; // use the unnamed package
482 }
483
484         {
485         /*
486          * Choose a name for the proxy class to generate.
487          */
488         long num;
489         synchronized (nextUniqueNumberLock) {
490             num = nextUniqueNumber++;
491         }
492         String proxyName = proxyPkg + proxyClassNamePrefix + num;
493         /*
494          * Verify that the class loader hasn't already
495          * defined a class with the chosen name.
496          */
497
498         /*
499          * Generate the specified proxy class.
500          */
501         byte[] proxyClassFile = ProxyGenerator.generateProxyClass(
502             proxyName, interfaces);
503         try {
504             proxyClass = defineClass0(loader, proxyName,
505             proxyClassFile, 0, proxyClassFile.length);
506         } catch (ClassFormatError e) {
507             /*
508              * A ClassFormatError here means that (barring bugs in the
509              * proxy class generation code) there was some other
510              * invalid aspect of the arguments supplied to the proxy
511              * class creation (such as virtual machine limitations
512              * exceeded).
513              */
514             throw new IllegalArgumentException (e.toString());
515         }
516         }
517         // add to set of all generated proxy classes, for isProxyClass
518 proxyClasses.put(proxyClass, null);
519
520     } finally {
521         /*
522          * We must clean up the "pending generation" state of the proxy
523          * class cache entry somehow. If a proxy class was successfully
524          * generated, store it in the cache (with a weak reference);
525          * otherwise, remove the reserved entry. In all cases, notify
526          * all waiters on reserved entries in this cache.
527          */
528         synchronized (cache) {
529         if (proxyClass != null) {
530             cache.put(key, new WeakReference (proxyClass));
531         } else {
532             cache.remove(key);
533         }
534         cache.notifyAll();
535         }
536     }
537     return proxyClass;
538     }
539
540     /**
541      * Returns an instance of a proxy class for the specified interfaces
542      * that dispatches method invocations to the specified invocation
543      * handler. This method is equivalent to:
544      * <pre>
545      * Proxy.getProxyClass(loader, interfaces).
546      * getConstructor(new Class[] { InvocationHandler.class }).
547      * newInstance(new Object[] { handler });
548      * </pre>
549      *
550      * <p><code>Proxy.newProxyInstance</code> throws
551      * <code>IllegalArgumentException</code> for the same reasons that
552      * <code>Proxy.getProxyClass</code> does.
553      *
554      * @param loader the class loader to define the proxy class
555      * @param interfaces the list of interfaces for the proxy class
556      * to implement
557      * @param h the invocation handler to dispatch method invocations to
558      * @return a proxy instance with the specified invocation handler of a
559      * proxy class that is defined by the specified class loader
560      * and that implements the specified interfaces
561      * @throws IllegalArgumentException if any of the restrictions on the
562      * parameters that may be passed to <code>getProxyClass</code>
563      * are violated
564      * @throws NullPointerException if the <code>interfaces</code> array
565      * argument or any of its elements are <code>null</code>, or
566      * if the invocation handler, <code>h</code>, is
567      * <code>null</code>
568      */
569     public static Object newProxyInstance(ClassLoader loader,
570                       Class <?>[] interfaces,
571                       InvocationHandler h)
572     throws IllegalArgumentException
573     {
574     if (h == null) {
575         throw new NullPointerException ();
576     }
577
578     /*
579      * Look up or generate the designated proxy class.
580      */
581     Class cl = getProxyClass(loader, interfaces);
582
583     /*
584      * Invoke its constructor with the designated invocation handler.
585      */
586     try {
587         Constructor cons = cl.getConstructor(constructorParams);
588         return (Object ) cons.newInstance(new Object [] { h });
589     } catch (NoSuchMethodException e) {
590         throw new InternalError (e.toString());
591     } catch (IllegalAccessException e) {
592         throw new InternalError (e.toString());
593     } catch (InstantiationException e) {
594         throw new InternalError (e.toString());
595     } catch (InvocationTargetException e) {
596         throw new InternalError (e.toString());
597     }
598     }
599
600     /**
601      * Returns true if and only if the specified class was dynamically
602      * generated to be a proxy class using the <code>getProxyClass</code>
603      * method or the <code>newProxyInstance</code> method.
604      *
605      * <p>The reliability of this method is important for the ability
606      * to use it to make security decisions, so its implementation should
607      * not just test if the class in question extends <code>Proxy</code>.
608      *
609      * @param cl the class to test
610      * @return <code>true</code> if the class is a proxy class and
611      * <code>false</code> otherwise
612      * @throws NullPointerException if <code>cl</code> is <code>null</code>
613      */
614     public static boolean isProxyClass(Class <?> cl) {
615     if (cl == null) {
616         throw new NullPointerException ();
617     }
618
619     return proxyClasses.containsKey(cl);
620     }
621
622     /**
623      * Returns the invocation handler for the specified proxy instance.
624      *
625      * @param proxy the proxy instance to return the invocation handler for
626      * @return the invocation handler for the proxy instance
627      * @throws IllegalArgumentException if the argument is not a
628      * proxy instance
629      */
630     public static InvocationHandler getInvocationHandler(Object proxy)
631     throws IllegalArgumentException
632     {
633     /*
634      * Verify that the object is actually a proxy instance.
635      */
636     if (!isProxyClass(proxy.getClass())) {
637         throw new IllegalArgumentException ("not a proxy instance");
638     }
639
640     Proxy p = (Proxy ) proxy;
641     return p.h;
642     }
643
644     private static native Class defineClass0(ClassLoader loader, String name,
645                          byte[] b, int off, int len);
646 }
647

A to Z: JavaDoc & Examples

---

Daily Java News & Articles

---

Open Source Projects

---

Open Source Codes

---

Free Computer Books

---

Remove Frame

---

Popular Tags