This class holds MIME parameters (attribute-value pairs). The mail.mime.encodeparameters and mail.mime.decodeparameters System properties control whether encoded parameters, as specified by RFC 2231, are supported. By default, such encoded parameters are supported.

Also, in the current implementation, setting the System property mail.mime.decodeparameters.strict to "true" will cause a ParseException to be thrown for errors detected while decoding encoded parameters. By default, if any decoding errors occur, the original (undecoded) string is used.

The current implementation supports the System property mail.mime.parameters.strict, which if set to false when parsing a parameter list allows parameter values to contain whitespace and other special characters without being quoted; the parameter value ends at the next semicolon. If set to true (the default), parameter values are required to conform to the MIME specification and must be quoted if they contain whitespace or special characters.

Nested and Inner Type Summary

Modifier and Type	Class and Description
private static class	ParameterList.LiteralValue A struct to hold a literal value that shouldn't be further encoded.
private static class	ParameterList.MultiValue A struct for a multi-segment parameter.
private static class	ParameterList.ParamEnum Map the LinkedHashMap's keySet iterator to an Enumeration.
private static class	ParameterList.ToStringBuffer A special wrapper for a StringBuffer that keeps track of the number of characters used in a line, wrapping to a new line as necessary; for use by the toString method.
private static class	ParameterList.Value A struct to hold an encoded value.

Field Summary

Modifier and Type	Field and Description
private static final boolean	applehack
private static final boolean	decodeParameters
private static final boolean	decodeParametersStrict
private static final boolean	encodeParameters
private static final char[]	hex
private String	lastName MWB 3BView: The name of the last parameter added to the map.
private Map<String, Object>	list The map of name, value pairs.
private Set<String>	multisegmentNames A set of names for multi-segment parameters that we haven't processed yet.
private static final boolean	parametersStrict
private Map<String, Object>	slist A map containing the segments for all not-yet-processed multi-segment parameters.
private static final boolean	splitLongParameters
private static final boolean	windowshack

Constructor Summary

Access	Constructor and Description
public	ParameterList() No-arg Constructor.
public	ParameterList(String the parameter-list string. s) Constructor that takes a parameter-list string.

Method Summary

Modifier and Type	Method and Description
private void	combineMultisegmentNames(boolean keepConsistentOnFailure) Iterate through the saved set of names of multi-segment parameters, for each parameter find all segments stored in the slist map, decode each segment as needed, combine the segments together into a single decoded value, and save all segments in a MultiValue object in the main list indexed by the parameter name.
public void	combineSegments() Normal users of this class will use simple parameter names.
private static String	decodeBytes(String value, String charset) Decode the encoded bytes in value using the specified charset.
private static void	decodeBytes(String value, OutputStream os) Decode the encoded bytes in value and write them to the OutputStream.
private static ParameterList.Value	encodeValue(String value, String charset) Encode a parameter value, if necessary.
private static ParameterList.Value	extractCharset(String value) Extract charset and encoded value.
public String	Returns: Value of the parameter. Returns `null` if the parameter is not present. get(String parameter name. name) Returns the value of the specified parameter.
public Enumeration<String>	Returns: Enumeration of all parameter names in this list. getNames() Return an enumeration of the names of all parameters in this list.
private void	putEncodedName(String name, String value) If the name is an encoded or multi-segment name (or both) handle it appropriately, storing the appropriate String or Value object.
private static String	quote(String value)
public void	remove(String name of the parameter. name) Removes the specified parameter from this ParameterList.
public void	set(String name of the parameter. name, String value of the parameter. value) Set a parameter.
public void	set(String name of the parameter. name, String value of the parameter. value, String charset of the parameter value. charset) Set a parameter.
pack-priv void	setLiteral(String name of the parameter. name, String value of the parameter. value) Package-private method to set a literal value that won't be further encoded.
public int	Returns: number of parameters. size() Return the number of parameters in this list.
public String	Returns: String toString() Overrides java.lang.Object.toString. Convert this ParameterList into a MIME String.
public String	Returns: String toString(int number of character positions already used, in the field into which the parameter list is to be inserted. used) Convert this ParameterList into a MIME String.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll wait wait wait

Field Detail

applehack	back to summary
private static final boolean applehack

decodeParameters	back to summary
private static final boolean decodeParameters

decodeParametersStrict	back to summary
private static final boolean decodeParametersStrict

