JCAT
v0.3.1

javax.jcat
Interface JcatTerminal


public interface JcatTerminal

A JcatTerminal represents a physical endpoint connected to the softswitch domain. For example, telephone set, computer workstations and hand-held devices are modeled as JcatTerminal objects if they act as physical endpoints in a communications network. A JcatTerminal object has a string name that is unique for all JcatTerminal objects. The JcatTerminal does not attempt to interpret this string in any way. This name is first assigned when the JcatTerminal is created and does not change throughout the lifetime of the object. The method getName() returns the name of the JcatTerminal object. The name of the JcatTerminal may not have any real-world interpretation. Typically, JcatTerminals are chosen from a list of JcatTerminal objects obtained from an JcatAddress object.

JcatTerminal objects may be classified into two categories: local and remote. Local JcatTerminal objects are those terminals which are part of the JcatProvider's local domain. These JcatTerminal objects are created by the implementation of the JcatProvider object when it is first instantiated. Remote JcatTerminal objects are those outside of the JcatProvider's domain which the JcatProvider learns about during its lifetime through various happenings (e.g., an incoming call from a currently unknown address). Note that applications never explicitly create new JcatTerminal objects through the JCAT API.

Address and Terminal Objects

JcatAddress and JcatTerminal objects exist in a many-to-many relationship. A JcatAddress object may have zero or more JcatTerminal objects associated with it. For each JcatTerminal associated with a JcatAddress, that JcatTerminal must also reflect its association with the JcatAddress. Since the implementation creates JcatAddress (and JcatTerminal) objects, it is responsible for insuring the correctness of these relationships. The JcatTerminal objects associated with a JcatAddress is given by the JcatAddress.getTerminals() method. An association between a JcatAddress and a JcatTerminal object indicates that the JcatTerminal contains the JcatAddress object as one of its telephone number addresses. 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. For example, some of the current PDAs may exhibit this configuration.

Terminals and Call Objects

JcatTerminal objects represent the physical endpoints of a call. With respect to a single JcatAddress endpoint on a JcatCall, multiple physical JcatTerminal endpoints may exist. JcatTerminal objects are related to JcatCall objects via the JcatTerminalConnection object. JcatTerminalConnection objects are associated with JcatCall indirectly via JcatConnection objects.

A JcatTerminal may be associated with a JcatCall only if one of its JcatAddress objects is associated with the JcatCall. The JcatTerminalConnection object has a state which describes the current relationship between the JcatConnection and the JcatTerminal. Each JcatTerminal object may be part of more than one call, and in each case, is represented by a separate JcatTerminalConnection object. The getTerminalConnections() method returns all JcatTerminalConnection objects currently associated with the Terminal.

A JcatTerminal object is associated with a JcatConnection until the JcatTerminalConnection moves into the JcatTerminalConnection.DROPPED state. At that time, the JcatTerminalConnection is no longer reported via the JcatTerminal.getTerminalConnections() method. Therefore, the JcatTerminal.getTerminalConnections() method never reports a JcatTerminalConnection in the JcatTerminalConnection.DROPPED state.

Terminal Listeners and Events

All changes in a JcatTerminal object are reported via the JcatTerminalListener interface. Applications instantiate an object which implements this interface and begins this delivery of events to this object using the addTerminalListener(JcatTerminalListener) method. Applications receive events on a listener until the listener is removed via the removeTerminalListener(JcatTerminalListener) method or until the JcatTerminal is no longer observable. In these instances, each JcatTerminalListener instance receives a JcatTerminalEvent.TERMINAL_EVENT_TRANSMISSION_ENDED as its final event. At this point, we envisage use of this feature to be used to report association and disassociation of JcatAddresses with a JcatTerminal.

Call Listeners

At times, applications may want to monitor a particular JcatTerminal for all JcatCalls which come to that JcatTerminal. For example, a desktop telephone application is only interested in calls associated with a particular agent terminal. To achieve this sort of JcatTerminal-based JcatCall monitoring applications may add JcatCallListeners to a JcatTerminal via the addCallListener(JccCallListener) method. When a JcatCallListener is added to a JcatTerminal, this listener instance is immediately added to all JcatCall objects at this JcatTerminal and is added to all calls which come to this JcatTerminal in the future. These listeners remain on the call as long as the JcatTerminal is associated with the call.

