Top Description Fields Constructors Methods
org.apache.tomcat.util.http

public Class MimeHeaders

Additional top-level classes in compilation unit: NamesEnumerator, ValuesEnumerator, MimeHeaderField.

extends Object
Class Inheritance
Imports
java.io.IOException, .PrintWriter, .StringWriter, java.util.Enumeration, org.apache.tomcat.util.buf.MessageBytes, org.apache.tomcat.util.res.StringManager
Memory-efficient repository for Mime Headers. When the object is recycled, it will keep the allocated headers[] and all the MimeHeaderField - no GC is generated.

For input headers it is possible to use the MessageByte for Fields - so no GC will be generated.

The only garbage is generated when using the String for header names/values - this can't be avoided when the servlet calls header methods, but is easy to avoid inside tomcat. The goal is to use _only_ MessageByte-based Fields, and reduce to 0 the memory overhead of tomcat.

This class is used to contain standard internet message headers, used for SMTP (RFC822) and HTTP (RFC2068) messages as well as for MIME (RFC 2045) applications such as transferring typed data and grouping related items in multipart message bodies.

Message headers, as specified in RFC822, include a field name and a field body. Order has no semantic significance, and several fields with the same name may exist. However, most fields do not (and should not) exist more than once in a header.

Many kinds of field body must conform to a specified syntax, including the standard parenthesized comment syntax. This class supports only two simple syntaxes, for dates and integers.

When processing headers, care must be taken to handle the case of multiple same-name fields correctly. The values of such fields are only available as strings. They may be accessed by index (treating the header as an array of fields), or by name (returning an array of string values).

Headers are first parsed and stored in the order they are received. This is based on the fact that most servlets will not directly access all headers, and most headers are single-valued. (the alternative - a hash or similar data structure - will add an overhead that is not needed in most cases)

Apache seems to be using a similar method for storing and manipulating headers.

Authors
[email protected], James Todd [[email protected]], Costin Manolache, kevin seguin

Field Summary

Modifier and TypeField and Description
private int
count

The current number of header fields.

public static final int
DEFAULT_HEADER_SIZE

Initial size - should be == average number of headers per request

private MimeHeaderField[]
headers

The header fields.

private int
limit

The limit on the number of header fields.

private static final StringManager
sm

Constructor Summary

AccessConstructor and Description
public
MimeHeaders()

Creates a new MimeHeaders object using a default buffer size.

Method Summary

Modifier and TypeMethod and Description
public MessageBytes

Returns:

the message bytes container for the value
addValue(String
The header name
name)

Create a new named header , return the MessageBytes container for the new value

public MessageBytes

Returns:

the message bytes container for the value
addValue(byte[]
The header name bytes
b, int
Offset
startN, int
Length
len)

Create a new named header using un-translated byte[].

public void
clear()
Deprecated

private MimeHeaderField
createHeader()

Adds a partially constructed field to the header.

public void
duplicate(MimeHeaders source)

public int

Returns:

the header index
findHeader(String
The header name
name, int
Index on which to start looking
starting)

Find the index of a header with the given name.

public String
getHeader(String name)

public MessageBytes

Returns:

the Nth header name, or null if there is no such header. This may be used to iterate through all header fields.
getName(int
The header index
n)

public MessageBytes

Returns:

the value if unique
getUniqueValue(String
The header name
name)

Finds and returns a unique header field with the given name.

public MessageBytes

Returns:

the Nth header value, or null if there is no such header. This may be used to iterate through all header fields.
getValue(int
The header index
n)

public MessageBytes

Returns:

the value
getValue(String
The header name
name)

Finds and returns a header field with the given name.

public Enumeration<String>

Returns:

the enumeration
names()

Returns an enumeration of strings representing the header field names.

public void
recycle()

Clears all header fields.

public void
removeHeader(String
the name of the header field to be removed
name)

Removes a header field with the specified name.

public void
removeHeader(int
the index of the header to remove.
idx)

Reset, move to the end and then reduce count by 1.

public void
setLimit(int
The new limit
limit)

Set limit on the number of header fields.

public MessageBytes

Returns:

the message bytes container for the value
setValue(String
The header name
name)

