001/*
002 *  Copyright 2010, 2011, 2012 Christopher Pheby
003 *
004 *  Licensed under the Apache License, Version 2.0 (the "License");
005 *  you may not use this file except in compliance with the License.
006 *  You may obtain a copy of the License at
007 *
008 *      http://www.apache.org/licenses/LICENSE-2.0
009 *
010 *  Unless required by applicable law or agreed to in writing, software
011 *  distributed under the License is distributed on an "AS IS" BASIS,
012 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 *  See the License for the specific language governing permissions and
014 *  limitations under the License.
015 */
016package org.jadira.cdt.phonenumber.api;
017
018import org.jadira.cdt.country.CountryCode;
019
020/**
021 * Applies to representations of phone numbers.
022 */
023public interface PhoneNumber {
024
025        /**
026         * Returns the dialling code for the country that this phone number belongs to.
027         * @return The country dialling code e.g. '+44'
028         */
029    String getCountryDiallingCode();
030    
031        /**
032         * Returns the national number part for the phone number.
033         * @return The country dialling code e.g. '1963350474'
034         */    
035    String getNationalNumber();
036
037        /**
038         * Returns the extension for the phone number or null.
039         * @return The extension
040         */
041    String getExtension();
042
043        /**
044         * Returns the E164 formatted telephone number. Any extension is ommitted.
045         * @return The telephone number formatted as E164.
046         */
047    String toE164NumberString();
048
049        /**
050         * Returns the E164 formatted telephone number. Any extension is appended to the number
051         * with the extension prefix given as ';ext='
052         * @return The telephone number formatted as E164 together with the extension, if any.
053         */
054    String toE164NumberWithExtensionString();
055
056    /**
057     * Returns the CountryCode this number belongs to
058     * @return The CountryCode
059     */
060    CountryCode extractCountryCode();
061    
062    /**
063     * Splits the national number into its constituent parts, returning that part of the number that
064     * represents the area code.
065     * @return The area code
066     */
067    String extractAreaCode();
068
069    /**
070     * Splits the national number into its constituent parts, returning that part of the number that
071     * represents the subscriber number.
072     * @return The subscriber number
073     */
074    String extractSubscriberNumber();
075}