javax.mail.internet

Class MimeMessage

public class MimeMessage extends Message implements MimePart

A MIME mail message. This may be a top-level part, or the content of a MIME body part with a "message/rfc822" Content-Type.

The string representation of RFC822 and MIME header fields must contain only US-ASCII characters. Non US-ASCII characters must be encoded as per the rules in RFC 2047. This class does not enforce those rules; the caller is expected to use MimeUtility to ensure that header values are correctly encoded.

Version: 1.4

Author: Chris Burdess

Nested Class Summary
static classMimeMessage.RecipientType
Additional recipient types specific to internet messages.
Field Summary
protected byte[]content
The bytes of the content of this message, if the message can be stored in memory.
protected InputStreamcontentStream
A SharedInputStream containing the byte content of this message, if the message cannot be stored in memory.
protected DataHandlerdh
The data handler managing this message's content.
protected Flagsflags
The message flags.
protected InternetHeadersheaders
The message headers.
protected booleanmodified
Indicates whether the message has been modified.
protected booleansaved
Indicates whether we do not need to call saveChanges on the message.
Constructor Summary
MimeMessage(Session session)
Constructor for an empty message.
MimeMessage(Session session, InputStream is)
Constructor with an input stream contining an RFC 822 message.
MimeMessage(MimeMessage source)
Constructor with an existing message.
protected MimeMessage(Folder folder, int msgnum)
Constructor with a parent folder and message number.
protected MimeMessage(Folder folder, InputStream is, int msgnum)
Constructor with a parent folder, message number, and RFC 822 input stream.
protected MimeMessage(Folder folder, InternetHeaders headers, byte[] content, int msgnum)
Constructor with a parent folder, message number, headers and byte content.
Method Summary
voidaddFrom(Address[] addresses)
Adds the specified addresses to From header field.
voidaddHeader(String name, String value)
Adds the specified header.
voidaddHeaderLine(String line)
Adds an RFC 822 header-line to this message.
voidaddRecipients(Message.RecipientType type, Address[] addresses)
Adds the given addresses to the recipients of the specified type.
voidaddRecipients(Message.RecipientType type, String addresses)
Adds the given addresses to the recipients of the specified type.
protected InternetHeaderscreateInternetHeaders(InputStream is)
Creates the headers from the given input stream.
protected MimeMessagecreateMimeMessage(Session session)
Creates a new MIME message.
EnumerationgetAllHeaderLines()
Returns all the header-lines.
EnumerationgetAllHeaders()
Returns all the headers.
Address[]getAllRecipients()
Returns all the recipients.
ObjectgetContent()
Returns this message's content as a Java object.
StringgetContentID()
Returns the value of the Content-ID header field.
String[]getContentLanguage()
Returns the languages specified in the Content-Language header field of this message, as defined by RFC 1766.
StringgetContentMD5()
Returns the value of the Content-MD5 header field.
protected InputStreamgetContentStream()
Returns the unencoded bytes of the content.
StringgetContentType()
Returns the value of the RFC 822 Content-Type header field, or "text/plain" if the header is not available.
DataHandlergetDataHandler()
Returns a data handler for accessing this message's content.
StringgetDescription()
Returns the Content-Description header field of this message.
StringgetDisposition()
Returns the value of the RFC 822 Content-Disposition header field, or null if the header is not available.
StringgetEncoding()
Returns the value of the Content-Transfer-Encoding header field.
StringgetFileName()
Returns the filename associated with this message.
FlagsgetFlags()
Returns the flags for this message.
Address[]getFrom()
Returns the value of the RFC 822 From header field.
String[]getHeader(String name)
Returns all the values for the specified header name.
StringgetHeader(String name, String delimiter)
Returns all the values for the specified header name as a single string, with headers separated by the given delimiter.
InputStreamgetInputStream()
Returns a decoded input stream for this message's content.
intgetLineCount()
Returns the number of lines in the content of this message, or -1 if this number cannot be determined.
EnumerationgetMatchingHeaderLines(String[] names)
Returns all the header-lines with any of the given names.
EnumerationgetMatchingHeaders(String[] names)
Returns all the headers with any of the given names.
StringgetMessageID()
Returns the value of the Message-ID header field.
EnumerationgetNonMatchingHeaderLines(String[] names)
Returns all the header-lines without any of the given names.
EnumerationgetNonMatchingHeaders(String[] names)
Returns all the headers without any of the given names.
InputStreamgetRawInputStream()
Returns the unencoded bytes of the content without applying any content transfer encoding.
DategetReceivedDate()
Returns the date on which this message was received.
Address[]getRecipients(Message.RecipientType type)
Returns the recipients of the given type.
Address[]getReplyTo()
Returns the value of the RFC 822 Reply-To header field.
AddressgetSender()
Returns the value of the RFC 822 Sender header field.
DategetSentDate()
Returns the value of the RFC 822 Date field.
intgetSize()
Returns the size of the content of this message in bytes, or -1 if the size cannot be determined.
StringgetSubject()
Returns the value of the Subject header field.
booleanisMimeType(String mimeType)
Indicates whether this message is of the specified MIME type.
booleanisSet(Flags.Flag flag)
Indicates whether the specified flag is set in this message.
protected voidparse(InputStream is)
Parses the given input stream, setting the headers and content fields appropriately.
voidremoveHeader(String name)
Removes all headers with the specified name.
Messagereply(boolean replyToAll)
Returns a new message suitable for a reply to this message.
voidsaveChanges()
Saves any changes to this message.
voidsetContent(Object o, String type)
Sets the content of this message using the specified Java object and MIME type.
voidsetContent(Multipart mp)
Sets the content of this message to be the specified multipart.
voidsetContentID(String cid)
Sets the Content-ID header field of this message.
voidsetContentLanguage(String[] languages)
Sets the Content-Language header of this message.
voidsetContentMD5(String md5)
Sets the Content-MD5 header field of this message.
voidsetDataHandler(DataHandler datahandler)
Sets the content of this part using the specified data handler.
voidsetDescription(String description)
Sets the Content-Description header field for this message.
voidsetDescription(String description, String charset)
Sets the Content-Description header field for this message.
voidsetDisposition(String disposition)
Sets the Content-Disposition header field of this message.
voidsetFileName(String filename)
Sets the filename associated with this part.
voidsetFlags(Flags flag, boolean set)
Sets the flags for this message.
voidsetFrom(Address address)
Sets the RFC 822 From header field.
voidsetFrom()
Sets the RFC 822 From header field using the value of the InternetAddress.getLocalAddress method.
voidsetHeader(String name, String value)
Sets the specified header.
voidsetRecipients(Message.RecipientType type, Address[] addresses)
Sets the recipients of the given type.
voidsetRecipients(Message.RecipientType type, String addresses)
Sets the recipients of the given type.
voidsetReplyTo(Address[] addresses)
Sets the RFC 822 Reply-To header field.
voidsetSender(Address address)
Sets the RFC 822 Sender header field.
voidsetSentDate(Date date)
Sets the RFC 822 Date header field.
voidsetSubject(String subject)
Sets the Subject header field.
voidsetSubject(String subject, String charset)
Sets the Subject header field.
voidsetText(String text)
Sets the content of this message using the specified text, and with a MIME type of "text/plain".
voidsetText(String text, String charset)
Sets the content of this message using the specified text, and with a MIME type of "text/plain".
voidsetText(String text, String charset, String subtype)
Sets the content of this message using the specified text, and with a text MIME type of the specified subtype.
protected voidupdateHeaders()
Updates the headers of this part, based on the content.
protected voidupdateMessageId()
Updates the Message-ID header.
voidwriteTo(OutputStream os)
Writes this message to the specified stream in RFC 822 format.
voidwriteTo(OutputStream os, String[] ignoreList)
Writes this message to the specified stream in RFC 822 format, without the specified headers.

