TelURL Interface

The TelURL interface represents tel URLs as defined in RFC 3966, which are used to specify telephone numbers in a standardized format. These URLs are particularly useful for addressing telephone numbers within SIP communication contexts. While SIP servlet containers may have the capability to route requests based on TelURL objects, such support is not mandatory. The TelURL interface extends the base URI interface, inheriting its capabilities while focusing specifically on the representation and manipulation of telephone numbers. By encapsulating telephone numbers as tel URLs, the interface provides a consistent and structured approach to handling telephony addressing within SIP applications.

Methods:

getPhoneNumber

java.lang.String getPhoneNumber()

The getPhoneNumber method retrieves the phone number contained within this TelURL.
Returns:
java.lang.String: The phone number as a string, including any visual separators (e.g., dashes or spaces) but excluding a leading + for global telephone URLs.

getPhoneContext

java.lang.String getPhoneContext()

The getPhoneContext method retrieves the phone context of this TelURL. It is useful for distinguishing between global and local telephone numbers and retrieving the context information necessary for interpreting local numbers.
Returns:
java.lang.String: The phone context for local numbers, which provides additional information to interpret the number, or null if the phone number is global.

setPhoneNumber

void setPhoneNumber(java.lang.String number)

The setPhoneNumber method sets a new global phone number for this TelURL. The specified number must comply with the global number format as defined in RFC3966.
Parameters:
number: A String representing the new global phone number. For example, "+1-201-555-0123".
Throws:
IllegalArgumentException: If the provided phone number is invalid according to the validation rules outlined in RFC3966.

setPhoneNumber

void setPhoneNumber(java.lang.String number,
                    java.lang.String phoneContext)

The setPhoneNumber method assigns a new local phone number to this TelURL, along with its corresponding phoneContext. The local number must conform to the "tel" scheme as defined in RFC3966.
Parameters:
number: A String representing the new local phone number. For example, "7042".
phoneContext: A String representing the phone-context parameter of this TelURL.
Throws:
IllegalArgumentException: If the provided phone number is invalid according to RFC3966 validation rules.

isGlobal

boolean isGlobal()

The isGlobal method checks whether this TelURL is in a global format. It helps determine if the TelURL represents a globally unique phone number (e.g., includes a leading "+" as per RFC3966) or a local number with a phone-context.
Returns: true if the TelURL is in a global form, false otherwise.

toString

java.lang.String toString()

The toString method provides the TelURL as a String in its full representation, with any reserved characters properly escaped in accordance with RFC2396. This ensures the TelURL is returned in a format suitable for use in SIP messages or other network-related operations.
Returns:
A String representation of this TelURL.

equals

boolean equals(java.lang.Object o)

The equals method compares the current TelURL instance with another TelURL based on the comparison rules specified in RFC 3966, section 5. It ensures that equality is determined according to the standardized guidelines for tel URLs, ensuring consistency and compliance in comparisons.
Parameters:
o - The TelURL object to be compared with this instance.
Returns: true if the two TelURL objects are considered equal as per the RFC 3966 rules, false otherwise.