    001/*
    002 * Licensed to the Apache Software Foundation (ASF) under one or more
    003 * contributor license agreements.  See the NOTICE file distributed with
    004 * this work for additional information regarding copyright ownership.
    005 * The ASF licenses this file to You under the Apache License, Version 2.0
    006 * (the "License"); you may not use this file except in compliance with
    007 * the License.  You may obtain a copy of the License at
    008 *
    009 *     https://www.apache.org/licenses/LICENSE-2.0
    010 *
    011 * Unless required by applicable law or agreed to in writing, software
    012 * distributed under the License is distributed on an "AS IS" BASIS,
    013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    014 * See the License for the specific language governing permissions and
    015 * limitations under the License.
    016 */
    017package org.apache.commons.configuration2.tree.xpath;
    018
    019import java.util.Locale;
    020
    021import org.apache.commons.configuration2.tree.NodeHandler;
    022import org.apache.commons.jxpath.ri.QName;
    023import org.apache.commons.jxpath.ri.model.NodePointer;
    024import org.apache.commons.jxpath.ri.model.NodePointerFactory;
    025
    026/**
    027 * <p>
    028 * Implements the {@code NodePointerFactory} interface for configuration nodes.
    029 * </p>
    030 * <p>
    031 * This class is able to create {@code NodePointer}s for the nodes of hierarchical configurations. Because there is no
    032 * common base class for configuration nodes (any specific configuration implementation can use its own node class) a
    033 * trick is needed for activating this factory for a concrete JXPath query: The {@code wrapNode()} method has to be
    034 * called with the node object and its corresponding {@code NodeHandler}. This creates a wrapper object containing all
    035 * information required by the factory for processing a query. Then this wrapper object has to be passed to the query
    036 * methods of the JXPath context.
    037 * </p>
    038 *
    039 * @since 1.3
    040 */
    041public class ConfigurationNodePointerFactory implements NodePointerFactory {
    042    /**
    043     * An internally used wrapper class that holds all information for processing a query for a specific node.
    044     *
    045     * @param <T> the type of the nodes this class deals with
    046     */
    047    static class NodeWrapper<T> {
    048        /** Stores the node. */
    049        private final T node;
    050
    051        /** Stores the corresponding node handler. */
    052        private final NodeHandler<T> nodeHandler;
    053
    054        /**
    055         * Creates a new instance of {@code NodeWrapper} and initializes it.
    056         *
    057         * @param nd the node
    058         * @param handler the node handler
    059         */
    060        public NodeWrapper(final T nd, final NodeHandler<T> handler) {
    061            node = nd;
    062            nodeHandler = handler;
    063        }
    064
    065        /**
    066         * Gets the wrapped node.
    067         *
    068         * @return the node
    069         */
    070        public T getNode() {
    071            return node;
    072        }
    073
    074        /**
    075         * Gets the node handler for the wrapped node.
    076         *
    077         * @return the node handler
    078         */
    079        public NodeHandler<T> getNodeHandler() {
    080            return nodeHandler;
    081        }
    082    }
    083
    084    /** Constant for the order of this factory. */
    085    public static final int CONFIGURATION_NODE_POINTER_FACTORY_ORDER = 200;
    086
    087    /**
    088     * Creates a node wrapper for the specified node and its handler. This wrapper has to be passed to the JXPath context
    089     * instead of the original node.
    090     *
    091     * @param <T> the type of the node
    092     * @param node the node
    093     * @param handler the corresponding node handler
    094     * @return a wrapper for this node
    095     */
    096    public static <T> Object wrapNode(final T node, final NodeHandler<T> handler) {
    097        return new NodeWrapper<>(node, handler);
    098    }
    099
    100    /**
    101     * Constructs a new instance.
    102     */
    103    public ConfigurationNodePointerFactory() {
    104        // empty
    105    }
    106
    107    /**
    108     * Creates a node pointer for the specified bean. If the bean is a configuration node, a corresponding pointer is
    109     * returned.
    110     *
    111     * @param parent the parent node
    112     * @param qName the name
    113     * @param bean the bean
    114     * @return a pointer for a configuration node if the bean is such a node
    115     */
    116    @Override
    117    @SuppressWarnings("unchecked")
    118    /*
    119     * Type casts are safe here, see above. Also, the hierarchy of node pointers is consistent, so a parent is compatible to
    120     * a child.
    121     */
    122    public NodePointer createNodePointer(final NodePointer parent, final QName qName, final Object bean) {
    123        if (bean instanceof NodeWrapper) {
    124            final NodeWrapper<Object> wrapper = (NodeWrapper<Object>) bean;
    125            return new ConfigurationNodePointer<>((ConfigurationNodePointer<Object>) parent, wrapper.getNode(), wrapper.getNodeHandler());
    126        }
    127        return null;
    128    }
    129
    130    /**
    131     * Creates a node pointer for the specified bean. If the bean is a configuration node (indicated by a wrapper object), a
    132     * corresponding pointer is returned.
    133     *
    134     * @param qName the name of the node
    135     * @param bean the bean
    136     * @param locale the locale
    137     * @return a pointer for a configuration node if the bean is such a node
    138     */
    139    @Override
    140    @SuppressWarnings("unchecked")
    141    /*
    142     * Type casts are safe here; because of the way the NodeWrapper was constructed the node handler must be compatible with
    143     * the node.
    144     */
    145    public NodePointer createNodePointer(final QName qName, final Object bean, final Locale locale) {
    146        if (bean instanceof NodeWrapper) {
    147            final NodeWrapper<Object> wrapper = (NodeWrapper<Object>) bean;
    148            return new ConfigurationNodePointer<>(wrapper.getNode(), locale, wrapper.getNodeHandler());
    149        }
    150        return null;
    151    }
    152
    153    /**
    154     * Gets the order of this factory between other factories.
    155     *
    156     * @return this order's factory
    157     */
    158    @Override
    159    public int getOrder() {
    160        return CONFIGURATION_NODE_POINTER_FACTORY_ORDER;
    161    }
    162}