001: /*
002: * $HeadURL: https://svn.apache.org/repos/asf/httpcomponents/httpcore/tags/4.0-beta1/module-main/src/main/java/org/apache/http/message/HeaderValueFormatter.java $
003: * $Revision: 571954 $
004: * $Date: 2007-09-02 13:05:21 +0200 (Sun, 02 Sep 2007) $
005: *
006: * ====================================================================
007: * Licensed to the Apache Software Foundation (ASF) under one
008: * or more contributor license agreements. See the NOTICE file
009: * distributed with this work for additional information
010: * regarding copyright ownership. The ASF licenses this file
011: * to you under the Apache License, Version 2.0 (the
012: * "License"); you may not use this file except in compliance
013: * with the License. You may obtain a copy of the License at
014: *
015: * http://www.apache.org/licenses/LICENSE-2.0
016: *
017: * Unless required by applicable law or agreed to in writing,
018: * software distributed under the License is distributed on an
019: * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
020: * KIND, either express or implied. See the License for the
021: * specific language governing permissions and limitations
022: * under the License.
023: * ====================================================================
024: *
025: * This software consists of voluntary contributions made by many
026: * individuals on behalf of the Apache Software Foundation. For more
027: * information on the Apache Software Foundation, please see
028: * <http://www.apache.org/>.
029: *
030: */
031:
032: package org.apache.http.message;
033:
034: import org.apache.http.HeaderElement;
035: import org.apache.http.NameValuePair;
036: import org.apache.http.util.CharArrayBuffer;
037:
038: /**
039: * Interface for formatting elements of a header value.
040: * This is the complement to {@link HeaderValueParser}.
041: * Instances of this interface are expected to be stateless and thread-safe.
042: *
043: * <p>
044: * All formatting methods accept an optional buffer argument.
045: * If a buffer is passed in, the formatted element will be appended
046: * and the modified buffer is returned. If no buffer is passed in,
047: * a new buffer will be created and filled with the formatted element.
048: * In both cases, the caller is allowed to modify the returned buffer.
049: * </p>
050: *
051: *
052: * <!-- empty lines above to avoid 'svn diff' context problems -->
053: * @version $Revision: 571954 $
054: *
055: * @since 4.0
056: */
057: public interface HeaderValueFormatter {
058:
059: /**
060: * Formats an array of header elements.
061: *
062: * @param buffer the buffer to append to, or
063: * <code>null</code> to create a new buffer
064: * @param elems the header elements to format
065: * @param quote <code>true</code> to always format with quoted values,
066: * <code>false</code> to use quotes only when necessary
067: *
068: * @return a buffer with the formatted header elements.
069: * If the <code>buffer</code> argument was not <code>null</code>,
070: * that buffer will be used and returned.
071: */
072: CharArrayBuffer formatElements(CharArrayBuffer buffer,
073: HeaderElement[] elems, boolean quote);
074:
075: /**
076: * Formats one header element.
077: *
078: * @param buffer the buffer to append to, or
079: * <code>null</code> to create a new buffer
080: * @param elem the header element to format
081: * @param quote <code>true</code> to always format with quoted values,
082: * <code>false</code> to use quotes only when necessary
083: *
084: * @return a buffer with the formatted header element.
085: * If the <code>buffer</code> argument was not <code>null</code>,
086: * that buffer will be used and returned.
087: */
088: CharArrayBuffer formatHeaderElement(CharArrayBuffer buffer,
089: HeaderElement elem, boolean quote);
090:
091: /**
092: * Formats the parameters of a header element.
093: * That's a list of name-value pairs, to be separated by semicolons.
094: * This method will <i>not</i> generate a leading semicolon.
095: *
096: * @param buffer the buffer to append to, or
097: * <code>null</code> to create a new buffer
098: * @param nvps the parameters (name-value pairs) to format
099: * @param quote <code>true</code> to always format with quoted values,
100: * <code>false</code> to use quotes only when necessary
101: *
102: * @return a buffer with the formatted parameters.
103: * If the <code>buffer</code> argument was not <code>null</code>,
104: * that buffer will be used and returned.
105: */
106: CharArrayBuffer formatParameters(CharArrayBuffer buffer,
107: NameValuePair[] nvps, boolean quote);
108:
109: /**
110: * Formats one name-value pair, where the value is optional.
111: *
112: * @param buffer the buffer to append to, or
113: * <code>null</code> to create a new buffer
114: * @param nvp the name-value pair to format
115: * @param quote <code>true</code> to always format with a quoted value,
116: * <code>false</code> to use quotes only when necessary
117: *
118: * @return a buffer with the formatted name-value pair.
119: * If the <code>buffer</code> argument was not <code>null</code>,
120: * that buffer will be used and returned.
121: */
122: CharArrayBuffer formatNameValuePair(CharArrayBuffer buffer,
123: NameValuePair nvp, boolean quote);
124:
125: }
|