Developing Java Applications

Transcription

1 WebSphere Voice Response for AIX with DirectTalk Technology Developing Java Applications Version 61 GC

2 Note Before using this information and the product it supports, read the general information under Notices on page 129 This edition applies to Version 6, Release 1 of IBM WebSphere Voice Response for AIX with DirectTalk Technology (program number 5724-I07), and to all subsequent releases and modifications until otherwise indicated in new editions Make sure you are using the correct edition for the level of the product Copyright International Business Machines Corporation 1998, 2009 US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp

3 Contents Figures vii Tables ix About this documentation xi Who should use this documentation xi How to use this documentation xi Typographic conventions xi Accessibility xii Notes on terminology xiii Where to find more information xiii Useful Web sites xiii Getting help xiv Making comments on this book xiv Chapter 1 Introduction to WebSphere Voice Response Java development 1 What tools are available for writing Java applications? 1 How does the Java API relate to the supplied WebSphere Voice Response JavaBeans? 2 Modifying JavaBeans applications 2 Java applications 2 How is an incoming call routed to a Java application? 2 What controls the sequence of events in a Java application? 3 How does the caller interact with the Java application? 5 How do you specify what the Java application says? 5 How do Java applications access information? 6 Creating reusable components 7 Integration and interoperability of Java applications 7 The benefits of Java 7 How to get voice data into applications 8 How voice segments are stored and identified 8 Making voice segments available to Java applications 10 What happens when you install a language? 11 How languages are identified in VoiceXML and Java 11 Why locale is important 12 Default locale 12 Internationalization 13 Defining your own locales 13 Language-only locales 14 How locale is used for speech recognition and text-to-speech 14 Chapter 2 Using the WebSphere Voice Response Java API classes 17 Installing the WebSphere Voice Response Java API classes 17 Prerequisites 17 Instructions 17 Registering the IBM Java Runtime Environment in Rational Application Developer 18 Creating a new voice application in Rational Application Developer 19 Introduction to applications 20 Managed and unmanaged applications 20 Exceptions 21 Getting started: the WVRApplication class 23 Setting the application environment 24 The ApplicationProperties class 26 Starting the call 27 Examples: receiving and making calls 30 Looping round to handle another call 31 Finishing with a call 32 Chapter 3 Creating voice applications 35 Saying something to the caller 35 Specifying what is to be spoken using the MediaType class 36 The VoiceSegment class 37 The DTMFSequence class 38 The AudioNumber class 39 The AudioCurrency class 40 The AudioDate class 41 The AudioTime class 42 The AudioString class 43 The TextToSpeech class 44 Creating a media sequence 45 Copyright IBM Corp 1998, 2009 iii

4 Voice enabling your data structures: the Playable interface 45 Playing output to the caller 46 Getting input from the caller 46 The CallplayAndGetInput() method 47 The PlayAttributes class 48 The InputAttributes class 49 The MenuAttributes class 52 The DTMFAttributes class 56 The RecoAttributes class 57 The Caller s response 59 Validating input 60 Recording the caller s voice input 61 Obtaining information about the recording 62 Dealing with silence 63 Changing the pacing tone 63 Internationalizing your applications 63 Setting the application locale 64 Changing the application locale dynamically 64 Determining which locale the application is using 65 Creating multilingual applications 65 Speaking currency values 65 Related information 67 More about handling calls 68 Summary of methods used for telephony-related functions 68 Handing a call to another application 68 Transferring a call to an agent 71 Getting called and calling numbers and application call data 77 Handling voice segments dynamically 78 Deleting voice segments dynamically 78 Importing and exporting voice segments dynamically 78 Invoking a VoiceXML application from a Java application 79 Invoking a state table 80 Obtaining information from state tables 81 Chapter 4 Managing your voice segments 83 Using dtjplex 83 dtjplex control file 84 Chapter 5 WebSphere Voice Response Java examples 87 Prerequisites for the examples 87 Voice segments for running the example applications 88 The language of the voice segments for the examples 88 Importing the voice segments into Java 88 List of voice segments in the Tutorials category 89 Examples 91 Example 1: Caller calls an application 92 Code for Example 1 93 Example 2: Select an item from a menu 94 Code for Example 2 95 Example 3: Caller exits from the application (menu item 5) 98 Code for Example 3 99 Example 4: Leave a message (menu item 1) 102 Code for Example Example 5: Key in a telephone number (menu item 2) 106 Code for Example Example 6: Order an item from a catalog (menu item 3) 111 Code for Example 6 Catalog class 112 Code for Example 6 InApp class 115 Example 7: Credit card validation (menu item 3 continued) 119 Code for Example 7 CardChecker class 121 Code for Example 7 Catalog class 123 Example 8: Order information (menu item 3 continued) 125 Code for Example 8 OrderInfo class 126 Code for Example 8 Catalog class 127 Notices 129 Trademarks 131 Glossary 133 List of WebSphere Voice Response and associated documentation 167 WebSphere Voice Response software 167 IBM hardware for use with WebSphere Voice Response 168 WebSphere Voice Response related products 168 WebSphere Voice Server 168 Unified Messaging for WebSphere Voice Response 168 AIX and the IBM pseries computer 168 HACMP 169 SS7 169 Integrated Services Digital Network 170 iv Developing Java Applications