Allow "set" operations, which removes all current values for this header.

public int

Returns:

the current number of header fields.
size()

public String
toString()

Overrides java.lang.Object.toString.

Returns a string representation of the object.

public Enumeration<String>
values(String name)

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAllwaitwaitwait

Field Detail

countback to summary
private int count

The current number of header fields.

DEFAULT_HEADER_SIZEback to summary
public static final int DEFAULT_HEADER_SIZE

Initial size - should be == average number of headers per request

headersback to summary
private MimeHeaderField[] headers

The header fields.

limitback to summary
private int limit

The limit on the number of header fields.

smback to summary
private static final StringManager sm

Constructor Detail

MimeHeadersback to summary
public MimeHeaders()

Creates a new MimeHeaders object using a default buffer size.

Method Detail

addValueback to summary
public MessageBytes addValue(String name)

Create a new named header , return the MessageBytes container for the new value

Parameters
name:String

The header name

Returns:MessageBytes

the message bytes container for the value

addValueback to summary
public MessageBytes addValue(byte[] b, int startN, int len)

Create a new named header using un-translated byte[]. The conversion to chars can be delayed until encoding is known.

Parameters
b:byte[]

The header name bytes

startN:int

Offset

len:int

Length

Returns:MessageBytes

the message bytes container for the value

clearback to summary
public void clear()

Deprecated

Annotations
@Deprecated
createHeaderback to summary
private MimeHeaderField createHeader()

Adds a partially constructed field to the header. This field has not had its name or value initialized.

duplicateback to summary
public void duplicate(MimeHeaders source) throws IOException
findHeaderback to summary
public int findHeader(String name, int starting)

Find the index of a header with the given name.

Parameters
name:String

The header name

starting:int

Index on which to start looking

Returns:int

the header index

getHeaderback to summary
public String getHeader(String name)
getNameback to summary
public MessageBytes getName(int n)
Parameters
n:int

The header index

Returns:MessageBytes

the Nth header name, or null if there is no such header. This may be used to iterate through all header fields.

getUniqueValueback to summary
public MessageBytes getUniqueValue(String name)

Finds and returns a unique header field with the given name. If no such field exists, null is returned. If the specified header field is not unique then an IllegalArgumentException is thrown.

Parameters
name:String

The header name

Returns:MessageBytes

the value if unique

Exceptions
IllegalArgumentException:
if the header has multiple values
getValueback to summary
public MessageBytes getValue(int n)
Parameters
n:int

The header index

Returns:MessageBytes

the Nth header value, or null if there is no such header. This may be used to iterate through all header fields.

getValueback to summary
public MessageBytes getValue(String name)

Finds and returns a header field with the given name. If no such field exists, null is returned. If more than one such field is in the header, an arbitrary one is returned.

Parameters
name:String

The header name

Returns:MessageBytes

the value

namesback to summary
public Enumeration<String> names()

Returns an enumeration of strings representing the header field names. Field names may appear multiple times in this enumeration, indicating that multiple fields with that name exist in this header.

Returns:Enumeration<String>

the enumeration

recycleback to summary
public void recycle()

Clears all header fields.

removeHeaderback to summary
public void removeHeader(String name)

Removes a header field with the specified name. Does nothing if such a field could not be found.

Parameters
name:String

the name of the header field to be removed

removeHeaderback to summary
public void removeHeader(int idx)

Reset, move to the end and then reduce count by 1.

Parameters
idx:int

the index of the header to remove.

setLimitback to summary
public void setLimit(int limit)

Set limit on the number of header fields.

Parameters
limit:int

The new limit

setValueback to summary
public MessageBytes setValue(String name)

Allow "set" operations, which removes all current values for this header.

Parameters
name:String

The header name

Returns:MessageBytes

the message bytes container for the value

sizeback to summary
public int size()
Returns:int

the current number of header fields.

toStringback to summary
public String toString()

Overrides java.lang.Object.toString.

Doc from java.lang.Object.toString.

Returns a string representation of the object. Satisfying this method's contract implies a non-null result must be returned.

Returns:String

a string representation of the object

Annotations
@Override
valuesback to summary
public Enumeration<String> values(String name)