84 package jdk.dynalink; |
84 package jdk.dynalink; |
85 |
85 |
86 /** |
86 /** |
87 * An object that describes a dynamic operation. Dynalink defines a set of |
87 * An object that describes a dynamic operation. Dynalink defines a set of |
88 * standard operations with the {@link StandardOperation} class, as well as a |
88 * standard operations with the {@link StandardOperation} class, as well as a |
89 * way to attach a fixed name to an operation using {@link NamedOperation} and |
89 * way to express the target {@link Namespace namespace(s)} of an operation |
90 * to express a set of alternative operations using {@link CompositeOperation}. |
90 * on an object using {@link NamespaceOperation} and finally a way to attach |
|
91 * a fixed target name to an operation using {@link NamedOperation}. |
91 * When presenting examples in this documentation, we will refer to standard |
92 * When presenting examples in this documentation, we will refer to standard |
92 * operations using their name (e.g. {@code GET_PROPERTY}), to composite |
93 * operations using their name (e.g. {@code GET}), to namespace operations |
93 * operations by separating their components with the vertical line character |
94 * by separating their base operation with a colon from their namespace |
94 * (e.g. {@code GET_PROPERTY|GET_ELEMENT}), and finally to named operations by |
95 * (e.g. {@code GET:PROPERTY}), or in case of multiple namespaces we will |
95 * separating the base operation and the name with the colon character (e.g. |
96 * further separate those with the vertical line character (e.g. |
96 * {@code GET_PROPERTY|GET_ELEMENT:color}). |
97 * {@code GET:PROPERTY|ELEMENT}), and finally we will refer to named operations |
|
98 * by separating the base operation and the name with the colon character (e.g. |
|
99 * {@code GET:PROPERTY|ELEMENT:color}). |
97 */ |
100 */ |
98 public interface Operation { |
101 public interface Operation { |
|
102 /** |
|
103 * Returns a {@link NamespaceOperation} using this operation as its base. |
|
104 * @param namespace the namespace that is the target of the namespace operation. |
|
105 * @return a {@link NamespaceOperation} with this operation as its base and the specified |
|
106 * namespace as its target. |
|
107 * @throws IllegalArgumentException if this operation is already a namespace operation or a named operation. |
|
108 * @throws NullPointerException if {@code namespace} is null. |
|
109 */ |
|
110 default NamespaceOperation withNamespace(final Namespace namespace) { |
|
111 return withNamespaces(namespace); |
|
112 } |
|
113 |
|
114 /** |
|
115 * Returns a {@link NamespaceOperation} using this operation as its base. |
|
116 * @param namespaces the namespaces that are the target of the namespace operation. |
|
117 * @return a {@link NamespaceOperation} with this operation as its base and the specified |
|
118 * namespaces as its targets. |
|
119 * @throws IllegalArgumentException if this operation is already a namespace operation or a named operation. |
|
120 * @throws NullPointerException if {@code namespace} or any of its elements is null. |
|
121 */ |
|
122 default NamespaceOperation withNamespaces(final Namespace... namespaces) { |
|
123 return new NamespaceOperation(this, namespaces); |
|
124 } |
|
125 |
|
126 /** |
|
127 * Returns a {@link NamedOperation} using this operation as its base. |
|
128 * @param name the name that is the target of the named operation. |
|
129 * @return a {@link NamedOperation} with this operation as its base and the specified name. |
|
130 * @throws IllegalArgumentException if this operation is already a named operation. |
|
131 * @throws NullPointerException if {@code name} is null. |
|
132 */ |
|
133 default NamedOperation named(final Object name) { |
|
134 return new NamedOperation(this, name); |
|
135 } |
99 } |
136 } |