5 Bellcore Specifications for ADSI Telephones 171 Index 173 Contents v

6 vi Developing Java Applications

7 Figures 1 Overview of some of the more important WebSphere Voice Response Java API classes 4 2 E-business application model 6 3 Adding voice to e-business 7 4 Voice segment database 8 5 Voice segments in the Java voice segment space 9 6 The Java voice segment space is divided into locales, which are divided into categories 9 7 Alternative ways of making voice segments available to your applications 11 8 Overview of WebSphere Voice Response Java API exceptions 22 9 Example of a control file Handing a call over to another application and waiting to get it back Handing a call over to another application Transferring the caller to an agent Consultation with an agent while the caller is on hold Retrieving a call from an agent Example of control file 85 Copyright IBM Corp 1998, 2009 vii

8 viii Developing Java Applications

9 Tables 1 Currency voice segments for XYZ currency 65 2 A value of spoken with different currency and locale property values 66 3 Voice segments required 67 4 Call-related methods and corresponding WebSphere Voice Response actions 68 Copyright IBM Corp 1998, 2009 ix

10 x Developing Java Applications

11 About this documentation This documentation provides information about developing Java applications for IBM WebSphere Voice Response for AIX Version 61 It includes an introduction to the Java Application Programming Interface (API), guidance for developing applications using Java, and instructions for testing applications Note: In this documentation, anywhere that Rational Application Developer is mentioned, you can use any Java integrated development environment (IDE) such as Eclipse Who should use this documentation To use this documentation you must be a Java application programmer You should also know how to use Rational Application Developer or another Java IDE How to use this documentation This documentation is in several sections and you may not need all of them If you want to print it from Adobe Acrobat, print the sections you need, by selecting the page numbers v Start with Chapter 1, Introduction to WebSphere Voice Response Java development, on page 1 to provide background information v Then read Chapter 2, Using the WebSphere Voice Response Java API classes, on page 17 and then follow the examples in Chapter 5, WebSphere Voice Response Java examples, on page 87 v Use Chapter 3, Creating voice applications, on page 35 for information about creating voice applications Typographic conventions This book uses the following typographic conventions: boldface Identifies an item that is in a WebSphere Voice Response window The item might be a keyword, an action, a field label, or a pushbutton Whenever one of the steps in a procedure includes a word in boldface, look in the window for an item that is labeled with that word Copyright IBM Corp 1998, 2009 xi

12 boldface italics Are used for emphasis Take extra care wherever you see bold italics italics Identify one of the following: v New terms that describe WebSphere Voice Response components or concepts A term that is printed in italics is usually followed by its definition v Parameters for which you supply the actual names or values v References to other books monospace Identifies one of the following: v Text that you type in an AIX window Because AIX is case sensitive, ensure that you type the uppercase and lowercase characters exactly as shown v Names of files and directories (path names) Accessibility WebSphere Voice Response for AIX is a voice application enabler The applications that are developed to run on WebSphere Voice Response provide telephone access to business data and services In this way, WebSphere Voice Response provides accessibility for people who cannot access the data and services by using regular Web pages or traditional graphic interfaces These telephone user interfaces are fully accessible to people who are blind or have low vision and, if speech recognition is used, to people with mobility impairments or limited hand use Speech recognition capability can be provided by products such as IBM WebSphere Voice Server In addition, support for users of Telephony Devices for the Deaf (TDD) is provided as part of the WebSphere Voice Response product With WebSphere Voice Response you can perform many application development and system administration tasks with a text editor or line commands these are accessible if you use a screen reader product to interface with them Also, the default settings of the WebSphere Voice Response graphical user interface can be changed to produce large fonts and high contrast colors Details of how to use these accessibility features can be found in the WebSphere Voice Response for AIX: User Interface Guide Alternatively, application development can be done with Java or VoiceXML development tools that are supplied by IBM and third parties You can also use a screen-reader product to access the WebSphere Voice Response publications in HTML format (for details of their availability refer to List of WebSphere Voice Response and associated documentation on page 167 at the back of this book) xii Developing Java Applications

