JCAT
v0.3.1

javax.jcat
Interface JcatAddress

All Superinterfaces:
JccAddress

public interface JcatAddress
extends JccAddress

Like a JccAddress, a JcatAddress represents a user's directory number. This directory number may be based on an E.164 addressing scheme or some other addressing scheme. For an IP-based network, the address might represent an IP address or a specific string (e.g., "758-1000@telcordia.com"), as indicated by JccAddress.getType(). At a minimum an address is unique within a Call Agent's local domain.

A JcatAddress object has a string name which corresponds to the directory number. This name is first assigned when the Address object is created and does not change throughout the lifetime of the object. The operation JccAddress.getName() returns the name of the JcatAddress object.

JcatAddress and JcatTerminal Objects

A JcatAddress is also associated with a JcatTerminal. JcatAddress and JcatTerminal objects exist in a many-to-many relationship. A JcatAddress object may have zero or more JcatTerminals associated with it. Each JcatTerminal associated with a JcatAddress must reflect its association with the JcatAddress. Since the implementation creates JcatAddress (and JcatTerminal) objects, it is responsible for ensuring the correctness of these relationships. The JcatTerminals associated with a JcatAddress are given by the getTerminals() operation.

An association between a JcatAddress and a JcatTerminal indicates that the JcatTerminal is addressable using that JcatAddress. In many instances, a telephone set (represented by a JcatTerminal object) has only one directory number (represented by a JcatAddress object) associated with it. In more complex configurations, telephone sets may have several directory numbers associated with them. Likewise, a directory number may appear on more than one telephone set.

JcatAddress and JcatCall Objects

JcatAddress objects represent the logical endpoints of a call. A logical view of a call views the call as originating from one JcatAddress endpoint and terminating at another JcatAddress endpoint.

JcatAddress objects are related to JcatCall objects via the JcatConnection object; this is the same as in case of the JccConnection objects. The JcatConnection object has a state which describes the current relationship between the JcatCall and the JcatAddress. Each JcatAddress object may be part of more than one call, and in each case, is represented by a separate JcatConnection object. The getConnections() operation returns all connection objects currently associated with the address.

A JcatAddress is associated with a JcatCall until the JcatConnection moves into the JccConnection.DISCONNECTED state. At that time, the JcatConnection is no longer reported via the getConnections() operation. This behavior is similar to that for JccConnection objects.

Address Listeners and Events

All changes in a JcatAddress object are reported via the JcatAddressListener interface. Applications instantiate an object which implements this interface and begins this delivery of events to this object using the addAddressListener(JcatAddressListener,EventFilter) operation. Applications receive events on a listener until the listener is removed via the removeAddressListener(JcatAddressListener) operation or until the JcatAddress is not longer observable. In these instances, each JcatAddressListener instance receives a JcatAddressEvent.ADDRESS_EVENT_TRANSMISSION_ENDED as its final event.

Since:
1.0
See Also:
JcatTerminal, JcatCall, JcatAddressListener

Field Summary
 
Fields inherited from interface javax.csapi.cc.jcc.JccAddress
AESA, E164, E164_MOBILE, GT, H323, IP, MULTICAST, NOT_PRESENT, NSAP, SIP, SMTP, SSN, UNDEFINED, UNICAST, URL, X400
 
Method Summary
 void addAddressListener(JcatAddressListener addrlistener, EventFilter eventFilter)
          Adds a listener to the address.
 void deregisterTerminal(JcatTerminal term)
          This method is used to deregister a JcatTerminal with a JcatAddress
 java.util.Set getConnections()
          Returns all the connection objects associated with this address.
 boolean getDisplayAllowed()
          Indication whether getDisplayText() is suppossed to be displayed.
 java.lang.String getDisplayText()
          Gets the text that can be displayed on the terminal.
 java.util.Set getTerminals()
          Returns a set of JcatTerminals associated with this JcatAddress object.
 void registerTerminal(JcatTerminal term)
          This method is used to register a JcatTerminal with a JcatAddress
 void removeAddressListener(JcatAddressListener addrlistener)
          Removes the given listener from the JcatAddress.
 void setDisplayText(java.lang.String text, boolean displayAllowed)
          Displays the specified string on the terminal.
 
