package org.jboss.resteasy.plugins.providers.multipart;

import java.util.Map;

/**
 * Represents a multipart/related (RFC2387) incoming mime message. A
 * multipart/related message is used to hold a root or start part and other
 * parts which are referenced from the root part. All parts have a unique id.
 * The type and the id of the start part is presented in parameters in the
 * message content-type header.
 *
 * @author Attila Kiraly
 * @version $Revision: 1 $
 */
public interface MultipartRelatedInput extends MultipartInput {

   /**
    * The type parameter as it was read from the content-type header of the
    * multipart/related message. A well formed multipart/related message always
    * has this parameter. This is the type of the root part of the message. If
    * a content-type header is presented in the root part as well it should
    * hold the same value.
    *
    * @return the type parameter of the content-type header of the message,
    *         null if there was no such parameter
    */
   String getType();

   /**
    * A start parameter is not mandatory in a message. If it is presented it
    * holds the id of the root part.
    *
    * @return the start parameter of the content-type header of the message,
    *         null if there was no such parameter
    */
   String getStart();

   /**
    * Optional.
    *
    * @return the start-info parameter of the content-type header of the
    *         message, null if there was no such parameter
    */
   String getStartInfo();

   /**
    * @return the root part of the message. If a start parameter was set in the
    *         message header the part with that id is returned. If no start
    *         parameter was set the first part is returned.
    */
   InputPart getRootPart();

   /**
    * @return a map holding all parts with their unique id-s as keys. The root
    *         part and the related parts too.
    */
   Map<String, InputPart> getRelatedMap();
}