13 Notes on terminology v A glossary of commonly-used terms is at the end of this book v The full product name of WebSphere Voice Response for AIX with DirectTalk Technology is generally abbreviated in this book to WebSphere Voice Response v The term pseries is generically used in this book to refer both to PCI-based RS/6000 computers and to appropriate models of the System and p5 pseries ranges (Consult your IBM representative for details of models that are supported for use with WebSphere Voice Response) RS/6000 computers with an MCA bus are not supported v The IBM Quad Digital Trunk Telephony PCI Adapter is generally referred to in this book by its abbreviation DTTA This adapter is a replacement for the IBM ARTIC960RxD Quad Digital Trunk PCI Adapter, which is generally referred to by the abbreviation DTXA The DTXA is not supported with WebSphere Voice Response Version 61 v References made to the VoiceXML 21 specification are intended to include VoiceXML 20 unless otherwise specified Where to find more information The information provided in the WebSphere Voice Response library will help you complete WebSphere Voice Response tasks more quickly A complete list of the available books and where you can obtain them is shown in List of WebSphere Voice Response and associated documentation on page 167 Useful Web sites The following Web sites are useful sources of information about WebSphere Voice Response and related products: WebSphere Voice Response IBM WebSphere developerworks resources (including WebSphere Voice products) VoiceXML Version 20 and 21 specifications CCXML Version 10 specification Genesys For more information on Genesys products go to the Genesys Web site at About this documentation xiii

14 Getting help If you have a problem with the Java and VoiceXML support in one of the WebSphere Voice Response products, report it to IBM using your normal support channel Making comments on this book If you especially like or dislike anything about this book, feel free to send us your comments You can comment on what you regard as specific errors or omissions, and on the accuracy, organization, subject matter, or completeness of this book Please limit your comments to the information that is in this book and to the way in which the information is presented Speak to your IBM representative if you have suggestions about the product itself When you send us comments, you grant to IBM a nonexclusive right to use or distribute the information in any way it believes appropriate without incurring any obligation to you You can get your comments to us quickly by sending an to idrcf@hursleyibmcom Alternatively, you can mail your comments to: User Technologies, IBM United Kingdom Laboratories, Mail Point 095, Hursley Park, Winchester, Hampshire, SO21 2JN, United Kingdom Please ensure that you include the book title, order number, and edition date xiv Developing Java Applications

15 Chapter 1 Introduction to WebSphere Voice Response Java development This section describes the Java application programming environment supported by WebSphere Voice Response, and then introduces some of the concepts that are fundamental to using Java in your applications The WebSphere Voice Response Java application programming interface (Java API) allows you to extend the capability of VoiceXML applications by accessing back end systems or complex telephony function such as call transfer Applications developed using the Java API can be integrated with VoiceXML 21 dialogs, and with CCXML call control scripts to deliver a robust complete solution This can include host data accessed through Enterprise JavaBeans (EJBs) and JavaServer Pages (JSPs), or specialized computer-telephony integration (CTI) functions accessed through WebSphere Voice Response state tables or CCXML It can also include legacy state tables that provide standard dialogs or that invoke custom servers to access databases You can also use the API to develop voice applications entirely in Java TheWebSphere Voice Response for AIX: General Information and Planning manual provides more background information about the kinds of application you can create with Java, and shows how you can fit these applications into your enterprise systems The following topics are covered in this section: v What tools are available for writing Java applications? v How does the Java API relate to the supplied WebSphere Voice Response JavaBeans? on page 2 v Java applications on page 2 v How to get voice data into applications on page 8 What tools are available for writing Java applications? The product CDs contain jar files that you can import into a Java integrated development environment such as Rational Application Developer that you can use instead of a text editor to code Java applications To help create and test your applications, you can use the Voice Toolkit, which is downloadable from: Copyright IBM Corp 1998,

16 How does the Java API relate to the supplied WebSphere Voice Response JavaBeans? Support for Java applications in releases of Version 3 of WebSphere Voice Response for AIX was based on the JavaBeans supplied with those versions These applications will run unchanged on the current release of WebSphere Voice Response However, for all new applications, it is recommended that you use the Java API The Java API provides all the functionality of the JavaBeans, but offers a cleaner interface and improved reusability The Java API also uses an exception model instead of the event model used by the beans There is some additional functionality in the Java API that was not available using JavaBeans: v The Playable interface allows you to make any data item presentable to the caller: for example, the name, date of birth, and salary retrieved from an employee record in a database could be spoken as TextToSpeech, AudioDate and AudioCurrency items respectively v You can specify the beep for recording or speech recognition, for example, as a spoken instruction ( please start recording ) v You can import and export voice segments at runtime Modifying JavaBeans applications If you need to modify a JavaBeans application to use functionality included in the supplied JavaBeans, you can do so as you have done in previous releases If you need to modify a JavaBeans application to use functionality available only through the Java API, you will need to convert the JavaBeans application Java applications This section describes how Java applications work, how you implement them and when you should consider Java rather than other programming models: v How is an incoming call routed to a Java application? v What controls the sequence of events in a Java application? on page 3 v How does the caller interact with the Java application? on page 5 v How do you specify what the Java application says? on page 5 v How do Java applications access information? on page 6 v Integration and interoperability of Java applications on page 7 v The benefits of Java on page 7 How is an incoming call routed to a Java application? A Java application can be started by one of the following methods: 2 Developing Java Applications

