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

Go to download
Show more of this group Show more artifacts with this name
Show all versions of amazon-mws-order Show documentation
Amazon MWS Orders API Client Library POM
The newest version!
/******************************************************************************* 
 * 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.Collection;

/**
 * Interface for objects that write data and complex types to some format. XML
 * and JSON for example.
 * 
 * @author mayerj
 */
public interface MwsWriter extends Closeable {

    /**
     * Write a begin tag for an object value. Can be nested.
     * 
     * Must follow with matching endObject call eventually.
     * 
     * 

     * For JSON writes [,]name: { or {
     * 

     * For XML writes  <name> 
     * 
     * @param name
     */
    void beginObject(String name);

    @Override
    void close();

    /**
     * Write the end of an object value.
     * 

     * Must previously have written a matching beginObject.
     * 

     * For JSON writes: }
     * 

     * For XML writes: </name>
     * 
     * @param name
     */
    void endObject(String name);

    /**
     * Write out an object with a namespace attribute.
     * 

     * Same as calling:
     * 
     *  if (value!=null) {
     *      w.beginObject(name);
     *      w.writeAttribute("xmlns",name);
     *      value.writeFragmentTo(w);
     *      w.endObject(name);
     *  }
     * 
     *
     * @param name
     *            The label for the value.
     * 
     * @param value
     *            The value to output.
     */
    void write(String namespace, String name, MwsObject value);

    /**
     * Write out a value, with proper escaping and delimiters for the context.
     * May be called nested in beginObject/endObject.
     * 

     * The value must be one of: null, Boolean, Number, String, MwsObject.
     * 

     * Calling with a null value does nothing and returns.
     * 

     * For JSON: [,]label:value or [,]value
     * 

     * For XML: <label>valueFragment</label>
     * 
     * @param name
     *            The label for the value.
     * 
     * @param value
     *            The value to output.
     */
    void write(String name, Object value);

    /**
     * Write out a labeled attribute value with proper escaping and delimiters
     * for the context.
     * 

     * Can only be called after beginObject or writeAttribute methods.
     * 

     * The value must be one of: null, Boolean, Number, String.
     * 

     * Calling with a null value does nothing and returns.
     * 

     * For JSON: same as write(name,value)
     * 

     * For XML: label = "value" inside the object tag.
     * 
     * @param name
     * @param value
     */
    void writeAttribute(String name, Object value);

    /**
     * Write a list using sibling elements.
     * 

     * For JSON: [,]name:[values...] or [values...]
     * 

     * For XML: <name>value</name>...
     * 
     * @param name
     * @param list
     */
    void writeList(String name, Collection list);

    /**
     * Write a list using child elements.
     * 

     * For JSON: [,]name:[values...] or [values...]
     * 

     * For XML: <name><memberName>value</memberName>...
     *
     * @param name
     * @param memberName
     * @param list
     */
    void writeList(String name, String memberName, Collection list);

    /**
     * Write a list of arbitrary elements.
     *
     * @param elements Collection of w3c DOM elements to write
     */
    void writeAny(Collection elements);

    /**
     * Write out an unlabeled value.
     * 

     * Calling with null value does nothing and returns.
     * 

     * For JSON: [,]Value:value or [,]value
     * 

     * For XML: value
     * 
     * @param value
     *            The object value.
     */
    void writeValue(Object value);

}