Field Detail

content

protected byte[] content
The bytes of the content of this message, if the message can be stored in memory.

contentStream

protected InputStream contentStream
A SharedInputStream containing the byte content of this message, if the message cannot be stored in memory.

dh

protected DataHandler dh
The data handler managing this message's content.

flags

protected Flags flags
The message flags.

headers

protected InternetHeaders headers
The message headers.

modified

protected boolean modified
Indicates whether the message has been modified. If false, any data in the content array is assumed to be valid and is used directly in the writeTo method. This field is set to true when an empty message is created or when the saveChanges method is called.

saved

protected boolean saved
Indicates whether we do not need to call saveChanges on the message. This flag is set to false by the public constructor and set to true by the saveChanges method. The writeTo method checks this flag and calls the saveChanges method as necessary.

Constructor Detail

MimeMessage

public MimeMessage(Session session)
Constructor for an empty message.

MimeMessage

public MimeMessage(Session session, InputStream is)
Constructor with an input stream contining an RFC 822 message. When this method returns, the stream will be positioned at the end of the data for the message.

Parameters: session the session context is the message input stream

MimeMessage

public MimeMessage(MimeMessage source)
Constructor with an existing message. This performs a deep copy of the target message.

Parameters: source the message to copy

MimeMessage

protected MimeMessage(Folder folder, int msgnum)
Constructor with a parent folder and message number.

