InvocationHandler


1   /*
2    * @(#)InvocationHandler.java   1.9 03/12/19
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  /**
11   * <code>InvocationHandler</code> is the interface implemented by
12   * the <i>invocation handler</i> of a proxy instance.
13   *
14   * <p>Each proxy instance has an associated invocation handler.
15   * When a method is invoked on a proxy instance, the method
16   * invocation is encoded and dispatched to the <code>invoke</code>
17   * method of its invocation handler.
18   *
19   * @author  Peter Jones
20   * @version 1.9, 03/12/19
21   * @see     Proxy
22   * @since   JDK1.3
23   */
24  public interface InvocationHandler {
25  
26      /**
27       * Processes a method invocation on a proxy instance and returns
28       * the result.  This method will be invoked on an invocation handler
29       * when a method is invoked on a proxy instance that it is
30       * associated with.
31       *
32       * @param   proxy the proxy instance that the method was invoked on
33       *
34       * @param   method the <code>Method</code> instance corresponding to
35       * the interface method invoked on the proxy instance.  The declaring
36       * class of the <code>Method</code> object will be the interface that
37       * the method was declared in, which may be a superinterface of the
38       * proxy interface that the proxy class inherits the method through.
39       *
40       * @param   args an array of objects containing the values of the
41       * arguments passed in the method invocation on the proxy instance,
42       * or <code>null</code> if interface method takes no arguments.
43       * Arguments of primitive types are wrapped in instances of the
44       * appropriate primitive wrapper class, such as
45       * <code>java.lang.Integer</code> or <code>java.lang.Boolean</code>.
46       *
47       * @return  the value to return from the method invocation on the
48       * proxy instance.  If the declared return type of the interface
49       * method is a primitive type, then the value returned by
50       * this method must be an instance of the corresponding primitive
51       * wrapper class; otherwise, it must be a type assignable to the
52       * declared return type.  If the value returned by this method is
53       * <code>null</code> and the interface method's return type is
54       * primitive, then a <code>NullPointerException</code> will be
55       * thrown by the method invocation on the proxy instance.  If the
56       * value returned by this method is otherwise not compatible with
57       * the interface method's declared return type as described above,
58       * a <code>ClassCastException</code> will be thrown by the method
59       * invocation on the proxy instance.
60       *
61       * @throws  Throwable the exception to throw from the method
62       * invocation on the proxy instance.  The exception's type must be
63       * assignable either to any of the exception types declared in the
64       * <code>throws</code> clause of the interface method or to the
65       * unchecked exception types <code>java.lang.RuntimeException</code>
66       * or <code>java.lang.Error</code>.  If a checked exception is
67       * thrown by this method that is not assignable to any of the
68       * exception types declared in the <code>throws</code> clause of
69       * the interface method, then an
70       * {@link UndeclaredThrowableException} containing the
71       * exception that was thrown by this method will be thrown by the
72       * method invocation on the proxy instance.
73       *
74       * @see UndeclaredThrowableException
75       */
76      public Object   invoke(Object   proxy, Method   method, Object  [] args)
77      throws Throwable  ;
78  }
79
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags