1 /*

     2  * Copyright (c) 2015, Oracle and/or its affiliates. All rights reserved.

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     4  *

     5  * This code is free software; you can redistribute it and/or modify it

     6  * under the terms of the GNU General Public License version 2 only, as

     7  * published by the Free Software Foundation.  Oracle designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Oracle in the LICENSE file that accompanied this code.

    10  *

    11  * This code is distributed in the hope that it will be useful, but WITHOUT

    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

    14  * version 2 for more details (a copy is included in the LICENSE file that

    15  * accompanied this code).

    16  *

    17  * You should have received a copy of the GNU General Public License version

    18  * 2 along with this work; if not, write to the Free Software Foundation,

    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

    20  *

    21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

    22  * or visit www.oracle.com if you need additional information or have any

    23  * questions.

    24  */

    25 

    26 /*

    27  * This file is available under and governed by the GNU General Public

    28  * License version 2 only, as published by the Free Software Foundation.

    29  * However, the following notice accompanied the original version of this

    30  * file, and Oracle licenses the original version of this file under the BSD

    31  * license:

    32  */

    33 /*

    34    Copyright 2015 Attila Szegedi

    35 

    36    Licensed under both the Apache License, Version 2.0 (the "Apache License")

    37    and the BSD License (the "BSD License"), with licensee being free to

    38    choose either of the two at their discretion.

    39 

    40    You may not use this file except in compliance with either the Apache

    41    License or the BSD License.

    42 

    43    If you choose to use this file in compliance with the Apache License, the

    44    following notice applies to you:

    45 

    46        You may obtain a copy of the Apache License at

    47 

    48            http://www.apache.org/licenses/LICENSE-2.0

    49 

    50        Unless required by applicable law or agreed to in writing, software

    51        distributed under the License is distributed on an "AS IS" BASIS,

    52        WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or

    53        implied. See the License for the specific language governing

    54        permissions and limitations under the License.

    55 

    56    If you choose to use this file in compliance with the BSD License, the

    57    following notice applies to you:

    58 

    59        Redistribution and use in source and binary forms, with or without

    60        modification, are permitted provided that the following conditions are

    61        met:

    62        * Redistributions of source code must retain the above copyright

    63          notice, this list of conditions and the following disclaimer.

    64        * Redistributions in binary form must reproduce the above copyright

    65          notice, this list of conditions and the following disclaimer in the

    66          documentation and/or other materials provided with the distribution.

    67        * Neither the name of the copyright holder nor the names of

    68          contributors may be used to endorse or promote products derived from

    69          this software without specific prior written permission.

    70 

    71        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS

    72        IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED

    73        TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A

    74        PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL COPYRIGHT HOLDER

    75        BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR

    76        CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF

    77        SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR

    78        BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,

    79        WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR

    80        OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF

    81        ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

    82 */

    83 

    84 package jdk.dynalink;

    85 

    86 import java.util.Arrays;

    87 import java.util.Objects;

    88 

    89 /**

    90  * Describes an operation that is composed of at least two other operations. The

    91  * component operations are treated as alternatives to each other in order of

    92  * preference. The semantics of the composite operation is "first successful".

    93  * That is, a composite of {@code GET_PROPERTY|GET_ELEMENT:color} should be

    94  * interpreted as <i>get the property named "color" on the object, but if the

    95  * property does not exist, then get the collection element named "color"

    96  * instead</i>.

    97  * <p>

    98  * Composite operations are helpful in implementation of languages that

    99  * don't distinguish between one or more of the property, method, and element

   100  * namespaces, or when expressing operations against objects that can be

   101  * considered both ordinary objects and collections, e.g. Java

   102  * {@link java.util.Map} objects. A composite operation

   103  * {@code GET_PROPERTY|GET_ELEMENT:empty} against a Java map will always match

   104  * the {@link java.util.Map#isEmpty()} property, but

   105  * {@code GET_ELEMENT|GET_PROPERTY:empty} will actually match a map element with

   106  * key {@code "empty"} if the map contains that key, and only fall back to the

   107  * {@code isEmpty()} property getter if the map does not contain the key. If

   108  * the source language mandates this semantics, it can be easily achieved using

   109  * composite operations.

   110  * <p>

   111  * Even if the language itself doesn't distinguish between some of the

   112  * namespaces, it can be helpful to map different syntaxes to different

   113  * compositions. E.g. the source expression {@code obj.color} could map to

   114  * {@code GET_PROPERTY|GET_ELEMENT|GET_METHOD:color}, but a different source

   115  * expression that looks like collection element access {@code obj[key]} could

   116  * be expressed instead as {@code GET_ELEMENT|GET_PROPERTY|GET_METHOD}.

   117  * Finally, if the retrieved value is subsequently called, then it makes sense

   118  * to bring {@code GET_METHOD} to the front of the list: the getter part of the

   119  * source expression {@code obj.color()} should be

   120  * {@code GET_METHOD|GET_PROPERTY|GET_ELEMENT:color} and the one for

   121  * {@code obj[key]()} should be {@code GET_METHOD|GET_ELEMENT|GET_PROPERTY}.

   122  * <p>

   123  * The elements of a composite operation can not be composites or named

   124  * operations, but rather simple operations such are elements of

   125  * {@link StandardOperation}. A composite operation itself can serve as the base

   126  * operation of a named operation, though; a typical way to construct e.g. the

   127  * {@code GET_ELEMENT|GET_PROPERTY:empty} from above would be:

   128  * <pre>

   129  * Operation getElementOrPropertyEmpty = new NamedOperation(

   130  *     new CompositeOperation(

   131  *         StandardOperation.GET_ELEMENT,

   132  *         StandardOperation.GET_PROPERTY),

   133  *     "empty");

   134  * </pre>

   135  * <p>

   136  * Not all compositions make sense. Typically, any combination in any order of

   137  * standard getter operations {@code GET_PROPERTY}, {@code GET_ELEMENT}, and

   138  * {@code GET_METHOD} make sense, as do combinations of {@code SET_PROPERTY} and

   139  * {@code SET_ELEMENT}; other standard operations should not be combined. The

   140  * constructor will allow any combination of operations, though.

   141  */

   142 public final class CompositeOperation implements Operation {

   143     private final Operation[] operations;

   144 

   145     /**

   146      * Constructs a new composite operation.

   147      * @param operations the components for this composite operation. The passed

   148      * array will be cloned.

   149      * @throws IllegalArgumentException if less than two components are

   150      * specified, or any component is itself a {@link CompositeOperation} or a

   151      * {@link NamedOperation}.

   152      * @throws NullPointerException if either the operations array or any of its

   153      * elements are {@code null}.

   154      */

   155     public CompositeOperation(final Operation... operations) {

   156         Objects.requireNonNull(operations, "operations array is null");

   157         if (operations.length < 2) {

   158             throw new IllegalArgumentException("Must have at least two operations");

   159         }

   160         final Operation[] clonedOps = operations.clone();

   161         for(int i = 0; i < clonedOps.length; ++i) {

   162             final Operation op = clonedOps[i];

   163             if (op == null) {

   164                 throw new NullPointerException("operations[" + i + "] is null");

   165             } else if (op instanceof NamedOperation) {

   166                 throw new IllegalArgumentException("operations[" + i + "] is a NamedOperation");

   167             } else if (op instanceof CompositeOperation) {

   168                 throw new IllegalArgumentException("operations[" + i + "] is a CompositeOperation");

   169             }

   170         }

   171         this.operations = clonedOps;

   172     }

   173 

   174     /**

   175      * Returns the component operations in this composite operation. The

   176      * returned array is a copy and changes to it don't have effect on this

   177      * object.

   178      * @return the component operations in this composite operation.

   179      */

   180     public Operation[] getOperations() {

   181         return operations.clone();

   182     }

   183 

   184     /**

   185      * Returns the number of component operations in this composite operation.

   186      * @return the number of component operations in this composite operation.

   187      */

   188     public int getOperationCount() {

   189         return operations.length;

   190     }

   191 

   192     /**

   193      * Returns the i-th component operation in this composite operation.

   194      * @param i the operation index

   195      * @return the i-th component operation in this composite operation.

   196      * @throws IndexOutOfBoundsException if the index is out of range.

   197      */

   198     public Operation getOperation(final int i) {

   199         try {

   200             return operations[i];

   201         } catch (final ArrayIndexOutOfBoundsException e) {

   202             throw new IndexOutOfBoundsException(Integer.toString(i));

   203         }

   204     }

   205 

   206     /**

   207      * Returns true if this composite operation contains an operation equal to

   208      * the specified operation.

   209      * @param operation the operation being searched for. Must not be null.

   210      * @return true if the if this composite operation contains an operation

   211      * equal to the specified operation.

   212      */

   213     public boolean contains(final Operation operation) {

   214         Objects.requireNonNull(operation);

   215         for(final Operation component: operations) {

   216             if (component.equals(operation)) {

   217                 return true;

   218             }

   219         }

   220         return false;

   221     }

   222 

   223     /**

   224      * Returns true if the other object is also a composite operation and their

   225      * component operations are equal.

   226      * @param obj the object to compare to

   227      * @return true if this object is equal to the other one, false otherwise.

   228      */

   229     @Override

   230     public boolean equals(final Object obj) {

   231         if (obj instanceof CompositeOperation) {

   232             return Arrays.equals(operations, ((CompositeOperation)obj).operations);

   233         }

   234         return false;

   235     }

   236 

   237     /**

   238      * Returns the hash code of this composite operation. Defined to be equal

   239      * to {@code java.util.Arrays.hashCode(operations)}.

   240      */

   241     @Override

   242     public int hashCode() {

   243         return Arrays.hashCode(operations);

   244     };

   245 

   246     /**

   247      * Returns the string representation of this composite operation. Defined to

   248      * be the {@code toString} of its component operations, each separated by

   249      * the vertical line character (e.g. {@code "GET_PROPERTY|GET_ELEMENT"}).

   250      * @return the string representation of this composite operation.

   251      */

   252     @Override

   253     public String toString() {

   254         final StringBuilder b = new StringBuilder();

   255         b.append(operations[0]);

   256         for(int i = 1; i < operations.length; ++i) {

   257             b.append('|').append(operations[i]);

   258         }

   259         return b.toString();

   260     }

   261 

   262     /**

   263      * Returns the components of the passed operation if it is a composite

   264      * operation, otherwise returns an array containing the operation itself.

   265      * This allows for returning an array of component even if it is not known

   266      * whether the operation is itself a composite (treating a non-composite

   267      * operation as if it were a single-element composite of itself).

   268      * @param op the operation whose components are retrieved.

   269      * @return if the passed operation is a composite operation, returns its

   270      * {@link #getOperations()}, otherwise returns the operation itself.

   271      */

   272     public static Operation[] getOperations(final Operation op) {

   273         return op instanceof CompositeOperation

   274                 ? ((CompositeOperation)op).operations.clone()

   275                 : new Operation[] { op };

   276     }

   277 

   278     /**

   279      * Returns true if the specified potentially composite operation is a

   280      * {@link CompositeOperation} and contains an operation equal to the

   281      * specified operation. If {@code composite} is not a

   282      * {@link CompositeOperation}, then the two operations are compared for

   283      * equality.

   284      * @param composite the potentially composite operation. Must not be null.

   285      * @param operation the operation being searched for. Must not be null.

   286      * @return true if the if the passed operation is a

   287      * {@link CompositeOperation} and contains a component operation equal to

   288      * the specified operation, or if it is not a {@link CompositeOperation} and

   289      * is equal to {@code operation}.

   290      */

   291     public static boolean contains(final Operation composite, final Operation operation) {

   292         if (composite instanceof CompositeOperation) {

   293             return ((CompositeOperation)composite).contains(operation);

   294         }

   295         return composite.equals(Objects.requireNonNull(operation));

   296     }

   297 }