--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/nashorn/src/jdk.dynalink/share/classes/jdk/dynalink/CompositeOperation.java Tue Nov 24 10:19:34 2015 +0100
@@ -0,0 +1,297 @@
+/*
+ * Copyright (c) 2015, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation. Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+/*
+ * This file is available under and governed by the GNU General Public
+ * License version 2 only, as published by the Free Software Foundation.
+ * However, the following notice accompanied the original version of this
+ * file, and Oracle licenses the original version of this file under the BSD
+ * license:
+ */
+/*
+ Copyright 2015 Attila Szegedi
+
+ Licensed under both the Apache License, Version 2.0 (the "Apache License")
+ and the BSD License (the "BSD License"), with licensee being free to
+ choose either of the two at their discretion.
+
+ You may not use this file except in compliance with either the Apache
+ License or the BSD License.
+
+ If you choose to use this file in compliance with the Apache License, the
+ following notice applies to you:
+
+ You may obtain a copy of the Apache License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied. See the License for the specific language governing
+ permissions and limitations under the License.
+
+ If you choose to use this file in compliance with the BSD License, the
+ following notice applies to you:
+
+ Redistribution and use in source and binary forms, with or without
+ modification, are permitted provided that the following conditions are
+ met:
+ * Redistributions of source code must retain the above copyright
+ notice, this list of conditions and the following disclaimer.
+ * Redistributions in binary form must reproduce the above copyright
+ notice, this list of conditions and the following disclaimer in the
+ documentation and/or other materials provided with the distribution.
+ * Neither the name of the copyright holder nor the names of
+ contributors may be used to endorse or promote products derived from
+ this software without specific prior written permission.
+
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+ IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+ TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+ PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL COPYRIGHT HOLDER
+ BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
+ BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
+ WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
+ OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
+ ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+*/
+
+package jdk.dynalink;
+
+import java.util.Arrays;
+import java.util.Objects;
+
+/**
+ * Describes an operation that is composed of at least two other operations. The
+ * component operations are treated as alternatives to each other in order of
+ * preference. The semantics of the composite operation is "first successful".
+ * That is, a composite of {@code GET_PROPERTY|GET_ELEMENT:color} should be
+ * interpreted as <i>get the property named "color" on the object, but if the
+ * property does not exist, then get the collection element named "color"
+ * instead</i>.
+ * <p>
+ * Composite operations are helpful in implementation of languages that
+ * don't distinguish between one or more of the property, method, and element
+ * namespaces, or when expressing operations against objects that can be
+ * considered both ordinary objects and collections, e.g. Java
+ * {@link java.util.Map} objects. A composite operation
+ * {@code GET_PROPERTY|GET_ELEMENT:empty} against a Java map will always match
+ * the {@link java.util.Map#isEmpty()} property, but
+ * {@code GET_ELEMENT|GET_PROPERTY:empty} will actually match a map element with
+ * key {@code "empty"} if the map contains that key, and only fall back to the
+ * {@code isEmpty()} property getter if the map does not contain the key. If
+ * the source language mandates this semantics, it can be easily achieved using
+ * composite operations.
+ * <p>
+ * Even if the language itself doesn't distinguish between some of the
+ * namespaces, it can be helpful to map different syntaxes to different
+ * compositions. E.g. the source expression {@code obj.color} could map to
+ * {@code GET_PROPERTY|GET_ELEMENT|GET_METHOD:color}, but a different source
+ * expression that looks like collection element access {@code obj[key]} could
+ * be expressed instead as {@code GET_ELEMENT|GET_PROPERTY|GET_METHOD}.
+ * Finally, if the retrieved value is subsequently called, then it makes sense
+ * to bring {@code GET_METHOD} to the front of the list: the getter part of the
+ * source expression {@code obj.color()} should be
+ * {@code GET_METHOD|GET_PROPERTY|GET_ELEMENT:color} and the one for
+ * {@code obj[key]()} should be {@code GET_METHOD|GET_ELEMENT|GET_PROPERTY}.
+ * <p>
+ * The elements of a composite operation can not be composites or named
+ * operations, but rather simple operations such are elements of
+ * {@link StandardOperation}. A composite operation itself can serve as the base
+ * operation of a named operation, though; a typical way to construct e.g. the
+ * {@code GET_ELEMENT|GET_PROPERTY:empty} from above would be:
+ * <pre>
+ * Operation getElementOrPropertyEmpty = new NamedOperation(
+ * new CompositeOperation(
+ * StandardOperation.GET_ELEMENT,
+ * StandardOperation.GET_PROPERTY),
+ * "empty");
+ * </pre>
+ * <p>
+ * Not all compositions make sense. Typically, any combination in any order of
+ * standard getter operations {@code GET_PROPERTY}, {@code GET_ELEMENT}, and
+ * {@code GET_METHOD} make sense, as do combinations of {@code SET_PROPERTY} and
+ * {@code SET_ELEMENT}; other standard operations should not be combined. The
+ * constructor will allow any combination of operations, though.
+ */
+public final class CompositeOperation implements Operation {
+ private final Operation[] operations;
+
+ /**
+ * Constructs a new composite operation.
+ * @param operations the components for this composite operation. The passed
+ * array will be cloned.
+ * @throws IllegalArgumentException if less than two components are
+ * specified, or any component is itself a {@link CompositeOperation} or a
+ * {@link NamedOperation}.
+ * @throws NullPointerException if either the operations array or any of its
+ * elements are {@code null}.
+ */
+ public CompositeOperation(final Operation... operations) {
+ Objects.requireNonNull(operations, "operations array is null");
+ if (operations.length < 2) {
+ throw new IllegalArgumentException("Must have at least two operations");
+ }
+ final Operation[] clonedOps = operations.clone();
+ for(int i = 0; i < clonedOps.length; ++i) {
+ final Operation op = clonedOps[i];
+ if (op == null) {
+ throw new NullPointerException("operations[" + i + "] is null");
+ } else if (op instanceof NamedOperation) {
+ throw new IllegalArgumentException("operations[" + i + "] is a NamedOperation");
+ } else if (op instanceof CompositeOperation) {
+ throw new IllegalArgumentException("operations[" + i + "] is a CompositeOperation");
+ }
+ }
+ this.operations = clonedOps;
+ }
+
+ /**
+ * Returns the component operations in this composite operation. The
+ * returned array is a copy and changes to it don't have effect on this
+ * object.
+ * @return the component operations in this composite operation.
+ */
+ public Operation[] getOperations() {
+ return operations.clone();
+ }
+
+ /**
+ * Returns the number of component operations in this composite operation.
+ * @return the number of component operations in this composite operation.
+ */
+ public int getOperationCount() {
+ return operations.length;
+ }
+
+ /**
+ * Returns the i-th component operation in this composite operation.
+ * @param i the operation index
+ * @return the i-th component operation in this composite operation.
+ * @throws IndexOutOfBoundsException if the index is out of range.
+ */
+ public Operation getOperation(final int i) {
+ try {
+ return operations[i];
+ } catch (final ArrayIndexOutOfBoundsException e) {
+ throw new IndexOutOfBoundsException(Integer.toString(i));
+ }
+ }
+
+ /**
+ * Returns true if this composite operation contains an operation equal to
+ * the specified operation.
+ * @param operation the operation being searched for. Must not be null.
+ * @return true if the if this composite operation contains an operation
+ * equal to the specified operation.
+ */
+ public boolean contains(final Operation operation) {
+ Objects.requireNonNull(operation);
+ for(final Operation component: operations) {
+ if (component.equals(operation)) {
+ return true;
+ }
+ }
+ return false;
+ }
+
+ /**
+ * Returns true if the other object is also a composite operation and their
+ * component operations are equal.
+ * @param obj the object to compare to
+ * @return true if this object is equal to the other one, false otherwise.
+ */
+ @Override
+ public boolean equals(final Object obj) {
+ if (obj instanceof CompositeOperation) {
+ return Arrays.equals(operations, ((CompositeOperation)obj).operations);
+ }
+ return false;
+ }
+
+ /**
+ * Returns the hash code of this composite operation. Defined to be equal
+ * to {@code java.util.Arrays.hashCode(operations)}.
+ */
+ @Override
+ public int hashCode() {
+ return Arrays.hashCode(operations);
+ };
+
+ /**
+ * Returns the string representation of this composite operation. Defined to
+ * be the {@code toString} of its component operations, each separated by
+ * the vertical line character (e.g. {@code "GET_PROPERTY|GET_ELEMENT"}).
+ * @return the string representation of this composite operation.
+ */
+ @Override
+ public String toString() {
+ final StringBuilder b = new StringBuilder();
+ b.append(operations[0]);
+ for(int i = 1; i < operations.length; ++i) {
+ b.append('|').append(operations[i]);
+ }
+ return b.toString();
+ }
+
+ /**
+ * Returns the components of the passed operation if it is a composite
+ * operation, otherwise returns an array containing the operation itself.
+ * This allows for returning an array of component even if it is not known
+ * whether the operation is itself a composite (treating a non-composite
+ * operation as if it were a single-element composite of itself).
+ * @param op the operation whose components are retrieved.
+ * @return if the passed operation is a composite operation, returns its
+ * {@link #getOperations()}, otherwise returns the operation itself.
+ */
+ public static Operation[] getOperations(final Operation op) {
+ return op instanceof CompositeOperation
+ ? ((CompositeOperation)op).operations.clone()
+ : new Operation[] { op };
+ }
+
+ /**
+ * Returns true if the specified potentially composite operation is a
+ * {@link CompositeOperation} and contains an operation equal to the
+ * specified operation. If {@code composite} is not a
+ * {@link CompositeOperation}, then the two operations are compared for
+ * equality.
+ * @param composite the potentially composite operation. Must not be null.
+ * @param operation the operation being searched for. Must not be null.
+ * @return true if the if the passed operation is a
+ * {@link CompositeOperation} and contains a component operation equal to
+ * the specified operation, or if it is not a {@link CompositeOperation} and
+ * is equal to {@code operation}.
+ */
+ public static boolean contains(final Operation composite, final Operation operation) {
+ if (composite instanceof CompositeOperation) {
+ return ((CompositeOperation)composite).contains(operation);
+ }
+ return composite.equals(Objects.requireNonNull(operation));
+ }
+}