1 /*

     2  * Copyright (c) 2016, 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 2016 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 operates on at least one {@link Namespace} of

    91  * an object. E.g. a property getter would be described as

    92  * <pre>

    93  * Operation propertyGetter = new NamespaceOperation(

    94  *     StandardOperation.GET,

    95  *     StandardNamespace.PROPERTY);

    96  * </pre>

    97  * They are often combined with {@link NamedOperation}, e.g. to express a

    98  * property getter for a property named "color", you would construct:

    99  * <pre>

   100  * Operation colorPropertyGetter = new NamedOperation(

   101  *     new NamespaceOperation(

   102  *         StandardOperation.GET,

   103  *         StandardNamespace.PROPERTY),

   104  *     "color");

   105  * </pre>

   106  * <p>While {@code NamespaceOperation} can be constructed directly, it is often convenient

   107  * to use the {@link Operation#withNamespace(Namespace)} and {@link Operation#withNamespaces(Namespace...)} factory

   108  * methods instead, e.g.:

   109  * <pre>

   110  * Operation getElementOrPropertyEmpty =

   111  *     StandardOperation.GET

   112  *         .withNamespace(StandardNamespace.PROPERTY)

   113  *         .named("color");

   114  * </pre>

   115  * <h3>Operations on multiple namespaces</h3>

   116  * If multiple namespaces are specified, the namespaces are treated as

   117  * alternatives to each other in order of preference. The semantics of

   118  * such operation is "first applicable".

   119  * That is, a composite of {@code GET:PROPERTY|ELEMENT:color} should be

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

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

   122  * instead</i>.

   123  * <p>

   124  * Operations with multiple namespaces are helpful in implementation of languages that

   125  * don't distinguish between one or more of the namespaces, or when expressing operations

   126  * against objects that can be considered both ordinary objects and collections, e.g. Java

   127  * {@link java.util.Map} objects. A {@code GET:PROPERTY|ELEMENT:empty} operation

   128  * against a Java map will always match

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

   130  * {@code GET:ELEMENT|PROPERTY:empty} will actually match a map element with

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

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

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

   134  * operations on multiple namespaces.

   135  * <p>

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

   137  * namespaces, it can be helpful to map different syntaxes to different namespace orderings.

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

   139  * {@code GET:PROPERTY|ELEMENT|METHOD:color}, but a different source

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

   141  * be expressed instead as {@code GET:ELEMENT|PROPERTY|METHOD} in order to favor the

   142  * element semantics. Finally, if the retrieved value is subsequently called, then it makes sense

   143  * to bring {@code METHOD} to the front of the namespace list: the getter part of the

   144  * source expression {@code obj.color()} could be

   145  * {@code GET:METHOD|PROPERTY|ELEMENT:color} and the one for

   146  * {@code obj[key]()} could be {@code GET:METHOD|ELEMENT|PROPERTY}.

   147  * <p>

   148  * The base operation of a namespace operation can not itself be a namespace or named

   149  * operation, but rather one of simple operations such are elements of

   150  * {@link StandardOperation}. A namespace operation itself can serve as the base

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

   152  * {@code GET:ELEMENT|PROPERTY:empty} from above would be:

   153  * <pre>

   154  * Operation getElementOrPropertyEmpty = StandardOperation.GET

   155  *     .withNamespaces(

   156  *         StandardNamespace.ELEMENT,

   157  *         StandardNamespace.PROPERTY)

   158  *     .named("empty");

   159  * </pre>

   160  */

   161 public final class NamespaceOperation implements Operation {

   162     private final Operation baseOperation;

   163     private final Namespace[] namespaces;

   164 

   165     /**

   166      * Constructs a new namespace operation.

   167      * @param baseOperation the base operation that operates on one or more namespaces.

   168      * @param namespaces one or more namespaces this operation operates on.

   169      * @throws IllegalArgumentException if less than one namespace is

   170      * specified, or the base operation is itself a {@link NamespaceOperation} or a

   171      * {@link NamedOperation}.

   172      * @throws NullPointerException if either the {@code namespaces} array or any of its

   173      * elements are {@code null}, or if {@code baseOperation} is {@code null}.

   174      */

   175     public NamespaceOperation(final Operation baseOperation, final Namespace... namespaces) {

   176         this.baseOperation = Objects.requireNonNull(baseOperation, "baseOperation is null");

   177         if (baseOperation instanceof NamedOperation) {

   178             throw new IllegalArgumentException("baseOperation is a NamedOperation");

   179         } else if (baseOperation instanceof NamespaceOperation) {

   180            throw new IllegalArgumentException("baseOperation is a NamespaceOperation");

   181         }

   182 

   183         this.namespaces = Objects.requireNonNull(namespaces, "namespaces array is null").clone();

   184         if (namespaces.length < 1) {

   185             throw new IllegalArgumentException("Must specify at least one namespace");

   186         }

   187         for(int i = 0; i < namespaces.length; ++i) {

   188             final int fi = i;

   189             Objects.requireNonNull(namespaces[i], () -> "operations[" + fi + "] is null");

   190         }

   191     }

   192 

   193     /**

   194      * Returns the base operation of this named operation.

   195      * @return the base operation of this named operation.

   196      */

   197     public Operation getBaseOperation() {

   198         return baseOperation;

   199     }

   200 

   201     /**

   202      * Returns the namespaces in this namespace operation. The returned

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

   204      * object.

   205      * @return the namespaces in this namespace operation.

   206      */

   207     public Namespace[] getNamespaces() {

   208         return namespaces.clone();

   209     }

   210 

   211     /**

   212      * Returns the number of namespaces in this namespace operation.

   213      * @return the number of namespaces in this namespace operation.

   214      */

   215     public int getNamespaceCount() {

   216         return namespaces.length;

   217     }

   218 

   219     /**

   220      * Returns the i-th namespace in this namespace operation.

   221      * @param i the namespace index

   222      * @return the i-th namespace in this namespace operation.

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

   224      */

   225     public Namespace getNamespace(final int i) {

   226         try {

   227             return namespaces[i];

   228         } catch (final ArrayIndexOutOfBoundsException e) {

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

   230         }

   231     }

   232 

   233     /**

   234      * Returns true if this namespace operation contains a namespace equal to

   235      * the specified namespace.

   236      * @param namespace the namespace being searched for. Must not be null.

   237      * @return true if the if this namespace operation contains a namespace

   238      * equal to the specified namespace.

   239      */

   240     public boolean contains(final Namespace namespace) {

   241         Objects.requireNonNull(namespace);

   242         for(final Namespace component: namespaces) {

   243             if (component.equals(namespace)) {

   244                 return true;

   245             }

   246         }

   247         return false;

   248     }

   249 

   250     /**

   251      * Returns true if the other object is also a namespace operation and their

   252      * base operation and namespaces are equal.

   253      * @param obj the object to compare to

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

   255      */

   256     @Override

   257     public boolean equals(final Object obj) {

   258         if (obj instanceof NamespaceOperation) {

   259             final NamespaceOperation other = (NamespaceOperation)obj;

   260             return baseOperation.equals(other.baseOperation) && Arrays.equals(namespaces, other.namespaces);

   261         }

   262         return false;

   263     }

   264 

   265     /**

   266      * Returns the hash code of this namespace operation. Defined to be equal

   267      * to {@code baseOperation.hashCode() + 31 * Arrays.hashCode(namespaces)}.

   268      */

   269     @Override

   270     public int hashCode() {

   271         return baseOperation.hashCode() + 31 * Arrays.hashCode(namespaces);

   272     };

   273 

   274     /**

   275      * Returns the string representation of this namespace operation. Defined to

   276      * be the {@code toString} of its base operation, followed by a colon character,

   277      * followed with the list of its namespaces separated with the vertical line

   278      * character (e.g. {@code "GET:PROPERTY|ELEMENT"}).

   279      * @return the string representation of this namespace operation.

   280      */

   281     @Override

   282     public String toString() {

   283         final StringBuilder b = new StringBuilder();

   284         b.append(baseOperation).append(':');

   285         b.append(namespaces[0]);

   286         for(int i = 1; i < namespaces.length; ++i) {

   287             b.append('|').append(namespaces[i]);

   288         }

   289         return b.toString();

   290     }

   291 

   292     /**

   293      * If the passed operation is a namespace operation, returns its

   294      * {@link #getBaseOperation()}, otherwise returns the operation as is.

   295      * @param op the operation

   296      * @return the base operation of the passed operation.

   297      */

   298     public static Operation getBaseOperation(final Operation op) {

   299         return op instanceof NamespaceOperation ? ((NamespaceOperation )op).getBaseOperation() : op;

   300     }

   301 

   302     /**

   303      * If the passed operation is a namespace operation, returns its

   304      * {@link #getNamespaces()}, otherwise returns an empty array.

   305      * @param op the operation

   306      * @return the namespaces of the passed operation.

   307      */

   308     public static Namespace[] getNamespaces(final Operation op) {

   309         return op instanceof NamespaceOperation ? ((NamespaceOperation)op).getNamespaces() : new Namespace[0];

   310     }

   311 

   312     /**

   313      * Returns true if the specified operation is a {@link NamespaceOperation}

   314      * and its base operation is equal to the specified operation, and it

   315      * contains the specified namespace. If it is not a {@link NamespaceOperation},

   316      * then it returns false.

   317      * @param op the operation. Must not be null.

   318      * @param baseOperation the base operation being searched for. Must not be null.

   319      * @param namespace the namespace being searched for. Must not be null.

   320      * @return true if the if the passed operation is a {@link NamespaceOperation},

   321      * its base operation equals the searched base operation, and contains a namespace

   322      * equal to the searched namespace.

   323      */

   324     public static boolean contains(final Operation op, final Operation baseOperation, final Namespace namespace) {

   325         if (op instanceof NamespaceOperation) {

   326             final NamespaceOperation no = (NamespaceOperation)op;

   327             return no.baseOperation.equals(baseOperation) && no.contains(namespace);

   328         }

   329         return false;

   330     }

   331 }