/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the 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.
 */
package org.apache.maven.api.xml;

import java.util.List;
import java.util.Map;

import org.apache.maven.api.annotations.Experimental;
import org.apache.maven.api.annotations.Immutable;
import org.apache.maven.api.annotations.Nonnull;
import org.apache.maven.api.annotations.Nullable;
import org.apache.maven.api.annotations.ThreadSafe;

/**
 * An immutable XML node, based on Plexus Utils mutable
 * <a href="https://codehaus-plexus.github.io/plexus-utils/apidocs/org/codehaus/plexus/util/xml/Xpp3Dom.html">Xpp3Dom</a>.
 *
 * @since 4.0
 */
@Experimental
@ThreadSafe
@Immutable
public interface Dom {

    String CHILDREN_COMBINATION_MODE_ATTRIBUTE = "combine.children";

    String CHILDREN_COMBINATION_MERGE = "merge";

    String CHILDREN_COMBINATION_APPEND = "append";

    /**
     * This default mode for combining children DOMs during merge means that where element names match, the process will
     * try to merge the element data, rather than putting the dominant and recessive elements (which share the same
     * element name) as siblings in the resulting DOM.
     */
    String DEFAULT_CHILDREN_COMBINATION_MODE = CHILDREN_COMBINATION_MERGE;

    String SELF_COMBINATION_MODE_ATTRIBUTE = "combine.self";

    String SELF_COMBINATION_OVERRIDE = "override";

    String SELF_COMBINATION_MERGE = "merge";

    String SELF_COMBINATION_REMOVE = "remove";

    /**
     * In case of complex XML structures, combining can be done based on id.
     */
    String ID_COMBINATION_MODE_ATTRIBUTE = "combine.id";

    /**
     * In case of complex XML structures, combining can be done based on keys.
     * This is a comma separated list of attribute names.
     */
    String KEYS_COMBINATION_MODE_ATTRIBUTE = "combine.keys";

    /**
     * This default mode for combining a DOM node during merge means that where element names match, the process will
     * try to merge the element attributes and values, rather than overriding the recessive element completely with the
     * dominant one. This means that wherever the dominant element doesn't provide the value or a particular attribute,
     * that value or attribute will be set from the recessive DOM node.
     */
    String DEFAULT_SELF_COMBINATION_MODE = SELF_COMBINATION_MERGE;

    @Nonnull
    String getName();

    @Nullable
    String getValue();

    @Nonnull
    Map<String, String> getAttributes();

    @Nullable
    String getAttribute(@Nonnull String name);

    @Nonnull
    List<Dom> getChildren();

    @Nullable
    Dom getChild(String name);

    @Nullable
    Object getInputLocation();

    default Dom merge(@Nullable Dom source) {
        return merge(source, (Boolean) null);
    }

    Dom merge(@Nullable Dom source, @Nullable Boolean childMergeOverride);

    Dom clone();

    /**
     * Merge recessive into dominant and return either {@code dominant}
     * with merged information or a clone of {@code recessive} if
     * {@code dominant} is {@code null}.
     *
     * @param dominant the node
     * @param recessive if {@code null}, nothing will happen
     * @return the merged node
     */
    @Nullable
    static Dom merge(@Nullable Dom dominant, @Nullable Dom recessive) {
        return merge(dominant, recessive, null);
    }

    @Nullable
    static Dom merge(@Nullable Dom dominant, @Nullable Dom recessive, @Nullable Boolean childMergeOverride) {
        if (recessive == null) {
            return dominant;
        }
        if (dominant == null) {
            return recessive;
        }
        return dominant.merge(recessive, childMergeOverride);
    }
}