17 1 An incoming telephone call is routed directly to the Java environment and the Java configuration maps the called number to the application 2 An incoming telephone call is routed directly to the Java environment and a CCXML document contains logic that can handle the call and route it to the application 3 A VoiceXML application can call a Java application The WVR class, which represents the WebSphere Voice Response system, establishes telephone calls and enables communication with the WebSphere Voice Response system The WVR class can also be used to make outgoing calls and to return the call at the end of the interaction The need for multiple application instances Each instance of a Java application typically handles a single call at one time To deal with more than one call you need to have multiple instances of the application waiting for calls: as many as you expect to handle during your peak hour If you have more than one application, you need a different set of instances for each, or you can have a top-level Java application that greets the caller, asks them what service they require, and calls other applications as needed The service application can be written in Java, VoiceXML, or it can be a state table What controls the sequence of events in a Java application? In a Java application, the sequence of events is determined by the ordering of statements in the program The WebSphere Voice Response Java API includes classes and methods representing the WebSphere Voice Response system, and also the components of a typical voice response application Figure 1 on page 4 gives an overview of some of the more important classes and methods in the Java API v The WVR class and its methods represent the WebSphere Voice Response system and its interactions v The Call class and its methods interact with and manipulate telephone calls through actions such as playing audio (the play() method), recording the caller (the record() method), getting input (the playandgetinput() method) and also by performing telephony functions, for example: the getcallednumber() and getani() methods, which provide called and calling number information to the application the consult(), conference(), transfer(), blindconference(), and blindtransfer() methods, which provide call transfer and conference call facilities v The PlayAttributes class specifies whether the caller can interrupt the messages played as part of a voice or DTMF input Chapter 1 Introduction to WebSphere Voice Response Java development 3

18 v The MenuAttributes class defines a menu that the caller can select a choice from Each choice contains a label to identify the choice to the application, a message to announce the choice to the caller, a DTMF selector key and a selector word v The InputAttributes class specifies how a caller is to be guided through giving an input, and how their input should be validated v The DTMFAttributes class specifies how a caller can use their telephone keypad to give input v The RecoAttributes class specifies how a caller can speak to the application to give input WVRApplication ApplicationProperties WVR makecall() waitforcall() MediaType PlayAttributes RecordingInfo InputAttributes MenuAttributes Call Call Call record() invokestatetable() StateTableResult DTMFAttributes RecoAttributes play() playandgetinput() InputResult Figure 1 Overview of some of the more important WebSphere Voice Response Java API classes 4 Developing Java Applications

19 How does the caller interact with the Java application? The caller can interact with the application in two ways: v Free form key or voice input v Structured menu input using key presses (DTMF), or speech recognition, or both There are five attribute classes that are used in conjunction with the CallplayAndGetInput() method to facilitate this: The PlayAttributes class on page 48, The InputAttributes class on page 49, The MenuAttributes class on page 52, The DTMFAttributes class on page 56 and The RecoAttributes class on page 57 To record the caller s speech and store it as a voice segment, you use the Callrecord() method For more information about speech recognition see the WebSphere Voice Response General Information and Planning manual and the WebSphere Voice Server Administrator s Guide for your version of WebSphere Voice Response How do you specify what the Java application says? You can use prerecorded speech or text-to-speech in a Java voice application by using any of the following subclasses of MediaType These media classes specify the sounds that the caller hears: v VoiceSegment specifies recorded voice data and is used both for output, and for input recorded from the user v DTMFSequence specifies a number of dual-tone multifrequency signals to be played v AudioCurrency specifies a currency amount to be spoken v AudioDate specifies a date to be spoken v AudioNumber specifies a number to be spoken v AudioString specifies a character string to be spoken v AudioTime specifies a time to be spoken v TextToSpeech specifies text from which speech is to be synthesized v MediaSequence is a composite of other MediaType objects You can also use arrays of MediaType objects to make a composite sequence of any of the media elements All the methods capable of playing a message can accept arrays of MediaTypes This allows your applications to play chains of MediaType objects in one operation Chapter 1 Introduction to WebSphere Voice Response Java development 5

