iplanet billerxpert 4.6 b2c edition customization guide · 2011-02-10 · or extending billerxpert...

Customization GuideiPlanet BillerXpert 4.6

May 2002

Copyright © 2002 Sun Microsystems, Inc. All rights reserved.

Sun, Sun Microsystems, the Sun logo, iPlanet are trademarks or registered trademarks of SunMicrosystems, Inc. in the United States and other countries.

Federal Acquisitions: Commercial Software—Government Users Subject to Standard License Termsand Conditions

The product described in this document is distributed under licenses restricting its use, copying,distribution, and decompilation. No part of the product or this document may be reproduced in anyform by any means without prior written authorization of Sun Microsystems, Inc. and its licensors,if any.

THIS DOCUMENTATION IS PROVIDED "AS IS" AND ALL EXPRESS OR IMPLIEDCONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIEDWARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE ORNON-INFRINGEMENT, ARE DISCLAIMED, EXCEPT TO THE EXTENT THAT SUCHDISCLAIMERS ARE HELD TO BE LEGALLY INVALID.

________________________________________________________________________________________

Copyright © 2002 Sun Microsystems, Inc. Tous droits réservés.

Sun, Sun Microsystems, le logo Sun, iPlanet sont des marques de fabrique ou des marques déposéesde Sun Microsystems, Inc. aux Etats-Unis et d’autre pays.

Le produit décrit dans ce document est distribué selon des conditions de licence qui en restreignentl'utilisation, la copie, la distribution et la décompilation. Aucune partie de ce produit ni de cedocument ne peut être reproduite sous quelque forme ou par quelque moyen que ce soit sansl’autorisation écrite préalable de Sun Microsystems, Inc. et le cas échéant, de ses bailleurs de licence.

CETTE DOCUMENTATION EST FOURNIE “EN L'ÉTAT”, ET TOUTES CONDITIONS EXPRESSESOU IMPLICITES, TOUTES REPRÉSENTATIONS ET TOUTES GARANTIES, Y COMPRIS TOUTEGARANTIE IMPLICITE D'APTITUDE À LA VENTE, OU À UN BUT PARTICULIER OU DE NONCONTREFAÇON SONT EXCLUES, EXCEPTÉ DANS LA MESURE OÙ DE TELLES EXCLUSIONSSERAIENT CONTRAIRES À LA LOI.

I

Contents

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1Before You Begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1Documentation Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2The Document Online . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3Product Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

Chapter 1 Introduction to iPlanet BillerXpert Customization . . . . . . . . . . . . . . . . . . . . . . . . . 5BillerXpert Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5Customization Strategy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Front-End Classes and Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Core Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9Servlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Application Business Object Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Validation Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Output Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12JSP Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Front-End Files and Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Chapter 2 Customization Techniques . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Modifying makefile Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Exercise 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Changing JSP Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29Exercise 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Displaying Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31Exercise 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

II iPlanet BillerXpert 4.6 Customization Guide • May 2002

Using Contexts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35Exercise 4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Invoking Servlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38Exercise 5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Collecting Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48Exercise 6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Validating Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61Exercise 7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

Implementing Servlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69Exercise 8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

Implementing an Event Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82Exercise 9 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

Changing Database Schemas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95Exercise 10 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97Tutorial Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

Configuring Table Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

Exercise 11 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99Implementing Component Business Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

Exercise 12 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

Chapter 3 Common Front-End Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121BXBaseServlet Class Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

