MethodHandle Classe

Définition

[Android.Runtime.Register("java/lang/invoke/MethodHandle", ApiSince=26, DoNotGenerateAcw=true)]
public abstract class MethodHandle : Java.Lang.Object

[<Android.Runtime.Register("java/lang/invoke/MethodHandle", ApiSince=26, DoNotGenerateAcw=true)>]
type MethodHandle = class
    inherit Object

Héritage

Object

JavaObject

Object

MethodHandle

Attributs

RegisterAttribute

Remarques

Un handle de méthode est une référence typée, directement exécutable à une méthode sous-jacente, un constructeur, un champ ou une opération de bas niveau similaire, avec des transformations facultatives d’arguments ou de valeurs de retour. Ces transformations sont assez générales et incluent des modèles tels que #asType conversion, #bindTo insertion, java.lang.invoke.MethodHandles#dropArguments deletion, et java.lang.invoke.MethodHandles#filterArguments substitution.

<Les handles de méthode h1>handle contents</h1> Method handles sont dynamiquement et fortement typés en fonction de leur paramètre et de leurs types de retour. Ils ne sont pas distingués par le nom ou la classe de définition de leurs méthodes sous-jacentes. Un handle de méthode doit être appelé à l’aide d’un descripteur de type symbolique qui correspond au descripteur de type #type du handle de méthode.

Chaque méthode gère son descripteur de type via l’accesseur #type type . Ce descripteur de type est un java.lang.invoke.MethodType MethodType objet dont la structure est une série de classes, dont l’un est le type de retour de la méthode (ou void.class si aucun).

Le type d’un handle de méthode contrôle les types d’appels qu’il accepte et les types de transformations qui s’y appliquent.

Un handle de méthode contient une paire de méthodes d’appelant spéciales appelées #invokeExact invokeExact et #invoke invoke. Les deux méthodes d’appelant fournissent un accès direct à la méthode, au constructeur, au champ ou à une autre opération sous-jacente du handle de méthode, comme modifié par les transformations d’arguments et de valeurs de retour. Les deux appelants acceptent les appels qui correspondent exactement au type du handle de méthode. L’appelant brut et incorrect accepte également une plage d’autres types d’appels.

Les handles de méthode sont immuables et n’ont aucun état visible. Bien sûr, ils peuvent être liés à des méthodes ou données sous-jacentes qui présentent l’état. En ce qui concerne le modèle de mémoire Java, tout handle de méthode se comporte comme si tous ses champs (internes) sont des variables finales. Cela signifie que tout handle de méthode rendu visible par l’application sera toujours entièrement formé. Cela est vrai même si le handle de méthode est publié par le biais d’une variable partagée dans une course de données.

Les handles de méthode ne peuvent pas être sous-classés par l’utilisateur. Les implémentations peuvent (ou non) créer des sous-classes internes qui MethodHandle peuvent être visibles via l’opération java.lang.Object#getClass Object.getClass . Le programmeur ne doit pas tirer des conclusions sur un handle de méthode à partir de sa classe spécifique, car la hiérarchie de classes de handle de méthode (le cas échéant) peut changer de temps à autre ou entre les implémentations de différents fournisseurs.

<h1>Method handle compilation</h1> A Java method call expression naming invokeExact ou invoke peut appeler un handle de méthode à partir de Java code source. Du point de vue du code source, ces méthodes peuvent prendre n’importe quel argument et leur résultat peut être converti en n’importe quel type de retour. Formellement, cela s’effectue en donnant aux méthodes Object appelantes des types de retour et des arguments d’arité Object variable, mais ils ont une qualité supplémentaire appelée <>em signature polymorphisme</em> qui connecte cette liberté d’appel directement à la pile d’exécution JVM.

Comme c’est le cas d’habitude avec les méthodes virtuelles, les appels au niveau source et invokeExact la invoke compilation vers une invokevirtual instruction. Plus inhabituellement, le compilateur doit enregistrer les types d’arguments réels et peut ne pas effectuer de conversions d’appel de méthode sur les arguments. Au lieu de cela, il doit les pousser sur la pile en fonction de leurs propres types non convertis. L’objet handle de méthode lui-même est envoyé (push) sur la pile avant les arguments. Le compilateur appelle ensuite le handle de méthode avec un descripteur de type symbolique qui décrit l’argument et les types de retour.

Pour émettre un descripteur de type symbolique complet, le compilateur doit également déterminer le type de retour. Cela est basé sur un cast sur l’expression d’appel de méthode, s’il en existe un ou si Object l’appel est une expression ou si void l’appel est une instruction. Le cast peut être d’un type primitif (mais pas void).