20 You can make any data item presentable to the caller using the Playable interface For example, the name, date of birth, and salary retrieved from an employee record in a database could be spoken as TextToSpeech, AudioDate and AudioCurrency items respectively How do Java applications access information? Unlike the proprietary programming languages and interfaces supplied with many interactive voice response systems (for example, WebSphere Voice Response state tables), you can use the Java API together with other APIs and classes from other sources to create your applications, for example, you can use other Java classes for database access, including: v IBM Host Application Connectivity Link (HACL) v JDBC database access v IBM Secureways (LDAP directory access) Adding voice capability to existing business applications Most importantly, you can add voice capability to existing business applications, taking advantage of what s already there without having to change it For example, if you are an IBM e-business, you may already be using Enterprise JavaBeans (EJBs) to write the server side components of your business applications in Java Your enterprise application model looks something like the one shown in Figure 2 Figure 2 E-business application model This model is designed to deliver Web pages You would probably use IBM Rational Application Developer to create the business logic and author the Web pages The applications would use connectors to access the data in tier-3 It s easy to add voice to this model Let s put it in terms of a real example Assume that one of the Java applications offered by the e-business shown in 6 Developing Java Applications

21 Telephone Network Caller Figure 2 on page 6 accesses insurance policy data and returns it to the user s Web browser The enterprise can add voice to the solution without changing the business logic and tier-3 server delivering data to users Using IBM Rational Application Developer and the Java API supplied with WebSphere Voice Response they can implement a voice application that integrates with the existing Web application at the Enterprise JavaBeans (EJB) level The final result provides user access to insurance data through fully integrated voice and Web applications, as shown in Figure 3 Web browser Host System HTML/HTTP WebSphere Application Server JSP JSP JSP Connector Connector Connector Data Voice response node Java Java application Java application application Command EJB EJB EJB Telephone Java and VoiceXML Environment WebSphere Voice Response system Figure 3 Adding voice to e-business This is a simple example, but the same principles apply to complex e-business environments in which WebSphere Voice Response might link with several other IBM products to enable successful e-business across existing enterprises These products include not only WebSphere but others such as SecureWay (for directory access), WebSphere MQ (for messaging), CICS (for transaction processing), and DB2 (for database access) Creating reusable components The Java language is especially suited to modular programming You can design your applications as a set of classes, which you can reuse in other applications, and which are easy to customize and maintain Integration and interoperability of Java applications In addition to being able to access data, Java applications are also very easy to integrate with other systems For example, call control can either be handled by the WebSphere Voice Response system or it can be fully integrated with a telephony service The benefits of Java Using Java provides the following benefits: Chapter 1 Introduction to WebSphere Voice Response Java development 7

22 v While it is recommended that you create the dialogs using VoiceXML, Java can be used to augment the capabilities of the W3C VoiceXML and CCXML specifications with additional functions available using Java such as fax, when required v Java provides a simple and friendly environment for the integration of VoiceXML dialogs with lower-level functions and a wealth of other capability v Platform independence Java applications run either on an application server or on the WebSphere Voice Response system How to get voice data into applications Voice segments are the prerecorded sounds that callers hear when they listen to a voice application A VoiceSegment media object represents a voice segment stored on the WebSphere Voice Response server A voice segment has a category and a name, these together with the locale uniquely identify the voice segment stored on the telephony server An understanding of how voice segments are stored is fundamental to understanding how Java voice applications work: v How voice segments are stored and identified v Making voice segments available to Java applications on page 10 v What happens when you install a language? on page 11 How voice segments are stored and identified Voice segments are stored in the voice segment database of the base WebSphere Voice Response system on the voice response node Host System Voice response node Java Java application Java application application Java and VoiceXML Environment WebSphere Voice Response system Voice segment database Figure 4 Voice segment database 8 Developing Java Applications

23 However, any voice segments that are required by Java voice applications must be located in a special Java voice segment space within the voice segment database, as shown in Figure 5 Utility commands are provided for adding your voice segments to this space Java voice segment space Voice segments available to Java applications Voice segment Voice segment database database Base WebSphere Voice Response system Figure 5 Voice segments in the Java voice segment space This space is divided into locales, which are, in turn, divided into categories Figure 6 shows an example where there are three locales, English (en), UK English (en_gb), and German (de_de) There is a Menu and a System category in both UK English and German, and a Tutorials category in English Figure 6 The Java voice segment space is divided into locales, which are divided into categories Chapter 1 Introduction to WebSphere Voice Response Java development 9

24 Note: If a voice segment for a specific country or region is not found, the search continues among voice segments for the language So, the en voice segments can be used by an application whose locale is either en_gb or en_us, or any other locale whose language component is en Making voice segments available to Java applications You can make voice segments available to your Java voice applications in any of the following ways (as shown in Figure 7 on page 11): 1 Record new voice segments in a studio or using a sound recorder utility, and import them from your file system, either singly or in batch See Chapter 4, Managing your voice segments, on page 83 2 Use voice segments that are already on your base WebSphere Voice Response system, and add them to the Java voice segment space See Chapter 4, Managing your voice segments, on page 83 3 Use the Callrecord() method to record new voice segments in a Java voice application See Recording the caller s voice input on page 61 4 Transfer them from the database on one voice response node to the database on another voice response node by exporting and then importing them See Chapter 4, Managing your voice segments, on page 83 5 Use the WVRimportVoiceSegment() and WVRexportVoiceSegment() methods in a Java application to import and export voice segments from or to a file or audio stream Note: These voice segments are used by Java applications only, not by VoiceXML applications 10 Developing Java Applications

