Класс Proxy

public class Proxy
extends Object
implements Serializable

Proxy предоставляет статические методы для создания динамических классов-прокси и экземпляров, а также является суперклассом всех динамических классов-прокси, созданных этими методами.

Для создания прокси для некоторого интерфейса Foo:

InvocationHandler handler = new MyInvocationHandler(...);
     Class<?> proxyClass = Proxy.getProxyClass(Foo.class.getClassLoader(), Foo.class);
     Foo f = (Foo) proxyClass.getConstructor(InvocationHandler.class).
                     newInstance(handler);

или проще:

Foo f = (Foo) Proxy.newProxyInstance(Foo.class.getClassLoader(),
                                          new Class<?>[] { Foo.class },
                                          handler);

Динамический класс-прокси (в дальнейшем просто класс-прокси) — это класс, реализующий список интерфейсов, указанных во время выполнения при создании класса, с поведением, описанным ниже. Интерфейс прокси — это такой интерфейс, который реализуется классом-прокси. Экземпляр прокси — это экземпляр класса-прокси. Каждый экземпляр прокси имеет связанный с ним объект обработчика вызовов, который реализует интерфейс InvocationHandler. Вызов метода на экземпляре прокси через один из его интерфейсов прокси будет перенаправлен на метод invoke обработчика вызовов экземпляра, передавая экземпляр прокси, объект java.lang.reflect.Method , определяющий метод, который был вызван, и массив типа Object содержащий аргументы. Обработчик вызовов обрабатывает закодированный вызов метода соответствующим образом, и результат, который он возвращает, будет возвращен как результат вызова метода на экземпляре прокси.

Класс-прокси имеет следующие свойства:

• Классы-прокси являются общедоступными, final и не абстрактными, если все интерфейсы прокси являются общедоступными.
• Классы-прокси являются не общедоступными, final и не абстрактными, если любой из интерфейсов прокси является неопределённым.
• Неполное имя класса-прокси не определено. Однако пространство имён классов, начинающихся со строки "$Proxy" должно быть зарезервировано для классов-прокси.
• Класс-прокси расширяет java.lang.reflect.Proxy.
• Класс-прокси реализует ровно те интерфейсы, которые были указаны при его создании, в том же порядке.
• Если класс-прокси реализует не общедоступный интерфейс, то он будет определён в той же папке, что и этот интерфейс. В противном случае, пакет класса-прокси также не определён. Обратите внимание, что уплотнение пакетов не помешает классу-прокси быть успешно определённым в определённом пакете во время выполнения, а также не помешают классы, уже определённые тем же загрузчиком классов и тем же пакетом с конкретными подписями.
• Поскольку класс-прокси реализует все интерфейсы, указанные при его создании, вызов getInterfaces на его объекте Class вернёт массив, содержащий тот же список интерфейсов (в порядке, указанном при его создании), вызов getMethods на его объекте Class вернёт массив объектов Method, которые включают все методы в этих интерфейсах, и вызов getMethod найдёт методы в интерфейсах прокси, как и ожидалось.
• Метод Proxy.isProxyClass вернёт true, если ему передан класс-прокси — класс, возвращаемый Proxy.getProxyClass или класс объекта, возвращаемого Proxy.newProxyInstance, и false в противном случае.
• Домен защиты java.security.ProtectionDomain класса-прокси такой же, как и у системных классов, загруженных загрузчиком класса загрузки, таких как java.lang.Object, потому что код класса-прокси генерируется надёжным системным кодом. Этот домен защиты обычно будет предоставлен java.security.AllPermission.
• Каждый класс-прокси имеет один общедоступный конструктор, который принимает один аргумент — реализацию интерфейса InvocationHandler, для установки обработчика вызовов для экземпляра прокси. Вместо того, чтобы использовать API рефлексии для доступа к общедоступному конструктору, экземпляр прокси также может быть создан путём вызова метода Proxy.newProxyInstance, который объединяет действия вызова Proxy.getProxyClass с вызовом конструктора с обработчиком вызовов.

Экземпляр прокси имеет следующие свойства:

• Учитывая экземпляр прокси proxy и один из интерфейсов, реализованных его классом-прокси Foo, следующее выражение вернёт true:

  proxy instanceof Foo

  и следующее преобразование типа будет успешным (вместо выброса ClassCastException) :

  (Foo) proxy

• Каждый экземпляр прокси имеет связанный с ним обработчик вызовов, тот, который был передан его конструктору. Статический метод Proxy.getInvocationHandler вернёт обработчик вызовов, связанный с экземпляром прокси, переданным в качестве аргумента.
• Вызов метода интерфейса на экземпляре прокси будет закодирован и передан методу обработчика вызовов invoke, как описано в документации для этого метода.
• Вызов методов hashCode, equals, или toString объявленных в java.lang.Object на экземпляре прокси будет закодирован и передан методу обработчика вызовов invoke аналогичным образом, как закодированы и перенаправлены вызовы методов интерфейса, как описано выше. Класс-объявление объекта Method , переданного invoke будет java.lang.Object. Другие общедоступные методы экземпляра прокси, унаследованные от java.lang.Object, не переопределяются классом-прокси, поэтому вызовы этих методов ведут себя так же, как и для экземпляров java.lang.Object.

Методы, дублирующиеся в нескольких интерфейсах прокси