En tant que cas d’angle, un argument noncasté null reçoit un descripteur de type symbolique de java.lang.Void. L’ambiguïté avec le type Void est inoffensive, car il n’existe aucune référence de type Void , sauf la référence Null.

<h1>Method handle invocation</h1> La première fois qu’une invokevirtual instruction est exécutée, elle est liée, en résolvant symboliquement les noms dans l’instruction et en vérifiant que l’appel de méthode est juridique statiquement. C’est vrai des appels à invokeExact et invoke. Dans ce cas, le descripteur de type symbolique émis par le compilateur est vérifié pour obtenir la syntaxe correcte et les noms qu’il contient sont résolus. Ainsi, une invokevirtual instruction qui appelle un handle de méthode lie toujours, tant que le descripteur de type symbolique est syntactiquement bien formé et que les types existent.

Lorsque l’exécution invokevirtual est effectuée après la liaison, le type du handle de méthode de réception est d’abord vérifié par la machine virtuelle JVM pour s’assurer qu’elle correspond au descripteur de type symbolique. Si la correspondance de type échoue, cela signifie que la méthode que l’appelant appelle n’est pas présente sur le handle de méthode individuel appelé.

Dans le cas de invokeExact, le descripteur de type de l’appel (après la résolution des noms de types symboliques) doit correspondre exactement au type de méthode du handle de méthode de réception. Dans le cas d’un descripteur de type brut et incorrect invoke, le descripteur de type résolu doit être un argument valide pour la méthode du #asType asType récepteur. Ainsi, la plaine invoke est plus permissive que invokeExact.

Après la correspondance de type, un appel à invokeExact directement et immédiatement appeler la méthode sous-jacente du handle de méthode (ou un autre comportement, comme le cas peut être).

Un appel à plain invoke fonctionne de la même façon qu’un appel à invokeExact, si le descripteur de type symbolique spécifié par l’appelant correspond exactement au propre type du handle de méthode. S’il existe une incompatibilité de type, invoke tente d’ajuster le type du handle de méthode de réception, comme s’il s’agit d’un appel à #asType asType, pour obtenir un handle M2de méthode invoqueable exactement. Cela permet une négociation plus puissante du type de méthode entre l’appelant et l’appelé.

(<em>Remarque :</em> Le handle M2 de méthode ajusté n’est pas directement observable et les implémentations ne sont donc pas nécessaires pour la matérialiser.)

<h1>Vérification de l’appel</h1> Dans les programmes classiques, la correspondance de type de handle de méthode réussit généralement. Mais en cas d’échec d’une correspondance, la machine virtuelle JVM lève directement WrongMethodTypeException(en cas de invokeExact) ou indirectement comme si par un appel a échoué à asType (dans le cas de invoke).

Par conséquent, une incompatibilité de type de méthode qui peut apparaître comme une erreur de liaison dans un programme typé statiquement peut apparaître comme une dynamique WrongMethodTypeException dans un programme qui utilise des handles de méthode.

Étant donné que les types de méthode contiennent des objets « live », Class la correspondance des types de méthode prend en compte les noms de types et les chargeurs de classes. Ainsi, même si un handle M de méthode est créé dans un chargeur L1 de classe et utilisé dans un autre L2, les appels de handle de méthode sont de type sécurisé, car le descripteur de type symbolique de l’appelant, tel qu’il est résolu, est mis en L2correspondance avec le descripteur de type symbolique de la méthode d’appel d’origine, comme résolu dans L1. La résolution se L1 produit lorsqu’elle M est créée et son type est affecté, tandis que la résolution L2 se produit lorsque l’instruction invokevirtual est liée.

Outre la vérification des descripteurs de type, la capacité d’un handle de méthode à appeler sa méthode sous-jacente est illimitée. Si un handle de méthode est formé sur une méthode non publique par une classe qui a accès à cette méthode, le handle résultant peut être utilisé à n’importe quel endroit par n’importe quel appelant qui reçoit une référence à cette méthode.

Contrairement à l’API Core Reflection, où l’accès est vérifié chaque fois qu’une méthode réfléchissante est appelée, la vérification de la gestion des accès de la méthode est effectuée lors de la création du handle de méthode. Dans le cas de (voir ci-dessous), la vérification d’accès ldc est effectuée dans le cadre de la liaison de l’entrée du pool constant sous-jacent au handle de méthode constante.