25 1 Record new voice segments in a studio or using a sound recorder utility, and import them in batch Record 2 Use voice segments from your base Voice Response system dtjplex -action addvs 3 Use the Callrecord() method to record new voice segments in a Java application File system dtjplex -action importvoicehost Java voice segment space Voice Voice segment segment database Voice segment database database dtjplex -action exportvoicehost File system 4 Transfer from one voice response node to another 5 Use the WVRimport Voice Segment() and WVRexport Voice Segment() methods in a Java application to import and export voice segments from or to a file or audio stream Figure 7 Alternative ways of making voice segments available to your applications What happens when you install a language? Whenever you install a language in the Java environment, new voice segments are imported from the language zip file into the Java voice segment space All these voice segments are located in the System and Menu categories How languages are identified in VoiceXML and Java All of the base WebSphere Voice Response products use the concept of language, and some languages are defined in terms of language and the country or region in which it is spoken: for example, Canadian French as opposed to French spoken in France In Java, this is explicitly acknowledged, by using the term locale to refer to both the language and the specific territory Each locale is identified by an ISO-defined code, which comprises a language component and a country or region component: for example, fr_ca for Canadian French and fr_fr for French in France Optionally, you can create your own locale identifiers, including an optional user-defined variant For example en_us_fred If you are using a locale to create Java voice segments, there is a limit of 15 characters for the length of Chapter 1 Introduction to WebSphere Voice Response Java development 11

26 the locale identifier, so the variant part can be up to 9 characters For portability across different versions of the JDK, ensure that the locale variant ( US in the previous example) is specified in uppercase In VoiceXML, the locale of the application is identified by the xml:lang attribute of the <vxml> tag This section tells you about v Why locale is important v Default locale v Internationalization on page 13 v Defining your own locales on page 13 v Language-only locales on page 14 v How locale is used for speech recognition and text-to-speech on page 14 Why locale is important Locale is used for: v Identifying precisely what is to be spoken to the caller: the words, accent, and phrasing used (by using the variant component of the locale identifier, you can also specify any other characteristics you want) In other words, locale is used to identify the voice segments to be used v Determining the technology to be used for text-to-speech and speech recognition v Optionally, altering the logic of your application In VoiceXML, the locale also determines the language of the built-in grammars, error prompts, and other language-specific features used by the browser to handle an incoming call Default locale The concept of a default locale is an important one, whether you are designing and writing applications or setting up and managing systems: v Each voice response node has a default locale, defined in the NodeName configuration entry (for more information see WebSphere Voice Response for AIX: Deploying and Managing VoiceXML and Java Applications) This default locale is used by Java applications For VoiceXML 21 applications, the default locale is the locale of the operating system If the operating system is running in an unsupported locale, the default will be en_us v Optionally, each application can have a default locale, overriding the node default locale This must be specified in the AppName entry 12 Developing Java Applications

27 Internationalization Although applications can be written to run on any supported locale, there are differences in the way that CCXML, VoiceXML, and Java applications are internationalized VoiceXML In VoiceXML, resources referenced by URIs are not subject to changes in the current locale, but built-in resources (such as built-in grammars) are You should associate a locale with the document rather than with the execution environment (by using the <vxml> xml:lang attribute) to ensure that the correct built-in resources are used CCXML In CCXML, resources referenced by URIs are not subject to changes in the current locale There is no mechanism for associating a locale with the document rather than with the execution environment CCXML can be written in any supported code page There is a charset attribute for the <script> element that allows the CCXML script to indicate the code page of an ECMA script to be fetched Java Java applications can be completely language-independent if the locale is not specified on any individual voice segment objects within the application To make the application speak a specific language, simply set the default locale of the node to that language You could have several voice response nodes, each running the same applications in a different language Provided that voice segments for the locale are available they are played to the caller in that language Instead of using the node default locale, you could specify a default locale for each application, and have applications speaking different languages running in the same node You can have several AppName configuration entries for the same Java class, each specifying a different application name and a different locale Thus, the current locale provides full internationalization for your Java applications, provided that each language is installed on the voice response node Defining your own locales It is up to you how you use the user-defined variant component of the locale identifier You might record voice segments for an application using different Chapter 1 Introduction to WebSphere Voice Response Java development 13

