message.java

手机游戏例子

/******************************************************************************
 * Mail4ME - Mail for the Java 2 Micro Edition
 *
 * A lightweight, J2ME- (and also J2SE-) compatible package for sending and
 * receiving Internet mail messages using the SMTP and POP3 protocols.
 *
 * Copyright (c) 2000-2002 J鰎g Pleumann <[e-mail]>
 *
 * Mail4ME is part of the EnhydraME family of projects. See the following web
 * sites for more information:
 *
 * -> http://mail4me.enhydra.org
 * -> http://me.enhydra.org
 *
 * Mail4ME is distributed under the Enhydra Public License (EPL), which is
 * discussed in great detail here:
 *
 * -> http://www.enhydra.org/software/license/index.html
 *
 * Have fun!
 ******************************************************************************/
package de.trantor.mail;

import java.util.Calendar;
import java.util.Random;
import java.util.TimeZone;
import java.util.Vector;
import java.io.IOException;

/**
 * Represents an internet mail message according to RFC 822. From the user's
 * point of view, the class basically consists of two parts:
 *
 * <ul>
 *   <li> An array-like structure holding the message's header lines. Each
 *        header line is stored in the textual format that is also used during
 *        transmission. To make access to the header data convenient, there are
 *        several methods for dealing with header lines as a whole, with names
 *        and fields separately and for searching specific header fields.
 *
 *   <li> An array-like structure holding the message's body lines. Again,
 *        several methods are provided to manipulate the body part of the
 *        message.
 * </ul>
 *
 * From the classes' internal point of view, both array-like structures are
 * held in a single Vector instance to save memory.
 * <p>
 * One could argue that the fully textual representation of a message results
 * in a slower operation than would be possible with - for example - a
 * hashtable. This is true, but the representation has been chosen with regard
 * to several concerns:
 *
 * <ul>
 *   <li> The limited memory of J2ME devices. The textual representation
 *        requires a lot less memory than a data structure separating field
 *        names and field values would.
 *
 *   <li> The principal of minimal mangling. This principle dictates that a
 *        system (possibly) responsible for e-mail transfer (a mailing list
 *        processor, for example) should keep changes to the messages to a
 *        minimum. We're trying to adhere to this principle in order to not
 *        limit the possible applications of the Mail4ME package. Since the
 *        internal representation of an e-mail inside a Message instance is
 *        equal to the external one, there is no mangling at all, as long as
 *        the message header or body is not modified on purpose. Note that this
 *        would not be the case if the headers were kept in, say, a hashtable,
 *        because it would be complicated to reconstruct the original order of
 *        the header fields when converting the message to the external
 *        representation again.
 * </ul>
 *
 * Messages can be retrieved from a POP3 server using the Pop3Client class.
 * They can be sent across the Internet using an instance of SmtpClient.
 * Depending on the application, it might be necessary to enclose the message
 * in an Envelope instance before sending it.
 *
 * @see Pop3Client
 * @see SmtpClient
 * @see Envelope
 */
public class Message {

    /**
     * Holds the message's header and body, line by line and separated by the
     * usual empty line between header and body.
     */
    private Vector lines = new Vector();

    /**
     * Holds the number of lines that belong to the message's header, that is,
     * the number of lines up to (but no including) the empty line that separates
     * header and body.
     */
    private int headerSize = 0;

    /**
     * Contructs a new, totally empty message.
     *
     * @see #Message(java.lang.String, java.lang.String, java.lang.String)
     */
    public Message() {
        lines.addElement("");
    }

    /**
     * Contructs a new message with the given sender ("From:" field), recipient
     * ("To:" field) and subject, respectively. If any of the parameters is
     * null, the corresponding field is not added to the message. The method
     * ensures that the newly created message gets a message ID and a date
     * field holding the current date/time.
     *
     * @see #Message()
     */
    public Message(String from, String to, String subject) {
        lines.addElement("");

        if (from != null) {
            addHeaderLine("From: " + from);

            /**
             * If we have sender information, we use it to construct a (hopefully)
             * unique message ID.
             */
            String s = getMachineAddress(from);
            addHeaderLine("Message-ID: <" + getRandomString() + "." + s + ">");
        }
        else {
            /**
             * Without sender information we have nothing to feed into the message
             * ID generator, so all we can do is keep our fingers crossed and hope
             * that the mixture of millisecond counter and random number suffices.
             */
            addHeaderLine("Message-ID: <" + getRandomString() + ">");
        }

        if (to != null) {
            addHeaderLine("To: " + to);
        }

        if (subject != null) {
            addHeaderLine("Subject: " + subject);
        }

        addHeaderLine("Date: " + getCanonicalDate(Calendar.getInstance(), TimeZone.getDefault()));
    }