encodeParameters	back to summary
private static final boolean encodeParameters

hex	back to summary
private static final char[] hex

lastName	back to summary
private String lastName MWB 3BView: The name of the last parameter added to the map. Used for the AppleMail hack.

list	back to summary
private Map<String, Object> list The map of name, value pairs. The value object is either a String, for unencoded values, or a Value object, for encoded values, or a MultiValue object, for multi-segment parameters, or a LiteralValue object for strings that should not be encoded. We use a LinkedHashMap so that parameters are (as much as possible) kept in the original order. Note however that multi-segment parameters (see below) will appear in the position of the first seen segment and orphan segments will all move to the end.

list

back to summary

private Map<String, Object> list

The map of name, value pairs. The value object is either a String, for unencoded values, or a Value object, for encoded values, or a MultiValue object, for multi-segment parameters, or a LiteralValue object for strings that should not be encoded. We use a LinkedHashMap so that parameters are (as much as possible) kept in the original order. Note however that multi-segment parameters (see below) will appear in the position of the first seen segment and orphan segments will all move to the end.

multisegmentNames	back to summary
private Set<String> multisegmentNames A set of names for multi-segment parameters that we haven't processed yet. Normally such names are accumulated during the inital parse and processed at the end of the parse, but such names can also be set via the set method when the IMAP provider accumulates pre-parsed pieces of a parameter list. (A special call to the set method tells us when the IMAP provider is done setting parameters.) A multi-segment parameter is defined by RFC 2231. For example, "title0=part1; title1=part2", which represents a parameter named "title" with value "part1part2". Note also that each segment of the value might or might not be encoded, indicated by a trailing "" on the parameter name. If any segment is encoded, the first segment must be encoded. Only the first segment contains the charset and language information needed to decode any encoded segments. RFC 2231 introduces many possible failure modes, which we try to handle as gracefully as possible. Generally, a failure to decode a parameter value causes the non-decoded parameter value to be used instead. Missing segments cause all later segments to be appear as independent parameters with names that include the segment number. For example, "title0=part1; title1=part2; title3=part4" appears as two parameters named "title" and "title*3".

multisegmentNames

back to summary

private Set<String> multisegmentNames

A set of names for multi-segment parameters that we haven't processed yet. Normally such names are accumulated during the inital parse and processed at the end of the parse, but such names can also be set via the set method when the IMAP provider accumulates pre-parsed pieces of a parameter list. (A special call to the set method tells us when the IMAP provider is done setting parameters.) A multi-segment parameter is defined by RFC 2231. For example, "title*0=part1; title*1=part2", which represents a parameter named "title" with value "part1part2". Note also that each segment of the value might or might not be encoded, indicated by a trailing "*" on the parameter name. If any segment is encoded, the first segment must be encoded. Only the first segment contains the charset and language information needed to decode any encoded segments. RFC 2231 introduces many possible failure modes, which we try to handle as gracefully as possible. Generally, a failure to decode a parameter value causes the non-decoded parameter value to be used instead. Missing segments cause all later segments to be appear as independent parameters with names that include the segment number. For example, "title*0=part1; title*1=part2; title*3=part4" appears as two parameters named "title" and "title*3".

parametersStrict	back to summary
private static final boolean parametersStrict

slist	back to summary
private Map<String, Object> slist A map containing the segments for all not-yet-processed multi-segment parameters. The map is indexed by "name*seg". The value object is either a String or a Value object. The Value object is not decoded during the initial parse because the segments may appear in any order and until the first segment appears we don't know what charset to use to decode the encoded segments. The segments are hex decoded in order, combined into a single byte array, and converted to a String using the specified charset in the combineMultisegmentNames method.

slist

back to summary

private Map<String, Object> slist

A map containing the segments for all not-yet-processed multi-segment parameters. The map is indexed by "name*seg". The value object is either a String or a Value object. The Value object is not decoded during the initial parse because the segments may appear in any order and until the first segment appears we don't know what charset to use to decode the encoded segments. The segments are hex decoded in order, combined into a single byte array, and converted to a String using the specified charset in the combineMultisegmentNames method.

splitLongParameters	back to summary
private static final boolean splitLongParameters

windowshack	back to summary
private static final boolean windowshack

Constructor Detail

ParameterList	back to summary
public ParameterList() No-arg Constructor.

