001    /****************************************************************
002     * Licensed to the Apache Software Foundation (ASF) under one   *
003     * or more contributor license agreements.  See the NOTICE file *
004     * distributed with this work for additional information        *
005     * regarding copyright ownership.  The ASF licenses this file   *
006     * to you under the Apache License, Version 2.0 (the            *
007     * "License"); you may not use this file except in compliance   *
008     * with the License.  You may obtain a copy of the License at   *
009     *                                                              *
010     *   http://www.apache.org/licenses/LICENSE-2.0                 *
011     *                                                              *
012     * Unless required by applicable law or agreed to in writing,   *
013     * software distributed under the License is distributed on an  *
014     * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY       *
015     * KIND, either express or implied.  See the License for the    *
016     * specific language governing permissions and limitations      *
017     * under the License.                                           *
018     ****************************************************************/
019    
020    package org.apache.james.mime4j.field.address;
021    
022    import java.io.Serializable;
023    import java.io.StringReader;
024    import java.util.List;
025    
026    import org.apache.james.mime4j.field.address.parser.AddressListParser;
027    import org.apache.james.mime4j.field.address.parser.ParseException;
028    
029    /**
030     * The abstract base for classes that represent RFC2822 addresses. This includes
031     * groups and mailboxes.
032     */
033    public abstract class Address implements Serializable {
034    
035        private static final long serialVersionUID = 634090661990433426L;
036    
037        /**
038         * Adds any mailboxes represented by this address into the given List. Note
039         * that this method has default (package) access, so a doAddMailboxesTo
040         * method is needed to allow the behavior to be overridden by subclasses.
041         */
042        final void addMailboxesTo(List<Mailbox> results) {
043            doAddMailboxesTo(results);
044        }
045    
046        /**
047         * Adds any mailboxes represented by this address into the given List. Must
048         * be overridden by concrete subclasses.
049         */
050        protected abstract void doAddMailboxesTo(List<Mailbox> results);
051    
052        /**
053         * Formats the address as a human readable string, not including the route.
054         * The resulting string is intended for display purposes only and cannot be
055         * used for transport purposes.
056         * 
057         * @return a string representation of this address intended to be displayed
058         * @see #getDisplayString(boolean)
059         */
060        public final String getDisplayString() {
061            return getDisplayString(false);
062        }
063    
064        /**
065         * Formats the address as a human readable string, not including the route.
066         * The resulting string is intended for display purposes only and cannot be
067         * used for transport purposes.
068         * 
069         * For example, if the unparsed address was
070         * 
071         * <"Joe Cheng"@joecheng.com>
072         * 
073         * this method would return
074         * 
075         * <Joe Cheng@joecheng.com>
076         * 
077         * which is not valid for transport; the local part would need to be
078         * re-quoted.
079         * 
080         * @param includeRoute
081         *            <code>true</code> if the route should be included if it
082         *            exists, <code>false</code> otherwise.
083         * @return a string representation of this address intended to be displayed.
084         */
085        public abstract String getDisplayString(boolean includeRoute);
086    
087        /**
088         * Returns a string representation of this address that can be used for
089         * transport purposes. The route is never included in this representation
090         * because routes are obsolete and RFC 5322 states that obsolete syntactic
091         * forms MUST NOT be generated.
092         * 
093         * @return a string representation of this address intended for transport
094         *         purposes.
095         */
096        public abstract String getEncodedString();
097    
098        /**
099         * Parses the specified raw string into an address.
100         * 
101         * @param rawAddressString
102         *            string to parse.
103         * @return an <code>Address</code> object for the specified string.
104         * @throws IllegalArgumentException
105         *             if the raw string does not represent a single address.
106         */
107        public static Address parse(String rawAddressString) {
108            AddressListParser parser = new AddressListParser(new StringReader(
109                    rawAddressString));
110            try {
111                return Builder.getInstance().buildAddress(parser.parseAddress());
112            } catch (ParseException e) {
113                throw new IllegalArgumentException(e);
114            }
115        }
116    
117        @Override
118        public String toString() {
119            return getDisplayString(false);
120        }
121    
122    }