    /**
     * Returns one of the message's header lines by its index.
     *
     * @see #addHeaderLine
     * @see #getHeaderLineCount
     * @see #setHeaderLine
     * @see #insertHeaderLine
     * @see #removeHeaderLine
     */
    public String getHeaderLine(int index) throws ArrayIndexOutOfBoundsException {
        if ((index < 0) || (index >= headerSize)) {
            throw new ArrayIndexOutOfBoundsException(index);
        }

        return (String)lines.elementAt(index);
    }

    /**
     * Returns the field name one of the given header line. The field name is
     * everything up to, but not including the first ':' of the line. If the
     * given header line does not contain a ':' character at all, the line is
     * assumed not to hold a correct header field, and null is returned
     * instead.
     *
     * @see #getHeaderValue(int)
     * @see #getHeaderValue(java.lang.String)
     * @see #getHeaderValue(java.lang.String, java.lang.String)
     * @see #getAllHeaderValues
     * @see #setHeaderValue
     * @see #getHeaderIndex(java.lang.String)
     * @see #getHeaderIndex(java.lang.String, int)
     */
    public String getHeaderName(int index) throws ArrayIndexOutOfBoundsException {
        return getStringName(getHeaderLine(index));
    }

    /**
     * Returns the field value one of the given header line. The field value is
     * everything that follows the first ':' of the line. Leading and trailing
     * spaces are removed. If the given header line does not contain a ':'
     * character at all, the line is assumed to hold a nameless value, and the
     * whole line is returned instead.
     *
     * @see #getHeaderName
     * @see #getHeaderValue(java.lang.String)
     * @see #getHeaderValue(java.lang.String, java.lang.String)
     * @see #getAllHeaderValues
     * @see #setHeaderValue
     * @see #getHeaderIndex(java.lang.String)
     * @see #getHeaderIndex(java.lang.String, int)
     */
    public String getHeaderValue(int index) throws ArrayIndexOutOfBoundsException {
        return getStringValue(getHeaderLine(index));
    }

    /**
     * Searches for a header field. The method returns the index of the first
     * header line that contains the given field name, and it starts searching
     * from the given index. If the header field can't be found, -1 is returned
     * instead.
     *
     * @see #getHeaderName
     * @see #getHeaderValue(int)
     * @see #getHeaderValue(java.lang.String)
     * @see #getHeaderValue(java.lang.String, java.lang.String)
     * @see #getAllHeaderValues
     * @see #setHeaderValue
     * @see #getHeaderIndex(java.lang.String)
     */
    public int getHeaderIndex(String name, int startIndex) {
        String lowerName = name.toLowerCase();

        for (int i = startIndex; i < headerSize; i++) {
            String s = getHeaderName(i);
            if ((s != null) && (s.toLowerCase().equals(lowerName))) {
                return i;
            }
        }

        return -1;
    }

    /**
     * Searches for a header field. The method returns the index of the first
     * header line that contains the given field name, and it starts searching
     * from the first header line. If the header field can't be found, -1 is
     * returned instead.
     *
     * @see #getHeaderName
     * @see #getHeaderValue(int)
     * @see #getHeaderValue(java.lang.String)
     * @see #getHeaderValue(java.lang.String, java.lang.String)
     * @see #getAllHeaderValues
     * @see #setHeaderValue
     * @see #getHeaderIndex(java.lang.String, int)
     */
    public int getHeaderIndex(String name) {
        return getHeaderIndex(name, 0);
    }

    /**
     * Returns the value of the first occurence of the given header field.
     * If the field doesn't exist, null is returned instead.
     *
     * @see #getHeaderName
     * @see #getHeaderValue(int)
     * @see #getHeaderValue(java.lang.String, java.lang.String)
     * @see #getAllHeaderValues
     * @see #setHeaderValue
     * @see #getHeaderIndex(java.lang.String)
     * @see #getHeaderIndex(java.lang.String, int)
     */
    public String getHeaderValue(String name) {
        return getHeaderValue(name, null);
    }

