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 }