Когда два или более интерфейса класса-прокси содержат метод с одинаковым именем и сигнатурой параметра, порядок интерфейсов класса-прокси становится существенным. При вызове такого метода-дубликата на экземпляре прокси, объект Method , переданный обработчику вызовов, не обязательно будет тем, чей объявляющий класс присваивается типу ссылки интерфейса, через который был вызван метод прокси. Это ограничение существует, потому что соответствующая реализация метода в сгенерированном классе-прокси не может определить, через какой интерфейс он был вызван. Поэтому, когда метод-дубликат вызывается на экземпляре прокси, объект Method для метода в главном интерфейсе, содержащем метод (либо напрямую, либо через супер-интерфейс), в списке интерфейсов класса-прокси передаётся обработчику вызовов invoke методу, независимо от типа ссылки, через который произошёл вызов метода.

Если интерфейс прокси содержит метод с таким же именем и сигнатурой параметра, как методы hashCode, equals, или toString класса java.lang.Object, при вызове такого метода на экземпляре прокси, объект Method , переданный обработчику вызовов, будет иметь java.lang.Object в качестве объявляющего класса. Другими словами, общедоступные, не-final методы java.lang.Object логически предшествуют всем интерфейсам прокси для определения, какой объект Method передать обработчику вызовов.

Также обратите внимание, что при перенаправлении дублирующегося метода обработчику вызовов, метод invoke может выбрасывать только типы проверенных исключений, которые присваиваются одному из типов исключений в throws пункте метода во всех интерфейсах прокси, через которые он может быть вызван. Если метод invoke выбрасывает проверенное исключение, которое не присваивается ни одному из типов исключений, объявленных методом в одном из интерфейсов прокси, через которые он может быть вызван, то не проверенное исключение UndeclaredThrowableException будет выброшено вызовом на экземпляре прокси. Это ограничение означает, что не все типы исключений, возвращённые вызовом getExceptionTypes на объекте Method , переданном методу invoke, могут быть успешно выброшены методом invoke.

Поля

h

protected InvocationHandler h

обработчик вызовов для данного экземпляра прокси.

Конструкторы

Proxy

protected Proxy(InvocationHandler h)

Создаёт новый Proxy экземпляр из подкласса (обычно, динамический класс прокси) со значением обработчика вызовов.

Параметры:

h - обработчик вызовов для данного экземпляра прокси

Исключения:

NullPointerException - если заданный обработчик вызовов, h, является null.

Методы

getProxyClass

public static Class<?> getProxyClass(ClassLoader loader,
                                     Class<?>... interfaces)
                              throws IllegalArgumentException

Параметры:

loader - загрузчик классов для определения класса прокси

interfaces - список интерфейсов для реализации классом прокси

Возвращаемое значение:

класс прокси, который определён в указанном загрузчике классов и реализует указанные интерфейсы

Исключения:

IllegalArgumentException - если какое-либо из ограничений на параметры, которые могут быть переданы в getProxyClass, нарушено

SecurityException - если присутствует менеджер безопасности, s, и выполняется любое из следующих условий:

• заданный loader является null, и загрузчик класса вызывающего метода не является null, и вызов s.checkPermission с правом RuntimePermission("getClassLoader") отклоняет доступ.
• для каждого интерфейса прокси, intf, загрузчик класса вызывающего метода не совпадает с загрузчиком класса для intf или не является его предком, и вызов s.checkPackageAccess() отклоняет доступ к intf.

NullPointerException - если аргумент массива interfaces или любой из его элементов являются null

newProxyInstance

public static Object newProxyInstance(ClassLoader loader,
                                      Class<?>[] interfaces,
                                      InvocationHandler h)
                               throws IllegalArgumentException

Параметры:

loader - загрузчик классов для определения класса прокси

interfaces - список интерфейсов для реализации классом прокси

h - обработчик вызовов для перенаправления вызовов методов

Возвращаемое значение:

экземпляр прокси с заданным обработчиком вызовов класса прокси, определённого указанным загрузчиком классов и реализующего указанные интерфейсы

Исключения:

IllegalArgumentException - если какое-либо из ограничений на параметры, которые могут быть переданы в getProxyClass, нарушено

SecurityException - если менеджер безопасности, s, присутствует и выполняется любое из следующих условий:

• заданный loader является null, и загрузчик класса вызывающего метода не является null, и вызов s.checkPermission с правом RuntimePermission("getClassLoader") отклоняет доступ;
• для каждого интерфейса прокси, intf, загрузчик класса вызывающего метода не совпадает с загрузчиком класса для intf или не является его предком, и вызов s.checkPackageAccess() отклоняет доступ к intf;
• любой из заданных интерфейсов прокси является непубличным, и класс вызывающего метода не находится в том же пакете выполнения, что и непубличный интерфейс, и вызов s.checkPermission с правом ReflectPermission("newProxyInPackage.{package name}") отклоняет доступ.

NullPointerException - если аргумент массива interfaces или любой из его элементов является null, или если обработчик вызовов, h, является null

isProxyClass

public static boolean isProxyClass(Class<?> cl)

Параметры:

cl - класс для проверки

Возвращаемое значение:

true если класс является классом прокси и false в противном случае

Исключения:

NullPointerException - если cl является null

getInvocationHandler

public static InvocationHandler getInvocationHandler(Object proxy)
                                              throws IllegalArgumentException

Возвращает обработчик вызовов для указанного экземпляра прокси.

Параметры:

proxy - экземпляр прокси, для которого требуется получить обработчик вызовов

Возвращаемое значение:

обработчик вызовов для экземпляра прокси

Исключения:

IllegalArgumentException - если аргумент не является экземпляром прокси

SecurityException - если менеджер безопасности, s, присутствует и загрузчик класса вызывающего метода не совпадает с загрузчиком класса обработчика вызовов или не является его предком, и вызов s.checkPackageAccess() отклоняет доступ к классу обработчика вызовов.