com.amazonservices.mws.client.MwsReader Maven / Gradle / Ivy

/******************************************************************************* 
 * Copyright 2009-2012 Amazon Services. All Rights Reserved.
 * 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://aws.amazon.com/apache2.0
 * This file 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.
 *******************************************************************************
 * Marketplace Web Service Runtime Client Library
 */
package com.amazonservices.mws.client;

import org.w3c.dom.Element;

import java.io.Closeable;
import java.util.List;

/**
 * Methods to read an object from XML, JSON or other serial form.
 * 
 * MwsReader instances can wrap an input stream or other resource
 * and should be closed to avoid resource leakage.
 * 
 * @author mayerj
 */
public interface MwsReader extends Closeable {

    @Override
    void close();

    /**
     * Read the next labeled value.
     * 

     * Returns null if the reader is not positioned on a labeled value
     * of the requested type.
     * 

     * For XML reads: <name>value</name>
     * 

     * For JSON reads: name:value if in Object or
     * value if in list.
     * 
     * @param name
     *            The expected label.
     * 
     * @param cls
     *            The expected value class.
     * 
     * @return The read in value.
     */
    public  T read(String name, Class cls);

    /**
     * Get an attribute by name.
     * 

     * Called when positioned on begin Object.
     * 

     * Returns null if the named attribute is not present.
     * 
     * @param name
     *            The attribute name to get.
     * 
     * @return The attribute value or null of not set.
     */
    public  T readAttribute(String name, Class cls);

    /**
     * Read a list of sibling elements.
     * 

     * For XML reads: <memberName>value</memberName>...
     * 

     * For JSON reads: name:[value...] or [value...]
     * 
     * 
     * @param memberName XML tag name of each member
     * @param cls
     * 
     * @return A List.
     */
    public  List readList(String memberName, Class cls);

    /**
     * Read a list of child elements.
     * 

     * For XML reads: <name><memberName>value</memberName>...
     * 

     * For JSON reads: name:[value...] or [value...]
     *
     *
     * @param name XML tag name of list parent
     * @param memberName XML tag name of each member
     * @param cls
     *
     * @return A List.
     */
    public  List readList(String name, String memberName, Class cls);

    /**
     * Read a list of all elements, ignoring type and name.
     *
     * @return A List of w3c DOM Elements
     */
    public List readAny();

    /**
     * Read raw string value.
     * 

     * For XML reads: characters up to next tag.
     * 

     * For JSON reads: "characters"
     * 
     * @return The read in string value.
     */
    public  T readValue(Class cls);

}