votorola.a.voter

Class IDPair

java.lang.Object

IDPair

All Implemented Interfaces:

Serializable

Direct Known Subclasses:

VSession.User

@ThreadSafe
public class IDPair
extends Object
implements Serializable

A user identifier in two forms: email address and mailish username. Both are globally unique and map 1:1.

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
static IDPair	NOBODY An ID pair for a non-existent user.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	IDPair(IDPair other) Constructs an IDPair by copying from another.
	IDPair(String _email, String _username, boolean _isFromEmail) Constructs an IDPair.

Method Summary

Methods

Modifier and Type	Method and Description
static StringBuilder	appendUsername(String email, StringBuilder b) Translates an email address to a mailish username, and appends the result to the specified string builder.
static StringBuilder	buildUserMnemonic(String username, StringBuilder sB) Appends a short abbreviation of the username to the string builder.
String	email() Identifies the user by canonical email address.
static String	emailOrNobody(String email, ResourceBundle resA) Returns the same email address; or, if it is null or NOBODY, the localized string for "nobody".
boolean	equals(Object o) True iff o is an ID pair constructed from the same (equals) email address.
boolean	equalsEmail(Object o) Returns true iff o is an ID pair with the same email address.
static IDPair	fromEmail(String email) Constructs an IDPair from a canonical email address.
static IDPair	fromUsername(String username) Constructs an IDPair from a username, which will automatically be translated to normal form.
boolean	isFromEmail() Deprecated. as an unecessary complexity and source of potential bugs.
static String	normalUsername(String name) Translates the mailish username to normal form by shifting the first letter to uppercase and substituting spaces for underscores.
static InternetAddress	toInternetAddress(String username) Translates a username to a canonical email address.
String	toString() Returns the same identifier from which the ID pair was constructed.
static String	toUsername(String email) Translates a canonical email address to a mailish username in normal form.
String	username() Identifies the user by mailish username.

Methods inherited from class java.lang.Object

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

Field Detail

NOBODY

public static IDPair NOBODY

An ID pair for a non-existent user.

Constructor Detail

IDPair

public IDPair(String _email,
      String _username,
      boolean _isFromEmail)

Constructs an IDPair. The username will automatically be translated to normal form.

See Also:

email(), username(), isFromEmail()

IDPair

protected IDPair(IDPair other)

Constructs an IDPair by copying from another.

Method Detail

fromEmail

public static IDPair fromEmail(String email)

Constructs an IDPair from a canonical email address.

Returns:

a newly constructed IDPair, or NOBODY if the email address is null.

See Also:

email(), InternetAddressX.canonicalAddress(String)

fromUsername

public static IDPair fromUsername(String username)
                           throws AddressException

Constructs an IDPair from a username, which will automatically be translated to normal form.

Returns:

a newly constructed IDPair, or NOBODY if the username is null.

Throws:

AddressException

See Also:

username()

appendUsername

public static StringBuilder appendUsername(String email,
                           StringBuilder b)

Translates an email address to a mailish username, and appends the result to the specified string builder.

             Email address  Mailish username
   -----------------------  ------------------------------
            Smith@acme.com  Smith AcmeCom
            smith@acme.com  Smith-AcmeCom
   ThomasvonderElbe@gmx.de  ThomasvonderElbe GmxDe
            mike@zelea.com  Mike-ZeleaCom

Note that MediaWiki ignores the case of the first letter of the username, forcing all names to begin with an uppercase letter, wheras the local part of an email address (before the @) is case sensitive. We therefore encode the fact of lowercase by mapping the '@' symbol to a dash '-' surrogate, and of uppercase by mapping it to a space ' ' surrogate. We might have tried using $wgCapitalLinks in MediaWiki, but, despite that, calls to ucfirst() in includes/User.php methods isValidUserName() and getCanonicalName() (and maybe elsewhere) block the creation of any username having a lowercase first character.

This translation should work with all email addresses in common use today. Here are the strict requirements:

  a) No '/' in address
      - invalid in MediaWiki username
  b) No ' ' in address
      - MediaWiki cannot distinguish '_' and ' ' in page names
  c) Only ASCII characters in domain name
      - only ASCII domain names are considered case insensitive
        and we use lower-to-uppercase boundaries in place of '.'
        to separate the component labels of the name
  d) No '-' or digit (or anything else non-lowercase) at start of a domain label
      - we encode label with leading uppercase
  e) No '-' at end of a domain label
      - next label is encoded with leading uppercase, so we have internal
        sequence '-U', where U is an uppercase letter; but we use '-U'
        to encode '@' (though only for email addresses that begin with
        lowercase)
  f) No '_' in domain name
      - we use it (or equivalently ' ') in place of '@' (though only for email
        addresses that begin with uppercase)

References:
      - http://tools.ietf.org/html/rfc1035
      - http://tools.ietf.org/html/rfc2181#section-11
          - no chars *abolutely* restricted in components (labels) of a domain name
      - http://tools.ietf.org/html/rfc1035#section-2.3.1
          - but mail hosts *ought* to follow the preferred name syntax
      - http://tools.ietf.org/html/rfc4343#section-3.2
          - case-insensitivity applies only to ASCII labels

Parameters:

email - a canonical email address.

Returns:

the same string builder b.

See Also:

toUsername(String), InternetAddressX.canonicalAddress(String)

buildUserMnemonic

public static StringBuilder buildUserMnemonic(String username,
                              StringBuilder sB)

Appends a short abbreviation of the username to the string builder.

email

public final String email()

Identifies the user by canonical email address. This is the primary form of identifier for purposes of persistent back-end storage.

See Also:

InternetAddressX.canonicalAddress(String)

emailOrNobody

public static String emailOrNobody(String email,
                   ResourceBundle resA)

Returns the same email address; or, if it is null or NOBODY, the localized string for "nobody".

Parameters:

resA - a resource bundle of type application (A)

equalsEmail

public final boolean equalsEmail(Object o)

Returns true iff o is an ID pair with the same email address. This method is provided for backward compatibility and will soon be deprecated; use plain equals() instead.

See Also:

equals(Object)

isFromEmail

@Deprecated
public final boolean isFromEmail()

Deprecated. as an unecessary complexity and source of potential bugs.

Whether this ID pair was created from an email address as opposed to a username.

normalUsername

public static String normalUsername(String name)

Translates the mailish username to normal form by shifting the first letter to uppercase and substituting spaces for underscores. The normal name is globally unique and maps 1:1 with the canonical email address. Examples are "Smith-AcmeCom" for smith@acme.com, or "Smith AcmeCom" for Smith@acme.com.

Returns:

the translated name, which may be the same name; or null if the name is null.

See Also:

username(), MediaWiki.normalUsername(String)

toInternetAddress

public static InternetAddress toInternetAddress(String username)
                                         throws AddressException

Translates a username to a canonical email address.

Parameters:

username - the username encoded with either a space (or equivalently underscore) or dash at-surrogate.

Throws:

AddressException

See Also:

username(), InternetAddressX.canonicalAddress(String)

toUsername

public static String toUsername(String email)

Translates a canonical email address to a mailish username in normal form.

Parameters:

email - the canonical email address of the user.

See Also:

username(), appendUsername(String,StringBuilder), InternetAddressX.canonicalAddress(String)

username

public final String username()

Identifies the user by mailish username. This is a front-end identifier for use in the pollwiki and other UIs where it offers a degree of protection from the address harvesting practices of spammers. Another advantage is its lack of punctuation characters ('@' and '.') which makes the UI a little easier to read.

See Also:

normalUsername(String), toUsername(String), MailishUsername extension for MediaWiki

equals

public final boolean equals(Object o)

True iff o is an ID pair constructed from the same (equals) email address.

Overrides:

equals in class Object

toString

public final String toString()

Returns the same identifier from which the ID pair was constructed.

Overrides:

toString in class Object

See Also:

isFromEmail()