Address.java

/****************************************************************
 * Licensed to the Apache Software Foundation (ASF) under one   *
 * or more contributor license agreements.  See the NOTICE file *
 * distributed with this work for additional information        *
 * regarding copyright ownership.  The ASF licenses this file   *
 * to you under the Apache License, Version 2.0 (the            *
 * "License"); you may not use this file except in compliance   *
 * with the License.  You may obtain a copy of the License at   *
 *                                                              *
 *   http://www.apache.org/licenses/LICENSE-2.0                 *
 *                                                              *
 * Unless required by applicable law or agreed to in writing,   *
 * software distributed under the License is distributed on an  *
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY       *
 * KIND, either express or implied.  See the License for the    *
 * specific language governing permissions and limitations      *
 * under the License.                                           *
 ****************************************************************/

package org.apache.james.mime4j.field.address;

import java.io.Serializable;
import java.io.StringReader;
import java.util.List;

import org.apache.james.mime4j.field.address.parser.AddressListParser;
import org.apache.james.mime4j.field.address.parser.ParseException;

/**
 * The abstract base for classes that represent RFC2822 addresses. This includes
 * groups and mailboxes.
 */
public abstract class Address implements Serializable {

    private static final long serialVersionUID = 634090661990433426L;

    /**
     * Adds any mailboxes represented by this address into the given List. Note
     * that this method has default (package) access, so a doAddMailboxesTo
     * method is needed to allow the behavior to be overridden by subclasses.
     */
    final void addMailboxesTo(List<Mailbox> results) {
        doAddMailboxesTo(results);
    }

    /**
     * Adds any mailboxes represented by this address into the given List. Must
     * be overridden by concrete subclasses.
     */
    protected abstract void doAddMailboxesTo(List<Mailbox> results);

    /**
     * Formats the address as a human readable string, not including the route.
     * The resulting string is intended for display purposes only and cannot be
     * used for transport purposes.
     * 
     * @return a string representation of this address intended to be displayed
     * @see #getDisplayString(boolean)
     */
    public final String getDisplayString() {
        return getDisplayString(false);
    }

    /**
     * Formats the address as a human readable string, not including the route.
     * The resulting string is intended for display purposes only and cannot be
     * used for transport purposes.
     * 
     * For example, if the unparsed address was
     * 
     * <"Joe Cheng"@joecheng.com>
     * 
     * this method would return
     * 
     * <Joe Cheng@joecheng.com>
     * 
     * which is not valid for transport; the local part would need to be
     * re-quoted.
     * 
     * @param includeRoute
     *            <code>true</code> if the route should be included if it
     *            exists, <code>false</code> otherwise.
     * @return a string representation of this address intended to be displayed.
     */
    public abstract String getDisplayString(boolean includeRoute);

    /**
     * Returns a string representation of this address that can be used for
     * transport purposes. The route is never included in this representation
     * because routes are obsolete and RFC 5322 states that obsolete syntactic
     * forms MUST NOT be generated.
     * 
     * @return a string representation of this address intended for transport
     *         purposes.
     */
    public abstract String getEncodedString();

    /**
     * Parses the specified raw string into an address.
     * 
     * @param rawAddressString
     *            string to parse.
     * @return an <code>Address</code> object for the specified string.
     * @throws IllegalArgumentException
     *             if the raw string does not represent a single address.
     */
    public static Address parse(String rawAddressString) {
        AddressListParser parser = new AddressListParser(new StringReader(
                rawAddressString));
        try {
            return Builder.getInstance().buildAddress(parser.parseAddress());
        } catch (ParseException e) {
            throw new IllegalArgumentException(e);
        }
    }

    @Override
    public String toString() {
        return getDisplayString(false);
    }

}