28 voices: male and female, for example You would identify these voice segments as, for example, en_us_male, en_us_female) You might have a different greeting at the beginning of an application, depending on which branch of your company the call is for, even though the logic of the application is the same for all branches To achieve this, invent a locale identifier for each branch (for example, en_us_chicago, en_us_washingto, en_us_newyork) Then name each greeting voice segment using the appropriate locale identifier, and use different default locales, in one of the ways described in Internationalization on page 13, to run instances of the application for each branch The other voice segments in the application, common to all branches, should be in the base locale (en_us) Whenever a voice segment for a specific variant cannot be found, a voice segment for the country or region and language is searched for Specifying PREEURO support with existing 3 part locales As a result of Euro support, five languages (French, Castilian Spanish, Catalan, German, and Italian) default to saying Euro rather than the national currency in both new and existing applications In two part locales (for example, fr_fr), you can override this by specifying a variant of PREEURO (for example, fr_fr_preeuro) in the locale option of the AudioCurrency object (see Developing Java applications) However, if you have defined your own locales with three parts (for example, fr_fr_paris), and want to use preeuro support, you can do this only by specifying dtjpreeurosupport = true in the dtjini file Language-only locales In some cases, you may want to use a language-only locale identifier, such as en or fr One example of this is the use of en as a locale identifier for the voice segments supplied for the example applications in Chapter 5, WebSphere Voice Response Java examples, on page 87 These voice segments can be used when the current language of an application is any derivative of the en locale: en_us, en_gb, en_au, and so on Whenever a voice segment for a specific country or region cannot be found, a voice segment for the generic language is searched for How locale is used for speech recognition and text-to-speech Because some speech recognition and text-to-speech technologies are better at some languages than others, you can use different technologies for processing different languages You specify one technology for all locales and then override this for the exceptional languages This can be specified on a per node or per application basis Specifying the technology for a new language or switching between technologies for any language is done without altering the application itself 14 Developing Java Applications

29 If you are using language-only locales, make sure you have speech plug-ins configured for all locales or the single-part locale The current application locale is assumed for all speech recognition attempts, and is used for text-to-speech unless specified within the application The current application locale for VoiceXML 21 applications is either the operating system locale or the application default locale, if one has been specified The current application locale for Java applications is the node default locale or the application default locale, if one has been specified Chapter 1 Introduction to WebSphere Voice Response Java development 15

30 16 Developing Java Applications

31 Chapter 2 Using the WebSphere Voice Response Java API classes Read this section after reading Chapter 1, Introduction to WebSphere Voice Response Java development, on page 1 If this is your first reading, we suggest that you have a quick look through this section, register the Java API classes with Rational Application Developer and then work through the supplied examples (refer to the Chapter 5, WebSphere Voice Response Java examples, on page 87) to get some practical experience You will find it useful to refer to this chapter when you come to develop your own applications For more detailed information about each class, see the JavaDoc Reference provided on the WebSphere Voice Response Publications CD This section includes the following topics: v Installing the WebSphere Voice Response Java API classes v Introduction to applications on page 20 v Starting the call on page 27 v Looping round to handle another call on page 31 v Finishing with a call on page 32 Related information can be found in the following sections: v Chapter 3, Creating voice applications, on page 35 Installing the WebSphere Voice Response Java API classes Before you can develop a Java application, you need to install the WebSphere Voice Response Java API classes, following the instructions in this section Prerequisites v TCP/IP must be installed, configured, and running, and the hostname must be resolvable by the voice response node (that is, it must have a DNS entry in the nameserver) v The system must have IBM Runtime Environment for Windows, Java 2 Technology Edition, Version 16 installed Instructions If you have not yet installed WebSphere Voice Response, you must do this first The jar files for the WebSphere Voice Response Java API classes are installed with WebSphere Voice Response The jar files are installed in the following AIX directory: Copyright IBM Corp 1998,

32 /var/dirtalk/dtbe/server 1 Create a directory for the jar files on the computer where you intend to develop your Java voice applications 2 Copy all the jar files in the /var/dirtalk/dtbe/server directory to the directory on the computer where you intend to develop your Java voice applications Registering the IBM Java Runtime Environment in Rational Application Developer Before using the Java API with IBM Rational Application Developer, you must ensure that Rational Application Developer is configured to use the same version of Java that is supplied with WebSphere Voice Response for AIX The IBM Java Runtime Environment supplied with WebSphere Voice Response for AIX is Version 60 Consequently, Rational Application Developer must be configured to use IBM 32-bit Runtime Environment for Windows, Java 2 Technology Edition, Version 60 before you can use the Java API with Rational Application Developer To do this: 1 Open Rational Application Developer 2 Select Window->Preferences 3 In the Preferences window, expand the Java section and click on Compiler On the Compliance and Classfiles tab, click on the drop down list next to Compiler compliance level, and select 60 If 60 is not shown in the list, you must install the version 60 JRE To do this: a In the Preferences window, under the expanded Java section, click on Installed JREs b Select the WebSphere v6 JRE If this JRE is not included in the list displayed, you must install version 60 of the IBM Java Runtime Environment After you have done this, perform the following steps c to k c Click Add to bring up the Add JRE window d In the Add JRE window, uncheck the Use default system libraries box e Enter a name for the JRE in the JRE name field f Click in the JRE home directory field and then click the Browse button g Navigate to the directory where you installed IBM Java Runtime Environment Version 60 h Click the Add External JARs button Navigate to the IBM Java Runtime Environment \lib directory 18 Developing Java Applications