    /**
     * Returns the value of the first occurence of the given header field.
     * If the field does not exist at all, the specified default value is
     * returned instead.
     *
     * @see #getHeaderName
     * @see #getHeaderValue(int)
     * @see #getHeaderValue(java.lang.String)
     * @see #getAllHeaderValues
     * @see #setHeaderValue
     * @see #getHeaderIndex(java.lang.String)
     * @see #getHeaderIndex(java.lang.String, int)
     */
    public String getHeaderValue(String name, String def) {
        int i = getHeaderIndex(name);

        if (i == -1) {
            return def;
        }
        else {
            return getHeaderValue(i);
        }
    }

    /**
     * Returns the values of all occurences of the given header field in the
     * this message. The results are stored in a string array. If the given
     * field doesn't exist at all, an empty array is returned.
     *
     * @see #getHeaderName
     * @see #getHeaderValue(int)
     * @see #getHeaderValue(java.lang.String)
     * @see #getHeaderValue(java.lang.String, java.lang.String)
     * @see #setHeaderValue
     * @see #getHeaderIndex(java.lang.String)
     * @see #getHeaderIndex(java.lang.String, int)
     */
    public String[] getAllHeaderValues(String name) {
        Vector lines = new Vector();

        int i = getHeaderIndex(name);
        while (i != -1) {
            lines.addElement(getHeaderValue(i));
            i = getHeaderIndex(name, i + 1);
        }

        String[] result = new String[lines.size()];
        for (int j = 0; j < lines.size(); j++) {
            result[j] = (String)lines.elementAt(j);
        }

        return result;
    }

    /**
     * Replaces the given header line by a new one.
     *
     * @see #addHeaderLine
     * @see #getHeaderLineCount
     * @see #getHeaderLine
     * @see #insertHeaderLine
     * @see #removeHeaderLine
     */
    public void setHeaderLine(int index, String line) {
        if ((index < 0) || (index >= headerSize)) {
            throw new ArrayIndexOutOfBoundsException(index);
        }

        lines.setElementAt(line, index);
    }

    /**
     * Returns the number of available header lines.
     *
     * @see #addHeaderLine
     * @see #getHeaderLine
     * @see #setHeaderLine
     * @see #insertHeaderLine
     * @see #removeHeaderLine
     */
    public int getHeaderLineCount() {
        return headerSize;
    }

    /**
     * Adds a new line to the end of the message's header, returning its index.
     *
     * @see #getHeaderLineCount
     * @see #getHeaderLine
     * @see #setHeaderLine
     * @see #insertHeaderLine
     * @see #removeHeaderLine
     */
    public int addHeaderLine(String line) {
        lines.insertElementAt(line, headerSize);
        return headerSize++;
    }

    /**
     * Inserts a new line at a given position into the message's header.
     *
     * @see #addHeaderLine
     * @see #getHeaderLineCount
     * @see #getHeaderLine
     * @see #setHeaderLine
     * @see #removeHeaderLine
     */
    public void insertHeaderLine(int index, String line) {
        if ((index < 0) || (index > headerSize)) {
            throw new ArrayIndexOutOfBoundsException(index);
        }

        lines.insertElementAt(line, index);
        headerSize++;
    }

    /**
     * Removes a complete header line.
     *
     * @see #addHeaderLine
     * @see #getHeaderLineCount
     * @see #getHeaderLine
     * @see #setHeaderLine
     * @see #insertHeaderLine
     */
    public void removeHeaderLine(int index) {
        if ((index < 0) || (index >= headerSize)) {
            throw new ArrayIndexOutOfBoundsException(index);
        }

        lines.removeElementAt(index);
        headerSize--;
    }

    /**
     * Sets a header field to a given value. This method changes the first
     * occurence of the given header field to the given value. If the field
     * doesn't exist in the message's header, it is appended as a new header
     * line. If the value parameter is null, an attempt is made to remove the
     * given field from the header.
     *
     * @see #getHeaderName
     * @see #getHeaderValue(int)
     * @see #getHeaderValue(java.lang.String)
     * @see #getHeaderValue(java.lang.String, java.lang.String)
     * @see #getAllHeaderValues
     * @see #getHeaderIndex(java.lang.String)
     * @see #getHeaderIndex(java.lang.String, int)
     */
    public void setHeaderValue(String name, String value) {
        int i = getHeaderIndex(name);
        if (i == -1) {
            if (value != null) {