Class Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123Context Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123Context Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124Session, Status, and Application Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124

Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125createBXBillingContext( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125createBXConfigContext( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125createBXMembershipContext( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125Create BXSession ( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125displayErrorMsg( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126displayTemplate( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127getBXSession( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128getSessionProxy( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128init( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128verifyUserSession( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129CheckACL( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

BXBaseView Class Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130Class Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131Context Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

III

Status Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

BXBaseView( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

debug( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132set( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133setBillingContext( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133setPaymentContext( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

BXConfigObj Class Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134Class Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

BXErrorCode Class Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135Class Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

BXSession Class Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143

Class Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

BXSession( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

debug( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146getAccount( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147getAddress( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147getAdTargetString( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147getBillerID( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148getBillType( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148getCountry( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148getEmulationID( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148getLocalelLanguage( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149setBillerId( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149setBillType( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149setCountry( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150setEmulationID( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150setLocaleLanguage( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151getBCAs( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151getDayPhone( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151getDefaultPaymentMethod( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152getDescription( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152getEmail( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152getFaxNumber( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153getFirstName( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153getLanguage( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153getLastName( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153getMiddleName( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154getNickName( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154

IV iPlanet BillerXpert 4.6 Customization Guide • May 2002

getNightPhone( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154getNumberMonth( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155getOnlineName( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155getPassword( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155getPrefix( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156getPrimaryContact( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156getProfileExtension( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156getSalutation( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157getSearchAttributes( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157getSecondaryContact( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157getSelectedAccount( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157getServiceExtension( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158getSuffix( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158getUserID( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158isUserProfile( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159parseExtension( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159saveValString( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160setAccount( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160setAddress( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160setBCAs( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161setDayPhone( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161isUserProfile( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162parseExtension( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162saveValString( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162setAccount( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163setAddress( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163setBCAs( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164setDefaultPaymentMethod( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164setDescription( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165setFaxNumber( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165setFirstName( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166setLanguage( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166setLastName( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166setMiddleName( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167setNickName( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167setNightPhone( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168setNumberMonth( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168setOnlineName( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168setPassword( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169setPrefix( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169setPrimaryContact( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170setProfileExtension( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170setSalutation( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170

V

setSearchAttributes( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171setSecondaryContact( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171setSelectedAccount( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172setServiceExtension( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172setSortField( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172setSuffix( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173setUserID( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173setValString( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174setUserProfile( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174

BXBaseBean Class Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175Class Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175Data Members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176

BXBaseBean . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176format( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176log( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176toString( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177

BXTemplateBeanMapBasic Class Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177Class Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178BXTemplateBeanMapBasic Data Members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178

BXTemplateBeanMapBasic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178format( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179log( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179set( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179setOAS( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180

toString( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180vectorToString( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

BXTemplateUtil Class Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181Class Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182

addressToString( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182format( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182dateToString( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183

BXValidateView Class Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184Class Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

BXValidateView . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

getMinLength( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

VI iPlanet BillerXpert 4.6 Customization Guide • May 2002

getNumErrors( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186getParmList( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186insertError( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186parmCount( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187printInParms( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187setError( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187validate( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

BXValidateAttribute Class Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188Class Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189

BXValidateAttribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190

getAttribute( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190getAttributeType( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190getDateMax( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191getFormatString( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191getFormatString( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191getMax( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192getMin( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192isRequired( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192setDateMax( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192setDateMin( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193

BXValidator Class Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193Class Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193Attribute Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194

validate( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194BXViewUtil Class Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195

Class Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196addressToString( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196ccValidate( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197getMonthNumber( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197getYear( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198getYearLong( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198parseExtension( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199stringToAddress( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199stringToDate( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200stringToDateLong( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200stringToVector( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201vectorToString( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201

Chapter 4 Common Templates and Screens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203Common Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203

VII

Services Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204Menu Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204Sign On Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205Sign Off Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205Error Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206Sign On Error Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207

Chapter 5 Billing Center Screens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209Billing Center Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210

Statement Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211Pay Balance Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214Payments Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215

Chapter 6 Search Screens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217Simple Statement Search Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218Advanced Statement Search Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219Statement Search Result Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220

Chapter 7 User Center Screens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223User Center Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223Contacts Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224Billing Address Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225Online Name and Password Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226Contact Information Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227Payment Methods Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228E-Mail Notification Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229Profile Editor Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230Preferences Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231

Chapter 8 Registration Screens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233Primary Contact Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233Account Information Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234Billing Address Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235Payment Method Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236Password and User Login Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237Additional Information Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238

Chapter 9 Currency Converter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241Currency Conversion Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242

VIII iPlanet BillerXpert 4.6 Customization Guide • May 2002

Installation Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242Loader Program for Currency Conversion Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243Database Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244Sample Code and Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246

API Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246To get conversion for a conversion rate as of a past Date: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247

Loading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247As a standalone : . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247Within your code : . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248

1

Preface

This Handbook describes the customizations you can make to BillerXpert.

This Preface discusses the intended audience, the organization of the Handbook,and provides a listing of typographic conventions used in this document. If youspend a few minutes looking through the Preface before reading the rest of theHandbook, you will be able to utilize the Handbook more effectively.

Before You BeginYou need to use this manual if you are changing the user interface for BillerXpertor extending BillerXpert by changing the database schema or adding eventhandlers. When customizing BillerXpert, you also may need to refer to theBillerXpert API and Schema Reference Manual for information about BillerXpert’scomponent business object interfaces and database schemas.

You will also need to have read or have available a book on iPlanet ApplicationServer (iAS). You should read Developing iAS Applications (Java) for generalbackground information about how to use the iAS programming constructs uponwhich BillerXpert has been developed.

AudienceThis manual is written for web site developers and Java programmers who want tomodify the appearance of BillerXpert or its operation. This manual assumes thatyou have experience with HTML and Java and have access to iPlanet ApplicationServer (iAS) documentation.

OrganizationThe book contains nine chapters, as follows:

Documentation Conventions

2 iPlanet BillerXpert 4.6 Customization Guide • April 2002

• Chapter 1, “Introduction to iPlanet BillerXpert Customization”

This chapter discusses the BillerXpert architecture and how to customizeBillerXpert.

• Chapter 2, “Customization Techniques”

This chapter presents a tutorial consisting of exercises that you can follow tolearn how to customize BillerXpert. Even if you do not follow the tutorialstep-by-step, you should skim these sections because they provide conceptualinformation about how to customize BillerXpert.

• Chapter 3, “Common Front-End Classes”

This chapter discusses the common classes used by the BillerXpert front end tomanipulate application business objects.

• Chapter 4, “Common Templates and Screens”

This chapter introduces common templates and shows screens used by severaldifferent AppLogics, all of which may be customized.

• Chapter 5, “Billing Center Screens”

This chapter shows the Billing Center screens that may be customized.

• Chapter 6, “Search Screens”

This chapter shows the Search screens that may be customized.

• Chapter 7, “User Center Screens”

This chapter shows the User Center screens that may be customized.

• Chapter 8, “Registration Screens”

This chapter shows the registration screens that may be customized.

• Chapter 9, “Currency Converter”

This chapter shows the currency converter features that may be customized.

Documentation ConventionsThis document uses the following conventions:

The Document Online

Preface 3

• The monospace font is used for sample code and code listings, ApplicationProgram Interface (API) and language elements (such as method names andproperty names), file names, commands, path names, directory names,Hypertext Markup Language (HTML) tags, and any text that must be typed onthe screen.

• The italic font is used in code to represent placeholder parameters (variables)that should be replaced with an actual value, or items that require emphasis.

• Brackets ([]) are used to enclose optional parameters.

• A slash (/) is used to separate directories in a path. (Windows NT supportsboth the slash and the backslash.)

The Document OnlineFor an overview of iPlanet BillerXpert 4.6 changes, refer to the iPlanet BillerXpert4.6 Release Notes.

An electronic version of these notes are available at:

http://docs.iplanet.com/docs/manuals/

Related DocumentationThe iPlanet BillerXpert 4.6 documentation set includes:

• Release Notes—Contains important information on the current release of iPlanetBillerXpert 4.6. Read this document before working with the new iPlanetBillerXpert 4.6 release.

• Administrator’s Guide—Provides reference information and instructions onadministering a fully-installed iPlanet BillerXpert 4.6 system.

• Installation Guide—Provides guidelines and instructions for installing theiPlanet BillerXpert 4.6 system.

• Integration Guide - Provides guidelines and instructions for integrating theiPlanet BillerXpert 4.6 system with other products.

• API & Schema Reference Guide - Provides API and Schema information for theiPlanet BillerXpert 4.6 system.

Documentation for all iPlanet products can be found at the following web site:

http://docs.iplanet.com/docs/manuals

Product Support

4 iPlanet BillerXpert 4.6 Customization Guide • April 2002

http://docs.iplanet.com/docs/manuals/

Product SupportIf you have problems with your BillerXpert system, contact iPlanet customersupport using one of the following mechanisms:

• iPlanet online support web site at:

http://www.iplanet.com/support/online/

From this location, the CaseTracker and CaseView tools are available forlogging problems.

• The telephone dispatch number associated with your maintenance contract

So that the technical support staff can best assist you in resolving problems, pleasehave the following information available when you contact support:

• Description of the problem, including the situation where the problem occursand its impact on your operation

• Machine type, operating system version, and product version, including anypatches and other software that might be affecting the problem

• Detailed steps on the methods you have used to reproduce the problem

• Any error logs or core dumps

http://docs.iplanet.com/docs/manuals

http://www.iplanet.com/support/online

5

Chapter 1

Introduction to iPlanet BillerXpertCustomization

This chapter discusses the BillerXpert architecture and how to customizeBillerXpert. BillerXpert is implemented as a collection of classes and templates builton the iPlanet Application Server (iAS). You customize BillerXpert by modifyingthe classes and templates to meet the needs of your customers. You may alsoimplement event handlers and component business object classes.

This chapter presents the following topics:

• BillerXpert Architecture

• Customization Strategy

• Front-End Classes and Templates

• Front-End Files and Directories

BillerXpert ArchitectureThe entry point to BillerXpert is the Servlet. A Servlet is a set of programminginstructions that accomplishes a well-defined modular task within an application.In BillerXpert, a Servlet typically takes the following actions:

• validates input from the form

• performs the business logic specified by the request

• fills in a template to respond to the request and sends it to the client

BillerXpert Architecture

6 iPlanet BillerXpert 4.6 Customization Guide • May 2002

An AppLogic creates application business objects to carry out the business logic,which in turn creates component business objects to manipulate data in arepository or communicate with a service. Figure 1-1 shows the BillerXpertarchitecture.

Figure 1-1 Figure 1.1 BillerXpert Architecture

For example, consider the Sign On processing that occurs when a user logs on. Bydefault, BillerXpert displays a form that contains fields for the user name andpassword. When the user submits the form, BillerXpert takes the following actions,which are numbered from 1 to 5 in Figure 1-1.

Servlet

JSP

BillerXpert Architecture

Chapter 1 Introduction to iPlanet BillerXpert Customization 7

1. The Servlet retrieves the user name and password from the form and creates avalidation object that verifies whether these fields are filled in and theconstraints, such as minimum and maximum lengths, were met.

2. The Servlet creates an application business object containing this data withwhich it performs authentication.

3. The application business object creates a component business object; in thiscase, the component business object represents a customer’s profile.

4. The application business object uses the component business object to retrievethe customer’s profile from a data repository; in this case, repository is theDirectory Server.

5. The Servlet uses the data to populate fields in the next form and outputs theHTML to display the form. The Servlet creates a bean, which define the rows ofdata or individual datum to be displayed; in the case of the Sign On Servlet, thedata is simply a bean that contains the verified user name from the datarepository.

If an error occurs, either as a result of validation or during retrieval of thecustomer’s profile, the Servlet outputs HTML that describes the error instead of thenormal processing described in the previous steps.

The previous examples noted the kinds of objects used by BillerXpert, which aresummarized in Table 1-1.

The kinds of objects identified in Table 1-1 are implemented in Java classes. Inaddition to the Java classes, BillerXpert includes HTML-based templates thatdefine the appearance of screens.

Table 1-1 Kinds of Objects

Object Description

Servlet Represents the processing of a request to BillerXpert

validation object Represents the validation logic for input data

application businessobject

Represents the data manipulated by the Servlet and methodsthat operate on the data

component businessobject

Represents data in a data repository and the methods thatcontrol access to the repository

bean object Represents rows of data to be displayed by a Servlettemplate map object Represents name-value pairs of data tobe displayed by a Servlet

Customization Strategy


With the exception of the component business objects, all objects in Table 1-1 arepart of the BillerXpert front end. BillerXpert provides source code for front-endclasses, which are the classes that you can modify. BillerXpert provides classlibraries for component business object classes; however, you can implement yourown component business object classes, as needed.

Customization StrategyBillerXpert follows the iAS Servlet-implementation recommendation of using asingle Servlet for a single purpose, thus keeping each Servlet small and focused ona single task. BillerXpert also separates the validation and data access into separateclasses from the Servlet itself.

You are not required to follow this model; however, object-oriented programminglends itself well to this kind of application structure. For example, if you want touse additional data in application business objects, you can derive your own classto access the data. Likewise, if your form accepts different inputs, you can deriveyour own validation class to verify them.

Front end classes are divided into two kinds, those that are specific to the billpresentment applications for the telephone industry and those that are generallyuseful for any kind of bill presentment application. The later category include theBillerXpert common and core classes.

You can customize BillerXpert front-end in the following ways:

• modify a .jsp file to change the appearance of a screen; this is probably the mostcommon task that you need to perform

• modify a Servlet to change the data that is displayed on a screen; this kind ofcustomization may require changing or replacing bean class, template (.jsp) fiel

• modify a validation class to handle additional input data; this may involveadding additional error codes and messages to the common portion of thefront-end

• modify or create a subclass of an application business class to store and retrievedata from a data repository; a component business object must already be insupport the of data you wish to access

• create a new Servlet to handle additional processing requirements, such asasynchronous events.

Front-End Classes and Templates


If BillerXpert does not provide support for the data that you want to access from adata repository, you can alter the schema to support the new data and implementyour own component business object class to provide access to the data.

Front-End Classes and TemplatesFront-end classes include Servlet classes, core classes from which other front-endclasses are derived or define common objects such as error codes and messages,application business object classes, output classes for placing data in templates,and validating classes. BillerXpert provides source code for all front-end classes.

Front-end classes do not include component business objects classes; source code isnot provided for these classes. For information about component business objectclasses and their APIs, see the BillerXpert API and Schema Reference Guide.

In addition to front-end classes, BillerXpert provides HTML source code that youmodify to change the appearance of the screens that BillerXpert displays. Thefollowing sections identify the front-end classes and HTML templates used byBillerXpert.

Core ClassesCore classes are BillerXpert classes that are derived from correspondingiAS-supplied classes, or they are utility classes that represent objects usedsystem-wide. Table 1-2 shows the common and core classes.

NOTE This version of BillerXpert only provides front-end classes for thetelephone industry.

Table 1-2 Core Classes

Class Description

BXBaseServlet Class from which Servlet classes are derived.

BXBaseView Abstract class from which view classes are derived.

BXConfigObj Represents NTV list entries in configuration files.

BXErrorCode Defines BillerXpert error codes.

BXSession BillerXpert session class.

BXValidateAttribute Represent attributes, such as input fields, which can bevalidated.



ServletsServlet classes implement BillerXpert Servlets. There is one class for each majorfeature supported by BillerXpert. Table 1-3 identifies the classes.

BXValidateView Abstract class from which classes that validate views arederived.

BXValidator Validates BillerXpert data types.

BXBaseBean Base class for BillerXpert to store data. This data is used byJSPs to generate html/

BXTemplateUtil Additional methods to support templates.

Table 1-3 Application Logic Classes

Servlet Description

BXAccountCenterServlet Presents account and service information to the customer.

BXBillDocServlet Displays a statement.

BXBillDocSearchServlet Searches for a statement.

BXBillingCenterServlet Presents billing summaries to the customer.

BXPayHistoryServlet Displays current and completed payments..

BXPaymentServlet Adds or changes payment or auto-payment information.

BXSignOnServlet Logs into online billing system.

BXSignOnCSR Can be used by a CSR to simulate a user signing on.

BXSignOutServlet Logs off of online billing system.

BXSignUpServletL Registers a customer for online billing.

BXUserCenterServlet Changes customer account information.

BXUserPaymentServlet Adds or changes payment method information.

BXUserProfileServlet Changes user profile information.


Class Description



Application Business Object ClassesApplication business objects implement the application logic and manipulatecomponent business objects representing records in the database. Applicationbusiness objects differ from component business objects in that an applicationbusiness object uses one or more component business objects and provides ahigher-level representation of data; for example, an application business objectrepresenting a customer account may combine membership information andbilling information from several different component business objects. Table 1-4shows the application business object classes in BillerXpert.

Table 1-4 Application Business Object Classes

Class Description

BXBillerCustAcctObj Determines information about a customer account.

BXBillerCustAcctUtil Provides utility methods for customer account objects.

BXBillerProfileView Retrieves biller profile information from membership server.

BXBillingActivity Manipulates billing activity information.

BXCustomerProfileView Stores customer profile in LDAP. Used by BSP in Admin.

BXCustomerServiceView Stores customer service options in LDAP. Used by BSP inAdmin.

BXCustomerAcctView Retrieves customer account information from database.

BXFinancialAcctObj Determines information about a financial account.

BXPaymentView Manipulates payment information, including paymentmethods.

BXSearchAttributes Determines information about search criteria.

BXSignUpSession Manipulates information provided by the user during signup.

BXStatementView Retrieves summaries, documents, and document details forstatements.

BXSummaryItem Determines information about a summary.

BXSummaryVector Provides support for vectors of summaries.

BXUserProfileObj Manipulates user profile objects.

BXUserProfileView Allows updates to user profile in LDAP. Used by a biller inAdmin.

BXUserServiceView Allows updates to customer service options in LDAP. Usedby Biller in Admin.



Validation ClassesValidation class objects validate input data from an HTML form on behalf ofServlets. Table 1-5 shows the BillerXpert’s validation classes.

Output ClassesOutput class objects create dynamic data to be displayed in a JSP page. BillerXpertuses JavaBean Objects to hold dynamic data that is displayed by the JSP pages.Table 1-6 shows the JavaBean classes used by BillerXpert.

BXViewUtil Provides utility methods for business objects.

Table 1-5 View and Validation Classes

Class Description

BXValidateAcctView Validates customer account information.

BXValidateAutoPayView Validates automatic payment information.

BXValidateBDSearchB1 Validates search information for California Telecom.

BXValidateBDSearchB2 Validates search information for California Cable.

BXValidateBDSearchB3 Validates search information for California Bank.

BXValidateNewBCAView Validates new BillerXpert account information.

BXValidateNewPaymentView Validates new payment information.

BXValidatePayView Validates payment information.

BXValidatePwdView Validates passwords.

BXValidateSignOnView Validates log-on information.

BXValidateSignUpView Validates registration information.

BXValidateStmtSearchView Validates search information.

Table 1-6 JavaBean Classes

Class Description

BXAccountCenterBeanData

BXAccountCenterBeanMap

Setup dynamic data for the account center JSP page.

Table 1-4 Application Business Object Classes

Class Description



JSP PagesJSP pages create web pages that are displayed in response to a request. Table 1-7shows the JSP pages that are invoked directly by Servlets. These JSP pages mayinvoke other JSP pages, which are not shown in Table 1-7.

BXAutoPayBeanData Setup dynamic data for the automatic payments JSP page.

BXBillDocSearchBeanData

BXBillDocSearchBeanMap

Setup dynamic data for the search JSP page.

BXBillDocBeanMap Setup dynamic data for the billing statement JSP page.

BXBillingCenterBean Setup dynamic data for the billing center JSP page.

BXCustomerAcctBean Setup dynamic data for the customer account information.

BXPayViewBean

BXPaymentViewBeanMap

Setup dynamic data for the payment JSP page.

BXUserCenterBeanMap

BXUserCenterBeanData

Setup dynamic data for the user center JSP page.

Table 1-7 Major JSP Pages

Template Description

add_payment_method.jsp Add payment method JSP page

billing_center.jsp Billing center JSP page

change_profile_confirm.jsp Change profile confirmation JSPpage

error_msg.jsp Error JSP page

index.jsp Sign on JSP page

logout_msg.jsp Sign off message JSP page

new_member-contacts.jsp Contact information JSP page

pay_account-balance.jsp Payment account balance JSPpage

pay_confirm.jsp Payment confirmation JSP page

pay_current-balance.jsp Current balance JSP page

Table 1-6 JavaBean Classes

Class Description

Front-End Files and Directories


Front-End Files and DirectoriesAfter you install BillerXpert, you should set an environment variable, BX_HOME, tothe billXpert directory from the root of the installation. For example, if you create auser to administer BillerXpert and install the software in the administrator’s homedirectory, your BX_HOME environment variable should point to the administrator’s$HOME/billXpert directory.

You can locate the files that you will need to modify in subdirectories of yourBX_HOME directory. Table 1-8 identifies the BX_HOME subdirectories and theircontents.

statement_current-1234.jsp Current statement JSP page

statement_current.jsp Current statement JSP page

statement_search-power.jsp Advanced search JSP page

statement_search-results.jsp Search results JSP page

statement_search.jsp Search JSP page

user_center-add_payment_method.jsp Add payment method JSP page

user_center-change_payment_bankaccount.jsp Change payment bank accountJSP page

user_center-change_payment_cc.jsp Change payment credit card JSPpage

user_center.jsp User center JSP page

NOTE The BX_HOME environment variable is set when you source thebillxpert_env.csh or billxpert_env.sh files.

Table 1-8 Source Subdirectories of BX_HOME

Subdirectory Contents

config BillerXpert configuration files

fe/src/fe makefile for front-end source code and resulting bxfe.zipfile

fe/src/fe/common base and common classes for the BillerXpert front end

Table 1-7 Major JSP Pages




You should also set a NAS_HOME environment variable that points to where iAS isinstalled. It is also set when you source the billxpert_env.csh orbillxpert_env.sh files. Subdirectories contain log files and the files you need tostart and stop iAS Application Server and perform other operations. Table 1-9identifies these subdirectories.

fe/src/fe/user/common front-end definition classes

fe/src/fe/user/view additional front-end classes

fe/src/fetelco makefile for telco-specific source code and resultingbx_fetelco.zip file

fe/src/fetelco/applogic telco-specific Servlets

fe/src/fetelco/view additional classes used by telco-specific Servlets

fe/templates/en/telco telco-specific templates

java destination directory for zip files and containsbillxpert.conf

NOTE When you make changes to source code, you must move the zip filesresulting from recompilation to$NAS_HOME/APPS/billxpert/bxfe/WEB-INF/libBy default the zip files are located in the java subdirectory.

Table 1-9 Subdirectories of NAS_HOME


ias/bin utilities for operating iAS

ias/logs log files containing BillerXpert output

Table 1-8 Source Subdirectories of BX_HOME


17

Chapter 2

Customization Techniques

This chapter presents a tutorial consisting of exercises that you can follow to learnhow to customize BillerXpert. Even if you do not follow the tutorial step-by- step,you should skim these sections because they provide conceptual information abouthow to customize BillerXpert.

This chapter contains the following sections:

• Getting Started

• Modifying makefile Files

• Changing JSP Files

• Displaying Data

• Using Contexts

• Invoking Servlets

• Collecting Input

• Validating Input

• Implementing Servlets

• Implementing an Event Handler

• Changing Database Schemas

• Configuring Table Definitions

• Implementing Component Business Objects

Getting Started


Getting StartedBillerXpert consists of JSPs and Servlets and related classes that you can modify toachieve the presentation and behavior for web-based bill presentment andpayment applications. In the simplest case, you can modify JSPs to change theappearance of bill presentment and modify Servlets to specify the data you want touse.

You are not restricted to simple kinds of customization. For example, you canchange the flow of an application by changing the order in which Servlets areinvoked. You can also add JSPs and Servlets to provide additional behavior.

BillerXpert also provides component business object interfaces to data repositories,such as billing data in an Oracle database or membership data in Directory server.You may use these interfaces to manipulate predetermined kinds of data within anapplication. You can also implement your own interfaces to manipulate additionalkinds of data.

To make the task of populating data repositories easier, BillerXpert provides aprogram for loading XML-encoded data. This tool allows you to define thestructure of data being loaded into BillerXpert. You can modify this program toload data that BillerXpert does not directly support.

The following sections discuss each of these kinds of customization and providesexercises that allow you to experiment with them. Before you start the exercises,you must set up your environment by sourcing billxpert_env.csh if you areusing a c-shell or by executing billxpert_env.sh if you are using a Bourne shell.You will probably want to follow a methodology similar to the following one asyou make changes to Java source files and compile them:

1. Locate the source file in one of the directories identified in Table 1-8.

2. Create a backup copy of your source file before you modify it.

3. Modify the source file and compile it.

4. Change to the directory that contains your zip file and create a backup copy ofthe zip file before you overwrite it with the changed file.

5. Copy the new zip file into the directory.

6. Stop and restart iAS.

These procedures assume that your makefile does not copy zip files. If it does, youshould make a backup copy of your zip file before compiling.

Modifying makefile Files

Chapter 2 Customization Techniques 19

If you are only changing a JSP file, you only need to follow Steps 1 and 2. If youmodify one of the configuration files, you must stop and restart iAS (step 5) inaddition to steps 1 and 2.

These procedures assume that your makefile does not copy zip files. If it does, youshould make a backup copy of your zip file before compiling.

If you are only changing an JSP file, you only need to follow steps 1 and 2. If youmodify one of the configuration files, you must stop and restart iAS (step 5) inaddition to steps 1 and 2.

Modifying makefile FilesThe BillerXpert source is divided into two parts, general-purpose Java classes thatare useful in building any front-end application, and, Java classes that are specificto a telephone company application. Each of these parts has its own makefile file,which you must modify to specify the location of the Java zip files and the locationof the java compiler. The makefile files use environment variables that specify thelocations of iAS and BillerXpert. Table 2-1 shows these environment variables.

Exercise 1In this exercise, you modify the makefile files so that you can compile changes youmake to Java classes.

FilesIn this exercise, you will modify the following makefile files:

Table 2-1 Common environment variables used in makefile files

Variable Contents

BX_HOME directory in which BillerXpert is installed

NAS_HOME directory in which iAS is installed

JAVA_HOME directory in which Java is installed

$BX_HOME/fe/src/fe/makefile front-end java makefile file

$BX_HOME/fe/src/fetelco/makefile telco-specific java makefile file



Tutorial StepsYou will modify the makefile files to specify the correct JAVA_HOME andCLASSPATH variables.

1. Open the $BX_Home/fe/src/fetelco/makefile file and view its contents.

The Contents should look something like this:

JAVA_HOME = /share/builds/components/jdk/1.2.2/SunOS

TELCO_HOME = $(BX_HOME)/fe/src/fetelco

PKGDIR = $(TELCO_HOME)

JAVAC = $(JAVA_HOME)/bin/javac

JAVAH = $(JAVA_HOME)/bin/javah

JAVA_ARCHIVE= $(JAVA_HOME)/bin/jar cvfM0

CLASSPATH = $(JAVA_HOME)/lib/classes.zip:$(NAS_HOME)/classes/java/kfcjdk11.jar:$(BX_HOME)/java/bx_common.zip:$(BX_HOME)/java/bx_be.zip:$(BX_HOME)/java/currconv.zip:$(BX_HOME)/java/bds.zip:$(BX_HOME)/java/bx_loading.zip:$(BX_HOME)/java/bxfe.zip:$(BX_HOME)/java/vbjorb.jar:$(BX_HOME)/java/vbjtools.jar:$(PKGDIR):$(BX_HOME)/java/bx_fetelco.zip:$(NAS_HOME)/classes/java/servlet.jar

ALL :J_SRCS zipall

####################################################

J_SRCS:\

view/BXValidateSignOnView.class \

view/BXValidateSignUpView.class \

view/BXValidateAcctView.class \

view/BXValidatePwdView.class \

view/BXValidateStmtSearchView.class \



view/BXValidatePayView.class \

view/BXValidateAutoPayView.class \

view/BXValidateNewPaymentView.class \

view/BXValidateNewBCAView.class \

view/BXCustomerAcctTemplateData.class \

view/BXBillingCenterTemplateData.class \

view/BXBillDocTemplateMap.class \

view/BXBillDocTemplateData.class \

view/BXPayViewTemplateData.class \

view/BXPaymentViewTemplateMap.class \

view/BXBillDocSearchTemplateMap.class \

view/BXBillDocSearchTemplateData.class \

view/BXUserCenterTemplateMap.class \

view/BXUserCenterTemplateData.class \

view/BXAutoPayTemplateMap.class \

view/BXAutoPayTemplateData.class \

view/BXAccountCenterTemplateMap.class \

view/BXAccountCenterTemplateData.class\

view/BXPayHistoryViewTemplateData.class\

view/IBXBillDetailTemplateData.class\

view/BXBillDetailTemplateDataB1.class\

view/IBXBillDetailView.class\

view/IBXBDSearchAttributes.class\

view/BXBDSearchAttributesB1.class\

view/BXBDSearchAttributesB2.class\

view/BXBDSearchAttributesB2_i.class\

view/IBXBDSearchTemplateData.class\

view/BXBDSearchTemplateMapB1.class\


view/BXBDSearchTemplateMapB2_i.class\

view/IBXBDSearchTemplateData.class\



view/BXBDSearchTemplateDataB1.class\

view/BXBDSearchTemplateDataB2.class\

view/BXBDSearchTemplateDataB2_i.class\

view/BXBDSearchVectorB2.class\

view/BXBillDetailViewB2.class\

view/BXBillDetailTemplateDataB2.class\

view/IBXValidateBDSearchView.class\

view/BXValidateBDSearchViewB1.class\

view/BXValidateBDSearchViewB2.class\

view/IBXBDSearchTemplateMap.class\



view/BXBDSearchTemplateMapB2_i.class\

view/BXBDSearchVectorB1.class\

view/BXBDSearchVectorB2_i.class\

view/BXBillDetailTemplateDataB2_i.class\

view/BXBDSearchAttributesFin.class\

view/BXCreditInfo.class\

view/BXBillDetailTemplateDataFin.class\

view/BXBillDetailViewFin.class\

view/BXBDSearchTemplateDataFin.class\

view/BXBDSearchTemplateMapFin.class\

view/BXValidateBDSearchViewFin.class\

view/BXBDSearchVectorFin.class\

view/BXAddressInfo.class\

view/BXBillingCenterBean.class\

view/BXPayViewBean.class\

view/BXCustomerAcctBean.class\

view/BXBillDocBeanMap.class\

view/BXPayHistoryViewBeanData.class\

view/BXUserCenterBeanData.class\



view/BXBillDocSearchBeanData.class\

view/BXBillDocSearchBeanMap.class\

view/BXAccountCenterBeanData.class\

view/BXAccountCenterBeanMap.class\

view/BXSignUpBeanMap.class\

view/BXDetailCallWrap.class\

view/BXPayScheduleWrap.class\

view/BXPaymentTypeWrapper.class\

view/BXDetailMiscWrap.class\

view/BXDetailCableWrap.class\

view/BXDetailTransactionWrap.class\

view/BXDetailChargesWrap.class\

view/BXPaymentViewBeanMap.class\

applogic/BXSignOnServlet.class \

applogic/BXBillingCenterServlet.class \

applogic/BXPaymentServlet.class \

applogic/BXBillDocServlet.class \

applogic/BXPayHistoryServlet.class \

applogic/BXUserCenterServlet.class \

applogic/BXBillDocSearchServlet.class \

applogic/BXSignOutServlet.class \

applogic/BXUserProfileServlet.class \

applogic/BXAccountCenterServlet.class \

applogic/BXSignUpServlet.class\

applogic/BXSignOnCSRServlet.class\

applogic/BXUserPaymentServlet.class\

applogic/BXPurgingServlet.class\

applogic/BXClickThroughServlet.class



####################################################

.SUFFIXES:

.SUFFIXES: .java .class

.java.class:

$(JAVAC) -classpath $(CLASSPATH) -d $(PKGDIR) $*.java

zipall:

$(JAVA_ARCHIVE) bx_fetelco.zip netscape

2. Change the value of the JAVA_HOME variable to match the location of theJava compiler.

3. Optionally, change the CLASSPATH variable to include zip files that are not inthe $BX_HOME/java subdirectory.

4. Save your changes, then open $BX_HOME/fe/src/fe/makefile.

The contents look something like this:

JAVA_HOME = /share/builds/components/jdk/1.2.2/SunOS

FE_HOME = $(BX_HOME)/fe/src/fe

PKGDIR = $(FE_HOME)

NASJARS = $(NAS_HOME)/../ias/classes/java

JAVAC = $(JAVA_HOME)/bin/javac

JAVAH = $(JAVA_HOME)/bin/javah

JAVA_ARCHIVE= $(JAVA_HOME)/bin/jar cvfM0



CLASSPATH = $(JAVA_HOME)/lib/classes.zip:$(NAS_HOME)/classes/java/kfcjdk11.jar:$(BX_HOME)/java/bx_common.zip:$(BX_HOME)/java/bx_be.zip:$(BX_HOME)/java/vbjorb.jar:$(BX_HOME)/java/vbjtools.jar:$(PKGDIR):$(BX_HOME)/java/bxofx.zip:$(BX_HOME)/java/currconv.zip:$(NASJARS)/activation.jar:$(NASJARS)/mail.jar:$(NASJARS)/javax.jar:$(NASJARS)/servlet.jar

ALL :J_SRCS zipall

####################################################

J_SRCS:\

common/BXSession.class \

common/BXCustAccountView.class \

common/BXErrorCode.class \

common/BXBaseServlet.class \

common/BXBaseView.class \

common/BXConfigObj.class \

common/BXValidateAttribute.class \

common/BXValidateView.class\

common/BXValidator.class\

user/common/BXBillerCustAcctDef.class \

user/common/BXBillerDBDef.class \

user/common/BXBillingALDef.class \

user/common/BXBillingDBDef.class \

user/common/BXMembershipDBDef.class \

user/common/BXPaymentALDef.class\

user/common/BXPaymentDBDef.class\



user/common/BXUtility.class\

user/view/BXUserProfileObj.class\

user/view/BXBillerSignUpSession.class\

user/view/BXViewUtil.class \

user/view/BXBillingActivity.class \

user/view/BXPaymentActivity.class \

user/view/BXMembershipActivity.class\

user/view/BXBillerProfileView.class\

user/view/BXSearchAttributes.class\

user/view/BXSignUpSession.class\

user/view/BXBillerCustAcctUtil.class\

user/view/BXFinancialAcctObj.class\

user/view/BXPaymentView.class \

user/view/BXTemplateUtil.class \

user/view/BXBillerCustAcctObj.class \

user/view/BXCustomerAcctView.class\

user/view/BXTemplateDataBasic.class \

user/view/BXTemplateMapBasic.class \

user/view/BXStatementView.class \

user/view/BXSummaryItem.class \

user/view/BXSummaryVector.class\

user/view/BXDetailItem.class \

user/view/BXDetailItemB2.class \

user/view/BXDetailItemB2_i.class \

user/view/BXDetailItemFin.class \

user/view/BXSearchVector.class \

user/view/BXBaseBean.class \

user/view/BXPayHistoryDetailObj.class \



user/view/BXPayHistoryView.class\

user/view/BXBillerServiceOptionVectors.class\

user/view/BXUserProfileView.class \

user/view/BXUserServiceView.class \

user/view/BXCustServiceView.class \

user/view/BXCustProfileView.class \

user/view/BXUtility.class \

user/view/BXConfigOptionView.class \

user/view/BXTemplateBeanMapBasic.class \

view/BXAutoPayViewData.class \

view/BXNewAutoPayBeanData.class \

view/BXAutoPayBeanData.class \

applogic/BXSendMail.class \

applogic/BXEmailTemplate.class \

applogic/InitBiller.class \

applogic/InitBillerServlet.class \

applogic/BXAutoPayServlet.class \

applogic/BXAPDateCalculateServlet.class \

applogic/BXStatementNotifyServlet.class

####################################################

.SUFFIXES:

.SUFFIXES: .java .class

.java.class:

$(JAVAC) -classpath $(CLASSPATH) -d $(PKGDIR) $*.java

zipall:

Changing JSP Files


$(JAVA_ARCHIVE) bxfe.zip netscape

5. Change the value of the JAVA_HOME variable to match the location of the Javacompiler.

6. Optionally, change the CLASSPATH variable to include zip files that are not inthe $BX_HOME/java subdirectory.

7. Save the file and execute make on each one.

cd $BX_HOME/fe/src/fe

make

cd $BX_HOME/fe/src/fetelco

make

ResultsThe make commands should execute without errors and create the following files:

bx_fetelco.zip

bxfe.zip

Changing JSP FilesOne of the first things you will do when you customize BillerXpert is to modify theappearance of your web pages. You can do this by simply changing the JSP files.After you change a JSP and save it, your change appears as soon as the page isloaded.

BillerXpert’s JSP files contain standard JSP tags which can be modified to suit thedesired look and feel.

NOTE Simply creating a zip file does not register your changes. You mustalso move the new zip file to$NAS_HOME/APPS/billxpert/bxfe/WEB-INF/lib.

NOTE For testing purposes, you may wish to set your browser’s disk andmemory caches to 0 KBytes and force the browser to check thenetwork for each access to avoid having the page loaded from thecache instead of downloaded each time the page is accessed.

Changing JSP Files


Exercise 2In this exercise, you modify the JSP part of the Billing Center template.

FilesIn this exercise, you will modify the following files:

Tutorial StepsYou will change the display at the top of the page from ‘bambam’s CaliforniaTelecom Bills’ to ‘User name: bambam’, where bambam is a customer’s onlinename. Figure 2-1 shows the top of the original Billing Center page.

Figure 2-1 Billing Center page

1. Change your directory to the location of the template files and open thebilling_center.jsp template in an editor.

cd $BX_HOME/fe/templates/en/telco

vi billing_center.jsp

2. Locate the line that contains ‘California Telecom Bills’. The line is in thefollowing table near the top of the file:

NOTE After modifying JSP pages, you will need to copy them to$NAS_HOME/APPS/billxpert/bxfe/<billername>.

Since iAS keeps a compiled version of these files in$NAS_HOME/APPS/billxpert/bxfe/WEB-INF/compiled_JSP/ itwould be necessary to delete the contents of this directory andrestart iAS before you can see the changes.

billing_center.jsp Billing Center Template

Changing JSP Files


<table border="0" width="700" cellpadding="2">

<tr>

<td><img src="telco/images/Logo-square.gif" alt="Logo-square.gif (533 bytes)" WIDTH="64" HEIGHT="64"></td>

<td valign="top" align="left" width="100%"><h2>Billing Center</h2>

<p><%= request.getAttribute("OnlineName") %>'s

<%= request.getAttribute("BillerID") %> Bills</td>

<td valign="middle" align="right"><a href="BXSignOutServlet"><img src="telco/images/logout.gif" alt="logout.gif (1221 bytes)"

border="0" WIDTH="89" HEIGHT="32"></a></td>

</tr>

</table>

3. Change the line to be ‘User name:’ followed by the online name.

<p>User name: <%=request.getAttribute(“onlineName”)%></td>

4. Save your changes and reload the page.

ResultsFigure 2-2 shows the top of the Billing Center page that contains the changed text.

Figure 2-2 Modified Billing Center page

Displaying Data


Displaying DataBillerXpert uses standard JavaBean components to carry dynamic data from theservlets to the JSP pages, where the data is displayed. These JavaBeans areinstantiated in the Servlets, and populated with the values that need to bedisplayed. The servlet then saves a reference to this Bean Object as a requestAttribute. The request is the forwarded to the JSP page. The JSP page retrives theBean from the Request Attriubute, and uses methods defined in the Bean to get thedata that is to be displayed. For example in the file BXBillingCenterServlet.java:

BXCustomerAcctBean acctData = new BXCustomerAcctBean();

acctData.setAccounts(accts);

acctData.setSelectedAccount(bca);

acctData.setMonSelected(numMon);

...

req.setAttribute("bca",acctData);

The request is forwarded to billing_center.jsp:

<% netscape.billxpert.fe.telco.BXCustomerAcctBean bxCustomerAcctBean =

(netscape.billxpert.fe.telco.BXCustomerAcctBean)request.getAttribute("bca"); %>

<select name="numberMonth" size="1">

<% int i = bxCustomerAcctBean.getMonSelected();

int numMonths = bxCustomerAcctBean.getNumMonthDisplay();

for (int ctr=1;ctr<=numMonths;ctr++) {

%>

<option <%= (ctr ==i)?"selected" : "" %> > <%= ctr %> </option>

<%}%>

</select>

Displaying Data


Exercise 3In this exercise, you modify the Billing Center Servlet to set additional data fordisplay and modify the BillingCenter template to display the data.

FilesIn this exercise you will modify the following files:

Tutorial StepsYou will change the display near the top of the page from Welcome bambam ... toGood evening bambam ... , where Good evening is the string based on the timeof day and bambam is a customer's first name. Figure 2-3 shows the top of theoriginal Billing Center page.

Figure 2-3 Billing Center page

1. First, modify the Bean class to have 2 more properties, called Greeting andFirstName respectively.

Locate the BXBillingCenterBean.java file in$BX_HOME/fe/src/fetelco/view directory. Open it in a text editor and addthe following lines to the BXBillingCenterBean class:

private String greeting = null;

private String firstName = null;

// setter Methods

void setGreeting(String greeting){

this.greeting = greeting;

BXBillingCenterServlet.java

BXBillingCenterBean.java

billing_center.jsp

Displaying Data


}

void setFirstName(String fname){

firstName = fname;

}

// getter methods

String getGreeting(){

return greeting;

}

String getFirstName(){

return firstName;

}

2. Modify the BXBillingCenterServlet.java file to populate these propertieswith correct values. Open the BXBillingCenterServlet.java file from the$BX_HOME/fe/src/fetelco/applogic directory in a text editor.

Navigate to the method called private void displayView(int numMon,

String bca, int sortField) and go to the end of the method. Add thefollowing lines before the req.setAttribute("Statement",data):

data.setFirstName(session.getFirstName());

Calendar calendar = Calendar.getInstance();

if (calendar.get(Calendar.HOUR_OF_DAY) < 12)

data.setGreeting("Good morning ");

else if (calendar.get(Calendar.HOUR_OF_DAY) < 18)

data.setGreeting("Good afternoon ");

else

data.setGreeting("Good evening ");

3. Save your changes, change to the front-end directory and recompile:


make

copy the csxfe.zip file to $NAS_HOME/APPS/billxpert/bxfe/WEB-INF/lib

Displaying Data


4. Modify the billing_center.jsp file in$BX_HOME/fe/templates/en/telcoModel to display the newly included beanproperties:

Open the billing_center.jsp file in a text editor.

Locate the line that contains "Welcome":

<td width="50%" valign="top"><span class="welcome">Welcome <%= request.getAttribute("OnlineName") %> ...</span><br>

Replace it with the following lines:

<td width="50%" valign="top"><span class="welcome"><%= bxBillingCenterBean.getGreeting()%>

<%= bxBillingCenterBean.getFirstName()%> ...</span><br>

Locate the following line:

netscape.billxpert.fe.telco.BXBillingCenterBean bxBillingCenterBean =

(netscape.billxpert.fe.telco.BXBillingCenterBean)request.getAttribute("Statement");

Shift this line from the original location to the the place just before the line youchanged above.

Make sure to put the line enclosed in <% %> like,

<%

netscape.billxpert.fe.telco.BXBillingCenterBean bxBillingCenterBean =

(netscape.billxpert.fe.telco.BXBillingCenterBean)request.getAttribute("Statement");

%>

5. Locate a string "TEMPLATE_BASE" in the jsp page and replace it with the"telco".

NOTE This is to make sure that Bean is instantiated before any method iscalled on it.

Using Contexts


6. Save your changes.

Copy the billing_center.jsp file to$NAS_HOME/APPS/billxpert/bxfe/telco.

Delete the contents of the$NAS_HOME/APPS/billxpert/bxfe/WEB-INF/compiled_jsp directory.

7. Restart iAS

Change to the bin subdirectory of the directory in which iAS is installed andissue the following commands:

cd $NAS_HOME/bin

KIVAes.sh stop

KIVAes.sh start

Figure 2-4 <Modified Billing Center page

Using ContextsBillerXpert provides contexts that use the Servlet’s IContext object. This objectprovides access to iAS services. In addition to managing the Servlet’s IContextobject, BillerXpert contexts provide database access, transaction management,status information, and the ability to write to the log file.

One of the first operations that a Servlet must perform is to initialize its context. Forexample, a Servlet that only accesses membership data needs only to create amembership context object. BillerXpert provides an init() method in itsBXBaseServlet class, from which BillerXpert Servlets descend, that creates contextobjects based on the context constant that you provide as an argument to themethod. Table 2-2 identifies the context constants.

Table 2-2 BillerXpert contexts

Context Constant Creates Object Referenced By Description

BILLING_CONTEXT BXBillingContext billingContext Billing context

Using Contexts


If you do not provide an argument to the init() method, the method creates allcontexts.

Exercise 4In this exercise, you change the Sign On Servlet to use both the billing andmembership contexts rather than just the membership context. In the next exerciseyou use this change to allow both billing and membership data to be accessedinstead of just membership data.


Tutorial StepsYou change the way the init() method is called to create all contexts and you willcreate BXCustomerAcctView objects using both the membership and billingcontexts.

1. Change your directory to the location of the Servlet files and open theBXSignOnServlet.java file in an editor.

cd $BX_HOME/fe/src/fetelco/applogic

vi BXSignOnServlet.java

2. Locate the call to the init() method from the doPost() method.

public void doPost(.....)

{

MEMBERSHIP_CONTEXT BXMembershipContext membershipContext Membership context

PAYMENT_CONTEXT BXPaymentContext paymentContext Payment context

CONFIG_CONTEXT BXConfigContex configContext Configuration context

ALL_CONTEXT all of the above — All contexts

BXSignOnServlet.java Sign On Servlet

Table 2-2 BillerXpert contexts

Context Constant Creates Object Referenced By Description

Using Contexts


if (!init(MEMBERSHIP_CONTEXT)) {

return displayErrorMsg(ERRMSG_TEMPLATE);

}

...

3. Change the call to the init() method to initialize all contexts.

if (!init()) {

4. Locate the line that creates a BXCustomerAcctView object in theverifyLogin() method.l

public boolean verifyLogin(String Username, String Password)

{

try {

ca = new BXCustomerAcctView(membershipContext, status);

}

catch (Exception e) {

e.printStackTrace();

return false;

}

return ca.authenticate(Username, Password);

}

5. Change the constructor invocation to use both the membership and billingcontexts.

ca =new BXCustomerAcctView

(membershipContext,billingContext,status);

6. Locate the line that creates a BXCustomerAcctView object in the

createSession() method.

public boolean createSession(String OnlineName, String Password)

{

...

if (ca == null) {

try (

ca = new BXCustomerAcctView(membershipContext, status);

Invoking Servlets


}


return false;

}

}

return ca.saveUserProfile(session, OnlineName);

}

7. Change the constructor invocation to use both the membership and billingcontexts.

ca =new BXCustomerAcctView

(membershipContext,billingContext,status);


You can compile your changes at this point, or you may wait and do this as part ofthe next exercise.

Invoking ServletsA Servlet can be invoked from a JSP or another Servlet. The basic flow of executionin BillerXpert is from the index.html template to the Sign On Servlet. When theSign On Servlet authenticates the login, it invokes another JSP which invokes theBilling Center JSP. The Billing Center JSP contains a menu, whose items invokeother Servlets.

Some Servlets require additional information when they are invoked. For example,the Payment Servlet, BXPaymentServlet, requires a command when it is invokedthat controls the behavior of the Servlet. For example, the menu item for Paymentpasses a value of ‘view’ for the cmd parameter:

<td width="90%" nowrap checked="false">

<a href="/BXPaymentServlet?cmd=view">

Pay Balance</a></td>

The Servlet can then make use of the value to control its behavior. For example, thePayment Servlet uses the cmd key name to determine whether to display payments(cmd=view), pay a balance, or invoke the Billing Center Servlet.

Invoking Servlets


In BillerXpert, the most common way to invoke a Servlet is from a form. Thefollowing form is defined in the pay_account-balance.jsp template. The valueof the field named cmd is set to either ‘Cancel’ or ‘Make Payment’ depending onwhich button causes the form to be submitted:

<form method="POST" name="form"action="BXPaymentServlet">...<td align="right"><input type="submit" value="Cancel" name="cmd" width="84"><strong><input type="submit" value="Make Payment" name="cmd" width="84"></strong></td>...

Input to a Servlet, whether it is explicitly passed as part of the Servlet’s invocation,submitted with a form, or part of the form’s data is available to the Servlet inside aHttpServletRequest Object. You can retrieve the value associated with a key fromthis HttpServletRequest Object object by calling the list’s getParameters()method and specifying the key whose value you want to retrieve. CodeExample 2-1 shows the retrieval of the value associated with cmd.

Code Example 2-1 The Payment Servlet’s doPost() method

public void doPost(HttpServletRequest req, HttpServletResponse resp) throws ServletException, java.io.IOException

{ init(req,resp); String billerId = getBXSession().getBillerId();

.... if (!verifyUserSession()) { displayTemplate(SIGNON_PAGE);

return; }

....

status.setBillerId((getBXSession()).getBillerId());

String request = req.getParameter("cmd");...

}

Invoking Servlets


Exercise 5In this exercise, you set up a pull-down menu on the Sign On page that allows theuser to select starting points in addition to the Billing Center. Because BillerXpertassumes that all users will go to the Billing Center first, BillerXpert createsbilling-related objects in the Billing Center Servlet. This exercise requires you toadd code to create billing objects in the Sign On Servlet because the user can nowbypass the Billing Center, thus the Billing Center Servlet is not guaranteed toexecute immediately after the Sign On Servlet.


Tutorial StepsYou will add a drop-down menu on the Sign On page and invoke a Servlet basedon the user’s selection.

1. Change your directory to the location of the template files and open theindex.html template in an editor.


vi new_index.html

2. Locate the OnlineName and Password input fields.

<table border="0" width="600" cellpadding="0" cellspacing="0">

...

<tr>

<td width="50%" align="right" nowrap>Online Name:</td>

<td width="50%">

<input name="OnlineName" size="8" value=""></td>

</tr>

<tr>

<td width="50%" align="right" nowrap>Password:</td>

<td width="50%"><input name="Password"

size="8" value="" type="password"></td>

new_index.html Sign On template

BXSignOnServlet.java Sign On Servlet

Invoking Servlets


</tr>

3. Add your drop-down menu immediately after the password row.

The menu consists of six items whose values are strings containing a digit from‘1’ to ‘6.’. The selected menu item is returned in the selectTask field.

<td width="50%"><input name="Password" size="8"

value="" type="password"></td>

</tr>

<tr>

<td width="30%" align="right" nowrap>Selection:</td>

<td>

<select name="selectTask" size="1">

<option value="1" selected>Billing Center</option>

<option value="2">View Current Statements</option>

<option value="3">View Payments</option>

<option value="4">Pay Balance</option>

<option value="5">Search</option>

<option value="6">User Center</option>

</select>

</td>

</tr>

4. Change your directory to the location of the Servlet files and open theBXSignOnServlet.java file in an editor.


vi BXSignOnServlet.java

5. Locate createSession() method, which creates a new session object and setsup the membership data.

public boolean createSession

(String OnlineName, String Password)

{

// always create a new BXSession when user logs in

BXSession session = createBXSession(OnlineName);

Invoking Servlets


if (session == null) {

status.push(BXStatus.STATUS_ERROR,

BXErrorCode.SESSION_CREATE_FAILED);

return false;

}

if (ca == null) {

try {

// constructor to BXCustomerAcctView changed in previous

// exercise

ca = new BXCustomerAcctView

(membershipContext, billingContext, status);

}


return false;

}

}


}

6. Add the code to create the billing session data before the code to save themembership data in the user profile.

BillerXpert Servlets that display billing data require the selected account and alist of all customer account numbers (BCA account numbers) to be set in thesession object. There must be at least one account per customer. The firstcustomer account number in the list must be the selected account. If a customerhas only one account, the list contains that account number twice; the first timerepresents the selected account and the second time represents the onlyaccount in the list of potential accounts. If no account is selected, the firstaccount number in the list is an empty string.

...

if (!setupBCAs(session, OnlineName)) return false;


Invoking Servlets


// original line

}

public boolean setupBCAs

(BXSession session, String OnlineName)

{

billingContext.log (billingContext.INFO,

"Retrieving BCAs");

Vector bcAccts = null;

try {

bcAccts = ca.getAllBCAs(OnlineName);

}



return false;

}

Vector acctNums = new Vector();

String acctNo = "";

int numAccts = bcAccts.size();

switch (numAccts) {

case 0: {

billingContext.log (billingContext.ERROR,

"No BCAs for " + OnlineName);

return false;

}

case 1:

acctNums.addElement(((IBXBillerCustAcct)

bcAccts.elementAt(0)).getAccountNumber());

break;

default:

Invoking Servlets


acctNums.addElement("");

}

for (int i=0; i<numAccts; i++) {

acctNo = ((IBXBillerCustAcct)

bcAccts.elementAt(i)).getAccountNumber();

acctNums.addElement(acctNo);

}

String selAcct = (String) acctNums.elementAt(0);

session.setSelectedAccount(selAcct);

session.setBCAs(acctNums);

return true;

}

7. Locate the import statements for netscape packages at the top of the file.

import netscape.billxpert.user.*;

import netscape.billxpert.core.*;

import netscape.billxpert.ejb.*;

import netscape.billxpert.common.*;

8. Add the import statement for the ejb.billing package.

This package contains the billing classes and is required because theIBXBillerCustAcct objects are now accessed by this Servlet.

import netscape.billxpert.ejb.billing.*;

9. Locate the call to the displayTemplate() method that displays the BillingCenter page at the end of the doPost() method.

...

//

// Save login criteria into the session.

//

if (!createSession(OnlineName, Password)) {

displayErrorMsg(ERRMSG_TEMPLATE);

}

Invoking Servlets


displayTemplate(WAIT_PAGE);

}

10. Add the code to dispatch a Servlet depending on the value returned in theselectTask field.

In some cases, the Servlet requires a value to be passed to it via the cmd field.These values are added to the valIn list that the Servlet can access as soon asthe Servlet’s doPost() method starts to execute.

...

if (!createSession(OnlineName, Password)) {


}

int selectTask = Integer.parseInt(req.getParameter(SELECTION));

if (dispatchTask(selectTask) != SUCCESS)


}

...

public int dispatchTask(int taskNum)

{

switch (taskNum)

{

case BILL_CTR:

{


return SUCCESS;

}

case CUR_STMT:

{

return handleNewRequest("BXBillDocServlet");

}

Invoking Servlets


case PYMTS:

{

return handleNewRequest("BXPayHistoryServlet?cmd=BXPaymentALDef.VIEW_HISTORY");

}

case PAY_BAL:

{

return handleNewRequest("BXPaymentServlet?cmd=BXPaymentALDef.VIEW_PAY");

}

case SEARCH:

{

return handleNewRequest("BXBillDocSearchServlet?cmd=simple");

}

case USER_CTR:

{

return handleNewRequest("BXUserCenterServlet");

}

}

return -1;

}

private int handleNewRequest (String path)

{

RequestDispatcher rd = getServletContext().getRequestDispatcher("/" + path);

rd.forward(req, res);

return SUCCESS;

}

Invoking Servlets


...

private static final String SELECTION = "selectTask";

private static final int BILL_CTR = 1;

private static final int CUR_STMT = 2;

private static final int PYMTS = 3;

private static final int PAY_BAL = 4;

private static final int SEARCH= 5;

private static final int USER_CTR = 6;

private static final int SUCCESS = 10;

private static final String ERRMSG_TEMPLATE_ ="/signon_msg.jsp";

private static final String WAIT_PAGE_ ="/auth_summary.jsp";

11. Save your changes, change to the telco front-end directory and recompile


make

12. Copy the bx_fetelco.zip file to BillerXpert’s java subdirectory.

cp bx_fetelco.zip $BX_HOME/java/bx_fetelco.zip

13. Restart iAS.

14. Change to the bin subdirectory of the directory in which iAS is installed andissue the following commands:

cd $NAS_HOME/bin

KIVAes.sh stop

KIVAes.sh start

ResultsYou must log into BillerXpert after restarting the server. Figure 2-5 shows the SignOn page that contains the drop down menu; the menu items take you to thecorresponding BillerXpert page.

Collecting Input


Figure 2-5 Modified Sign On page

Collecting InputWhen you customize BillerXpert, you often need to collect additional informationand store it for later use. You collect this information by setting up input fields informs, saving it as part of the session data, and making the data persistent.

For example, the following HTML input tag creates an input field named‘PasswordHint’ and populates it with the value specified by the request parameter‘PasswordHint’:

<input name="PasswordHint" size="20" maxlength="24" value="<%request.getAttributes"PasswordHint”)%>

You set up the GX tag in the same way as you do for displaying other data. See“Displaying Data” for more information.

Once the data in the form has been submitted, the responding Servlet canmanipulate it. Typically, the Servlet stores the data in the session object and alsowrites it to a data repository. It is not necessary to carry all information in thesession object; the more data in the session object, the longer it takes to pass thedata to a Servlet when it is invoked.

Collecting Input


BillerXpert creates a BXSession object that maintains session data in the Sign OnServlet. Calls to accessor methods for the OnlineName field are shown in CodeExample 2-2. You can modify the BXSession class to add your own accessormethods to this class to get and set the value of your input data.

Code Example 2-2 Accessor methods for the OnlineName field

public void setOnlineName(String val){(true);OnlineName=val;}

public String getOnlineName()( return OnlineName;}

Saving session data does not make the data persistent after the session ends. If youchanged session data, you must store it in the database either by explicitly callingcomponent business object interface methods or by using application businessobjects.

BillerXpert provides several application business classes that you can use tomanipulate membership and billing data. For example, the BXCustomerAcctView

class provides methods to manipulate membership and billing data related to acustomer’s account. The BXCustomerAcctView class uses a BXUserProfileObj

helper object to manipulate the customer profile membership data.

To save membership data, you create a BXCustomerAcctView object then call theBXUserProfileObj.set() method to copy the contents of relevant fields from thesession object to the BXCustomerAcctView object. You call theBXCustomerAcctView object’s getUserProfile() method to retrieveIBXCustomerProfile object containing the membership data. You then can setadditional fields in the IBXCustomerProfile object. After setting the additionalfields, you call the BXCustomerAcctView object’s updateUserProfile() methodto store the contents of the changed IBXCustomerProfile object in the database.

NOTE You must call the session object’s saveSession() method beforeevaluating a template, for example by calling displayTemplate()

or displayError(), or invoking another Servlet; otherwise,changes to the session data are not available to the next Servlet thatexecutes.

Collecting Input


The BXUserProfileObj class manipulates only fields thar are explicitly specified.You must modify the BXUserProfileObj.set() method as well as the save() andread() methods to specify additional fields. The save() method copies the datafrom a customer profile object and saves it in the session object. The read()method creates a customer profile component business object. and instantiates thecustomer profile object’s data from the session object. These methods are calledfrom methods in the BXCustomerAcctView class.

Exercise 6In this exercise, you add a field in the Edit Password jsp file to collect a passwordhint, modify the User Center Servlet to populate the field and modify the UserProfile Servlet to handle changes to the field. Because the password hint field onlyexists in the Directory Server data repository and not in BillerXpert’s front-end,you will need to make the hint available from the session object and modify thefront end’s user profile object to retrieve the field and store it in the repository.


Tutorial StepsYou will modify the User Center - Edit Password jsp file to collect and display thecontents of the password hint field in the Directory Server repository. Next, youwill modify the BXSession and BXUserProfileObj classes to retrieve and store thepassword hint. Finally, you will populate the template with the contents of thefield in the User Center Servlet and process changes to the field in the User profileServlet.

1. Change your directory to the location of the template files and open theuser_center-editor-password.jsp template in an editor.


vi user_center-editor-password.jsp

user_center-editor-password.jsp User Center - EditPassword template

BXSession.java Session class

BXUserProfileObj.java User profile class

BXUserCenterServlet.java User Center Servlet

BXUserProfileServlet.java User Profile Servlet

Collecting Input


2. Locate the Repeat Password input field.

<tr>

<td align="right" width="33%">Repeat Password</td>

<td width="66%"><input type="password" name="Password2"

size="20" maxlength="24"></td>

</tr>

3. Add your Password Hint field immediately after the repeat password row.

<tr>

<td align="right" width="33%">Password Hint</td>

<td width="66%"><input name="PasswordHint" size="20"

maxlength="24" value="<%RequestGetAttributes”PasswordHint”%>

</td>

</tr>

4. Locate the submit and close buttons.

<p><input type="submit" name="RequestAction"

value="Change Password" width="84">

<input type="button" value="Done" name="done"

onclick="window.close();return false" width="84"></p>

5. Rename the ‘Change Password’ button to ‘Change All’ and add a ‘ChangeHint’ button.

<p><input type="submit" name="RequestAction"

value="Change All" width="84">

<input type="submit" name="RequestAction"

value="Change Hint" width="84">

<input type="button" value="Done" name="done"

onclick="window.close();return false" width="84"></p>

6. Save the file and change your directory to the location of the commonfront-end class files. Open the BXSession.java file in an editor.

cd $BX_HOME/fe/src/fe/common

vi BXSession.java

Collecting Input


7. Add member variable String passwordHint;

Add a getPasswordHint() method.

The getPasswordHint() method retrieves the session data whose key is‘PasswordHint’.

public String getPasswordHint(){ return PasswordHint;}

8. Add a setPasswordHint() method.

The setPasswordHint() method sets the session data whose key is‘PasswordHint’ and sets a flag to indicate that the data has changed.

public void setPasswordHint(String val){passwordHint=val;}

9. Save the file and change your directory to the location of the commonfront-end view class files. Open the BXUserProfileObj.java file in an editor.

cd $BX_HOME/fe/src/fe/user/view

vi BXUserProfileObj.java

10. Locate the save() method.

The save() method copies the data from a customer profile object and saves itin the session object.

public static void save(IBXCustomerProfile custProfile,

BXSession session)

{

session.setUserID(custProfile.getPrimaryKey());

session.setAccount(custProfile.getAccount())

...

session.setPassword(custProfile.getPassword());

...

session.saveSession();

Collecting Input


}

11. Add a line after the password line that saves the password hint in the sessionobject.

...

session.setPassword(custProfile.getPassword());

session.setPasswordHint(custProfile.getPasswordHint());

...

session.saveSession();

}

12. Locate the read() method.

The read() method creates a customer profile component business object. andinstantiates the customer profile object’s data from the session object.

public static IBXCustomerProfile read(BXStatus status,

BXSession session) throws Exception

{

IBXCustomerProfile custProfile = null;

try {

custProfile = (IBXCustomerProfile)

BXMembershipMgr.createCustomerProfile(null);

custProfile.setPrimaryKey(session.getUserID());

custProfile.setAccount(session.getAccount());

...

custProfile.setPassword(session.getPassword());

...

}


status.push( BXStatus.STATUS_ERROR,

BXErrorCode.DB_MEMBERMGR_ERROR);

throw e;

}

Collecting Input


return custProfile;

}

13. Add a line after the password line that sets the password hint in the customerprofile object.

...custProfile.setPassword(session.getPassword());

custProfile.setPasswordHint(session.getPasswordHint());

...

14. Locate the set() method.

The set() method sets the customer profile object’s data from the sessionobject.

public static void set(IBXCustomerProfile custProfile,

BXStatus status, BXSession session) throws Exception

{

custProfile.setPrimaryKey(session.getUserID());

custProfile.setAccount(session.getAccount());

...


...

}

15. Add a line after the password line that sets the password hint in the customerprofile object.

...


custProfile.setPasswordHint(session.getPasswordHint());

...

16. Save the file and change your directory to the location of the commonfront-end makefile file. Compile the common front-end files.


make

17. Copy the bxfe.zip file to BillerXpert’s java subdirectory.

cp bxfe.zip $BX_HOME/java/bxfe.zip

Collecting Input


18. Change your directory to the location of the Servlet files and open theBXUserCenterServlet.java file in an editor.


vi BXUserCenterServlet.java

19. Locate processChangeUserProfile() method, which populates the templatevalues used by User Center editors.

protected void processChangeUserProfile(String dispTemplate, int colorID)

{

BXSession session = getBXSession();

try {

IBXCustomerProfile custProfile = BXUserProfileObj.read(status, session);

BXUserCenterBeanMap map = new BXUserCenterBeanMap(req, custProfile);

map.setColor(colorID);

BXUserCenterBeanData data = new BXUserCenterBeanData(custProfile);

if ((colorID == PROFILE_ID) || (colorID == PREFERENCES_ID)) {

createBXConfigContext();

BXConfigOptionView optionView = new BXConfigOptionView(configContext, status);

Hashtable options = optionView.getAllProfileOptions(session.getBillerId());

data.setProfileOptions(options);

}

logActivity("CHANGE_USER_INFO", BXActivities.getActivityMessage("BXFE_00203.user_center"),

null, null, null);

req.setAttribute("beanMap",map);

Collecting Input


req.setAttribute("beanData",data);

displayTemplate(dispTemplate);

return;

}


Logger.logError(context, getBXSession().getUserID(), getBXSession().getBillerId(),

"UI_0038", "2", BXActivities.getActivityMessage("BXFE_00003.user_center"),

getBXSession().getEmulationID());


return;

}

}

20. Add the code to add the password hint to the template map before the page isdisplayed.

...

req.setAttribute("PasswordHint", session.getPasswordHint());

displayTemplate(dispTemplate);

}

21. Open the BXUserProfileServlet.java file in an editor.

vi BXUserProfileServlet.java

22. Locate the static strings at the end of the file. Change the CHANGE_PWD string to‘Change All’ to match the value returned. Add a new string,

CHANGE_HINT, for the ‘Change Hint’ button.

public static final String CHANGE_PWD = "Change All";

public static final String CHANGE_HINT = "Change Hint";

23. Locate the dispatch() method, which determines which section of the UserCenter was chosen.

protected void dispatch(String request)

{

if (request == null) {

Collecting Input



BXErrorCode.Servlet_INVALID_REQUEST);

}

BXValidateSignUpView validateView =

new BXValidateSignUpView(status, valIn);

if (!validateView.validate()) (


}

if (request.equals(BXUserProfileServlet.SAVE_CONTACTS)) {

saveContacts();

...

else if (request.equals(BXUserProfileServlet.CHANGE_PWD)) {

changePassword();

}

...

else {


BXErrorCode.AL_INVALID_REQUEST);

}


}

24. Bypass validation checking on the password and user name if the user ischanging the password hint.

if (!request.equals(BXUserProfileAL.CHANGE_HINT)) {

BXValidateSignUpView validateView =

new BXValidateSignUpView(status, valIn);

NOTE Validation of the user name and password is unnecessary in thiscase; for information about validation, see “Validating Input”.

Collecting Input


if (!validateView.validate()) {


}

}

25. Add a block that calls a new method, changeHint() that executes when theuser selects ‘Change Hint’.

...

else if (request.equals(BXUserProfileServlet.CHANGE_PWD)) {

changePassword();

}

else if (request.equals(BXUserProfileServlet.CHANGE_HINT)) {

changeHint();

}

...

26. Add a method, changeHint() method that executes when the user selects‘Change Hint’.

All methods that add a value to the membership database retrieve the value tochange from the valIn list and create a customer account view object. Thecustomer account view is used to retrieve and update the field in the databasewith the new value. The value is also saved in the session object.

private void changeHint()

{


String hint = req.getparamter("PasswordHint");

try {

BXCustomerAcctView ca = new

BXCustomerAcctView(membershipContext, status);

IBXCustomerProfile custProfile =

getCustomerProfile(session, ca);

custProfile.setPasswordHint(hint);

ca.updateUserProfile(custProfile);

Collecting Input


// save new data in the session object

session.setPasswordHint(hint);

displayConfirmTemplate();

}




}

}

27. Locate the changePassword() method that executes when the user selects‘Change All’ and add the code to save the password hint.

The code to add is shown in bold. It is very similar to the code you need to addto the changeHint() method in Step 26.

private int changePassword()

{

BXValidatePwdView pwdView = new BXValidatePwdView(status, valIn);

if (!pwdView.validate()) {


}

try {

BXCustomerAcctView ca = new BXCustomerAcctView(membershipContext, status);


String pwd1 = req.getParamter(CP_PASSWORD1);

String hint = req.getParameter("PasswordHint");

//ca.changePassword(session.getOnlineName(), pwd1.trim(), session.getBillerId() );

Collecting Input


logActivity("CHANGE_PASSWORD", BXActivities.getActivityMessage("BXFE_0

0208.user_center"), null, null, null);

IBXCustomerProfile custProfile = getCustomerProfile(session,ca);

custProfile.setPasswordHint(hint);

ca.updateUserProfile(custProfile);

// Must update password after storing customer profile.

custProfile.updatePassword(session.getOnlineName(), pwd1.trim());

// save new data in the session object

session.setPasswordHint(hint);

displayConfirmTemplate();

}


Logger.logError(context, getBXSession().getUserID(), getBXSession().ge

tBillerId(), "UI_0046", "2",

BXActivities.getActivityMessage("BXFE_00035.user

_center"), getBXSession().getEmulationID());


}

}

28. Save your changes, change to the telco front-end directory and recompile.


make


Validating Input



30. Restart iAS.


cd $NAS_HOME/bin

KIVAes.sh stop

KIVAes.sh start

ResultsYou must log into BillerXpert after restarting the server. Figure 2-6 shows the UserCenter - Edit Password page that contains the password hint field. When youchange the password hint, it should persist after you log out and log back intoBillerXpert.

Figure 2-6 Modified User Profile - Edit Password page

Validating InputTo validate input, you must create a validation class and define codes andmessages for the kinds of errors that you want to detect. Typically, you will modifythe error codes first and then use them in your validation class.

The BXErrorCode class contains strings that define all error codes used by theBillerXpert front-end. Each error code has a corresponding message in the$BX_HOME/config/messages.conf configuration file. For example, theBXErrorCode class contains the code ‘BXFE_001005’ which is represented by thestring ‘USER_NOT_FOUND’, as follows:

Validating Input


public final static String USER_NOT_FOUND = "BXFE_001005";

The corresponding message in the messages.conf file is ‘User not found!’, asfollows:

"BXFE_001005" Str "User not found!",

You add an error code to the BXErrorCode class and a corresponding message inthe messages.conf file whenever you define a new kind of error.

ImportantYou must take great care with punctuation when modifying the messages.conffile; otherwise, error messages will not display correctly. BillerXpert displays themessage ‘Unknown Error’ when the format of this file is incorrect.

Your validation class is a subclass of the BXValidateView class, in which you mustprovide two methods, validate() and setError(). You call the validate() method from the Servlet receiving the input to perform the validation. If an erroroccurs, the validate() method calls the setError() method to set the error code.Code Example 2-3 shows the validate() and setError() methods of theBXValidateSignOnView class.

Code Example 2-3 The validate() and setError() methods of theBXValidateSignOnView class

public boolean validate()

{ boolean isValid = BXValidator.validate(elements, this);

if (!isValid) { setError(); }

return isValid;}

protected void setError(){ if (status == null) { return; }

String errCode = BXErrorCode.VALIDATE_UNKNOWN;

if (getNumErrors() > 0) { String key = errorList.getNextKey();

Validating Input


int rc = errorList.getValInt(key);

switch (rc) {

case ACValidateError.ERROR_REQUIRED:

if (key.equals(ONLINE_NAME)) {

errCode = BXErrorCode.ONLINENAME_MISSING;

}

else if (key.equals(PASSWORD)) {

errCode = BXErrorCode.PASSWORD_MISSING;

}

break;

default:

if (key.equals(ONLINE_NAME)) {

errCode = BXErrorCode.ONLINENAME_INVALID;

}

else if (key.equals(PASSWORD)) {

errCode = BXErrorCode.PASSWORD_INVALID;

}

}

}

status.push(BXStatus.STATUS_ERROR, errCode);

}

In this example, the validate() method calls the BXValidator.validate()method to validate the fields, then calls the setError() method to determinewhether an error occurred. You can add additional validation to the validate()method.

The elements in the list to be validated by the BXValidator.validate() methodmust be BXValidateAttribute objects. The Sign On Servlet defines two of them asfollows:

Validating Input


Vector list = new Vector(2);list.addElement(new BXValidateAttribute(ONLINE_NAME, BXValidator.BX_TYPE_STRING, "", true, oMinLength, oMaxLength));list.addElement(new BXValidateAttribute(PASSWORD, BXValidator.BX_TYPE_STRING, "", true, pMinLength, pMaxLength));

When you create your BXValidateAttribute objects, you specify the way theattribute is to be validated. The constructor specifies the kind of validation that youwant to occur. Its parameters are:

1. Field name

2. Kind of field

3. Format string (regular expression)

4. Minimum value

5. Maximum value

Exercise 7In this exercise, you will create a validation class. This class is used in the followingsection, “Implementing Servlets”. You will also modify error message files.


TutorialSteps You will add error codes to the BXErrorCode class and correspondingmessages to the message.conf configuration file. You will use the error codeswhen you create the new MyValidateEmailView class.

1. Change your directory to the location of the common front-end class files.Open the BXErrorCode.java file in an editor.

cd $BX_HOME/fe/src/fe/common

messages.conf Messages configuration file

BXErrorCode.java Error code definition file

makefile front-end telco makefile

MyValidateEmailView.java Your validation class Italic

Validating Input


vi BXErrorCode.java

2. Locate the messages associated with the sign-on view and add your messagesafter them.

Your messages should continue in increasing order from the existing messages.The new messages are shown in bold.

// Sign on view

public final static String ONLINENAME_MISSING =

"BXFE_001000";

...

public final static String USER_NOT_FOUND = "BXFE_001005";

public final static String USER_STATUS_NOTACTIVE = "BXFE_001006";

...

public final static String EMAIL_MISSING = "BXFE_001012";

public final static String EMAIL_INVALID = "BXFE_001013";

public final static String EMAIL_MISMATCH = "BXFE_001014";

3. Save the file and change your directory to the location of the commonfront-end makefile file. Compile the common front-end files.


make

4. Copy the bxfe.zip file to BillerXpert’s java subdirectory.

cp bxfe.zip $BX_HOME/java/bxfe.zip

5. Save your changes and change your directory to the location of the BillerXpertconfiguration files. Open the messages.conf file in an editor.

cd $BX_HOME/config

vi messages.conf

6. Locate the BXFE_001005 message and add your messages after them. Thestring name in messages.conf must match the contents of the string in theBXErrorCode.java file. Changes to the message configuration file take effectwhen you restart iAS.

...

"BXFE_001005" Str "User not found!",

"BXFE_001006" Str "Authentication failed: Status is not

Validating Input


ACTIVE. É",

...

"BXFE_001012" Str "Validation failed: E-mail address is

missing.",

"BXFE_001013" Str "Validation failed: Invalid e-mail

address.",

"BXFE_001014" Str "E-mail address does not match registration

info.",

...

7. Change your directory to the location of the front-end telco view files andcreate the MyValidateEmailView.java file.

cd $BX_HOME/fe/src/fetelco/view

vi MyValidateEmailView.java

8. Define the MyValidateEmailView class as an extension of the BXValidateViewclass. Define a string that matches the input field name and a vector thatcontains the elements to be validated. This class validates only one field,named email.

public class MyValidateEmailView extends BXValidateView

{

public static final String EMAIL = "email";

private static Vector elements = new Vector(1);

}

9. Add a constructor that creates a BXValidateAttribute object for validating ane-mail address.

public MyValidateEmailView(BXStatus stat)

{

super();

status = stat;

“int mMinLength = BXValidateView.getMinLength

“int mMaxLength = BXValidateView.getMaxLength

“int mMinLength = 1;

‘ int mMinLength = 100;

Validating Input


elements.addElement( new BXValidateAttribute(EMAIL,

BXValidator.BX_TYPE_EMAIL,

"", true, mMinLength, mMaxLength));

}

10. Define a set() method that defines the items to be validated.

11. This implementation specifies validation of the entire valIn list, which in thiscase consists of only the e-mail field.

public void set(HttpServletRequest req)

{

IValList valIn = GX.CreateValList();

Enumeration enum = req.getParameterNames();

while (enum.hasMoreElements()) {

String name = (String) enum.nextElement();

String value = req.getParameter(name);

valIn.setValString(name, value);

}

parmList = valIn;

}

12. Define a validate() method that returns isValid if the data meets theattribute object’s specification or throws an exception that specifies the kind ofvalidation error that occurred.

This implementation calls a setError() method to set up the exception.

public boolean validate()

{

boolean isValid = BXValidator.validate(elements, this);

if (!isValid) {

setError();

}

return isValid;

Validating Input


}

protected void setError()

{

if (status == null) {

return;

}

String errCode = BXErrorCode.VALIDATE_UNKNOWN;

if (getNumErrors() > 0) {

String key = errorList.getNextKey();

int rc = errorList.getValInt(key);

switch (rc) {

case ACValidateError.ERROR_REQUIRED:

if (key.equals(EMAIL)) {

errCode = BXErrorCode.EMAIL_MISSING;

}

break;

default:

if (key.equals(EMAIL)) {

errCode = BXErrorCode.EMAIL_INVALID;

}

}

}

status.push(BXStatus.STATUS_ERROR, errCode)

}

13. Save your changes, change to the telco front-end directory, and modify themakefile file to include the MyValidateEmailView class.


vi makefile

Validating Input


14. Add a line to modify the MyValidateEmailView class at the end of thevalidation classes.

J_SRCS: \




view/BXValidatePwdView.class \






view/MyValidateEmailView.class \

...

15. Save your changes and recompile.

make

16. Optionally, copy the bx_fetelco.zip file to BillerXpert’s java subdirectoryand restart iAS.

This step is optional because you have not made use of this class as yet. You will need torecompile the bx_fetelco.zip and restart the iAS in the next exercise.


cd $NAS_HOME/bin

KIVAes.sh stop

KIVAes.sh start

ResultsThere is no visible output from this exercise. The MyValidateEmailView class isused by the Servlet created in the following section, “Implementing Servlets.”

Implementing Servlets


Implementing ServletsThe section Invoking Servlets describes how to invoke a Servlet, either from a form,an HTML hyperlink, or from another Servlet. This section describes how toimplement a Servlet, regardless of how it is invoked.

A Servlet is a class whose execution is managed by iAS. Servlets in BillerXpert arebundled into an Enterprise Application which is then deployed on iAS. When youcreate a Servlet, you define a subclass of the BXBaseServlet class. When a Servletis invoked, iAS calls the Servlet's doGet() or doPost() method.

The doGet() or doPost() method typically obtains session data, then calls othermethods to perform the specified action, handle validation, database access, and soon. The method typically terminates by forwarding the request to a JSP, forexample by calling displayTemplate() or displayError() which are defined inthe Base Class, CSXBaseServlet.

You should write your code so that it checks for validation and initializes thecontext in which database access takes place. Code Example 2-4 shows a skeletalexample of a doGet() method.

Code Example 2-4 doGet() method.

public void doGet(HttpServletRequest req, HttpServletResponse res) {

init(req, res);

if (!verifyUserSession()) {

displaySessionTimeout();

return;

}

// should always call init after verifyUserSession

if (!init(ALL_CONTEXT, req, resp)) {


return;

}

// Perform other initialization

...

String request = req.getParameter("...");



// get parameter value

if (request != null) {

if (request.equals(...)) { // test request

return ...; // call method to handle the request

}

else if (request.equals(...)) { // test request


}

else if (request.equals(...)) { // test request


}

}


return;

}

Exercise 8In this exercise, you will create a Servlet and modify a JSP that invokes the Servlet.You will also create JSP that the Servlet invokes. The Servlet uses the validationclass that you created in the previous exercise.


Tutorial StepsYou will modify the Sign On message JSP to invoke the new Servlet and create JSPsto display the password hint and sign-on error messages.

signon_msg.jsp Sign On message JSP

signon_error.jsp Signon Error message JSP

my_hint.jsp JSP page to display password hint

makefile front-end makefile

MyPasswordServlet.java Servlet to handle authentication errors



1. Change your directory to the location of the template files and copy thesignon_msg.jsp file to the signon_error.jsp file.

The signon_msg.jsp file will now be used to allow the user to display a hint orrequest a new password. The signon_error.jsp template will be used tohandle non-authentication errors.

cd $BX_HOME/fe/templates/telcoModel

cp signon_msg.jsp signon_error.jsp

2. Open the signon_msg.jsp page in an editor.

vi signon_msg.jsp

3. Modify the JSP to add the email field, buttons, and text shown in the followingfigure. The form should invoke your new Servlet.

In this example, the MyPasswordServlet is invoked by the form. The input tagsspecify submit buttons with the name RequestAction, whose value will be sentto the Servlet when the user clicks one of the buttons.

<html>

<head>

<link rel="stylesheet" href="telco/styles.css">

<title>Sign On</title>

</head>

<body>

<form method="POST" name=BXHome action="MyPasswordServlet">

...

<table border="0" width="100%" cellspacing="0">

<tr>

<td width="100%" align="left" nowrap>

<B>Forgot your password?

</B></td>

</tr>

<tr>


View your password hint or request a new password.</td>

</tr>



<tr>


Enter your registered e-mail address to receive a new

password:

</td>

</tr>

<tr>

<td width="100%"><input name="email" size="40" value="">

</td>

</tr>

</table>

<p>


value="Display Hint" width="84" >


value="Request New Password" width="84" > </p>

<table border="0" width="100%" cellpadding="0">

<tr>

<td width="10%"><img src="telco/images/bttn-home.gif"

alt="Home"

align="middle" border="0" WIDTH="20" HEIGHT="20"></td>

<td width="90%"><a href="telco/index.html">Home</a></td>

</tr>

</table>

</form>

</body>

</html>

4. Create a my_hint.jsp template to display the password hint.

For simplicity, you can take the signon_error.jsp template, which was theoriginal signon.html and modify it.




<tr></tr><tr></tr>

<tr>

<td><h3><b><%= request.getAttribute("hint") %></b></h3></td>

</tr>

</table>

<br>


<tr>

<td width="10%">

<img src="telco/images/bttn-home.gif" alt="Home"

align="middle" border="0" WIDTH="20" HEIGHT="20"></td>

<td width="90%"><a href="telco/index.html">Home</a></td>

</tr>

</table>

</form>

</body>

</html>

5. Change your directory to the location of the Servlet files and create the Servletclass.

Call your Servlet class MyPasswordServlet. Make it part of thenetscape.billxpert.fe.telc package and extend the BXBaseServlet class.

package netscape.billxpert.fe.telco;

import java.lang.*;

import java.util.*;

import java.net.*;

import java.io.*;

import com.kivasoft.*;

import com.kivasoft.types.*;

import com.kivasoft.util.*;

import com.kivasoft.applogic.*;






import netscape.billxpert.ejb.membership.*;


import javax.servlet.http.*;

import javax.servlet.*;

public class MyPasswordServlet extends BXBaseServlet

{

...

private final static String SIGNON_PAGE =

"/index.html";

private static final String ERRMSG_TEMPLATE =

"/signon_msg.jsp";

private static final String HINT_TEMPLATE =

"/my_hint.jsp";

private static final String DISPLAY_HINT = "Display Hint";

private static final String NEW_PASSWORD =

"Request New Password";

private static final String EMAIL = "email";

6. Add a doPost() method.

7. The doPost() method checks that initialization has been performed anddispatches to other methods based on the requested action.

public void doPost(HttpServletRequest req, HttpServletResponse res)

{

init(req, res);

if (!verifyUserSession()) {



displaySessionTimeout();

return;

}

// should always call init after verifyUserSession

// completes successfully

if (!init(MEMBERSHIP_CONTEXT)) {


return;

}


String onlineName = session.getOnlineName();

if (onlineName == null) {

...

}

String request = req.getParameter("RequestAction");

if (request == null) {



}

if (request.equals(NEW_PASSWORD)) {

handlePasswordRequest(onlineName);

}

else if (request.equals(DISPLAY_HINT)) {

displayHint(onlineName);

}

else {



}


return;



}

8. Handle retrieval and display of the password hint.

Since a session has not been established, you cannot retrieve the password hintusing the BXCustomerAcctView object's getUserProfile() method. Thefollowing example uses the IBXCustomerProfile component business objectinterface directly to retrieve the password hint.

private void displayHint(String OnlineName)

{

try {

IBXCustomerProfile custProfile;



custProfile.setStatus(status);

custProfile.setMembershipContext(membershipContext);

custProfile.setPrimaryKey(OnlineName);

custProfile.ejbLoad();

String hint = custProfile.getPasswordHint();

if (hint == null || hint.length() == 0) {

hint = "No hint on file.";

custProfile.setPasswordHint("not set.");

custProfile.ejbStore();

}

else

hint = "Your hint is " + hint;

// Save the hint as a request attribute

req.setAttribute("hint", hint);

displayTemplate(HINT_TEMPLATE);

return;

}






}

}

9. Handle validation of the request for a new password.

Your method should check for validation of the proper e-mail format andretrieve the e-mail address from the database if the format is valid. Once thee-mail address has been retrieved, you can check that the user-suppliedaddress matches the one stored in the database.

private int handlePasswordRequest(String onlineName)

{

String email = req.getparameter(EMAIL);

MyValidateEmailView emailView =

new MyValidateEmailView(status);

emailView.set(req);

if (!emailView.validate())


try {






custProfile.setPrimaryKey(onlineName);


String emailOnFile = custProfile.getEmail();

if (email.equals(emailOnFile)) {

displayTemplate(SIGNON_PAGE);

return;

}

else {

// e-mail authentication failed




BXErrorCode.EMAIL_MISMATCH);


return;

}

}




return;

}

}

10. Save your changes in the MyPasswordServlet.java file, change to the telcofront-end directory, and modify the makefile file to include theMyPasswordAL class.


vi makefile

11. Add a line to modify the MyPasswordServlet class at the end of the Servletclasses.

J_SRCS: \

...

applogic/MyPasswordServlet.class


make

13. BillerXpert is bundled as an enterprise J2EE application and deployed on iAS.Now we need to re-create the enterprise archive file with your changes. Thearchive files are placed for your convenience in the $BX_HOME/fe/configfolder.

Create a temporary working directory called $BX_HOME/tmp and copy thearchive file to that directory:

mkdir $BX_HOME/tmp



cp $BX_HOME/fe/config/billxpert.ear $BX_HOME/tmp

Now, extract the files in billxpert.ear

cd $BX_HOME/tmp

jar xvf billxpert.ear

Among the extracted files is the front-end web archive, called bxfe.war andfetelco.war. Extract the files in this archive into a folder called bxfe andfetelco:

mkdir bxfe

cd bxfe

jar xvf ../bxfe.war

mkdir fetelco

cd fetelco

jar xvf ../fetelco.war

14. Copy the bxfe.zip and bx_fetelco.zip created in step 12 to theWEB-INF/lib directory.

Copy the JSP files created earlier to the telco directory.

15. Modify the deployment descriptors to include your servlet. There are 2deployment descriptors for the web archive: WEB-INF/web.xml andWEB-INF/ias-web.xml.

First we will modify the web.xml file:

vi WEB-INF/web.xml

Add the following lines immediately after the <distributable></distributable>tags:

<servlet>

<servlet-name>MyPasswordServlet</servlet-name>

<servlet-class>netscape.csxpert.fe.MyPasswordServlet</servlet-class>

<load-on-startup>0</load-on-startup>



</servlet>

Next, modify the ias-web.xml file. For this, you will first need to generate aGUID for your servlet using the kguidgen utility in the $NAS_HOME/bin directory:

$NAS_HOME/bin/kguidgen

{01FB557B-8AB9-1CB6-9E73-0800208A9388}

This string is a Globally Unique IDentifier or GUID that can be used to identifyyour servlet.

Make a note of this string: you will need to add it to the ias-web.xml file.

vi WEB-INF/ias-web.xml

Add the following lines immediately after the <ias-web-app> tag:

<servlet>

<servlet-name>MyPasswordServlet</servlet-name>

<guid>{01FB557B-8AB9-1CB6-9E73-0800208A9388}</guid>

<validation-required>false</validation-required>

<servlet-info>

<sticky>true</sticky>

<encrypt>false</encrypt>

<number-of-singles>10</number-of-singles>

<disable-reload>false</disable-reload>

</servlet-info>

</servlet>

16. Save your changes and re-assemble the archives:

cd $BX_HOME/tmp

rm billxpert.ear billxpert.war

jar cvf billxpert.war bxfe/* fetelco/*

jar cvf billxpert.ear *

Now deploy the application to iAS:

$NAS_HOME/bin/iasdeploy redeployapp billxpert.ear



17. Restart iAS.


cd $NAS_HOME/bin

KIVAes.sh stop

KIVAes.sh start

ResultsYou must log into BillXpert after restarting the server. Figure 2-7 shows the sign-onmessage field that appears when BillXpert detects a problem with either the onlinename or password.

Figure 2-7 Sign On message page

Figure 2-8 shows the password hint page.

Figure 2-8 Password hint display page

Implementing an Event Handler


Implementing an Event HandlerBillerXpert provides an event-handling mechanism that allows a Servlet to push anevent onto a queue which can then be retrieved and processed by another javaclass, called an event handler. The BillerXpert event server handles communicationbetween the Servlet that pushes an event onto the queue and the event handler thatresponds to the event.

The event server is part of the BillerXpert admin console that defines the events, thehandlers, and mappings from an event to a handler. Each mapping specifies ahandler that responds to an event. A handler can respond on one or more events.

The Servlet that pushes an event must take the following actions:

1. Create an IEventChannel object that represents the event channel by whichthe event will be sent to the server.

2. Set the event channel’s context; typically, you set the context to be the same asthe Servlet’s context.

3. Create an iVal list that contains the event name and the data to pass to theevent handler.

4. Call the event channel’s ShouldPushEvent() method to determine whether ahandler exists to respond to the event.

5. If an event handler exists, call the channel’s PushEventData() method to pushthe event with the data needed by the event handler into the event queue.

Code Example 2-5 shows these steps.

Code Example 2-5 Creating and pushing an event...

try {

channel = (IEventChannel)

EventChannelMgr.createEventChannel();

channel.SetContext(icontext_, null);

}


throw new Exception

("Call to createEventChannel() failed.");

}



...

IValList eventIVal=GX.CreateValList();

eventIVal.setValString

(EventChannel.EVENTNAME, "LoaderMailEvent");

if (channel.ShouldPushEvent(eventIVal)) {

eventIVal.setValString

(EventChannel.EVENTDATA, "BX_FILEID="+FileId);

if (channel.PushEventData(eventIVal) < 0) {

throw new Exception

("Failed to push event data into channel.");

}

}

...

The event handler is a java class; thus, you define executeEvent() method. TheexecuteEvent() method is invoked by the event server when it processes an eventthat is mapped to the handler. The event handler does not tidally make use of thesession object or application business objects, because the handler executesindependently of the BillerXpert front end. The event handler typically creates itsown database connection and manipulates component business objects directly.

Exercise 9In this exercise, you will modify the Servlet that you created in the previousexercise to support requests for new passwords. The Servlet will push an eventonto the event queue whenever a new password is requested. You will also createan event handler java class that responds to the request and set up the event serverto use the handler to process the event.


MyPasswordServlet.java Servlet to handle authentication errors

MyPasswordHandler.java Java class to handle new password requests

makefile telco front-end makefile



Tutorial StepsYou will modify the The MyPasswordServlet.java file created in the section“Implementing Servlets” and add a new class, called MyPasswordHandler.java.Finally, you will use the BillerXpert admin console to set up the event server.

1. Change your directory to the location of the Servlet files and open theMyPasswordServlet.java file in an editor.


vi MyPasswordServlet.java

2. Import the event channel package.






import netscape.billxpert.eventchannel.*;

3. Add the code that creates an event channel and push a PasswordEvent eventinto the queue.

You need to define a reference to an IEventChannel object with the otherdata members of your class.

private void handlePasswordRequest(String onlineName)

{

System.out.println("MyPasswordAL:handlePasswordRequest");

String email=(String) req.getParameter(EMAIL);;

System.out.println("email:" + email + ":");

MyValidateEmailView emailView = new MyValidateEmailView(status);

System.out.println("MyValidationEmailView");

emailView.set(valIn);

System.out.println("check validate");

if (!emailView.validate()) {

System.out.println("validation failed");



return; displayErrorMsg(ERRMSG_TEMPLATE);

}

try {

System.out.println("entering try block");


custProfile = (IBXCustomerProfile)BXMembershipMgr.createCustomerProfile(null);





String emailOnFile = custProfile.getEmail();

System.out.println("emailonFile:" + emailOnFile + ":");


String billerId = session.getBillerId();

System.out.println("billerId:" + billerId + ":");

if (email.equals(emailOnFile)) {

try {

System.out.println("createEventChannel");

channel = (IEventChannel)EventChannelMgr.createEventChannel();

channel.SetContext(context,billerId);

}


throw new Exception ("Call to createEventChannel() failed.");

}

IValList eventIVal=GX.CreateValList();

eventIVal.setValString(EventChannel.EVENTID,"5");

eventIVal.setValString(EventChannel.EVENTNAME,"PasswordEvent");



eventIVal.setValString(EventChannel.BILLERNAME,billerId);

eventIVal.setValString(EventChannel.PRIORITY,"2"); // normal priority

eventIVal.setValString(EventChannel.EVENTDATE,(DateFormat.getInstance()).format(new Date()));

System.out.println("Checking if ShouldPushEvent");

if (channel.ShouldPushEvent(eventIVal)) {

System.out.println("Pushing data");

eventIVal.setValString(EventChannel.EVENTDATA,

"OLNAME="+onlineName+"&BILLERID="+billerId);

if (channel.PushEventData(eventIVal) < 0) {

System.out.println("Failed to push data into channel");

throw new Exception

("Failed to push event data into channel.");

}

}

return; displayTemplate(SIGNON_PAGE);

}

else {

// e-mail authentication failed


BXErrorCode.EMAIL_MISMATCH);

return; displayErrorMsg(ERRMSG_TEMPLATE);

}

}






}

}

...

private IEventChannel channel = null;

private final static String SIGNON_PAGE = "telco/new_index.html";

private final static String ERRMSG_TEMPLATE = "telco/signon_msg.jsp";

private final static String HINT_TEMPLATE = "telco/my_hint.jsp";

private final static String DISPLAY_HINT = "Display Hint";

private final static String NEW_PASSWORD = "Request New Password";

private final static String EMAIL = "email";


5. Change your directory to the location of the event handler files and create thehandler class.

Call your class MyPasswordHandler. Make it part of thenetscape.billxpert.fe.telco package and implement IHandler interface..

package netscape.billxpert.fe.telco;



import com.kivasoft.session.*;



import com.kivasoft.dlm.*;

import java.util.*;

import java.util.Random*;

import java.io.*;



import java.sql.*;

import java.actra.util.ntv.*;






import netscape.billxpert.eventchannel.*;

public class MyPasswordHandler implements IHandler

{

...

}

6. Add an executeEvent method.

The executeEvent() method resets the password and sends e-mail.public int executeEvent(IContext KivaContect, Hashtable eventdata)

{

System.out.println("MyPasswordHandlerAL execute");

GXContext.Log(context, GXLOG.GXEVENTTYPE_INFORMATION, -1,

"MyPasswordHandler -- Invoking password handler.");

String onlineName = (String)eventdata.get("OLNAME");

if (onlineName == null || onlineName.length() == 0) {


"MyPasswordHandler -- Cannot retrieve on-line name parameter.");

return 0;

}

String billerId = (String)eventdata.get("BILLERID");

if (billerId == null || billerId.length() == 0) {




"MyPasswordHandler -- Cannot retrieve biller id parameter.");

return 0;

}

BXStatus status = new BXStatus();

System.out.println("billerId:" + billerId + ":");

try {

BXDBContext dbcontext = new BXDBContext(context, status,billerId);

Connection conn = dbcontext.getConnection();

}


GXContext.Log(context, GXLOG.GXEVENTTYPE_INFORMATION,-1,

"MyPasswordHandler -- database initialization failed.");

return 0;

}

try {

BXMembershipContext membershipContext =

new BXMembershipContext(context,billerId);


custProfile = (IBXCustomerProfile)BXMembershipMgr.createCustomerProfile(null);





String email = custProfile.getEmail();

IMailbox sendMB = createMailbox("geez","Password Administrator","","[email protected]");



if (sendMB != null) {

if (sendMB.open(GX_MBOX_OPEN_FLAG.OPEN_SEND)

==GXE.SUCCESS) {

String emailAry[] = {email,null};

String newPassword= createRandomPassword();

custProfile.setPassword(newPassword);

custProfile.ejbStore();

String msg = "Subject: Your new password\n";

msg += "Your password has been reset.\n";

msg += "Your new password is ";

msg += newPassword;

msg += "\n";

sendMB.send(emailAry,msg);

sendMB.close();

GXContext.Log(context,GXLOG.GXEVENTTYPE_INFORMATION,

-1,"MyPasswordHandler -- Sent e-mail to " +

email + ".");

}

}

else {

GXContext.Log(context, GXLOG.GXEVENTTYPE_INFORMATION,

-1, "MyPasswordHandler -- sendMB is null.");

}

}




"MyPasswordHandler-Cannot access e-mail for user " +



onlineName);

}

return 0;

}

private String createRandomPassword()

{

String newPassword;

byte randBytes[] = new byte[16];

Random ranSeq = new Random();

newPassword = randBytes.toString();

return newPassword.substring(7);

}

}

Add a createRandomPassword() method to create a password.

private String createRandomPassword()

{

String newPassword;

byte randBytes[] = new byte[16];

Random ranSeq = new Random();

ranSeq.nextBytes(randBytes);

newPassword = randBytes.toString();

return newPassword.substring(7);

}

7. Save your changes in the MyPasswordHandler java file, change to the telcofront-end directory, and modify the makefile file to include theMyPasswordServlet class.


vi makefile



8. Add a line to modify the MyPasswordServlet class at the end of the Servletclasses.

J_SRCS: \




view/BXValidatePwdView.class\






view/MyValidateEmailView.class \

...

view/BXPayHistoryViewBean.class \

applogic/BXSignOnServlet.class \

...

applogic/BXPayHistoryServlet.class \

applogic/MyPassworServlet.class \

applogic/MyPasswordHandler

...


make




Run the deploytool program in the bin subdirectory of the directory in whichiAS is installed.

$NAS_HOME/bin/deploytool

12. Create an ear file containing MyPasswordServlet.class andMyPasswordHandler.class files and deploy them using deploytool



13. Restart iAS.


cd $NAS_HOME/bin

KIVAes.sh stop

KIVAes.sh start

14. Add the following lines to the file $BX_HOME/schema/oracle/event.sql:

REM

REM insert PasswordEvent into the BXEVENT table

REM

delete BXEVENT where EVENTNAME = 'PasswordEvent' and BILLERID='DEFAULT'

/

insert into BXEVENT

(EVENTID, BILLERID, EVENTNAME, DESCRIPTION, STATUS)

values

(5, 'DEFAULT', 'PasswordEvent', '', 'ACTIVE')

/

REM

REM insert PasswordEventHandler into the BXHANDLER table

REM

delete BXHANDLER where HANDLERNAME = 'PasswordEventHandler'

/

insert into BXHANDLER

(HANDLERID, HANDLERNAME, APPLICATIONID, DESCRIPTION, PACKAGE, CLASSPATH,

EXTENSION1, EXTENSION2, EXTENSION3, EXTENSION4)

Changing Database Schemas


values

(6, 'PasswordEventHandler',null}',

'', 'netscape.billxpert.fe', 'PasswordEventHandler',

null,null,null,null)

/

REM

REM insert the mapping into the BXEVENTHANDLER table

REM

delete BXEVENTHANDLER where EVENTID = 5 and HANDLERID = 6

/

insert into BXEVENTHANDLER

(EVENTHANDLERID, EVENTID, STATUS, HANDLERID)

values

(5, 5, 'ACTIVE', 6)

/

15. Enter the data into the database using your user name, password, and databasename for your Billing Service Provider (BSP) account.

sqlplus USERNAME/PASSWD@DBNAME <event.sql

ResultsThe password will be reset and e-mail will be sent to the e-mail address on file inthe database at the time the e-mail was created. After you receive the e-mail, youshould log in to BillerXpert again and change the password back to some value thatyou can remember.

Changing Database SchemasThis section and the sections that follow show how to add a bill presentmenthandling capability for a different industry. Specifically, these examples show thebasics of how to customize BillerXpert to handle bill presentment for the cabletelevision industry.



The previous sections show how to modify the BillerXpert front end to presentdata in a different format or to store and retrieve data that is already defined by aschema. When customizing BillerXpert to handle bill presentment for a differentindustry, it probably will be necessary to collect different kinds of data and, thus,require you to modify the schema to meet the requirements of the new industry.

You most likely will modify the Oracle database schema that defines the details ofa billing record. BillerXpert provides several tables that hold detail records for atelephone company. You can ignore or drop these tables and add one or more thatholds detail records for the industry for which you want to present bills. For thetelephone industry, BillerXpert provides the BXLineItemTelcoCall,BXLineItemTelcoMisc, and BXLineItemTelcoRating tables to hold data abouttelephone calls.

Code Example 2-6 shows the script that defines the schema and trigger for theBXLineItemCable table.

Code Example 2-6 create_cable.sql script

create table BXLINEITEMCABLE

(

LINEID NUMBER(15) not null,

LINEITEMTYPE VARCHAR2(32) not null,

DESCRIPTION VARCHAR2(128) not null,

TOTALAMOUNT DECIMAL(16,4) not null,

constraint PK_BXLINEITEMCABLE2 primary key (LINEID)

USING INDEX

TABLESPACE TS02

STORAGE (

INITIAL 16K

NEXT 16K

)

NOTE This section and the sections that follow assume that you need notchange more than the detail lines for an industry. BillerXpertassumes that all line items, regardless of industry, share the samedocument, summary, and document-to-detail assignment tables.



)

TABLESPACE TS01

STORAGE (

INITIAL 16K

NEXT 16K

)

/

create sequence BXLINEITEMCABLE_seq minvalue 2000

/

CREATE TRIGGER del_cable_details

BEFORE DELETE ON BXDOCLINEASGT for each row

DECLARE

BEGIN

if (:old.linetype = 'IBXDetailCable')

then

delete BXLINEITEMCABLE where BXLINEITEMCABLE.lineid =

:old.lineid;

end if;

end;

/

Code Example 2-7 shows the script that drops the BXLineItemCable table andtrigger.

Code Example 2-7 Delete BXDetailCable script

drop table BXLINEITEMCABLE cascade constraints

/

drop trigger del_cable_details

/

Configuring Table Definitions


drop sequence BXLINEITEMCABLE_seq

/

Exercise 10In this exercise, you will create a table for holding detail information aboutmonthly cable TV charges. These files are located in the $BX_HOME/samples/cable/schema/oracle directory.

FilesIn this exercise, you will execute the following files:

Tutorial StepsYou will log into Oracle and execute the create_cable.sql script.

1. Log into sqlplus and execute the create_ cable.sql script.

sqlplus bx/bx@bx

@create_cable.sql

2. If you need to recreate the table, you can execute the drop_cable.sql scriptbefore repeating the previous step.

@drop_cable.sql

Configuring Table DefinitionsLDAP is used by BillerXpert to map database column names to names used withinBillerXpert to identify fields in component business objects, described in the section“Implementing Component Business Objects”, and by the loading program,described in the following section on page “Search for the accessor methods.,” onpage 103. After you create the database schema, you should update LDAP.

LDAP is a collection of NTV lists, which are lists of name-type-value tuples. NTVlists for component business objects and the loader program define the datastructures available to BillerXpert and the loader program.

create_cable.sql script that creates the cable TV detail line table

drop_cable.sql (optional)

script that drops the cable TV detail line table

Configuring Table Definitions


The NTV list consists of the following information:

1. Name of the NTV list

2. Database table or LDAP schema that corresponds to the list

3. A list of attributes that define the names that can be used programmatically

Each attribute is itself an NTV list that contains the following information:

An attribute contains information about the database table:

1. Table or schema and field associated with the attribute.

2. Ordinal number of the a column represented by the attribute name

3. Length of the database field

4. Type of field, such as INT for integer or STRING for string

The following screenshot shows the NTV list:

Exercise 11In this exercise, you examine the structure of the LDAP file. In this example, youexamine the database in the $NAS_HOME directory.

Implementing Component Business Objects


FilesIn this exercise, you will examine the LDAP database contents.

Tutorial StepsExamine the LDAP database contents.

1. Change to the iPlanet Application Server (iAS) configuration directory andopen the Directory Server.

cd $NAS_HOME/..

startconsole

2. Log in as the IAS Administrator.

Search for the BXDetailCable entry as in the previous figure.

Implementing Component Business ObjectsComponent business object classes represent records in a database. BillerXpertprovides sample interface and implementation classes for detail cable TV charges.You can modify these classes to define your own component business objectclasses.

To implement a component business object class, you must define accessormethods for each field in the record and also implement the following methods,which are defined in the IBXEntity interface:

ejbCreate() Creates a record in the database.

ejbStore() Updates a record in the database.

ejbRemove() Removes a record from the database.

ejbLoad() Reads a record, identified by object ID, from thedatabase.

ejbFindByPrimaryKey() Reads a record, identified by key, from thedatabase.

ejbFindAll() Reads selected records from the database.

getName() Determines the class name.

dump() Displays the fields in anobject.X_HOME/samples/cable/ejb dir



You may define other methods as needed. The sample cable TV detail chargerecord class, defines methods for setting all fields in a record and for checking thatrequired fields have been set.

Exercise 12In this exercise, you examine the structure of the files that define sample interfaceand implementation classes for detail cable TV charges. The steps indicate thechanges you should make to implement a different kind of detail record.

FilesIn this exercise, you will examine or execute the following files:

Tutorial StepsExamine the IBXDetailCable and BXDetailCable classes.

1. Change to the $BX_HOME/samples/cable/ejb directory and open theIBXDetailCable.java file.

cd

vi IBXDetailCable.java

2. Examine the interface for the IBXDetailCable class.

To implement your own component business object class, you should define aninterface class that provides accessor methods to each field in the record. Detailrecords extend the IBXDetail class. Methods to create, store, load, and findrecords are defined in the IBXEntity class from which all other interfacesdescend. You can use any package.

package netscape.billxpert.ejb.billing;

import java.lang.*;

import java.util.*;

import java.io.*;


import netscape.billxpert.ejb.common.*;

IBXDetailCable.java interface to the cable TV detail record

BXDetailCable.java implementation of the cable TV detail record

makefile makefile file for cable TV detail component objectclass



public interface IBXDetailCable extends IBXDetail

{

/////////////////////////////////////////////////////////////

// Attribute access and modification

/////////////////////////////////////////////////////////////

public String getDocID() ;

public void setDocID( String docID) ;

public String getFileID() ;

public void setFileID( String fileID) ;

public String getLineItemType() ;

public void setLineItemType( String lineItemType) ;

public String getDescription() ;

public void setDescription( String description ) ;

public double getTotalAmount();

public void setTotalAmount( double amount );

}

3. Close the file and open the BXDetailCable.java file.

vi BXDetailCable.java

4. Examine the structure of the BXDetailCable class.

To implement your own component business object class, you define privatedata for each database field and a getName() method as well as a dump()method. Other methods are described in the following steps.

package netscape.billxpert.ejb.billing;

import java.lang.*;

import java.util.*;

import java.net.*;

import java.io.*;



import java.text.*;







public class BXDetailCable extends BXBillingEntity

implements IBXDetailCable

{

private String docID_;

private String fileID_;

private String lineItemType_;

private int lineNumber_;

private String description_;

private double totalAmount_;

private String extension_;

private String className_ = "BXDetailCable";

public String getName() throws Exception {

return ( className_ );

}

...

public void dump( PrintStream out ) {

out.println("ObjectID = " + getPrimaryKey());

out.println("DocID = " + getDocID());

out.println("FileID = " + getFileID());



out.println("LineItemType = " + getLineItemType());

out.println("Description = " + getDescription());

out.println("TotalAmount = " + getTotalAmount());

}

}

5. Search for the accessor methods.

To implement your own component business object class, you must definemethods that get and set each of the fields in your record.

public String getDocID() {

return docID_;

}

public void setDocID( String docID) {

docID_ = docID;

}

public String getFileID() {

return fileID_;

}

public void setFileID( String fileID) {

fileID_ = fileID;

}

public String getLineItemType() {

return lineItemType_;

}

public void setLineItemType( String lineItemType) {

lineItemType_ = lineItemType;

}

public String getDescription() {

return description_;

}

public void setDescription( String description ) {

description_ = description;



}

public double getTotalAmount() {

return totalAmount_;

}

public void setTotalAmount( double amount ) {

totalAmount_ = amount;

}

public int getLineNumber() {

return lineNumber_;

}

public void setLineNumber( int num ) {

lineNumber_ = num;

}

public String getExtension() {

return extension_;

}

public void setExtension( String extension) {

extension_ = extension;

}

6. Search for the ejbCreate() method.

To implement your own component business object class, your ejbCreate() method must update all fields in the record identified by the primary key.Typically, you would only need to change the table parameter in the calls tothe connection’s getTable() and getNextSeq() methods and set the fields inthe table. These actions are shown in bold.

public String ejbCreate() throws Exception {

// Check if DBContext is valid.

checkDBContext();

context_.log( BXDBContext.INFO, "BXDetailCable::ejbCreate" );



// Cjeck required fields.

checkRequiredFields();

// Construct Insert statement.

Connection conn = context_.getConnection();

conn.setAutoCommit(false);

BXJDBCHelper helper = new BXJDBCHelper(conn);

helper.setBXDBContext( context_ );

helper.setTable(BXDef.BXLINEITEMCABLE);

// Get sequence number

int seq = context_.getNextSeq( BXDef.BXLINEITEMCABLE );

context_.log( BXDBContext.INFO, "BXDetailCable::ejbCreate;seqNum = " + seq );

// Get Date.

Date date = new Date();

// Set the contents.

helper.setInt( "PRIMARYKEY", seq ); //ObjectID

helper.setString("LINEITEMTYPE", lineItemType_ );

helper.setString("DESCRIPTION", description_ );

helper.setDouble("TOTALAMOUNT", totalAmount_ );

// For asssignment table

BXJDBCHelper asghelper = new BXJDBCHelper(conn);

asghelper.setBXDBContext( context_ );

asghelper.setTable(BXDBDef.BXDOCLINEASGT);



int docID = 0;

if( docID_ != null )

docID = Integer.parseInt(docID_,10);

int fileID = 0;

if( fileID_ != null )

fileID = Integer.parseInt(fileID_,10);

asghelper.setInt ( "DOCID", docID );

asghelper.setInt ( "LINEID", seq );

asghelper.setInt ( "FILEID", fileID );

asghelper.setString ( "LINETYPE", BXDef.CABLEDETAIL );

asghelper.setString ( "TABLENAME", BXDef.BXLINEITEMCABLE );

// Execute the query

context_.log( BXDBContext.INFO, "BXDetailCable::ejbCreate;before insert");

int rc = 0, rc1 = 0;

try{

rc = helper.insert();

rc1 = asghelper.insert();

}catch(SQLException e){

conn.rollback();

context_.log( BXDBContext.INFO, "BXDetailCable::ejbCreate:errorCode=" + e.getErrorCode());

IValList paramList = GX.CreateValList();

paramList.setValString("msg", e.getMessage() );



paramList.setValInt("errnum", e.getErrorCode() );

getBXStatus().push( BXStatus.STATUS_ERROR,BXError.BAD_DB_EXECUTION, paramList );

throw new Exception("BXDetailCable::ejbCreate() failed. Error code = " + e.getErrorCode() );

}

if(rc == 1 && rc1 == 1){

conn.commit();

}else{

conn.rollback();

context_.log( BXDBContext.INFO, "BXDetailCable::ejbCreate() failed");

getBXStatus().push( BXStatus.STATUS_ERROR, BXError.BAD_DB_EXECUTION, null);

throw new Exception("BXDetailCable::ejbCreate() failed");

}

// Everything is fine, return ID.

setPrimaryKey( String.valueOf(seq) );

return String.valueOf(seq);

}

7. Search for the checkRequiredFields() method.

If you use the checkRequiredFields() method to implement your owncomponent business object class, you must modify the this method. ThecheckRequiredFields() method pushes an error status if a required field ismissing.

private void checkRequiredFields() throws Exception {

// Doc ID or Container ID must exist.

// A detail can belong to both doc and container.


if( docID_ == null ) {

paramList.setValString("field", "Doc ID " );



getBXStatus().push( BXStatus.STATUS_ERROR,BXError.MISSING_REQUIRED_FIELDS, paramList );

throw new Exception("BXDetailCable::checkRequiredFields() failed .. DocID and Container ID are missing.");

}

}

8. Search for the ejbLoad() method.

To implement your own component business object class, your ejbLoad()method must read all fields in the record identified by the primary key.Typically, you do not need to modify this method, rather you modify thereadData() method called by ejbLoad() to retrieve the fields.

public void ejbLoad() throws Exception {

checkDBContext();

context_.log( BXDBContext.INFO, "BXDetailCable::ejbLoad: ID = " + objID_ );

BXFilter filter = new BXFilter();

filter.setBXDBContext(context_);

filter.addCondition("PrimaryKey", BXFilter.OP_EQUAL, getPrimaryKey() );

Vector result = ejbFindAll( filter, null, "100", 1 );

if( result.size() != 1 ) {

context_.log( BXDBContext.INFO, "BXDetailCable::ejbLoad:nothing found" );

getBXStatus().push( BXStatus.STATUS_INFO, BXError.OBJECT_NOT_FOUND, null);

throw new Exception("BXDetailCable::ejbLoad:nothing found");

}

readData( (BXDetailCable)result.elementAt(0) );



context_.log( BXDBContext.INFO, "BXDetailCable::ejbLoad: exit" );

}

9. Search for the readData() methods.

If you modify the ejbLoad() or ejbFindAll() methods provided with thecable TV sample to implement your own component business object class, youmust also modify the readData() methods. The readData() methods set thefields from either a result set returned by an SQL query or from another recordfrom the same table.

private void readData ( BXDetailCable rset ) throws Exception {

// !!Should not hard codeded column number ....

setPrimaryKey ( rset.getPrimaryKey());

setLineItemType ( rset.getLineItemType() );

setDescription ( rset.getDescription());

setTotalAmount ( rset.getTotalAmount());

setDocID ( rset.getDocID());

setFileID ( rset.getFileID());

}

10. Search for the ejbStore() method.

To implement your own component business object class, your ejbStore()method must update all fields in the record identified by the primary key;typically, you would only need to change the table parameter in the call to theconnection’s getTable() method and the field references in the calls to thetable’s setValueString() method, which are shown in bold.

public void ejbStore() throws Exception {


checkDBContext();

context_.log( BXDBContext.INFO, "BXDetailCable::ejbStore" );



// Check if objectID exists .

checkPrimaryKey();

// Construct Update statement.




helper.setBXDBContext( context_ );


context_.log( BXDBContext.INFO, "BXDetailCable::ejbStore:after getconnection" );

helper.setString ("LINEITEMTYPE", lineItemType_);

helper.setString ("DESCRIPTION", description_);

helper.setDouble ("TOTALAMOUNT", totalAmount_);


context_.log( BXDBContext.INFO, "BXDetailCable::ejbStore;before updateRow");

int rc = 0;

try{

rc = helper.update(getPrimaryKey());


conn.rollback();




context_.log( BXDBContext.INFO, "BXDetailCable::ejbStore:errorCode=" + e.getErrorCode());

// Push stack




getBXStatus().push( BXStatus.STATUS_ERROR, BXError.BAD_DB_EXECUTION, paramList );

throw new Exception("BXDetailCable::ejbStore() failed." );

}

if(rc == 1){

conn.commit();

}else{

context_.log( BXDBContext.INFO, "BXDetailCable()::ejbStore() faild");


throw new Exception("BXDetailCable::ejbStore() failed");

}

context_.log( BXDBContext.INFO, "BXDetailCable::ejbStore exit" );

}

11. Search for the ejbRemove() method.

To implement your own component business object class, you must modify theSQL query in this method. To implement your own component business objectclass, your ejbRemove() method must remove the row identified by primarykey and remove the related assignment table entries; typically, you would onlyneed to change the table parameter in the call to the connection’s getTable()method.

public void ejbRemove() throws Exception {




checkDBContext();

context_.log( BXDBContext.INFO, "BXDetailCable::ejbRemove" );

// Check if objectID exists .

checkPrimaryKey();



context_.log( BXDBContext.INFO, "BXDetailCable::ejbRemove:after getconnection" );


BXJDBCHelper asghelper = new BXJDBCHelper(conn);

helper.setBXDBContext(context_);

asghelper.setBXDBContext(context_);


asghelper.setTable(BXDBDef.BXDOCLINEASGT);

helper.setInt("PRIMARYKEY", Integer.parseInt(getPrimaryKey(),10));

String query = "DELETE FROM " + BXDBDef.BXDOCLINEASGT +

" WHERE LINEID = " + getPrimaryKey() +

" AND " +

BXDBDef.BXDOCLINEASGT + ".LINETYPE = '" + BXDef.CABLEDETAIL + "' " ;




context_.log( BXDBContext.INFO, "BXDetailCable::ejbRemove;before deleteRow");

int rc = 0, rc1 = 0;

Hashtable rh = null;

try{

rc = helper.delete();

rh = asghelper.doExecute(query, BXJDBCHelper.DELETE);

rc1 = ((Integer)rh.get(new Integer(BXJDBCHelper.DELETE))).intValue();


conn.rollback();

context_.log( BXDBContext.INFO, "BXDetailCable::ejbRemove:errorCode=" + e.getErrorCode());

// Push stack




getBXStatus().push( BXStatus.STATUS_ERROR, BXError.BAD_DB_EXECUTION, paramList );

asghelper.closeStatement();

throw new Exception("ACDetailCable::ejbRemove() failed." );

}

if(rc == 1 && rc1 == 1){

conn.commit();

}else{



context_.log( BXDBContext.INFO, "BXDetailCable::ejbRemove() faild");



throw new Exception("BXDetailCable::ejbRemove() failed");

}

//.deleteRow( 0, "LINEID = " + getPrimaryKey() + " AND " +

//BXDBDef.BXDOCLINEASGT + ".LINETYPE = '"+ BXDef.CABLEDETAIL+ "'


context_.log( BXDBContext.INFO, "BXDetailCable::ejbRemove exit" );

}

12. Search for the ejbFindByPrimaryKey() method.

public void ejbFindByPrimaryKey( String key ) throws Exception {

this.objID_ = key;

this.ejbLoad();

}

13. Search for the ejbFindAll() methods.

There are two implementations, one that retrieves the specified number ofrecords sequentially starting with the specified primary key value and oneversion that selects all records. The context must be set. To implement yourown component business object class, you must modify the SQL query in thismethod in the ejbFindAll() method.



public Vector ejbFindAll(BXFilter filter, BXOrder order , String startIndex,

int maxRows ) throws Exception {


checkDBContext();

context_.log( BXDBContext.INFO, "BXDetailCable::ejbFindAll" );



helper.setBXDBContext(context_);

helper.setTabledefTableName(getName());

// Construct Select statement.

StringBuffer sqlBuf = new StringBuffer();

sqlBuf.append( " SELECT " + BXDef.BXLINEITEMCABLE +

".* , BXDOCLINEASGT.DOCID , BXDOCLINEASGT.FILEID FROM " +

BXDef.BXLINEITEMCABLE + " , BXDOCLINEASGT ");

/*

WHERE " +

BXDef.BXLINEITEMCABLE + ".LINEID >= "

+ startIndex + " AND " +

BXDef.BXLINEITEMCABLE + ".LINEID = " +

BXDBDef.BXDOCLINEASGT+ ".LINEID AND " +

BXDBDef.BXDOCLINEASGT + ".LINETYPE = '" +

BXDef.CABLEDETAIL + "' " );

*/



if (filter == null) filter = new BXFilter();

filter.addCondition("PRIMARYKEY", BXFilter.OP_GREATEREQUAL, startIndex);

filter.addCondition("PRIMARYKEY", BXFilter.OP_EQUAL, "" +

BXDBDef.BXDOCLINEASGT+ ".LINEID");

filter.addCondition("LINETYPE", BXFilter.OP_EQUAL, BXDef.CABLEDETAIL);

Hashtable rh = null;

ResultSet rset = null;

try{

rh = helper.doExecute(filter, order, sqlBuf.toString(),

maxRows, BXJDBCHelper.SELECT);

rset = (ResultSet)rh.get(new Integer(BXJDBCHelper.SELECT));

}catch(SQLException se){

// Always close the result set

if (rset != null)

rset.close();

helper.closeStatement();

se.printStackTrace();

context_.log(BXDBContext.INFO, "BXDetailCable()::ejbFindAll:errorCode=" + se.getErrorCode());


paramList.setValString("msg", se.getMessage());

paramList.setValInt("errnum", se.getErrorCode());

getBXStatus().push(BXStatus.STATUS_ERROR,

BXError.BAD_DB_EXECUTION, paramList);



throw new Exception("BXDetailCable::ejbFindAll faild, Error code = " + se.getErrorCode() );

}

// Process query.

Vector result = new Vector();

if( rset == null) {


return result;

}

int count = 0;

BXDetailCable detail = null;

while(rset.next()){

detail = new BXDetailCable();

detail.setBillingContext(context_);

detail.readData( rset );

result.addElement( detail );

count++;

if( ( maxRows != -1) && ( count >= maxRows ) )

break;

}

// Close result set.

rset.close( );




context_.log( BXDBContext.INFO, "BXDetailCable::ejbFindAll exit" );

return result;

}

////////////////////////////////////////////////////////////////////

// Query, fileter and order is not implemented.

////////////////////////////////////////////////////////////////////

public Vector ejbFindAll(BXFilter filter, BXOrder order ) throws Exception {

return ejbFindAll( filter, order, "100", -1 );

}

public void dump( PrintStream out ) {

out.println("ObjectID = " + getPrimaryKey());

out.println("DocID = " + getDocID());

out.println("FileID = " + getFileID());

out.println("LineItemType = " + getLineItemType());

out.println("Description = " + getDescription());

out.println("TotalAmount = " + getTotalAmount());

}

}

14. Save your changes if you made any and close the file.

15. At this point, you may compile your classes.

121

Chapter 3

Common Front-End Classes

This chapter discusses the common classes used by the BillerXpert front end tomanipulate application business objects.


• Overview

• BXBaseServlet Class Reference

• BXBaseView Class Reference

• BXConfigObj Class Reference

• BXErrorCode Class Reference

• BXSession Class Reference

• BXBaseBean Class Reference

• BXTemplateBeanMapBasic Class Reference

• BXTemplateUtil Class Reference

• BXValidateView Class Reference

• BXValidateAttribute Class Reference

• BXValidator Class Reference

• BXViewUtil Class Reference

OverviewTable 3-1 shows the classes that are available to any kind of BillerXpert application.

BXBaseServlet Class Reference


BXBaseServlet Class ReferenceInstances of the BXBaseServlet class represent BillerXpert Servlets. You typicallydefine a subclass of the BXBaseServlet class to implement your Servlets.

Methods


Class Description

BXBaseServlet Class from which Servlet classes are derived.

BXBaseView Abstract class from which view classes are derived.

BXConfigObj Represents NTV list entries in configuration files.

BXErrorCode Defines BillerXpert error codes.

BXSession BillerXpert session class.

BXValidateAttribute Represent attributes, such as input fields, which can bevalidated.

BXValidateView Abstract class from which classes that validate views arederived.

BXValidator Validates BillerXpert data types.

BXBaseBean Base classes for the string display data.

BXTemplateUtil Additional methods to support templates.

BXViewUtil Additional methods to support view objects.

Table 3-2 Summary List

Initialization

init( ) Initializes database contexts.

Context management

createBXBillingContext( ) Creates a billing context.

createBXMembershipContext( ) Creates a membership context.

createBXConfigContext( ) Creates a configuration context.

releaseBXDBContext( ) Releases database contexts.


Chapter 3 Common Front-End Classes 123

Class Definition

Packagenetscape.billxpert.common

Syntaxpublic class BXBaseServlet extends HttpServlet { ... }

Context FlagsYou can use a context flag to specify the contexts to create when you call a Servlet’sinit( ) method:

Syntaxprotected final int ALL_CONTEXT = 0;protected final int BILLING_CONTEXT = 1;protected final int MEMBERSHIP_CONTEXT = 2;protected final int PAYMENT_CONTEXT = 3;protected final int CONFIG_CONTEXT = 4;

Session management

getSessionProxy( ) Returns the session proxy.

getBXSession( ) Returns the current session object.

createBXSession( ) Creates a BillerXpert session object.

verifyUserSession( ) Verifies that a valid session exists.

parseSessionID( ) Determines the session’s ID.

Displaying templates and error information

displayTemplate( ) Displays a template.

displayErrorMsg( ) Displays an error message template.

Debugging support

logError Logs the error in a log file.

logActivity Logs the activities.

Access Control

CheckACL( ) Checks if the Access Contorl List (ACL) role isauthorized.




Context ObjectsYou can use the following context objects within your Servlet; these objects arecreated for you when you call the Servlet’s init( ) method.

Syntaxprotected BXBillingContext billingContext = null;protected BXMembershipContext membershipContext = null;protected BXPaymentContext paymentContext = null;protected BXConfigContext configContext = null;

Session, Status, and Application InformationThe following session, status, and application information can be used within yourServlet:

Syntax BXSession m_sessionProxy = null;protected BXStatus status = null;public String appName = "BillXpert";protected String SESSION_ID_NAME = "gx_session_id_BillXpert";

ALL_CONTEXT Create one of each kind of context object.

BILLING_CONTEXT Create a billing context object.

MEMBERSHIP_CONTEXT Create a membership context object.

PAYMENT_CONTEXT Create a payment context object.

CONFIG_CONTEXT Create a configuration context object.

billingContext Reference to the current billing context

membershipContext Reference to the current membershipcontext

paymentContext Reference to the current payment context

configContext Reference to the current configurationcontext

m_sessionProxy Reference to the current session object.

status Reference to the stackable status object.

appName A string that contains the application name.



MethodsThis section describes the methods of the BXBaseServlet class.

createBXBillingContext( )Creates a billing context.

Syntaxvoid createBXBillingContext( );

DiscussionThe createBXBillingContext( ) method creates a BXBillingContext object andassociates it with the billingContext variable. The createBXBillingContext( )method is protected.

createBXConfigContext( )Creates a configuration context.

Syntaxvoid createBXConfigContext( );

DiscussionThe createBXConfigContext( ) method creates a BXConfigContext object andassociates it with the configContext variable. The createBXConfigContext( )method is protected.

createBXMembershipContext( )Creates a membership context.

Syntaxvoid createBXMembershipContext( );

DiscussionThe createBXMembershipContext( ) method creates a BXMembershipContextobject and associates it with the payment Context variable. The createBXPaymentContext ( ) method is protected.

SESSION_ID_NAME A string that contains the session ID name.



Create BXSession ( )Creates a BillerXpert session object.

SyntaxBXSession createBXSession( );BXSession createBXSession(String OnlineName)

ParametersThe method has the following parameters:

ReturnsA BXSession object that represents the current session.

DiscussionThe first form of the createBXSession( ) method creates a session object only if anobject representing the current session does not exist. The second form of thecreateBXSession( ) method creates a new session object if the online name is not thesame as the current online name or if an object representing the current sessiondoes not exist. The createBXSession( ) method assigns a reference to a newlycreated session object to the m_sessionProxy variable.

displayErrorMsg( )Displays an error message template.

Syntaxvoid displayErrorMsg(String templateFile);


ReturnsGXE.SUCCESS if no error occurred; otherwise, the returned value is not defined.

OnlineName A string that contains the user’s onlinename.

templateFile A string that contains the pathname of theHTML template.



DiscussionThe method invokes the specified template and attempts to display the errormessage and code, which is stored in the current status object. If the status object isempty, the displayErrorMsg( ) method displays the message “Unknown Error,” forerror code BXFE_10000. The displayErrorMsg( ) method calls the displayTemplate() method to perform this action.

ExampleThe following example displays the Sign On error message template if the Servletcannot be initialized.

private static final String ERRMSG_TEMPLATE = "telco/signon_msg.jsp";...if (!init(MEMBERSHIP_CONTEXT)) return displayErrorMsg(ERRMSG_TEMPLATE);

displayTemplate( )Displays a template.

Syntaxvoid displayTemplate( String template);


DiscussionThe method invokes the specified template and attempts to display the dataspecified the data and map parameters. These parameters specify the data to beretrieved from a data repository. The displayTemplate( ) method calls the iASevalOutput( ) method to perform this action.

NOTE The displayErrorMsg( ) method releases all database contexts.

template A string that contains the pathname of theHTML template or JSP page.



See AlsoThe evalOutput( ) method in the iPlanet Application Server (iAS) Server FoundationReference (Java) manual.

getBXSession( )Returns the current session object.

SyntaxBXSession getBXSession( );

ReturnsA BXSession object that represents the session object.

DiscussionThe getBXSession( ) method returns the session object referenced by them_sessionProxy variable. If the variable is null, the getBXSession( ) method createsa session object and assigns it to the m_sessionProxy variable.

getSessionProxy( )Returns the session proxy.

SyntaxBXSession getSessionProxy( );

ReturnsA BXSession object that represents the session proxy.

DiscussionThe getSessionProxy( ) method returns the session object referenced by them_sessionProxy variable. If the variable is null, the getSessionProxy( ) methodcreates a session object and assigns it to the m_sessionProxy variable. ThegetSessionProxy( ) method is a protected method.

init( )Initializes database context.

NOTE The displayTemplate( ) method releases all database contexts.



Syntaxboolean init( );boolean init(int whichContext);

ParametersThe method has the following parameters: xy.

ReturnsA boolean value that is true if the operation was successful; otherwise, the value isfalse.

DiscussionThe first form of the method creates a context object for each context. The secondform of the method creates a context object for the specified context using a contextflag to specify the context. The init( ) method is a protected method.

releaseBXDBContext( )Releases database contexts.

Syntaxvoid releaseBXDBContext( );

DiscussionAll database contexts are released. The releaseBXDBContext( ) method is aprotected method.

verifyUserSession( )Verifies that a valid session exists.

Syntaxboolean verifyUserSession( );

ReturnsA boolean value that is true if a valid session exists; otherwise, it is false.

whichContext An integer that specifies the databasecontext.

BXBaseView Class Reference


DiscussionIf this method returns a false value, the user is not logged into BillerXpert. Youshould call this method before taking any other action in your Servlet’s doPost( )method.

CheckACL( )Checks if Access Control List (ACL) role is authorized.

Syntaxint checkACL (String perm);


Returns0 if the the specific permission is granted, or, -1 if the specific permission is notgranted.

BXBaseView Class ReferenceThe BXBaseView class is an abstract from which other view classes descend.

Methods

perm The permission to check for


Constructor

BXBaseView( ) Creates a BXBaseView object.

Context management

setBillingContext( ) Associates a billing context with this object.

setMembershipContext( ) Associates a membership context with this object.

setPaymentContext( ) Associates a payment context with this object.

setConfigContext( ) Associates a configuration context with this object.



Class Definition


Syntaxpublic abstract class BXBaseView { ... }

Context ObjectsYou can use the following context object references within your view; thesereferences are associated with context objects when you instantiate a subclass ofBXBaseView or call one of the methods defined in this class that set the context.

Syntaxprotected BXBillingContext billingContext = null;protected BXMembershipContext membershipContext = null;protected BXPaymentContext paymentContext = null;protected BXConfigContext configContext = null;

Status ObjectThe following status information can be used within a view object, if the referenceis set:

Associating a status object

set( ) Associates a status object with this object.

Debugging support

debug( ) Writes the specified message to the system output stream.

billingContext Reference to a billing context

membershipContext Reference to a membership context

paymentContext Reference to a payment context

configContext Reference to a configuration context




Syntaxprotected BXStatus status = null;

Constructors

BXBaseView( )Creates a BXBaseView object.

SyntaxBXBaseView(BXStatus stat);BXBaseView(BXBillingContext context, BXStatus stat);BXBaseView(BXMembershipContext context, BXStatus stat);BXBaseView(BXPaymentContext context, BXStatus stat);BXBaseView(BXConfigContext context, BXStatus stat);

ParametersThe constructor has the following parameters:

DiscussionThe first constructor does not associate a context with this object. Each of the otherconstructors sets the specified kind of context.

MethodsThis section describes the methods of the BXBaseView class.

debug( )Writes the specified message to the system output stream.

status Reference to the current status object.

context The context object to associate with thisview object.

stat The BXStatus object to associate with thisview object.



Syntaxvoid debug(String msg);


set( )Associates a status object with this object.

Syntaxvoid set(BXStatus stat);


setBillingContext( )Associates a billing context with this object.

Syntaxvoid setBillingContext(BXBillingContext context);


setPaymentContext( )Associates a payment context with this object.

Syntaxvoid setPaymentContext(BXPaymentContext context);

msg A string that contains the message.

stat The BXStatus object to associate with thisobject.

context The BXBillingContext object to associatewith this object.

BXConfigObj Class Reference



BXConfigObj Class ReferenceThe BXConfigObj class provides access several configuration parameters. Youshould use the static strings defined in this class instead of the methods.

Class Definition


Syntaxpublic class BXConfigObj { ... };

VariablesYou can use the following static variables within your application:

Syntaxpublic final static String BILLER_NAME_DEF

= "biller_section.biller-name";public final static String MERCHANT_ID_DEF

= "biller_section.merchant-id";

public static final String SESSION_TIMEOUT = "BX_FE_SESSION_TIME";public static final String NUM_STMTS = "BX_FE_NUM_STMTS";

public final static String BILLER_ID = BXConfigObj.getBillerID( );public final static String BILLER_NAME =

BXConfigObj.getBillerID( );public final static String MERCHANT_ID =

BXConfigObj.getMerchantID( );

context The BXPaymentContext object to associatewith this object.

BILLER_NAME_DEF Biller name definition section

MERCHANT_ID_DEF Merchant ID definition section

BXErrorCode Class Reference


BXErrorCode Class ReferenceThe BXError class defines constants for error codes; it lists all errors used by theBillerXpert front end. To define your own error codes and constants, you can createyour own subclass of this class or simply add error codes to this class.

Class Definition


Syntaxpackage netscape.billxpert.common;

public class BXErrorCode{ public final static String VALIDATE_UNKNOWN = "BXFE_000001";

public final static String UNKNOWN_ERROR = "BXFE_100000"; public final static String DB_BILLINGMGR_ERROR = "BXFE_100001"; public final static String DB_MEMBERMGR_ERROR = "BXFE_100002"; public final static String AL_INVALID_REQUEST = "BXFE_100003"; public final static String DB_PAYMENTMGR_ERROR = "BXFE_100004"; public final static String ACCESS_NOT_ALLOWED = "BXFE_100005";

SESSION_TIMEOUT Session timeout value

NUM_STMTS Number of statements

BILLER_ID Biller ID

BILLER_NAME Biller name

MERCHANT_ID Merchant ID



// Sign on view public final static String ONLINENAME_MISSING = "BXFE_001000"; public final static String PASSWORD_MISSING = "BXFE_001001"; public final static String ONLINENAME_INVALID = "BXFE_001002"; public final static String PASSWORD_INVALID = "BXFE_001003"; public final static String SESSION_CREATE_FAILED = "BXFE_001004"; public final static String USER_NOT_FOUND = "BXFE_001005"; public final static String USER_STATUS_NOTACTIVE = "BXFE_001006"; public final static String COUNTRY_MISSING = "BXFE_001007"; public final static String LANGUAGE_MISSING = "BXFE_001008";

public final static String MEM_CONTEXT_MISSING = "BXFE_001009"; public final static String UNABLE_TO_VALIDATE = "BXFE_001010"; public final static String USER_SESSION_MISSING = "BXFE_001011";

public final static String EMAIL_MISSING = "BXFE_001012"; public final static String EMAIL_INVALID = "BXFE_001013"; public final static String EMAIL_MISMATCH = "BXFE_001014";

public final static String BCA_MISSING = "BXFE_002000"; public final static String NUM_MONTH_MISSING = "BXFE_002001"; public final static String BCA_INVALID = "BXFE_002002"; public final static String NUM_MONTH_INVALID = "BXFE_002003"; public final static String BCA_NOT_FOUND = "BXFE_002004";



// simple and advance search public final static String SEARCH_BCA_MISSING = "BXFE_002500"; public final static String SEARCH_BALANCE_MISSING = "BXFE_002501"; public final static String SEARCH_AMOUNT_MISSING = "BXFE_002502"; public final static String SEARCH_DURATION_MISSING = "BXFE_002503"; public final static String SEARCH_BCA_INVALID = "BXFE_002504"; public final static String SEARCH_BALANCE_INVALID = "BXFE_002505"; public final static String SEARCH_AMOUNT_INVALID = "BXFE_002506"; public final static String SEARCH_DURATION_INVALID = "BXFE_002507"; public final static String SEARCH_TIME_INVALID = "BXFE_002508"; public final static String SEARCH_TIME_AFTER_ERROR = "BXFE_002509"; public final static String SEARCH_TIME_BEFORE_ERROR = "BXFE_002510";public final static String NOTHING_TO_SORT = "BXFE_002511";

// statement, details public final static String BILLDOC_NOT_FOUND = "BXFE_003000"; public final static String DOC_CURRENT_NOT_FOUND = "BXFE_003001"; public final static String BCA_NOT_SELECTED = "BXFE_003002"; public final static String TEMPLATE_BASE_NOT_FOUND = "BXFE_003003";

// change user profile public final static String PWD_MATCH_FAILED = "BXFE_004000"; public final static String NEW_PASSWORD_MISSING = "BXFE_004001"; public final static String REPEAT_PASSWORD_MISSING = "BXFE_004002"; public final static String NEW_PASSWORD_INVALID = "BXFE_004003"; public final static String REPEAT_PASSWORD_INVALID = "BXFE_004004";



public final static String UP_CONTACT_EMPTY = "BXFE_004500";

public final static String UP_FIN_ACCT_NOT_FOUND = "BXFE_004600";

// user registration errors public final static String REG_BCA_MISSING = "BXFE_005000"; public final static String REG_BALANCE_MISSING = "BXFE_005001"; public final static String REG_BCA_INVALID = "BXFE_005002"; public final static String REG_BALANCE_INVALID = "BXFE_005003"; public final static String REG_BANK_ROUTING_INVALID = "BXFE_005004"; public final static String REG_BANK_ACCT_INVALID = "BXFE_005005"; public final static String REG_BANK_NICKNAME_INVALID = "BXFE_005006"; public final static String REG_CC_TYPE_INVALID = "BXFE_005007"; public final static String REG_CC_NUMBER_INVALID = "BXFE_005008"; public final static String REG_CC_EXP_MONTH_INVALID = "BXFE_005009"; public final static String REG_CC_EXP_YEAR_INVALID = "BXFE_005010"; public final static String REG_CC_NICKNAME_INVALID = "BXFE_005011"; public final static String REG_FIRSTNAME_MISSING = "BXFE_005012"; public final static String REG_LASTNAME_MISSING = "BXFE_005013"; public final static String REG_FIRSTNAME_INVALID = "BXFE_005014"; public final static String REG_LASTNAME_INVALID = "BXFE_005015"; public final static String REG_MIDDLENAME_INVALID = "BXFE_005016"; public final static String REG_PREFIX_INVALID = "BXFE_005017"; public final static String REG_SUFFIX_INVALID = "BXFE_005018";



public final static String REG_CA_INVALID = "BXFE_005019"; public final static String REG_EMAIL_INVALID = "BXFE_005020"; public final static String REG_CC_BRAND_MISSING = "BXFE_005021"; public final static String REG_CC_NUMBER_MISSING = "BXFE_005022"; public final static String REG_CC_EXP_MONTH_MISSING = "BXFE_005023"; public final static String REG_CC_EXP_YEAR_MISSING = "BXFE_005024"; public final static String REG_CC_HOLDERNAME_MISSING = "BXFE_005025"; public final static String REG_CC_ADDRESS1_MISSING = "BXFE_005026"; public final static String REG_CC_CITY_MISSING = "BXFE_005027"; public final static String REG_CC_STATE_MISSING = "BXFE_005028"; public final static String REG_CC_POSTALCODE_MISSING = "BXFE_005029"; public final static String REG_CC_BRAND_INVALID = "BXFE_005030"; public final static String REG_CC_HOLDERNAME_INVALID = "BXFE_005031"; public final static String REG_CC_ADDRESS1_INVALID = "BXFE_005032"; public final static String REG_CC_CITY_INVALID = "BXFE_005033"; public final static String REG_CC_STATE_INVALID = "BXFE_005034"; public final static String REG_CC_POSTALCODE_INVALID = "BXFE_005035";

public final static String REG_CC_VISA_BAD = "BXFE_005036"; public final static String REG_CC_MASTERCARD_BAD = "BXFE_005037"; public final static String REG_CC_AMEX_BAD = "BXFE_005038"; public final static String REG_CC_DISCOVER_BAD = "BXFE_005039"; public final static String REG_CC_DINERSCLUB_BAD = "BXFE_005040";



public final static String REG_CC_ONLINENAME_MISSING = "BXFE_005041"; public final static String REG_CC_ONLINENAME_INVALID = "BXFE_005042"; public final static String REG_CC_PASSWORD_MISSING = "BXFE_005043"; public final static String REG_CC_PASSWORD_INVALID = "BXFE_005044";

public final static String REG_CC_DATE_INVALID = "BXFE_005045"; public final static String REG_CC_MOD10_FAILED = "BXFE_005046"; public final static String REG_CK_ROUTING_MISSING = "BXFE_005047"; public final static String REG_CK_ACCT_MISSING = "BXFE_005048"; public final static String REG_CK_ROUTING_INVALID = "BXFE_005049"; public final static String REG_CK_ACCT_INVALID = "BXFE_005050"; public final static String REG_CK_NICKNAME_INVALID = "BXFE_005051"; public final static String REG_CC_BAD_CARD_FORMAT = "BXFE_005052"; public final static String REG_CC_NUMBER_BLANK_INVALID = "BXFE_005053";

public final static String REG_EMAIL_MISSING = "BXFE_005054"; public final static String REG_PHONE_MISSING = "BXFE_005055";

public final static String REG_PAY_METHOD_MISSING = "BXFE_005056"; public final static String REG_CK_MOD10_FAILED = "BXFE_005057"; public final static String REG_CK_BAD_ROUTING_FORMAT = "BXFE_005058";public final static String REG_CK_NICKNAME_DUPLICATE = "BXFE_005059";public final static String REG_CK_NICKNAME_MISSING = "BXFE_005110";

// bca related view



public final static String BCA_ADDRESS1_INVALID = "BXFE_005500"; public final static String BCA_ADDRESS2_INVALID = "BXFE_005501"; public final static String BCA_ADDRESS3_INVALID = "BXFE_005502"; public final static String BCA_CITY_INVALID = "BXFE_005503"; public final static String BCA_STATE_INVALID = "BXFE_005504"; public final static String BCA_POSTALCODE_INVALID = "BXFE_005505"; public final static String BCA_ADDRESS1_MISSING = "BXFE_005506"; public final static String BCA_CITY_MISSING = "BXFE_005507"; public final static String BCA_STATE_MISSING = "BXFE_005508"; public final static String BCA_POSTALCODE_MISSING = "BXFE_005509";

// pay view public final static String PAY_BCA_NOT_FOUND = "BXFE_006000"; public final static String PAY_NOT_SELECT = "BXFE_006001"; public final static String PAY_METHOD_NOT_SELECT = "BXFE_006002"; public final static String PAY_INVALID_PAYDATE = "BXFE_006003"; public final static String PAY_AFTER_DUEDATE = "BXFE_006004"; public final static String PAY_BEFORE_CURRENTDATE = "BXFE_006005"; public final static String PAYMENT_CANCEL_NOT_SELECT = "BXFE_006006"; public final static String PAY_PAST_DUE = "BXFE_006007"; public final static String PAY_ERROR = "BXFE_006008";public final static String PAY_AMOUNT_ERROR = "BXFE_006009";public final static String PAY_CREDIT_REQUIRED = "BXFE_006010";

// Error Code related to AutoPay

BXSession Class Reference


public final static String NO_ACCT_FOR_AUTOPAY = "BXFE_006200"; public final static String NO_USER_FOR_ACCT = "BXFE_006201"; public final static String FAILED_TO_DSP_ADD_AUTOPAY = "BXFE_006202"; public final static String NO_AUTOPAY_SCHEDULE = "BXFE_006203"; public final static String FAILED_TO_DSP_EDIT_AUTOPAY = "BXFE_006204"; public final static String FAILED_TO_ADD_AUTOPAY = "BXFE_006205"; public final static String FAILED_TO_UPDATE_AUTOPAY = "BXFE_006206"; public final static String FAILED_TO_DELETE_AUTOPAY = "BXFE_006207"; public final static String AUTOPAY_AMT_ERR = "BXFE_006208"; public final static String AUTOPAY_SCHEDULE_EJBREMOVE_FAILED = "BXFE_006209"; public final static String IGS_FAILED = "BXFE_006210";

}

BXSession Class ReferenceThe BXSession class represents a BillerXpert session. It contains the user profileinformation of the user that is currently logged in. You use the BXSession object tomaintain state information within a Servlet and to transfer this informationbetween Servlets. Each BillerXpert Servlet has access to the session object by callingthe Servlet’s getBXSession( ) method.



MethodsTable 3-4 Summary List

Constructor

BXSession( ) Creates a BXSession object.

Session state maintenance

isDirty( ) Determines whether the session data has changed.

setDirty( ) Specifies that the session data has changed.

saveSession( ) Save the session data for use by another Servlet.

User and service profile manipulation

isUserProfile( ) Determines whether a user profile exists.

setUserProfile( ) Specifies that a user profile exists.

getProfileExtension( ) Determines the profile extension data.

setProfileExtension( ) Specifies the profile extension data.

getServiceExtension( ) Determines the service extension data.

setServiceExtension( ) Specifies the service extension data.

parseExtension( ) Determines the elements of an extension field.

Getting and setting object fields

Advertising support

getAdTargetString( ) Creates a target string for an advertisement based on userprofile options.

Getting and setting object fields

saveValString( ) Specifies a value for a session data field and saves all sessiondata.

setValString( ) Specifies a value for a session data field.

getUserID( ) Determines the user ID.

setUserID( ) Specifies the user ID.

getAccount( ) Determines the account number.

setAccount( ) Specifies the account number.

getPrefix( ) Determines the name prefix.

setPrefix( ) Specifies the name prefix.

getSuffix( ) Determines the name suffix.



setSuffix( ) Specifies the name suffix.

getCountry( ) Determines the country.

setCountry() Specifies the country.

getEmulationID() Determines the emulation ID.

setEmulationID() Specifies the emulation ID.

getBillerID() Determines the BillerID.

setBillerID() Specifies the BillerID.

getLocalelanguage() Determines the current locale language..

setLocalLanguage() Specifies the current local language.

getLastName( ) Determines the last name.

setLastName( ) Specifies the last name.

getFirstName( ) Determines the first name.

setFirstName( ) Specifies the first name.

getMiddleName( ) Determines the middle name.

setMiddleName( ) Specifies the middle name.

getNickName( ) Determines the nick name.

setNickName( ) Specifies the nick name.

getDescription( ) Determines the description.

setDescription( ) Specifies the description.

getAddress( ) Determines the address.

setAddress( ) Specifies the address.

getDayPhone( ) Determines the day-time phone number.

setDayPhone( ) Specifies the day-time phone number.

getNightPhone( ) Determines the night-time phone number.

setNightPhone( ) Specifies the night-time phone number.

getFaxNumber( ) Determines the fax number.

setFaxNumber( ) Specifies the fax number.

getEmail( ) Determines the e-mail address.

setEmail( ) Specifies the e-mail address.




getOnlineName( ) Determines the online name.

setOnlineName( ) Specifies the online name.

getPassword( ) Determines the password.

setPassword( ) Specifies the password.

getLanguage( ) Determines the language.

setLanguage( ) Specifies the language.

getPrimaryContact( ) Determines the primary contact.

setPrimaryContact( ) Specifies the primary contact.

getSecondaryContact( ) Determines the secondary contact.

setSecondaryContact( ) Specifies the secondary contact.

getBilltType() Determines the bill type.

setBillType() Specifies the bill type.

getSalutation( ) Determines the salutation.

setSalutation( ) Specifies the salutation.

getDefaultPaymentMethod( ) Determines the default payment method.

setDefaultPaymentMethod( ) Specifies the default payment method.

getNumberMonth( ) Determines the number of months data to display.

setNumberMonth( ) Specifies the number of months data to display.

getSelectedAccount( ) Determines the current account.

setSelectedAccount( ) Specifies the current account.

getSortField( ) Determines the sort field.

setSortField( ) Specifies the sort field.

getBCAs( ) Determines the list of billing customer accounts.

setBCAs( ) Specifies the list of billing customer accounts.

getSearchAttributes( ) Determines the search attributes.

setSearchAttributes( ) Specifies the search attributes.

Debugging

debug( ) Displays session data.




Class Definition


Syntaxclass BXBaseAppLogic extends AppLogic { ... }

Constructors

BXSession( )Creates a BXSession object.

SyntaxBXSession(IAppLogic logic, ISession2 session);


DiscussionYou do not typically create a BXSession object directly; rather, you call yourServlet’s createBXSession( ) method.

MethodsThis section describes the methods of the BXSession class.

debug( )Displays session data.

Syntaxvoid debug( );

logic Your application logic object

session The current IAS session object.



DiscussionAll session object key and value pairs are written as informational messages to thelog file.

getAccount( )Determines the account number.

SyntaxString getAccount( );

ReturnsA string that contains the customer’s account number.

DiscussionThis method returns the value associated with the “Account” key in the sessionobject.

getAddress( )Determines the address.

SyntaxString getAddress( );

ReturnsA string that contains the address.

DiscussionThis method returns the value associated with the “Address” key in the sessionobject.

getAdTargetString( )Creates a target string for an advertisement based on user profile options.

SyntaxString getAdTargetString( )

ReturnsA string that contains the target information.



DiscussionThe target string consists of the e-mail address, language, and profile extensions,separated by delimiters.

getBillerID( )Determines the BillerID associated with the user.

SyntaxString getBillerID( )

ReturnsA string that contains the BillerID.

DescriptionThis method returns the BillerID associated with this session.

getBillType( )Determines the Bill Type associated with the user.

SyntaxString getBillType( )

ReturnsA string that contains the Bill Type.

DescriptionThis method returns a String value that contains the Bill Type.

getCountry( )Determines the Country associated with the user.

SyntaxString getCountry( )

ReturnsA string that specifies the default Country associated with the Biller.

DescriptionThis method gets the Country associated with this Biller.



getEmulationID( )Determines the EmulationID.

SyntaxString getEmulationID( )

ReturnsA string that specifies the Emulation ID.

DescriptionThis method gets the Emulation ID associated with this Biller.

getLocalelLanguage( )Determines the Locale Language set for this Biller.

SyntaxString getLocalelanguage( )

ReturnsA string that specifies the Locale Language set for this Biller.

DescriptionThis method gets the Locale Language set for this Biller.

setBillerId( )Specifies the Biller Id associated with the user.

Syntaxvoid setBillerId( )

ParametersThe Method has the following parameters:

DescriptionThis method sets the Biller ID associated with this session.

val A string that specifies the Biller ID.



setBillType( )Specifies the Bill Type associated with the user.

Syntaxvoid setBillType(String val)


DescriptionThis method sets the Bill Type associated with this session.

setCountry( )Specifies the Country associated with the Biller.

Syntaxvoid setCountry(String val)


DescriptionThis method sets the Country associated with this Biller taking the value from theindex page.

setEmulationID( )Specifies the Emulation ID.

Syntaxvoid setEmulationID(String val)

val A string that specifies the Biller Type.

val A string that specifies the Country.




DescriptionThis method sets the Emulation ID associated with this Biller.

setLocaleLanguage( )Specifies the Locale Language set for the Biller.

Syntaxvoid setLocalelanguage(String val)


DescriptionThis method sets the Locale Language set for the Biller.

getBCAs( )Determines the list of billing customer accounts.

SyntaxVector getBCAs( );

ReturnsA vector object that contains the accounts.

DiscussionThis method returns the value associated with the “bcas” key in the session object.

getDayPhone( )Determines the day-time phone number.

val A string that specifies the Emulation ID.

val A string that specifies the Locale Language.



SyntaxString getDayPhone( );

ReturnsA string that contains the phone number.

DiscussionThis method returns the value associated with the “DayPhone” key in the sessionobject.

getDefaultPaymentMethod( )Determines the default payment method.

SyntaxString getDefaultPaymentMethod( );


DiscussionThis method returns the value associated with the “DefaultPaymentMethod” keyin the session object.

getDescription( )Determines the description.

SyntaxString getDescription( );

ReturnsA string that contains the description.

DiscussionThis method returns the value associated with the “Description” key in the sessionobject.

getEmail( )Determines the e-mail address.



SyntaxString getEmail( );

ReturnsA string that contains the e-mail address.

DiscussionThis method returns the value associated with the “email” key in the session object.

getFaxNumber( )Determines the fax number.

SyntaxString getFaxNumber( );

ReturnsA string that contains the fax number.

DiscussionThis method returns the value associated with the “FaxNumber” key in the sessionobject.

getFirstName( )Determines the first name.

SyntaxString getFirstName( );

ReturnsA string that contains the name.

DiscussionThis method returns the value associated with the “Firstname” key in the sessionobject.

getLanguage( )Determines the language.

SyntaxString getLanguage( );



ReturnsA string that contains the language.

DiscussionThis method returns the value associated with the “Language” key in the sessionobject.

getLastName( )Determines the last name.

SyntaxString getLastName( );


DiscussionThis method returns the value associated with the “Lastname” key in the sessionobject.

getMiddleName( )Determines the middle name.

SyntaxString getMiddleName( );


DiscussionThis method returns the value associated with the “Middlename” key in thesession object.

getNickName( )Determines the nick name.

SyntaxString getNickName( );




DiscussionThis method returns the value associated with the “NickName” key in the sessionobject.

getNightPhone( )Determines the night-time phone number.

SyntaxString getNightPhone( );


DiscussionThis method returns the value associated with the “NightPhone” key in the sessionobject.

getNumberMonth( )Determines the number of months data to display.

Syntaxint getNumberMonth( );

ReturnsA string that contains the number.

DiscussionThis method returns the value associated with the “NumberMonth” key in thesession object.

getOnlineName( )Determines the online name.

SyntaxString getOnlineName( );




DiscussionThis method returns the value associated with the “OnlineName” key in thesession object.

getPassword( )Determines the password.

SyntaxString getPassword( );


DiscussionThis method returns the value associated with the “Password” key in the sessionobject

getPrefix( )Determines the name prefix.

SyntaxString getPrefix( );

ReturnsA string that contains the prefix.

DiscussionThis method returns the value associated with the “Prefix” key in the sessionobject.

getPrimaryContact( )Determines the primary contact.

SyntaxString getPrimaryContact( );



ReturnsA string that contains the primary contact.

DiscussionThis method returns the value associated with the “PrimaryContact” key in thesession object.

getProfileExtension( )Determines the profile extension data.

SyntaxString getProfileExtension( );

ReturnsA string that contains the profile extension.

DiscussionThis method returns the value associated with the “ProfileExtension” key in thesession object.

getSalutation( )Determines the salutation.

SyntaxString getSalutation( );

ReturnsA string that contains the salutation.

DiscussionThis method returns the value associated with the “Salutation” key in the sessionobject.

getSearchAttributes( )Determines the search attributes.

SyntaxString getSearchAttributes( );



ReturnsA string that contains the search attributes.

DiscussionThis method returns the value associated with the “searchAttributes” key in thesession object.

getSecondaryContact( )Determines the secondary contact.

SyntaxVector getSecondaryContact( );

ReturnsA vector that contains the secondary contacts.

DiscussionThis method returns the value associated with the “SecondaryContact” key in thesession object.

getSelectedAccount( )Determines the current account.

SyntaxString getSelectedAccount( );

ReturnsA string that contains the account.

DiscussionThis method returns the value associated with the “SelectedAccount” key in thesession object.

getServiceExtension( )Determines the service extension data.

SyntaxString getServiceExtension( );



ReturnsA string that contains the service extension.

DiscussionThis method returns the value associated with the “ServiceExtension” key in thesession object.

getSuffix( )Determines the name suffix.

SyntaxString getSuffix( );

ReturnsA string that contains the suffix.

DiscussionThis method returns the value associated with the “Suffix” key in the sessionobject.

getUserID( )Determines the user ID.

SyntaxString getUserID( );

ReturnsA string that contains the ID.

DiscussionThis method returns the value associated with the “UserID” key in the sessionobject.

isUserProfile( )Determines whether a user profile exists.

Syntaxboolean isUserProfile( );



ReturnsA boolean value that is true if the user profile is set; otherwise it is false.

DiscussionThis method returns true if the value associated with the “isUserProfileSet” key inthe session object is 1; otherwise it returns false.

parseExtension( )Determines the elements of an extension field.

SyntaxHashtable parseExtension(String ext);


ReturnsA Hashtable object that hashes the keys of the extension and associates them withtheir respective values in the hash table.

DiscussionThe format of an extension data is key=value and multiple elements are separatedby commas.

saveValString( )Specifies a value for a session data field and saves all session data.

Syntaxvoid saveValString(String key, String value);


ext A string that contains the extension data.

key A string that specifies the key.

value A string that specifies the value



DiscussionThe saveValString( ) method saves all session data.

setAccount( )Specifies the account number.

Syntaxvoid setAccount( String value );



setAddress( )Specifies the address.

Syntaxvoid setAddress(String value);


DiscussionThis method changes the value associated with the “Address” key in the sessionobject.

setBCAs( )Specifies the list of billing customer accounts.

value A string that specifies the account.

value A string that specifies the address.



Syntaxvoid setBCAs(Vector bcaList);


DiscussionThis method changes the value associated with the “bcas” key in the session object.

setDayPhone( )Specifies the day-time phone number.

Syntaxvoid setDayPhone( String value);


DiscussionThis method changes the value associated with the “DayPhone” key in the sessionobject.

isUserProfile( )Determines whether a user profile exists.

Syntaxboolean isUserProfile( );

ReturnsA boolean value that is true if the user profile is set; otherwise it is false.

bcaList A Vector object that specifies the accounts.

value A string that specifies the phone number.



DiscussionThis method returns true if the value associated with the “isUserProfileSet” key inthe session object is 1; otherwise it returns false.

parseExtension( )Determines the elements of an extension field.





saveValString( )Specifies a value for a session data field and saves all session data.

Syntaxvoid saveValString(String key, String value);


DiscussionThe saveValString( ) method saves all session data.


key A string that specifies the key

value A string that specifies the value



setAccount( )Specifies the account number.

Syntaxvoid setAccount( String value );



setAddress( )Specifies the address.

Syntaxvoid setAddress(String value);


DiscussionThis method changes the value associated with the “Address” key in the sessionobject.

setBCAs( )Specifies the list of billing customer accounts.

Syntaxvoid setBCAs(Vector bcaList);

value A string that specifies the account.

value A string that specifies the address.




DiscussionThis method changes the value associated with the “bcas” key in the session object.

setDayPhone( )Specifies the day-time phone number.

Syntaxvoid setDayPhone( String value);


DiscussionThis method changes the value associated with the “DayPhone” key in the sessionobject.

setDefaultPaymentMethod( )Specifies the default payment method.

Syntaxvoid setDefaultPaymentMethod(String value);


bcaList A Vector object that specifies the accounts.


value A string that specifies the payment method.



DiscussionThis method changes the value associated with the “DefaultPaymentMethod” keyin the session object.

setDescription( )Specifies the description.

Syntaxvoid setDescription( String value);


DiscussionThis method changes the value associated with the “Description” key in the sessionobject.

setFaxNumber( )Specifies the fax number.

Syntaxvoid setFaxNumber( String value);


DiscussionThis method changes the value associated with the “FaxNumber” key in thesession object.

setFirstName( )Specifies the first name.

value A string that specifies the description.

value A string that specifies the fax number.



Syntaxvoid setFirstName( String value );


DiscussionThis method changes the value associated with the “FirstName” key in the sessionobject.

setLanguage( )Specifies the language.

Syntaxvoid setLanguage( String value );


DiscussionThis method changes the value associated with the “Language” key in the sessionobject.

setLastName( )Specifies the last name.

Syntaxvoid setLastName( String value );

value A string that specifies the name.

value A string that specifies the language.




DiscussionThis method changes the value associated with the “LastName” key in the sessionobject.

setMiddleName( )Specifies the middle name.

Syntaxvoid setMiddleName( String value );


DiscussionThis method changes the value associated with the “MiddleName” key in thesession object.

setNickName( )Specifies the nick name.

Syntaxvoid setNickName( String value );







DiscussionThis method changes the value associated with the “NickName” key in the sessionobject.

setNightPhone( )Specifies the night-time phone number.

Syntaxvoid setNightPhone( String value);


DiscussionThis method changes the value associated with the “NightPhone” key in thesession object.

setNumberMonth( )Specifies the number of months data to display.

Syntaxvoid setNumberMonth(int value);


DiscussionThis method changes the value associated with the “NumberMonth” key in thesession object.

setOnlineName( )Specifies the online name.


value A string that specifies the number ofmonths.



Syntaxvoid setOnlineName( String value);


DiscussionThis method changes the value associated with the “OnlineName” key in thesession object.

setPassword( )Specifies the password.

Syntaxvoid setNightPhone( String value);


DiscussionThis method changes the value associated with the “Password” key in the sessionobject.

setPrefix( )Specifies the name prefix.

Syntaxvoid setPrefix( String value );



value A string that specifies the password.

value A string that specifies the prefix.



DiscussionThis method changes the value associated with the “Prefix” key in the sessionobject.

setPrimaryContact( )Specifies the primary contact.

Syntaxvoid setPrimaryContact( String value);


DiscussionThis method changes the value associated with the “PrimaryContact” key in thesession object.

setProfileExtension( )Specifies the profile extension data.

Syntaxvoid setProfileExtension( String value);


DiscussionThis method changes the value associated with the “ProfileExtension” key in thesession object.

setSalutation( )Specifies the salutation.

value A string that specifies the primary contact.

value A string that specifies the profile extension.



Syntaxvoid setSalutation(String value);


DiscussionThis method changes the value associated with the “Salutation” key in the sessionobject.

setSearchAttributes( )Specifies the search attributes.

Syntaxvoid setSearchAttributes(String value);


DiscussionThis method changes the value associated with the “searchAttributes” key in thesession object.

setSecondaryContact( )Specifies the secondary contact.

Syntaxvoid setSecondaryContact( Vector value);


value A string that specifies the salutation.

value A string that specifies the salutation

value A vector that specifies the secondarycontacts.



DiscussionThis method changes the value associated with the “SecondaryContact” key in thesession object.

setSelectedAccount( )Specifies the current account.

Syntaxvoid setSelectedAccount( Vector value);


DiscussionThis method changes the value associated with the “SelectedAccount” key in thesession object.

setServiceExtension( )Specifies the service extension data.

Syntaxvoid setServiceExtension( String value);


DiscussionThis method changes the value associated with the “ServiceExtension” key in thesession object.

setSortField( )Specifies the sort field.

value A vector that specifies the account.

value A string that specifies the service extension.



Syntaxvoid setSortField( String value );


DiscussionThis method changes the value associated with the “SortField” key in the sessionobject.

setSuffix( )Specifies the name suffix.

Syntaxvoid setSuffix( String value );


DiscussionThis method changes the value associated with the “Suffix” key in the sessionobject.

setUserID( )Specifies the user ID.

Syntaxvoid setUserID(String value);


value A string that specifies the sort field.

value A string that specifies the suffix.

value A string that specifies the ID.



DiscussionThis method changes the value associated with the “UserID” key in the sessionobject.

setValString( )Specifies a value for a session data field and saves all session data.

Syntaxvoid setValString(String key, String value);


DiscussionThis method changes the value associated with the specified key in the sessionobject.

See AlsoThe “saveValString( )”.

setUserProfile( )Specifies that a user profile exists.

Syntaxvoid setUserProfile(boolean value);


key A string that specifies the key.

value A string that specifies the new value

value A boolean value that is true to specify that auser profile exists or false to specify that itdoes not exist.

BXBaseBean Class Reference


DiscussionThis method changes the value associated with the “isUserProfileSet” key in thesession object to 1 if the value parameter is true; otherwise, it is set to false.

BXBaseBean Class ReferenceInstances of the BXBaseBean class represent BillerXpert template data. Youtypically create a BXBaseBean object that defines the rows of data you want todisplay.

Methods

Class Definition

Packagenetscape.billxpert.user

Syntaxpublic class BXBaseBean { ... }

Data MembersThe following data members are protected:


Constructor

BXBaseBean( ) Creates a BXBasebean object.

Template manipulation

toString( ) Displays a date in the local locale.

format( ) Formats a double-precision floating point number.

Debugging support

log( ) Writes a message to the log.

BXBaseBean Class Reference


Syntaxprotected int maxFractionDigits;

Constructors

BXBaseBeanCreates a BXBaseBean object.

Syntaxpublic BXBaseBean;

MethodsThis section describes the methods of the BXBaseBean class.

format( )Formats a double-precision floating point number.

SyntaxString format(double value, int maxDigits);


ReturnsA string that contains the formatted number.

log( )Writes a message to the log.

maxFractionDigits Number of digits to the right of the decimalpoint, which is 2 by default.

value The double-precision floating point numberto format.

maxDigits The number of digits to include to the rightof the decimal point.

BXTemplateBeanMapBasic Class Reference


Syntaxvoid log(String msg);


toString( )Displays a date in the local locale.

SyntaxString toString(Date date);


BXTemplateBeanMapBasic Class ReferenceInstances of the BXTemplateBeanMapBasic class represent BillerXpert templatedata. You typically create a BXTemplateBeanMapBasic object that definesindividual pieces of data you want to display.

Methods

msg A string that contains the message todisplay.

data A Date object that contains the date.


Constructor

BXTemplateBeanMapBasic( ) Creates a BXTemplateBeanMapBasic object.

Advertising support

setOAS( ) Sets up the advertisement’s image.

Template manipulation

toString( ) Displays a date in the local locale.



Class Definition


Syntaxpublic class BXTemplateBeanMapBasic { ... }

BXTemplateBeanMapBasic Data MembersThe following data members are protected:

Syntaxprotected int maxFractionDigits;HttpServletRequest req;

Constructors

BXTemplateBeanMapBasicCreates a BXTemplateBeanMapBasic object.

SyntaxBXTemplateBeanMapBasic(HttpServletRequest, req);


set( ) Adds a double-precision floating point number to thistemplate object.

vectorToString( ) Creates a string from a vector of data.

Debugging support

log( ) Displays a message to the log.

maxFractionDigits Number of digits to the right of the decimalpoint.




BXTemplateBeanMapBasic( );


MethodsThis section describes the methods of the BXTemplateBeanMapBasic class.





log( )Displays a message to the log.

Syntaxvoid log(String msg);

req The request object.






set( )Adds a double-precision floating point number to this template object.

Syntaxvoid set(String key, double value, int maxDigits);


setOAS( )Sets up the advertisement’s image.

Syntaxvoid setOAS( );

DiscussionIf OAS is installed, this method calls the getAdURI( ) method to determine whichadd to display. If the getAdURI( ) method returns an empty string, as in the casewhen OAS is not installed, the getAdURI( ) method returns the following imagetag:

<img src=\"/telco/images/Ads/dlj_dljwin21_banner.gif\" alt=\"AD\"border=0 WIDTH=468 HEIGHT=60>

msg A string that contains the message todisplay.

key A string that contains the key used in theHTML template.





toString( )Displays a date in the local locale.

SyntaxString toString(Date date);


ReturnsA string that contains the date.

vectorToString( )Creates a string from a vector of data.

SyntaxString vectorToString(Vector list);


ReturnsA string that contains the list data.

DiscussionEach element of the vector is cast to a string. The result of the cast is appended tothe returned string. The elements of the vector are separated by the HTML <br> tagin the string.

data A Date object that contains the date.

list A Vector object that contains the items toconvert.

BXTemplateUtil Class Reference


BXTemplateUtil Class ReferenceThe BXTemplateUtil class provides several static methods that you can use in yourderived subclasses of BXBaseBean and BXTemplateBeanMapBasic.

Methods

Class Definition


Syntaxpublic class BXTemplateUtil { ... }

MethodsThis section describes the methods of the BXTemplateUtil class.

addressToString( )Creates a string from an IBXAddress object.

Syntaxstatic String addressToString(IBXAddress address);


Table 3-7

Convenience methods

addressToString( ) Creates a string from an IBXAddress object.


dateToString( ) Creates a string from a Date object.

address An IBXAddress object that contains theaddress.

BXTemplateUtil Class Reference



DiscussionThe string contains the three address lines separated by the HTML <br> tag,followed by the city, state, and postal code in the format of ‘<br>city, state, postal’.





dateToString( )Creates a string from a Date object.

Syntaxstatic String dateToString(Date date)





date A Date object that contains the date.

BXValidateView Class Reference


DiscussionThe format of the date is ‘day, month date, year’, such as ‘Saturday, July 12, 1997’.

BXValidateView Class ReferenceThe BXValidateView class is an abstract class from which validation view classesare derived. Your subclass must implement the validate( ) and setError( ) methods.

Methods

Class Definition


Syntaxpublic abstract class BXValidateView { ... }


Constructor

BXValidateView( ) Creates a BXValidateView object.

Abstract methods

validate( ) Performs validation of input parameters.

setError( ) Specifies the input parameters that contain errors.

Utility methods

parmCount( ) Determines the number of parameters to validate.

getParmList( ) Obtains the list of input parameters.

insertError( ) Adds a parameter to the list of errors.

getNumErrors( ) Determines the number of errors.

getMinLength( ) Determines the minimum length allowed for a parameter.

printInParms( ) Writes the list of input parameters to the log file.



VariablesThe following IValList objects and status information can be used within yourAppLogic:

Syntaxprotected IValList parmList;protected IValList errorList;protected BXStatus status;

Constructors

BXValidateViewCreates a BXValidateView object.

SyntaxBXValidateView( );

DiscussionYour subclass constructor should call this constructor.

MethodsThis section describes the methods of the BXValidateView class.

getMinLength( )Determines the minimum length allowed for a parameter.

Syntaxstatic int getMinLength(String className, String attrName);

parmList An IValList object that contains theparameters to be validated.

errorList An IValList object that contains theparameters that failed validation.

status Reference to the stackable status object.




ReturnsAn integer that specifies the minimum length.

DiscussionThe minimum value is stored in the tabledef.conf file.

See AlsoFor information about the tabledef.conf file, see “Configuring TableDefinitions”.

getNumErrors( )Determines the number of errors.

Syntaxint getNumErrors( );

ReturnsAn integer that specifies the number of errors.

getParmList( )Obtains the list of input parameters.

SyntaxIValList getParmList( );

ReturnsAn IValList object that specifies the number of errors.

insertError( )Adds a parameter to the list of errors.

className The name of the class in which theparameter is defined.

attrName The name of the input parameter.



Syntaxvoid insertError(String fieldName, int errorCode);


parmCount( )Determines the number of parameters to validate.

Syntaxint parmCount( );

ReturnsAn integer that specifies the number of parameters.

printInParms( )Writes the list of input parameters to the log file.

Syntaxvoid printInParms( );

DiscussionUse this method for debugging only; it will decrease performance. TheprintInParms( ) method is a protected method.

setError( )Specifies the input parameters that contain errors.

Syntaxabstract void setError( );

DiscussionThe setError( ) method determines the parameters that are invalid and sets theappropriate error code in the status object. You must implement a setError( )method in your derived subclass. The setError( ) method is a protected method.

fieldName The a string that contains the name of theinput parameter.

errorCode An integer that specifies the error.

BXValidateAttribute Class Reference


ExampleSee “Exercise 7,” on page 64.

validate( )Performs validation of input parameters.

Syntaxabstract boolean validate( );

ReturnsA boolean value that is true if the input parameter is valid; otherwise the value isfalse.

DiscussionYou must implement a validate( ) method in your derived subclass.

ExampleSee “Exercise 7.”

BXValidateAttribute Class ReferenceThe BXValidateAttribute class represents the validation criteria. ABXValidateAttribute object specifies the criteria for a single attribute or parameter.A BXValidateView object typically uses a list of BXValidateAttribute objects toperform validation.

Methods


Constructor

BXValidateAttribute( ) Creates a BXValidateAttribute object.

Getting attribute characteristics

getAttribute( ) Determines the attribute name.

getAttributeType( ) Determines the attribute type.

getFormatString( ) Determines the format string.

isRequired( ) Determines whether the attribute is required.



Class Definition


Syntaxpublic class BXValidateAttribute { ... }

Constructors

BXValidateAttributeCreates a BXValidateAttribute object.

SyntaxBXValidateAttribute(String field, int type);BXValidateAttribute( String field,

int type, String format, boolean req,int min,int max);


getMin( ) Determines the minimum length allowed for an attribute.

getMax( ) Determines the maximum length allowed for an attribute.

getDateMin( ) Determines the minimum date allowed for an attribute.

setDateMin( ) Specifies the minimum date allowed for an attribute.

getDateMax( ) Determines the maximum date allowed for an attribute.

setDateMax( ) Specifies the maximum date allowed for an attribute.

field A string that contains the attribute name.

type An integer that specifies the attribute type.




ExampleThe following code adds two BXValidateAttribute objects to a list of validationcriteria:

int oMinLength = 2;int oMaxLength = BXValidateView.getMaxLength("BXCustomerProfile", "LOGINNAME");int pMinLength = 2;int pMaxLength = BXValidateView.getMaxLength("BXCustomerProfile", "PASSWORD");Vector list = new Vector(2);list.addElement(new BXValidateAttribute(ONLINE_NAME, BXValidator.BX_TYPE_STRING, "", true, oMinLength, oMaxLength));list.addElement(new BXValidateAttribute(PASSWORD, BXValidator.BX_TYPE_STRING, "", true, pMinLength, pMaxLength));

See AlsoFor information about attribute types, see “Attribute Types.”

MethodsThis section describes the methods of the BXValidateAttribute class.

getAttribute( )Determines the attribute name.

SyntaxString getAttribute( );

format A string that contains the format of a stringattribute.

req A boolean value that specifies whether theattribute is required (true) or not (false).

min An integer that specifies the minimumvalue.

max An integer that specifies the maximumvalue.



ReturnsA string that specifies the name.

getAttributeType( )Determines the attribute type.

Syntaxint getAttributeType( );

ReturnsAn integer that specifies the type.

See AlsoFor information about attribute types, see “Attribute Types.”

getDateMax( )Determines the maximum date allowed for an attribute.

SyntaxDate getDateMin( );

ReturnsA Date object that specifies the date.

getDateMin( )Determines the minimum date allowed for an attribute.

SyntaxDate getDateMin( );

ReturnsA Date object that specifies the date.

getFormatString( )Determines the format string.

SyntaxString getFormatString( );



ReturnsA string that specifies the format.

getFormatString( )Determines the format string.

SyntaxString getFormatString( );

ReturnsA string that specifies the format.

getMax( )Determines the maximum length allowed for an attribute.

Syntaxint getMax( );

ReturnsAn integer that specifies the maximum value.

getMin( )Determines the minimum length allowed for an attribute.

Syntaxint getMin( );

ReturnsAn integer that specifies the minimum value.

isRequired( )Determines whether the attribute is required.

Syntaxboolean isRequired( );

ReturnsA boolean value that is true if the attribute is required; otherwise, it is false.

BXValidator Class Reference


setDateMax( )Specifies the maximum date allowed for an attribute.

Syntaxvoid setDateMax(Date max);


setDateMin( )Specifies the minimum date allowed for an attribute.

Syntaxvoid setDateMin(Date min);


BXValidator Class ReferenceThe BXValidator class provides a static validate( ) method that you can use in yourBXValidateView subclass to perform validation. The BXValidator class alsoprovides attribute type definitions, which you can use when you create aBXValidateAttribute object.

MethodsSummary list:

max A Date object that specifies the date.

min A Date object that specifies the date.

Validation

validate( ) Performs validation of a vector of elementsassociated with a validation view.

BXValidator Class Reference


Class Definition


Syntaxpublic class BXValidator { ... }

Attribute TypesYou can use the following attribute types to specify the kind of attribute:

Syntaxpublic static final int BX_TYPE_CURRENCY = 0;public static final int BX_TYPE_DATETIME = 1;public static final int BX_TYPE_DOUBLE = 2;public static final int BX_TYPE_EMAIL = 3;public static final int BX_TYPE_INT = 4;public static final int BX_TYPE_PERCENT = 5;public static final int BX_TYPE_PHONE = 6;public static final int BX_TYPE_STRING = 7;public static final int BX_TYPE_URL = 8;public static final int BX_TYPE_REGEXP = 9;

BX_TYPE_CURRENCY Currency

BX_TYPE_DATETIME Date and time

BX_TYPE_DOUBLE Double

BX_TYPE_EMAIL E-mail

BX_TYPE_INT Integer

BX_TYPE_PHONE Phone number

BX_TYPE_STRING String

BX_TYPE_URL URL

BX_TYPE_REGEXP Regular expression

BXViewUtil Class Reference


MethodsThis section describes the methods of the BXValidator class.

validate( )Performs validation of a vector of elements associated with a validation view.

SyntaxStatic boolean validate (Vector elements, BXValidateView view)

ParametersThe method has the following parameters

ReturnsA boolean value that is true if all elements of the vector are valid; otherwise, thevalue is false.

DiscussionThe validate( ) method performs validation of the data in the specified validationview object using the criteria in the vector of elements. The validate( ) methodmatches each attribute name in the vector with the key in the view object’sparameter list and performs validation using the associated criteria. An entry isinserted into the view’s error list if the data is not valid. The validate( ) method isstatic.

BXViewUtil Class ReferenceThe BXViewUtil class provides validation and conversion methods that you canuse within your BXValidateView subclass.

elements A Vector object that contains references toBXValiidateAttribute objects that identifythe attributes to validate and the criteria touse.

view A BXValidateView object that contains thedata values to validate.



Methods

Class Definition


Syntaxpublic class BXViewUtil { ... }

MethodsThis section describes the methods of the BXViewUtil class.


Validation

ccValidate( ) Performs credit card validation.

routingNumberValidate Performs routing number validation.

Conversion

stringToVector( ) Converts a string to a vector.

vectorToString( ) Converts a vector to a string.

stringToAddress( ) Converts a string to an address.

addressToString( ) Converts an address to a string.

stringToDate( ) Converts a string to a date using the default format.

stringToDateLongFormat( )

Converts a string to a date using the long format.

getYear( ) Converts a year to a string that contains two digits.

getYearLong( ) Converts a year to a string that contains four digits.

getMonthNumber( ) Converts a month into its numeric representation.

getMonthString( ) Converts a string that contains the numeric month into itsname.

parseExtension( ) Creates a hash table with the contents of an extension field.



addressToString( )Converts an address to a string.

Syntaxstatic String addressToString(IBXAddress address);



DiscussionThe string contains the three address lines separated by the HTML <br> tag,followed by the city, state, and postal code in the format of ‘<br>city, state, postal’.

ccValidate( )Performs credit card validation.

Syntaxstatic boolean ccValidate( BXStatus status,

String cardBrand,String cardNumber)


ReturnsA boolean value that is true if the brand and number are valid; otherwise it is false.

address An IBXAddress object that contains theaddress.

status A BXStatus object to receive the resultingstatus.

cardBrand A string that contains the card brand.

cardNumber A string that contains the card number.



getMonthNumber( )Converts a month into its numeric representation.

Syntaxstatic String getMonthNumber(String month);


ReturnsA string that contains the two-digit representation of the month.

DiscussionYou can specify the month in any case. The month number for January throughSeptember has a leading zero, e.g. ‘01’.

getYear( )Converts a year to a string that contains two digits.

Syntaxstatic String getYear(String year);


ReturnsA string that contains the two-digit representation of the year.

DiscussionThe last two digits of the year are returned. Error checking is not performed.

month A string that contains the month.

year A string that contains a two or four-digitrepresentation of the year.



getYearLong( )Converts a year to a string that contains four digits.

Syntaxstatic String getYearLong(String year);


ReturnsA string that contains the four-digit representation of the year.

DiscussionThe year must be two digits. Dates before 1990, are returned in the 21st century,e.g. ‘89’ is returned as ‘2089’.

parseExtension( )Creates a hash table with the contents of an extension field.





year A string that contains a two or four-digitrepresentation of the year.




stringToAddress( )Converts a string to an address.

Syntaxstatic IBXAddress stringToAddress(String str);


ReturnsAn IBXAddress object that contains the address.

DiscussionThe string contains the three address lines, the city, state, and postal code separatedby semicolons ( ; ).

stringToDate( )Converts a string to a date using the default format.

Syntaxstatic Date stringToDate(String date);


ReturnsA Date object that contains the date.

DiscussionThe string contains the short form (default) of the date.

string An IBXAddress object that contains theaddress.

date A string that contains the date.



stringToDateLong( )Converts a string to a date using the long format.

Syntaxstatic Date stringToDateLongFormat(String date);


ReturnsA Date object that contains the date.

DiscussionThe string contains the long form of the date.

stringToVector( )Converts a string to a vector.

Syntaxstatic Vector stringToVector(String strval);


ReturnsA Vector object that contains the string data.

DiscussionEach substring, separated by a semicolon ( ; ) becomes an element in the vector.

vectorToString( )Converts a vector to a string.

date A string that contains the date.

strval A string that you want to convert.



Syntaxstatic String vectorToString(Vector list);


DiscussionEach element of the vector is cast to a string. The result of the cast is appended tothe returned string. The elements of the vector are separated by semicolons ( ; ) inthe string.

list A Vector object that contains the items toconvert.

203

Chapter 4

Common Templates and Screens

This chapter introduces common templates and shows screens used by severaldifferent Servlets, all of which may be customized.


• Common Templates

• Services Template

• Menu Template

• Sign On Screen

• Sign Off Screen

• Error Screen

• Sign On Error Screen

Common TemplatesThe following sections describe templates that are invoked from several differentServlets or are included in many other templates. Table 4-1 lists the templates thatare commonly used throughout BillerXpert:

Table 4-1 Common Templates


services.html Main service menu

generic_services.html General-purpose menu

Common Templates


Figure 4-1 shows the common elements of most telephone company-relatedscreens in BillerXpert. The services menu and a more generic menu appear on theleft-hand side of these screens.

Figure 4-1 Common templates

Services TemplateThe services.html template is included by most templates that display an entirescreen. This template displays hierarchal references and associated descriptive textand is responsible for invoking an Servlet for each menu item.

Menu TemplateThe generic_services.html template displays a general-purpose menu whose itemsprovide return to the main menu, searching, and contact information.

Common Templates

Chapter 4 Common Templates and Screens 205

Sign On Screen

Templateindex.html

AppLogicBXSignOnServlet, BXSignUpServlet

The Sign On screen appears when the user enters the URL for the BillerXpertapplication. Figure 4-2 shows the Sign On screen.

Figure 4-2 Sign On screen

Sign Off Screen

Templatelogout_msg.jsp

Common Templates


ServletBXSignOutServlet

The Sign Off screen appears when the user clicks on the log off button on any of theuser screens. Figure 4-3 shows the Sign Off screen.

Figure 4-3 Sign Off screen

Error Screen

Templateerror_msg.jsp

ServletBXSignOnServlet

The error_msg.jsp template displays an error message and allows the user toreturn to the Billing Center screen. Figure 4-4 shows the screen.

Common Templates

Chapter 4 Common Templates and Screens 207

Figure 4-4 Error screen

Sign On Error Screen

Templatesignon_msg.jsp

ServletBXSignOnServlet

The error_msg.jsp template displays an error message and allows the user toreturn to the Billing Center screen. Figure 4-5 shows the screen.

Common Templates


Figure 4-5 Error screen

209

Chapter 5

Billing Center Screens

This chapter shows the Billing Center screens that may be customized.


• Billing Center Screen

• Pay Balance Screen

• Payments Screen

• Statement Screen

Billing Center Screen


Billing Center ScreenTemplatebilling_center.jsp

ServletBXBillingCenterServlet

The Billing Center screen is the screen that first appears after the user signs on tothe system. It displays summary information about the user’s statements. Figure5-1 shows the Billing Center screen.


Chapter 5 Billing Center Screens 211

Figure 5-1 Billing Center screen

Statement Screen

Templatestatement_current.jsp

ServletBXBillDocServlet

A Statement screen appears when the user selects an account summary from theBilling Center screen or when the user chooses to display current statements.Figure 5-2 shows the upper portion of a statement.



Figure 5-2 Upper portion of Statement screen

Figure 5-3 shows the lower portion of a statement.



Figure 5-3 Lower portion of Statement screen

Notes:The Servlet uses the following values to retrieve line item records:

Code Description

LDS Long distance call

LTC Local toll call

INT International call

CCC Calling card call

LDSTOT Long distance call total

LTCTOT Local toll call total

INTTOT International call total

CCCTOT Calling card total

MONCHG Monthly charge

Pay Balance Screen


Pay Balance ScreenTemplatepay_account-balance.jsp

ServletBXPaymentServlet

A Pay Balance screen appears when the user selects Pay Balance. This screen liststhe accounts that are available for payment. This screen displays the due date,default payment method, and the total amount due for each account number. Fromthis screen, the user can select which accounts to pay. Figure 5-4 shows the PayBalance screen.

MONCHGTOT Monthly charge total

TAXSUR Tax surcharge

TAXSURTOT Tax surcharge total

Payments Screen


Figure 5-4 Pay Balance screen

Payments ScreenTemplatepayments.jsp

ServletBXPayHistoryServlet

The Payments screen appears when the user selects Payments. This screen lists thestatus of all of the user’s payments, account information, and payment status.Figure 5-5 shows the Payments screen.

Payments Screen


Figure 5-5 Payments screen

217

Chapter 6

Search Screens

This chapter shows the Search screens that may be customized.


• Introduction

• Simple Statement Search Screen

• Advanced Statement Search Screen

• Statement Search Result Screen

IntroductionStatement Search screens allow the user to choose which statements to display. Theuser can make the selection from a screen with the most common parameters orfrom a screen that allows selection of any parameter. These searches arerespectively called simple search and power search.

Simple Statement Search Screen


Simple Statement Search ScreenTemplatestatement_search-simple.jsp

ServletBXBillDocSearchServlet

Figure 6-1 shows the Statement Search screen for a simple search. It supportssearching for an account’s statements for a period of time, based on the duration orcost of the call.

Advanced Statement Search Screen

Chapter 6 Search Screens 219

Figure 6-1 Statement Search screen

Advanced Statement Search ScreenTemplatestatement_search-power.jsp


Figure 6-2 shows the Statement Search screen for a power search. It supportssearching by additional parameters than by the simple search. In addition tosearching for an account’s statements for a period of time, based on the duration orcost of the call, the advanced search supports searching by destination location,phone number called, time of day, rate, and call type.

Statement Search Result Screen


Figure 6-2 Advanced Statement Search screen

Statement Search Result ScreenTemplatestatement_search-results.jsp


When a search completes, BillerXpert displays a results screen that shows the callsthat match the search criteria. It displays the results of the search, including the calldate, starting time, destination phone number and location, call type, rate,duration, and amount. You can also sort the results. Figure 6-3 shows the screen.


Chapter 6 Search Screens 221

Figure 6-3 Statement Search Results screen

223

Chapter 7

User Center Screens

This chapter shows the User Center screens that may be customized.


• User Center Screen

• Contacts Screen

• Billing Address Screen

• Online Name and Password Screen

• Contact Information Screen

• Payment Methods Screen

• E-Mail Notification Screen

• Profile Editor Screen

• Preferences Screen

User Center ScreenTemplateuser_center.jsp

ServletBXUserCenterServlet

Contacts Screen


The user can display the User Center screen by selecting it from the Billing Centerscreen. From this screen the user can view or change their current information. Tochange current information, the user can click on Change in any of the informationtype boxes. The appropriate change screen will display. The following sectionsshow the change screens for each of the information types shown in the UserCenter screen. Figure 7-1 shows the User Center screen.

Figure 7-1 User Center screen this screen

Contacts ScreenTemplateuser_center-editor-contacts.jsp

ServletBXUserProfileServlet

Billing Address Screen

Chapter 7 User Center Screens 225

The user can specify the name a primary contact and additional contacts in theContacts screen. Figure 7-2 shows the Contacts screen.

Figure 7-2 Contacts screen

Billing Address ScreenTemplateuser_center-editor-address.jsp


The user can update their billing address from the Billing Address screen. Figure7-3 shows the Billing Address screen.

Online Name and Password Screen


Figure 7-3 Billing Address screen

Online Name and Password ScreenTemplateuser_center-editor-password.jsp


The user can change their user identification and password from the Online Nameand Password screen. Figure 7-4 shows the Online Name and Password screen.

Contact Information Screen


Figure 7-4 Online Name and Password screen

Contact Information ScreenTemplateuser_center-editor-contact.jsp


The user can change their contact information from the Contact Information screen.Figure 7-5 shows the Contact Information screen.

Payment Methods Screen


Figure 7-5 Contact Information screen

Payment Methods ScreenTemplateuser_center-editor-payment.jsp

ServletBXUserPaymentServlet

The user can specify a payment method for any of their active accounts from thePayment Methods screen. Credit card and check methods are supported inBillerXpert. Figure 7-6 shows the Payment Methods screen.

E-Mail Notification Screen


Figure 7-6 Payment Methods screen

E-Mail Notification ScreenTemplateuser_center-editor-notify.jsp


The user can specify when to send e-mail notifications, for example, when a newstatement is available from the biller. Figure 7-7 shows the E-Mail Notificationscreen.

NOTE If you have set the CHECK type to inactive in the BillerXpertAdmin console, you must remove the display of the checkinformation from the user_center-add_ payment_method.jsptemplate.

Profile Editor Screen


Figure 7-7 E-mail Notification screen

Profile Editor ScreenTemplateuser_center-editor-adinfo.jsp


The user can specify additional profile information in the Profile Editor screen, forexample, their profession or personal interests. Figure 7-8 shows the Profile Editorscreen.

Preferences Screen


Figure 7-8 Profile Editor screen

Preferences ScreenTemplateuser_center-editor-prefs.jsp


The user can specify additional preferences from the Preferences screen, forexample, whether to enable or disable marketing promotions. Figure 7-9 shows thePreferences screen.

Preferences Screen


Figure 7-9 Preferences screen

233

Chapter 8

Registration Screens

This chapter shows the registration screens that may be customized.


• Primary Contact Screen

• Account Information Screen

• Billing Address Screen

• Payment Method Screen

• Password and User Login Screen

• Additional Information Screen

When the user enters the URL for the BillerXpert application, they will see a signon screen. From the screen, a new user can sign up with the biller site by enteringinformation into a series of registration screens. The following sections introducethese screens.

Primary Contact ScreenTemplatenew_member-contacts.jsp

ServletBXSignUpServlet

The user can enter their main contact information from the Primary Contact screen.Figure 8-1 shows the Primary Contact screen.

Account Information Screen


Figure 8-1 Primary Contact screen

Account Information ScreenTemplatenew_member-authenticate.jsp


The user can specify one or more account numbers from the Account Informationscreen. Figure 8-2 shows the Account Information screen.

Billing Address Screen

Chapter 8 Registration Screens 235

Figure 8-2 Account Information screen

Billing Address ScreenTemplatenew_member-address.jsp


The user can specify their primary billing address from the Billing Address screen.Figure 8-3 shows the Billing Address screen.

Payment Method Screen


Figure 8-3 Billing Address screen

Payment Method ScreenTemplatenew_member-payment_info.jsp


The user can specify a primary payment method to pay bills from the PaymentMethod screen. BillerXpert supports credit card and check payment methods.Figure 8-4 shows the Payment Method screen.

Password and User Login Screen


Figure 8-4 Payment Method screen

Password and User Login ScreenTemplatenew_member-online_info.jsp


NOTE If you have set the CHECK type to inactive in the Admin interface,you must remove the display of the check information from thenew_member-payment_ info.jsp template.

Additional Information Screen


The user can specify their user login and password from the Password and UserLogin screen. Figure 8-5 shows the Password and User Login screen.

Figure 8-5 Password and User Login Screen

Additional Information ScreenTemplatenew_member-additional_info.jsp


The user can specify any additional information from the Additional Informationscreen, for example, their profession or personal interests. Figure 8-6 shows theAdditional Information screen.



Figure 8-6 Additional Information screen

241

Chapter 9

Currency Converter


• Introduction

• Currency Conversion Process

• Installation Process

• Loader Program for Currency Conversion Data

• Database Schema

• Sample Code and Usage

IntroductioniPlanet BillerXpert software (www.iplanet.com) provides a comprehensiveInternet Bill Presentment and Payment (IBPP) solution that allows an enterprise toprovide customer convenience, build customer loyalty, manage customerrelationships, and generate new revenue opportunities.

BillerXpert 4.6 has introduced a Customization Guide module to support currencyconversion capabilities for both banks and billers. The Customization Guidemodule is a plugable component that provides host applications API's to helpconvert currencies. It is EURO compliant.

Within the Customization Guide module, there is also a loader program, which isused to load the currency conversion entries. The loader program takes in anExtensible Markup Language (XML) file of conversion data and loads it into theconversion table. Updates to the currency conversion table are performed by theadministrator either manually, or via an external scheduling software program,such as ECXpert.

Currency Conversion Process


ECXpert is an Internet commerce exchange application that enables an enterprise toautomate and manage the processes that occur between organizations over the Internet andexisting private networks. ECXpert enables encrypted transmission of documents andmessages among heterogeneous trading partner systems, and can transform informationfrom one format into another.

Currency Conversion ProcessThe currency conversion process is as follows:

1. Currency codes and related information are loaded at the time of installation.These codes are International Organization for Standardization (ISO) standardand should not change. The Euro currencies are identified through the use of aspecial flag.

2. The latest currency rates are loaded into the database using a loader program.This program reads the data in XML format from a file and loads the rate table.Each load is tracked on the basis of conversion date. Each load is tracked in thedatabase by a sequentially generated id, fileid. Please refer to the databaseschema for more details.

3. When the conversion method is called, it retrieves the appropriate fileid byusing the date specified to find the latest track for that date. This search is onthe basis of conversion date (not the load date).

4. Once the appropriate load is determined, the required rate is searched from thecurrencyconversion table, using the fileid retrieved in step 3.

5. If the currency is a Euro currency, the rate between the other currency andEuro is retrieved. This rate is then used to convert the amount from onecurrency to another. In case of Euro currencies, the conversion always passesthrough Euro, i.e. Euro currency -> Euro -> other currency. Please refer to theofficial sitehttp://europa.eu.int/eur-lex/en/lif/dat/1997/en_397R1103.html forconversion rules regarding the EURO.

Installation ProcessThe currency conversion module is installed automatically as part of the iPlanetBillerXpert installation.The following tasks are performed as part of the BillerXpertinstallation, which are specific to the currency converter module:

Loader Program for Currency Conversion Data

Chapter 9 Currency Converter 243

1. Three tables are created in the BSP schema. They are:

• currency

• currency conversion

• currencyloadtrack.Please refer to the database schema for more details.

2. The files currconv.zip and xml.jar will be created under $BX_HOME/java.

3. The files billxpert_env.csh and billxpert_env.sh will be modified toinclude currconv.zip and xml.jar in the CLASSPATH.

• The system will prompt you to specify whether the same user that exists inBillerXpert should be used, or, if a new user needs to be created.

To perform the installation, follow these steps:1. Extract the files from ccinstall.tar

2. Change dir to ccinstall

3. Excute the script setup.sh

4. If sample conversion data is required for testing, run the script loadSampleConversionData.csh to load sample data.

5. Source the script currconv_env.csh to setup the environment.

• Create a database.

• Create three (3) tables, which will be used for new exchange information. Oneof these tables will populate the table named currency.

Loader Program for Currency Conversion DataThe loader program is used to load the currency conversion entries. The loaderprogram takes in an XML file of conversion data and load it into the conversiontable. Updates to the currency conversion table can be performed by theadministrator either manually, or via an external scheduling software program.

Typically, a biller would manually execute the loader on a daily basis; whereas afinancial institution may choose to schedule updates every 30 minutes, or morefrequently.

Database Schema


The loader program contains the following three (3) tables:

The currencyloadtrack table provides the following information concerning agiven load:

• Pathname

• Number of records

• Load date and time

• Status (success, failure, or in progress)

• Source (i.e.: Reuters)

• Conversion date

Database SchemaThe database schema for Currency Converter is listed below.

-- __COPYRIGHT__-- $Id:-- $log:

-- ============================================================-- Table: CURRENCY

Table Name Purpose

Currency Master data is loaded to this table only.

currencyconversion Displays exchange information for each load.

currencyloadtrack Stores information about when and where eachload took place.

NOTE The load process should normally take no more than one minute tocomplete.

The load date refers to the date the data was loaded. Theconversion date refers to the date the data became valid.

Database Schema


-- ============================================================create table CURRENCY( CURCODE CHAR(3) not null, CURID NUMBER(10) not null, MINORUNIT NUMBER(5) not null, CURDESC VARCHAR2(240) null, CREATEDATE DATE null, EUFLAG CHAR(1) null, constraint PK_CURRENCY primary key (CURCODE) USING INDEX)/

-- ============================================================-- Table: CURRENCYLOADTRACK -- ============================================================create table CURRENCYLOADTRACK( FILEID NUMBER(15) not null, FILEPATH VARCHAR2(240) not null, RECORDCOUNT NUMBER(10) not null, LOADDATE DATE not null, STATUS VARCHAR2(16) not null, SOURCE VARCHAR2(240) null, -- eg Reuters, BOA CONVDATE DATE not null, -- currency conv date time constraint PK_CURRENCYLOADTRACK primary key (FILEID) USING INDEX)/

create sequence CURRENCYLOAD_seq minvalue 2000/

-- ============================================================-- Table: CURRENCYCONVERSION -- ============================================================create table CURRENCYCONVERSION( CONVID NUMBER(15) not null, FROMCUR CHAR(3) not null, TOCUR CHAR(3) not null, FACTOR NUMBER(20,8) not null, FILEID NUMBER(15) not null, constraint PK_CURRENCYCONVERSION primary key (CONVID) USING INDEX)

Sample Code and Usage


/

create sequence CONVERSION_seq minvalue 2000/

create unique index CURRENCYCONVERSIONI1 on CURRENCYCONVERSION ( FILEID asc, FROMCUR asc, TOCUR asc) TABLESPACE TS02 STORAGE ( INITIAL 1M NEXT 1M )/

alter table CURRENCYCONVERSION add constraint FK_CURRENCYCONVERSION1 foreign key (FROMCUR) references CURRENCY (CURCODE) on delete cascade/

alter table CURRENCYCONVERSION add constraint FK_CURRENCYCONVERSION2 foreign key (TOCUR) references CURRENCY (CURCODE) on delete cascade/

alter table CURRENCYCONVERSION add constraint FK_CURRENCYCONVERSION3 foreign key (FILEID) references CURRENCYLOADTRACK (FILEID) on delete cascade/


API UsageCurrencyIface a = (CurrencyIface) new CurrencyDBImpl(con); Currency cur1 = a.getCurrency ("USD"); Currency cur2 = a.getCurrency ("ESP"); CurrencyConvertor cc = new a.getCurrencyConvertor (cur1, cur2); outval1 = cc.convert (inval1, precision, rounding); outval2 = cc.convert (inval2, precision, rounding); outval3 = cc.convert (inval3, precision, rounding);



where con is a java.sql.Connection

and cur1, and cur2 are com.iplanet.ecomm.currconv.Currency

CurrencyIface a = (CurrencyIface) new CurrencyDBImpl(con); Currency cur1 = a.getCurrency ("USD"); Currency cur2 = a.getCurrency ("ESP"); CurrencyConvertor cc = new a.getCurrencyConvertor (cur1, cur2); outval1 = cc.convert (inval1, precision, rounding); outval2 = cc.convert (inval2, precision, rounding); outval3 = cc.convert (inval3, precision, rounding);

where con is a java.sql.Connection

and cur1, and cur2 are com.iplanet.ecomm.currconv.Currency

To get conversion for a conversion rate as of a past Date: Date dt ; ...

CurrencyIface a = (CurrencyIface) new CurrencyDBImpl(con);

LoadTrack lt = a.getLastLoadTrack (dt);

Currency cur1 = a.getCurrency ("USD");

Currency cur2 = a.getCurrency ("ESP");

CurrencyConvertor cc = new a.getCurrencyConvertor (cur1, cur2, lt);

outval1 = cc.convert (inval1, precision, rounding);



Loading

As a standalone :java com.iplanet.ecomm.currconv.CCLoad <InputXMLFile> <dbpropertiesfile >

where



-InputXMLFile : Input XML file (please refer to DTD and sample XML file)

-dbpropertiesFile : properties file, which is used to make a connection to thedatabase.

Within your code :CCLoad ccLoad = new CCLoad(xmlFile, dbpropertiesFile);

or

CCLoad ccLoad = new CCLoad(xmlFile, con);

ccLoad.loadData();

where con is a jdbc Connection, xmlFile and dbpropertiesFile are String variableswhose value is the xmlFile Name and dbpropertiesFile name.

iplanet billerxpert 4.6 b2c edition customization guide · 2011-02-10 · or extending billerxpert...

Documents