1 /* 2 * $HeadURL: http://svn.apache.org/repos/asf/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/message/HeaderValueFormatter.java $ 3 * $Revision: 571954 $ 4 * $Date: 2007-09-02 04:05:21 -0700 (Sun, 02 Sep 2007) $ 5 * 6 * ==================================================================== 7 * Licensed to the Apache Software Foundation (ASF) under one 8 * or more contributor license agreements. See the NOTICE file 9 * distributed with this work for additional information 10 * regarding copyright ownership. The ASF licenses this file 11 * to you under the Apache License, Version 2.0 (the 12 * "License"); you may not use this file except in compliance 13 * with the License. You may obtain a copy of the License at 14 * 15 * http://www.apache.org/licenses/LICENSE-2.0 16 * 17 * Unless required by applicable law or agreed to in writing, 18 * software distributed under the License is distributed on an 19 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 20 * KIND, either express or implied. See the License for the 21 * specific language governing permissions and limitations 22 * under the License. 23 * ==================================================================== 24 * 25 * This software consists of voluntary contributions made by many 26 * individuals on behalf of the Apache Software Foundation. For more 27 * information on the Apache Software Foundation, please see 28 * <http://www.apache.org/>. 29 * 30 */ 31 32 package org.apache.http.message; 33 34 35 import org.apache.http.HeaderElement; 36 import org.apache.http.NameValuePair; 37 import org.apache.http.util.CharArrayBuffer; 38 39 40 41 /** 42 * Interface for formatting elements of a header value. 43 * This is the complement to {@link HeaderValueParser}. 44 * Instances of this interface are expected to be stateless and thread-safe. 45 * 46 * <p> 47 * All formatting methods accept an optional buffer argument. 48 * If a buffer is passed in, the formatted element will be appended 49 * and the modified buffer is returned. If no buffer is passed in, 50 * a new buffer will be created and filled with the formatted element. 51 * In both cases, the caller is allowed to modify the returned buffer. 52 * </p> 53 * 54 * 55 * <!-- empty lines above to avoid 'svn diff' context problems --> 56 * @version $Revision: 571954 $ 57 * 58 * @since 4.0 59 */ 60 public interface HeaderValueFormatter { 61 62 /** 63 * Formats an array of header elements. 64 * 65 * @param buffer the buffer to append to, or 66 * <code>null</code> to create a new buffer 67 * @param elems the header elements to format 68 * @param quote <code>true</code> to always format with quoted values, 69 * <code>false</code> to use quotes only when necessary 70 * 71 * @return a buffer with the formatted header elements. 72 * If the <code>buffer</code> argument was not <code>null</code>, 73 * that buffer will be used and returned. 74 */ 75 CharArrayBuffer formatElements(CharArrayBuffer buffer, 76 HeaderElement[] elems, 77 boolean quote) 78 ; 79 80 81 /** 82 * Formats one header element. 83 * 84 * @param buffer the buffer to append to, or 85 * <code>null</code> to create a new buffer 86 * @param elem the header element to format 87 * @param quote <code>true</code> to always format with quoted values, 88 * <code>false</code> to use quotes only when necessary 89 * 90 * @return a buffer with the formatted header element. 91 * If the <code>buffer</code> argument was not <code>null</code>, 92 * that buffer will be used and returned. 93 */ 94 CharArrayBuffer formatHeaderElement(CharArrayBuffer buffer, 95 HeaderElement elem, 96 boolean quote) 97 ; 98 99 100 101 /** 102 * Formats the parameters of a header element. 103 * That's a list of name-value pairs, to be separated by semicolons. 104 * This method will <i>not</i> generate a leading semicolon. 105 * 106 * @param buffer the buffer to append to, or 107 * <code>null</code> to create a new buffer 108 * @param nvps the parameters (name-value pairs) to format 109 * @param quote <code>true</code> to always format with quoted values, 110 * <code>false</code> to use quotes only when necessary 111 * 112 * @return a buffer with the formatted parameters. 113 * If the <code>buffer</code> argument was not <code>null</code>, 114 * that buffer will be used and returned. 115 */ 116 CharArrayBuffer formatParameters(CharArrayBuffer buffer, 117 NameValuePair[] nvps, 118 boolean quote) 119 ; 120 121 122 /** 123 * Formats one name-value pair, where the value is optional. 124 * 125 * @param buffer the buffer to append to, or 126 * <code>null</code> to create a new buffer 127 * @param nvp the name-value pair to format 128 * @param quote <code>true</code> to always format with a quoted value, 129 * <code>false</code> to use quotes only when necessary 130 * 131 * @return a buffer with the formatted name-value pair. 132 * If the <code>buffer</code> argument was not <code>null</code>, 133 * that buffer will be used and returned. 134 */ 135 CharArrayBuffer formatNameValuePair(CharArrayBuffer buffer, 136 NameValuePair nvp, 137 boolean quote) 138 ; 139 140 } 141 142