33 i Select all the JAR files and click OK j Make sure that corejar is at the top of the list To move a JAR file, select the file and move it using the Up and Down buttons k Click OK l Repeat steps 2 and 3 of this procedure Rational Application Developer will now compile projects using IBM Java Runtime Environment Version 60 Creating a new voice application in Rational Application Developer You register the Java API classes in IBM Rational Application Developer when you create a new application Follow these instructions to create a new voice application: 1 Create a new project by selecting File->New->Project 2 Select Java and Java Project Click Next 3 Give the project a name, for example if you are running the examples, use VRExamples Click Next 4 Click the Libraries tab Click Add External JARs and navigate to the directory where you copied the jar files from the /var/dirtalk/dtbe/ server directory on the AIX machine wherewebsphere Voice Response is installed Open the following files: v ibmcctljar v ibmdtalkjar v ibmdtextjar v ibmwvrapijar v ibmdtext2jar v jsjar v vxijar v vxievjar v vxisrvcjar Click Finish 5 Create a new package for the WebSphere Voice Response Java and VoiceXML Environment application by selecting File->New->Package 6 Give the package a name, for example, if you are running the examples, use tut Click Finish 7 Create the new class for the application by selecting File->New->Class 8 Make sure the Source Folder and Package fields match the project and package names you used in steps 3 and 6 Chapter 2 Using the WebSphere Voice Response Java API classes 19

34 9 In the Name field, type a name for the class 10 In the Superclass field, click Browse Type WVRApplication, select the WVRApplication class and click OK 11 In the section labeled Which method stubs would you like to create?, ensure that the check box for public static void main(string[] args) is unchecked and the check box for Inherited abstract methods is checked Click Finish The new class is created in the package and project you specified, and the corresponding application code is generated, for example: package tut; import comibmtelephonywvrwvrapplication; import comibmtelephonywvrwvrexception; /** * * To change this generated comment edit the template variable "typecomment": * Window>Preferences>Java>Templates * To enable and disable the creation of type comments go to * Window>Preferences>Java>Code Generation */ public class InApp extends WVRApplication { /** comibmtelephonywvrwvrapplication#voicemain() */ public void voicemain() throws WVRException { Introduction to applications All WebSphere Voice Response Java applications are extensions of the WVRApplication class This class contains methods which are used automatically by the Java and VoiceXML environment when it manages your application The WVRApplication class also contains a voicemain() method, which will contain the main implementation of your application Within this voicemain() method your code will include a WVR object, which represents the base WebSphere Voice Response system, and at least one Call object, which represents a single call The WVR class is used to receive and make telephone calls, handle voice segments and define application properties The Call class is used to interact with and manipulate telephone calls, for example, by playing audio, transferring calls, getting input from callers and so on Managed and unmanaged applications WebSphere Voice Response Java applications can be: Managed When you deploy your application you will want it to be completely 20 Developing Java Applications

35 managed by the Java and VoiceXML environment In order for this to happen you must define an AppName entry in the configuration file, defaultcff For more information about the AppName entry see WebSphere Voice Response for AIX: Deploying and Managing VoiceXML and Java Applications When you start the application, the Java and VoiceXML environment automatically retrieves the settings for the application environment, such as locale, from the configuration file When you tell the voice response node to start up the application, the Java and VoiceXML environment automatically creates an instance of your application and starts it running For more information about running applications managed (also known as running applications in a node ), see WebSphere Voice Response for AIX: Deploying and Managing VoiceXML and Java Applications Unmanaged When you are testing your application you will probably run it unmanaged This means that the application is not completely managed by the Java and VoiceXML environment, and there is no AppName entry in the configuration file for this application There are no environment settings for the application to retrieve so you must define them yourself within the application See Setting the application environment on page 24 Unmanaged applications also do not run automatically You must implement the standard Java main() method to enable the application to be run from a command line For more information, see Getting started: the WVRApplication class on page 23 Exceptions The WebSphere Voice Response Java API uses a fairly standard exception model Some exceptions are expected, like WVRRequestCancelledException or WVRHungUpException, but most are thrown when the application encounters an error condition The exceptions are arranged into a hierarchy The hierarchy groups related exceptions together and allows you to catch a whole group of exceptions in one go by catching the exception that is the base class for the group For instance all exceptions relating to the Call class are either direct or indirect sub classes of WVRCallException The base classes are as follows: Chapter 2 Using the WebSphere Voice Response Java API classes 21