/*
 * Segment.java February 2007
 *
 * Copyright (C) 2001, Niall Gallagher <niallg@users.sf.net>
 *
 * 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 org.simpleframework.http.message;

import java.util.List;

import org.simpleframework.http.ContentDisposition;
import org.simpleframework.http.ContentType;

/**
 * The <code>Segment</code> object represents a collection of header values that
 * is followed by a body. This is used to represent the header of a multipart
 * upload part. The raw value of each header for the part can be acquired using
 * this interface, also the type and the disposition of the body can be
 * determined from this.
 * 
 * @author Niall Gallagher
 * 
 * @see org.simpleframework.http.Part
 */
public interface Segment {

    /**
     * This method is used to determine the type of a part. Typically a part is
     * either a text parameter or a file. If this is true then the content
     * represented by the associated part is a file.
     * 
     * @return this returns true if the associated part is a file
     */
    boolean isFile();

    /**
     * This method is used to acquire the name of the part. Typically this is
     * used when the part represents a text parameter rather than a file.
     * However, this can also be used with a file part.
     * 
     * @return this returns the name of the associated part
     */
    String getName();

    /**
     * This method is used to acquire the file name of the part. This is used
     * when the part represents a text parameter rather than a file. However,
     * this can also be used with a file part.
     * 
     * @return this returns the file name of the associated part
     */
    String getFileName();

    /**
     * This can be used to get the value of the first message header that has
     * the specified name. The value provided from this will be trimmed so there
     * is no need to modify the value, also if the header name specified refers
     * to a comma separated list of values the value returned is the first value
     * in that list. This returns null if there is no HTTP message header.
     * 
     * @param name
     *            the HTTP message header to get the value from
     * 
     * @return this returns the value that the HTTP message header
     */
    String getValue(String name);

    /**
     * This can be used to get the values of HTTP message headers that have the
     * specified name. This is a convenience method that will present that
     * values as tokens extracted from the header. This has obvious performance
     * benefits as it avoids having to deal with <code>substring</code> and
     * <code>trim</code> calls.
     * <p>
     * The tokens returned by this method are ordered according to there HTTP
     * quality values, or "q" values, see RFC 2616 section 3.9. This also strips
     * out the quality parameter from tokens returned. So "image/html; q=0.9"
     * results in "image/html". If there are no "q" values present then order is
     * by appearance.
     * <p>
     * The result from this is either the trimmed header value, that is, the
     * header value with no leading or trailing whitespace or an array of
     * trimmed tokens ordered with the most preferred in the lower indexes, so
     * index 0 is has highest preference.
     * 
     * @param name
     *            the name of the headers that are to be retrieved
     * 
     * @return ordered array of tokens extracted from the header(s)
     */
    List<String> getValues(String name);

    /**
     * This is a convenience method that can be used to determine the content
     * type of the message body. This will determine whether there is a
     * <code>Content-Type</code> header, if there is then this will parse that
     * header and represent it as a typed object which will expose the various
     * parts of the HTTP header.
     * 
     * @return this returns the content type value if it exists
     */
    ContentType getContentType();

    /**
     * This is a convenience method that can be used to determine the content
     * type of the message body. This will determine whether there is a
     * <code>Content-Disposition</code> header, if there is this will parse that
     * header and represent it as a typed object which will expose the various
     * parts of the HTTP header.
     * 
     * @return this returns the content disposition value if it exists
     */
    ContentDisposition getDisposition();

    /**
     * This is a convenience method that can be used to determine the content
     * type of the message body. This will determine whether there is a
     * <code>Transfer-Encoding</code> header, if there is then this will parse
     * that header and return the first token in the comma separated list of
     * values, which is the primary value.
     * 
     * @return this returns the transfer encoding value if it exists
     */
    String getTransferEncoding();

    /**
     * This is a convenience method that can be used to determine the length of
     * the message body. This will determine if there is a
     * <code>Content-Length</code> header, if it does then the length can be
     * determined, if not then this returns -1.
     * 
     * @return the content length, or -1 if it cannot be determined
     */
    long getContentLength();
}