1 /****************************************************************
2 * Licensed to the Apache Software Foundation (ASF) under one *
3 * or more contributor license agreements. See the NOTICE file *
4 * distributed with this work for additional information *
5 * regarding copyright ownership. The ASF licenses this file *
6 * to you under the Apache License, Version 2.0 (the *
7 * "License"); you may not use this file except in compliance *
8 * with the License. You may obtain a copy of the License at *
9 * *
10 * http://www.apache.org/licenses/LICENSE-2.0 *
11 * *
12 * Unless required by applicable law or agreed to in writing, *
13 * software distributed under the License is distributed on an *
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY *
15 * KIND, either express or implied. See the License for the *
16 * specific language governing permissions and limitations *
17 * under the License. *
18 ****************************************************************/
19
20 package org.apache.james.mime4j.field.address;
21
22 import java.io.Serializable;
23 import java.io.StringReader;
24 import java.util.List;
25
26 import org.apache.james.mime4j.field.address.parser.AddressListParser;
27 import org.apache.james.mime4j.field.address.parser.ParseException;
28
29 /**
30 * The abstract base for classes that represent RFC2822 addresses. This includes
31 * groups and mailboxes.
32 */
33 public abstract class Address implements Serializable {
34
35 private static final long serialVersionUID = 634090661990433426L;
36
37 /**
38 * Adds any mailboxes represented by this address into the given List. Note
39 * that this method has default (package) access, so a doAddMailboxesTo
40 * method is needed to allow the behavior to be overridden by subclasses.
41 */
42 final void addMailboxesTo(List<Mailbox> results) {
43 doAddMailboxesTo(results);
44 }
45
46 /**
47 * Adds any mailboxes represented by this address into the given List. Must
48 * be overridden by concrete subclasses.
49 */
50 protected abstract void doAddMailboxesTo(List<Mailbox> results);
51
52 /**
53 * Formats the address as a human readable string, not including the route.
54 * The resulting string is intended for display purposes only and cannot be
55 * used for transport purposes.
56 *
57 * @return a string representation of this address intended to be displayed
58 * @see #getDisplayString(boolean)
59 */
60 public final String getDisplayString() {
61 return getDisplayString(false);
62 }
63
64 /**
65 * Formats the address as a human readable string, not including the route.
66 * The resulting string is intended for display purposes only and cannot be
67 * used for transport purposes.
68 *
69 * For example, if the unparsed address was
70 *
71 * <"Joe Cheng"@joecheng.com>
72 *
73 * this method would return
74 *
75 * <Joe Cheng@joecheng.com>
76 *
77 * which is not valid for transport; the local part would need to be
78 * re-quoted.
79 *
80 * @param includeRoute
81 * <code>true</code> if the route should be included if it
82 * exists, <code>false</code> otherwise.
83 * @return a string representation of this address intended to be displayed.
84 */
85 public abstract String getDisplayString(boolean includeRoute);
86
87 /**
88 * Returns a string representation of this address that can be used for
89 * transport purposes. The route is never included in this representation
90 * because routes are obsolete and RFC 5322 states that obsolete syntactic
91 * forms MUST NOT be generated.
92 *
93 * @return a string representation of this address intended for transport
94 * purposes.
95 */
96 public abstract String getEncodedString();
97
98 /**
99 * 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 }