Parameters: folder the parent folder msgnum the message number

MimeMessage

protected MimeMessage(Folder folder, InputStream is, int msgnum)
Constructor with a parent folder, message number, and RFC 822 input stream. When this method returns, the stream will be positioned at the end of the data for the message.

Parameters: folder the parent folder is the message input stream msgnum the message number of this message within the folder

MimeMessage

protected MimeMessage(Folder folder, InternetHeaders headers, byte[] content, int msgnum)
Constructor with a parent folder, message number, headers and byte content.

Parameters: folder the parent folder headers the headers content the content byte array msgnum the message number of this message within the folder

Method Detail

addFrom

public void addFrom(Address[] addresses)
Adds the specified addresses to From header field.

Parameters: addresses the senders of this message

Throws: IllegalWriteException if the underlying implementation does not support modification of existing values IllegalStateException if this message is obtained from a READ_ONLY folder

addHeader

public void addHeader(String name, String value)
Adds the specified header.

Parameters: name the header name value the header value

Throws: IllegalWriteException if the underlying implementation does not support modification of existing values IllegalStateException if this message is obtained from a READ_ONLY folder

addHeaderLine

public void addHeaderLine(String line)
Adds an RFC 822 header-line to this message.

Throws: IllegalWriteException if the underlying implementation does not support modification of existing values IllegalStateException if this message is obtained from a READ_ONLY folder

addRecipients

public void addRecipients(Message.RecipientType type, Address[] addresses)
Adds the given addresses to the recipients of the specified type.

Parameters: type the recipient type addresses the addresses

Throws: IllegalWriteException if the underlying implementation does not support modification of existing values IllegalStateException if this message is obtained from a READ_ONLY folder

addRecipients

public void addRecipients(Message.RecipientType type, String addresses)
Adds the given addresses to the recipients of the specified type.

Parameters: type the recipient type addresses the addresses

Throws: IllegalWriteException if the underlying implementation does not support modification of existing values IllegalStateException if this message is obtained from a READ_ONLY folder

createInternetHeaders

protected InternetHeaders createInternetHeaders(InputStream is)
Creates the headers from the given input stream.

Parameters: is the input stream to read the headers from

createMimeMessage

protected MimeMessage createMimeMessage(Session session)
Creates a new MIME message. Used by the reply method to determine the MimeMessage subclass, if any, to use.

Since: JavaMail 1.4

getAllHeaderLines

public Enumeration getAllHeaderLines()
Returns all the header-lines.

Returns: an Enumeration of Strings

getAllHeaders

public Enumeration getAllHeaders()
Returns all the headers.

Returns: an Enumeration of Header objects

getAllRecipients

public Address[] getAllRecipients()
Returns all the recipients. This returns the TO, CC, BCC, and NEWSGROUPS recipients.

getContent

public Object getContent()
Returns this message's content as a Java object.

Throws: IOException if an error occurred in the data handler layer

getContentID

public String getContentID()
Returns the value of the Content-ID header field.

See Also: MimeBodyPart

getContentLanguage

public String[] getContentLanguage()
Returns the languages specified in the Content-Language header field of this message, as defined by RFC 1766. This method returns null if this header is not available.

See Also: MimeBodyPart

getContentMD5

public String getContentMD5()
Returns the value of the Content-MD5 header field.

See Also: MimeBodyPart

getContentStream

protected InputStream getContentStream()
Returns the unencoded bytes of the content.

See Also: MimeBodyPart

getContentType

public String getContentType()
Returns the value of the RFC 822 Content-Type header field, or "text/plain" if the header is not available.

getDataHandler