ParameterList	back to summary
public ParameterList(String s) throws ParseException Constructor that takes a parameter-list string. The String is parsed and the parameters are collected and stored internally. A ParseException is thrown if the parse fails. Note that an empty parameter-list string is valid and will be parsed into an empty ParameterList. Parameters s:String the parameter-list string. Exceptions ParseException: if the parse fails.

ParameterList

back to summary

public ParameterList(String s) throws ParseException

Constructor that takes a parameter-list string. The String is parsed and the parameters are collected and stored internally. A ParseException is thrown if the parse fails. Note that an empty parameter-list string is valid and will be parsed into an empty ParameterList.

Parameters

s:String: the parameter-list string.

Exceptions

ParseException:: if the parse fails.

Method Detail

combineMultisegmentNames	back to summary
private void combineMultisegmentNames(boolean keepConsistentOnFailure) throws ParseException Iterate through the saved set of names of multi-segment parameters, for each parameter find all segments stored in the slist map, decode each segment as needed, combine the segments together into a single decoded value, and save all segments in a MultiValue object in the main list indexed by the parameter name.

combineMultisegmentNames

back to summary

private void combineMultisegmentNames(boolean keepConsistentOnFailure) throws ParseException

Iterate through the saved set of names of multi-segment parameters, for each parameter find all segments stored in the slist map, decode each segment as needed, combine the segments together into a single decoded value, and save all segments in a MultiValue object in the main list indexed by the parameter name.

combineSegments back to summary

combineSegments	back to summary
public void combineSegments() Normal users of this class will use simple parameter names. In some cases, for example, when processing IMAP protocol messages, individual segments of a multi-segment name (specified by RFC 2231) will be encountered and passed to the `set` method. After all these segments are added to this ParameterList, they need to be combined to represent the logical parameter name and value. This method will combine all segments of multi-segment names. Normal users should never need to call this method. Since JavaMail 1.5

public void combineSegments()

Normal users of this class will use simple parameter names. In some cases, for example, when processing IMAP protocol messages, individual segments of a multi-segment name (specified by RFC 2231) will be encountered and passed to the set method. After all these segments are added to this ParameterList, they need to be combined to represent the logical parameter name and value. This method will combine all segments of multi-segment names.

Normal users should never need to call this method.

Since: JavaMail 1.5

decodeBytes	back to summary
private static String decodeBytes(String value, String charset) throws ParseException, UnsupportedEncodingException Decode the encoded bytes in value using the specified charset.

decodeBytes	back to summary
private static void decodeBytes(String value, OutputStream os) throws ParseException, IOException Decode the encoded bytes in value and write them to the OutputStream.

encodeValue	back to summary
private static ParameterList.Value encodeValue(String value, String charset) Encode a parameter value, if necessary. If the value is encoded, a Value object is returned. Otherwise, null is returned. XXX - Could return a MultiValue object if parameter value is too long.

extractCharset	back to summary
private static ParameterList.Value extractCharset(String value) throws ParseException Extract charset and encoded value. Value will be decoded later.

get back to summary

get	back to summary
public String get(String name) Returns the value of the specified parameter. Note that parameter names are case-insensitive. Parameters name:String parameter name. Returns:String Value of the parameter. Returns `null` if the parameter is not present.

public String get(String name)

Returns the value of the specified parameter. Note that parameter names are case-insensitive.

Parameters

name:String: parameter name.

Returns:String

Value of the parameter. Returns null if the parameter is not present.

getNames	back to summary
public Enumeration<String> getNames() Return an enumeration of the names of all parameters in this list. Returns:Enumeration<String> Enumeration of all parameter names in this list.

getNames

back to summary

public Enumeration<String> getNames()

Return an enumeration of the names of all parameters in this list.

Returns:Enumeration<String>: Enumeration of all parameter names in this list.

putEncodedName	back to summary
private void putEncodedName(String name, String value) throws ParseException If the name is an encoded or multi-segment name (or both) handle it appropriately, storing the appropriate String or Value object. Multi-segment names are stored in the main parameter list as an emtpy string as a placeholder, replaced later in combineMultisegmentNames with a MultiValue object. This causes all pieces of the multi-segment parameter to appear in the position of the first seen segment of the parameter.

putEncodedName

back to summary

private void putEncodedName(String name, String value) throws ParseException