Ainsi, les handles aux méthodes non publiques, ou aux méthodes dans les classes non publiques, doivent généralement être gardés secrets. Ils ne doivent pas être passés à du code non approuvé, sauf si leur utilisation à partir du code non approuvé serait inoffensive.

<Le code Java de la> méthode h1<> peut créer un handle de méthode qui accède directement à n’importe quelle méthode, constructeur ou champ accessible à ce code. Cette opération s’effectue via une API réfléchissante basée sur les capacités appelée java.lang.invoke.MethodHandles.Lookup MethodHandles.Lookup Par exemple, un handle de méthode statique peut être obtenu à partir de java.lang.invoke.MethodHandles.Lookup#findStatic Lookup.findStatic. Il existe également des méthodes de conversion à partir d’objets API Core Reflection, comme java.lang.invoke.MethodHandles.Lookup#unreflect Lookup.unreflect.

Comme les classes et les chaînes, les handles de méthode qui correspondent aux champs, méthodes et constructeurs accessibles peuvent également être représentés directement dans le pool de constantes d’un fichier de classe en tant que constantes à charger par octets ldc . Un nouveau type d’entrée de pool constant, CONSTANT_MethodHandlefait référence directement à une entrée de pool de constantes associée CONSTANT_MethodrefCONSTANT_InterfaceMethodrefou CONSTANT_Fieldref à un pool constant. (Pour plus d’informations sur les constantes de handle de méthode, consultez les sections 4.4.8 et 5.4.3.5 de la spécification de machine virtuelle Java.)

Les handles de méthode générés par des recherches ou des charges constantes à partir de méthodes ou de constructeurs avec le bit de modificateur de variable (0x0080) ont une arité de variable correspondante, comme s’ils étaient définis avec l’aide de #asVarargsCollector asVarargsCollector.

Une référence de méthode peut faire référence à une méthode statique ou non statique. Dans le cas non statique, le type de handle de méthode inclut un argument de récepteur explicite, précédé d’autres arguments. Dans le type du handle de méthode, l’argument récepteur initial est typé en fonction de la classe sous laquelle la méthode a été initialement demandée. (Par exemple, si un handle de méthode non statique est obtenu via ldc, le type du récepteur est la classe nommée dans l’entrée du pool constant.)

Les constantes de handle de méthode sont soumises aux mêmes vérifications d’accès au moment du lien vérifient leurs instructions bytecode correspondantes, et l’instruction ldc lève des erreurs de liaison correspondantes si les comportements de code bytecode lèvent ces erreurs.

En conséquence, l’accès aux membres protégés est limité aux récepteurs uniquement de la classe d’accès, ou à l’une de ses sous-classes, et la classe d’accès doit à son tour être une sous-classe (ou un frère de package) de la classe de définition du membre protégé. Si une référence de méthode fait référence à une méthode non statique protégée ou à un champ d’une classe en dehors du package actuel, l’argument récepteur est limité au type de la classe d’accès.

Lorsqu’un handle de méthode vers une méthode virtuelle est appelé, la méthode est toujours recherchée dans le récepteur (autrement dit, le premier argument).

Un handle de méthode non virtuel pour une implémentation de méthode virtuelle spécifique peut également être créé. Celles-ci n’effectuent pas de recherche virtuelle en fonction du type de récepteur. Un tel handle de méthode simule l’effet d’une invokespecial instruction sur la même méthode.

<Exemples d’utilisation> h1</h1> Voici quelques exemples d’utilisation : <blockquote>

{@code
            Object x, y; String s; int i;
            MethodType mt; MethodHandle mh;
            MethodHandles.Lookup lookup = MethodHandles.lookup();
            // mt is (char,char)String
            mt = MethodType.methodType(String.class, char.class, char.class);
            mh = lookup.findVirtual(String.class, "replace", mt);
            s = (String) mh.invokeExact("daddy",'d','n');
            // invokeExact(Ljava/lang/String;CC)Ljava/lang/String;
            assertEquals(s, "nanny");
            // weakly typed invocation (using MHs.invoke)
            s = (String) mh.invokeWithArguments("sappy", 'p', 'v');
            assertEquals(s, "savvy");
            // mt is (Object[])List
            mt = MethodType.methodType(java.util.List.class, Object[].class);
            mh = lookup.findStatic(java.util.Arrays.class, "asList", mt);
            assert(mh.isVarargsCollector());
            x = mh.invoke("one", "two");
            // invoke(Ljava/lang/String;Ljava/lang/String;)Ljava/lang/Object;
            assertEquals(x, java.util.Arrays.asList("one","two"));
            // mt is (Object,Object,Object)Object
            mt = MethodType.genericMethodType(3);
            mh = mh.asType(mt);
            x = mh.invokeExact((Object)1, (Object)2, (Object)3);
            // invokeExact(Ljava/lang/Object;Ljava/lang/Object;Ljava/lang/Object;)Ljava/lang/Object;
            assertEquals(x, java.util.Arrays.asList(1,2,3));
            // mt is ()int
            mt = MethodType.methodType(int.class);
            mh = lookup.findVirtual(java.util.List.class, "size", mt);
            i = (int) mh.invokeExact(java.util.Arrays.asList(1,2,3));
            // invokeExact(Ljava/util/List;)I
            assert(i == 3);
            mt = MethodType.methodType(void.class, String.class);
            mh = lookup.findVirtual(java.io.PrintStream.class, "println", mt);
            mh.invokeExact(System.out, "Hello, world.");
            // invokeExact(Ljava/io/PrintStream;Ljava/lang/String;)V
            }

