|
JSR-043: JTAPI-1.4 | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--javax.telephony.media.symbols.BaseSymbol | +--javax.telephony.media.Symbol
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).
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.
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().
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 |
public static Symbol getSymbol(int value)
Symbol
object
with the given int
value.value
- the int value represented by the Symbol
.public boolean equals(java.lang.Object other)
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.
equals
in class javax.telephony.media.symbols.BaseSymbol
other
- a Symbol to compare to this Symbol.public int hashCode()
hashCode
in class javax.telephony.media.symbols.BaseSymbol
public java.lang.String toString()
Attempt to parse the symbol value to identify the Vendor, Object and ItemName.
toString
in class javax.telephony.media.symbols.BaseSymbol
public static Symbol getSymbol(java.lang.String stringName)
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.
stringName
- a String that names a Symbolpublic void setName(java.lang.String stringName)
Symbol.toString()
uses the last assigned name.
The name applies to all Symbol object that are equal() to this.
setName
in class javax.telephony.media.symbols.BaseSymbol
stringName
- the name to be given to that Symbolpublic static void saveSymbolNames(java.lang.String pathName)
pathName
- a String that indicates where to store the symbol table.public static void loadSymbolNames(java.lang.String pathName)
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 | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |