The TelephoneNumber class was designed to use the java.text.MessageFormat class to format a US phone number with the proper characters and spacing. The class excepts numbers any many different ways and parses them into it's internal data so that it can display the phone number in the standard way, i.e. (800) 555-1212. It can even accept an alpha number like "877 HOLY-COW" and with the right options format it as alpha or numbers.
The TelephoneNumber class represents a US telephone number.
This class contains many constructors for various uses. It then stores the telephone number internally in seperate codes (area code, exchange, etc.). This encourages use of the format method to output the telephone number in any style the programmer wishes.
[needs i18n work]
Example usage:
long number = 8005551212L;
TelephoneNumber phone = new TelephoneNumber(number);
StringBuffer msg = new StringBuffer("Call me at ");
msg.append(phone.format());
// msg is now "Call me at (800) 555-1212"
US Format:
The general US format is a 3 digit area code, a 3 digit exchange, a 4 digit station. Typically written (800) 555-1212. Area codes are concidered optional unless you live in a '10 digit' calling area as many people now do. In which case you may want to set the isTenDigitArea flag which removes the parenthesis from the String output ie Denver area code requires 10 digit dailing 303 555-1212.
International Format:
International phone numbers are often written in this format:
+CC-(N)AAA-EEE-SSSS.
This expresses the numbers used for both international and national long-distance calls. In the example, +CC indicates the country code, while (N) indicates the NDD. When dialing from outside the country, the NDD would not be used after dialing the country code; when dialing from within that country, the NDD would be used, but the country code would not. Where AAA indicates the area code, EEE indicates the exchange, and SSSS indicates the station.
Country Code:
The country code is the national prefix to be used when dialing TO that particular country FROM another country.
NDD Prefix: (National Direct Dialing)
The NDD prefix is the access code used to make a call WITHIN that country from one city to another (when calling another city in the same vicinity, this may not be necessary). The NDD is followed by the city/area code for the place you are calling.
IDD Prefix: (International Direct Dialing)
The IDD prefix is the international prefix needed to dial a call FROM a country TO another country. This is followed by the country code for the country you are calling. The IDD is not part of the telephone number - but is a property of the locale, or the 'dailing device'.
Outside Line Prefix:
The Outside line prefix is use inside some private branch exchange (PBX) to connect with the outer exchange/trunk. It is typically 9 in the average US company. This is not part of the telephone number - but once again the property of the locale, or the 'dailing device'.
/*
* Copyright (c) 2003 David A. Koontz
* Licensed under the Open Software License version 2.0
*
* Grant of Copyright License. Licensor hereby grants You a world-wide,
* royalty-free, non-exclusive, perpetual, sublicenseable license to
* do the following:
* a) to reproduce the Original Work in copies;
* b) to prepare derivative works ("Derivative Works") based upon
* the Original Work;
* c) to distribute copies of the Original Work and Derivative Works
* to the public, with the proviso that copies of Original Work or
* Derivative Works that You distribute shall be licensed under the
* Open Software License;
* d) to perform the Original Work publicly; and
* e) to display the Original Work publicly.
*/
//package com..util;
import java.text.MessageFormat;
/**
* The
TelephoneNumber class represents a US telephone number.
*
* This class contains many constructors for various uses. It then stores the
* telephone number internally in seperate codes (area code, exchange, etc.).
* This encourages use of the
format method to output the
* telephone number in any style the programmer wishes.
*
* [needs i18n work]
*
* Example usage:
*
* long number = 8005551212L;
* TelephoneNumber phone = new TelephoneNumber(number);
* StringBuffer msg = new StringBuffer("Call me at ");
* msg.append(phone.format());
* // msg is now "Call me at (800) 555-1212"
*
*
* US Format:
* The general US format is a 3 digit area code, a 3 digit exchange, a 4 digit
* station. Typically written (800) 555-1212. Area codes are concidered
* optional unless you live in a '10 digit' calling area as many people now do.
* In which case you may want to set the
isTenDigitArea flag which
* removes the parenthesis from the String output ie Denver area code
* requires 10 digit dailing 303 555-1212.
*
* International Format:
* International phone numbers are often written in this format:
* +CC-(N)AAA-EEE-SSSS.
* This expresses the numbers used for both international and
* national long-distance calls. In the example, +CC indicates
* the country code, while (N) indicates the NDD. When dialing
* from outside the country, the NDD would not be used after dialing
* the country code; when dialing from within that country, the NDD
* would be used, but the country code would not. Where AAA indicates
* the area code, EEE indicates the exchange, and SSSS indicates the
* station.
*
*
*
* Country Code:
* The country code is the national prefix to be used when dialing TO
* that particular country FROM another country.
*
*
* NDD Prefix: (National Direct Dialing)
* The NDD prefix is the access code used to make a call WITHIN
* that country from one city to another (when calling another city in
* the same vicinity, this may not be necessary).
* The NDD is followed by the city/area code for the place you are
* calling.
*
*
* IDD Prefix: (International Direct Dialing)
* The IDD prefix is the international prefix needed to dial a call
* FROM a country TO another country. This is
* followed by the country code for the country you are calling.
* The IDD is not part of the telephone number - but is a property of
* the locale, or the 'dailing device'.
*
* Outside Line Prefix:
* The Outside line prefix is use inside some private branch exchange (PBX)
* to connect with the outer exchange/trunk. It is typically 9 in the
* average US company. This is not part of the telephone number - but
* once again the property of the locale, or the 'dailing device'.
*
*
*
* @author David A. Koontz mailto:dakoontz@yahoo.com">[dakoontz@yahoo.com]
* @version 1.0, 7/20/2003
* @see MessageFormat
* @see http://www.opensource.org/licenses/osl-2.0.php">Open Software License
version 2.0
*
*/
public class TelephoneNumber {
// International direct dial code is not part of a telephone
// number - it would be info in the locale that the dialer is in.
/** National direct dial code */
protected String ndd; // NDD of US is 1; UK is 0
/** Country code */
protected String countryCode; // Country code of US is 1; UK is 44
/** Area code */
protected String areaCode;
/** Exchange */
protected String exchange;
/** Station */
protected String station;
/** Extension */
protected String extension;
/** Is phone number part of a ten digit dialing area. */
protected boolean isTenDigitArea = false;
/** Alphanumeric phone number */
protected String alphaNumber; // used when we store "(800) GOT MILK"
/** Is phone number an alphanumberic */
protected boolean isAlphaNumber = false;
/** The default format pattern - US centric */
protected String defaultPatternUS = "({2}) {3}-{4}";
/** The default format pattern */
protected String defaultPattern = defaultPatternUS;
/**
* Basic constructor.
*/
public TelephoneNumber() {
this(null, null, null, "555", "1212", null);
}
/**
* General constructor.
* Create +1-(1)(800) 555-1212 ext: 34
*
* @param countryCode the country code (US is 1; UK is 44)
* @param ndd the national direct dial code (US is 1; UK is 0)
* @param areaCode the area code (or city code)
* @param exchange the exchange
* @param station the station
* @param extension the extension (inside the PBX)
*/
public TelephoneNumber(String countryCode, String ndd, String areaCode, String exchange, String station, String extension) {
if ( exchange == null )
throw new IllegalArgumentException("null arg forms not allowed for 'exchange'");
if ( station == null )
throw new IllegalArgumentException("null arg forms not allowed for 'station'");
this.countryCode = countryCode;
this.ndd = ndd;
this.areaCode = areaCode;
this.exchange = exchange;
this.station = station;
this.extension = extension;
}
/**
* Create (800) 555-1212 ext: 34
*/
public TelephoneNumber(String areaCode, String exchange, String station, String extension) {
this(null, null, areaCode, exchange, station, extension);
}
/**
* Create 555-1212 ext: 34
*/
public TelephoneNumber( String exchange, String station, String extension) {
this(null, null, null, exchange, station, extension);
}
/**
* Create 555-1212
*/
public TelephoneNumber( String exchange, String station) {
this(null, null, null, exchange, station, null);
}
/**
* Create 888 HOLY COW by using alphanumeric digits
*/
public TelephoneNumber( boolean isAlphaNumeric, String alphaNumber) {
this();
this.isAlphaNumber = isAlphaNumeric;
if ( isAlphaNumber == true ) {
this.alphaNumber = alphaNumber;
// parse it
String[] nums = parse(convertFromAlpha(alphaNumber));
// ignore country code & NDD
this.areaCode = nums[1];
this.exchange = nums[2];
this.station = nums[3];
this.extension= nums[4];
} else {
// parse this also - assuming no alpha char.
String[] nums = parse(alphaNumber);
// ignore country code & NDD
this.areaCode = nums[1];
this.exchange = nums[2];
this.station = nums[3];
this.extension= nums[4];
}
}
/**
* Create (888) 555-1212 by parsing string
*/
public TelephoneNumber( String str) {
this();
// parse the string into numbers array
String[] nums = parse(str);
// ignore country code & NDD
this.areaCode = nums[1];
this.exchange = nums[2];
this.station = nums[3];
this.extension= nums[4];
}
/**
* Create (479) 555-1212 by parsing a long integer
*/
public TelephoneNumber(long number) {
this();
String[] nums = parse(number);
// convert from longs to strings
this.areaCode = nums[1];
this.exchange = nums[2];
this.station = nums[3];
}
/** Create 555-1212 via long integers
*/
public TelephoneNumber( long exchange, long station) {
this();
// convert from longs to strings
if (exchange > 0) {
this.exchange = String.valueOf(exchange);
}
if (station > 0) {
this.station = String.valueOf(station);
}
}
/**
* Create (479) 555-1212 via long integers
*/
public TelephoneNumber(long areaCode, long exchange, long station) {
this();
// convert from longs to strings
if (areaCode > 0) {
this.areaCode = String.valueOf(areaCode);
}
if (exchange > 0) {
this.exchange = String.valueOf(exchange);
}
if (station > 0) {
this.station = String.valueOf(station);
}
}
/**
* Parse a string like "(888) 555-1212 x 68" into a phone number.
* Requires area code.
* Does not allow country codes etc.
* US centric.
*/
protected String[] parse( String str) {
String[] numbers = new String[5];
StringBuffer ndd = new StringBuffer();
StringBuffer area = new StringBuffer();
StringBuffer exch = new StringBuffer();
StringBuffer stat = new StringBuffer();
StringBuffer ext = new StringBuffer();
char ch = ' ';
int areaCount = 0;
int exchCount = 0;
int statCount = 0;
if ( str != null && str.length()>0 ) {
// for each char in string
for (int i = 0; i < str.length(); i++) {
ch = str.charAt(i);
// only look at digits
if ( Character.isDigit(ch) ) {
// this is only finding this pattern 123 123 1234 99...
if ( areaCount < 3 ) {
area.append(ch);
areaCount++;
} else if ( exchCount < 3 ) {
exch.append(ch);
exchCount++;
} else if ( statCount < 4 ) {
stat.append(ch);
statCount++;
} else {
ext.append(ch);
}
// doesnot work for "571 3345 ext 897"
//@todo - get better parser
}
}
}
numbers[0] = ndd.toString();
numbers[1] = area.toString();
numbers[2] = exch.toString();
numbers[3] = stat.toString();
numbers[4] = ext.toString();
return numbers;
}
/**
* Parse a long integer like 4795718080 into phone number.
* Does not allow country codes or extensions.
* US centric.
*/
protected String[] parse(long number) {
String[] nums = new String[5];
long area = 0;
long exch = 0;
long stat = 0;
// parse the long from right to left
// assume US style phone number without extension
// example: 8005551212 or 2368000
if (number > 0) {
if (number > 9999) {
exch = number / 10000;
stat = number - (exch * 10000);
if ( exch > 999 ) {
area = exch / 1000;
exch = exch - (area * 1000);
}
}
}
// convert from longs to strings
if (area > 0) {
nums[1] = String.valueOf(area);
}
if (exch > 0) {
nums[2] = String.valueOf(exch);
}
if (stat > 0) {
nums[3] = String.valueOf(stat);
}
return nums;
}
/** Convert alphanumeric phone number to numeric. */
protected static String convertFromAlpha(String alpha) {
// If you don't want US style key pad - change it.
return convertFromAlphaUS(alpha);
}
/** Convert alphanumeric phone number to numeric - US centric */
protected static String convertFromAlphaUS(String alpha) {
// convert a US alphanumeric number into numberic
// example: 800 GOT MILK -> 800 468-6455
// where the Alpha to Numberic Key Pad
//
// 1 2 3
// ABC DEF
//
// 4 5 6
// GHI JKL MNO
//
// 7 8 9
// PQRS TUV WXYZ
//
// * 0 #
//
// prep the alpha string
StringBuffer sb = new StringBuffer(alpha.toUpperCase().trim());
// for each char in the string
for (int i = 0; i < sb.length(); i++) {
char ch = sb.charAt(i);
if ( Character.isDigit(ch) ) {
; // ignore it
} else if ( ch == '(' || ch == ')' ) {
; // ignore them
} else if ( ch == 'A' || ch == 'B' || ch == 'C' ) {
sb.deleteCharAt(i);
sb.insert(i, '2');
} else if ( ch == 'D' || ch == 'E' || ch == 'F' ) {
sb.deleteCharAt(i);
sb.insert(i, '3');
} else if ( ch == 'G' || ch == 'H' || ch == 'I' ) {
sb.deleteCharAt(i);
sb.insert(i, '4');
} else if ( ch == 'J' || ch == 'K' || ch == 'L' ) {
sb.deleteCharAt(i);
sb.insert(i, '5');
} else if ( ch == 'M' || ch == 'N' || ch == 'O' ) {
sb.deleteCharAt(i);
sb.insert(i, '6');
} else if ( ch == 'P' || ch == 'Q' || ch == 'R' || ch == 'S') {
sb.deleteCharAt(i);
sb.insert(i, '7');
} else if ( ch == 'T' || ch == 'U' || ch == 'V' ) {
sb.deleteCharAt(i);
sb.insert(i, '8');
} else if ( ch == 'W' || ch == 'X' || ch == 'Y' || ch == 'Z' ) {
sb.deleteCharAt(i);
sb.insert(i, '9');
} else {
; // ignore
}
}
return sb.toString();
}
/**
* Format the telephone number with the supplied
MessageFormat pattern.
* The pattern has 7
messageFormatElement arguments (0 - 6).
*
* argument 0 - ndd
* argument 1 - countryCode
* argument 2 - areaCode
* argument 3 - exchange
* argument 4 - station
* argument 5 - extension
* argument 6 - alphanumeric
*
* Examples:
* "({2}) {3}-{4} ext {5}" gives "(800) 555-1212 ext 99"
* "{2}.{3}.{4}" gives "800.555.1212"
* "{6} [{2} {3}-{4}]" gives "888 HOLY COW [888 465-9269]"
*
* @param pattern the format pattern to be used
* @see MessageFormat
*
*/
public String format(String pattern) {
// create objects array from telephone codes
Object[] objects = {ndd, countryCode, areaCode, exchange, station, extension, alphaNumber};
// create a MessageFormat with pattern
MessageFormat mf = new MessageFormat(pattern);
return mf.format(objects);
}
/**
* Format the telephone number with the
defaultPattern MessageFormat.
* US centric.
*/
public String format() {
// create objects array from telephone codes
Object[] objects = {ndd, countryCode, areaCode, exchange, station, extension, alphaNumber};
// create a MessageFormat with default pattern
MessageFormat mf = new MessageFormat(defaultPattern);
return mf.format(objects);
}
/** Human readable output
*/
public String toString() {
return toStringUS();
}
/** US centric human readable output
*/
public String toStringUS() {
// use US convention: "(800) 555-1212 ext: 20"
StringBuffer sb = new StringBuffer(20);
if ( this.isAlphaNumber ) {
// just spit back the string
sb.append(this.alphaNumber);
sb.append(" [").append(areaCode).append(" ").append(exchange).append(" ").append(station).append("]");
} else {
if (countryCode != null && countryCode.length() > 0) {
// format country code as '+CC-'
sb.append("+").append(countryCode).append("-");
}
if (ndd != null && ndd.length() > 0) {
if (countryCode != null && countryCode.equals("1") ) {
// in the US we don't write both the country code & the NDD
; // igonre the NDD
} else {
// format NDD as '(N) '
sb.append("(").append(ndd).append(") ");
}
}
if (areaCode != null && areaCode.length() > 0) {
// we could use a java.text.Format - but noooooo
// assume US style (000)
if ( areaCode.length() == 1 ) {
if (isTenDigitArea == true) {
sb.append("00").append(areaCode).append(" ");
} else {
sb.append("(").append("00").append(areaCode).append(") ");
}
} else if (areaCode.length() == 2 ) {
if (isTenDigitArea == true) {
sb.append("0").append(areaCode).append(" ");
} else {
sb.append("(").append("0").append(areaCode).append(") ");
}
} else if (areaCode.length() == 3 ) {
if (isTenDigitArea == true) {
sb.append(areaCode).append(" ");
} else {
sb.append("(").append(areaCode).append(") ");
}
} else {
// more than 3 digits? - OK whatever
if (isTenDigitArea == true) {
sb.append(areaCode).append(" ");
} else {
sb.append("(").append(areaCode).append(") ");
}
}
}
// exchange - assume US style 000
if ( exchange.length() == 1 ) {
sb.append("00").append(exchange).append("-");
} else if (exchange.length() == 2 ) {
sb.append("0").append(exchange).append("-");
} else if (exchange.length() == 3 ) {
sb.append(exchange).append("-");
} else {
// more than 3 digits? - OK whatever
sb.append(exchange).append("-");
}
// station - assume US style 0000
if ( station.length() == 1 ) {
sb.append("000").append(station);
} else if (station.length() == 2 ) {
sb.append("00").append(station);
} else if (station.length() == 3 ) {
sb.append("0").append(station);
} else {
sb.append(station);
}
if (extension != null && extension.length() > 0) {
sb.append(" ext: ").append(extension);
}
}
return sb.toString();
}
/** MAIN - a test stub */
public static void main(String[] args) {
// test it out
TelephoneNumber n1 = new TelephoneNumber(); // test null params
TelephoneNumber n2 = new TelephoneNumber(571L, 9999L); // test 2 longs
TelephoneNumber n3 = new TelephoneNumber(479L, 571L, 1003L); // test 3 longs
TelephoneNumber n4 = new TelephoneNumber(303L, 222L, 7800L); // test ten digit dialing
n4.isTenDigitArea = true;
TelephoneNumber n5 = new TelephoneNumber("(888) 341-8876"); // test formated string
TelephoneNumber n6 = new TelephoneNumber(127, 345, 8765); // test 3 integers
TelephoneNumber n7 = new TelephoneNumber(true, "800 GOT MILK"); // test parsing Alpha
TelephoneNumber n8 = new TelephoneNumber(3L, 4L, 5L); // test zero padding
TelephoneNumber n9 = new TelephoneNumber("1", "1", "479", "571", "8509", "40"); // test 6 strings
TelephoneNumber n10 = new TelephoneNumber(9876543210L); // test 1 long
TelephoneNumber n11 = new TelephoneNumber(false, "/800/ 555-1212 x 0"); // test parsing Non-Alpha
System.out.println("TelephoneNumber(): " + n1);
System.out.println("TelephoneNumber(571L, 9999L): " + n2);
System.out.println("TelephoneNumber(479L, 571L, 1003L): " + n3);
System.out.println("TelephoneNumber(303L, 222L, 7800L): " + n4);
System.out.println("TelephoneNumber(\"(888) 341-8876\"): " + n5);
System.out.println("TelephoneNumber(127, 345, 8765): " + n6);
System.out.println("TelephoneNumber(true, \"800 GOT MILK\"): " + n7);
System.out.println("TelephoneNumber(3L, 4L, 5L): " + n8);
System.out.println("TelephoneNumber(\"1\", \"1\", \"479\", \"571\", \"8509\", \"40\"): " + n9);
System.out.println("TelephoneNumber(9876543210L): " + n10);
System.out.println("TelephoneNumber(false, \"/800/ 555-1212 x 0\"): " + n11);
System.out.println("TelephoneNumber.format(\"{6} [{2} {3}-{4}]\"): " + n7.format("{6} [{2} {3}-{4}]"));
System.out.println("TelephoneNumber.format(): " + n9.format());
}
/******************************************************************/
/*** Getter/Setter ***/
/******************************************************************/
public String getNdd() {
return ndd;
}
public void setNdd(String value) {
ndd = value;
}
public String getCountryCode() {
return countryCode;
}
public void setCountryCode(String value) {
countryCode = value;
}
public String getAreaCode() {
return areaCode;
}
public void setAreaCode(String value) {
areaCode = value;
}
public String getExchange() {
return exchange;
}
public void setExchange(String value) {
exchange = value;
}
public String getStation() {
return station;
}
public void setStation(String value) {
station = value;
}
public String getExtension() {
return extension;
}
public void setExtension(String value) {
extension = value;
}
public boolean isTenDigitArea() {
return isTenDigitArea;
}
public void setTenDigitArea(boolean value) {
isTenDigitArea = value;
}
public String getAlphaNumber() {
return alphaNumber;
}
public void setAlphaNumber(String value) {
alphaNumber = value;
}
public boolean isAlphaNumber() {
return isAlphaNumber;
}
public void setAlphaNumber(boolean value) {
isAlphaNumber = value;
}
}
Comments