</blockquote> Chacun des appels ci-dessus vers invokeExact ou brut invoke génère une instruction invokevirtual unique avec le descripteur de type symbolique indiqué dans le commentaire suivant. Dans ces exemples, la méthode assertEquals d’assistance est supposée être une méthode qui appelle java.util.Objects#equals(Object,Object) Objects.equals ses arguments et affirme que le résultat est vrai.

<h1>Exceptions</h1> Les méthodes invokeExact et invoke sont déclarées à lever java.lang.Throwable Throwable, c’est-à-dire qu’il n’existe aucune restriction statique sur ce qu’un handle de méthode peut lever. Étant donné que la machine virtuelle JVM ne fait pas la distinction entre les exceptions vérifiées et non vérifiées (autres que par leur classe, bien sûr), il n’existe aucun effet particulier sur la forme bytecode d’une description des exceptions vérifiées pour gérer les appels de méthode. Toutefois, dans Java code source, les méthodes qui exécutent des appels de gestion de méthode doivent lever Throwableexplicitement, ou bien intercepter toutes les levées localement, en rerowing uniquement celles qui sont légales dans le contexte et encapsulant celles qui sont illégales.

<h1>"sigpoly">Polymorphisme< de signature/h1> Le comportement inhabituel de compilation et de liaison d’et de invokeExact brut invoke est référencé par le terme <>em signature polymorphisme</em>. Comme défini dans la spécification de langage Java, une méthode polymorphe de signature est une méthode qui peut fonctionner avec n’importe quel large éventail de signatures d’appel et de types de retour.

Dans le code source, un appel à une méthode polymorphe de signature est compilé, quel que soit le descripteur de type symbolique demandé. Comme d’habitude, le compilateur Java émet une invokevirtual instruction avec le descripteur de type symbolique donné par rapport à la méthode nommée. La partie inhabituelle est que le descripteur de type symbolique est dérivé de l’argument réel et des types de retour, et non de la déclaration de méthode.

Lorsque la machine virtuelle JVM traite le bytecode contenant des appels polymorphes de signature, elle lie correctement n’importe quel appel de ce type, quel que soit son descripteur de type symbolique. (Pour conserver la sécurité des types, la machine virtuelle JVM protège ces appels avec des vérifications de type dynamique appropriées, comme décrit ailleurs.)

Les générateurs bytecode, y compris le back-end du compilateur, sont nécessaires pour émettre des descripteurs de type symbolique non transformés pour ces méthodes. Les outils qui déterminent la liaison symbolique sont nécessaires pour accepter ces descripteurs non transformés, sans signaler d’erreurs de liaison.

<h1>Interoperation entre les handles de méthode et l’API< Core Reflection/h1> À l’aide de méthodes de fabrique dans l’API java.lang.invoke.MethodHandles.Lookup Lookup , tout membre de classe représenté par un objet API Core Reflection peut être converti en handle de méthode équivalent comportemental. Par exemple, une réflexion java.lang.reflect.Method Method peut être convertie en handle de méthode à l’aide java.lang.invoke.MethodHandles.Lookup#unreflect Lookup.unreflectde . Les handles de méthode résultants fournissent généralement un accès plus direct et efficace aux membres de classe sous-jacents.

En tant que cas spécial, lorsque l’API De réflexion principale est utilisée pour afficher les méthodes invokeExact polymorphes de signature ou simples invoke dans cette classe, elles apparaissent comme des méthodes non polymorphes ordinaires. Leur apparence réfléchissante, telle qu’elle est vue par java.lang.Class#getDeclaredMethod Class.getDeclaredMethod, n’est pas affectée par leur statut spécial dans cette API. Par exemple, java.lang.reflect.Method#getModifiers Method.getModifiers signale exactement ces bits de modificateur requis pour toute méthode déclarée de la même façon, y compris dans ce cas native et varargs les bits.

