jodd.mail

Class EmailAddress

java.lang.Object

jodd.mail.EmailAddress

public class EmailAddress
extends java.lang.Object

A utility class to parse, clean up, and extract email addresses from messages per RFC2822 syntax. Designed to integrate with Javamail (this class will require that you have a javamail mail.jar in your classpath), but you could easily change the existing methods around to not use Javamail at all. For example, if you're changing the code, see the difference between getInternetAddress and getDomain: the latter doesn't depend on any javamail code. This is all a by-product of what this class was written for, so feel free to modify it to suit your needs.

For real-world addresses, this class is roughly 3-4 times slower than parsing with InternetAddress, but it can handle a whole lot more. Because of sensible design tradeoffs made in javamail, if InternetAddress has trouble parsing, it might throw an exception, but often it will silently leave the entire original string in the result of ia.getAddress(). This class can be trusted to only provide authenticated results.

This class has been tested on a few thousand real-world addresses, and is live in production environments, but you may want to do some of your own testing to ensure that it works for you. In other words, it's not beta, but it's not guaranteed yet.

Comments/Questions/Corrections welcome: java <at> caseyconnor.org

Started with code by Les Hazlewood: leshazlewood.com.

Modified/added: removed some functions, added support for CFWS token, corrected FWSP token, added some boolean flags, added getInternetAddress and extractHeaderAddresses and other methods, some optimization.

Where Mr. Hazlewood's version was more for ensuring certain forms that were passed in during registrations, etc, this handles more types of verifying as well a few forms of extracting the data in predictable, cleaned-up chunks.

Note: CFWS means the "comment folded whitespace" token from 2822, in other words, whitespace and comment text that is enclosed in ()'s.

Limitations: doesn't support nested CFWS (comments within (other) comments), doesn't support mailbox groups except when flat-extracting addresses from headers or when doing verification, doesn't support any of the obs-* tokens. Also: the getInternetAddress and extractHeaderAddresses methods return InternetAddress objects; if the personal name has any quotes or \'s in it at all, the InternetAddress object will always escape the name entirely and put it in quotes, so multiple-token personal names with those characters somewhere in them will always be munged into one big escaped string. This is not really a big deal at all, but I mention it anyway. (And you could get around it by a simple modification to those methods to not use InternetAddress objects.) See the docs of those methods for more info.

Note: This does not do any header-length-checking. There are no such limitations on the email address grammar in 2822, though email headers in general do have length restrictions. So if the return path is 40000 unfolded characters long, but otherwise valid under 2822, this class will pass it.

Examples of passing (2822-valid) addresses, believe it or not:

bob @example.com
"bob" @ example.com
bob (comment) (other comment) @example.com (personal name)
"<bob \" (here) " < (hi there) "bob(the man)smith" (hi) @ (there) example.com (hello) > (again)

(none of which are permitted by javamail, incidentally)

By using getInternetAddress(), you can retrieve an InternetAddress object that, when toString()'ed, would reveal that the parser had converted the above into:

<bob@example.com>
<bob@example.com>
"personal name" <bob@example.com>
"<bob \" (here)" <"bob(the man)smith"@example.com>

(respectively)

If parsing headers, however, you'll probably be calling extractHeaderAddresses().

A future improvement may be to use this class to extract info from corrupted addresses, but for now, it does not permit them.

Some of the configuration booleans allow a bit of tweaking already. The source code can be compiled with these booleans in various states. They are configured to what is probably the most commonly-useful state.

Field Summary

Fields

Modifier and Type	Field and Description
static java.util.regex.Pattern	VALID_PATTERN

Constructor Summary

Constructors

Constructor and Description
EmailAddress()
EmailAddress(java.lang.String text)

Method Summary

Methods

Modifier and Type	Method and Description
boolean	equals(java.lang.Object o)
java.lang.String	getLabel() Party label associated with this address, for example, 'Home', 'Work', etc.
java.lang.String	getText() Returns the actual email address string, e.g.
int	hashCode()
boolean	isBouncing() Returns whether or not any emails sent to this email address come back as bounced (undeliverable).
boolean	isValid() Returns whether or not the text represented by this object instance is valid according to the RFC 2822 rules.
static boolean	isValidText(java.lang.String email) Utility method that checks to see if the specified string is a valid email address according to the RFC 2822 specification.
boolean	isVerified() Returns whether or not the party associated with this email has verified that it is their email address.
void	setBouncing(boolean bouncing)
void	setLabel(java.lang.String label)
void	setText(java.lang.String text)
void	setVerified(boolean verified)
java.lang.String	toString()

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

VALID_PATTERN

public static final java.util.regex.Pattern VALID_PATTERN

Constructor Detail

EmailAddress

public EmailAddress()

EmailAddress

public EmailAddress(java.lang.String text)

Method Detail

getText

public java.lang.String getText()

Returns the actual email address string, e.g. someone@somewhere.com

Returns:

the actual email address string.

setText

public void setText(java.lang.String text)

isBouncing

public boolean isBouncing()

Returns whether or not any emails sent to this email address come back as bounced (undeliverable).

Default is false for convenience's sake - if a bounced message is ever received for this address, this value should be set to true until verification can made.

Returns:

whether or not any emails sent to this email address come back as bounced (undeliverable).

setBouncing

public void setBouncing(boolean bouncing)

isVerified

public boolean isVerified()

Returns whether or not the party associated with this email has verified that it is their email address.

Verification is usually done by sending an email to this address and waiting for the party to respond or click a specific link in the email.

Default is false.

Returns:

whether or not the party associated with this email has verified that it is their email address.

setVerified

public void setVerified(boolean verified)

getLabel

public java.lang.String getLabel()

Party label associated with this address, for example, 'Home', 'Work', etc.

Returns:

a label associated with this address, for example 'Home', 'Work', etc.

setLabel

public void setLabel(java.lang.String label)

isValid

public boolean isValid()

Returns whether or not the text represented by this object instance is valid according to the RFC 2822 rules.

Returns:

true if the text represented by this instance is valid according to RFC 2822, false otherwise.

isValidText

public static boolean isValidText(java.lang.String email)

Utility method that checks to see if the specified string is a valid email address according to the RFC 2822 specification.

Parameters:

email - the email address string to test for validity.

Returns:

true if the given text valid according to RFC 2822, false otherwise.

equals

public boolean equals(java.lang.Object o)

Overrides:

equals in class java.lang.Object

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object