Since:
1.0

Method Summary
 void addCallListener(JccCallListener listener)
          Adds a listener to a JcatCall when this JcatTerminal first becomes part of that JcatCall.
 void addTerminalListener(JcatTerminalListener listener)
          Adds a listener to the Terminal.
 void deregisterAddress(JcatAddress addr)
          This method is used to deregister a JcatAddress with the JcatTerminal
 java.util.Set getAddresses()
          Returns an array of JcatAddress objects associated with this JcatTerminal object.
 java.lang.String getName()
          Returns the name of the JcatTerminal.
 JcatProvider getProvider()
          Returns the JcatProvider associated with this JcatTerminal.
 JcatTerminalCapabilities getTerminalCapabilities()
          Returns the dynamic capabilities for the instance of the JcatTerminal object.
 java.util.Set getTerminalConnections()
          Returns a set of JcatTerminalConnection objects associated with this JcatTerminal.
 void registerAddress(JcatAddress addr)
          This method is used to register a JcatAddress with the JcatTerminal
 void removeCallListener(JccCallListener calllistener)
           
 void removeTerminalListener(JcatTerminalListener termlistener)
          Removes the given listener from the Terminal.
 

Method Detail

addCallListener

public void addCallListener(JccCallListener listener)
                     throws MethodNotSupportedException,
                            ResourceUnavailableException
Adds a listener to a JcatCall when this JcatTerminal first becomes part of that JcatCall. This method permits applications to select a JcatTerminal object in which they are interested and automatically have the implementation attach this listener to all present and future calls which come to this JcatTerminal. If an application attempts to add an instance of a call listener already present on this JcatTerminal, it will silently fail. When a call listener is added to a JcatTerminal with this method, the following behavior is exhibited by the implementation.
  1. It is immediately associated with any existing calls at the JcatTerminal and a snapshot of those calls are reported to the call listener.
  2. It is associated with all future calls which come to this JcatTerminal.
Note that the definition of the term "... JcatTerminal first becomes part of that JcatCall ..." means that the JcatCall contains a JcatConnection which contains a terminal connection with this JcatTerminal as its JcatTerminal.

Call Listener on Multiple Terminals

It is possible for an application to add call listeners to more than one JcatTerminal (using addCallListener(JccCallListener)). The rules outlined above still apply, with the following additions:
  1. A call listener is not added to a JcatCall more than once, even if it has been added to more than one JcatTerminal which are present on the JcatCall.
  2. The call listener leaves the call only if ALL of the objects through which the call listener was added leave the call. If one of those objects becomes part of the JcatCall again, the call listener is re-applied to the JcatCall.

Call Listener Event level of Granularity

The application shall receive the event reports associated with the methods which are defined in the Call Listener interface that the application implements - either the JccCallListener, JccConnectionListener or JcatConnectionListener interface. Note that the JccCallListener, JccConnectionListener and JcatConnectionListener form a hierarchy of interfaces, and so provide successively increasing amounts of call information and successively finer-grained event granularity.

Call Listener Lifetime

For all call listeners which are present on calls because of this method, the following behavior is exhibited with respect to the lifetime of the call.
  1. The call listener receives events until the call is no longer at this JcatTerminal.
  2. All object that have added the call listener have also (subsequently) removed the call listener.
  3. The JcatCall can no longer be monitored by the implementation.
  4. The JcatCall moves into the JccCall.INVALID state.
When the Call Listener leaves the JcatCall because of one of the reasons above, it receives a JccCallEvent.CALL_EVENT_TRANSMISSION_ENDED as its final event.

Parameters:
listener - to be added to any JcatCalls on this JcatTerminal.
Throws:
MethodNotSupportedException
ResourceUnavailableException

addTerminalListener