public DataHandler getDataHandler()
Returns a data handler for accessing this message's content.

getDescription

public String getDescription()
Returns the Content-Description header field of this message.

If the Content-Description field is encoded as per RFC 2047, it is decoded and converted into Unicode.

See Also: MimeBodyPart

getDisposition

public String getDisposition()
Returns the value of the RFC 822 Content-Disposition header field, or null if the header is not available.

See Also: MimeBodyPart

getEncoding

public String getEncoding()
Returns the value of the Content-Transfer-Encoding header field.

See Also: MimeBodyPart

getFileName

public String getFileName()
Returns the filename associated with this message.

This method returns the value of the "filename" parameter from the Content-Disposition header field of this message. If the latter is not available, it returns the value of the "name" parameter from the Content-Type header field.

See Also: MimeBodyPart

getFlags

public Flags getFlags()
Returns the flags for this message.

getFrom

public Address[] getFrom()
Returns the value of the RFC 822 From header field. If this header field is absent, the Sender header field is used instead.

getHeader

public String[] getHeader(String name)
Returns all the values for the specified header name. Note that headers may be encoded as per RFC 2047 if they contain non-US-ASCII characters: these should be decoded.

Parameters: name the header name

getHeader

public String getHeader(String name, String delimiter)
Returns all the values for the specified header name as a single string, with headers separated by the given delimiter. If the delimiter is null, only the first header is returned.

Parameters: name the header name delimiter the delimiter

getInputStream

public InputStream getInputStream()
Returns a decoded input stream for this message's content.

Throws: IOException if an error occurs in the data handler layer

See Also: MimeBodyPart

getLineCount

public int getLineCount()
Returns the number of lines in the content of this message, or -1 if this number cannot be determined.

Note that this number may not be an exact measure, but if not -1, it will be suitable for display to the user.

getMatchingHeaderLines

public Enumeration getMatchingHeaderLines(String[] names)
Returns all the header-lines with any of the given names.

Returns: an Enumeration of Strings

getMatchingHeaders

public Enumeration getMatchingHeaders(String[] names)
Returns all the headers with any of the given names.

Returns: an Enumeration of Header objects

getMessageID

public String getMessageID()
Returns the value of the Message-ID header field.

getNonMatchingHeaderLines

public Enumeration getNonMatchingHeaderLines(String[] names)
Returns all the header-lines without any of the given names.

Returns: an Enumeration of Strings

getNonMatchingHeaders

public Enumeration getNonMatchingHeaders(String[] names)
Returns all the headers without any of the given names.

Returns: an Enumeration of Header objects

getRawInputStream

public InputStream getRawInputStream()
Returns the unencoded bytes of the content without applying any content transfer encoding.

See Also: MimeBodyPart

getReceivedDate

public Date getReceivedDate()
Returns the date on which this message was received. This returns null if the received date cannot be obtained.

getRecipients

public Address[] getRecipients(Message.RecipientType type)
Returns the recipients of the given type.

Parameters: type the recipient type

getReplyTo

public Address[] getReplyTo()
Returns the value of the RFC 822 Reply-To header field. If the header is absent, the value of the getFrom method is returned.

getSender

public Address getSender()
Returns the value of the RFC 822 Sender header field.

Since: JavaMail 1.3

getSentDate

public Date getSentDate()
Returns the value of the RFC 822 Date field. This is the date on which this message was sent.

getSize

public int getSize()
Returns the size of the content of this message in bytes, or -1 if the size cannot be determined.

Note that this number may not be an exact measure, but if not -1, it will be suitable for display to the user.

getSubject

public String getSubject()
Returns the value of the Subject header field.

If the subject is encoded as per RFC 2047, it is decoded and converted into Unicode.

isMimeType

public boolean isMimeType(String mimeType)
Indicates whether this message is of the specified MIME type.

If the subtype of mimeType is the special character '*', the subtype is ignored during the comparison.

See Also: MimeBodyPart

isSet

public boolean isSet(Flags.Flag flag)
Indicates whether the specified flag is set in this message.

Parameters: flag the flag

parse

protected void parse(InputStream is)
Parses the given input stream, setting the headers and content fields appropriately. This resets the modified flag.

Parameters: is the message input stream

removeHeader

public void removeHeader(String name)
Removes all headers with the specified name.

Parameters: name the header name