If the name is an encoded or multi-segment name (or both) handle it appropriately, storing the appropriate String or Value object. Multi-segment names are stored in the main parameter list as an emtpy string as a placeholder, replaced later in combineMultisegmentNames with a MultiValue object. This causes all pieces of the multi-segment parameter to appear in the position of the first seen segment of the parameter.

quote	back to summary
private static String quote(String value)

remove	back to summary
public void remove(String name) Removes the specified parameter from this ParameterList. This method does nothing if the parameter is not present. Parameters name:String name of the parameter.

remove

back to summary

public void remove(String name)

Removes the specified parameter from this ParameterList. This method does nothing if the parameter is not present.

Parameters

name:String: name of the parameter.

set	back to summary
public void set(String name, String value) Set a parameter. If this parameter already exists, it is replaced by this new value. Parameters name:String name of the parameter. value:String value of the parameter.

set

back to summary

public void set(String name, String value)

Set a parameter. If this parameter already exists, it is replaced by this new value.

Parameters

name:String: name of the parameter.
value:String: value of the parameter.

set back to summary

set	back to summary
public void set(String name, String value, String charset) Set a parameter. If this parameter already exists, it is replaced by this new value. If the `mail.mime.encodeparameters` System property is true, and the parameter value is non-ASCII, it will be encoded with the specified charset, as specified by RFC 2231. Parameters name:String name of the parameter. value:String value of the parameter. charset:String charset of the parameter value. Since JavaMail 1.4

public void set(String name, String value, String charset)

Set a parameter. If this parameter already exists, it is replaced by this new value. If the mail.mime.encodeparameters System property is true, and the parameter value is non-ASCII, it will be encoded with the specified charset, as specified by RFC 2231.

Parameters

name:String: name of the parameter.
value:String: value of the parameter.
charset:String: charset of the parameter value.

Since

JavaMail 1.4

setLiteral	back to summary
pack-priv void setLiteral(String name, String value) Package-private method to set a literal value that won't be further encoded. Used to set the filename parameter when "mail.mime.encodefilename" is true. Parameters name:String name of the parameter. value:String value of the parameter.

setLiteral

back to summary

pack-priv void setLiteral(String name, String value)

Package-private method to set a literal value that won't be further encoded. Used to set the filename parameter when "mail.mime.encodefilename" is true.

Parameters

name:String: name of the parameter.
value:String: value of the parameter.

size	back to summary
public int size() Return the number of parameters in this list. Returns:int number of parameters.

size

back to summary

public int size()

Return the number of parameters in this list.

Returns:int: number of parameters.

toString	back to summary
public String toString() Overrides java.lang.Object.toString. Convert this ParameterList into a MIME String. If this is an empty list, an empty string is returned. Returns:String String Annotations @Override

toString

back to summary

public String toString()

Overrides java.lang.Object.toString.

Convert this ParameterList into a MIME String. If this is an empty list, an empty string is returned.

Returns:String

String

Annotations

@Override

toString	back to summary
public String toString(int used) Convert this ParameterList into a MIME String. If this is an empty list, an empty string is returned. The 'used' parameter specifies the number of character positions already taken up in the field into which the resulting parameter list is to be inserted. It's used to determine where to fold the resulting parameter list. Parameters used:int number of character positions already used, in the field into which the parameter list is to be inserted. Returns:String String

toString

back to summary

public String toString(int used)

Convert this ParameterList into a MIME String. If this is an empty list, an empty string is returned. The 'used' parameter specifies the number of character positions already taken up in the field into which the resulting parameter list is to be inserted. It's used to determine where to fold the resulting parameter list.

Parameters

used:int: number of character positions already used, in the field into which the parameter list is to be inserted.

Returns:String

String

javax.mail.internet back to summary

private Class ParameterList.LiteralValue

Class Inheritance

extends Object

java.lang.Object
javax.mail.internet.ParameterList.LiteralValue

A struct to hold a literal value that shouldn't be further encoded.

Field Summary

Modifier and Type	Field and Description
pack-priv String	value

Constructor Summary

Access	Constructor and Description
private	LiteralValue()

Method Summary

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

value	back to summary
pack-priv String value

Constructor Detail

LiteralValue	back to summary
private LiteralValue()

javax.mail.internet back to summary

private Class ParameterList.MultiValue

Class Inheritance

