JSR-043: JTAPI-1.4

Package javax.telephony.phone

The JTAPI Phone package provides objects that model the physical characteristics of the terminal, such as, speakerphone,microphone, display, buttons, ringer, handset, and lamp.

See:
          Description

Interface Summary
Component The Component interface is the base interface for all individual components used to model telephone hardware.
ComponentGroup A ComponentGroup is a grouping of Component objects.
PhoneButton Phone button interface.
PhoneDisplay Phone display interface.
PhoneGraphicDisplay A PhoneGraphicsDisplay represents a display device that is pixel-addressable, and which can be drawn into using AWT primitives.
PhoneHookswitch Phone hook switch interface.
PhoneLamp Phone lamp interface.
PhoneMicrophone Phone microphone interface.
PhoneRinger Phone ringer interface.
PhoneSpeaker Phone speaker interface
PhoneTerminal The PhoneTerminal interface extends the Terminal interface to provide functionality for the Phone package.
PhoneTerminalEvent The PhoneTerminalEvent is the base event for all events in the phone package.
PhoneTerminalListener The PhoneTerminalListener interface reports all changes that happen to the phone components.
PhoneTerminalObserver Deprecated. As of JTAPI 1.4, replaced by PhoneTerminalListener
 

Package javax.telephony.phone Description

The JTAPI Phone package provides objects that model the physical characteristics of the terminal, such as, speakerphone,microphone, display, buttons, ringer, handset, and lamp.

Introduction

This document provides an overview of the Phone Extension Package to the JavaTM Telephony API. The Phone Extension Package permits implementations to describe physical Terminals in terms of standardized components. Applications may query each Terminal, using this package, for the components of which it is made and control certain attributes of these components.


Note: The Phone Extension Package was previously named the Set Extension Package in Version 1.0 of this specification. Because of overwelming feedback on this specification, the JavaTM Telephony Specification working partners decided the term Set was ambiguous and has many meanings. Additionally, backwards compatability to the name Set will NOT be maintained. We apologize for any inconvienience this may have caused.

The Phone Extension Package defines a number of components standard to traditional telephone-set hardware. These components include speakerphone, microphone, display, buttons, ringer, handset, and lamp. Each component exports a standard interface to control its attributes. For example, the ringer permits applications to control its volume, while the buttons permit applications to simulate pressing buttons.


Overview Document Organization

This overview document is organized into the following sections:

Phone Package Architecture This section summarizes the architecture used by the Phone Extension Package to describe Terminals in term of the standard telephone-set components.
Extending the Terminal interface The section summarizes the java.telephony.PhoneTerminal interface. This interface extends the core Terminal interfaces to permit applications to query for the number and kinds of components of which it is composed.
Phone Package Standard Components This section describes the standard components in this package used to described traditional telephone-set hardware.

Phone Package Architecture.

This section explains how the Phone package describes Terminals in terms of their individual components.

Component Interface

The Phone package consists of a set of interfaces, each modelling some physical feature of a traditional telephone hardware set. There exists interfaces to model buttons, displays, lamps, ringers, hookswitches, speakers, and microphones. Each of these distinct interfaces provide methods to control the attributes inherent to each component type.

Each individual component extends the Component interface. These corresponding individual component interfaces are: PhoneButton, PhoneDisplay, PhoneLamp, PhoneRinger, PhoneHookswitch, PhoneSpeaker, and PhoneMicrophone. Each component is identified by its type and a string name.

ComponentGroup Interface

One or more individual components are organized into component groups. These component groups represent an association between components as they exist on the actual, physical hardware. Applications obtain an array of the components associated with a component group via the getComponents() method on this interface.

There may be more than one ComponentGroup associated with a single Terminal object. Applications obtain an array of the component groups associated with a Terminal via the getComponentGroups() method on the PhoneTerminal interface.

Terminals may have more than one ComponentGroup for the following reasons: at times an implementation may want to model a physical endpoint (i.e. Terminal) with two groups of components. One of these groups may model a telephone hardware set sitting on a person's desktop, while the other group may model a "virtual" telephone set drawn on the person's workstation's display.

Only a single ComponentGroup may be "activated" on a Terminal at a time. The act of activating a ComponentGroup enables its components to become actively part of the telephone call. For example, if a speaker component is part of a ComponentGroup which is activated, that speaker will receive all of the media sent to it. Applications activated a ComponentGroup with the activate() method and deactivate a group with the deactivate() method.



Extending the Terminal Interface

The Phone Extension Package extends the core Terminal interface with the PhoneTerminal interface. This interface permits applications to query for the components which make up the Terminal object.

As described in the previous section, each Terminal is composed of zero or more ComponentGroups. These groups are obtained via the PhoneTerminal.getComponentGroups() method. The following code segment queries for the Terminal named "5551212" and for the groups of components associated with this Terminal.