Methods inherited from interface javax.csapi.cc.jcc.JccAddress
getName, getProvider, getType
 

Method Detail

addAddressListener

public void addAddressListener(JcatAddressListener addrlistener,
                               EventFilter eventFilter)
Adds a listener to the address. The address Listener can be used to listen to events such as registration of terminals associated with this JcatAddress. The address object will report events to this address listener object for the lifetime of the Address object, until the listener is removed with the removeAddressListener(JcatAddressListener) operation or until the address is no longer observable. In these instances, a JcatAddressEvent.ADDRESS_EVENT_TRANSMISSION_ENDED is delivered to the listener as its final event. The listener will receive no events after ADDRESS_EVENT_TRANSMISSION_ENDED unless the listener is explicitly re-added via this operation.

If an application attempts to add an instance of a listener already present on this address, this attempt will silently fail.

Parameters:
addrlistener - JcatAddressListener which will receive state changes in this JcatAddress.
eventFilter - EventFilter determines if the JcatAddressEvent.TERMINAL_REGISTERED is to be delivered to the specified listener.

registerTerminal

public void registerTerminal(JcatTerminal term)
                      throws InvalidPartyException,
                             MethodNotSupportedException,
                             PrivilegeViolationException
This method is used to register a JcatTerminal with a JcatAddress

Parameters:
term - This parameter contains the terminal which is to be registered with this address.
Throws:
InvalidPartyException - The specified terminal provided is not valid.
MethodNotSupportedException - This operation is not supported by the implementation.
PrivilegeViolationException - The application does not have the proper authority to invoke this operation.

deregisterTerminal

public void deregisterTerminal(JcatTerminal term)
                        throws InvalidPartyException,
                               MethodNotSupportedException,
                               PrivilegeViolationException
This method is used to deregister a JcatTerminal with a JcatAddress

Parameters:
term - This parameter contains the terminal which is to be deregistered with this address.
Throws:
InvalidPartyException - The specified terminal provided is not valid.
MethodNotSupportedException - This operation is not supported by the implementation.
PrivilegeViolationException - The application does not have the proper authority to invoke this operation.

getTerminals

public java.util.Set getTerminals()
Returns a set of JcatTerminals associated with this JcatAddress object.

Returns:
set of JcatTerminals associated with this JcatAddress object.

removeAddressListener

public void removeAddressListener(JcatAddressListener addrlistener)
Removes the given listener from the JcatAddress. If successful, the listener will no longer receive events generated by this Address object. As its final event, the Address Listener receives is an JcatAddressEvent.ADDRESS_EVENT_TRANSMISSION_ENDED event. If a listener is not part of the address, then this operation fails silently.

Parameters:
addrlistener - JcatAddressListener which was registered to receive state changes in this JcatAddress.

getConnections

public java.util.Set getConnections()
Returns all the connection objects associated with this address.

Returns:
a set of connections associated with this address.

setDisplayText

public void setDisplayText(java.lang.String text,
                           boolean displayAllowed)
                    throws InvalidArgumentException
Displays the specified string on the terminal.

Parameters:
text - the string to be displayed
displayAllowed - is displaying the text is allowed
Throws:
InvalidArgumentException - This exception is thrown if one of the parameter is invalid, e.g. typically if the text to be displayed cannot be displayed due to its length or because of invalid characters.

getDisplayText

public java.lang.String getDisplayText()
Gets the text that can be displayed on the terminal.

Returns:
the string to be displayed if getDisplayAllowed() returns true

getDisplayAllowed

public boolean getDisplayAllowed()
Indication whether getDisplayText() is suppossed to be displayed.

Returns:
indication whether getDisplayText() is suppossed to be displayed

JCAT
v0.3.1

August, 2003
If you have any comments or queries, please mail them to JSR-122-EG@JCP.ORG

Copyright - 2001, 2003 Sun Microsystems