public void addTerminalListener(JcatTerminalListener listener)
Adds a listener to the Terminal. The Terminal Listener reports all JcatTerminal-related state changes as JcatTerminalEvents. The terminal object will report events to this terminal listener object for the lifetime of the terminal object, until the listener is removed with the removeTerminalListener(JcatTerminalListener) or until the terminal is no longer observable. In these instances, a JcatTerminalEvent.TERMINAL_EVENT_TRANSMISSION_ENDED is delivered to the listener as its final event. The listener will receive no events after TERMINAL_EVENT_TRANSMISSION_ENDED unless the listener is explicitly re-added via the this method. If an application attempts to add an instance of a listener already present on this terminal, this attempt will silently fail.


getAddresses

public java.util.Set getAddresses()
Returns an array of JcatAddress objects associated with this JcatTerminal object.

Returns:
a set of JcatAddresses associated with this JcatTerminal.

getName

public java.lang.String getName()
Returns the name of the JcatTerminal. Each JcatTerminal possesses a unique name. This name is assigned by the implementation and may or may not carry a real-world interpretation.

Returns:
the name of the JcatTerminal.

getProvider

public JcatProvider getProvider()
Returns the JcatProvider associated with this JcatTerminal. This JcatProvider object is valid throughout the lifetime of the JcatTerminal and does not change once the JcatTerminal is created.

Returns:
JcatProvider associated with this JcatTerminal.

getTerminalConnections

public java.util.Set getTerminalConnections()
Returns a set of JcatTerminalConnection objects associated with this JcatTerminal. Once a JcatTerminalConnection is added to a JcatTerminal, the JcatTerminal maintains a reference until the JcatTerminalConnection moves into the JcatTerminalConnection.DROPPED state.

Returns:
a set of JcatTerminalConnection objects associated with this JcatTerminal.

removeCallListener

public void removeCallListener(JccCallListener calllistener)

removeTerminalListener

public void removeTerminalListener(JcatTerminalListener termlistener)
Removes the given listener from the Terminal. If successful, the listener will no longer receive events generated by this Terminal object. As its final event, the Terminal Listener receives a JcatTerminalEvent.TERMINAL_EVENT_TRANSMISSION_ENDED. If a listener is not part of the Terminal, then this method fails silently.

Parameters:
termlistener - listener to be removed from the JcatTerminal.

getTerminalCapabilities

public JcatTerminalCapabilities getTerminalCapabilities()
Returns the dynamic capabilities for the instance of the JcatTerminal object. Dynamic capabilities tell the application which actions are possible at the time this method is invoked based upon the implementation's knowledge of its ability to successfully perform the action. This determination may be based upon argument passed to this method, the current state of the call model, or some implementation-specific knowledge. These indications do not guarantee that a particular method will be successful when invoked, however.


registerAddress

public void registerAddress(JcatAddress addr)
                     throws InvalidPartyException,
                            MethodNotSupportedException,
                            PrivilegeViolationException
This method is used to register a JcatAddress with the JcatTerminal

Parameters:
addr - This parameter contains the address which is to be registered with this terminal. Successfully invoking this method will lead to emmitting JcatAddressEvent.TERMINAL_REGISTERED and JcatTerminalEvent.ADDRESS_REGISTERED.
Throws:
InvalidPartyException - - The specified address provided is not valid.
MethodNotSupportedException - - This method is not supported by the implementation.
PrivilegeViolationException - - The application does not have the proper authority to invoke this method.

deregisterAddress

public void deregisterAddress(JcatAddress addr)
                       throws InvalidPartyException,
                              MethodNotSupportedException,
                              PrivilegeViolationException
This method is used to deregister a JcatAddress with the JcatTerminal

Parameters:
addr - This parameter contains the address which is to be deregistered with this terminal. Successfully invoking this method will lead to emmitting JcatAddressEvent.TERMINAL_DEREGISTERED and JcatTerminalEvent.ADDRESS_DEREGISTERED.
Throws:
InvalidPartyException - - The specified address provided is not valid.
MethodNotSupportedException - - This method is not supported by the implementation.
PrivilegeViolationException - - The application does not have the proper authority to invoke this method.

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