1. /*
  2. * @(#)InvocationHandler.java 1.5 00/02/02
  3. *
  4. * Copyright 1999, 2000 Sun Microsystems, Inc. All Rights Reserved.
  5. *
  6. * This software is the proprietary information of Sun Microsystems, Inc.
  7. * Use is subject to license terms.
  8. *
  9. */
  10. package java.lang.reflect;
  11. /**
  12. * <code>InvocationHandler</code> is the interface implemented by
  13. * the <i>invocation handler</i> of a proxy instance.
  14. *
  15. * <p>Each proxy instance has an associated invocation handler.
  16. * When a method is invoked on a proxy instance, the method
  17. * invocation is encoded and dispatched to the <code>invoke</code>
  18. * method of its invocation handler.
  19. *
  20. * @author Peter Jones
  21. * @version 1.5, 00/02/02
  22. * @see Proxy
  23. * @since JDK1.3
  24. */
  25. public interface InvocationHandler {
  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. }