/*

 * Copyright (c) 2016, 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 2016 Attila Szegedi

*/

package jdk.dynalink;

import java.util.Arrays;

import java.util.Objects;

/**

 * Describes an operation that operates on at least one {@link Namespace} of

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

 * <pre>

 * Operation propertyGetter = new NamespaceOperation(

 *     StandardOperation.GET,

 *     StandardNamespace.PROPERTY);

 * </pre>

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

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

 * <pre>

 * Operation colorPropertyGetter = new NamedOperation(

 *     new NamespaceOperation(

 *         StandardOperation.GET,

 *         StandardNamespace.PROPERTY),

 *     "color");

 * </pre>

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

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

 * methods instead, e.g.:

 * <pre>

 * Operation getElementOrPropertyEmpty =

 *     StandardOperation.GET

 *         .withNamespace(StandardNamespace.PROPERTY)

 *         .named("color");

 * </pre>

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

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

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

 * such operation is "first applicable".

 * That is, a composite of {@code GET:PROPERTY|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>

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

 * don't distinguish between one or more of the 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 {@code GET:PROPERTY|ELEMENT:empty} operation

 * against a Java map will always match

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

 * {@code GET:ELEMENT|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

 * operations on multiple namespaces.

 * <p>

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

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

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

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

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

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

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

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

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

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

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

 * <p>

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

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

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

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

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

 * <pre>

 * Operation getElementOrPropertyEmpty = StandardOperation.GET

 *     .withNamespaces(

 *         StandardNamespace.ELEMENT,

 *         StandardNamespace.PROPERTY)

 *     .named("empty");

 * </pre>

 */

public final class NamespaceOperation implements Operation {

    private final Operation baseOperation;

    private final Namespace[] namespaces;

    /**

     * Constructs a new namespace operation.

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

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

     * @throws IllegalArgumentException if less than one namespace is

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

     * {@link NamedOperation}.

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

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

     */

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

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

        if (baseOperation instanceof NamedOperation) {

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

        } else if (baseOperation instanceof NamespaceOperation) {

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

        }

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

        if (namespaces.length < 1) {

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

        }

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

            final int fi = i;

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

        }

    }

    /**

     * Returns the base operation of this named operation.

     * @return the base operation of this named operation.

     */

    public Operation getBaseOperation() {

        return baseOperation;

    }

    /**

     * Returns the namespaces in this namespace operation. The returned

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

     * object.

     * @return the namespaces in this namespace operation.

     */

    public Namespace[] getNamespaces() {

        return namespaces.clone();

    }

    /**

     * Returns the number of namespaces in this namespace operation.

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

     */

    public int getNamespaceCount() {

        return namespaces.length;

    }

    /**

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

     * @param i the namespace index

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

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

     */

    public Namespace getNamespace(final int i) {

        try {

            return namespaces[i];

        } catch (final ArrayIndexOutOfBoundsException e) {

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

        }

    }

    /**

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

     * the specified namespace.

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

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

     * equal to the specified namespace.

     */

    public boolean contains(final Namespace namespace) {

        Objects.requireNonNull(namespace);

        for(final Namespace component: namespaces) {

            if (component.equals(namespace)) {

                return true;

            }

        }

        return false;

    }

    /**

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

     * base operation and namespaces 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 NamespaceOperation) {

            final NamespaceOperation other = (NamespaceOperation)obj;

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

        }

        return false;

    }

    /**

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

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

     */

    @Override

    public int hashCode() {

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

    };

    /**

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

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

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

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

     * @return the string representation of this namespace operation.

     */

    @Override

    public String toString() {

        final StringBuilder b = new StringBuilder();

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

        b.append(namespaces[0]);

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

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

        }

        return b.toString();

    }

    /**

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

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

     * @param op the operation

     * @return the base operation of the passed operation.

     */

    public static Operation getBaseOperation(final Operation op) {

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

    }

    /**

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

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

     * @param op the operation

     * @return the namespaces of the passed operation.

     */

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

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

    }

    /**

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

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

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

     * then it returns false.

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

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

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

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

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

     * equal to the searched namespace.

     */

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

        if (op instanceof NamespaceOperation) {

            final NamespaceOperation no = (NamespaceOperation)op;

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

        }

        return false;

    }

}