JSR-043: JTAPI-1.4

javax.telephony.media
Class Symbol

java.lang.Object
  |
  +--javax.telephony.media.symbols.BaseSymbol
        |
        +--javax.telephony.media.Symbol
All Implemented Interfaces:
java.io.Serializable

public final class Symbol
extends javax.telephony.media.symbols.BaseSymbol
implements java.io.Serializable

Symbols are opaque, immutable, nominal tokens. They are used in applications only for assignment and equality/identity testing.

Symbol is a Java class to encapsulate/implement the ECTF defined Symbols. Symbols are namespace and value space controlled ints that allow extensibilty by vendors, interoperability across languages, and other benefits.

Symbols are defined as "public final static" members of various JTAPI Media interfaces. Symbol constants are used to identify Events, Event Qualifiers, MediaService and Resource Parameters, RTC triggers Conditions, RTC Actions, and Keys or Values in Dictionaries (or Maps).

Symbol name convention:

A particular Symbol (and its associated value) may be used in multiple contexts. Each expected usage of the Symbol is given a distinct name, composed by a diffentiating prefix that indicates the usage, and an item name that identifies the actual value.

The convention for Symbol name prefixes is as follows:
With prefix:the Symbol is used as: for example:
a_Attribute    a_LocalState
e_Error    e_Disconnected
ev_Event   ev_SignalDetected
p_Parameter    p_EnabledEvents
q_Qualifier    q_Disconnected
rtca_RTC Action rtca_Stop
rtcc_RTC Condition rtcc_SignalDetected
v_Dictionary value    v_Stop

Each (non-error) Symbol typically appears as a final static field in each interface or class to which it is relevant. This is often accomplished by defining the Symbol in a "Constants" interface that is inherited by the classes or interfaces in which the Symbol is relevant. For example, each Resource class has a ResourceConstants interface that is inherited by the Resource interface and the associated ResourceEvent interface.

Note: Symbols used to identify errors, (that is, the return values from getError() are used solely for errors and do not appear in other contexts. Because error Symbols are numerous and may appear in many contexts, the error Symbols are defined in interface ErrSym and are not always renamed or inherited in other interfaces. Therefore, error Symbols are generally accessed as ErrSym.e_ItemName.

Note: Pre-defined Symbol constants with the same internal value generally refer to the same Object, but this cannot be relied upon. As with Integer, to compare two Symbols for numerical/logical equivalence, the equals method must be used.

Note: The other methods on Symbol are useful when debugging, and may be used by JTAPI Media implementors, but are not usually needed (or useful) during production. Symbols are defined by name in final static fields, by the classes that assign some meaning to a Symbol. Applications do not need to create Symbols at runtime.

Why no intValue()?

Symbol is like an Integer but is restricted to nominal not scalar operations: it is ligitimate to use equals and hashCode, but one should not do arithmetic operations on a Symbol.

Note: intValue() may be of use to compare against int suberror values; but such usage is so rare we don't mind telling the motivated developer to use hashCode() instead of intValue().

Since:
JTAPI-1.3
See Also:
Serialized Form

Method Summary
 boolean equals(java.lang.Object other)
          Compares the internal value of two Symbols.
static Symbol getSymbol(int value)
          Returns a Symbol object with the given int value.
static Symbol getSymbol(java.lang.String stringName)
          Returns a Symbol with the given name.
 int hashCode()
          Returns a hashcode for this Symbol.
static void loadSymbolNames(java.lang.String pathName)
          Load Symbol name information from somewhere.
static void saveSymbolNames(java.lang.String pathName)
          Store Symbol name information to someplace.
 void setName(java.lang.String stringName)
          Assign a name to a Symbol.
 java.lang.String toString()
          Return a String representation of this Symbol.
 
Methods inherited from class javax.telephony.media.symbols.BaseSymbol
intValue
 
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait
 

Method Detail

getSymbol

public static Symbol getSymbol(int value)
Returns a Symbol object with the given int value.
Parameters:
value - the int value represented by the Symbol.
Returns:
a Symbol object with the given value.

equals

public boolean equals(java.lang.Object other)
Compares the internal value of two Symbols.

The result is true if and only if the argument is an instance of Symbol and contains the same internal value as this Symbol.

Note: The "==" operator just compares the identity (object handle) of two Symbols.

Overrides:
equals in class javax.telephony.media.symbols.BaseSymbol
Parameters:
other - a Symbol to compare to this Symbol.
Returns:
TRUE iff the Symbols have the same value.

hashCode

public int hashCode()
Returns a hashcode for this Symbol.

Overrides:
hashCode in class javax.telephony.media.symbols.BaseSymbol
Returns:
a hashcode value for this Symbol.

toString

public java.lang.String toString()
Return a String representation of this Symbol.

Attempt to parse the symbol value to identify the Vendor, Object and ItemName.

Overrides:
toString in class javax.telephony.media.symbols.BaseSymbol
Returns:
a String representing this Symbol.

getSymbol

public static Symbol getSymbol(java.lang.String stringName)
Returns a Symbol with the given name.

Returns a Symbol with the given name, if the name is recognized.

The default implementation works for Symbols that are public static Symbol fields of public classes. The name should be formatted as: (class.FieldName) The package name "javax.telephony.media" is prepended if necessary.

For example:
getSymbol("ESymbol.Any_NULL");
getSymbol("PlayerEvent.q_RTC");
getSymbol("ErrSym.e_OK");
getSymbol("com.vendor.package.VendorSyms.Item_Name");

A JTAPI Media vendor may alter this implementation; for example, to prepend other package names, or use other techniques to map from name to Symbol.

Parameters:
stringName - a String that names a Symbol
Returns:
the named Symbol, or null if stringName is not registered.

setName

public void setName(java.lang.String stringName)
Assign a name to a Symbol. A Symbol may be given multiple names. Symbol.toString() uses the last assigned name.

The name applies to all Symbol object that are equal() to this.

Overrides:
setName in class javax.telephony.media.symbols.BaseSymbol
Parameters:
stringName - the name to be given to that Symbol

saveSymbolNames

public static void saveSymbolNames(java.lang.String pathName)
Store Symbol name information to someplace.
Parameters:
pathName - a String that indicates where to store the symbol table.

loadSymbolNames

public static void loadSymbolNames(java.lang.String pathName)
Load Symbol name information from somewhere.
Parameters:
pathName - a String that indicates which symbol table to load. if pathName is null, load standard/default symbol table.

Note: The format of the pathName String is not yet standardized.
The implementation supplied in the reference code accepts strings like: "class:javax.telephony.media.symbols.R2SymbolNames". The indicated class file is loaded, which runs its static block and invokes Symbol.setName(String) for each Symbol.


JSR-043: JTAPI-1.4

Send comments to: JSR-43@ectf.org