Comme avec n’importe quelle méthode réfléchie, ces méthodes (lorsqu’elles sont reflétées) peuvent être appelées via java.lang.reflect.Method#invoke java.lang.reflect.Method.invoke. Toutefois, ces appels réfléchissants n’entraînent pas d’appels de gestion de méthode. Un tel appel, s’il est passé l’argument requis (un seul, de type Object[]), ignore l’argument et lève un UnsupportedOperationException.

Étant donné que invokevirtual les instructions peuvent appeler en mode natif des handles de méthode sous n’importe quel descripteur de type symbolique, cette vue réfléchissante est en conflit avec la présentation normale de ces méthodes via des bytecodes. Ainsi, ces deux méthodes natives, lorsqu’elles sont réfléchies par Class.getDeclaredMethod, peuvent être considérées comme des espaces réservés uniquement.

Pour obtenir une méthode d’appelant pour un descripteur de type particulier, utilisez java.lang.invoke.MethodHandles#exactInvoker MethodHandles.exactInvokerou java.lang.invoke.MethodHandles#invoker MethodHandles.invoker. L’API java.lang.invoke.MethodHandles.Lookup#findVirtual Lookup.findVirtual est également en mesure de retourner un handle de méthode pour appeler invokeExact ou brut invoke, pour tout descripteur de type spécifié.

<L’interopérabilité h1>entre les handles de méthode et Java handles< de méthode génériques/h1> A peut être obtenue sur une méthode, un constructeur ou un champ déclaré avec Java types génériques. Comme avec l’API Core Reflection, le type du handle de méthode sera construit à partir de l’effacement du type de niveau source. Lorsqu’un handle de méthode est appelé, les types de ses arguments ou le type de conversion de valeur de retour peuvent être des types génériques ou des instances de type. Si cela se produit, le compilateur remplace ces types par leurs effacements lorsqu’il construit le descripteur de type symbolique pour l’instruction invokevirtual .

Les handles de méthode ne représentent pas leurs types de fonction en termes de types Java paramétrables (génériques), car il existe trois incompatibilités entre les types de type fonction et les types Java paramétrés. <Les types de méthode ul><li>s’étendent sur toutes les arités possibles, entre aucun argument et jusqu’au nombre maximal d’arguments autorisés. Les génériques ne sont pas varidiciques et ne peuvent donc pas représenter cela.<Les types de méthode /li><li>peuvent spécifier des arguments de types primitifs, qui Java types génériques ne peuvent pas dépasser la plage.</li li><>Les fonctions d’ordre supérieur sur les handles de méthode (combinateurs) sont souvent génériques sur un large éventail de types de fonctions, y compris ceux de plusieurs arités. Il est impossible de représenter une telle générique avec un paramètre de type Java.</li></ul>

<h1>"maxarity">Arity limits</h1> The JVM impose à toutes les méthodes et constructeurs de tout type une limite absolue de 255 arguments empilés. Cette limite peut apparaître plus restrictive dans certains cas : <ul><li>A long ou double nombre d’arguments (à des fins de limites d’arité) comme deux emplacements d’argument. <Li>Une méthode non statique consomme un argument supplémentaire pour l’objet sur lequel la méthode est appelée. <li>A constructeur consomme un argument supplémentaire pour l’objet qui est construit. <li>Since a method handle' la méthode s invoke (ou une autre méthode polymorphe de signature) n’est pas virtuelle, elle consomme un argument supplémentaire pour le handle de méthode lui-même, en plus de tout objet récepteur non virtuel. </ul> Ces limites impliquent que certains handles de méthode ne peuvent pas être créés uniquement en raison de la limite JVM sur les arguments empilés. Par exemple, si une méthode JVM statique accepte exactement 255 arguments, un handle de méthode ne peut pas être créé pour celui-ci. Les tentatives de création de handles de méthode avec des types de méthodes impossibles mènent à un IllegalArgumentException. En particulier, un handle de méthode' le type ne doit pas avoir une arité de la valeur maximale de 255.

Java documentation pour java.lang.invoke.MethodHandle.

Les parties de cette page sont des modifications basées sur le travail créé et partagé par Android Open Source et utilisées en fonction des termes décrits dans la Creative Commons 2.5 Attribution License.