extends ArrayList<Object>

java.lang.Object
java.util.AbstractCollection
java.util.AbstractList
java.util.ArrayList
javax.mail.internet.ParameterList.MultiValue

A struct for a multi-segment parameter. Each entry in the List is either a String or a Value object. When all the segments are present and combined in the combineMultisegmentNames method, the value field contains the combined and decoded value. Until then the value field contains an empty string as a placeholder.

Field Summary

Modifier and Type	Field and Description
private static final long	serialVersionUID Hides java.util.ArrayList.serialVersionUID.
pack-priv String	value

Constructor Summary

Access	Constructor and Description
private	MultiValue()

Method Summary

Field Detail

serialVersionUID	back to summary
private static final long serialVersionUID Hides java.util.ArrayList.serialVersionUID.

value	back to summary
pack-priv String value

Constructor Detail

MultiValue	back to summary
private MultiValue()

javax.mail.internet back to summary

private Class ParameterList.ParamEnum

Class Inheritance

extends Object
implements Enumeration<String>

java.lang.Object
javax.mail.internet.ParameterList.ParamEnum

All Implemented Interfaces

java.util.Enumeration

Map the LinkedHashMap's keySet iterator to an Enumeration.

Field Summary

Modifier and Type	Field and Description
private Iterator<String>	it

Constructor Summary

Access	Constructor and Description
pack-priv	ParamEnum(Iterator<String> it)

Method Summary

Modifier and Type	Method and Description
public boolean	hasMoreElements() Implements java.util.Enumeration.hasMoreElements. Tests if this enumeration contains more elements.
public String	nextElement() Implements java.util.Enumeration.nextElement. Returns the next element of this enumeration if this enumeration object has at least one more element to provide.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

it	back to summary
private Iterator<String> it

Constructor Detail

ParamEnum	back to summary
pack-priv ParamEnum(Iterator<String> it)

Method Detail

hasMoreElements back to summary

hasMoreElements	back to summary
public boolean hasMoreElements() Implements java.util.Enumeration.hasMoreElements. Doc from java.util.Enumeration.hasMoreElements. Tests if this enumeration contains more elements. Returns:boolean `true` if and only if this enumeration object contains at least one more element to provide; `false` otherwise. Annotations @Override

public boolean hasMoreElements()

Implements java.util.Enumeration.hasMoreElements.

Doc from java.util.Enumeration.hasMoreElements.

Tests if this enumeration contains more elements.

Returns:boolean

true if and only if this enumeration object contains at least one more element to provide; false otherwise.

Annotations

@Override

nextElement

back to summary

public String nextElement()

Implements java.util.Enumeration.nextElement.

Doc from java.util.Enumeration.nextElement.

Returns the next element of this enumeration if this enumeration object has at least one more element to provide.

Returns:String

the next element of this enumeration.

Annotations

@Override

javax.mail.internet back to summary

private Class ParameterList.ToStringBuffer

Class Inheritance

extends Object

java.lang.Object
javax.mail.internet.ParameterList.ToStringBuffer

A special wrapper for a StringBuffer that keeps track of the number of characters used in a line, wrapping to a new line as necessary; for use by the toString method.

Field Summary

Modifier and Type	Field and Description
private StringBuilder	sb
private int	used

Constructor Summary

Access	Constructor and Description
public	ToStringBuffer(int used)

Method Summary

Modifier and Type	Method and Description
public void	addNV(String name, String value)
public String	toString() Overrides java.lang.Object.toString. Returns a string representation of the object.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll wait wait wait

Field Detail

sb	back to summary
private StringBuilder sb

used	back to summary
private int used

Constructor Detail

ToStringBuffer	back to summary
public ToStringBuffer(int used)

Method Detail

addNV	back to summary
public void addNV(String name, String value)

toString

back to summary

public String toString()

Overrides java.lang.Object.toString.

Doc from java.lang.Object.toString.

Returns a string representation of the object.

Returns:String

a string representation of the object.

Annotations

@Override

public Class ParameterList

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

private Class ParameterList.LiteralValue

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

private Class ParameterList.MultiValue

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

private Class ParameterList.ParamEnum

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

private Class ParameterList.ToStringBuffer

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

private Class ParameterList.Value

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Modifier and Type	Field and Description
pack-priv String	charset
pack-priv String	encodedValue
pack-priv String	value