Throws: IllegalWriteException if the underlying implementation does not support modification of existing values IllegalStateException if this message is obtained from a READ_ONLY folder

reply

public Message reply(boolean replyToAll)
Returns a new message suitable for a reply to this message. The new message will have its headers set appropriately for sending, but no content.

Parameters: replyToAll the reply should be sent to all the recipients of this message

saveChanges

public void saveChanges()
Saves any changes to this message. Header fields in the message are updated appropriately to be consistent with the message contents.

Throws: IllegalWriteException if the underlying implementation does not support modification of existing values IllegalStateException if this message is obtained from a READ_ONLY folder

setContent

public void setContent(Object o, String type)
Sets the content of this message using the specified Java object and MIME type. Note that a data content handler for the MIME type must be installed and accept objects of the type given.

Parameters: o the content object type the MIME type of the object

Throws: IllegalWriteException if the underlying implementation does not support modification of existing values IllegalStateException if this message is obtained from a READ_ONLY folder

See Also: MimeBodyPart

setContent

public void setContent(Multipart mp)
Sets the content of this message to be the specified multipart.

Parameters: mp the multipart content

Throws: IllegalWriteException if the underlying implementation does not support modification of existing values IllegalStateException if this message is obtained from a READ_ONLY folder

See Also: setContent

setContentID

public void setContentID(String cid)
Sets the Content-ID header field of this message.

Throws: IllegalWriteException if the underlying implementation does not support modification of existing values IllegalStateException if this message is obtained from a READ_ONLY folder

setContentLanguage

public void setContentLanguage(String[] languages)
Sets the Content-Language header of this message.

Parameters: languages the array of language tags

Throws: IllegalWriteException if the underlying implementation does not support modification of existing values IllegalStateException if this message is obtained from a READ_ONLY folder

See Also: MimeBodyPart

setContentMD5

public void setContentMD5(String md5)
Sets the Content-MD5 header field of this message.

Throws: IllegalWriteException if the underlying implementation does not support modification of existing values IllegalStateException if this message is obtained from a READ_ONLY folder

See Also: MimeBodyPart

setDataHandler

public void setDataHandler(DataHandler datahandler)
Sets the content of this part using the specified data handler.

Throws: IllegalWriteException if the underlying implementation does not support modification of existing values IllegalStateException if this message is obtained from a READ_ONLY folder

See Also: MimeBodyPart

setDescription

public void setDescription(String description)
Sets the Content-Description header field for this message.

If the description contains non US-ASCII characters, it will be encoded using the platform default charset.

Parameters: description the content description

Throws: IllegalWriteException if the underlying implementation does not support modification of existing values IllegalStateException if this message is obtained from a READ_ONLY folder

See Also: MimeBodyPart

setDescription

public void setDescription(String description, String charset)
Sets the Content-Description header field for this message.

If the description contains non US-ASCII characters, it will be encoded using the specified charset.

Parameters: description the content description charset the charset used for any encoding

Throws: IllegalWriteException if the underlying implementation does not support modification of existing values IllegalStateException if this message is obtained from a READ_ONLY folder

See Also: MimeBodyPart

setDisposition

public void setDisposition(String disposition)
Sets the Content-Disposition header field of this message.

Parameters: disposition the disposition value to set, or null to remove

Throws: IllegalWriteException if the underlying implementation does not support modification of existing values IllegalStateException if this message is obtained from a READ_ONLY folder

See Also: MimeBodyPart

setFileName

public void setFileName(String filename)
Sets the filename associated with this part.

Throws: IllegalWriteException if the underlying implementation does not support modification of existing values IllegalStateException if this message is obtained from a READ_ONLY folder

See Also: MimeBodyPart

setFlags

public void setFlags(Flags flag, boolean set)
Sets the flags for this message.

Throws: IllegalWriteException if the underlying implementation does not support modification of existing values IllegalStateException if this message is obtained from a READ_ONLY folder

setFrom

public void setFrom(Address address)
Sets the RFC 822 From header field.

Parameters: address the sender of this message

Throws: IllegalWriteException if the underlying implementation does not support modification of existing values IllegalStateException if this message is obtained from a READ_ONLY folder

setFrom

public void setFrom()
Sets the RFC 822 From header field using the value of the InternetAddress.getLocalAddress method.

