author | mbaesken |
Tue, 02 Jul 2019 13:45:08 +0200 | |
changeset 55556 | 19d0b382f086 |
parent 47216 | 71c04702a3d5 |
permissions | -rw-r--r-- |
34979
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
1 |
/* |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
2 |
* Copyright (c) 2015, Oracle and/or its affiliates. All rights reserved. |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
3 |
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
4 |
* |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
5 |
* This code is free software; you can redistribute it and/or modify it |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
6 |
* under the terms of the GNU General Public License version 2 only, as |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
7 |
* published by the Free Software Foundation. Oracle designates this |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
8 |
* particular file as subject to the "Classpath" exception as provided |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
9 |
* by Oracle in the LICENSE file that accompanied this code. |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
10 |
* |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
11 |
* This code is distributed in the hope that it will be useful, but WITHOUT |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
12 |
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
13 |
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
14 |
* version 2 for more details (a copy is included in the LICENSE file that |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
15 |
* accompanied this code). |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
16 |
* |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
17 |
* You should have received a copy of the GNU General Public License version |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
18 |
* 2 along with this work; if not, write to the Free Software Foundation, |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
19 |
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
20 |
* |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
21 |
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
22 |
* or visit www.oracle.com if you need additional information or have any |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
23 |
* questions. |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
24 |
*/ |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
25 |
|
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
26 |
package jdk.dynalink.beans; |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
27 |
|
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
28 |
import java.lang.invoke.MethodHandle; |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
29 |
import jdk.dynalink.DynamicLinkerFactory; |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
30 |
import jdk.dynalink.NamedOperation; |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
31 |
import jdk.dynalink.NoSuchDynamicMethodException; |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
32 |
import jdk.dynalink.StandardOperation; |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
33 |
import jdk.dynalink.linker.LinkRequest; |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
34 |
import jdk.dynalink.linker.LinkerServices; |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
35 |
|
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
36 |
/** |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
37 |
* A factory for creating method handles for linking missing member behavior |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
38 |
* in {@link BeansLinker}. BeansLinker links these method handles into guarded |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
39 |
* invocations for link requests specifying {@code GET_*} and {@code SET_*} |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
40 |
* {@link StandardOperation}s when it is either certain or possible that the |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
41 |
* requested member (property, method, or element) is missing. They will be |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
42 |
* linked both for {@link NamedOperation named} and unnamed operations. The |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
43 |
* implementer must ensure that the parameter types of the returned method |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
44 |
* handle match the parameter types of the call site described in the link |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
45 |
* request. The return types can differ, though, to allow |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
46 |
* {@link DynamicLinkerFactory#setPrelinkTransformer(jdk.dynalink.linker.GuardedInvocationTransformer)} |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
47 |
* late return type transformations}. It is allowed to return {@code null} for a |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
48 |
* method handle if the default behavior is sufficient. |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
49 |
* <h2>Default missing member behavior</h2> |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
50 |
* When a {@link BeansLinker} is configured without a missing member handler |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
51 |
* factory, or the factory returns {@code null} for a particular handler |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
52 |
* creation invocation, the default behavior is used. The default behavior is to |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
53 |
* return {@code null} from |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
54 |
* {@link BeansLinker#getGuardedInvocation(LinkRequest, LinkerServices)} when it |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
55 |
* can be determined at link time that the linked operation will never address |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
56 |
* an existing member. This lets the {@code DynamicLinker} attempt the next |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
57 |
* linker if there is one, or ultimately fail the link request with |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
58 |
* {@link NoSuchDynamicMethodException}. For other cases (typically all unnamed |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
59 |
* member operations as well as most named operations on collection elements) |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
60 |
* {@code BeansLinker} will produce a conditional linkage that will return |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
61 |
* {@code null} when invoked at runtime with a name that does not match any |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
62 |
* member for getters and silently ignore the passed values for setters. |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
63 |
* <h2>Implementing exception-throwing behavior</h2> |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
64 |
* Note that if the language-specific behavior for an operation on a missing |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
65 |
* member is to throw an exception then the factory should produce a method |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
66 |
* handle that throws the exception when invoked, and must not throw an |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
67 |
* exception itself, as the linkage for the missing member is often conditional. |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
68 |
* |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
69 |
* @see BeansLinker#BeansLinker(MissingMemberHandlerFactory) |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
70 |
*/ |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
71 |
@FunctionalInterface |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
72 |
public interface MissingMemberHandlerFactory { |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
73 |
/** |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
74 |
* Returns a method handle suitable for implementing missing member behavior |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
75 |
* for a particular link request. See the class description for details. |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
76 |
* @param linkRequest the current link request |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
77 |
* @param linkerServices the current link services |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
78 |
* @return a method handle that can be invoked if the property, element, or |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
79 |
* method being addressed by an operation is missing. The return value can |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
80 |
* be null. |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
81 |
* @throws Exception if the operation fails for any reason. Please observe |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
82 |
* the class documentation notes for implementing exception-throwing |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
83 |
* missing member behavior. |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
84 |
*/ |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
85 |
public MethodHandle createMissingMemberHandler(LinkRequest linkRequest, LinkerServices linkerServices) throws Exception; |
03b189baa361
8144919: Implement missing member handler for BeansLinker
attila
parents:
diff
changeset
|
86 |
} |