com.jayway.restassured.path.xml.element.PathElement Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of xml-path Show documentation
There is a newer version: 2.9.0
/*
 * Copyright 2013 the original author or authors.
 *
 * Licensed 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 com.jayway.restassured.path.xml.element;

import java.util.List;

/**
 * Base object for all XML objects.
 */
public interface PathElement extends Iterable {

    /**
     * Get a value from the current XML object.
     * 
     * This method returns the child whose name matches name. If several
     * children matches the name then a {@link List} of Node's
     * are returned.
     * 
     * 
     * If this object is a Node and you want to return an attribute value you need to prefix
     * the name with an @. E.g. given
     * 
     *   <category type="present">
     *      <item when="Aug 10">
     *         <name>Kathryn's Birthday</name>
     *         <price>200</price>
     *      </item>
     *   </category>
     * 
     * then
     *      *  String type = node.get("@type");
     * 
     * will return "present".
     * 
     *
     * @param name The name of the child, children or attribute.
     * @param   The expected type of the return value.
     * @return A Node, a list of nodes, an attribute value or null if not found.
     */
     T get(String name);

    /**
     * Get a value from the current XML using Groovy's GPath expression syntax.
     *
     * @param path The GPath expression syntax
     * @param   The expected type of the return value.
     * @return The outcome of the gpath expression
     */
     T getPath(String path);

    /**
     * Get a value from the current XML using Groovy's GPath expression syntax.
     *
     * @param path         The GPath expression syntax
     * @param explicitType Converts the outcome of the GPath expression to tis type if allowed
     * @param           The expected type of the return value.
     * @return The outcome of the gpath expression
     */
     T getPath(String path, Class explicitType);

    /**
     * Get a {@link Node} whose name matches the supplied name
     * from the current XML object.
     * 
     * 
     * Note that there's no guarantee that this method actually
     * will return a Node. It could result in a {@java.lang.ClassCastException}.
     *
     * @param name The name of the Node to get.
     * @return The Node matching the name or null if non were found.
     */
    Node getNode(String name);

    /**
     * Get a list of {@link Node}'s whose name matches the supplied name
     * from the current XML object.
     *
     * @param name The name of the Nodes to get.
     * @return The Node matching the name or an empty list of non were found.
     */
    List getNodes(String name);
}