Throws: IllegalWriteException if the underlying implementation does not support modification of existing values IllegalStateException if this message is obtained from a READ_ONLY folder

setHeader

public void setHeader(String name, String value)
Sets the specified header.

Parameters: name the header name value the header value

Throws: IllegalWriteException if the underlying implementation does not support modification of existing values IllegalStateException if this message is obtained from a READ_ONLY folder

setRecipients

public void setRecipients(Message.RecipientType type, Address[] addresses)
Sets the recipients of the given type.

Parameters: type the recipient type addresses the addresses, or null to remove recipients of this type

Throws: IllegalWriteException if the underlying implementation does not support modification of existing values IllegalStateException if this message is obtained from a READ_ONLY folder

setRecipients

public void setRecipients(Message.RecipientType type, String addresses)
Sets the recipients of the given type.

Parameters: type the recipient type addresses the addresses, or null to remove recpients of this type

Throws: IllegalWriteException if the underlying implementation does not support modification of existing values IllegalStateException if this message is obtained from a READ_ONLY folder

setReplyTo

public void setReplyTo(Address[] addresses)
Sets the RFC 822 Reply-To header field.

Parameters: addresses the addresses, or null to remove this header

Throws: IllegalWriteException if the underlying implementation does not support modification of existing values IllegalStateException if this message is obtained from a READ_ONLY folder

setSender

public void setSender(Address address)
Sets the RFC 822 Sender header field.

Parameters: address the sender of this message

Throws: IllegalWriteException if the underlying implementation does not support modification of existing values IllegalStateException if this message is obtained from a READ_ONLY folder

Since: JavaMail 1.3

setSentDate

public void setSentDate(Date date)
Sets the RFC 822 Date header field.

Parameters: date the sent date, or null to remove this header

Throws: IllegalWriteException if the underlying implementation does not support modification of existing values IllegalStateException if this message is obtained from a READ_ONLY folder

setSubject

public void setSubject(String subject)
Sets the Subject header field.

If the subject contains non US-ASCII characters, it will be encoded using the platform default charset.

Parameters: subject the subject

Throws: IllegalWriteException if the underlying implementation does not support modification of existing values IllegalStateException if this message is obtained from a READ_ONLY folder

setSubject

public void setSubject(String subject, String charset)
Sets the Subject header field.

If the subject contains non US-ASCII characters, it will be encoded using the specified charset.

Parameters: subject the subject charset the charset used for any encoding

Throws: IllegalWriteException if the underlying implementation does not support modification of existing values IllegalStateException if this message is obtained from a READ_ONLY folder

setText

public void setText(String text)
Sets the content of this message using the specified text, and with a MIME type of "text/plain".

If the string contains non US-ASCII characters, it will be encoded using the platform default charset.

Parameters: text the text content

See Also: setText

setText

public void setText(String text, String charset)
Sets the content of this message using the specified text, and with a MIME type of "text/plain".

If the string contains non US-ASCII characters, it will be encoded using the specified charset.

Parameters: text the text content charset the charset used for any encoding

See Also: setText

setText

public void setText(String text, String charset, String subtype)
Sets the content of this message using the specified text, and with a text MIME type of the specified subtype.

If the string contains non US-ASCII characters, it will be encoded using the specified charset.

Parameters: text the text content charset the charset used for any encoding subtype the MIME text subtype (e.g. "plain", "html")

Since: JavaMail 1.4

See Also: setText

updateHeaders

protected void updateHeaders()
Updates the headers of this part, based on the content.

Throws: IllegalWriteException if the underlying implementation does not support modification of existing values IllegalStateException if this message is obtained from a READ_ONLY folder

See Also: MimeBodyPart

updateMessageId

protected void updateMessageId()
Updates the Message-ID header. This method is called by updateHeaders, and should set the Message-Id header to a suitably unique value if overridden.

Since: JavaMail 1.4

writeTo

public void writeTo(OutputStream os)
Writes this message to the specified stream in RFC 822 format.

Throws: IOException if an error occurs writing to the stream or in the data handler layer

writeTo

public void writeTo(OutputStream os, String[] ignoreList)
Writes this message to the specified stream in RFC 822 format, without the specified headers.

Throws: IOException if an error occurs writing to the stream or in the data handler layer

© Copyright 2003, 2004 The Free Software Foundation, All rights reserved