try {
  Terminal terminal = myprovider.getTerminal("5551212");

  ComponentGroup groups[];
  if (terminal instanceof PhoneTerminal) {
    groups = ((PhoneTerminal)terminal).getComponentGroups();
  }
} catch (Exception excp) {
  // Handle exceptions
}

Once an application obtains a list of groups, it may choose to activate one of these groups. The meaning of activating and deactivating a group of components was described in the previous section. The following code segment chooses the first group and activates it.

if (groups != null && groups.length >= 1) {
  try {
    groups[0].activate();
  } catch (Exception excp) {
    // Handle exceptions
  }
}

Next, applications may query for the array of individual components in the component group. An application may iterate through this array and control the attributes of each component-type. In the code sample below, the application looks for the microphone component and sets it on the maximum volume.

Component components[] = groups[0].getComponents();

 for (int i = 0; i < components.length; i++) {
  if (components[i] instanceof PhoneMicrophone) {
    PhoneMicrophone mic = (PhoneMicrophone)components[i];

    mic.setVolume(PhoneMicrophone.FULL);
  }
}


Phone Package Standard Components

The Phone Extension Package defines a number of standard components found on traditional telephone hardware. Each component exports its own interfaces and controls over its attributes. Each component also has specific events indicating when its attributes change. This section briefly describes each component, the methods available on its interfaces, and the event associated with them.

Button Component

    The PhoneButton component models a button on a telephone keypad. Applications may "press" this button via the buttonPress() on the PhoneButton interface. Each button has an indentifying piece of information associated with it (e.g. the text label on the telephone keypad button). Applications may obtain and set this information via the getinfo() and setInfo() methods, repsectively. Additionally, there may be a lamp-component associated with a button, obtained via the getAssociatedPhoneLamp() method.

    Applications receive the ButtonPressEv event when the button component has been pressed and the ButtonInfoEv when the identifying information on the button has changed.

Display Component

    The PhoneDisplay component models the display on the telephone hardware set. This display is composed of a certain number of rows and columns. Applications may set and obtain the text displayed at a particular coordinate via the setDisplay() and getDisplay() methods, respectively.

    When any information on the display has changed, the application receives the DisplayUpdateEv.

Hookswitch Component

    The PhoneHookswitch component models the physical hookswitch on a telephone hardware set. (A hookswitch is the level component on the telephone set on which the handset rests, which is depressed when the phone is on-hook.) The Hookswitch component can either be in an ON_HOOK state or an OFF_HOOK state. The application may set and obtain the hookswitch state via the setHookswitchState()) and getHookswitchState() methods, respectively.

    Applications receive the HookswitchStateEv event when the state of a hookswitch changes.

Lamp Component

    The PhoneLamp component models a light-indicator on the telephone hardware set. Often, this lamp is a single green-color or red-color LED. Lamp components have a "mode" attribute which indicate the pattern of its flashing light. For example, the lamp mode can be LAMPMODE_FLUTTER, LAMPMODE_STEADY, or LAMPMODE_WINK, to name a few. Applications may set and obtain the lamp mode via the setMode() and getMode() methods, respectively. Additionally, lamp components may be associated with a button component. This button component is obtained via the getAssociatedPhoneButton() method.

    Applications receive the LampModeEv when the mode of the lamp component has changed.

Microphone Component

    The PhoneMicrophone component represents the audio input device on a telephone hardware set. The microphone has a single attribute: its gain. Applications may set or obtain the microphone's gain via the setGain() and getGain() methods, respectively.

    Applications receive the MicrophoneGainEv event when the gain of a microphone component has changed.

Ringer Component

    The PhoneRinger component represents the audible ringing device on a telephone hardware set. The ringer component has several attributes. First, applications may control the ringing pattern of the ringer component. In order to control the ringing pattern, applications obtain the number of ringing patterns via the getNumberOfRingPatterns() method. Applications then set the ringing pattern via the setRingerPattern(). It uses an integer index value between zero and the number of ringing patterns minus one. Applications may obtain the current ringing pattern via the getRingingPattern() method, and the number of rings which have already happened via the getNumberOfRings() method.

    The ringer component also has a volume attribute that may be set or obtained via the setRingerVolume() and getRingerVolume() methods, respectively.

    Applications receive the RingerPatternEv when the ringing pattern has changed on the ringer component and the RingerVolumeEv when the ringer volume has changed.

Speaker Component

    The PhoneSpeaker component represents the audio output device on a telephone hardware set. The speaker has a single attribute: its volume. Applications may set or obtain the speaker's volume via the setVolume() and getVolume() methods, respectively.

    Applications receive the SpeakerVolumeEv event when the volume of a speaker component has changed.


JSR-043: JTAPI-1.4

Send comments to: JSR-43@ectf.org