Building web serivices with Java making sencse of XML

Gratis

0
1
481
1 year ago
Preview
Full text

Building Web Services with Java™: Making Sense of XML, SOAP, WSDL, and UDDI

  By Steve Graham , Simeon Simeonov , Toufic Boubez , Doug Davis , Glen Daniels , Yuichi Nakamura , Ryo Neyama Publisher : Sams Publishing Pub Date : December 12, 2001

  ISBN : 0-672-32181-5 Pages : 600 : Slots

  Based on open indust ry st andards, Web services enable your soft w are t o int egrat e w it h part ners and client s in a fashion t hat is loosely coupled, sim ple, and plat form - independent . Building Web Services w it h Java: Making Sense of XML, SOAP, WSDL, and UDDI present s t he concept of Web services and explains how t o incorporat e Web services int o your business. The book addresses em erging st andards associat ed wit h Web services, such as Sim ple Obj ect Access Prot ocol ( SOAP) , Web Services Descript ion Language ( WSDL) , and Universal Descript ion Discovery and I nt egrat ion ( UDDI ) .

  Copyright Copyright © 2002 by Sams Publishing

  All right s reserved. No part of t his book shall be reproduced, st ored in a ret rieval syst em , or t ransm it t ed by any m eans, elect ronic, m echanical, phot ocopying, recording, or ot herw ise, w it hout w rit t en perm ission from t he publisher. No pat ent liabilit y is assum ed w it h respect t o t he use of t he inform at ion cont ained herein. Alt hough every precaut ion has been t aken in t he preparat ion of t his book, t he publisher and aut hor assum e no responsibilit y for errors or om issions. Nor is any liabilit y assum ed for dam ages result ing from t he use of t he inform at ion cont ained herein. Library of Congress Cat alog Card Num ber: 2001090920 Print ed in t he Unit ed St at es of Am erica First Print ing: Decem ber 2001 04 03 02 01 4 3 2 1

  Trademarks

  All t erm s m ent ioned in t his book t hat are know n t o be t radem arks or service m arks have been appropriat ely capit alized. Sam s Publishing cannot at t est t o t he accuracy of t his inform at ion. Use of a t erm in t his book should not be regarded as affect ing t he validit y of any t radem ark or service m ark.

  Warning and Disclaimer

  Every effort has been m ade t o m ake t his book as com plet e and as accurat e as possible, but no w arrant y or fit ness is im plied. The inform at ion provided is on an " as is" basis. The aut hors and t he publisher shall have neit her liabilit y nor responsibilit y t o any person or ent it y w it h respect t o any loss or dam ages arising from t he inform at ion cont ained in t his book.

  Executive Editor Michael Stephens Acquisitions Editor Michael Stephens Development Editor Tiffany Taylor Managing Editor Matt Purcell Project Editor Christina Smith Copy Editor Tiffany Taylor Indexer

  Eric Schroeder Proofreader Plan-It Publishing Technical Editor Chad Fowler Craig Pfiefer Team Coordinator Pamalee Nelson Media Developer Dan Scherf Interior Designer Anne Jones Cover Designer Aren Howell Page Layout Heather Stephenson

About the Authors

  St eve Graham is an archit ect in t he Em erging Technologies division of I BM Soft w are Group. He has spent t he last several years working on service- orient ed archit ect ures, m ost recent ly as part of t he I BM Web Services I nit iat ive. Prior t o t his, St eve w orked as a t echnologist and consult ant on various em erging t echnologies such as Java and XML, and before t hat he w as an archit ect and consult ant w it h t he I BM Sm allt alk consult ing organizat ion.

  Before j oining I BM, St eve w as a developer w it h Sybase, a consult ant , and a facult y m em ber in t he Depart m ent of Com put er Science at t he Universit y of Wat erloo. St eve holds a BMat h and MMAt h in com put er science from t he Universit y of Wat erloo. You can reach him at sggraham @us.ibm .com .

  Sim eon ( Sim ) Sim eonov has been developing soft ware for m ore t han 15 years. Sim 's areas of expert ise encom pass obj ect - orient ed t echnology, com piler t heory, I nt ernet t ools, ent erprise com put ing, and t he broad spect rum of XML t echnologies. As chief archit ect at Macrom edia I nc., Sim provides direct ion for t he evolut ion of t he com pany's t echnology and product st rat egy as w ell as t he archit ect ure of it s server- side plat form product s. Previously, Sim w as chief archit ect at Allaire Corporat ion, w here his init iat ives brought about num erous innovat ions t o t he core product lines. Sim is current ly w orking on service- orient ed archit ect ures for t he next generat ion of

  Process in t he areas of I nt ernet applicat ions, XML, and Web Services. Sim also represent s Macrom edia on t he W3C w orking group on XML Prot ocol. He is a regular speaker at conferences and a m ont hly colum nist for XML Journal. Sim holds a B.A. in Com put er Science, Econom ics, and Mat hem at ics and a MSc in Com put er Science.

  Toufic Boubez is t he chief t echnology officer of Saffron Technology. Prior t o j oining Saffron, he w as a senior t echnologist in I BM's Em erging Technologies group, and lead archit ect of I BM's Web services init iat ive. He w as I BM's t echnical represent at ive t o t he UDDI Web Services Consort ium w it h Microsoft and Ariba and co- aut hored t he UDDI API specificat ion. He w as also t he I BM t echnical lead on t he UN/ CEFACT/ OASI S ebXML init iat ive and helped drive I BM's early XML and Web services st rat egies.

  Dr. Boubez has m ore t han 15 years of experience in I T and has published and present ed on Web services, XML, obj ect t echnology, dist ribut ed com put ing, int elligent agent s, B2B, business m odeling, sim ulat ion, neural net w orks, and w avelet analysis. He holds a doct orat e in Biom edical Engineering from Rut gers Universit y.

  Doug Davis w orks in t he Em erging Technology organizat ion of I BM, w orking on I BM's Web Services Toolkit , and he is one of I BM's represent at ives in t he W3C XML Prot ocol w orking group. Previous proj ect s include WebSphere's Machine Translat ion proj ect , Team Connect ion, and I BM's FORTRAN 90 com piler. Doug has a Bachelor of Science degree from t he Universit y of California at Davis and a Mast er's degree in Com put er Science from Michigan St at e Universit y.

  Glen Daniels, in his 13 years in t he soft ware indust ry, has run t he gam ut from device drivers and net w ork st acks up t hrough user int erface and Web sit e w ork, in everyt hing from assem bly language t o C+ + t o Lisp. Dist ribut ed com put ing has alw ays been a passion, and as such he is current ly t echnical lead for t he JRun Web Services t eam at Macrom edia. Glen is an act ive m em ber of t he W3C XML Prot ocol group as w ell as one of t he lead developers of Axis. When not coding, he can oft en be found playing bass or harm onica, hanging out w it h his m any crazy friends in t he Bost on area, or relaxing w it h his cat s.

  Yuichi Nakam ura is an advisory researcher at t he I BM Tokyo Research Laborat ory. His research int erest s are Web services including SOAP and XML securit y, obj ect - orient ed syst em s, J2EE, m ult iagent syst em s, B2B e- com m erce, and knowledge engineering. He received an MSc and a PhD in Applied Physics from Osaka Universit y in 1987 and 1990, respect ively. Ryo Neyam a is a researcher at t he I BM Tokyo Research Laborat ory. His research int erest s are dist ribut ed obj ect syst em s including Web services, obj ect request brokers, and securit y. He received an MSc in I nform at ion and Com put er Science from Waseda Universit y in 1999.

Acknowledgments

  To Karen, Erin and Jessie, m y fam ily, m y inspirat ion. For all t he m om ent s sacrificed t o creat e t his book, m y m ost heart felt t hanks for your underst anding. My t hanks t o m y cow orkers at I BM, and in part icular t he WSTK t eam for doing such an out st anding j ob. My t hanks also t o Rod Sm it h for fost ering an excellent environm ent for creat ive work. My t hanks also t o t he st aff at Sam s, part icularly Tiffany Taylor and Michael St ephens, for t he hard w ork t hat w ent int o m aking t his proj ect a realit y. Rom ans 12: 2.

  I t is m uch easier t o w rit e a book w hen ot hers believe you can. My deepest t hanks t o Pyrra: m y t rue love and a const ant source of inspirat ion. Thanks also t o all m y friends and co- w orkers w ho never st opped being int erest ed in Web services and t he progress of t he book. See? I t 's done.

  —Sim Sim eonov To Lucy and Yasm ine: Thank you for your pat ience, love, and underst anding. This was a m aj or undert aking for a new dad w it h anot her full- t im e j ob. To m y old I BM t eam , Sam Adam s, St eve Burbeck, Jay Casler, St eve Graham , Maryann Hondo, and Rod Sm it h, t hank you for t he great , challenging, and recept ive w ork environm ent . I seriously don't t hink t he concept of Web services w ould have evolved t o w here it is t oday in a different environm ent . To m y new t eam at Saffron, t hank you for replicat ing t hat environm ent ! —Toufic Boubez Lin—I ow e so m any t hings t o your pat ience, support , and m ost of all your sense of hum or. I can never say it enough, but t hank you.

  —Doug Davis For all m y friends and fam ily w ho so pat ient ly cont inue t o be t here for m e t hrough even t he busiest t im es—love and t hanks t o all of you.

  —Glen Daniels To Michiyo: Thank you for your underst anding and pat ience during t his w ork. Thanks t o m y kids, Arisa and Ryot aro: You alw ays m ade m e happy w it h your lovely sm iles.

  My t hanks t o all XML and Securit y t eam m em bers at I BM Tokyo Research Laborat ory. —Yuichi Nakam ura My t hanks t o m y parent s, Jun and Sachie, for bringing m e up and alw ays support ing m e.

  My t hanks also t o Takako and m y friends for t heir encouragem ent and underst anding. My t hanks t o m y cow orkers at I BM Tokyo Research Laborat ory for t heir deep insight s on Web services and relat ed t echnologies.

  —Ryo Neyam a

Tell Us What You Think!

  As t he reader of t his book, you are our m ost im port ant crit ic and com m ent at or. We value your opinion and w ant t o know w hat w e're doing right , w hat w e could do bet t er, w hat areas you'd like t o see us publish in, and any ot her w ords of w isdom you're w illing t o pass our way.

  As an Execut ive Edit or for Sam s Publishing, I w elcom e your com m ent s. You can fax, e- m ail, or w rit e m e direct ly t o let m e know w hat you did or didn't like about t his book—as w ell as w hat w e can do t o m ake our books st ronger. Please not e t hat I cannot help you w it h t echnical problem s relat ed t o t he t opic of t his book, and t hat due t o t he high volum e of m ail I receive, I m ight not be able t o reply t o every m essage. When you w rit e, please be sure t o include t his book's t it le and aut hors' nam es as w ell as your nam e and phone or fax num ber. I w ill carefully review your com m ent s and share t hem w it h t he aut hors and edit ors w ho w orked on t he book.

  E-mail: feedback@samspublishing.com Mail:

  Michael St ephens Execut ive Edit or Sam s Publishing 201 West 103rd St reet I ndianapolis, I N 46290 USA

  Introduction

  Welcom e t o t he w orld of Web services! This is a rapidly evolving set of st andards and im plem ent at ion t echnologies t hat have great prom ise for t he w orld of applicat ion int egrat ion and dist ribut ed com put ing. Before w e get going, w e need t o clarify som e t hings about t he purpose and st ruct ure of t he book. Let 's t alk about t hem now .

Goals of this Book

  The overall goal of t his book is t o fam iliarize you w it h t he concept of Web services and w hat it w ill t ake t o incorporat e Web services as part of your business. We w ill int roduce t he concept of Web services and give you a fram ew ork t hat describes how you can posit ion t he various em erging st andards t hat are associat ed w it h Web services, such as Sim ple Obj ect Access Prot ocol ( SOAP) , Web Services Descript ion Language ( WSDL) , and Universal Descript ion Discovery and I nt egrat ion ( UDDI ) . We w ill help posit ion Web services from a business and t echnical perspect ive, explaining and dem onst rat ing how Web services can be used t o address various business problem s,

  part icularly relat ed t o applicat ion int egrat ion. Anot her goal of t his book is t o help developers underst and t he issues and det ails relat ed t o building Web services using t he t echniques covered by t his book. What pieces are required w hen you're planning a Web services st rat egy? What t hings do you need t o t ake care of w hen developing Web services? We provide lot s of exam ples and running code t o dem onst rat e t hese approaches. We also review in det ail t he Apache Axis Web services infrast ruct ure w it h our running exam ples. Ot her t ools and Web services infrast ruct ures are discussed as w ell, but not in t he sam e det ail as Axis.

Assumed Background

  This book is m eant for com put ing t echnical professionals w it h som e experience building Web applicat ions and dist ribut ed com put ing syst em s. You don't need t o be a seasoned vet eran of t he dist ribut ed obj ect w ars t o appreciat e t his book, but som e fam iliarit y w it h Web- based archit ect ures and t echniques such as HTTP and HTML is assum ed. I f you do not have any experience w it h t hese t echniques, som e of t he m at erial could be a lit t le confusing—part icularly som e of t he code exam ples—but you should st ill be able t o get a lot out of t his book.

  We assum e you are fam iliar w it h Java, and in part icular t he Java Server Pages ( JSP) and Java servlet t echnologies. We also briefly discuss t he relat ionship bet w een Ent erprise Java Beans ( EJBs) and Web services, so som e fam iliarit y w it h EJBs is helpful as w ell. I f you need t o supplem ent your underst anding of t hese t echniques, m any, m any good

  You w ill also discover t hat t he Ext ensible Markup Language ( XML) is at t he core of all t hings dealing w it h Web service. Alt hough w e devot e an ent ire chapt er t o explaining t he core pieces of XML needed t o build Web services, t he m ore underst anding of XML you have, t he m ore successful you w ill be in building Web services.

  Philosophy

  I t is difficult t o st ruct ure a book on Web services. The concept s and st andards are very m uch int erdependent . I t is hard t o cover each t opic in isolat ion, because it is t he com binat ion of t hese concept s and st andards t hat m ake Web services im port ant t o dist ribut ed com put ing.

  The philosophy of t his book can be sum m arized by four point s: pragm at ics, progressive disclosure, a running exam ple, and a service- orient ed archit ect ure fram ew ork.

Pragmatics

  I n t his book, w e t ry t o get t o program m ing exam ples and running code as quickly as possible. I n part icular, w e focus on building and consum ing SOAP- based Web services using t he Apache Axis Web services infrast ruct ure. This is a Java- cent ric approach t o building Web services. Whereas w e em phasize t hat Web services are fundam ent ally program m ing language neut ral, ult im at ely, any given Web service is im plem ent ed in som e program m ing language t echnology. I n t he case of t his book, w e have chosen Java. Where issues of int eroperabilit y w it h Web services w rit t en in ot her program m ing languages m ight appear, w e not e t hem . Det ailed coverage of ot her Web services im plem ent at ion approaches, such as Microsoft 's .NET, is beyond t he scope of t his book, alt hough w e do give som e basic exam ples of .NET and ot her environm ent s in Chapt er 8 , " I nt eroperabilit y, Tools, and Middlew are Product s."

  Progressive Disclosure

  Aft er t he overview of Web services, w e st art w it h t he fundam ent als of XML, and t hen layer on new concept s, m ot ivat ed by a business com put ing problem . These layers produce a series of Web services t echnology " st acks." For each of t he t echnologies and st andards in t he Web services arena, w e focus on underst anding t he t echnology from t he perspect ive of w hat problem s it solves, balancing t he explanat ion of t he t echnology it self.

  Running Example

  The t echnologies and st andards t hat m ake up t he Web services concept are each exam ined in t he cont ext of a running exam ple ( w hich w e discuss lat er in t his int roduct ion) . The use of t he running exam ple adds insight t o t he explanat ion of t he concept in t he t ext of t he book and support s t he progressive disclosure approach as w e follow t he exam ple, adding t he layers of Web services t echnology t o t he solut ion. This approach helps posit ion various best - pract ices approaches t o Web service developm ent and deploym ent . You can dow nload t he source code for t hese running exam ples from

  w w w .sam spublishing.com . When you reach t hat page, ent er t his book's I SBN num ber

  ( 0672321815) in t he search box t o access inform at ion about t he book and a Source Code link.

Service-Oriented Architecture

  The exam ples and Web services concept s are discussed in t he cont ext of a service- orient ed archit ect ure ( SOA) t hat w e int roduce in Chapt er 1 , " Web Services Overview ." We use t he SOA fram ew ork t o help posit ion t he various Web services concept s back int o a bigger pict ure.

  

Chapt er 1 begins t he book w it h an explanat ion of w hat t he Web services approach is all

  about . We describe w hat a Web service is, w hat st andards and t echnologies are associat ed w it h Web services, and w hat problem s can be solved using Web services. We use t his chapt er t o int roduce t he SOA concept ual fram ew ork and begin t o explain how t he various Web services st andards such as SOAP, WSDL, and UDDI fit t oget her. This chapt er w ill give you a solid concept ual basis for t he rest of t he book. Before w e can get int o t he core Web services st andards, w e t ake a brief side t rip t o explain XML in Chapt er 2 , " XML Prim er." Because XML is at t he heart of all t he Web services st andards and t echniques, it is im port ant you underst and it w ell. XML is a huge t opic, but w e focus our exam inat ion of XML on w hat you w ill need t o know in order t o underst and t he rest of t he Web services t opics. Aft er t he review of XML, Chapt er 3 , " Sim ple Obj ect Access Prot ocol ( SOAP) ," dives in t o t he core problem of invoking a Web service. We review t he t opic of XML m essaging in a dist ribut ed com put ing environm ent , focusing on t he SOAP m essage enveloping st andard. SOAP form s t he core basis of com m unicat ion bet w een a service request or and a service provider in a Web services environm ent .

  

Chapt er 4 , " Creat ing Web Services," refines your underst anding of SOAP in t he cont ext of

  a part icular SOAP infrast ruct ure: t he Apache Axis proj ect . Chapt er 4 dives int o t he det ails of how Axis w orks and how you can use it t o m ake it easy t o deploy Web services and have your applicat ions consum e Web services. At t his point , you w ill have a great background underst anding of SOAP and at least one w ay t o m ake SOAP real: Axis. But SOAP alone is not enough t o do m ore t han very sim ple Web services. Chapt er 5 , " Using SOAP for e- Business," adds det ail t o t he concept s int roduced in Chapt ers 3 and

  4 by explaining how you can build Web services for

  com plet e business com put ing problem s. Chapt er 5 discusses how Web services addresses m any dist ribut ed com put ing problem s including securit y, perform ance, qualit y of service, reliabilit y, and so on.

  Chapt er 6 , " Describing Web Services," int roduces t he im port ant not ion of service

  descript ion, w hich is key t o m aking Web services t he great applicat ion int egrat ion t echnology for building loosely coupled syst em s. Chapt er 6 discusses how Web services uses service descript ion t o address t he problem of com m unicat ing w hat det ails t he service request or needs t o know about t he Web service in order t o properly underst and how ( and why) t o invoke it . Now , you need t o underst and how t he service request or got t he service descript ion in t he first place. Chapt er 7 , " Discovering Web Services," picks up where Chapt er 6 left off, discussing t he various t echniques for Web service discovery. This chapt er exam ines t he st andards relat ed t o finding w hat Web services are provided by businesses w it h w hich a com pany m ight w ant t o collaborat e.

  Chapt er 8 , " I nt eroperabilit y, Tools, and Middlew are Product s," fills out your

  underst anding of best pract ices in t he Web services arena by exam ining various ot her Web services infrast ruct ure and t ooling environm ent s. The book concludes w it h a forw ard- looking Chapt er 9 , " Fut ure Concept s," w hich speculat es on som e possible fut ure uses of Web services t echnologies t o address ot her problem s in dist ribut ed com put ing.

Note

  This book int roduces quit e a few t erm s w it h w hich you m ight not be fam iliar. We have included a glossary at t he back of t his book t hat act s as a great reference guide t o t he t erm inology used in t he book. We w ill annot at e t he first use of each t erm appearing in

  So, before w e get st art ed, let 's int roduce t he fict ional com pany w e'll use for our exam ples t hroughout t his book: Skat esTow n. We w ill follow Skat esTow n as t he com pany exploit s Web services t o im prove it s business.

Introducing SkatesTown

  Skat esTow n is a sm all but grow ing business in New York founded by t hree m echanically inclined friends w it h a passion for cars and skat eboards. They st art ed by designing and selling cust om pre- built boards out of Dean Carroll's garage, and w ord soon spread about t he qualit y of t heir w ork. They cam e up w it h som e innovat ive new const ruct ion t echniques, and w it hin m ont hs t hey had orders piling up. Now Skat esTow n has a sm all m anufact uring operat ion in Brooklyn, and t he com pany is selling boards, clot hing, and equipm ent t o st ores around t he cit y. Dean, Frank St em kow ski, and Chad Washingt on couldn't be happier about how t heir business has grow n.

  Of t he t hree, Chad is t he real gearhead, and he has been responsible for m ost of t he daring const ruct ion and design choices t hat have helped Skat esTow n get w here it is t oday. He's t he president and head of t he t eam . Frank, gregarious and a sm oot h t alker ever since childhood, now handles m arket ing and sales. Dean has t ight ly t racked t he com put er revolut ion over t he years, and is chief t echnical officer for t he com pany. A few years back, Dean realized t hat net w orking t echnology w as going t o be big, and he w ant ed t o m ake sure t hat Skat esTow n could cat ch t he w ave and ut ilize dist ribut ed com put ing t o leverage it s business. This focus t urned out t o be a great m ove. Dean set up a Web presence so Skat esTow n could help it s cust om ers st ay up- t o- dat e w it hout requiring a large st aff t o answ er phones and quest ions. He also built an online order- processing syst em t o help st ream line t he act ual flow of t he business w it h net w ork- enabled client s. I n recent m ont hs, m ore and m ore st ores w ho carry Skat esTow n product s have been using t he syst em t o great effect .

Our Story Begins…

  At present , Dean is pret t y happy w it h t he w ay t hings are w orking w it h Skat esTow n's elect ronic com m erce syst em s. But t here have been a few problem s, and Dean is sure t hat t hings could be even bet t er. He realizes t hat as t he business grow s, t he m anual t asks associat ed w it h order gat hering and invent ory resupply w ill lim it t he com pany's success. Alw ays one t o w at ch t he horizon, Dean has heard t he buzz about Web services, and w ant s t o know m ore. At t he urging of a friend, he got in t ouch w it h Al Rosen, a cont ract or for Silver Bullet Consult ing. Silver Bullet specializes in Web services solut ions, and aft er a couple of m eet ings w it h Al, Dean w as convinced—he hired SBC t o com e in, evaluat e Skat esTow n's syst em s, and help t he com pany grow int o a Web service–enabled business.

  As w e m ove t hrough t he rest of t he book, w e'll keep an eye on how Skat esTow n uses t echnologies like XML and, lat er, SOAP, WSDL, and UDDI t o increase efficiency, product ivit y, and est ablish new and valuable relat ionships w it h it s cust om ers and business part ners. Silver Bullet , as w e'll see, usually lives up t o it s nam e.

  Trends in e-business • Why Do We Need a Web Services Approach? • Service-Oriented Architectures • Web Services Interoperability Stacks

  • I n t his chapt er, w e w ill provide t he basic t erm inology and set of concept s t hat put t he rem ainder of t he book int o cont ext . We w ill define w hat w e m ean by a Web service and describe sit uat ions in w hich Web services w ill play an im port ant role. We w ill describe a sim ple fram ew ork, called service- orient ed archit ect ure , t hat helps st ruct ure t he applicat ion of Web services t echnologies. We w ill also provide a fram ew ork, in t he form of t hree " int eroperabilit y" st acks t hat posit ion how t he various Web services t echnologies such as Sim ple Obj ect Access Prot ocol ( SOAP) , Web Services Descript ion Language ( WSDL) , and Universal Descript ion Discovery and I nt egrat ion ( UDDI ) relat e. The rest of t he book, t hen, is an elaborat ion of t he basic concept s present ed here.

What Is a Web Service?

  This is a book about building Web services. We cannot describe how t o build a Web service w it hout first clarifying w hat w e m ean by a Web service. The t erm Web services has gained a lot of m om ent um in t he last year. Many soft w are vendors ( large and sm all) are announcing Web services init iat ives and adopt ion ( see t he sidebar " Web Services Market Dynam ics " ) . Many organizat ions are involved in t he refinem ent of Web services st andards. Alt hough t here seem s t o be a slow convergence t ow ards a com m on underst anding of w hat t he t erm m eans, t here is no single, universally adopt ed definit ion of w hat is m eant by t he t erm Web service. This sit uat ion is rem iniscent of t he early days of obj ect - orient ed program m ing: Not unt il t he concept s of inherit ance, encapsulat ion, and polym orphism w ere w ell defined did obj ect - orient ed program m ing becom e accept ed int o t he m ainst ream of developm ent m et hodologies. Several m aj or Web services infrast ruct ure providers have published t heir definit ions for a Web service:

  I BM offers t his definit ion at

  ht t p: / / w w w 4.ibm .com / soft w are/ solut ions/ Webservices/ pdf/ WSCA.pdf :

  A Web service is an int erface t hat describes a collect ion of operat ions t hat are net w ork accessible t hrough st andardized XML m essaging. Web services fulfill a specific t ask or a set of t asks. A Web service is described using a st andard, form al XML not ion, called it s service descript ion, t hat provides all of t he det ails necessary t o int eract w it h t he service, including m essage form at s ( t hat det ail t he operat ions) , t ransport prot ocols, and locat ion.

  The nat ure of t he int erface hides t he im plem ent at ion det ails of t he service so t hat it can be used independent ly of t he hardw are or soft w are plat form on w hich it is im plem ent ed and independent ly of t he program m ing language in w hich it is w rit t en. This allow s and encourages Web services t echnology im plem ent at ions. Web services can be used alone or in conj unct ion w it h ot her Web services t o carry out a com plex aggregat ion or a business t ransact ion. Microsoft has a couple of definit ions for Web service. The first is at ht t p: / /

  m sdn.m icrosoft .com / library/ default .asp?url= / nhp/ Default .asp?cont ent id= 28000442 :

  A Web service is a unit of applicat ion logic providing dat a and services t o ot her applicat ions. Applicat ions access Web services via ubiquit ous Web prot ocols and dat a form at s such as HTTP, XML, and SOAP, w it h no need t o w orry about how each Web service is im plem ent ed. Web services com bine t he best aspect s of com ponent - based developm ent and t he Web, and are a cornerst one of t he Microsoft .NET program m ing m odel.

  The ot her Microsoft definit ion is at

  ht t p: / / m sdn.m icrosoft .com / library/ default .asp?url= / library/ en- us/ dnWebsrv/ ht m l/ Websvcs_plat form .asp :

  A Web service is program m able applicat ion logic accessible using st andard I nt ernet prot ocols. Web services com bine t he best aspect s of com ponent - based developm ent and t he Web. Like com ponent s, Web services represent black- box funct ionalit y t hat can be reused w it hout w orrying about how t he service is im plem ent ed. Unlike current com ponent t echnologies, Web services are not accessed via obj ect - m odel- specific prot ocols, such as t he dist ribut ed Com ponent Obj ect Model ( DCOM) , Rem ot e Met hod I nvocat ion ( RMI ) , or I nt ernet I nt er- ORB Prot ocol ( I I OP) . I nst ead, Web services are accessed via ubiquit ous Web prot ocols and dat a form at s, such as Hypert ext Transfer Prot ocol ( HTTP) and Ext ensible Markup Language ( XML) . Furt herm ore, a Web service int erface is defined st rict ly in t erm s of t he m essages t he Web service accept s and generat es.

  Consum ers of t he Web service can be im plem ent ed on any plat form in any program m ing language, as long as t hey can creat e and consum e t he m essages defined for t he Web service int erface. Sun provides t he follow ing definit ion at

  ht t p: / / w w w .sun.com / soft w are/ sunone/ faq.ht m l# 2 :

  Web services are soft ware com ponent s t hat can be spont aneously discovered, com bined, and recom bined t o provide a solut ion t o t he user's problem / request . The Java™ language and XML are t he prom inent t echnologies for Web services.

  As you can see, t here is broad agreem ent on w hat a Web service m ight be, but no single agreed- upon definit ion. Many developers w ill claim t hey cannot define w hat a Web service is, but t hey know one w hen t hey see one. From t he perspect ive of t his book, a Web service is a plat form and im plem ent at ion independent soft w are com ponent t hat can be:

  Described using a service description language • Published to a registry of services • Discovered through a standard mechanism (at runtime or design time) • Invoked through a declared API, usually over a network

  • Composed with other services •
One im port ant point is t hat a Web service need not necessarily exist on t he World Wide Web. This is an unfort unat e hist orical nam ing issue. A Web service can live anyw here on t he net w ork, I nt er- or int ranet ; som e Web services can be invoked by a sim ple m et hod invocat ion in t he sam e operat ing syst em process, or perhaps using shared m em ory bet w een t ight ly coupled processes running on t he sam e m achine. I n fact , Web services have lit t le t o do w it h t he brow ser- cent ric, HTML- focused World Wide Web. Som et im es, t he nam es w e choose in t he inform at ion t echnology ( I T) indust ry don't m ake a lot of sense; t hey sim ply t ake on a life of t heir ow n.

  Anot her im port ant point is t hat a Web service's im plem ent at ion and deploym ent plat form det ails are not relevant t o a program t hat is invoking t he service. A Web service is available t hrough it s declared API and invocat ion m echanism ( net w ork prot ocol, dat a encoding schem es, and so on) . This is analogous t o t he relat ionship bet w een a Web brow ser and a Web applicat ion server: Very lit t le shared underst anding exist s bet w een t he t w o com ponent s. The Web brow ser doesn't part icularly care if t he Web applicat ion server is Apache Tom cat , Microsoft I I S, or I BM Websphere. The shared underst anding is t hat t hey bot h speak HTTP and converse in HTML or a very lim it ed set of MI ME t ypes. Sim ilarly, t he Web applicat ion server really doesn't care w hat kind of client is using it — various brands of Web browsers or even non- browser client s. This m inim al shared underst anding bet w een com ponent s allow s Web services t o form a syst em of loosely coupled com ponent s.

Business Perspective

  To a business person, t he Web services approach is all about int egrat ion: int egrat ing applicat ion funct ionalit y w it hin an organizat ion or int egrat ing applicat ions bet w een business part ners ( in a supply chain, for exam ple) . The scenario in t his book illust rat es t his approach, part icularly in Chapt er 7 , " Discovering Web Services." This applicat ion int egrat ion allow s t im e and cost efficiencies for receiving purchase orders, answ ering st at us inquiries, processing shipm ent request s, and so on. The im port ant point is t hat applicat ion int egrat ion is enabled w it hout t ight lock- in t o any part icular business part ner. I f anot her supplier has a bet t er price, shipping t erm s, or qualit y assurance, t hen a com pany's reorder syst em s can be easily reposit ioned t o use t hat supplier; doing so is as easy as point ing a Web brow ser at a different Web sit e. Wit h a broader adopt ion of Web services and XML docum ent form at st andards, t his st yle of dynam ic business part ner int egrat ion w ill becom e m ore broadly used. When syst em s are t his easy t o int egrat e, an organizat ion's reach t o suppliers, cust om ers, and ot her business part ners is ext ended, yielding cost savings, flexible business m odels, bet t er cust om er service, higher cust om er ret ent ion, and so on. Just as I T is fundam ent al t o t he efficient operat ions of an organizat ion, Web services- based syst em s int egrat ion w ill be fundam ent al t o flexible, light w eight syst em s int egrat ion—for int ernal applicat ion int egrat ion w it hin an organizat ion over an int ranet and ext ernal part ner int egrat ion over t he I nt ranet or ext ended virt ual privat e net w ork. So, from a business perspect ive, a Web service is a business process or st ep wit hin a business process t hat is m ade available over a net w ork t o int ernal and/ or ext ernal business part ners t o achieve som e business goal.

Technical Perspective

  From a t echnical perspect ive, a Web service is not hing m ore t han a collect ion of one or m ore relat ed operat ions t hat are accessible over a net w ork and are described by a service descript ion. At t his level, t he Web services concept is not new . Wit h Web services, t he I T indust ry is t rying t o address t he fundam ent al challenge of dist ribut ed com put ing t hat has been around for decades—locat ing and accessing rem ot e syst em s. The big difference is t hat now t he indust ry is approaching t his problem using open t echnology ( XML and I nt ernet prot ocols) and open st andards m anaged by broad evolut ion of t he SOAP and WSDL specificat ions) . Furt her, t he approach oft en t aken w it h Web services uses capabilit ies- based lookup , w here t he kind of service is searched for, as opposed t o a service of a part icular nam e or obj ect ident ifier.

The Web Service Opportunity

  The Web services approach is an applicat ion int egrat ion concept ; it is a set of t echnologies t hat provides access t o business funct ionalit y, such as purchase order processing. Oft en, t he business funct ionalit y already exist s in t he form of legacy t ransact ion processing syst em s, exist ing Web applicat ions, Ent erprise Java Beans, and so on. Web services t echnology is about access and applicat ion int egrat ion; it is not an im plem ent at ion t echnology.

  Organizat ions use Web services t echnology in t w o broad cat egories: Ent erprise Applicat ion I nt egrat ion ( EAI ) and business- t o- business ( B2B) part ner int egrat ion over t he I nt ernet . I n eit her of t hese cat egories, Web services can range in sophist icat ion from sim ple request response funct ions such as a credit card check t o very com plicat ed m ult i- part y, m ult i- st age long- running business t ransact ions such as a supply configurat ion and order syst em . Web services can be invoked by PC- based program s, m ainfram e syst em s, Web browsers, or even sm all m obile devices such as cell phones or personal digit al assist ant s ( PDAs) .

  Regardless of t he applicat ion, Web services w ill be used for syst em s int egrat ion: flexible, loosely- coupled syst em s int egrat ion yielding syst em s t hat can be decom posed and recom posed t o reflect changes in t he business.

Enterprise Application Integration

  Ent erprise Applicat ion I nt egrat ion is st ill a field w here large consult ing com panies com m and m ult im illion dollar cont ract s t o help t heir client s deal w it h a m ess of applicat ions t hat w ere never m eant t o int eroperat e. The st at e of t he art wit hin m any ent erprise syst em s rem ains t hat of large, m onolit hic applicat ion " silos." These syst em s are oft en ext rem ely difficult t o change, let alone int egrat e w it h ot her syst em s. These applicat ions oft en define unique dat a form at s, and som et im es ( for hist orical, oft en perform ance- relat ed reasons) even define t heir ow n com m unicat ions prot ocols. Furt herm ore, m any syst em s, part icularly in large organizat ions, can exist on m ult iple different plat form t echnologies. I nt eroperabilit y bet w een syst em s is a significant challenge. I n m any organizat ions, part icularly organizat ions t hat result from a m erger of t w o previously independent com panies, I T int egrat ion cost s can seriously im pact t he financial healt h of t he com pany. The Web services approach offers an at t ract ive set of t echnologies by w hich exist ing legacy syst em s can be w rappered as Web services and m ade available for int egrat ion w it h ot her syst em s w it hin t he organizat ion. Applicat ions exposed as Web services are accessible by ot her applicat ions running on different hardw are plat form s and w rit t en in different program m ing languages. Using t his approach, t he com plexit y of t hese syst em s can be encapsulat ed behind indust ry- st andard XML prot ocols. Pair- w ise syst em int egrat ion proj ect s can be replaced w it h one- t o- m any syst em s int eract ions based on Web services. The prom ise of higher- level int eroperabilit y init iat ives is t hat over t im e w e w ill be able t o develop t he set of st andards, t echnologies, and t ools t hat w ill enable sm all and large businesses all over t he w orld t o easily int egrat e syst em s int ernally, and t hen m ix and m at ch t he im plem ent at ion of various act ivit ies w it hin a business process, m aint aining t he opt ion t o, at any t im e, choose t o out source any or all of t hese act ivit ies if doing so m akes business sense.

  For m any organizat ions, t heir first im plem ent at ions using Web services t echnology w ill be w it h I T. Flexible syst em s w ill yield flexible business m odels. Flexible business m odels w ill yield organizat ions bet t er able t o adapt t o changes in t he business environm ent .

B2B

  Anot her key driver behind t he rise of Web services is t he cont inuing evolut ion of B2B com put ing. B2B com put ing is about int egrat ing t he business syst em s of t w o or m ore com panies t o support cross- ent erprise business processes such as supply chain m anagem ent . Som e indust ry pundit s claim t hat supply chain int egrat ion w ill be t he killer applicat ion of Web services, part icularly as a result of t he st andardizat ion of com m on indust ry form at s for XML and Web services relat ed t o supply chain business processes. B2B applicat ions can be as sim ple as aut om at ed credit card validat ion or as com plex as t he full aut om at ion of t he m ult i- billion- dollar supply chain of a Fort une 100 com pany. The challenges of building B2B applicat ions com bined w it h t heir huge m arket pot ent ial drove rapid innovat ion t hat has t aken t he indust ry from sim ple business- t o- consum er ( B2C) applicat ions t o SOAP- enabled Web services in a m at t er of five years. B2C, B2B, and Web services Online HTML- based applicat ions are consum er- orient ed. The classic exam ple of a B2C Web applicat ion is t he Am azon book search. To access t his funct ionalit y, a hum an being needs t o use a Web brow ser t o navigat e t he com pany's sit e t hrough m ult iple page t ransit ions, input inform at ion using Web form s, subm it t hem , and get t he result s back in hum an- readable form . The only w ay t o aut om at e t his process is t o sim ulat e how a hum an uses t he syst em . Doing so involves reverse- engineering t he Web applicat ion t o see how it m oves dat a bet w een pages, passing t he dat a aut om at ically from page t o page, and, finally, parsing any dat a cont ained in t he response HTML of pages. This screen- scraping approach w as popular in t he early years of t he Web ( 1995–97) . I t is very error prone. Any changes in t he Web applicat ion—even changes t hat are com plet ely UI - cent ric and do not change t he dat a being passed back and fort h—can break screen- scraping applicat ions. These problem s are com pounded because m ost of t hese applicat ions do not properly separat e present at ion from applicat ion processing logic. The only t rue w ay t o int egrat e applicat ions on t he Web is t o use a B2B- focused solut ion. Because B2B applicat ions are designed t o have ot her applicat ions as t heir client s, t hey are fundam ent ally different from B2C applicat ions. Table 1.1 sum m arizes som e of t hese differences for Java applicat ions. Bot h t ypes of applicat ion are unrest rict ed as t o t he t ype of backend t hey can use—t ypically, Java classes or Ent erprise Java Beans ( EJBs) . ( We discuss how Web services w ork w it h EJBs in m ore det ail in Chapt er 5 , " Using SOAP for e- Business." ) This is where t he sim ilarit ies end, however. To cust om ize backend logic, B2C applicat ions use servlet s or Java Server Pages ( JSPs) t hat are host ed in a servlet engine. B2B applicat ions cust om ize t heir backends using st raight Java code ( oft en EJBs) t hat is host ed inside a Web service engine. B2C applicat ions com m unicat e w it h a brow ser over HTTP. B2B applicat ions can use any of t he open I nt ernet prot ocols such as HTTP, SMTP, or FTP, or propriet ary net w orks such as EDI . B2C applicat ions handle dat a over t he st raight HTTP prot ocol. I nput com es as GET param et ers ( on t he URL/ query st ring) or as POST param et ers from Web form s. Only st rings can be exchanged. Any ot her dat at ypes, even num bers, need t o be encoded as st rings. For out put , dat a is m ixed t oget her w it h form at t ing rules inside HTML pages. This is in m arked cont rast w it h B2B applicat ions t hat use XML for bot h dat a input and out put . XML is perfect for B2B com put ing because it is program m ing language- and plat form - neut ral, it can represent arbit rary dat a st ruct ures, it is easy t o process, and it can be validat ed independent ly of it s processing. B2C applicat ions need t o have som e UI ( t ypically HTML, alt hough som e have used Java applet s) because t heir client s are hum ans. B2B applicat ions have no UI because t heir client s are ot her applicat ions.

Table 1.1. Comparing B2C and B2B Java Applications

Area B2C application B2B application

  Backend logic Java classes and EJBs Java classes and EJBs Custom logic Servlets and JSPs Web service engine Communication HTTP HTTP, SMTP, FTP, TCP/IP, EDI, protocol JMS, RMI/IIOP… Data input HTTP GET/POST

  XML parameters Data output HTML

  XML UI HTML + script N/A Client Human behind a Software application browser

Trends in e-business I t is clear t hat t he net w ork econom y is current ly driving t he evolut ion of business

  Businesses m ust respond t o increasingly dynam ic m arket places. Wit hin corporat e depart m ent s, applicat ion int egrat ion has been a m aj or issue in t he last few years. Tradit ional archit ect ures are brit t le, and t his brit t leness is being exposed as t he scale, dem and level, t ransact ion volum e, and rat e of change of t ransact ion volum e increases.

  I nt eroperabilit y, part icularly bet w een het erogeneous dist ribut ed syst em s com ponent s, has been one of t he m aj or t hem es in soft w are engineering in general, and EAI in part icular, for t he last decade. I t 's unfort unat e t hat t he seam less int eroperabilit y vision is st ill a dream . Brit t leness in all current archit ect ures is prevent ing soft w are from achieving t his vision. Brit t leness com es from t ight ly coupled syst em s t hat generat e dependencies at every level in t he syst em . One of t he m ost im port ant lessons w e learned as developers and archit ect s is t hat syst em s need t o be able t o find resources ( soft w are or ot herwise) aut om at ically, w hen and as needed, w it hout hum an int ervent ion. This abilit y frees business people t o concent rat e on t heir business and cust om ers rat her t han w orry about

  I T com plexit ies. At t he sam e t im e, it frees syst em developers t o concent rat e on enabling t heir business and t heir cust om ers rat her t han deal w it h int eroperabilit y headaches by w rit ing glue code and pat ching syst em s t oget her. More t han any t echnical considerat ion, t his concept of im plicit , seam less int egrat ion as a m aj or business benefit is one of t he m ain drivers for service orient at ion. I n ot her w ords, t he t im e has com e for " j ust in t im e" int egrat ion! Trends in applicat ion design are m oving from rigid st ruct ures t o flexible archit ect ures. Trends in business part ner int eract ions are m oving from st at ic agreem ent s t o m ore dynam ic agreem ent s. Trends in B2B int egrat ion are m oving from t echnology- based int egrat ion t o business process- based int egrat ion. There is a corresponding shift in program m ing and archit ect ure m odels t o enable t hese t rends: from t ight ly coupled applicat ions t o loosely coupled services. On t he t echnical side, m aj or shift s have occurred t ow ard flexibilit y and int eroperabilit y, t hrough open and w idely accept ed st andards. The first m aj or shift happened t w o decades ago wit h t he advent of TCP/ I P as an open plat form for net w orking. This st ep enabled such im port ant and pervasive archit ect ures as client - server com put ing. I t t ook t he advent of t he World Wide Web for t he next m aj or shift , w it h HTML and HTTP providing t he first t ruly universal open and port able user int erface. Next , Java gave us t ruly open port able program m ing, and finally XML brought w it h it open port able dat a exchange. The next st ep in t his evolut ion of open st andards is t he int egrat ion st ep. How do all t hese ingredient s com e t oget her t o facilit at e t he next evolut ion of e- business? Web services.

  One aspect of m ore loosely coupled syst em s is reflect ed in t he m ove from Rem ot e Procedure Call ( RPC) int erfaces t ow ards a m essaging or docum ent - cent ric m odel of dist ribut ed com put ing int erface. Wit h a docum ent - cent ric approach, t he int erface t o t he Web service becom es m uch m ore sim ple and flexible. An RPC int erface present ing a fixed set of param et ers in a fixed order is quit e brit t le. Sm all changes t o inform at ion required— for exam ple, a new requirem ent for an expirat ion dat e on a credit card—require a new int erface t o be creat ed, published, and underst ood by t he service request or. Wit h a docum ent - cent ric approach, t he new inform at ion can be added t o t he docum ent schem a defined in t he Web service int erface. Program s t hat use t he older schem a don't necessarily break w hen t he new XML elem ent is added ( t his is a propert y of XML nam espaces t hat you w ill see in Chapt er 2 , " XML Prim er" ) . This approach yields Web services int erfaces t hat are m uch m ore flexible, result ing in syst em s t hat are m uch m ore adapt ive.

  Web Services Market Dynamics

  Most m aj or soft ware com panies and m any sm aller soft ware vendors have em braced t he concept of Web services in one form or anot her. Som e m ight j ust be giving it lip service, hedging on whet her it 's j ust anot her fad, or using it as a buzzw ord t o generat e m arket ing fodder. Ot hers have st aked t heir fut ure on it . Here is a brief exam inat ion of t he Web services init iat ives from a few m aj or players:

  IBM: Dynamic e-business—IBM provides a broad collection of • Web services technology, including a SOAP stack as part of

WebSphere (derived from Apache SOAP 2.2), WSDL tooling in the

Web Services Toolkit, and a UDDI implementation. Many major products within IBM are incorporating the Web services approach in some fashion.

  Microsoft: .NET—It can be argued that Microsoft is "betting • the business" on the success of .NET. Although .NET is based on Web services technologies, the .NET initiative is much broader than Web services, including a new programming language, C#, and a common runtime layer upon which implementations of multiple programming languages can be built. We will look at .NET in more detail in

  "Interoperability, Tools, and Middleware Products."

  • Sun: SunOne ( Open Net Environm ent) — Sun declared the notion of sm art Web services t hat can som ehow underst and t he cont ext in which t hey w ere deployed or invoked ( such as user ident it y, t ype of client device and privacy policy, and so on) . Sm art Web services includes a st andard for sharing t his not ion of " cont ext " and an infrast ruct ure SunONE upon w hich t o deploy it .

  Sun's approach to Web services is fairly similar to the approach taken by the other major IT vendors, in that Sun bases its Web services technology on the core XML, SOAP, WSDL, UDDI technology set. Sun also augments these technologies with technologies derived from ebXML. The together. Sun's sponsorship of the Java Community Process and its definition of Java specifications related to Web services is also a major component of the company's Web services initiative.

  • Oracle: Oracle 9i Web Services Broker— The Oracle approach to Web services also follow s t he t radit ional SOAP, WSDL, UDDI perspect ive. Oracle em phasizes t he role of it s dat abase t echnology as a service regist ry ( broker) providing securit y and ot her value added services as an int erm ediary bet w een service request or and service provider.
  • Macrom edia: Macrom edia platform — Macrom edia has em braced Web services t hroughout it s m ass- ent erprise plat form . I t s rich client s can display inform at ion ret rieved t hrough Web services, it s applicat ion servers m ake building Web services possible for developers at all skill levels, and it s t ools provide high- level support for building applicat ions t hat leverage Web services.

  I t is excit ing t o see so m any soft ware vendors act ive in Web services. Wit h m ult iple vendors, t here is a risk of incom pat ibilit y of im plem ent at ions. Unless Web services from different vendors can int eroperat e, Web services w ill fail t o at t ain crit ical m ass of adopt ion. Happily, t here is significant focus am ong t he various Web services im plem ent at ions t o develop and m aint ain int eroperabilit y.

  Chapt er 8 w ill look at a collect ion of Web services im plem ent at ions in t he

  indust ry, from large soft w are vendors t o sm aller bout ique Web services infrast ruct ure providers.

Why Do We Need a Web Services Approach?

  The beginning of t his chapt er explained t he m ot ivat ion for applicat ion- t o- applicat ion com m unicat ion over t he I nt ernet t o address t he current challenges of dist ribut ed com put ing and B2B int egrat ion in part icular. Since 1999, t he soft w are indust ry has been rapidly evolving XML- based Web services t echnologies as t he approach t o t hese problem s. I n t he m aelst rom of press hype, product releases, and st andards announcem ent s, m any people have been left w ondering w het her t his is a good in w hich direct ion t o go. Aft er all, w e already have m any different m echanism s for dist ribut ed com put ing. Surely, som e of t hem w ould be able t o rise t o m eet t he challenges of e- business. Why build a com plet ely new dist ribut ed com put ing st ack based on Web services? This is a very good quest ion and one t hat is hard t o give a short answ er t o. " Because Web services use XML" is not t he right answ er. I t is a correct observat ion, but it doesn't answ er t he crucial quest ion as t o w hy using XML m akes such a big difference. At a basic level, t here are t hree key reasons w hy exist ing dist ribut ed com put ing approaches are inferior t o Web services for solving t he problem s of e- business:

  The scope of problems they try to address • The choice of available technology • Industry dynamics around standards control and innovation • Tradit ional dist ribut ed com put ing m echanism s have t ypically evolved around t echnical archit ect ures rat her t han broader problem s of applicat ion int egrat ion. For exam ple, CORBA evolved as a solut ion t o t he problem of im plem ent ing rich dist ribut ed obj ect archit ect ures. At t he t im e, it w as im plicit ly assum ed t hat t his w as t he right approach t o get t ing applicat ions t o com m unicat e w it h one anot her. As w e discussed earlier, experience has show n t hat RPCs are not alw ays t he best archit ect ure for t his requirem ent . The need for loosely coupled applicat ions and business process aut om at ion has clearly shown t he benefit s of sim ply exchanging m essages cont aining dat a ( t ypically a business docum ent ) bet w een t he part icipant s of e- business int eract ions, a so- called docum ent - cent ric approach. Dist ribut ed com put ing specificat ions address m essaging as a com put ing archit ect ure; how ever, t here has been no unifying approach t hat brings RPCs and m essaging t o t he sam e level of im port ance—unt il Web services, t hat is.

  Web services have evolved not around pre- defined archit ect ures but around t he problem of applicat ion int egrat ion. This is a very im port ant dist inct ion. The choice of problem scope defines t he focus of a t echnology init iat ive. Web services t echnologies have been designed from t he ground up t o focus on t he problem s of applicat ion int egrat ion. As a result , w e are able t o do t hings out side t he scope of t radit ional dist ribut ed com put ing approaches:

  Support both document-centric messaging and RPCs

  • Transport encoded data from both applications and business documents • Work over open Internet protocols such as HTTP and SMTP •

  I n ot her words, Web services are bet t er suit ed for t he t ask t han what we have so far because w e have specifically built t hem w it h t his in m ind. COM/ CORBA/ RMI are st ill great t echnologies for t ying t oget her dist ribut ed obj ect s on t he corporat e net w ork. How ever, t he e- business applicat ion int egrat ion problem is best t ackled by Web services.

Core Technologies

  Because Web services address a m uch m ore broadly scoped problem , t hey use m uch m ore flexible t echnologies t han t radit ional dist ribut ed com put ing approaches. Furt her, w it h Web services w e can leverage all t hat w e have learned about connect ing and int egrat ing applicat ions since w e first st art ed doing dist ribut ed com put ing. These t w o fact ors put Web services on a bet t er t echnology foundat ion for solving t he problem s of e- business t han t radit ional dist ribut ed com put ing approaches.

  Lat er, in t he " Web Services I nt eroperabilit y St acks " sect ion, w e int roduce t he not ion of Web services int eroperabilit y st acks. These int eroperabilit y st acks organize a layering of t echnologies t hat define t he capabilit ies of Web services. I t is possible t o com pare t he Web services approach t o t radit ional dist ribut ed com put ing approaches level- by- level t o see w hy t he t echnical foundat ion of Web services is m ore appropriat e for t he problem s it needs t o solve. Rat her t han going t hrough t his lengt hy process, let 's focus on t w o key capabilit ies: t he abilit y t o represent dat a st ruct ures and t he abilit y t o describe t hese dat a st ruct ures.

  Dat a encoding is a key w eakness for t radit ional dist ribut ed com put ing approaches,

  part icularly t hose t hat are program m ing language independent . Sure, t hey t ypically have a m echanism t o represent sim ple dat a ( num bers, st rings, booleans, dat e- t im e values, and so on) , basic arrays, and st ruct ures w it h propert ies. How ever, m apping exist ing com plex dat at ypes in applicat ions t o t he underlying dat a encoding m echanism s w as very difficult . Adding new nat ive dat at ypes w as pract ically im possible ( doing so required a com plet e updat e of specificat ions) . The fact t hat dat a w as encoded in binary form at s furt her com plicat ed m at t ers. For exam ple, processing code had t o w orry about lit t le- vs. big- endian issues w hen reading and w rit ing num bers.

  Web services address t hese issues by using XML t o represent inform at ion. XML's t ext - based form elim inat es byt e ordering concerns. The w ide availabilit y of XML processing t ools m akes part icipat ion in t he w orld of Web services relat ively easy. XML's hierarchical st ruct ure ( achieved by t he nest ing of XML elem ent s) allows changes at som e level of nest ing in an XML docum ent t o be m ade w it h ease w it hout w orrying about t he effect on ot her part s of t he docum ent . Also, t he expressive nat ure of at t ribut es and nest ed elem ent s m akes it considerably easier t o represent com plex dat a st ruct ures in XML t han in t he pure binary form at s t radit ionally used by COM and CORBA, for exam ple. I n short ,

  XML m akes w orking w it h arbit rary dat a easier. The choice of XML brought anot her advant age t o Web services—t he abilit y t o describe dat at ypes and validat e w het her dat a com ing on t he w ire com plies w it h it s specificat ion. This happens t hrough t he use of XML m et a- languages such as XML Schem a. Binary dat a encodings t ypically used for dist ribut ed com put ing offered no such m echanism and t hus pushed dat a validat ion int o applicat ion logic, considerably com plicat ing applicat ions dealing w it h non- t rivial dat a.

  Industry Dynamics

  Mom ent um is a very im port ant aspect of t he dynam ics of soft w are innovat ion. Great problem s gat e great opport unit ies. The desire t o capit alize on t he opport unit ies generat es m om ent um around a set of init iat ives t arget ed at solving t he problem . This m om ent um is t he binding force of our indust ry. This is how m aj or innovat ion t akes place on a broad scale. The challenge of e- business applicat ion int egrat ion is great ; t his is w hy all t he key players in t he indust ry are focused on it ( see t he sidebar " Web Services

  Market Dynam ics " ) . Cust om er need, m arket pressure, and t he desire t o be part of t he

  front ier- defining elit e have pushed m any com panies t o becom e deeply engaged w it h Web services. Good t hings are bound t o happen. Consider t his: The last t im e every one of t he key infrast ruct ure vendors was focused on t he sam e set of issues was during t he early days of e- business w hen t he indust ry w as t rying t o address t he challenges of building Web applicat ions. The net result w as a new m odel for applicat ion developm ent t hat leveraged t he Web brow ser as a universal client and t he Web applicat ion server as a universal backend. I n short , t rust t hat som e of t he very best m inds in t he indust ry w orking t oget her under t he aegis of organizat ions such as t he W3C and OASI S w ill be able t o com e up w it h a good solut ion t o t he problem s of e- business int egrat ion. To t he vet erans of t he soft w are indust ry, m om ent um som et im es equals hype. So, are w e t rying t o say t hat Web services w ill succeed because t here is so m uch hype around t hem ? Absolut ely not ! The m om ent um around Web services is real and different from w hat w e have experienced so far w it h ot her dist ribut ed com put ing fads. The fundam ent al difference is around t he abilit y of m any indust ry players t o engage in com plem ent ary st andardizat ion in parallel.

  Parallelism is key t o building real m om ent um and increasing t he bandw idt h of innovat ion. Tradit ional dist ribut ed com put ing effort s could not achieve t his kind of parallelism because t hey w ere eit her driven by a single vendor—Microsoft prom ot ing COM, for exam ple—or t hey w ere driven by a large, slow organizat ion such as t he Obj ect Managem ent Group ( OMG) , w hich ow ns t he CORBA st andards. I n bot h cases, t he key barrier t o fast progress w as t he cent ralized m anagem ent of st andards. Any change had t o be approved by t he body ow ning t he st andard. And Microsoft and OMG ow ned all of COM and CORBA, respect ively. This is no w ay t o gain real m om ent um , regardless of t he size of t he m arket ing budget s t o prom ot e any given t echnology. Vendors t hat feel t hey have very lit t le cont rol over t he evolut ion of a t echnology w ill likely spend very lit t le t im e invest ing in it s evolut ion. I n ot her w ords, you m ight use COM, but if you t hink you have no chance of influencing Microsoft 's direct ion on COM you w ill probably not spend m uch t im e t hinking about and prot ot yping w ays t o im prove COM. Open- source effort s such as t he Linux operat ing syst em and proj ect s of t he Apache Soft w are Foundat ion fundam ent ally generat e m om ent um because people w orking on t hem can have a direct st andardizat ion w ork is going on in parallel at t he W3C, OASI S, UDDI , and m any ot her horizont al and vert ical indust ry st andards organizat ions. Furt her, t he m aj or players so far have show n a com m it m ent t o do a lot of innovat ion out in t he open. The int erest ing t hing from a t echnical perspect ive is t hat XML act ually has som et hing t o do w it h t he abilit y of Web service st andardizat ion t o be parallelized. XML has facilit ies ( nam espaces and schem a) t hat enable t he decent ralized evolut ion of XML- based st andards w it hout prevent ing t he lat er com posit ion of t hese st andards in t he cont ext of a single solut ion. For exam ple, if group A ow ns som e st andard and group B is t rying t o build an ext ension t o t he st andard, t hen w it h som e careful use of XML, group B can design t he ext ensions such t hat :

  Its extension can be published independently of the standard. • Its extension can be present in cases where the standard is used. • Applications that do not understand the extension will not break if

  • the extension is present. Applications that need the extension will only work if the extension • is present.

  The indust ry's focus on Web services com bines t he right scope ( e- business applicat ion int egrat ion) w it h t he right t echnologies ( XML- based st andards) w it h t he pot ent ial for significant parallelism and high- bandw idt h innovat ion. This is w hy Web services w ill be successful.

Distributed Computing History

  Hist orically, dist ribut ed com put ing has been focused on t he problem of dist ribut ing com put at ion bet w een several syst em s t hat are j oint ly w orking on a problem . The m ost oft en used dist ribut ed com put ing abst ract ion is t he RPC. RPCs allow a rem ot e funct ion t o be invoked as if it w ere a local one. Dist ribut ed obj ect - orient ed syst em s require obj ect - based RPCs ( ORPCs) . ORPCs need som e addit ional cont ext t o be able t o invoke m et hods on specific obj ect inst ances. The hist ory of RPC- st yle dist ribut ed com put ing and dist ribut ed obj ect s is fairly com plicat ed. The follow ing t im eline illust rat es som e of t he key event s:

  1987 •

  o

  Sun Microsystems developed the Open Network Computing (ONC) RPC system as the basic communication mechanism for its Network File System (NFS).

  o

  Apollo Computer developed the Network Computing System (NCS) RPC system for its Domain operating system. 1989 •

  o The Open Software Foundation (OSF, now The Open Group)

  issued a Request for Technology (RFT) for an RPC

system. OSF received two key submissions. The first submission came from HP/DEC based on NCS (HP had based on ONC. OSF selected NCS as the RPC mechanism for its Distributed Computing Environment (DCE).

  o The Object Management Group (OMG) was formed to deliver

  language- and platform-neutral specifications for distributed computing. (The consortium includes about 650 members as of the time of this writing.) The OMG began development of specifications for Common Object Request Broker Architecture (CORBA), a distributed objects platform.

  1990

  • o Microsoft based its RPC initiatives on a modified version of DCE/RPC.

  1991 •

  o DCE 1.0 was released by OSF. o CORBA 1.0 shipped with a single language mapping for

  the C language. The term Object Request Broker (ORB) gained popularity to denote the infrastructure software that enables distributed objects. 1996 •

  o Microsoft shipped the Distributed Component Object

  Model (DCOM), which was closely tied to previous Microsoft component efforts such as Object Linking and Embedding (OLE), non-distributed COM (a.k.a. OLE2), and ActiveX (lightweight components for Web applications). The core DCOM capabilities are based on Microsoft's RPC technologies. DCOM is an ORPC protocol.

  o

  CORBA 2.0 shipped with major enhancements in the core distributed computing model as well as higher-level services that distributed objects could use. The Internet Inter-ORB Protocol (IIOP) was part of the specification. IIOP allows multiple ORBs to interoperate in a vendor-agnostic manner. IIOP is an ORPC protocol. 1997 •

  o Sun shipped JDK 1.1, which included Remote Method

  Invocation (RMI). RMI defines a model for distributed computing using Java objects. RMI is similar to CORBA

  

ORPC protocol called Java Remote Method Protocol

(JRMP).

  o Microsoft announced the first iteration of COM+, the

  successor of DCOM. The capabilities of COM+ brought it much closer to the CORBA model for distributed computing. 1999

  • o Sun shipped J2EE (Java 2 Platform Enterprise Edition).

  The Java 2 platform integrated RMI with IIOP, making it easy to interoperate between Java and CORBA systems.

  o Simple Object Access Protocol (SOAP) appeared for the first time. The era of Web services was born. Alt hough RPCs and dist ribut ed obj ect s have been t he t radit ional approaches for building dist ribut ed syst em s, t hey are by no m eans t he only ones. Anot her very im port ant approach is t hat of dat a- orient ed or docum ent - cent ric m essaging. Rat her t han being focused on dist ribut ing com put at ion by specifically invoking rem ot e code, m essaging t akes a different approach. Applicat ions t hat com m unicat e via m essaging run t heir ow n independent com put at ions and com m unicat e via m essages t hat cont ain pure dat a. Messaging w as popularized via t he effort s of syst em int egrat ors w ho w ere t rying t o get highly het erogeneous syst em s t o int eroperat e. I n m ost cases, t he syst em s were so different t hat t he requirem ent t o perform fine- grain int egrat ion via RPCs w as im possible t o sat isfy. I nst ead, syst em int egrat ors w ere happy t o be able t o reliably m ove pure dat a bet w een t he syst em s. Com m ercially, t he im port ance of m essaging applicat ions has been st eadily grow ing since I BM released it s m essaging product MQSeries in 1993. Microsoft 's m essaging product is t he Microsoft Message Queuing Server ( MSMQ) . J2EE defines a set of API s for m essaging t hrough t he Java Messaging Service ( JMS) . There has been no at t em pt t o define a st andard int eroperabilit y prot ocol for m essaging servers. One of t he key benefit s of Web services is t hat t he core Web service prot ocols can support RPCs and m essaging w it h equal ease. Chapt er 3 , " Sim ple Obj ect Access Prot ocol ( SOAP) ," has a sect ion t hat addresses t his t opic in det ail.

  Service-Oriented Architectures

  Early on in t he Web services t echnology evolut ion, w e not iced a pat t ern. Each t im e w e applied Web services t echnologies t o an applicat ion int egrat ion problem , a pat t ern em erged. We called t his pat t ern service- orient ed archit ect ure ( SOA) . SOA is a sim ple concept , w hich m akes it applicable t o a w ide variet y of Web services sit uat ions. Figure

  1.1 depict s t he m ain roles and operat ions in an SOA.

Figure 1.1. Service-oriented architecture. Any service- orient ed archit ect ure cont ains t hree roles: a service request or , a service provider , and a service regist ry :

  A service provider is responsible for creating a service description • , publishing that service description to one or more service registries, and receiving Web service invocation messages from one or more service requestors. A service provider, then, can be any company

that hosts a Web service made available on some network. You can

think of a service provider as the "server side" of a client-server relationship between the service requestor and the service provider.

  • A service requestor is responsible for finding a service description

  published to one or more service registries and is responsible for using service descriptions to bind to or invoke Web services hosted by service providers. Any consumer of a Web service can be considered

a service requestor. You can think of a service requestor as the

"client side" of a client-server relationship between the service requestor and the service provider.

  The service registry is responsible for advertising Web service • descriptions published to it by service providers and for allowing service requestors to search the collection of service descriptions contained within the service registry. The service registry role is

simple: be a match-maker between service requestor and service provider. Once the service registry makes the match, it is no longer between the service requestor and the service provider for the Web service invocation.

  Each of t hese roles can be played by any program or net w ork node. I n som e circum st ances, a single program m ight fulfill m ult iple roles; for exam ple, a program can be a service provider, providing a Web service t o dow nst ream consum ers as w ell as a service request or, it self consum ing Web services provided by ot hers.

  An SOA also includes t hree operat ions: publish , find , and bind . These operat ions define t he cont ract s bet w een t he SOA roles:

  • The publish operation is an act of service registration or service

  advertisement. It acts as the contract between the service registry and the service provider. When a service provider publishes its Web

service description to a service registry, it is advertising the

details of that Web service to a community of service requestors. The actual details of the publish API depend on how the service registry is implemented. In certain simple or "direct publish" scenarios, the service registry role is played by the network itself, with publish

being simply an act of moving the service description into a Web

application server's directory structure. Other services registry implementations, such as UDDI, define a very sophisticated implementation of the publish operation. The find operation is the logical dual of the publish operation. The •

find operation is the contract between a service requestor and a

service registry. With the find operation, the service requestor

states a search criteria, such as type of service, various other

aspects of the service such as quality of service guarantees, and so

on. The service registry matches the find criteria against its

collection of published Web service descriptions. The result of the find operation is a list of service descriptions that match the find criteria. Of course, the sophistication of the find operation varies with the implementation of the service registry role. Simple service registries can provide a find operation with nothing more sophisticated than an unparameterized HTTP GET. This means the find operation always returns all Web services published to the service registry and it is the service requestor's job to figure out which Web service description matches its needs. UDDI, of course, provides extremely powerful find capabilities.

  The bind operation embodies the client-server relationship between

  • the service requestor and the service provider. The bind operation can be quite sophisticated and dynamic, such as on-the-fly generation

    of a client-side proxy based on the service description used to invoke the Web service; or it can be a very static model, where a

    developer hand-codes the way a client application invokes a Web

The key t o SOA is t he service descript ion. I t is t he service descript ion t hat is published by t he service provider t o t he service regist ry. I t is t he service descript ion t hat is ret rieved by t he service request or as a result of t he find operat ion. I t is a service descript ion t hat t ells t he service request or everyt hing it needs t o know in order t o bind t o or invoke t he Web service provided by t he service provider. The service descript ion also indicat es w hat inform at ion ( if any) is ret urned t o t he service request or as a result of t he Web service invocat ion. Each t im e a service- orient ed archit ect ure is deployed, t here m ight be different t echnologies t o fulfill each role. Chapt er 7 , " Discovering Web Services," discusses various opt ions for im plem ent ing a service regist ry and goes int o great det ail on t he UDDI service regist ry t echnology. Chapt er 6 , " Describing Web Services," discusses service descript ion and how a service descript ion can be used t o aut om at e t he t ask of building a client - side proxy t o t he Web service and a server- side skelet on t o dispat ch t he Web service invocat ion t o t he t arget Web service im plem ent at ion. Chapt ers 3 and

  4 , " Sim ple Obj ect Access Prot ocol ( SOAP) " and " Creat ing Web Services ," focus on t he use of SOAP

  t o fulfill t he bind operat ion; Chapt er 5 , " Using SOAP for e- Business," det ails how t he bind can be m ade ready for e- business.

Web Services Interoperability Stacks

  An alphabet soup of t echnologies is sw im m ing around t he Web services space. We have

  XML, SOAP, WSDL, UDDI , WSEL, WSFL, and m ore. How can anyone m ake sense of what t hese t echnologies are and how t hey fit t oget her? Well, t hat is one of t he purposes of t his book. To help put a fram ew ork around t hese t echnologies, w e refer t o a t rio of Web services int eroperabilit y st acks, first proposed t o t he W3C by I BM and Microsoft in March 2001 ( ht t p: / / w w w .w 3.org/ 2001/ 03/ WSWS- popa/ paper51 ) . This proposal fact ored Web services t echnologies int o t hree st acks:

  The wire stack • The description stack

  • The discovery stack •

  The cont ent s of t he st acks present ed in t his book reflect a different fact oring t han originally proposed t o t he W3C, due in part t o t he addit ional st andards effort s t hat have com e int o play since March 2001.

  The Wire Stack Figure 1.2 shows t he wire st ack as we define it .

Figure 1.2. The wire stack. The w ire st ack represent s t he t echnologies t hat det erm ine how a m essage is sent from t he service request or t o t he service provider. The base of t he w ire st ack is a net w ork prot ocol. Web services can be based on a variet y of st andard, I nt ernet w ire prot ocols such as HTTP or HTTPS, SMTP, FTP, and so on, as well as sophist icat ed ent erprise- level prot ocols such as RMI / I I OP and MQSeries. For dat a encoding, Web services use XML. I n addit ion, non- XML cont ent can be referenced from a Web service invocat ion m essage, allow ing full flexibilit y in t he kinds of dat a used in t he m essage. For dat a specificat ion, Web services use XML Schem a. This includes bot h cust om schem as in t he case of XML m essaging or schem as conform ing t o a set of pre- defined rules, such as t he SOAP encoding rules discussed in Chapt er 3 . Built on t op of t he net w orking prot ocol and dat a- encoding layers are t he XML m essaging layers. For XML m essaging, Web services use SOAP in all it s dat a encoding, int eract ion st yle, and prot ocol binding variat ions. SOAP is used as a sim ple approach t o w rapper an

  XML m essage in an envelope. The result is a solid, st andards- based foundat ion for Web services. Concept ually layered on t op of t he SOAP enveloping m echanism is a m echanism for envelope ext ensions called SOAP headers . Wit h SOAP headers, ort hogonal ext ensions such as a digit al signat ure can be associat ed w it h t he body of t he m essage cont ained w it hin t he SOAP envelope. Chapt er 3 w ill give det ails on t he SOAP enveloping m echanism and t he SOAP header facilit y. The layers of t his st ack are w ell defined, eit her as st andard net w orking prot ocols or as t he SOAP specificat ion it self. This st ack is t he m ost accept ed and m ost w idely deployed set of t echnologies for Web services. At right in Figure 1.2 are t hree vert ical colum ns represent ing associat ed t echnologies t hat im pact m ult iple levels of t he w ire st ack. Securit y, for exam ple, can appear at each level— SSL at t he net w ork prot ocol level and digit al signat ures at t he envelope ext ensions level, for inst ance. I t is doubt ful t here w ill ever be a single st andard t hat fit s all aspect s of Web services securit y needs. Chapt er 5 goes int o m ore det ail on t he current Web services– handful of facet s of Web services t hat can appear at several levels of t he w ire st ack. There is no w ell- accept ed st andard for t hese facet s, but w ork is underw ay in t hese areas.

The Description Stack

  The w ire st ack is only w here t he capabilit ies of Web services begin. Even t he sim plest exam ple of Web service use show s t he need for a higher level of int eroperabilit y. Consider t he follow ing sit uat ion ( w e'll see t his exam ple in great er det ail in Chapt er 3 ) . A com pany has provided an invent ory checking service, allowing cust om ers t o det erm ine w het her a part icular num ber of it em s are in st ock for a given product code ( as represent ed as a st ock keeping unit [ SKU] ) . The Web service t akes as param et ers a st ring represent ing t he SKU and an int eger represent ing t he num ber of unit s needed. I f t he com pany has on hand t he request ed num ber of unit s, t he Web service responds w it h a Boolean t rue value; ot herw ise, t he response is a Boolean false. From a pure SOAP perspect ive, t he int eract ion w it h t his Web service is t rivial. How ever, t hings get m uch m ore com plicat ed when we consider how m uch com m on underst anding m ust exist bet w een t he service request or and t he service provider. For t he int eract ion t o succeed, at a m inim um , t he service request or needs t o know t he follow ing:

  The address of the Web service.

  • It should make requests and receive responses over HTTP. • It should use SOAP 1.1. • Requests and responses should use the SOAP data encoding.
  • Requests will be RPC requests containing as parameters a string SKU • and an integer indicating the desired quantity. Responses will be RPC responses containing a Boolean indicating the • inventory check outcome.

  Throw in securit y, paym ent s, error handling, and ot her capabilit ies required t o build ent erprise- grade Web services, and t he need for shared know ledge expands even furt her…. How can t he service request or acquire t his inform at ion? Well, t radit ionally Web services have advert ised t heir capabilit ies in som e hum an readable form . Developers have read t he descript ion of t hese capabilit ies and configured user applicat ions t o be able t o com m unicat e w it h part icular Web services.

  While t his approach w orks in principle, it is not scalable for m any reasons:

  It requires costly (in terms of both time and money) manual

  • configuration by highly skilled, and therefore scarce, personnel. It is error prone because it does not utilize formalized service • specifications. It precludes automatic discovery and engagement of Web services; a • priori knowledge is required for configuration of the user application.

  No built-in mechanism exists for change notifications and/or failure • recovery; every time a Web service evolves, there is a risk that existing user applications will fail.

  These are som e of t he reasons w hy indust ry leaders are developing t he st andards described in a service descript ion st ack. Figure 1.3 shows t he service descript ion st ack.

Figure 1.3. The service description stack.

  Key t o t he ent ire service- orient ed archit ect ure approach is t he service descript ion it self. Many aspect s of a Web service need t o be com m unicat ed, and t herefore t he descript ion st ack has m ult iple levels. The focus on service descript ion is t o com m unicat e t hose aspect s of a service t hat m ight be im port ant t o t he service request or. Chapt er 6 goes int o det ail on each of t he t echnologies used for service descript ion.

  I n Web services, XML is t he basis of service descript ion. XML schem a is t he base dat a t ype m echanism in t he service descript ion and all of t he service descript ion t echnologies in t he st ack are expressed using XML. Much of t he pow er of Web services is derived from

  The next t w o levels of t he st ack, service im plem ent at ion and service int erface, are described using t he Web Services Descript ion Language ( WSDL) . WSDL is a not e t o t he W3C, and t here is act ive w ork t o refine t his language int o a st andard. WSDL is t he int erface definit ion language for Web services; it is t he key t o underst anding Web services. Wit h WSDL, a developer describes t he set of operat ions support ed by a Web service, including t he kinds of obj ect s t hat are expect ed as input and out put of t he operat ions, t he various bindings t o concret e net w ork and dat a encoding schem es. This level const it ut es t he core definit ion of t he service's int erface. The service im plem ent at ion defines t he net w ork address w here t he service it self can be invoked. WSDL allow s for aut om at ic code- generat ion of Web service client s based on t his inform at ion.

  But I DL is not enough for Web services. Ot her aspect s of t he Web service could affect w het her a service request or w ould choose t o bind t o a Web service. For exam ple, if t w o different service providers host im plem ent at ions of t he sam e service int erface, perhaps a st ock quot e service, t hen from t he I DL perspect ive, t he services are alm ost indist inguishable: The net w ork address is t he only difference. How ever, t he service providers m ight differ w idely in t heir privacy policy, cost t o use, t im eliness of response, and so on. These non- operat ional charact erist ics m ight be crit ical t o t he service request or. The role of t he endpoint definit ion is t o layer on t op of t he WSDL descript ion inform at ion about charact erist ics of t he Web service t hat are im pact ed by it s im plem ent at ion environm ent . Work in t his area is at it s very beginnings. The not ion of a Web Services Endpoint Language ( WSEL) has only been hint ed at publicly. Ot her exam ples of t his sort of descript ion include t he ebXML Collaborat ion- Prot ocol Profile and Agreem ent Specificat ion ( CPP) . At t he t op of t he service descript ion st ack is t he elusive prom ise of seam less, aut om at ic service int egrat ion: t he service orchest rat ion layer. Wit h service orchest rat ion , t he developer describes how a collect ion of Web services is com bined t o produce a m ore sophist icat ed Web service. For exam ple, you w ould use service orchest rat ion t o m odel how a purchase order subm ission Web service could be com bined wit h a not ificat ion service and a ret urns- processing service t o produce a richer overall purchasing Web service. At t his level, several alt ernat ive approaches exist . I BM has proposed t he Web Services Flow Language, and Microsoft has Xlang. A single st andard has not em erged in t his space.

  The orchest rat ion of Web services poses significant challenges from bot h a t echnical and a business perspect ive. On t he t echnical side, seam less service int egrat ion requires a significant t echnological foundat ion. Most im port ant is t he descript ion of service behavior, defined by t he rules for sequencing operat ion invocat ions and for sending and receiving m essages. Next is t he problem of com posing services int o process- based int eract ions. The problem is m ade harder by t he requirem ent t hat som e com posit ion bindings m ust happen at runt im e. Wit hout t his capabilit y, it is difficult t o m ap t he t echnology t o w ell- est ablished business processes such as represent at ion, referral, and brokering. On t he business side, t he problem s are no less significant . From a business perspect ive, service int egrat ion is a w orkflow problem and as such could int roduce dependencies on aspect s of com panies' core business m odels. Part icularly difficult in t his perspect ive is pot ent ially t he m ost valuable t ype of service int egrat ion—t he one t hat spans ent erprise boundaries.

The Discovery Stack

  Given t he abilit y t o describe Web services, w e are bet t er off t han w e w ere, but w e st ill have solved only part of t he Web service int egrat ion problem . Service descript ions t ell us how t o bind t o Web services, but how did t he service request or get t he service descript ion in t he first place? Clearly, w e need som e form of a Web service discovery m echanism . The requirem ent here is for a direct ory or search engine for Web services. Service providers w ill need a publicat ion m echanism so t hat t hey can provide inform at ion

  Service request ors w ill need w ell- defined find API s. This is t he SOA service regist ry role w e described earlier.

Figure 1.4 show s t he t hird int eroperabilit y st ack, t he discovery st ack. The discovery st ack organizes t echnologies associat ed wit h Web service discovery.Figure 1.4. The discovery stack.

  The first level of t he st ack represent s a sim ple inspect ion level. I nspect ion is a t echnique of discovering t he service descript ion given t hat t he det ails about t he service ( a service ident ifier or URL, for exam ple) are already known. Once again, no single st andard exist s in t his space. I BM has ADS and Microsoft has DI SCO .

  The direct ory level represent s t he capabilit y of discovering Web services and business part ners using a capabilit ies- based lookup. Unlike previous dist ribut ed com put ing t echniques t hat relied on w ell know n nam es as t he basis for rem ot e discovery of services, Web services can use find t echniques based on t he kind of service or service capabilit ies. The UDDI st andard is t he proposed t echnology for Web services direct ory.

  Chapt er 7 is dedicat ed t o explaining service discovery in m uch m ore det ail, and in part icular review ing t he UDDI st andard.

Putting the Interoperability Stacks Together

  Does any given Web service require all of t hese t echnologies in order t o be considered a Web service? Cert ainly not . Looking at t he w ire st ack, no single net w ork prot ocol—not even HTTP—is a required part of a Web service; any num ber of net w orking prot ocols can be used. Som e Web services don't even need t o use a net w ork prot ocol. Techniques such as t he Web Services I nvocat ion Fram ew ork ( WSI F) ( ht t p: / / w w w .alphaw orks.ibm .com / t ech/ w sif ) discuss t he possibilit y of a Web service being a sim ple Java m et hod invocat ion, w here t he service request or and service provider are in t he sam e Java Virt ual Machine. Moving up t he st ack, we can discover t hat even SOAP is not a necessary t echnology for Web services. I t is possible t hat a com ponent accessed t hrough a sim ple HTTP POST can be considered a Web service. I n t hese cases, t he com m onalit y t hat m akes t hese com ponent s Web services is t he use of WSDL t o describe t he service. So, is a service descript ion required in order for a com ponent t o be considered a Web service? Again, not necessarily. Many Web services, part icularly older Web services developed w hen SOAP w as first int roduced, do not have a corresponding service descript ion. These com ponent s are considered Web services, but it is w ort h not ing t hat w it hout a service descript ion, t he Web service cannot be a part of t he publish, find, bind operat ions in a service- orient ed archit ect ure. As t he WSDL st andard is adopt ed, you w ill

  Many developers have concluded t hat a Web service is sim ply " anyt hing t hat can be described using WSDL." Does a Web service have t o appear in a UDDI regist ry in order t o be considered a Web service? Clearly not . Many Web services advert ised on t he Web do not appear in UDDI and do not support t he ADS or DI SCO sim ple service discovery convent ions. So you w ill agree t hat any given Web service doesn't need all of t hese t echnologies t o be considered a Web service. But are any of t hese t echnologies found in each and every Web service? I f you follow t he argum ent s above, clearly not . I s SOAP required in all Web services? No. I s WSDL? No. UDDI ? No. There is no single Web services t echnology w hose use det erm ines t hat a com ponent is a Web service. For t his reason, defining w hat is a Web service rem ains difficult . I n addit ion t o w rit ing great specificat ions, t he Web services indust ry has been busy building soft w are t hat m akes t he st andards com e t o life and solve m eaningful business problem s. This book uses Apache Axis at t he heart of our Web services exam ples. Axis is an advanced Web services engine w it h a highly scalable and ext ensible archit ect ure. We w ill exam ine Axis in great dept h in Chapt er 4 . There are, how ever, ot her great Web services im plem ent at ions from m ult iple vendors.

  Chapt er 8 looks at t he current ly available best - of- breed Web services t ooling, it s capabilit ies and it s int eroperabilit y record.

  I nt eroperabilit y is key for Web services. I n t he World Wide Web, does m y brow ser care about w hich Web server you are running? No. The sam e t hing is t rue in Web services. Any service request or should be able t o consum e any st andard ( no cust om ext ensions) Web service provided via any Web services engine. We m ight be som e dist ance from t his holy grail, but t he indust ry is w orking hard at it because everyone know s t his is t he only w ay t o m ake Web services ( and dynam ic applicat ion int egrat ion) successful.

Summary

  I n t his chapt er, w e provided you w it h a definit ion for Web services and helped posit ion w here t hese t echnologies w ill benefit businesses. We also provided a concept ual fram ew ork—service- orient ed archit ect ure—you can use t o t hink about problem s relat ed t o Web services. We int roduced t he alphabet soup of Web services t echnologies and illust rat ed an organizat ional fram ew ork around t hree relat ed int eroperabilit y st acks. The rest of t his book builds upon w hat w e int roduced here. Chapt er 2 explores t he root of all Web services t echnologies: XML. Chapt er 3 builds upon t hat discussion by exam ining t he wire st ack and, in part icular, t he SOAP t echnology as t he access m echanism of choice for m any Web services. Chapt er 4 show s how SOAP is im plem ent ed in t he Apache Axis proj ect . Chapt er 5 expands upon SOAP and Axis, describing how ot her e- business aspect s such as securit y can be layered int o a Web service. Chapt er 6 explores t he service descript ion st ack, focusing on how t he service request or knows what kind of m essage t o send and w here t o send it . Chapt er 7 exam ines t he discovery st ack and in part icular t he UDDI st andard. Chapt er 8 explores ot her Web services infrast ruct ures. We close wit h Chapt er 9 , " Fut ure Concept s," w hich discusses som e fut ure t rends for Web services.

  Document- Versus Data-Centric XML •

  XML Instances •

  XML Namespaces • Document Type Definitions

  • XML Schemas • Processing XML •

  Since it s int roduct ion in 1998, Ext ensible Markup Language ( XML) has revolut ionized t he w ay in w hich w e t hink about st ruct uring, describing, and exchanging inform at ion. The ways in which XML is used in t he soft ware indust ry are m any and growing. Cert ainly for Web services t he im port ance of XML is param ount ; all key Web service t echnologies are based on it .

  One great t hing about XML is t hat it is const ant ly changing and evolving. How ever, t his can also be it s dow nside. New problem s require new approaches and uses of XML t hat drive aggressive t echnological innovat ion. The net result is a m aelst rom of invent ion—a pace of change so rapid t hat it leaves m ost people confused. To say t hat you are using

  XML is m eaningless. Are you using DTDs or XML Schem a and, if so, t hen whose? How about XML Nam espaces, XPoint er, XLink, XPat h, XSLT, XQuery, RDF, SOAP, WSDL, UDDI , XAML, WSFL, WSCL, or WS- I ? Does your soft w are use SAX, DOM, JAXB, JAXP, JAXM, JAXR, or JAX- RPC? I t is easy t o get lost , t o drow n in t he acronym soup. You are int erest ed in Web services ( you bought t his book, rem em ber?) . How m uch do you really need t o know about XML? The t rut h is pleasant ly surprising. First , m any XML t echnologies you m ight have heard about are not relevant t o Web services. You can safely forget half t he acronym s you w ish you knew m ore about . Second, even w it h relevant t echnologies, you need t o know only a few core concept s. ( The 80/ 20 rule does not disappoint .) Third, t his chapt er is all you need t o read and underst and t o be able t o handle t he rest of t he book and m ake t he m ost of it . This chapt er w ill cover, in sufficient det ail:

  The origins of XML and the fundamental difference between document-

  • and data-centric XML applications The syntax and rules governing XML documents •

  XML Namespaces, the key specification enabling the distributed • evolution of XML technologies

  XML Schema, the de facto standard for describing document structure

  • and XML datatypes for data-oriented applications The key mechanisms for creating and processing XML with Java software •

  This chapt er w ill develop a set of exam ples around Skat esTow n's purchase order subm ission and invoice generat ion process. The exam ples w ill cover all t he t echnologies w e've list ed here. I f you are an old hand at XML w ho underst ands t he XML nam espace m echanism and

  xsi:type

  feels at hom e w it h schem a ext ensibilit y and t he use of , you should go st raight t o Chapt er 3 , " Sim ple Obj ect Access Prot ocol ( SOAP) " and dive int o Web services. I f you t his chapt er t o get a quick refresher of som e core XML t echnologies. I f you are som eone w it h m ore lim it ed XML experience, do not w orry—by t he end of t his chapt er, you w ill be able t o hold your ow n.

  Origins of XML

  World Wide Web Consort ium ( W3C) began w ork on Ext ensible Markup Language ( XML) in t he m iddle of 1996. XML 1.0, released on February 10, 1998, result ed from t he com put er indust ry's need t o develop a sim ple yet ext ensible m echanism for t he t ext ual represent at ion of st ruct ured and sem i- st ruct ured inform at ion. The design inspirat ion for

  XML cam e from t w o m ain sources: St andard Generalized Markup Language ( SGML) and HTML. The concept of generalized m arkup ( GM) has been around for decades. I t involves using t ags t o ident ify pieces of inform at ion. Sim ply put , t ags are nam es surrounded by

  < > <title>

  point y bracket s ( and ) . For exam ple, is a t ag. The innovat ive t hing about GM is t hat it requires inform at ion t o be surrounded by bot h st art and end t ags. End t ags look

  /

  like st art t ags w it h t he addit ion of a forw ard slash ( ) before t he t ag nam e, as in

  </title>

  . The not ion of st art and end t ags allow s for nest ing, w hich, in t urn, let s you st ruct ure inform at ion in a hierarchical m anner. Consider t he follow ing exam ple, w hich uses m arkup t o indicat e t hat a book has a t it le and several aut hors:

  <book> <t i t l e>Bui l di ng Web Servi ces wi t h J ava</t i t l e> <aut hors> <aut hor>St eve Graham</aut hor> <aut hor>Si meon Si meonov</aut hor> <aut hor>Touf i c Boubez</aut hor> <aut hor>Doug Davi s</aut hor> <aut hor>Gl en Dani el s</aut hor> <aut hor>Yui chi Nakamura</aut hor> <aut hor>Ryo Neyama</aut hor> </aut hors> </book>

  Using m arkup t o represent inform at ion about books has m any benefit s. The inform at ion is readily readable by hum ans. I t is also quit e easy t o process wit h soft ware because st art and end t ags clearly delineat e w here cert ain pieces of inform at ion st art and w here t hey end. Furt her, t his w ay t o represent inform at ion is inherent ly ext ensible. For exam ple, you can easily im agine how t o add m ore aut hors or ot her inform at ion ( such as t he book's I SBN) t o t he book descript ion. Markup is appealing because of it s sim plicit y com bined w it h t he pot ent ial for ext ensibilit y. Not all m arkup is sim ple, t hough. I n fact , our indust ry's first at t em pt t o form ally define generalized m arkup yielded a very com plex specificat ion. SGML w as rat ified by I SO in 1986. I t defined everyt hing you could ever w ant t o know about m arkup and m ore. SGML- enabled soft w are w as expensive; t ypically, only large com panies could afford it . The soft ware also t ended t o be full of defect s. Over t im e, a grow ing com m unit y of SGML expert s began t o voice opinions t hat , perhaps, t he core ideas of SGML could be organized in a m uch sim pler fashion. All t hat was needed w as a cat alyst t o force t he change and an organizat ion t hat could lead t he st andardizat ion effort . The cat alyst w as t he com binat ion of HTML and t he Web. The organizat ion w as t he W3C.

  By it s nat ure, SGML is a m et a- language . I t does not prescribe any part icular m arkup; inst ead, it defines how any given m arkup language can be form ally specified.

  Because t he t erm is confusing ( a m arkup language specificat ion is not a piece of soft w are) , it is rarely used now adays, but you st ill m ight encount er it in som e of t he reference m at erials point ed out at t he end of t he chapt er. The m ost popular SGML applicat ion is HTML, t he m arkup language t hat rules t he Web. HTML com bines m arkup from several different cat egories t o provide a rich hypert ext experience:

  <H1> <H2> <P> <BR> Text structuring tags: • , , ,

  • Formatting tags: <B> , <I>

  <IMG> <A> Linking and embedding tags: •

  , Data input tags:

  • <FORM> , <INPUT> , <SELECT>

  The HTML specificat ion is ow ned by W3C. Unfort unat ely, due t o t he rapid grow t h of t he I nt ernet and t he m arket pressure caused by t he brow ser w ars, t he leading brow ser vendors int roduced a num ber of incom pat ible t ags t o HTML com plet ely out side t he scope of t he HTML specificat ion. These t ags creat ed problem s for I nt ernet soft w are vendors and HTML docum ent aut hors—t hey had t o be careful w hat m arkup t hey used, based on t he t ype of brow ser t hat w ould display t he HTML docum ent . Yet at t he sam e t im e, t hey t hem selves w ere not able t o ext end HTML w it h m arkup t hat could have been useful t o t hem .

  The need t o sim plify SGML coincided w it h t he need t o cont rol t he evolut ion of HTML and creat e a sim ple generalized m arkup language for use on t he Web. SGML w as t oo heavy for t his purpose—it sim ply t ook t oo m uch effort t o support and process. XML becam e t hat light w eight language. Aft er about one- and- a- half- years of w ork, t he XML w orking group at t he W3C produced a final specificat ion. XML is sim ilar t o SGML in t hat it preserves t he not ion of GM. How ever, t he specificat ion is m uch sim pler. There are very few opt ional feat ures, and m ost SGML feat ures t hat were deem ed difficult t o im plem ent were abandoned.

  XML is here t o st ay. The XML indust ry is experiencing a boom . XML has becom e t he de fact o st andard for represent ing st ruct ured and sem i- st ruct ured inform at ion in t ext ual form . Many specificat ions are built on t op of XML t o ext end it s capabilit ies and enable it s use in a broader range of scenarios. One of t he m ost excit ing areas of use for XML is Web services. The rest of t his chapt er w ill int roduce t he set of XML t echnologies and st andards t hat are t he foundat ion of Web services:

  • XML instances— The rules for creating syntactically correct XML docum ents
  • XML Schem a— A recent standard that enables detailed validation of XML docum ent s as w ell as t he specificat ion of XML dat at ypes
  • XML Nam espaces— Definitions of the m echanism s for com bining XML from m ult iple sources in a single docum ent
  • XML processing— The core architecture and m echanism s for creating, parsing, and m anipulat ing XML docum ent s from program m ing languages

Document- Versus Data-Centric XML

  Generally speaking, t here are t w o broad applicat ion areas of XML t echnologies. The first relat es t o docum ent - cent ric applicat ions, and t he second t o dat a- cent ric applicat ions. Because XML can be used in so m any different w ays, it is im port ant t o underst and t he difference bet w een t hese t w o cat egories.

Document-Centric XML

  Because of it s SGML origins, in t he early days of it s exist ence XML gained rapid adopt ion w it hin publishing syst em s as a m echanism for represent ing sem i- st ruct ured docum ent s such as t echnical m anuals, legal docum ent s, and product cat alogs. The cont ent in t hese docum ent s is t ypically m eant for hum an consum pt ion, alt hough it could be processed by any num ber of applicat ions before it is present ed t o hum ans. The key elem ent of t hese docum ent s is sem i- st ruct ured m arked- up t ext .

  The follow ing m arkup is a perfect exam ple of XML used in a docum ent - cent ric m anner. The cont ent is direct ed t ow ards hum an consum pt ion—it 's part of t he Fast Glide skat eboard user guide. The cont ent is sem i- st ruct ured. The usage rules for t ags such as

  <B> <I> <LINK>

  , and are very loosely defined; t hey could appear pret t y m uch anyw here in t he docum ent :

  <H1>Skat eboard Usage Requi rement s</H1> <P>I n order t o use t he <B>Fast Gl i de</B> skat eboard you have t o have: </P> <LI ST> <I TEM>A st rong pai r of l egs. </I TEM> <I TEM>A reasonabl y l ong st ret ch of smoot h road surf ace. </I TEM> <I TEM>The i mpul se t o i mpress ot hers. </I TEM> </LI ST> <P>I f you have al l of t he above, you can proceed t o <LI NK HREF="Chapt er2. xml">Get t i ng on t he Board</LI NK>. </P>

Data-Centric XML

  By cont rast , dat a- cent ric XML is used t o m ark up highly st ruct ured inform at ion such as t he t ext ual represent at ion of relat ional dat a from dat abases, financial t ransact ion inform at ion, and program m ing language dat a st ruct ures. Dat a- cent ric XML is t ypically generat ed by m achines and is m eant for m achine consum pt ion. I t is XML's nat ural abilit y t o nest and repeat m arkup t hat m akes it t he perfect choice for represent ing t hese t ypes of dat a.

  Consider t he purchase order exam ple in List ing 2.1 . I t is a purchase order from t he Skat eboard Warehouse, ret ailer of skat eboards t o Skat esTow n. The order is for 5 backpacks, 12 skat eboards, and 1,000 Skat esTow n prom ot ional st ickers ( t his is w hat t he st ock keeping unit [ SKU] of 008- PR st ands for) .

  Listing 2.1 Purchase Order in XML

  <po i d="43871" submit t ed="2001- 10- 05"> <bi l l To> <company>The Skat eboard Warehouse</company> <st reet >One Warehouse Park</st reet > <st reet >Bui l di ng 17</st reet > <ci t y>Bost on</ci t y> <st at e>MA</st at e> <post al Code>01775</post al Code> </bi l l To> <shi pTo> <company>The Skat eboard Warehouse</company> <st reet >One Warehouse Park</st reet > <st reet >Bui l di ng 17</st reet >

  <st at e>MA</st at e> <post al Code>01775</post al Code> </shi pTo> <order> <i t em sku="318- BP" quant i t y="5"> <descri pt i on>Skat eboard backpack; f i ve pocket s</descri pt i on> </i t em> <i t em sku="947- TI " quant i t y="12"> <descri pt i on>St reet - st yl e t i t ani um skat eboard. </descri pt i on> </i t em> <i t em sku="008- PR" quant i t y="1000"> </i t em> </order> </po>

  The use of XML is very different from t he previous user guide exam ple:

  The ratio of markup to content is high. The XML includes many • different types of tags. There is no long-running text. The XML includes machine-generated information; for example, the • submission date of the purchase order uses a date-time format of year-month-day. A human authoring an XML document is unlikely to enter a date-time value in this format. The tags are organized in a highly structured manner. Order and • positioning matter, relative to other tags. For example,

<description> <item> <order>

must be under , which must be under , which must be under <po> . The <order> tag can be used only once in the document. Markup is used to describe what a piece of information means rather • than how it should be presented to a human.

  I n short , if you can easily im agine t he XML as a dat a st ruct ure in your favorit e program m ing language, you are probably looking at a dat a- cent ric use of XML. An exam ple Java class t hat could, w it h a bit m ore w ork, be used t o represent t he purchase order dat a is show n here:

  cl ass PO { i nt i d; Dat e submit t ed; Address bi l l To; Address shi pTo; I t em order[ ] ; } Document Lifetime

  Docum ent - and dat a- cent ric uses of XML can differ in one ot her very significant aspect — t he lifet im e of t he XML docum ent . Typically, XML docum ent s for hum an consum pt ion inform at ion cont ained in t hem can be used for a long t im e. On t he ot her hand, som e dat a- cent ric XML could live for only a few m illiseconds. Consider t he exam ple of a dat abase t hat is ret urning t he result s of a query in XML form at . The w hole operat ion t akes several m illiseconds. Aft er t he query is used, t he dat a is discarded. Furt her, no real

  XML docum ent exist s. The XML is j ust bit s on a w ire or bit s in an applicat ion's dat a st ruct ure. St ill, for convenience purposes, w e w ill use t he t erm XML docum ent t o refer t o any part icular w hole piece of XML being used. As a general ident ificat ion of part s of a w hole XML docum ent , t his book uses t he highly t echnical t erm chunk.

  Web services are about dat a- cent ric uses of XML. Through t he rest of t his chapt er and t he rest of t his book, w e w ill purposefully ignore discussing docum ent - cent ric XML.

  XML Instances

  The st ruct ure and form at t ing of XML in an XML docum ent m ust follow t he rules of t he

  XML inst ance synt ax. The t erm inst ance is used t o explicit ly dist inguish t he difference bet w een t he use of som e part icular t ype of XML and it s specificat ion. This usage parallels t he difference in obj ect - orient ed t erm inology bet w een an obj ect inst ance and an obj ect t ype.

  Document Prolog

  XML docum ent s cont ain an opt ional prolog follow ed by a root elem ent t hat cont ains t he cont ent s of t he docum ent . Typically t he prolog serves up t o t hree roles:

  Identifies the document as an XML document

  • Includes any comments about the document • Includes any meta-information about the content of the document •

  A docum ent can be ident ified as an XML docum ent t hrough t he use of a processing inst ruct ion . Processing inst ruct ions ( PI s) are special direct ives t o t he applicat ion t hat w ill process t he XML docum ent . They have t he follow ing synt ax:

  <?PI Target . . . ?> <? ... ?>

  PI s are enclosed in . The PI t arget is a keyw ord m eaningful t o t he processing

  ?>

  applicat ion. Everyt hing bet w een t he PI t arget and t he m arker is considered t he cont ent s of t he PI . I n general, dat a- orient ed XML applicat ions do not use applicat ion- specific processing inst ruct ions. I nst ead, t hey t end t o put all inform at ion in elem ent s and at t ribut es. However, you should use one st andard processing inst ruct ion—t he XML declarat ion

  —in t he XML docum ent prolog t o det erm ine t w o very im port ant pieces of inform at ion: t he version of XML in t he docum ent and t he charact er encoding:

  <?xml versi on="1. 0" encodi ng="UTF- 8"?> version xml

  The param et er of t he PI t ells t he processing applicat ion t he version of t he

  XML specificat ion t o w hich t he docum ent conform s. Current ly, t here is only one version:

  "1.0" encoding

  . The param et er is opt ional. I t ident ifies t he charact er set of t he

  "UTF-8" docum ent . The default value is . UTF- 8 is a variable- lengt h charact er encoding st andard t hat generat es 7- bit safe out put . This t ype of out put m akes it easy t o m ove XML on t he I nt ernet using st andard com m unicat ion prot ocols such as HTTP, SMTP, and FTP. Keep in m ind t hat XML is int ernat ionalized by design and can support ot her charact er encodings such as Unicode and I SO/ I EC 10646. How ever, for sim plicit y and readabilit y purposes, t his book w ill use UTF- 8 encoding for all sam ples.

  I f you om it t he XML declarat ion, t he XML version is assum ed t o be 1.0, and t he processing applicat ion w ill t ry t o guess t he encoding of t he docum ent based on clues such as t he raw byt e order of t he dat a st ream . This approach has problem s, and w henever int eroperabilit y is of high im port ance—such as for Web services—applicat ions should alw ays provide an explicit XML declarat ion and use UTF- 8 encoding.

  XML docum ent prologs can also include com m ent s t hat pert ain t o t he whole docum ent . Com m ent s use t he follow ing synt ax:

  <! - - Sampl e comment and more . . . - - >

  Com m ent s can span m ult iple lines but cannot be nest ed ( com m ent s cannot enclose ot her com m ent s) . Everyt hing inside t he com m ent m arkers w ill be ignored by t he processing applicat ion. Som e of t he XML sam ples in t his book w ill use com m ent s t o provide you w it h useful cont ext about t he exam ples in quest ion.

  Wit h w hat you have learned so far, you can ext end t he purchase order exam ple from

  

List ing 2.1 t o include an XML declarat ion and a com m ent about t he docum ent ( see List ing

2.2 ) .

  Listing 2.2 XML Declaration and Comment for the Purchase Order

  <?xml versi on="1. 0" encodi ng="UTF- 8"?> <! - - Creat ed by Bob Di st er, approved by Mary J ones - - > <po i d="43871" submit t ed="2001- 10- 05"> <! - - The rest of t he purchase order wi l l be t he same as bef ore - - > . . . </po> po I n t his case, is t he root elem ent of t he XML docum ent .

  Elements

  The t erm elem ent is a t echnical nam e for t he pairing of a st art and end t ag in an

  po <po>

  XML docum ent . I n t he previous exam ple, t he elem ent has t he st art t ag and t he

  </po>

  end t ag . Every st art t ag m ust have a m at ching end t ag and vice versa. Everyt hing bet w een t hese t w o t ags is t he cont ent of t he elem ent . This includes any nest ed elem ent s, t ext , com m ent s, and so on.

  [0-

  Elem ent nam es can include all st andard program m ing language ident ifier charact ers (

  9A-Za-z] _ :

  • customer-name

  ) as w ell as underscore ( ) , hyphen ( ) , and colon ( ) , but t hey m ust st art w it h

  a let t er. is a valid XML elem ent nam e. How ever, because XML is case-

  customer-name Customer-Name sensit ive, is not t he sam e elem ent as .

  According t o t he XML Specificat ion, elem ent s can have t hree different cont ent t ypes. They can have elem ent - only cont ent , m ixed cont ent , or em pt y cont ent . Elem ent - only cont ent consist s ent irely of nest ed elem ent s. Any w hit espace separat ing elem ent s is not considered significant in t his case. Mixed cont ent refers t o any com binat ion of nest ed elem ent s and t ext . All elem ent s in t he purchase order exam ple, w it h t he except ion of

  description

  , have elem ent cont ent . Most elem ent s in t he skat eboard user guide Not e t hat t he XML Specificat ion does not define a t ext - only cont ent m odel. Out side t he let t er of t he specificat ion, an elem ent t hat cont ains only t ext is oft en referred t o as having dat a cont ent ; but , t echnically speaking, it has m ixed cont ent . This aw kw ardness com es as a result of XML's root s in SGML and docum ent - orient ed applicat ions. However, in m ost dat a- orient ed applicat ions, you w ill never see elem ent s w hose cont ent s are bot h nest ed elem ent s and t ext . I t w ill t ypically be one or t he ot her, because lim it ing t he cont ent t o be eit her elem ent s or t ext m akes processing XML m uch easier. The synt ax for elem ent s w it h em pt y cont ent is a st art t ag im m ediat ely follow ed by an

  <emptyElement></emptyElement>

  end t ag, as in . Because t his is sim ply t oo m uch t ext ,

  <emptyElement/>

  t he XML Specificat ion also allow s t he short hand form . For exam ple,

  description

  because t he last it em in our purchase order does not have a nest ed elem ent , it has em pt y cont ent . Therefore, w e could have w rit t en it as follow s:

  <i t em sku="008- PR" quant i t y="1000"/>

  XML elem ent s m ust be st rict ly nest ed. They cannot overlap, as show n here:

  <! - - Thi s i s correct nest i ng - - > <P><B><I >Bol d, i t al i ci zed t ext i n a paragraph</I ></B></P> <! - - Bad synt ax: overl appi ng I and B t ags - - > <P><I ><B>Bol d, i t al i ci zed t ext i n a paragraph</I ></B></P> <! - - Bad synt ax: overl appi ng P and B t ags - - > <B><P><I >Bol d, i t al i ci zed t ext i n a paragraph</I ></B></P>

  The not ion of an XML docum ent root im plies t hat t here can be only one elem ent at t he very t op level of a docum ent . For exam ple, t he follow ing w ould not be a valid XML docum ent :

  <f i rst >I am t he f i rst el ement </f i rst > <second>I am t he second el ement </second>

  I t is easy t o t hink of nest ed XML elem ent s as a hierarchy. For exam ple, Figure 2.1 shows a hierarchical t ree represent at ion of t he XML elem ent s in t he purchase order exam ple t oget her w it h t he dat a ( t ext ) associat ed w it h t hem .

Figure 2.1. Tree representation of XML elements in a purchase order. Unfort unat ely, it is oft en difficult t o ident ify XML elem ent s precisely in t he hierarchy. To aid t his t ask, t he XML com m unit y has t aken t o using genealogy t erm s such as parent , child, sibling, ancest or, and descendant . Figure 2.2 illust rat es t he t erm inology as it applies t o t he

  order

  elem ent of t he purchase order: • Its parent is po .

  • Its ancestor is

  po .

  • Its siblings are billTo and ship
  • Its children are three item elements.
  • Its descendants are three

  item elements and two description elements.

Figure 2.2. Common terminology for XML element relationships. Attributes

  The st art t ags for XML elem ent s can have zero or m ore at t ribut es. An at t ribut e is a nam e- value pair. The synt ax for an at t ribut e is a nam e ( w hich uses t he sam e charact er set as an XML elem ent nam e) follow ed by an equal sign ( = ) , follow ed by a quot ed value. The XML Specificat ion requires t he quot ing of values; bot h single and double quot es can

  po

  be used, provided t hey are correct ly m at ched. For exam ple, t he elem ent of our

  

id submitted

  purchase order has t w o at t ribut es, and :

  <po i d="43871" submit t ed="2001- 10- 05"> . . . </po> xml

  A fam ily of at t ribut es w hose nam es begin w it h : is reserved for use by t he XML

  xml:lang

  Specificat ion. Probably t he best exam ple is , w hich is used t o ident ify t he language of t he t ext t hat is t he cont ent of t he elem ent w it h t hat at t ribut e. For exam ple,

  description

  w e could have w rit t en t he elem ent s in our purchase order exam ple t o ident ify t he descript ion t ext as English:

  <descri pt i on xml: l ang="en">Skat eboard backpack; f i ve pocket s</descri pt i on>

  Not e t hat applicat ions processing XML are not required t o recognize, process, and act based on t he values of t hese at t ribut es. The key reason w hy t he XML Specificat ion ident ified t hese at t ribut es is t hat t hey address com m on use- cases; st andardizing t hem w ould aid int eroperabilit y bet w een applicat ions.

  Wit hout any m et a- inform at ion about an XML docum ent , at t ribut e values are considered t o be pieces of t ext . I n t he previous exam ple, t he id m ight look like a num ber and t he subm ission dat e m ight look like a dat e, but t o an XML processor t hey w ill bot h be j ust st rings. This obviously causes som e headaches when processing dat a- orient ed XML, and it is one of t he prim ary reasons m ost dat a- orient ed XML docum ent s have associat ed m et a- inform at ion described in XML Schem a ( int roduced lat er in t his chapt er) .

  At t he sam e t im e, XML applicat ions are free t o at t ach any sem ant ics t hey choose t o XML m arkup. A com m on use- case is leveraging at t ribut es t o creat e a basic linking m echanism w it hin an XML docum ent . The t ypical scenario involves a docum ent having duplicat e inform at ion in m ult iple locat ions. The goal is t o elim inat e inform at ion duplicat ion. The process has t hree st eps: 1. Put the information in the document only once.

  3. Refer to this identifier every time you need to refer to the information.

  The purchase order exam ple offers t he opport unit y t o t ry t his out ( see List ing 2.3 ) . As show n in t he exam ple, in m ost cases, t he bill- t o and ship- t o addresses w ill be t he sam e. Listing 2.3 Duplicate Address Information in a Purchase Order

  <po i d="43871" submit t ed="2001- 10- 05"> <bi l l To> <company>The Skat eboard Warehouse</company> <st reet >One Warehouse Park</st reet > <st reet >Bui l di ng 17</st reet > <ci t y>Bost on</ci t y> <st at e>MA</st at e> <post al Code>01775</post al Code> </bi l l To> <shi pTo> <company>The Skat eboard Warehouse</company> <st reet >One Warehouse Park</st reet > <st reet >Bui l di ng 17</st reet > <ci t y>Bost on</ci t y> <st at e>MA</st at e> <post al Code>01775</post al Code> </shi pTo> . . . </po>

  There is no reason t o duplicat e t his inform at ion. I nst ead, w e can use t he m arkup show n in List ing 2.4 . Listing 2.4 Using ID/IDREF Attributes to Eliminate Redundancy

  <po i d="43871" submit t ed="2001- 10- 05"> <bi l l To i d="addr- 1"> <company>The Skat eboard Warehouse</company> <st reet >One Warehouse Park</st reet > <st reet >Bui l di ng 17</st reet > <ci t y>Bost on</ci t y> <st at e>MA</st at e> <post al Code>01775</post al Code> </bi l l To> <shi pTo href ="addr- 1"/> . . . </po>

  We follow ed t he t hree st eps described previously:

  1. We put the address information in the document only once, under the billTo element.

  2. We uniquely identified the address as "addr-1" and stored that

id billTo

information in the attribute of the element. We only need

  

to worry about the uniqueness of the identifier within the XML

document. shipTo

  3. To refer to the address from the element we use another attribute, href , whose value is the unique address identifier "addr- 1" . id href

  The at t ribut e nam es and are not required but nevert heless are com m only used by convent ion.

  po billTo

  You m ight have not iced t hat now bot h t he and elem ent s have an at t ribut e

  id called . This is fine, because at t ribut es are alw ays associat ed w it h an elem ent .

  Elements Versus Attributes

  Given t hat inform at ion can be st ored in bot h elem ent cont ent and at t ribut e values, sooner or lat er t he quest ion of w het her t o use an elem ent or an at t ribut e arises. This debat e has erupt ed a few t im es in t he XML com m unit y and has claim ed m any casualt ies.

  One com m on rule is t o represent st ruct ured inform at ion using m arkup. For

  address company street

  exam ple, you should use an elem ent w it h nest ed , ,

  city state postalCode country

  , , , and elem ent s inst ead of including a w hole address as a chunk of t ext . Even t his sim ple rule is subj ect t o int erpret at ion and t he choice of applicat ion dom ain. For exam ple, t he choice bet w een

  <work number="617. 219. 2000">

  and

  <work> <area>617</area> <number>219. 2000</number> <ext /> </work>

  really depends on w het her your applicat ion needs t o have phone num ber inform at ion in granular form ( for exam ple, t o perform searches based on t he area code only) . I n ot her cases, only personal preference and st ylist ic choice apply. We m ight ask if Skat esTow n should have used

  <po> <i d>43871</i d> <submit t ed>2001- 10- 05</submit t ed> . . . </po>

  inst ead of

  <po i d="43871" submit t ed="2001- 10- 05"> . . . </pol >

  There really isn't a good w ay t o answ er t his quest ion w it hout adding all sort s of

  I n general, w henever hum ans design XML docum ent s, you w ill see m ore frequent use of at t ribut es. This is t rue even in dat a- orient ed applicat ions. On t he ot her hand, w hen XML docum ent s are aut om at ically " designed" and generat ed by applicat ions, you m ight see a m ore prevalent use of elem ent s. The reasons are som ew hat com plex; Chapt er 3 w ill address som e of t hem .

Character Data

  At t ribut e values as w ell as t he t ext and w hit espace bet w een t ags m ust follow precisely a sm all but st rict set of rules. Most XML developers t end t o t hink of t hese as m apping t o t he st ring dat a t ype in t heir program m ing language of choice. Unfort unat ely, t hings are not t hat sim ple.

  Encoding First , and m ost im port ant , all charact er dat a in an XML docum ent m ust com ply w it h t he docum ent 's encoding. Any charact ers out side t he range of charact ers t hat can be included in t he docum ent m ust be escaped and ident ified as charact er references . The escape sequence used t hroughout XML uses t he am persand ( &) as it s st art and t he sem i- colon ( ; ) as it s end. The synt ax for charact er references is an am persand, follow ed by a pound/ hash sign ( # ) , follow ed by eit her a decim al charact er code or low ercase x follow ed by a hexadecim al charact er code, follow ed by t he sem icolon. Therefore, t he 8-

  € bit charact er code 128 w ill be encoded in a UTF- 8 XML docum ent as .

  Unfort unat ely, for obscure docum ent - orient ed reasons, t here is no w ay t o include charact er codes 0 t hrough 7, 9, 11, 12, or 14 t hrough 31 ( t ypically know n as non- whit espace cont rol charact ers in ASCI I ) in XML docum ent s. Even a correct ly escaped charact er reference w ill not do. This sit uat ion can cause unexpect ed problem s for program m ers w hose st ring dat a t ypes can som et im es end up w it h t hese values. Whitespace Anot her legacy from t he docum ent - cent ric w orld t hat XML cam e from is t he rules for w hit espace handling. I t is not im port ant t o com plet ely define t hese rules here, but a couple of t hem are w ort h m ent ioning:

  

An XML processor is required to convert any carriage return (CR)

  • character, as well as the sequence of a carriage return and a line feed (LF) character, it sees in the XML document into a single line feed character. Whitespace can be treated as either significant or insignificant. The • set of rules for how applications are notified about either of these has erupted more than one debate in the XML community.

  Luckily, m ost dat a- orient ed XML applicat ions care lit t le about w hit espace. Entities I n addit ion t o charact er references, XML docum ent s can define ent it ies as well as references t o t hem ( ent it y references ) . Ent it ies are t ypically not im port ant for dat a- orient ed applicat ions and w e w ill not discuss t hem in det ail here. How ever, all XML processors m ust recognize several pre- defined ent it ies t hat m ap t o charact ers t hat can

  > & '

  ( ) ; am persand ( ) ; apost rophe, a.k.a. single quot e ( ) ; and quot e, a.k.a. double quot e

  " ( ) . Table 2.1 shows t he synt ax for escaping t hese charact ers.

Table 2.1. Pre-defined XML Character Escape Sequences

Character Escape sequence

  < < > > & & ' ' " "

  For exam ple, t o include a chunk of XML as t ext , not m arkup, inside an XML docum ent , all special charact ers should be escaped:

  <exampl e- t o- show> &l t ; ?xml versi on=&quot ; 1. 0&quot ; ?&gt ; &l t ; root El ement &gt ; &l t ; chi l dEl ement i d=&quot ; 1&quot ; &gt ; The man sai d: &quot ; Hel l o, t here! &quot ; . &l t ; /chi l dEl ement &gt ; &l t ; /root El ement &gt ; </exampl e- t o- show>

  The result is not only reduced readabilit y but also a significant increase in t he size of t he docum ent , because single charact ers are m apped t o charact er escape sequences w hose lengt h is at least four charact ers. To address t his problem , t he XML Specificat ion has a special m ult i- charact er escape const ruct . The nam e of t he const ruct , CDATA sect ion , refers t o t he sect ion holding

  <![CDATA[

  charact er dat a. The synt ax is , followed by any sequences of charact ers

  ]]> ]]>

  allow ed by t he docum ent encoding t hat does not include , follow ed by . Therefore, you can w rit e t he previous exam ple m uch m ore sim ply as follow s:

  <exampl e- t o- show><! [ CDATA[ <?xml versi on="1. 0"?> <root El ement > <chi l dEl ement i d="1"> The man sai d: "Hel l o, t here! ". </chi l dEl ement > </root El ement > ] ] ></exampl e- t o- show> A Simpler Purchase Order

  Based on t he inform at ion in t his sect ion, w e can re- w rit e t he purchase order docum ent as shown in List ing 2.4 . Listing 2.4 Improved Purchase Order Document

  <?xml versi on="1. 0" encodi ng="UTF- 8"?> <! - - Creat ed by Bob Di st er, approved by Mary J ones - - > <po i d="43871" submit t ed="2001- 10- 05"> <bi l l To i d="addr- 1"> <company>The Skat eboard Warehouse</company> <st reet >One Warehouse Park</st reet >

  <ci t y>Bost on</ci t y> <st at e>MA</st at e> <post al Code>01775</post al Code> </bi l l To> <shi pTo href ="addr- 1"/> <order> <i t em sku="318- BP" quant i t y="5"> <descri pt i on>Skat eboard backpack; f i ve pocket s</descri pt i on> </i t em> <i t em sku="947- TI " quant i t y="12"> <descri pt i on>St reet - st yl e t i t ani um skat eboard. </descri pt i on> </i t em> <i t em sku="008- PR" quant i t y="1000"/> </order> </po>

  XML Namespaces

  An im port ant propert y of XML docum ent s is t hat t hey can be com posed t o creat e new docum ent s. This is t he m ost basic m echanism for reusing XML. Unfort unat ely, sim ple com posit ion creat es t he problem s of recognit ion and collision. To illust rat e t hese problem s, consider a scenario w here Skat esTow n w ant s t o receive it s purchase orders via t he XML m essaging syst em of XCom m erce Messaging, I nc. The form at of t he m essages is sim ple:

  <message f rom=". . . " t o=". . . " sent =". . . "> <t ext > Thi s i s t he t ext of t he message. </t ext > <! - - A message can have at t achment s - - > <at t achment > <descri pt i on>Bri ef descri pt i on of t he at t achment . </descri pt i on> <i t em> <! - - XML of at t achment goes here - - > </i t em> </at t achment > </message> List ing 2.5 shows a com plet e m essage wit h a purchase order at t achm ent .

  Listing 2.5 Message with Purchase Order Attachment

  <message f rom="bj @bj skat es. com" t o="orders@skat est own. com" sent ="2001- 10- 05"> <t ext > Hi , here i s what I need t hi s t i me. Thx, BJ . </t ext > <at t achment > <descri pt i on>The PO</descri pt i on> <i t em> <po i d="43871" submit t ed="2001- 10- 05">

  <company>The Skat eboard Warehouse</company> <st reet >One Warehouse Park</st reet > <st reet >Bui l di ng 17</st reet > <ci t y>Bost on</ci t y> <st at e>MA</st at e> <post al Code>01775</post al Code> </bi l l To> <shi pTo href ="addr- 1"/> <order> <i t em sku="318- BP" quant i t y="5"> <descri pt i on> Skat eboard backpack; f i ve pocket s </descri pt i on> </i t em> <i t em sku="947- TI " quant i t y="12"> <descri pt i on> St reet - st yl e t i t ani um skat eboard. </descri pt i on> </i t em> <i t em sku="008- PR" quant i t y="1000"/> </order> </po> </i t em> </at t achment > </message>

  I t is relat ively easy t o ident ify t he t w o problem s m ent ioned earlier in t he com posed docum ent :

  • Recognition— How does an XML processing application distinguish between the

  XML elem ent s t hat describe t he m essage and t he XML elem ent s t hat are part of t he purchase order?

  • Collision— Does the elem ent description refer t o at t achm ent descript ions in

  item

  m essages or order it em descript ions? Does t he elem ent refer t o an it em of at t achm ent or an order it em ? Very sim ple applicat ions m ight not be bot hered by t hese problem s. Aft er all, t he know ledge of w hat an elem ent m eans can reside in t he applicat ion logic. How ever, as applicat ion com plexit y increases and t he num ber of applicat ions t hat need t o w ork w it h som e part icular com posed docum ent t ype grow s, t he need t o clearly dist inguish bet w een t he XML elem ent s becom es param ount . The XML Nam espaces specificat ion brings order t o t he chaos.

  Namespace Mechanism

  The problem of collision in com posed XML docum ent s arises because of t he likelihood of elem ent s w it h com m on nam es ( descript ion, it em , and so on) t o be reused in different docum ent t ypes. This problem can be addressed by qualifying an XML elem ent nam e w it h an addit ional ident ifier t hat is m uch m ore likely t o be unique w it hin t he com posed docum ent . I n ot her w ords:

  Qualified name (a.k.a. QName) = Namespace identifier + Local name This approach is sim ilar t o how nam espaces are used in languages such as C+ + and C# and t o how package nam es are used in t he Java program m ing language. The problem of recognit ion in com posed XML docum ent s arises because no good m echanism exist s t o ident ify all elem ent s belonging t o t he sam e docum ent t ype. Given nam espace qualifiers, t he problem is addressed in a sim ple w ay—all elem ent s t hat have t he sam e nam espace ident ifier are considered t oget her.

  For ident ifiers, XML Nam espaces uses Uniform Resource I dent ifiers ( URI s) . URI s are described in RFC 2396. URI s are not hing fancy, but t hey are very useful. They can be locat ors, nam es, or bot h. URI locat ors are known as Uniform Resource Locat ors ( URLs) , a t erm fam iliar t o all using t he Web. URLs are st rings such as

  http://www.skatestown.com/services/POSubmission

  and

  mailto:orders@skatestown.com .

  Uniform Resource Nam es ( URNs) are URI s t hat are globally unique and persist ent . Universally Unique I dent ifiers ( UUI Ds) are perfect for use as URNs. UUI Ds are 128- bit ident ifiers t hat are designed t o be globally unique. Typically, t hey com bine net w ork card ( Et hernet ) addresses w it h a high- precision t im est am p and an increm ent

  urn:uuid:2FAC1234-31F8-11B4-A222-

  count er. An exam ple URN using a UUI D is

  08002B34C003

  . UUI Ds are used as unique ident ifiers in Universal Descript ion Discovery and I nt egrat ion ( UDDI ) as det ailed in Chapt er 7 , " Discovering Web Services."

  Namespace Syntax

  Because URI s can be rat her long and t ypically cont ain charact ers t hat are not allow ed in

  XML elem ent nam es, t he synt ax of including nam espaces in XML docum ent s involves t w o st eps:

  1. A namespace identifier is associated with a prefix, a name that contains only legal XML element name characters with the exception of the colon (:).

  2. Qualified names are obtained as a combination of the prefix, the colon character, and the local element name, as in myPrefix:myElementName .

  List ing 2.6 shows an exam ple of t he com posed XML docum ent using nam espaces.

  Listing 2.6 Message with Namespaces

  <msg: message f rom="bj @bj skat es. com" t o="orders@skat est own. com" sent ="2001- 10- 05" xmlns: msg="ht t p: //www. xcommercemsg. com/ns/message" xmlns: po="ht t p: //www. skat est own. com/ns/po"> <msg: t ext > Hi , here i s what I need t hi s t i me. Thx, BJ . </msg: t ext > <msg: at t achment > <msg: descri pt i on>The PO</msg: descri pt i on> <msg: i t em> <po: po i d="43871" submit t ed="2001- 10- 05"> <po: bi l l To i d="addr- 1"> <po: company>The Skat eboard Warehouse</po: company>

  <po: st reet >One Warehouse Park</po: st reet > <po: st reet >Bui l di ng 17</po: st reet > <po: ci t y>Bost on</po: ci t y> <po: st at e>MA</po: st at e> <po: post al Code>01775</po: post al Code> </po: bi l l To> <po: shi pTo href ="addr- 1"/> <po: order> <po: i t em sku="318- BP" quant i t y="5"> <po: descri pt i on> Skat eboard backpack; f i ve pocket s </po: descri pt i on> </po: i t em> <po: i t em sku="947- TI " quant i t y="12"> <po: descri pt i on> St reet - st yl e t i t ani um skat eboard. </po: descri pt i on> </po: i t em> <po: i t em sku="008- PR" quant i t y="1000"/> </po: order> </po: po> </msg: i t em> </msg: at t achment > </msg: message> msg

  I n t his exam ple, t he elem ent s prefixed w it h are associat ed w it h a nam espace w hose

  po

  ident ifier is ht t p: / / w w w .xcom m ercem sg.com / ns/ m essage , and t hose prefixed w it h are

  http://www.skatestown.com/ns/po associat ed w it h a nam espace w hose ident ifier is .

  The prefixes are linked t o t he com plet e nam espace ident ifiers by t he at t ribut es on t he

  message xmlns xmlns:msg xmlns:po

  t op elem ent beginning w it h : ( and ) . XML processing soft w are w ill have access t o bot h t he prefixed nam e and t o t he m apping of prefixes t o com plet e nam espace ident ifiers. Adding a prefix t o every single elem ent in t he docum ent som ew hat decreases readabilit y and increases docum ent size. Therefore, XML Nam espaces let you use a default nam espace in a docum ent . Elem ent s belonging t o t he default nam espace do not require

  msg prefixes. List ing 2.7 m akes t he nam espace t he default .

  Listing 2.7 Using Default Namespaces

  <message f rom="bj @bj skat es. com" t o="orders@skat est own. com" sent ="2001- 10- 05" xmlns ="ht t p: //www. xcommercemsg. com/ns/message" xmlns: po="ht t p: //www. skat est own. com/ns/po"> <t ext > Hi , here i s what I need t hi s t i me. Thx, BJ . </t ext > <at t achment > <descri pt i on>The PO</descri pt i on> <i t em> <po: po i d="43871" submit t ed="2001- 10- 05"> . . . </po: po>

  </at t achment > </message>

  Default nam espaces w ork because t he cont ent of any nam espace- prefixed elem ent is considered t o belong t o t he nam espace of it s parent elem ent unless, of course, t he

  xmlns

  elem ent is explicit ly defined t o be in anot her nam espace w it h it s ow n - t ype at t ribut e. We can use t his t o furt her clean up t he com posed XML docum ent by m oving

  po t he PO nam espace declarat ion t o t he elem ent ( see List ing 2.8 ) .

  Listing 2.8 Using Nested Namespace Defaulting

  <message f rom="bj @bj skat es. com" t o="orders@skat est own. com" sent ="2001- 10- 05" xmlns="ht t p: //www. xcommercemsg. com/ns/message"> <t ext > Hi , here i s what I need t hi s t i me. Thx, BJ . </t ext > <at t achment > <descri pt i on>The PO</descri pt i on> <i t em> <po: po i d="43871" submit t ed="2001- 10- 05" xmlns: po="ht t p: //www. skat est own. com/ns/po"> <bi l l To i d="addr- 1"> . . . </bi l l To> <shi pTo href ="addr- 1"/> <order> . . . </order> </po: po> </i t em> </at t achment > </message>

  This exam ple shows an efficient , readable synt ax t hat com plet ely elim inat es t he recognit ion and collision problem s. XML processors can ident ify t he nam espace of any elem ent in t he docum ent .

Namespace-Prefixed Attributes

  At t ribut es can also have nam espaces associat ed w it h t hem . I nit ially, it m ight be hard t o im agine w hy a capabilit y like t his w ould be useful for XML applicat ions. The com m on use- case scenario is t he desire t o ext end t he inform at ion provided by an XML elem ent w it hout having t o m ake changes direct ly t o it s docum ent t ype.

  A concret e exam ple m ight involve Skat esTow n w ant ing t o have an indicat ion of t he priorit y of cert ain it em s in purchase orders. High- priorit y it em s could be shipped im m ediat ely, w it hout w ait ing for any back- ordered it em s t o becom e available and com plet e t he w hole order. I t em priorit ies are not som et hing t hat Skat esTow n's aut om at ic order processing soft w are underst ands. They are j ust a hint for t he fulfillm ent syst em on how it should react in case of back- ordered it em s.

  item

  A sim ple im plem ent at ion could involve ext ending t he elem ent w it h an opt ional

  priority

  at t ribut e. How ever, t his could cause a problem for t he order processing soft w are t hat does not expect t o see such an at t ribut e. A bet t er solut ion is t o at t ach

  priority

  priorit y inform at ion t o it em s using a nam espace- prefixed at t ribut e. Because

  The exam ple in List ing 2.9 uses t his m echanism t o m ake t he backpacks high priorit y and

  priority

  t he prom ot ional m at erials low priorit y. By default , any it em s w it hout a at t ribut e, such as t he skat eboards, are presum ed t o be of m edium priorit y. Listing 2.9 Adding Priority to Order Items

  <message f rom="bj @bj skat es. com" t o="orders@skat est own. com" sent ="2001- 10- 05" xmlns="ht t p: //www. xcommercemsg. com/ns/message"> <t ext > Hi , here i s what I need t hi s t i me. Thx, BJ . </t ext > <at t achment > <descri pt i on>The PO</descri pt i on> <i t em> <po: po i d="43871" submit t ed="2001- 10- 05" xmlns: po="ht t p: //www. skat est own. com/ns/po"> xmlns: p="ht t p: //www. skat est own. com/ns/pri ori t y"> . . . <po: order> <po: i t em sku="318- BP" quant i t y="5" p: pri ori t y="hi gh"> <po: descri pt i on> Skat eboard backpack; f i ve pocket s </po: descri pt i on> </po: i t em> <po: i t em sku="947- TI " quant i t y="12"> <po: descri pt i on> St reet - st yl e t i t ani um skat eboard. </po: descri pt i on> </po: i t em> <po: i t em sku="008- PR" quant i t y="1000" p: pri ori t y="l ow"/> </po: order> </po: po> </i t em> </at t achment > </message>

Dereferencing URIs

  All t he exam ples in t his sect ion have used nam espace URI s t hat are URLs. A nat ural quest ion arises: What is t he resource at t hat URL? The answ er is t hat it doesn't m at t er. XML Nam espaces does not require t hat a resource be t here. The URI is used ent irely for ident ificat ion purposes.

  This could cause problem s for applicat ions t hat see an unknow n nam espace in an XML docum ent and have no w ay t o obt ain m ore inform at ion about t he elem ent s and at t ribut es t hat belong t o t hat nam espace. Lat er in t his chapt er, in t he sect ion on XML Schem as, you w ill see a m echanism t hat addresses t his issue.

  Document Type Definitions

  Docum ent Type Definit ions ( DTDs) are an opt ional feat ure of XML docum ent s. A at t ribut es can be part of t he docum ent and w here can t hey appear. DTDs originat e from SGML, alt hough XML's DTDs are great ly sim plified. The presence of DTDs in XML docum ent s allow s us t o dist inguish t he concept s of w ell- form edness and validit y

  Well-Formedness and Validity

  I f a docum ent subscribes t o t he rules of XML synt ax ( as described in t he sect ion "

  XML I nst ances " ) it is considered w ell- form ed. Well- form edness im plies t hat XML processing

  soft ware can read t he docum ent wit hout any basic errors associat ed wit h parsing such as invalid charact er dat a, m ism at ched st art and end t ags, m ult iple at t ribut es w it h t he sam e nam e, and so on. The XML Specificat ion m andat es t hat if any w ell- form edness const raint is not m et , t he XML parser m ust im m ediat ely generat e a non- recoverable error. This rigid m andat e m akes it easy t o separat e t he doings of t he soft w are focused on t he logical st ruct ure of an XML docum ent ( w hat t he m arkup m eans) from t he m undane det ails of t he physical st ruct ure of t he docum ent ( t he m arkup synt ax) . How ever, w ell- form edness is not sufficient for m ost applicat ions. Consider, for exam ple, t he Skat esTow n order processing applicat ion. When an XML docum ent is subm it t ed t o it , it cares not t hat it is w ell- form ed XML but t hat it is indeed a purchase order in t he specific XML form at it requires. The not ion of form at applies t o t he set of rules describing

  po

  Skat esTow n's purchase orders: " The docum ent m ust begin w it h a elem ent t hat has

  id submitted billTo

  t w o at t ribut es ( and ) w hich w ill be follow ed by a elem ent …" and so on. I n ot her w ords, before a subm it t ed docum ent is processed, it m ust be ident ified as a valid purchase order. This is how t he not ion of validit y com es in. DTDs offer an aut om at ed, declarat ive m echanism for validat ing t he cont ent s of XML docum ent s as t hey are parsed. Therefore,

  XML applicat ions can lim it t he am ount of validat ion t hey need t o perform . I f t he Skat esTow n purchase order processing applicat ion could not delegat e validat ion t o t he

  XML processor, it w ould have had t o express all validat ion rules direct ly in code. Code is procedural in nat ure and m uch harder t o m aint ain t han DTDs, w hich are declarat ive and have a reasonably readable synt ax. To handle validit y checks, DTDs m ust enable t he follow ing:

  Identification of the elements that can be in a document

  • Identification of the order and relation between elements • Identification of the attributes of every element and whether they
  • are optional or required

  Last but not least , t here needs t o be a m echanism t o associat e DTDs w it h XML docum ent s.

Document Structure

  DTDs are a m echanism t o express t he valid st ruct ure of a docum ent . One way t o visualize t he st ruct ure of a docum ent is as a t ree of possible elem ent and at t ribut e com binat ions. For exam ple, Figure 2.3 shows t he docum ent st ruct ure for purchase orders as expressed by a popular XML processing t ool. The im age uses som e synt ax from regular expressions t o visualize t he m ult iplicit y of elem ent s: quest ion m ark ( ?) st ands for opt ional ( zero or one) , ast erisk ( * ) st ands for any ( zero or m ore) , and plus ( + ) st ands for at least som e ( one or m ore) .

  Every elem ent in t he docum ent st ruct ure t ree has an associat ed m odel group. Model groups ident ify t he sequencing and m ult iplicit y of elem ent cont ent . There are t w o t ypes of sequences: sequence and choice. Sequence defines t he exact order in which child elem ent s m ust appear. I n DTDs, t he sequence operat or in m odel groups is t he com m a ( ,) . The m odel group ( A, B, C) defines a cont ent m odel w here t he first child elem ent w ill be A, follow ed by B, follow ed by C. Choice defines t he possible elem ent s t hat can appear at any given posit ion in t he cont ent m odel. The choice operat or in m odel groups is t he pipe charact er ( | ) . The m odel group ( A | B | C) defines a cont ent m odel w here t here will be only one child elem ent t hat can be A or B or C. Sequences and choices can be nest ed, as in ( ( A | ( X, Y, Z) ) , B, ( C | D) ) . This cont ent m odel defines t he follow ing possible com binat ions of child elem ent s:

  A, B, D • X, Y, Z, B, C • X, Y, Z, B, D •

  The m ult iplicit y of elem ent s is defined using t he sam e regular expression synt ax used in docum ent st ruct ure t rees. The absence of a suffix st ands for exact ly one, quest ion m ark

  ( + ) st ands for at least som e ( one or m ore) . For exam ple, t he m odel group ( A, B?, C* , D+ ) allow s for t he follow ing com binat ions of child elem ent s ( … st ands for " pot ent ially m any m ore of t he sam e elem ent " ) :

  A, D… •

  A, B, D… •

  A, B, C…, D…

  • A, C…, D… • Are DTDs Enough?

  Docum ent s associat ed wit h DTDs are a huge st ep forward from basic XML m arkup. DTDs allow for validat ing docum ent st ruct ure ( elem ent cont ent , allow ed at t ribut es, and t heir value t ypes) , w hich significant ly reduces t he am ount of cust om validat ion code t hat needs t o be w rit t en in XML applicat ions. How ever, DTDs have som e not able deficiencies:

  Although they express structured information, they do not use XML • markup. DTD syntax is not as easy to process and manipulate as XML. DTDs were designed before namespaces came into existence and don't • have good facilities for dealing with them. This is a problem for data-oriented applications that rely heavily on namespaces. DTDs do not offer sufficient reusability and extensibility • capabilities. No mechanism exists for associating more than one DTD

with an XML document. It is easy to reach the limit of what DTDs

allow for even basic applications. DTDs model groups are sometimes too restrictive, in particular with • respect to the order of child elements. No convenient DTD mechanism exists for declaring, for example, that the content of some element

could include two child elements A and five child elements B,

regardless of the order in which they appear. DTDs have no notion of data types. This hurts data-oriented • applications where XML is eventually bound to some application-level data structure in a programming language. For example, DTDs offer no quantity mechanism to enforce the simple rule that the values of the attribute of the item element should be positive integers. For these reasons and others, one of the main Web service protocols— • Simple Object Access Protocol (SOAP), which we'll discuss in Chapter 3 —explicitly forbids the use of DTDs for defining document structure.

  For t hese reasons, t his chapt er w ill not discuss DTDs in any furt her det ail. We w on't even int roduce t he basic DTD synt ax here because dat a- orient ed XML applicat ions have m oved aw ay from DTDs; t hese applicat ions use anot her m echanism t o validat e XML docum ent s in DTDs, t he XML com m unit y developed XML Schem a, a m uch richer m et a- language for XML docum ent s expressed nat ively in XML.

XML Schemas

  XML provides a flexible set of st ruct ures t hat can represent m any different t ypes of docum ent - and dat a- orient ed inform at ion. As part of XML 1.0, DTDs offered t he basic m echanism for defining a vocabulary specifying t he st ruct ure of XML docum ent s in an at t em pt t o est ablish a cont ract ( how an XML docum ent w ill be st ruct ured) bet w een m ult iple part ies w orking w it h t he sam e t ype of XML. DTDs cam e int o exist ence because people and applicat ions w ant ed t o be able t o t reat XML at a higher level t han a collect ion of elem ent s and at t ribut es. Well- designed DTDs at t ach sem ant ics ( m eaning) t o t he XML synt ax in docum ent s.

  At t he sam e t im e, DTDs fail t o address t he com m on needs of nam espace int egrat ion, m odular vocabulary design, flexible cont ent m odels, and t ight int egrat ion w it h dat a- orient ed applicat ions. This failure com es as a direct result of XML's SGML origins and t he predom inant ly docum ent - cent ric nat ure of SGML applicat ions. To address t hese issues, t he XML com m unit y, under t he leadership of t he W3C, t ook up t he t ask of creat ing a m et a- language for describing bot h t he st ruct ure of XML docum ent and t he m apping of

  XML synt ax t o dat a t ypes. Aft er long deliberat ion, t he effort produced t he final version of t he XML Schem a specificat ion in March, 2001. I n a nut shell, XML Schem a can be described as pow erful but com plex. I t is pow erful because it allow s for m uch m ore expressive and precise specificat ion of t he cont ent of XML docum ent s. I t is com plex for t he sam e reason. The specificat ion is broken int o t hree part s:

  • XML Schem a Part 0: Prim er is a non- norm ative docum ent that tries to m ake sense of XML Schem a by parceling com plexit y int o sm all chunks and using m any exam ples.
  • XML Schem a Part 1: Structures focuses prim arily on serving the needs of docum ent - orient ed applicat ions by laying out t he rules for defining t he st ruct ure of XML docum ent s.
  • XML Schem a Part 2: Datatypes builds upon the structures specification with addit ional capabilit ies t hat address t he needs of dat a- orient ed applicat ions such as defining reusable dat at ypes, associat ing XML synt ax w it h schem a dat at ypes, and m apping t hese t o applicat ion- level dat a.

  Part 0 is m eant for general consum pt ion, w hereas Part s 1 and 2 are deeply t echnical and require a skilled and det erm ined reader. The rest of t his sect ion w ill at t em pt t o provide an int roduct ion t o XML Schem a t hat is very m uch biased t ow ards schem a usage in dat a- orient ed applicat ions. You should be able t o gain sufficient underst anding of st ruct ure and dat at ype specificat ions t o com prehend and use com m on Web service schem as. St ill, because XML Schem a is fundam ent al t o Web services, w e highly recom m end t hat you go t hrough t he prim er docum ent of t he XML Schem a specificat ion.

  XML Schema Basics List ing 2.10 shows t he basic st ruct ure of t he Skat esTown purchase order schem a.

  Listing 2.10 Basic XML Schema Structure

  <?xml versi on="1. 0" encodi ng="UTF- 8"?> <xsd: schema xmlns="ht t p: //www. skat est own. com/ns/po" xmlns: xsd="ht t p: //www. w3. org/2001/XMLSchema" t arget Namespace="ht t p: //www. skat est own. com/ns/po">

  <xsd: annot at i on> <xsd: document at i on xml: l ang="en"> Purchase order schema f or Skat esTown. </xsd: document at i on> </xsd: annot at i on> . . . </xsd: schema>

  The m ost st riking difference bet w een schem as ( t hat is how t he book w ill inform ally refer t o XML Schem as) and DTDs is t hat schem as are expressed in XML. This w as done t o elim inat e t he need for XML parsers t o know anot her synt ax ( t hat of DTDs) and also t o gain t he power of expressive XML synt ax. Of course, t he XML Schem a vocabulary is it self defined using schem a as an ult im at e proof of t he pow er of t he schem a m et a- language. The second very im port ant feat ure of schem a is t hat t hey are designed w it h nam espaces in m ind from t he ground up. I n t his part icular schem a docum ent , all elem ent s belonging

  xsd

  t o t he schem a specificat ion are prefixed w it h : . The prefix's nam e is not im port ant ,

  xsd

  but : ( w hich com es from XML Schem a Definit ion) is t he convent ion. The prefix is associat ed wit h t he ht t p: / / w w w .w 3.org/ 2001/ XMLSchem a nam espace t hat ident ifies t he W3C Recom m endat ion of t he XML Schem a specificat ion. The default nam espace of t he

  http://www.skatestown.com/ns/po

  docum ent is set t o be , t he nam espace of t he Skat esTow n purchase order. The schem a docum ent needs bot h nam espaces t o dist inguish bet w een XML elem ent s t hat belong t o t he schem a specificat ion versus XML

  targetNamespace

  elem ent s t hat belong t o purchase orders. Finally, t he at t ribut e of t he

  schema

  elem ent ident ifies t he nam espace of t he docum ent s t hat w ill conform t o t his schem a. This is set t o t he purchase order schem a nam espace.

  xsd:schema

  The schem a is enclosed by t he elem ent . The cont ent of t his elem ent w ill be ot her schem a elem ent s t hat are used for elem ent , at t ribut e, and dat at ype definit ions. The annot at ion and docum ent at ion elem ent s can be used liberally t o at t ach auxiliary inform at ion t o t he schem a.

  Associating Schemas with Documents

  Schem as do not have t o be associat ed w it h XML docum ent s. For exam ple, applicat ions can be pre- configured t o use a part icular schem a w hen processing docum ent s. Alt ernat ively, t here is a powerful m echanism for associat ing schem as wit h docum ent s.

  List ing 2.11 shows how t o associat e t he previous schem a wit h a purchase order docum ent .

  Listing 2.11 Associating Schema with Documents

  <?xml versi on="1. 0" encodi ng="UTF- 8"?> <po: po xmlns: po="ht t p: //www. skat est own. com/ns/po" xmlns: xsi ="ht t p: //www. w3. org/2001/XMLSchema- i nst ance" xsi : schemaLocat i on="ht t p: //www. skat est own. com/ns/po ht t p: //www. skat est own. com/schema/po. xsd" i d="43871" submit t ed="2001- 10- 05"> . . . </po: po>

  First , because t he purchase order schem a ident ified a t arget nam espace, purchase order docum ent s are required t o use nam espaces t o ident ify t heir elem ent s. The purchase

  po order docum ent uses t he prefix for t his t ask.

  Next , t he docum ent uses anot her nam espace— ht t p: / / w w w .w 3.org/ 2001/ XMLSchem a-

  inst ance —t hat has a special m eaning. I t defines a num ber of at t ribut es t hat are part of

  t he schem a specificat ion. These at t ribut es can be applied t o elem ent s in inst ance docum ent s t o provide addit ional inform at ion t o a schem a- aw are XML processor. By

  xsi

  convent ion, m ost docum ent s use t he nam espace prefix : ( for XML Schem a: I nst ance) . The binding bet w een t he purchase order docum ent and it s schem a is est ablished via t he

  xsi:schemaLocation

  at t ribut e. This at t ribut e cont ains a pair of values. The first value is t he nam espace ident ifier w hose schem a's locat ion is ident ified by t he second value. Typically, t he second value w ill be a URL, but specialized applicat ions can use ot her t ypes of values, such as an ident ifier in a schem a reposit ory or a well- known schem a nam e. I f

  xsi:schemaLocation

  t he docum ent used m ore t han one nam espace, t he at t ribut e w ould cont ain m ult iple pairs of values.

  Simple Types

  One of t he biggest problem s of DTDs is t hat t hey have no not ion of dat at ypes, even for sim ple values such as t he charact er dat a cont ent of an elem ent or an at t ribut e value. Because of t his, prior t o t he arrival of XML schem a, XML applicat ions included a large am ount of validat ion code. For exam ple, even a sim ple purchase order requires t he follow ing validat ion rules t hat are out side t he scope of DTDs:

  Attribute

  • id of the po element must be a positive integer.

  Attribute • submitted of the po element must be a date in the format yyyy-mm-dd.

  • Attribute quantity of the item element must be a positive integer.
  • sku item

  

Attribute (stock keeping unit) of the element must be a

string with the format three digits followed by a dash followed by two uppercase letters.

  XML schem as address t hese issues in t w o ways. First , t he specificat ion com es wit h a large set of pre- defined basic dat at ypes such as st ring, posit ive int eger, and dat e. These

  sku

  can be used direct ly. For cust om dat a t ypes, such as t he values of t he at t ribut e, t he specificat ion defines a pow erful m echanism for defining new t ypes. Table 2.2 shows som e of t he com m only used pre- defined schem a t ypes w it h som e exam ples of t heir use.

Table 2.2. Pre-defined XML Schema Simple Types

Simple Type Examples (delimited by commas) Notes

  string Confirm this is electric base64Binary

  GpM7 hexBinary

  0FB7 integer

  • 126789, -1, 0, 1, 126789

  positiveInteger 1, 126789 negativeInteger

  • 126789, -1

  nonNegativeInteger 0, 1, 126789

  • 126789, -1, 0
  • 1.23, 0, 123.4, 1000.00

  maxLength

  

IDREF

  at t ribut es perfect for handling at t ribut es such as t he

  id

  /

  href ones in Skat esTow n's purchase order address elem ent .

  The process for creat ing new sim ple dat at ypes is st raight forw ard. The new t ype m ust be derived from a base t ype: a pre- defined schem a t ype or anot her already defined sim ple t ype. The base t ype is rest rict ed along a num ber of facet s t o obt ain t he new t ype. The facet s ident ify various charact erist ics of t he t ypes such as:

  ,

  minLength

  and

  — t he exact , m inim um and m axim um charact er lengt h of t he value

  ID

  — a regular expression pat t ern for t he value

  — a list of all possible values

  — t he rules for handling w hit espace in t he value

  ,

  minInclusive

  ,

  

maxInclusive

  and

  maxExclusive

  — t he range of num eric values t hat are allow ed

  /

  value. This m akes

  — t he num ber of decim al digit s in num eric values Of course, not all facet s apply t o all t ypes. For exam ple, t he not ion of fract ion digit s m akes no sense for a dat e or a nam e. Tables 2.3 and

  XML 1.0 ID attribute type

  nonPositiveInteger

  decimal

  boolean true, false 1, 0 time

  13:20:00.000, 13:20:00.000-05:00 dateTime

  1999-05-31T13:20:00.000-05:00 May 31st 1999 at 1.20pm Eastern Standard Time, which is 5 hours behind Coordinated Universal Time duration

  P1Y2M3DT10H30M12.3S 1 year, 2 months, 3 days, 10 hours, 30 minutes, and12.3 seconds date

  1999-05-31 Name shipTo

  XML 1.0 Name type QName po:USAddress

  XML Namespace QName anyURI http://www.example.com/ , http://www.example.com/doc.html#ID5

  ID

  IDREF

  ID

  XML 1.0 IDREF attribute type The information in this table comes from the XML Schema Primer.

  A not e on

  ID

  /

  IDREF

  at t ribut es: An XML processor is required t o generat e an error if a docum ent cont ains t w o

  ID

  at t ribut es w it h t he sam e value or an

  IDREF

  w it h a value t hat has no m at ching

  • length
  • pattern
  • enumeration
  • whiteSpace
  • minExclusive
  • totalDigits

  2.4 cross- link t he pre- defined t ypes and t he facet s t hat are applicable for t hem .

Table 2.3. XML Schema Facets for Simple Types

Simple Types Facets

  length minLength maxLength pattern enumeration whiteSpace string base64Binary hexBinary integer positiveInteger negativeInteger nonNegativeInteger nonPositiveInteger decimal boolean time dateTime duration date Name QName anyURI

  ID

  IDREF The information in this table comes from the XML Schema Primer.

  The facet s list ed in Table 2.4 apply only t o sim ple t ypes t hat have an im plicit order.

Table 2.4. XML Schema Facets for Ordered Simple Types

Simple Types Facets

Max Max Min Min Total Fraction Inclusive Exclusive Inclusive Exclusive Digits Digits

  integer positiveInteger negativeInteger nonNegativeInteger nonPositiveInteger decimal time dateTime duration date The information in this table comes from the XML Schema Primer.

  The synt ax for creat ing new t ypes is sim ple. For exam ple, t he schem a snippet in List ing

  skuType

2.12 defines a sim ple t ype for purchase order SKUs. The nam e of t he t ype is . I t

  is based on a st ring and it rest rict s it t o have t he pat t ern of t hree digit s follow ed by dash follow ed by t w o uppercase let t ers. Listing 2.12 Using Patterns to Define String Format

  <xsd: si mpl eType name="skuType"> <xsd: rest ri ct i on base="xsd: st ri ng"> <xsd: pat t ern val ue="\d{ 3} - [ A- Z] { 2} "/> </xsd: rest ri ct i on> </xsd: si mpl eType> List ing 2.13 show s how t o force purchase order ids t o be great er t han 10,000 but less t han 100,000 and define an enum erat ion of all U.S. st at es.

  Listing 2.13 Using Ranges and Enumerations

  <xsd: si mpl eType name="poI dType"> <xsd: rest ri ct i on base="xsd: i nt eger"> <xsd: minExcl usi ve val ue="10000"/> <xsd: maxExcl usi ve val ue="100000"/> </xsd: rest ri ct i on> </xsd: si mpl eType> <xsd: si mpl eType name="st at eType"> <xsd: rest ri ct i on base="xsd: st ri ng"> <xsd: enumerat i on val ue="AK"/> <xsd: enumerat i on val ue="AL"/> <xsd: enumerat i on val ue="AR"/> . . . </xsd: rest ri ct i on> </xsd: si mpl eType>

Complex types

  I n XML Schem a, sim ple t ypes define t he valid choices for charact er- based cont ent such as at t ribut e values and elem ent s w it h charact er cont ent . Com plex t ypes, on t he ot her hand, define com plex cont ent m odels, such as t hose of elem ent s t hat can have at t ribut es and nest ed children. Com plex t ype definit ions do address bot h t he sequencing and m ult iplicit y of child elem ent s as w ell as t he nam es of associat ed at t ribut es and w het her t hey are required or opt ional. The m ain difference w it h respect t o DTDs is t hat t he schem a synt ax is m uch m ore expressive and t he schem a capabilit ies are m uch m ore pow erful.

  The synt ax for defining com plex t ypes is st raight forward:

  <xsd: compl exType name="t ypeName"> <xsd: someTopLevel Model Group> <! - - Sequenci ng and mul t i pl i ci t y const rai nt s f or

  </xsd: someTopLevel Model Group> <! - - At t ri but e decl arat i ons usi ng xsd: at t ri but e - - > </xsd: compl exType> xsd:complexType

  The elem ent ident ifies t he t ype definit ion. There are m any different w ays t o specify t he m odel group of t he com plex t ype. The m ost com m only used t op- level m odel group elem ent s you w ill see are:

  • xsd:sequence

  — A sequence of elem ent s

  • xsd:choice

  — Allow s one out of a num ber of elem ent s

  • xsd:all

  — Allow s a cert ain set of elem ent s t o appear once or not at all but in any order

  • xsd:group

  — References a m odel group t hat is defined som eplace else

  xsd:group

  These could be furt her nest ed t o creat e m ore com plex m odel groups. The m odel group elem ent is covered lat er in t his chapt er in t he sect ion " Cont ent Model

  Groups ." xsd:element

  I nside t he m odel group specificat ion, child elem ent s are defined using . The m odel group specificat ion is follow ed by any num ber of at t ribut e definit ions using

  xsd:attribute .

  For exam ple, one possible w ay t o define t he cont ent m odel of t he purchase order address

  billTo shipTo

  used in t he and elem ent s is show n in List ing 2.14 . The nam e of t he

  addressType xsd:sequence xsd:element

  com plex t ype is . Using and , it defines a

  name company street city state postalCode

  sequence of t he elem ent s , , , , , , and

  country .

  Listing 2.14 Schema Fragment for the Address Complex Type

  <xsd: compl exType name="addressType"> <xsd: sequence> <xsd: el ement name="name" t ype="xsd: st ri ng" minOccurs="0"/> <xsd: el ement name="company" t ype="xsd: st ri ng" minOccurs="0"/> <xsd: el ement name="st reet " t ype="xsd: st ri ng" maxOccurs="unbounded"/> <xsd: el ement name="ci t y" t ype="xsd: st ri ng"/> <xsd: el ement name="st at e" t ype="xsd: st ri ng" minOccurs="0"/> <xsd: el ement name="post al Code" t ype="xsd: st ri ng" minOccurs="0"/> <xsd: el ement name="count ry" t ype="xsd: st ri ng" minOccurs="0"/> </xsd: sequence> <xsd: at t ri but e name="i d" t ype="xsd: I D"/> <xsd: at t ri but e name="href " t ype="xsd: I DREF"/> </xsd: compl exType> minOccurs

  The m ult iplicit ies of t hese elem ent s' occurrences are defined using t he and

  maxOccurs xsd:element minOccurs

  at t ribut es of . The value of zero for renders an elem ent 's presence opt ional ( " ?" in t he docum ent st ruct ure diagram s) . The default value

  minOccurs maxOccurs "unbounded"

  for is 1. The special value for of is used for t he st reet elem ent t o indicat e t hat t here m ust be at least one present ( " " in t he docum ent

  • st ruct ure diagram s) .

  xsd:element

  Every elem ent is associat ed w it h a t ype using t he t ype at t ribut e . I n t his xsd:string

  t ype. I t m ight seem unusual t o you t hat t he nam espace prefix is used inside an at t ribut e value. I t is t rue, t he XML Nam espaces specificat ion does not explicit ly address t his use of nam espace prefixes. How ever, t he idea is sim ple. A schem a can define any num ber of t ypes. Som e of t hem are built int o t he specificat ion, and ot hers are user- defined. The only w ay t o know for sure w hich t ype is being referred t o is t o associat e t he t ype nam e w it h t he nam espace from w hich it is com ing. What bet t er w ay t o do t his t han t o prefix all references t o t he t ype w it h a nam espace prefix? Aft er t he m odel group definit ion com e t he at t ribut e definit ions. I n t his exam ple,

  xsd:attribute id href

  ID

  IDREF

  is used t o define at t ribut es and of t ypes and , respect ively. Bot h at t ribut es are opt ional by default .

  po

  Now , consider a slight ly m ore com plex exam ple of a com plex t ype definit ion—t he elem ent 's t ype ( see List ing 2.15 ) . Listing 2.15 Schema Fragment for the Purchase Order Complex Type

  <xsd: compl exType name="poType"> <xsd: sequence> <xsd: el ement name="bi l l To" t ype="addressType"/> <xsd: el ement name="shi pTo" t ype="addressType"/> <xsd: el ement name="order"> <xsd: compl exType> <xsd: sequence> <xsd: el ement name="i t em" t ype="i t emType" maxOccurs="unbounded"/> </xsd: sequence> </xsd: compl exType> </xsd: el ement > </xsd: sequence> <xsd: at t ri but e name="i d" use="requi red" t ype="xsd: posi t i veI nt eger"/> <xsd: at t ri but e name="submit t ed" use="requi red" t ype="xsd: dat e"/> </xsd: compl exType> poType

  The int roduces t hree int erest ing aspect s of schem a:

  It shows how easy it is to achieve basic reusability of types. Both • billTo shipTo addressType

the and elements refer to the defined

previously. Note that because this is a user defined complex type, a namespace prefix is not necessary in this case.

  It shows that the association between elements and their types can be

  • implicit. The order element's type is defined inline as a sequence of

  itemType

one or more item elements of type . This is convenient

because it keeps the schema more readable and it prevents the need to define a global type that is used in only one place.

  It shows that the presence of attributes can be required through the

  • use="required" attribute-value pair of the xsd:attribute element. To

  give default and fixed values to attributes, you can also use the aptly named default and fixed attributes of xsd:attribute . The Purchase Order Schema

  Wit h t he inform at ion gat hered so far, w e can com plet ely define t he Skat esTow n purchase order schem a. The docum ent st ruct ure t ree in Figure 2.4 looks very sim ilar t o t hat from t he sect ion on DTDs. The m ain difference is t he presence of m ore det ailed dat at ype inform at ion. List ing 2.16 shows t he com plet e schem a.

Figure 2.4. Document structure defined by purchase order schema.

  Listing 2.16 The Complete SkatesTown Purchase Order Schema ( )

  po.xsd <?xml versi on="1. 0" encodi ng="UTF- 8"?> <xsd: schema xmlns="ht t p: //www. skat est own. com/ns/po" xmlns: xsd="ht t p: //www. w3. org/2001/XMLSchema" t arget Namespace="ht t p: //www. skat est own. com/ns/po"> <xsd: annot at i on> <xsd: document at i on xml: l ang="en"> Purchase order schema f or Skat esTown. </xsd: document at i on> </xsd: annot at i on>

  <xsd: compl exType name="poType"> <xsd: sequence> <xsd: el ement name="bi l l To" t ype="addressType"/> <xsd: el ement name="shi pTo" t ype="addressType"/> <xsd: el ement name="order"> <xsd: compl exType> <xsd: sequence> <xsd: el ement name="i t em" t ype="i t emType" maxOccurs="unbounded"/> </xsd: sequence> </xsd: compl exType> </xsd: el ement > </xsd: sequence> <xsd: at t ri but e name="i d" use="requi red" t ype="xsd: posi t i veI nt eger"/> <xsd: at t ri but e name="submit t ed" use="requi red" t ype="xsd: dat e"/> </xsd: compl exType> <xsd: compl exType name="addressType"> <xsd: sequence> <xsd: el ement name="name" t ype="xsd: st ri ng" minOccurs="0"/>

<xsd: el ement name="company" t ype="xsd: st ri ng" minOccurs="0"/> <xsd: el ement name="st reet " t ype="xsd: st ri ng" maxOccurs="unbounded"/> <xsd: el ement name="ci t y" t ype="xsd: st ri ng"/> <xsd: el ement name="st at e" t ype="xsd: st ri ng" minOccurs="0"/> <xsd: el ement name="post al Code" t ype="xsd: st ri ng" minOccurs="0"/>

<xsd: el ement name="count ry" t ype="xsd: st ri ng" minOccurs="0"/> </xsd: sequence> <xsd: at t ri but e name="i d" t ype="xsd: I D"/> <xsd: at t ri but e name="href " t ype="xsd: I DREF"/> </xsd: compl exType> <xsd: compl exType name="i t emType"> <xsd: sequence> <xsd: el ement name="descri pt i on" t ype="xsd: st ri ng" minOccurs="0"/> </xsd: sequence> <xsd: at t ri but e name="sku" use="requi red"> <xsd: si mpl eType> <xsd: rest ri ct i on base="xsd: st ri ng"> <xsd: pat t ern val ue="\d{ 3} - [ A- Z] { 2} "/> </xsd: rest ri ct i on> </xsd: si mpl eType> </xsd: at t ri but e> t ype="xsd: posi t i veI nt eger"/> </xsd: compl exType> </xsd: schema> po

  Everyt hing should look fam iliar except perhaps for t he st andalone definit ion of t he elem ent right aft er t he schem a annot at ion. This brings us t o t he im port ant t opic of local versus global elem ent s and at t ribut es. Any elem ent or at t ribut e defined inside a com plex t ype definit ion is considered local t o t hat definit ion. Conversely, any elem ent or at t ribut e

  xsd:schema defined at t he t op level ( as a child of ) is considered global.

  All global elem ent s can be docum ent root s. That is t he m ain reason why m ost schem as

  po

  define a single global elem ent . I n t he case of t he Skat esTow n purchase order, t he elem ent m ust be t he root of t he purchase order docum ent and is hence defined as a global elem ent . The not ion of global at t ribut es m ight not m ake m uch sense at first , but t hey are very convenient . You can use global at t ribut es ( in nam espace- prefixed form ) on any elem ent in a docum ent t hat allow s t hem . The it em priorit y at t ribut e discussed in t he sect ion "

  XML Nam espaces " can be defined w it h t he short schem a in List ing 2.17 .

  Listing 2.17 Defining the Priority Global Attribute Using Schema

  <?xml versi on="1. 0" encodi ng="UTF- 8"?> <xsd: schema xmlns="ht t p: //www. skat est own. com/ns/pri ori t y" t arget Namespace="ht t p: //www. skat est own. com/ns/pri ori t y" xmlns: xsd="ht t p: //www. w3. org/2001/XMLSchema"> <xsd: at t ri but e name="pri ori t y" use="opt i onal " def aul t ="medi um"> <xsd: si mpl eType> <xsd: rest ri ct i on base="xsd: st ri ng"> <xsd: enumerat i on val ue="l ow"/> <xsd: enumerat i on val ue="medi um"/> <xsd: enumerat i on val ue="hi gh"/> </xsd: rest ri ct i on> </xsd: si mpl eType> </xsd: at t ri but e> </xsd: schema>

Basic Schema Reusability

  The concept of reusabilit y is im port ant for XML Schem a. Reusabilit y deals w it h t he quest ion of how t o best leverage any already creat ed asset s in new proj ect s. I n schem a, t he asset s include elem ent and at t ribut e definit ions, cont ent m odel definit ions, sim ple and com plex dat at ypes, and w hole schem as. We can roughly break dow n reusabilit y m echanism s int o t w o kinds: basic and advanced. The basic reusabilit y m echanism s address t he problem s of using exist ing asset s in m ult iple places. Advanced reusabilit y m echanism s address t he problem s of m odifying exist ing asset s t o serve needs t hat are perhaps different from what t hey were originally designed for.

  This sect ion w ill address t he follow ing basic reusabilit y m echanism s:

  Element references • Content model groups

  • Attribute groups •

  Schema imports •

  Element References I n XML Schem a, you can define elem ent s using a nam e and a t ype. Alt ernat ively,

  ref

  elem ent declarat ions can refer t o pre- exist ing elem ent s using t he at t ribut e of

  xsd:element

  as follow s, w here a globally defined com m ent elem ent is being reused for bot h a person and a t ask com plex t ype:

  <xsd: el ement name="comment " t ype="xsd: st ri ng"/> <xsd: compl exType name="personType"> <xsd: sequence> <xsd: el ement name="name" t ype="xsd: st ri ng"/> <xsd: el ement ref ="comment " minOccurs="0"/> </xsd: sequence> </xsd: compl exType> <xsd: compl exType name="t askType"> <xsd: sequence> <xsd: el ement name="t oDo" t ype="xsd: st ri ng"/> <xsd: el ement ref ="comment " minOccurs="0"/> </xsd: sequence> </xsd: compl exType>

  Content Model Groups Elem ent references are perfect for reusing t he definit ion of a single elem ent . How ever, if your goal is t o reuse w hole or part of a cont ent m odel, t hen elem ent groups are t he w ay

  xsd:group

  t o go. Elem ent groups are defined using and are referred t o using t he sam e m echanism used for elem ent s. The follow ing schem a fragm ent illust rat es t he concept . I t ext ends t he previous exam ple so t hat inst ead of a single com m ent elem ent , public and privat e com m ent elem ent s are reused as a group:

  <xsd: group name="comment s"> <xsd: sequence> <xsd: el ement name="publ i cComment " t ype="xsd: st ri ng" minOccurs="0"/> <xsd: el ement name="pri vat eComment " t ype="xsd: st ri ng" minOccurs="0"/> </xsd: sequence> </xsd: group> <xsd: compl exType name="personType"> <xsd: sequence> <xsd: el ement name="name" t ype="xsd: st ri ng"/> <xsd: group ref ="comment s"/> </xsd: sequence> </xsd: compl exType> <xsd: compl exType name="t askType"> <xsd: sequence> <xsd: el ement name="t oDo" t ype="xsd: st ri ng"/>

  </xsd: sequence> </xsd: compl exType>

  Attribute Groups The sam e reusabilit y m echanism can be applied t o com m only used at t ribut e groups. The

  ID

  IDREF id href

  follow ing exam ple defines t he / com binat ion of an and at t ribut e as a referenceable at t ribut e group. I t is t hen applied t o bot h t he person and t he t ask t ype:

  <xsd: at t ri but eGroup name="ref erenceabl e"> <xsd: at t ri but e name="i d" t ype="xsd: I D"/> <xsd: at t ri but e name="href " t ype="xsd: I DREF"/> </xsd: at t ri but eGroup> <xsd: compl exType name="personType"> <xsd: sequence> <xsd: el ement name="name" t ype="xsd: st ri ng"/> </xsd: sequence> <xsd: at t ri but eGroup ref ="ref erenceabl e"/> </xsd: compl exType> <xsd: compl exType name="t askType"> <xsd: sequence> <xsd: el ement name="t oDo" t ype="xsd: st ri ng"/> </xsd: sequence> <xsd: at t ri but eGroup ref ="ref erenceabl e"/> </xsd: compl exType>

  Schema Includes and Imports Elem ent references and groups as w ell as at t ribut e groups provide reusabilit y w it hin t he sam e schem a docum ent . However, when you're dealing wit h very com plex schem a or t rying t o achieve m axim um reusabilit y, you'll oft en need t o split a schem a int o several docum ent s. The schem a include and im port m echanism s allow t hese docum ent s t o reference one anot her. Consider t he scenario w here Skat esTow n is int ent on reusing t he schem a definit ion for it s address t ype for a m ailing list schem a. Skat esTow n m ust solve t hree sm all problem s:

  Put the address type definition in its own schema document • Reference this schema document from the purchase order schema • document

  • Reference this schema document from the mailing list schema document Pulling t he address definit ion int o it s ow n schem a is as easy as a sim ple cut - and- past e operat ion ( see List ing 2.18 ) . Even t hough t his is a different docum ent t han t he m ain purchase order schem a, t hey bot h define port ions of t he Skat esTow n purchase order nam espace. The binding bet w een schem a docum ent s and t he nam espaces t hey define is

  targetNamespace

  not one- t o- one. I t is explicit ly ident ified by t he at t ribut e of t he

  xsd:schema elem ent .

  Listing 2.18 Standalone Address Type Schema

  <?xml versi on="1. 0" encodi ng="UTF- 8"?> xmlns: xsd="ht t p: //www. w3. org/2001/XMLSchema" t arget Namespace="ht t p: //www. skat est own. com/ns/po"> <xsd: annot at i on> <xsd: document at i on xml: l ang="en"> Address t ype schema f or Skat esTown. </xsd: document at i on> </xsd: annot at i on> <xsd: compl exType name="addressType"> <xsd: sequence> <xsd: el ement name="name" t ype="xsd: st ri ng" minOccurs="0"/> <xsd: el ement name="company" t ype="xsd: st ri ng" minOccurs="0"/> <xsd: el ement name="st reet " t ype="xsd: st ri ng" maxOccurs="unbounded"/> <xsd: el ement name="ci t y" t ype="xsd: st ri ng"/> <xsd: el ement name="st at e" t ype="xsd: st ri ng" minOccurs="0"/> <xsd: el ement name="post al Code" t ype="xsd: st ri ng" minOccurs="0"/> <xsd: el ement name="count ry" t ype="xsd: st ri ng" minOccurs="0"/> </xsd: sequence> <xsd: at t ri but e name="i d" t ype="xsd: I D"/> <xsd: at t ri but e name="href " t ype="xsd: I DREF"/> </xsd: compl exType> </xsd: schema>

  Referring t o t his schem a is also very easy. I nst ead of having t he address t ype definit ion inline, t he purchase order schem a needs t o include t he address schem a using t he

  xsd:include

  elem ent . During t he processing of t he purchase order schem a, t he address schem a w ill be ret rieved and t he address t ype definit ion w ill becom e available ( see

  List ing 2.19 ) .

  Listing 2.19 Referring to the Address Type Schema

  <?xml versi on="1. 0" encodi ng="UTF- 8"?> <xsd: schema xmlns="ht t p: //www. skat est own. com/ns/po" xmlns: xsd="ht t p: //www. w3. org/2001/XMLSchema" t arget Namespace="ht t p: //www. skat est own. com/ns/po"> <xsd: i ncl ude schemaLocat i on="ht t p: //www. skat est own. com/schema/address. xsd"/> . . . </xsd: schema> mailingList

  The m ailing list schem a is very sim ple. I t defines a single elem ent t hat

  address

  cont ains any num ber of cont act elem ent s w hose t ype is . Being an alt oget her different schem a t han purchase orders, t he m ailing list schem a uses a new nam espace,

  http://www.skatestown.com/ns/mailingList

  . List ing 2.20 shows one possible way t o define t his schem a. Listing 2.20 Mailing List Schema

  <?xml versi on="1. 0" encodi ng="UTF- 8"?> <xsd: schema xmlns="ht t p: //www. skat est own. com/ns/po" xmlns: xsd="ht t p: //www. w3. org/2001/XMLSchema" t arget Namespace="ht t p: //www. skat est own. com/ns/mai l i ngLi st "> <xsd: i ncl ude schemaLocat i on="ht t p: //www. skat est own. com/schema/address. xsd"/> <xsd: annot at i on> <xsd: document at i on xml: l ang="en"> Mai l i ng l i st schema f or Skat esTown. </xsd: document at i on> </xsd: annot at i on> <xsd: el ement name="mai l i ngLi st "> <xsd: sequence> <xsd: el ement name="cont act " t ype="addressType" minOccurs="0" maxOccurs="unbounded"/> </xsd: sequence> </xsd: el ement > </xsd: schema> xsd:include

  This exam ple uses t o bring in t he schem a fragm ent defining t he address t ype. There is no problem w it h t hat approach. How ever, t here m ight be a problem w it h

  mailingList

  aut horing m ailing list docum ent s. The root of t he problem is t hat t he and

  contact

  elem ent s are defined in one nam espace

  http://www.skatestown.com/ns/mailingList

  ( ) , w hereas t he elem ent s belonging t o t he

  

name company street city state postalCode country

  address t ype— , , , , , , —are defined

  http://www.skatestown.com/ns/po

  in anot her ( ) . Therefore, t he m ailing list docum ent m ust reference bot h nam espaces ( see List ing 2.21 ) . Listing 2.21 Mailing List that References Two Namespaces

  <?xml versi on="1. 0" encodi ng="UTF- 8"?> <l i st : mai l i ngLi st xmlns: l i st ="ht t p: //www. skat est own. com/ns/mai l i ngLi st " xmlns: addr="ht t p: //www. skat est own. com/ns/po" xmlns: xsi ="ht t p: //www. w3. org/2001/XMLSchema- i nst ance" xsi : schemaLocat i on="ht t p: //www. skat est own. com/ns/mai l i ngLi st ht t p: //www. skat est own. com/schema/mai l i ngLi st . xsd ht t p: //www. skat est own. com/ns/po ht t p: //www. skat est own. com/schema/address. xsd"> <cont act > <addr: company>The Skat eboard Warehouse</addr: company> <addr: st reet >One Warehouse Park</addr: st reet > <addr: st reet >Bui l di ng 17</addr: st reet > <addr: ci t y>Bost on</addr: ci t y> <addr: st at e>MA</addr: st at e> <addr: post al Code>01775</addr: post al Code> </cont act > </l i st : mai l i ngLi st >

  I deally, w hen reusing t he address t ype definit ion in t he m ailing list schem a, w e w ant t o hide t he fact t hat it originat es from a different nam espace and t reat it as a t rue part of

  

xsd:include

  t he m ailing list schem a. Therefore, t he m echanism is not t he right one t o use, because it m akes no nam espace changes. The reuse m echanism t hat w ill allow t he m erging of schem a fragm ent s from m ult iple nam espaces int o a single schem a is t he im port m echanism . List ing 2.22 show s t he new m ailing list schem a.

  Listing 2.22 Importing Rather Than Including the Address Type Schema

  <?xml versi on="1. 0" encodi ng="UTF- 8"?> <xsd: schema xmlns="ht t p: //www. skat est own. com/ns/po" xmlns: xsd="ht t p: //www. w3. org/2001/XMLSchema" xmlns: addr="ht t p: //www. skat est own. com/ns/po" xmlns: xsi ="ht t p: //www. w3. org/2001/XMLSchema- i nst ance" xsi : schemaLocat i on="ht t p: //www. skat est own. com/ns/po ht t p: //www. skat est own. com/schema/address. xsd" t arget Namespace="ht t p: //www. skat est own. com/ns/mai l i ngLi st "> <xsd: i mport namespace="ht t p: //www. skat est own. com/ns/po"/> <xsd: annot at i on> <xsd: document at i on xml: l ang="en"> Mai l i ng l i st schema f or Skat esTown. </xsd: document at i on> </xsd: annot at i on> <xsd: el ement name="mai l i ngLi st "> <xsd: sequence> <xsd: el ement name="cont act " t ype="addr: addressType" minOccurs="0" maxOccurs="unbounded"/> </xsd: sequence> </xsd: el ement > </xsd: schema>

  Alt hough t he m echanism is sim ple t o describe, it t akes several st eps t o execut e:

  1. We declare the namespace of the address type definition and assign it addr the prefix .

  2. We use the standard xsi:schemaLocation mechanism to point to the location of the address schema.

  3. We use xsd:import instead of xsd:include . We import just the namespace; we already know the schema location.

  

4. When referring to the address type, we use its fully qualified name

addr:addressType .

  The net result is t hat t he m ailing list inst ance docum ent has been sim plified ( see List ing 2.23 ) . Listing 2.23 Simplified Instance Document that Requires a Single Namespace

  <l i st : mai l i ngLi st xmlns: l i st ="ht t p: //www. skat est own. com/ns/mai l i ngLi st " xmlns: xsi ="ht t p: //www. w3. org/2001/XMLSchema- i nst ance" xsi : schemaLocat i on="ht t p: //www. skat est own. com/ns/mai l i ngLi st ht t p: //www. skat est own. com/schema/mai l i ngLi st . xsd"> <cont act > <company>The Skat eboard Warehouse</company> <st reet >One Warehouse Park</st reet > <st reet >Bui l di ng 17</st reet > <ci t y>Bost on</ci t y> <st at e>MA</st at e> <post al Code>01775</post al Code> </cont act > </l i st : mai l i ngLi st > Advanced Schema Reusability

  The previous sect ion dem onst rat ed how you can reuse t ypes and elem ent s " as is" from t he sam e or a different nam espace. This capabilit y can go a long w ay in som e cases, but m any real- w orld scenarios require m ore sophist icat ed reuse capabilit ies. Consider, for exam ple, t he form at of t he invoice t hat Skat esTow n w ill send t o The Skat eboard Warehouse based on it s purchase order ( see List ing 2.24 ) . Listing 2.24 SkatesTown Invoice Document

  <?xml versi on="1. 0" encodi ng="UTF- 8"?> <i nvoi ce: i nvoi ce xmlns: i nvoi ce="ht t p: //www. skat est own. com/ns/i nvoi ce" xmlns: xsi ="ht t p: //www. w3. org/2001/XMLSchema- i nst ance" xsi : schemaLocat i on="ht t p: //www. skat est own. com/ns/i nvoi ce ht t p: //www. skat est own. com/schema/i nvoi ce. xsd" i d="43871" submit t ed="2001- 10- 05"> <bi l l To i d="addr- 1"> <company>The Skat eboard Warehouse</company> <st reet >One Warehouse Park</st reet > <st reet >Bui l di ng 17</st reet > <ci t y>Bost on</ci t y> <st at e>MA</st at e> <post al Code>01775</post al Code> </bi l l To> <shi pTo href ="addr- 1"/> <order> <i t em sku="318- BP" quant i t y="5" uni t Pri ce="49. 95"> <descri pt i on>Skat eboard backpack; f i ve pocket s</descri pt i on> </i t em> <i t em sku="947- TI " quant i t y="12" uni t Pri ce="129. 00"> <descri pt i on>St reet - st yl e t i t ani um skat eboard. </descri pt i on> </i t em> <i t em sku="008- PR" quant i t y="1000" uni t Pri ce="0. 00"> <descri pt i on>Promot i onal : Skat esTown st i ckers</descri pt i on> </i t em> </order> <t ax>89. 89</t ax>

  <t ot al Cost >2087. 64</t ot al Cost > </i nvoi ce: i nvoi ce>

  The invoice docum ent has m any of t he feat ures of a purchase order docum ent , w it h a few im port ant changes:

  Invoices use a different namespace, • http://www.skatestown.com/ns/invoice .

  • invoice po The root element of the document is and not .

  The invoice element has three additional children: tax ,

  • shippingAndHandling , and totalCost .
  • item

  unitPrice The element has an additional attribute, .

  How can w e leverage t he w ork done t o define t he purchase order schem a in defining t he invoice schem a? This sect ion w ill int roduce t he advanced schem a reusabilit y m echanism s t hat m ake t his possible. Design Principles I m agine t hat purchase orders, addresses, and it em s w ere represent ed as classes in an obj ect - orient ed program m ing language such as Java. We could creat e an invoice obj ect

  item invoiceItem unitPrice po invoice

  by sub- classing t o ( w hich adds ) and t o ( w hich

  tax shippingAndHandling totalCost

  adds , , and ) . The benefit of t his approach is t hat

  address

  any changes t o relat ed classes such as w ill be aut om at ically picked up by bot h

  item

  purchase orders and invoices. Furt her, any changes in base t ypes such as w ill be

  invoiceItem aut om at ically picked up by derived t ypes such as .

  The follow ing pseudo- code show s how t his approach m ight w ork:

  cl ass Address { . . . } cl ass I t em { St ri ng sku; i nt quant i t y; } cl ass I nvoi ceI t em ext ends I t em { f l oat uni t Pri ce; } cl ass PO { i nt i d; Dat e submit t ed; Address bi l l To; Address shi pTo; I t em order[ ] ; }

  { f l oat t ax; f l oat shi ppi ngAndHandl i ng; f l oat t ot al Cost ; }

  Everyt hing looks good except for one im port ant det ail. You m ight have not iced t hat

  Invoice PO order

  probably shouldn't subclass . The reason is t hat t he array inside an

  invoice InvoiceItem Item

  obj ect m ust hold s and not j ust . The subclassing relat ionship

  Item InvoiceItem

  w ill force you t o w ork w it h s inst ead of s. Doing so w ill w eaken st at ic t ype- checking and w ill require const ant dow ncast ing, w hich is generally a bad t hing in

  Invoice

  w ell- designed obj ect - orient ed syst em s. A bet t er design for t he class,

  

PO

  unfort unat ely, requires som e duplicat ion of 's dat a m em bers:

  cl ass I nvoi ce { i nt i d; Dat e submit t ed; Address bi l l To; Address shi pTo; I nvoi ceI t em order[ ] ; f l oat t ax; f l oat shi ppi ngAndHandl i ng; f l oat t ot al Cost ; }

  Item InvoiceItem InvoiceItem

  Not e t hat subclassing t o get is a good decision because

  Item

  is a pure ext ension of . I t adds new dat a m em bers; it does not in any w ay require

  Item m odificat ions t o 's dat a m em bers, nor does it change t he w ay t hey are used.

  Extensions and Restrictions The analysis from obj ect - orient ed syst em s can be direct ly applied t o t he design of

  invoice

  Skat esTow n's invoice schem a. The schem a w ill define t he elem ent in t erm s of

  

addressType item

  pre- exist ing t ypes such as , and t he invoice's t ype w ill reuse t he already defined purchase order it em t ype via ext ension ( see List ing 2.25 ) . Listing 2.25 SkatesTown Invoice Schema

  <?xml versi on="1. 0" encodi ng="UTF- 8"?> <xsd: schema xmlns="ht t p: //www. skat est own. com/ns/i nvoi ce" t arget Namespace="ht t p: //www. skat est own. com/ns/i nvoi ce" xmlns: xsd="ht t p: //www. w3. org/2001/XMLSchema" xmlns: po="ht t p: //www. skat est own. com/ns/po"> <xsd: i mport namespace="ht t p: //www. skat est own. com/ns/po" schemaLocat i on="ht t p: //www. skat est own. cm/schema/po. xsd"/> <xsd: annot at i on> <xsd: document at i on xml: l ang="en"> I nvoi ce schema f or Skat esTown. </xsd: document at i on> </xsd: annot at i on>

  <xsd: compl exType name="i nvoi ceType"> <xsd: sequence> <xsd: el ement name="bi l l To" t ype="po: addressType"/> <xsd: el ement name="shi pTo" t ype="po: addressType"/> <xsd: el ement name="order"> <xsd: compl exType> <xsd: sequence> <xsd: el ement name="i t em" t ype="i t emType" maxOccurs="unbounded"/> </xsd: sequence> </xsd: compl exType> </xsd: el ement > <xsd: el ement name="t ax" t ype="pri ceType"/> <xsd: el ement name="shi ppi ngAndHandl i ng" t ype="pri ceType"/> <xsd: el ement name="t ot al Cost " t ype="pri ceType"/> </xsd: sequence> <xsd: at t ri but e name="i d" use="requi red" t ype="xsd: posi t i veI nt eger"/> <xsd: at t ri but e name="submit t ed" use="requi red" t ype="xsd: dat e"/> </xsd: compl exType> <xsd: compl exType name="i t emType"> <xsd: compl exCont ent > <xsd: ext ensi on base="po: i t emType"> <xsd: at t ri but e name="uni t Pri ce" use="requi red" t ype="pri ceType"/> </xsd: ext ensi on> </xsd: compl exCont ent > </xsd: compl exType> <xsd: si mpl eType name="pri ceType"> <xsd: rest ri ct i on base="xsd: deci mal "> <xsd: minI ncl usi ve val ue="0"/> </xsd: rest ri ct i on> </xsd: si mpl eType> </xsd: schema>

  By now t he schem a m echanics should be fam iliar. The beginning of t he schem a declares t he purchase order and invoice nam espaces. The purchase order schem a has t o be im port ed because it does not reside in t he sam e nam espace as t he invoice schem a.

  invoiceType po:addressType

  The schem a address t ype is defined in t erm s of , but t he

  order itemType po:itemType

  elem ent 's cont ent is of t ype and not . That 's because t he

  itemType po:itemType unitPrice

  invoice's needs t o ext end and add t he at t ribut e. This happens at t he next com plex t ype definit ion. I n general, t he schem a ext ension synt ax, alt hough som ew hat verbose, is easy t o use:

  <xsd: compl exType name=". . . "> <xsd: compl exCont ent >

  <! - - Opt i onal ext ensi on cont ent model - - > <! - - Opt i onal ext ensi on at t ri but es - - > </xsd: ext ensi on> </xsd: compl exCont ent > </xsd: compl exType>

  The cont ent m odel of ext ended t ypes cont ains all t he child elem ent s of t he base t ype plus any addit ional elem ent s added by t he ext ension. Any at t ribut es in t he ext ension are added t o t he at t ribut e set of t he base t ype. Last but not least , t he invoice schem a defines a sim ple price t ype as a non- negat ive decim al num ber. The definit ion happens via rest rict ion of t he low er bound of t he decim al t ype using t he sam e m echanism int roduced in t he sect ion on sim ple t ypes. The rest rict ion m echanism in schem a applies not only t o sim ple t ypes but also t o com plex t ypes. The synt ax is sim ilar t o t hat of ext ension:

  <xsd: compl exType name=". . . "> <xsd: compl exCont ent > <xsd: rest ri ct i on base=". . . "> <! - - Cont ent model and at t ri but es - - > </xsd: rest ri ct i on> </xsd: compl exCont ent > </xsd: compl exType>

  The concept of rest rict ion has a very precise m eaning in XML Schem a. The declarat ions of t he t ype derived by rest rict ion are very close t o t hose of t he base t ype but m ore lim it ed. There are several possible t ypes of rest rict ions:

  • Multiplicity restrictions

  Deletion of optional element • Tighter limits on occurrence constraints • Providing default values • Providing types where there were none, or narrowing types

  • For exam ple, you can ext end t he address t ype by rest rict ion t o creat e a corporat e address t hat does not include a nam e:

  <xsd: compl exType name="corporat eAddressType"> <xsd: compl exCont ent > <xsd: rest ri ct i on base="addressType"> <xsd: sequence> <! - - Add maxOccurs="0" t o del et e opt i onal name el ement - - > <xsd: el ement name="name" t ype="xsd: st ri ng" minOccurs="0" maxOccurs="0"/> <! - - The rest i s t he same as i n addressType - - > <xsd: el ement name="company" t ype="xsd: st ri ng" minOccurs="0"/> <xsd: el ement name="st reet " t ype="xsd: st ri ng" maxOccurs="unbounded"/> <xsd: el ement name="ci t y" t ype="xsd: st ri ng"/> minOccurs="0"/> <xsd: el ement name="post al Code" t ype="xsd: st ri ng" minOccurs="0"/> <xsd: el ement name="count ry" t ype="xsd: st ri ng" minOccurs="0"/> </xsd: sequence> <xsd: at t ri but e name="i d" t ype="xsd: I D"/> <xsd: at t ri but e name="href " t ype="xsd: I DREF"/> </xsd: rest ri ct i on> </xsd: compl exCont ent > </xsd: compl exType>

  The Importance of xsi:type The nat ure of rest rict ion is such t hat an applicat ion t hat is prepared t o deal w it h t he base t ype can cert ainly accept t he derived t ype. I n ot her w ords, you can use a corporat e

  billTo shipTo

  address t ype direct ly inside t he and elem ent s of purchase orders and invoices w it hout a problem . There are t im es, how ever, w hen it m ight be convenient t o ident ify t he act ual schem a t ype t hat is used in an inst ance docum ent . XML Schem a

  

xsi:type

  allow s t his t hrough t he use of t he global at t ribut e. This at t ribut e can be applied t o any elem ent t o signal it s act ual schem a t ype, as List ing 2.26 shows. Listing 2.26 Using

  xsi:type <?xml versi on="1. 0" encodi ng="UTF- 8"?> <po: po xmlns: po="ht t p: //www. skat est own. com/ns/po" xmlns: xsi ="ht t p: //www. w3. org/2001/XMLSchema- i nst ance" xsi : schemaLocat i on="ht t p: //www. skat est own. com/ns/po ht t p: //www. skat est own. com/schema/po. xsd" i d="43871" submit t ed="2001- 10- 05"> <bi l l To xsi : t ype="po: corporat eAddressType"> <company>The Skat eboard Warehouse</company> <st reet >One Warehouse Park</st reet > <st reet >Bui l di ng 17</st reet > <ci t y>Bost on</ci t y> <st at e>MA</st at e> <post al Code>01775</post al Code> </bi l l To> . . . </po: po> xsi:type

  Alt hough derivat ion by rest rict ion does not require t he use of , derivat ion by ext ension oft en does. The reason is t hat an applicat ion prepared for t he base schem a t ype is unlikely t o be able t o process t he derived t ype ( it adds inform at ion) w it hout a hint . But , why would such a scenario ever occur? Why would an inst ance docum ent cont ain dat a from a t ype derived by ext ension in a place w here a base t ype is expect ed by t he schem a? One reason is t hat XML Schem a allow s derivat ion by ext ension t o be used in cases w here it really should not be used, as in t he case of t he invoice and purchase order dat at ypes.

  xsi:type

  I n t hese cases, m ust be used in t he inst ance docum ent t o ensure successful validat ion. Consider a scenario w here t he invoice t ype w as derived by ext ension from t he purchase order t ype:

  <xsd: compl exType name="i nvoi ceType">

  <xsd: ext ensi on base="po: poType"> <xsd: el ement name="t ax" t ype="pri ceType"/> <xsd: el ement name="shi ppi ngAndHandl i ng" t ype="pri ceType"/> <xsd: el ement name="t ot al Cost " t ype="pri ceType"/> </xsd: ext ensi on> </xsd: compl exCont ent > </xsd: compl exType>

  Rem em ber, ext ension does not change t he cont ent m odel of t he base t ype; it can only

  item

  add t o it . Therefore, t his definit ion w ill m ake t he elem ent inside invoices of t ype

  po:itemType invoice:itemType xsi:type

  , not . The use of ( see List ing 2.27 ) is t he only w ay t o add unit prices t o it em s w it hout violat ing t he validit y const raint s of t he docum ent im posed by t he schem a. An im perfect analogy from program m ing languages is t hat

  xsi:type

  provides t he t rue t ype t o dow ncast t o w hen you are holding a reference t o a base t ype. Listing 2.27 Using xsi:type to Correctly Identify Invoice Item Elements

  <order> <i t em sku="318- BP" quant i t y="5" uni t Pri ce="49. 95" xsi : t ype="i nvoi ce: i t emType"> <descri pt i on>Skat eboard backpack; f i ve pocket s</descri pt i on> </i t em> <i t em sku="947- TI " quant i t y="12" uni t Pri ce="129. 00" xsi : t ype="i nvoi ce: i t emType"> <descri pt i on>St reet - st yl e t i t ani um skat eboard. </descri pt i on> </i t em> <i t em sku="008- PR" quant i t y="1000" uni t Pri ce="0. 00" xsi : t ype="i nvoi ce: i t emType"> <descri pt i on>Promot i onal : Skat esTown st i ckers</descri pt i on> </i t em> </order> xsi:type

  This exam ple show s a use of t hat com es as a result of poor schem a design. I f, inst ead of ext ending purchase order, t he invoice t ype is defined on it s ow n, t he need for

  xsi:type

  disappears. How ever, som et im es even good schem a design does not prevent t he need t o ident ify act ual t ypes in inst ance docum ent s. I m agine t hat , due t o const ant t ypos in shipping and billing address post al codes, Skat esTown decides t o becom e m ore rest rict ive in it s docum ent validat ion. The com pany defines t hree t ypes of addresses t hat can be used in purchase orders and schem a. The t ypes have t he follow ing const raint s:

  • Address — Sam e as alw ays

  \d{ 5} (-\d{ 4}

  • USAddress

  — Count ry is not allow ed, and t he Zip code pat t ern "

  )?

  " is enforced

  [0-9A-Z]{ 3}

  • UKAddress

  — Count ry is fixed t o UK and t he post al code pat t ern "

  [0-9A-Z]{ 3}

  " is enforced To get t he best possible validat ion, Skat esTow n's applicat ions need t o know t he exact

  xsi:type

  t ype of address t hat is being used in a docum ent . Wit hout using , t he purchase order and invoice schem a w ill each have t o define nine ( t hree squared) possible

  billTo shipTo billTo shipTo billTo shipToUS

  com binat ions of and elem ent s: / , / ,

  billTo shipToUK billToUS shipTo billTo

  / , / , and so on. I t is bet t er t o st ick w it h and There's More

  This com plet es t he w hirlw ind t our of XML Schem a. Fort unat ely or unfort unat ely, m uch m at erial useful for dat a- orient ed applicat ions falls out side t he scope of w hat can be addressed in t his chapt er. Som e furt her m at erial w ill be int roduced t hroughout t he rest of t he book as needed.

  Processing XML

  So far, t his chapt er has int roduced t he key XML st andards and explained how t hey are expressed in XML docum ent s. The final sect ion of t he chapt er focuses on processing XML w it h a quick t our of t he specificat ions and API s you need t o know t o be able t o generat e, parse, and process XML docum ent s in your Java applicat ions.

Basic Operations The basic XML processing archit ect ure shown in Figure 2.5 consist s of t hree key layers

  At far left are t he XML docum ent s an applicat ion needs t o w ork w it h. At far right is t he applicat ion. I n t he m iddle is t he infrast ruct ure layer for w orking w it h XML docum ent s, w hich is t he t opic of t his sect ion.

Figure 2.5. Basic XML processing architecture.

  For an applicat ion t o be able t o w ork w it h an XML docum ent , it m ust first be able t o parse it . Parsing is a process t hat involves breaking up t he t ext of an XML docum ent int o sm all ident ifiable pieces ( nodes) . Parsers w ill break docum ent s int o pieces such as st art t ags, end t ags, at t ribut e value pairs, chunks of t ext cont ent , processing inst ruct ions, com m ent s, and so on. These pieces are fed int o t he applicat ion using a w ell- defined API im plem ent ing a part icular parsing m odel. Four parsing m odels are com m only in use:

  Pull parsing involves the application always having to ask the • parser to give it the next piece of information about the document. It is as if the application has to "pull" the information out of the parser and hence the name of the model. The XML community has not yet defined standard APIs for pull parsing. However, because pull parsing is becoming popular, this could happen soon.

  Push parsing — The parser sends notifications to the application

  • about the types of XML document pieces it encounters during the

    parsing process. The notifications are sent in "reading" order, as they appear in the text of the document. Notifications are typically implemented as event callbacks in the application code, and thus push

    parsing is also commonly known as event-based parsing. The XML

    community created a de facto standard for push parsing called Simple

  One-step parsing — The parser reads the whole XML document and •

generates a data structure (a parse tree) describing its entire

contents (elements, attributes, PIs, comments, and so on). The data

structure is typically deeply nested; its hierarchy mimics the

nesting of elements in the parsed XML document. The W3C has defined a Document Object Model (DOM) for XML. The XML DOM specifies the

types of objects that will be included in the parse tree, their

properties, and their operations. The DOM is so popular that one-step parsing is typically referred to as DOM parsing. The DOM is a

language- and platform-independent API. It offers many obvious

benefits but also some hidden costs. The biggest problem with the DOM APIs is that they often do not map well to the native data structures of particular programming languages. To address this issue for Java, the Java community has started working on a Java DOM (JDOM) specification whose goal is to simplify the manipulation of document trees in Java by using object APIs tuned to the common patterns of Java programming. Hybrid parsing — This approach tries to combine different

  • characteristics of the other two parsing models to create efficient

    parsers for special scenarios. For example, one common pattern

    combines pull parsing with one-step parsing. In this model, the

    application thinks it is working with a one-step parser that has

    processed the whole XML document from start to end. In reality, the parsing process has just begun. As the application keeps accessing more objects on the DOM (or JDOM) tree, the parsing continues incrementally so that just enough of the document is parsed at any

    given point to give the application the objects it wants to see.

  The reasons t here are so m any different m odels for parsing XML have t o do w it h t rade- offs bet w een m em ory efficiency, com put at ional efficiency, and ease of program m ing.

Table 2.6 ident ifies som e of t he charact erist ics of t he different parsing m odels. Cont rol of

  parsing refers t o w ho has t o m anage t he st ep- by- st ep parsing process. Pull parsing requires t hat t he applicat ion does t hat . I n all ot her m odels, t he parser w ill t ake care of t his process. Cont rol of cont ext refers t o who has t o m anage cont ext inform at ion such as t he level of nest ing of elem ent s and t heir locat ion relat ive t o one anot her. Bot h push and pull parsing delegat e t his cont rol t o t he applicat ion. All ot her m odels build a t ree of nodes t hat m akes m aint aining cont ext m uch easier. This approach m akes program m ing w it h DOM or JDOM generally easier t han w orking w it h SAX. The price is m em ory and com put at ional efficiency, because inst ant iat ing all t hese obj ect s t akes up bot h t im e and m em ory. Hybrid parsers at t em pt t o offer t he best of bot h w orlds by present ing a t ree view of t he docum ent but doing increm ent al parsing behind t he scenes.

Table 2.6. XML Parsing Models and Their Trade-offs

  Model Control of Control of Memory Computational Ease of Parsing context efficiency efficiency programming Pull Application Application High Highest Low

  Push Parser Application High High Low (SAX) One-step Parser Parser Lowest Lowest High (DOM) One-step Parser Parser Low Low Highest (JDOM) Hybrid Parser Parser Medium Medium High (DOM)

Hybrid Parser Parser Medium Medium Highest (JDOM)

  I n t he Java w orld, a st andardized API —Java API for XML Processing ( JAXP) —exist s for inst ant iat ing XML parsers and parsing docum ent s using eit her SAX or DOM. Wit hout JAXP, Java applicat ions w ere not com plet ely port able across XML parsers because different parsers, despit e following SAX and DOM, had different API s for creat ion, configurat ion, and parsing of docum ent s. JAXP is current ly released in version 1.1. I t does not support JDOM yet because t he JDOM specificat ion is not com plet e at t his point .

  Alt hough XML parsing addresses t he problem of feeding dat a from XML docum ent s int o applicat ions, XML out put addresses t he reverse problem —applicat ions generat ing XML docum ent s. At t he m ost basic level, an applicat ion can direct ly out put XML m arkup. I n

Figure 2.5 , t his is indicat ed by t he applicat ion w orking w it h a charact er st ream . This is

  not very difficult t o do, but handling all t he basic synt ax rules ( at t ribut es quot ing, special charact er escaping, and so on) can becom e cum bersom e. I n m any cases, it m ight be easier for t he applicat ion t o const ruct a dat a st ruct ure ( DOM or JDOM t ree) describing t he

  XML docum ent t hat should be generat ed. Then, t he applicat ion can use a serializat ion process t o t raverse t he docum ent t ree and em it XML m arkup corresponding t o it s elem ent s. This capabilit y is not direct ly defined in t he DOM and JDOM API s, but m ost XML t oolkit s m ake it very easy t o do j ust t hat .

Data-Oriented XML Processing

  When you're t hinking about applicat ions w orking w it h XML, it is im port ant t o not e t hat all t he m echanism s for parsing and generat ing XML described so far are synt ax- orient ed. They force t he applicat ion t o w ork w it h concept s such as elem ent s, at t ribut es, and pieces of t ext . This is sim ilar t o applicat ions t hat use t ext files for st orage being forced t o w ork w it h charact ers, lines, carriage ret urns ( CR) , and line feeds ( LF) . Typically, applicat ions w ant a higher- level view of t heir dat a. They are not concerned w it h t he physical st ruct ure of t he dat a, be it charact ers and lines in t he case of t ext files or elem ent s and at t ribut es in t he case of XML docum ent s. They w ant t o abst ract t his aw ay and expose t he m eaning or sem ant ics of t he dat a. I n ot her w ords, applicat ions do not w ant t o w ork w it h synt ax- orient ed API s, t hey w ant t o w ork w it h dat a- orient ed API s. Therefore, t ypical dat a- orient ed XML applicat ions int roduce a dat a abst ract ion layer bet w een t he synt ax- orient ed parsing and out put API s and applicat ion logic ( see Figure 2.6 ) .

Figure 2.6. Data abstraction layer in XML applications. When w orking w it h XML in a dat a- orient ed m anner, you'll t ypically use one of t w o approaches: operat ion- cent ric and dat a- cent ric. The operat ion- cent ric approach w orks in t erm s of cust om - built API s for cert ain operat ions on t he XML docum ent . The im plem ent at ion of t hese API s hides t he det ails of XML processing. Only non- XML t ypes are passed t hrough t he API s. Consider for exam ple, t he t ask of Skat esTow n t rying t o independent ly check t he t ot al am ount on t he invoices it is sending t o it s cust om ers. From a Java applicat ion perspect ive, a good w ay t o im plem ent an operat ion like t his w ould be t hrough t he int erface show n in List ing 2.28 .

  Listing 2.28 InvoiceChecker Interface

  package com.skat est own. i nvoi ce; i mport j ava. i o. I nput St ream; /**

  • Skat esTown i nvoi ce checker
  • / publ i c i nt erf ace I nvoi ceChecker { /** * Check i nvoi ce t ot al s.
  • @param i nvoi ceXML I nvoi ce XML document
  • @except i on Except i on Any except i on ret urned duri ng checki ng
  • / voi d checkI nvoi ce( I nput St ream i nvoi ceXML) t hrows Except i on; }

  checkInvoice

The act ual im plem ent at ion of w ill have t o do t he follow ing: 1. Obtain an XML parser

  2. Parse the XML from the input stream.

  3. Initialize a running total to zero.

  

4. Find all order items and calculate item subtotals by multiplying

quantities and unit prices. Add item subtotals to the running total.

  5. Add tax to the running total.

  6. Add shipping and handling to the running total.

  7. Compare the running total to the total on invoice.

  8. If there is a difference, throw an exception.

  9. Otherwise, return.

  The m ost im port ant aspect t o t his approach is t hat any XML processing det ails w ill be

  InvoiceChecker

  hidden from t he applicat ion. I t can happily w ork w it h t he int erface,

  checkInvoice never know ing or caring about how does it s w ork. An alt ernat ive is t he dat a- cent ric approach. Dat a- cent ric XML com put ing reduces t he problem of w orking w it h XML docum ent s t o t hat of m apping t he XML t o and from applicat ion dat a and t hen w orking w it h t he dat a ent irely independent of it s XML origins. Applicat ion dat a covers t he com m on dat at ypes developers w ork w it h every day: boolean values, num bers, st rings, dat e- t im e values, arrays, associat ive arrays ( dict ionaries, m aps, hash t ables) , dat abase recordset s, and com plex obj ect t ypes. Not e t hat in t his cont ext , DOM t ree obj ect s w ill not be considered " t rue" applicat ion dat a because t hey are t ied t o XML synt ax. The process of convert ing applicat ion dat a t o XML is called serializat ion. The XML is a serialized represent at ion of t he applicat ion dat a. The process of generat ing applicat ion dat a from XML is called deserializat ion . For exam ple, t he XML invoice m arkup could be m apped t o t he set of Java classes int roduced in t he schem a sect ion ( see List ing 2.29 ) .

  Listing 2.29 Java Classes Representing Invoice Data

  cl ass Address { . . . } cl ass I t em { . . . } cl ass I nvoi ceI t em ext ends I t em { . . . } cl ass I nvoi ce { i nt i d; Dat e submit t ed; Address bi l l To; Address shi pTo; I nvoi ceI t em order[ ] ; f l oat t ax; f l oat shi ppi ngAndHandl i ng; f l oat t ot al Cost ; }

  The t radit ional approach for generat ing XML from applicat ion dat a has been t o sit dow n and cust om - code how dat a values becom e elem ent s, at t ribut es, and elem ent cont ent . The t radit ional approach of w orking w it h XML t o produce applicat ion dat a has been t o parse it using a SAX or a DOM parser. Dat a st ruct ures are built from t he SAX event s or t he DOM t ree using cust om code. There are, how ever, bet t er w ays t o m ap dat a t o and from XML using t echnologies specifically built for serializing and deserializing dat a t o and from XML. Ent er schem a com pilat ion t ools. Schem a com pilers are t ools t hat analyze XML schem a and code- generat e serializat ion and deserializat ion m odules specific t o t he schem a. These m odules w ill w ork w it h dat a st ruct ures t uned t o t he schem a. Figure 2.7 shows t he basic process for working wit h schem a com pilers. The schem a com piler needs t o be invoked only once. Then t he applicat ion can use t he code- generat ed m odules j ust like any ot her API . For exam ple, a schem a com piler w orking on t he Skat esTow n invoice schem a could have generat ed t he helper class shown in List ing 2.30 t o w rap serializat ion and deserializat ion.

Figure 2.7. Using a schema compiler. Listing 2.30 Serialization/Deserialization Helper

  cl ass I nvoi ceXMLHel per { // Al l except i on si gnat ures removed f or readabi l i t y publ i c st at i c I nvoi ceXMLHel per creat e( ) ; publ i c seri al i ze( I nvoi ce i nv, Out put St ream xml) ; publ i c I nvoi ce deseri al i ze( I nput St ream xml) ; } Chapt ers 3 ( " Sim ple Obj ect Access Prot ocol ( SOAP) " ) and 4 ( " Creat ing Web Services" )

  w ill int roduce som e advanced dat a m apping concept s specific t o Web services as w ell as som e m ore sophist icat ed m echanism s for w orking w it h XML. The rest of t his sect ion w ill

  checkInvoice()

  offer a t ast e of XML processing by im plem ent ing t he API described earlier using bot h a SAX and a DOM parser.

  SAX-based checkInvoice

  The basic archit ect ure of t he JAXP SAX parsing API s is show n in Figure 2.8 . I t uses t he com m on abst ract fact ory design pat t ern. First , you m ust creat e an inst ance of

  SAXParserFactory SAXParser

  t hat is used t o creat e an inst ance of . I nt ernally, t he parser

  SAXReader

  w raps a obj ect t hat is defined by t he SAX API . JAXP developers t ypically do

  SAXReader parse()

  not have t o w ork direct ly w it h . When t he parser's m et hod is invoked, t he reader st art s firing event s t o t he applicat ion by invoking cert ain regist ered callbacks.

Figure 2.8. SAX parsing architecture.

Package Description

  SAXParser The

  — Cont ains m et hods for all basic XML parsing event s:

  The follow ing list cont ains t he callback int erfaces and som e of t heir im port ant m et hods:

  DefaultHandler and override the methods they are interested in receiving.

  DefaultHandler implements all SAX callback interfaces with null methods. Custom handlers subclass

  DefaultHandler Not shown in Figure 2.8 ,

  

In general, you pass an XML data source and a

DefaultHandler object to the parser, which processes the XML and invokes the appropriate methods in the handler object.

  SAXParser interface defines several kinds of parse() methods.

  SAXParserFactory object creates an instance of the parser determined by the system property, javax.xml.parsers.SAXParserFactory .

  Working w it h JAXP and SAX involves four im port ant Java packages:

  SAXParserFactory A

  Here is a sum m ary of t he key SAX- relat ed obj ect s:

  SAXParser classes

  Defines the

SAXParserFactory

and

  Defines helper classes such as DefaultHandler javax.xml.parsers

  Defines advanced SAX extensions for DTD processing and detailed syntax information org.xml.sax.helpers

  org.xml.sax Defines the SAX interfaces org.xml.sax.ext

  • ContentHandler
  • Voi d st art Document ( ) Receive notification of the beginning of a document. Voi d endDocument ( ) Receive notification of the end of a document.

    Voi d st art El ement ( St ri ng namespaceURI , St ri ng l ocal Name, St ri ng qName,

  Receive notification of the beginning of an element.

  Voi d charact ers( char[ ] ch, i nt st art , i nt l engt h) Receive notification of character data.

  • ErrorHandler

  — Cont ains m et hods for receiving error not ificat ion. The default

  DefaultHandler

  im plem ent at ion in t hrow s errors for fat al errors but does not hing for non- fat al errors, including validat ion errors:

  • Receive notification of a recoverable error. An example of a recoverable error is a validation error.

  Voi d error( SAXParseExcept i on except i on)

  Voi d f at al Error( SAXParseExcept i on except i on) Receive notification of a non-recoverable error. An example of a non- recoverable error is a well-formedness error.

  • DTDHandler — Cont ains m et hods for dealing w it h XML ent it ies.
  • EntityResolver

  — Cont ains m et hods for resolving t he locat ion of ext ernal ent it ies. SAX defines an event - based parsing m odel. A SAX parser w ill invoke t he callbacks from t hese int erfaces as it is w orking t hrough t he docum ent . Consider t he follow ing sam ple docum ent :

  <?xml versi on="1. 0" encodi ng="UTF- 8"?> <sampl eDoc> <greet i ng>Hel l o, worl d! </greet i ng> </sampl eDoc>

  An event - based parser w ill m ake t he series of callbacks t o t he applicat ion as follow s:

  st art document st art el ement : sampl eDoc st art el ement : greet i ng charact ers: Hel l o, worl d! end el ement : greet i ng end el ement : sampl eDoc end document

  Because of t he sim plicit y of t he parsing m odel, t he parser does not need t o keep m uch st at e inform at ion in m em ory. This is w hy SAX- based parsers are very fast and highly efficient . The flip side t o t his benefit is t hat t he applicat ion has t o m anage any cont ext associat ed w it h t he parsing process. For exam ple, for t he applicat ion t o know t hat t he

  greeting

  st ring " Hello, world! " is associat ed wit h t he elem ent , it needs t o m aint ain a flag t hat is raised in t he st art elem ent event for greet ing and low ered in t he end elem ent event . More com plex applicat ions t ypically m aint ain a st ack of elem ent s t hat are in t he process of being parsed. Here are t he SAX event s w it h an added cont ext st ack:

  st art document ( ) st art el ement : sampl eDoc ( sampl eDoc) st art el ement : greet i ng ( sampl eDoc, greet i ng) charact ers: Hel l o, worl d! ( sampl eDoc, greet i ng) end el ement : greet i ng ( sampl eDoc, greet i ng) end el ement : sampl eDoc ( sampl eDoc)

  Wit h t his inform at ion in m ind, building a class t o check invoice t ot als becom es relat ively sim ple ( see List ing 2.31 ) . Listing 2.31 SAX-based Invoice Checker ( )

  InvoiceCheckerSAX.java package com.skat est own. i nvoi ce; i mport j ava. i o. I nput St ream; i mport org. xml. sax. At t ri but es; i mport org. xml. sax. SAXExcept i on; i mport j avax. xml. parsers. SAXParser; i mport j avax. xml. parsers. SAXParserFact ory; i mport org. xml. sax. hel pers. Def aul t Handl er; /**

  • Check Skat esTown i nvoi ce t ot al s usi ng a SAX parser.
  • / publ i c cl ass I nvoi ceCheckerSAX ext ends Def aul t Handl er i mpl ement s I nvoi ceChecker { // Cl ass- l evel dat a // i nvoi ce runni ng t ot al doubl e runni ngTot al = 0. 0; // i nvoi ce t ot al doubl e t ot al = 0. 0; // Ut i l i t y dat a f or ext ract i ng money amount s f rom cont ent

  bool ean i sMoneyCont ent = f al se; doubl e amount = 0. 0; /** * Check i nvoi ce t ot al s.

  • @param i nvoi ceXML I nvoi ce XML document
  • @except i on Except i on Any except i on ret urned duri ng checki ng
  • / publ i c voi d checkI nvoi ce( I nput St ream i nvoi ceXML) t hrows Except i on { // Use t he def aul t ( non- val i dat i ng) parser SAXParserFact ory f act ory = SAXParserFact ory. newI nst ance( ) ; SAXParser saxParser = f act ory. newSAXParser( ) ; // Parse t he i nput ; we are t he handl er of SAX event s saxParser. parse( i nvoi ceXML, t hi s) ; }

  // SAX Document Handl er met hods publ i c voi d st art Document ( ) t hrows SAXExcept i on { runni ngTot al = 0. 0; t ot al = 0. 0; i sMoneyCont ent = f al se; publ i c voi d endDocument ( ) t hrows SAXExcept i on { // Use del t a equal i t y check t o prevent cumul at i ve // bi nary ari t hmet i c errors. I n t hi s case, t he del t a // i s one hal f of one cent i f ( Mat h. abs( runni ngTot al - t ot al ) >= 0. 005) { t hrow new SAXExcept i on( "I nvoi ce error: t ot al i s " + Doubl e. t oSt ri ng( t ot al ) + " whi l e our cal cul at i on shows a t ot al of " +

Doubl e. t oSt ri ng( Mat h. round( runni ngTot al * 100) / 100. 0) ) ;

} } publ i c voi d st art El ement ( St ri ng namespaceURI , St ri ng l ocal Name, St ri ng qual i f i edName, At t ri but es at t rs) t hrows SAXExcept i on { i f ( l ocal Name. equal s( "i t em") ) { // Fi nd i t em subt ot al ; add i t t o runni ng t ot al runni ngTot al += I nt eger. val ueOf ( at t rs. get Val ue( namespaceURI , "quant i t y") ) . i nt Val ue( ) * Doubl e. val ueOf ( at t rs. get Val ue( namespaceURI , "uni t Pri ce") ) . doubl eVal ue( ) ; } el se i f ( l ocal Name. equal s( "t ax") || l ocal Name. equal s( "shi ppi ngAndHandl i ng") || l ocal Name. equal s( "t ot al Cost ") ) { // Prepare t o ext ract money amount i sMoneyCont ent = t rue; } } publ i c voi d endEl ement ( St ri ng namespaceURI , St ri ng l ocal Name, St ri ng qual i f i edName) t hrows SAXExcept i on { i f ( i sMoneyCont ent ) { i f ( l ocal Name. equal s( "t ot al Cost ") ) { t ot al = amount ; } el se { // I t must be t ax or shi ppi ngAndHandl i ng runni ngTot al += amount ; } i sMoneyCont ent = f al se; } } publ i c voi d charact ers( char buf [ ] , i nt of f set , i nt l en) t hrows SAXExcept i on {

  St ri ng val ue = new St ri ng( buf , of f set , l en) ; amount = Doubl e. val ueOf ( val ue) . doubl eVal ue( ) ; } } } InvoiceCheckerSAX InvoiceChecker

  m ust im plem ent t he int erface in order t o provide

  checkInvoice DefaultHandler

  t he funct ionalit y. I t also subclasses t o obt ain default im plem ent at ions for all SAX callbacks. I n t his w ay t he im plem ent at ion can focus on overriding only t he relevant callbacks.

  runningTotal total

  The class m em bers and m aint ain st at e inform at ion about t he

  isMoneyContent amount

  invoice during t he parsing process. The class m em bers and are necessary in order t o m aint ain parsing cont ext . Because event s about charact er dat a are independent of event s about elem ent s, w e need a flag t o indicat e w het her w e should

  tax shippingAndHandling

  at t em pt t o parse charact er dat a as a dollar am ount for t he , ,

  totalCost isMoneyContent

  and elem ent s. This is w hat does. Aft er w e parse t he t ext int o

  amount

  a dollar figure, w e save it int o t he m em ber variable and w ait unt il t he

  endElement() callback t o det erm ine w hat t o do w it h it . checkInvoice()

  The m et hod im plem ent at ion show s how easy it is t o use JAXP for XML parsing. Parsing an XML docum ent w it h SAX only t akes t hree lines of code. At t he beginning of t he docum ent , w e have t o init ialize all m em ber variables. At t he end of t he docum ent , w e check w het her t here is a difference bet w een t he running t ot al and t he t ot al cost list ed on t he invoice. I f t here is a problem , w e t hrow an except ion w it h a descript ive m essage. Not e t hat w e cannot use an equalit y check because no exact m apping exist s bet w een decim al num bers and t heir binary represent at ion. During t he

  runningTotal m any addit ions t o , a very t iny error w ill be int roduced in t he calculat ion.

  So, inst ead of checking for equalit y, w e need t o check w het her t he difference bet w een t he list ed and t he calculat ed t ot als is significant . Significant in t his case w ould be any am ount great er t han half a cent , because a half- cent difference can affect t he rounding of a final value t o a cent .

  startElement()

  The parser pushes event s about t he new elem ent s t o t he m et hod. I f t he

  item

  elem ent w e get a not ificat ion about is an elem ent , w e can im m ediat ely ext ract t he

  quantity unitPrice values of t he and at t ribut es from it s at t ribut es collect ion.

  Mult iplying t hem t oget her creat es an it em subt ot al, w hich w e add t o t he running t ot al.

  tax shippingAndHandling totalCost

  Alt ernat ively, if t he elem ent is one of , , or , we prepare t o ext ract a m oney am ount from it s t ext cont ent . All ot her elem ent s are sim ply ignored. We only care t o process end elem ent not ificat ions if w e w ere expect ing t o ext ract a m oney am ount from t heir cont ent . Based on t he nam e of t he elem ent , w e decide w het her t o save t he am ount as t he t ot al cost of t he invoice or w het her t o add it t o t he running t ot al.

  When w e process charact er dat a and w e are expect ing a dollar value, w e ext ract t he

  amount

  elem ent cont ent , convert it t o a double value, and save it in t he class m em ber for

  endElement() use by t he callback. endElement()

  Not e t hat w e could have skipped im plem ent ing alt oget her if w e had also st ored t he elem ent nam e as a st ring m em ber of t he class or used an enum erat ed value.

  characters() Then, w e w ould have decided how t o use t he dollar am ount right inside .

  That 's all t here is t o it . Of course, t his is a very sim ple exam ple. A real applicat ion w ould have done at least t w o t hings different ly:

  It would have used namespace information and prefixed element names • instead of simply using local names. It would have defined its own exception type to communicate invoice • validation information. It would have also overridden the default callbacks for error() and fatalError() and used these to collect better exception information.

  Unfort unat ely, t hese ext ensions fall out side t he scope of t his chapt er. The rest of t he book has several exam ples of building robust XML processing soft w are.

  DOM-based checkInvoice

  The basic archit ect ure of t he JAXP DOM parsing API s is show n in Figure 2.9 . I t uses t he sam e fact ory design pat t ern as t he SAX API . An applicat ion w ill use t he

  javax.xml.parsers.DocumentBuilderFactory DocumentBuilder

  class t o get a obj ect inst ance, and use t hat t o produce a docum ent t hat conform s t o t he DOM specificat ion.

  javax.xml.parsers.DocumentBuilderFactory

  The value of t he syst em propert y det erm ines w hich fact ory im plem ent at ion w ill produce t he builder. This is how JAXP enables applicat ions t o w ork w it h different DOM parsers.

Figure 2.9. DOM parsing architecture.

  The im port ant packages for w orking w it h JAXP and DOM are as follow s:

Package Description

  org.w3c.dom Defines the DOM programming interfaces for XML (and, optionally, HTML) documents, as specified by the W3C javax.xml.parsers DocumentBuilder DocumentBuilderFactory

Defines and classes

  The DOM defines API s t hat allow applicat ions t o navigat e XML docum ent s and t o m anipulat e t heir cont ent and st ruct ure. The DOM defines int erfaces, not a part icular im plem ent at ion. These int erfaces are specified using t he I nt erface Descript ion Language ( I DL) so t hat any language can define bindings for t hem . Separat e Java bindings are provided t o m ake w orking w it h t he DOM in Java very easy.

  The DOM has several levels and various facet s w it hin a level. I n t he fall of 1998, DOM Level 1 w as released. I t provided t he basic funct ionalit y t o navigat e and m anipulat e XML and HTML docum ent s. DOM Level 2 builds upon Level 1 w it h m ore and bet t er- segm ent ed funct ionalit y:

  The DOM Level 2 Core API builds upon Level 1, fixes some problem • spots, and defines additional ways to navigate and manipulate the

content and structure of documents. These APIs also provide full

support for namespaces.

  The DOM Level 2 Views API specifies interfaces that provide

  • programmers with the ability to view alternate presentations of the XML or HTML document. The DOM Level 2 Style API specifies interfaces that provide • programmers with the ability to dynamically access and manipulate style sheets. The DOM Level 2 Events API specifies interfaces that provide • programmers with a generic event sys
  • The DOM Level 2 Traversal-Range API specifies interfaces that provide

  programmers with the ability to traverse a representation of the XML document.

The DOM Level 2 HTML API specifies interfaces that provide • programmers with the ability to work with HTML documents

  All int erfaces apart from t he core ones are opt ional. This is t he m ain reason w hy m ost applicat ions choose t o rely ent irely on t he DOM Core. You can expect m ore of t he DOM t o be support ed by parsers soon. I n fact , t he W3C is current ly w orking on DOM Level 3. The DOM originat ed as an API for XML processing at a t im e when t he m aj orit y of XML applicat ions w ere docum ent - cent ric. As a result , t he int erfaces in t he DOM describe fairly low - level synt ax const ruct s in XML docum ent s. This m akes w orking w it h t he DOM for dat a- orient ed applicat ions som ew hat cum bersom e, and is one of t he reasons t he Java com m unit y is w orking on t he JDOM API s. To bet t er underst and t he XML DOM, you need t o underst and t he core int erfaces and t he m ost significant m et hods in t hem . Figure 2.10 show s a Universal Modeling Language ( UML) diagram describing som e of t hese.

Figure 2.10. Key DOM interfaces and operations. Node

  The root int erface is . I t cont ains m et hods for w orking w it h t he node nam e

  

getNodeName() getNodeType() getNodeAttributes() Node

( ) , t ype ( ) , and at t ribut es ( ) .

  t ypes cover various possible XML synt ax elem ent s: docum ent , elem ent , at t ribut es, charact er dat a, t ext node, com m ent , processing inst ruct ion, and so on. All of t hese are

  Node

  shown in subclass but not all are show n in Figure 2.10 . To t raverse t he docum ent

  getParentNode()

  hierarchy, nodes can access t heir parent ( ) as w ell as t heir children

  getChildNodes() Node

  ( ) . also has several convenience m et hods for ret rieving t he first and last child as w ell as t he previous and follow ing sibling.

  Document

  The m ost im port ant operat ions in involve creat ing nodes ( at least one for every node t ype) , assem bling t hese nodes int o t he t ree ( not show n) , and locat ing elem ent s by

  getElementsByTagName()

  nam e, regardless of t heir locat ion in t he DOM ( ) . This last API is very convenient because it can save you from having t o t raverse t he t ree t o get t o a

  part icular node. The rest of t he int erfaces on t he figure are very sim ple. Elem ent s, at t ribut es, and charact er dat a offer a few m et hods each for get t ing and set t ing t heir dat a m em bers. NodeList NamedNodeMap and are convenience int erfaces for dealing w it h collect ions of nodes and at t ribut es, respect ively. What Figure 2.10 does not show is t hat DOM Level 2 is fully nam espace aw are and all DOM API s have versions t hat t ake in nam espace URI s. Typically, t heir nam e is t he sam e as t he nam e of t he original API w it h NS appended, such

  Element getAttributeNS(String nsURI, String localName)

  as 's . Wit h t his inform at ion in m ind, building a class t o check invoice t ot als becom es relat ively

  

InvoiceChecker

sim ple. The DOM im plem ent at ion of is show n in List ing 2.32 .

  Listing 2.32 DOM-based Invoice Checker ( )

  InvoiceCheckerDOM.java package com.skat est own. i nvoi ce; i mport j ava. i o. I nput St ream; i mport org. w3c. dom.Node; i mport org. w3c. dom.NodeLi st ; i mport org. w3c. dom.Document ; i mport org. w3c. dom.El ement ; i mport org. w3c. dom.Charact erDat a; i mport j avax. xml. parsers. Document Bui l der;

  /** * Check Skat esTown i nvoi ce t ot al s usi ng a DOM parser.

  • / publ i c cl ass I nvoi ceCheckerDOM i mpl ement s I nvoi ceChecker { /** * Check i nvoi ce t ot al s.
  • @param i nvoi ceXML I nvoi ce XML document
  • * @except i on Except i on Any except i on ret urned duri ng checki ng

  • / publ i c voi d checkI nvoi ce( I nput St ream i nvoi ceXML) t hrows Except i on { // I nvoi ce runni ng t ot al doubl e runni ngTot al = 0. 0; // Obt ai n parser i nst ance and parse t he document Document Bui l derFact ory f act ory = Document Bui l derFact ory. newI nst ance( ) ;

  Document Bui l der bui l der = f act ory. newDocument Bui l der( ) ; Document doc = bui l der. parse( i nvoi ceXML) ; // Cal cul at e order subt ot al NodeLi st i t emLi st = doc. get El ement sByTagName( "i t em") ; f or ( i nt i = 0; i < i t emLi st . get Lengt h( ) ; i ++) { // Ext ract quant i t y and pri ce El ement i t em = ( El ement ) i t emLi st . i t em(i ) ; I nt eger qt y = I nt eger. val ueOf ( i t em.get At t ri but e( "quant i t y") ) ; Doubl e pri ce = Doubl e. val ueOf ( i t em.get At t ri but e( "uni t Pri ce") ) ; // Add subt ot al t o runni ng t ot al runni ngTot al += qt y. i nt Val ue( ) * pri ce. doubl eVal ue( ) ; } // Add t ax Node nodeTax = doc. get El ement sByTagName( "t ax") . i t em(0) ; runni ngTot al += doubl eVal ue( nodeTax) ; // Add shi ppi ng and handl i ng Node nodeShi ppi ngAndHandl i ng =

doc. get El ement sByTagName( "shi ppi ngAndHandl i ng") . i t em(0) ;

runni ngTot al += doubl eVal ue( nodeShi ppi ngAndHandl i ng) ; // Get i nvoi ce t ot al Node nodeTot al Cost = doc. get El ement sByTagName( "t ot al Cost ") . i t em(0) ;

  // Use del t a equal i t y check t o prevent cumul at i ve // bi nary ari t hmet i c errors. I n t hi s case, t he del t a // i s one hal f of one cent i f ( Mat h. abs( runni ngTot al - t ot al ) >= 0. 005) { t hrow new Except i on( "I nvoi ce error: t ot al i s " + Doubl e. t oSt ri ng( t ot al ) + " whi l e our cal cul at i on shows a t ot al of " + Doubl e. t oSt ri ng( Mat h. round( runni ngTot al * 100) / 100. 0) ) ; } } /**

  • Ext ract a doubl e f rom t he t ext cont ent of a DOM node.
  • @param node A DOM node wi t h charact er cont ent .
  • @ret urn The doubl e represent at i on of t he node' s cont ent .
  • @except i on Except i on Coul d be t he resul t of ei t her a node
  • t hat does not have t ext cont ent bei ng passed i n * or a node whose t ext cont ent i s not a number.
  • / pri vat e doubl e doubl eVal ue( Node node) t hrows Except i on { // Get t he charact er dat a f rom t he node and parse i t St ri ng val ue = ( ( Charact erDat a) node. get Fi rst Chi l d( ) ) . get Dat a( ) ; ret urn Doubl e. val ueOf ( val ue) . doubl eVal ue( ) ; } }

  InvoiceCheckerDOM InvoiceChecker

  m ust im plem ent t he int erface in order t o provide

  checkInvoice

  t he funct ionalit y. Apart from t his, it is a st andalone class. Also, not e t hat t he class has no m em ber dat a, because t here is no need t o m aint ain parsing cont ext . The cont ext is im plicit in t he hierarchy of t he DOM t ree t hat w ill be t he result of t he parsing process.

  The fact ory pat t ern used here t o parse t he invoice is t he sam e as t he one from t he SAX

  DocumentBuilderFactory DocumentBuilder im plem ent at ion; it j ust uses and inst ead.

  Alt hough t he SAX parse m et hod ret urns no dat a ( it st art s firing event s inst ead) , t he DOM

  parse() Document

  m et hod ret urns a obj ect t hat holds t he com plet e parse t ree of t he invoice docum ent .

  getElementsByTagName("item")

  Wit hin t he parse t ree, t he call t o ret rieves a node list of

  quantity unitPrice

  all order it em s. The loop it erat es over t he list , ext ract ing t he and at t ribut es for every it em , obt aining an it em subt ot al, and adding t his t o t he running t ot al.

  getElementsByTagName()

  The sam e API com bined w it h t he ut ilit y funct ion

  doubleValue()

  ext ract s t he am ount s of t ax, t he shipping and handling, and t he invoice t ot al cost . Just as in t he SAX exam ple, t he code has t o use a difference check inst ead of a direct equalit y check t o guard against inexact decim al- t o- binary conversions. The class also defines a convenient ut ilit y funct ion t hat t akes in a DOM node t hat should have only charact er cont ent and ret urns t he num eric represent at ion of t hat cont ent as a double. Any non- t rivial DOM processing w ill t ypically require t hese t ypes of ut ilit y funct ions. I t goes t o prove t hat t he DOM is very synt ax- orient ed and not at all concerned about dat a. That 's all t here is t o it . Of course, t his is a very sim ple exam ple and, j ust as in t he SAX exam ple, a real applicat ion w ould have done at least t hree t hings different ly:

  It would have used namespace information and prefixed element names • instead of simply using local names. It would have defined its own exception type to communicate invoice

  • validation information. It would have implemented try-catch logic

  checkInvoice inside the method in order to report more meaningful errors.

  It would have either explicitly turned on validation of the incoming •

  XML document or traversed the DOM tree step-by-step from the document root to all the elements of interest. Using getElementsByTagName() presumes that the structure of the document (relative positions of elements) has already been validated. If this is the case, it is OK

to ask for all item elements regardless of where they are in the

document. The example implementation took this approach for code

readability purposes.

  These changes are not com plex, but t hey w ould have increased t he size and com plexit y of t he exam ple beyond it s goals as a basic int roduct ion t o DOM processing.

  Testing the Code

  Rat her t han forcing you t o set up t he Java Runt im e Environm ent ( JRE) , m odify

  CLASSPATH

  environm ent variables, and run exam ples from t he com m and line, t his book has t aken a novel, Web- cent ric approach. All exam ples are accessible from t he book's exam ple Web sit e. The act ual exam ple code is w rit t en using Java Server Pages ( JSP) . JSP allow s Java code t o be m ixed in w it h HTML for building Web applicat ions. JSP builds on t op of t he Java servlet st andard for building Web com ponent s. Java applicat ion servers com pile JSPs dow n t o servlet s.

  InvoiceCheckerSAX InvoiceCheckerDOM

  The exam ple code t hat drives and appears in List ing 2.33 . Listing 2.33 JSP Page for Checking Invoices ( )

  /ch2/ex1/index.jsp <%@ page i mport ="j ava. i o. *, bws. BookUt i l , com.skat est own. i nvoi ce. *" %> <HTML> <HEAD><TI TLE>I nvoi ce Checker</TI TLE></HEAD> <h1>I nvoi ce Checker</h1> <p>Thi s exampl e i mpl ement s a web f orm dri ver f or Skat esTowns' s i nvoi ce checker. You can modi f y t he i nvoi ce on t he f orm i f you wi sh ( t he def aul t one i s f rom Chapt er 2) , sel ect a DOM or SAX parser and perf orm a check on t he i nvoi ce t ot al . </p>

  <% St ri ng xml = request . get Paramet er( "xml") ; i f ( xml == nul l ) { xml = BookUt i l . readResource( appl i cat i on, "/resources/sampl eI nvoi ce. xml") ; } %> <TEXTAREA NAME="xml" ROWS="20" COLS="90"><%= xml%></TEXTAREA> <P></P> Sel ect parser t ype: <I NPUT t ype="RADI O" name="parserType" val ue="SAX" CHECKED> SAX <I NPUT t ype="RADI O" name="parserType" val ue="DOM"> DOM <P></P> <I NPUT t ype="SUBMIT" val ue=" Check I nvoi ce"> </FORM> <% // Check f or f orm submissi on i f ( request . get Paramet er( "xml") ! = nul l ) { out . pri nt l n( "<HR>") ; // I nst ant i at e appropri at e parser t ype I nvoi ceChecker i c; i f ( request . get Paramet er( "parserType") . equal s( "SAX") ) { out . pri nt ( "Usi ng SAX parser. . . <br>") ; i c = new I nvoi ceCheckerSAX( ) ; } el se { out . pri nt ( "Usi ng DOM parser. . . <br>") ; i c = new I nvoi ceCheckerDOM() ; } // Check t he i nvoi ce t ry { i c. checkI nvoi ce( new St ri ngBuf f erI nput St ream(xml) ) ; out . pri nt ( "I nvoi ce checks OK. ") ; } cat ch( Except i on e) { out . pri nt ( e. get Message( ) ) ; } } %> </BODY> </HTML>

  <%@ ... %> page import="..."

  JSP uses t he synt ax for com pile- t im e direct ives. The

  import direct ive accom plishes t he equivalent of a Java st at em ent .

  The HTML code set s up a sim ple Web form t hat w ill post back t o t he sam e page. The form cont ains a t ext area w it h t he nam e xm l t hat w ill cont ain t he XML of t he invoice t o be validat ed.

  <% ... %>

  I n JSP, you can use t he const ruct t o surround arbit rary Java code em bedded in t he JSP page. The request obj ect is an im plicit obj ect on t he page associat ed w it h t he Web request . I m plicit obj ect s in JSP are set up by t he JSP com piler. They can be used w it hout requiring any t ype of declarat ion or set up. One of t he m ost useful m et hods of t he

  getParameter()

  request obj ect is , w hich ret rieves t he value of a param et er passed from t he Web such as a form field or ret urns null if t his param et er did not com e w it h t he

  getParameter("xml")

  request . The code uses t o check w het her t he form is being displayed ( ret urn is null) versus subm it t ed ( ret urn is non- null) . I f t he form is displayed for t he first t im e, t he page loads t he invoice XML from a sam ple file in

  /resources/sampleInvoice.xml .

  The rest of t he Java code runs only if t he form has been subm it t ed. I t uses t he im plicit

  out parserType

  obj ect t o send out put t o t he result ing Web page. I t uses t he value of t he field in t he Web page t o det erm ine w het her t o inst ant iat e a SAX or a DOM parser. I t t hen

  xml

  checks t he invoice by passing t he value of t he t ext area on t he page t o t he

  checkInvoice()

  m et hod. I f t he call is successful, t he invoice checks OK, and an

  checkInvoice()

  appropriat e m essage is displayed. I f an except ion is t hrow n by , an invoice t ot al discrepancy ( or an XML processing error) has been det ect ed, w hich w ill be out put t o t he brow ser. That 's all t here is t o creat ing a Web t est client for t he invoice checker. Figure 2.11 shows t he Web page ready for subm ission.

Figure 2.11. Invoice checker Web page.

  Summary

  This chapt er has focused on explaining som e of t he core feat ures of XML and relat ed t echnologies. The goal w as t o prepare you for t he Web service–relat ed m at erial in t he rest of t he book, w hich relies heavily on t he concept s present ed here. To t his end, w e covered, in som e det ail:

  The origins of XML and the fundamental difference between document- • example of data-centric XML use. The material in this chapter purposefully ignored some aspects of XML that are more document- oriented. The syntax and rules governing the physical structure of XML

  • documents: document prologs, elements, attributes, character content,

    CDATA sections, and so on. We omitted document-oriented features of

  XML such as entities and notations due to their infrequent use in the context of Web services. The SkatesTown purchase order document format made its initial appearance.

  • XML Namespaces, the key tool for resolving the problems of name

    recognition and name collision in XML applications. Namespaces are

    fundamental to mixing information from multiple schemas into a single document, something that all core Web service technologies rely upon. SkatesTown's purchase order inside an XML message wrapper is an example of a common pattern for XML use that will be explored in depth in the next chapter. The namespace mechanism is simple and

    beautiful; however, people often try to read more into it than is

    really there, as demonstrated by the debate over whether namespace

    URIs should point to meaningful resources. One of the slightly more

    complex aspects of the specification is the multiple namespace defaulting mechanisms that simplify document markup while preserving namespace information. The concepts of well-formedness and validity and Document Type • Definitions (DTDs) as a mechanism to validate XML document structure.

    DTDs are powerful, but they also have great limitations such as non-

  

XML syntax, no ties to namespaces, and poor support for even basic

data types such as numbers and dates.

  XML Schema, the de facto standard for describing document structure • and XML datatypes for data-oriented applications. Although XML Schema

is a recent standard, the XML community had defined specifications

based on draft versions of the standard for nearly two years. The

flexible content models, the large number of pre-defined datatypes

and the powerful extensibility and reuse features make this one of

the most important developments in the XML space since XML 1.0. All

Web service specifications are described using schema. Through the

definition of SkatesTown's purchase order and invoice schemas, this

  • Starting with the basic syntax-oriented XML processing architecture, the chapter progressed to define a data-oriented XML processing

  XML parsing. In the context of SkatesTown's desire to independently validate invoice totals sent to its customers, we used the Java APIs for XML Processing (JAXP), the Simple APIs for XML (SAX), and the XML Document Object Model (DOM) to build two separate implementations of an invoice checker. A simple Web-based front end served as the test bed for the code.

  This chapt er explicit ly did not focus on ot her im port ant but not very relevant XML t echnologies such as XPoint er/ XLink, Resource Definit ion Fram ew ork ( RDF) , XPat h, Ext ensible St ylesheet Language Transform at ions ( XSLT) , or XQuery. They are im port ant in t heir ow n dom ains and useful t o be fam iliar w it h in general but are not com m only used in t he cont ext of Web services. Ot her m ore t echnical XML specificat ion such as XML Digit al Signat ures w ill be int roduced lat er in t he book as part of m eaningful Web service usage scenarios.

  Right now , you know enough about XML t o go deep int o t he excit ing w orld of Web services. Chapt er 3 int roduces t he core Web service m essaging t echnologies: Sim ple Obj ect Access Prot ocol ( SOAP) and XML Prot ocol ( XMLP) .

Resources

  • DOM Level 1—DOM Level 1 Specificat ion ( W3C, Oct ober 1998) . Available at ht t p: / / w w w .w 3.org/ TR/ REC- DOM- Level- 1 .
  • DOM Level 2 Core—W3C ( World Wide Web Consort ium ) Docum ent Obj ect Model Level 2 Core ( W3C, Novem ber 2000) . Available at ht t p: / / w w w .w 3.org/ TR/ 2000/ REC- DOM- Level- 2- Core- 20001113 .
  • JAXP—Java API for XML Processing 1.1 ( Sun Microsyst em s, I nc., February 2001) . Available at ht t p: / / j ava.sun.com / xm l/ xm l_j axp.ht m l .
  • JDOM—Java Docum ent Obj ect Model. Available at ht t p: / / w w w .j dom .org/ docs/ apidocs .
  • JSP—Java Server Pages 1.2 ( Sun Microsyst em s, I nc., April 2001) . Available at ht t p: / / j ava.sun.com / product s/ j sp .
  • RFC2396—RFC 2396, " Uniform Resource I dent ifiers ( URI ) : Generic Synt ax" ( I ETF, August 1998) . Available at ht t p: / / w w w .iet f.org/ rfc/ rfc2396.t xt .
  • SAX—Sim ple API for XML ( SAX) 2.0 ( May 2000) . Available at ht t p: / / w w w .m egginson.com / SAX/ Java/ index.ht m l .
  • XML—Ext ensible Markup Language ( XML) 1.0, 2nd ed. ( W3C, August 2000) . Available at ht t p: / / w w w .w 3.org/ TR/ 2000/ WD- xm l- 2e- 20000814 .
  • XML Nam espaces" Nam espaces in XML" ( W3C, January 1999) . Available at ht t p: / / w w w .w 3.org/ TR/ 1999/ REC- xm l- nam es- 19990114 .
  • XML Schem a Part 0: Prim er" XML Schem a Part 0: Prim er" ( W3C, May 2001) . Available at ht t p: / / w w w .w 3.org/ TR/ 2001/ REC- xm lschem a- 0- 20010502 .
  • XML Schem a Part 1: St ruct ures" XML Schem a Part 1: St ruct ures" ( W3C, May 2001) . Available at ht t p: / / w w w .w 3.org/ TR/ 2001/ REC- xm lschem a- 1- 20010502 .
  • XML Schem a Part 2: Dat at ypes" XML Schem a Part 2: Dat at ypes" ( W3C, May 2001) . Available at ht t p: / / w w w .w 3.org/ TR/ 2001/ REC- xm lschem a- 2- 20010502 .
  • Inventory Check Web Service • SOAP Envelope Framework &b
  • Taking Advantage of SOAP Extensibility

  SOAP Intermediaries • Error Handling in SOAP

  • SOAP Data Encoding • Architecting Distributed Systems with Web Services • Purchase Order Submission Web Service • SOAP Protocol Bindings •

  There is a lot m ore t o Web services t han Sim ple Obj ect Access Prot ocol ( SOAP) . Chapt er

  

1 , " Web Services Overview ," int roduced t he Web services int eroperabilit y st ack t hat w ent

  several levels higher t han SOAP. SOAP is synonym ous w it h Web services, how ever, because since it s int roduct ion in lat e 1999, it has becom e t he de fact o st andard for Web services m essaging and invocat ion. Wit h com pet it ive and m arket pressures driving t he Web services indust ry in a hard race t o provide m eaningful solut ions t o cross- ent erprise int egrat ion problem s, SOAP is t he go- t o- m arket t echnology of choice.

  What is SOAP all about , you ask? Will it save you from failure ( and keep you clean) w hile you t oil 80- hour w ork w eeks on a business- t o- business ( B2B) int egrat ion proj ect from hell? Will it support your ext ensibilit y needs as requirem ent s change, and provide you w it h int eroperabilit y across m ult i- vendor offerings? Will it be t he keyw ord on your resum e t hat w ill guarant ee you a big raise as you sw it ch j obs? I n short , is it t he new new t hing? Well, m aybe.

  SOAP is so sim ple and so flexible t hat it can be used in m any different ways t o fit t he needs of different Web service scenarios. This is bot h a blessing and a curse. I t is a blessing because chances are t hat SOAP can fit your needs. I t is a curse because you probably w on't know how t o m ake it do t hat . This is w here t his chapt er com es in. When you are t hrough w it h it , you w ill know not only how t o use SOAP st raight out of t he box, but also how t o ext end SOAP in m ult iple w ays t o support your diverse and changing needs. You w ill also have applied design best pract ices t o build several m eaningful e- com m erce Web services for our favorit e com pany, Skat esTow n. Last but not least , you w ill be ready t o handle t he rest of t he book and clim b st ill higher t ow ard t he t op of t he Web services int eroperabilit y st ack. To t his end, t he chapt er w ill discuss t he follow ing t opics:

  • The evolution of XML protocols and the history and motivation behind

  SOAP's creation The SOAP envelope framework, complete with discussions of versioning, • header-based vertical extensibility, intermediary-based horizontal extensibility, error handling, and bindings to multiple transport protocols The various mechanisms for packaging information in SOAP messages, • including SOAP's own data-encoding rules and a number of heuristics for putting just about any kind of data in SOAP messages The use of SOAP within multiple distributed system architectures such • as RPC-and messaging-based systems in all their flavors

Building and consuming Web services using the Java-based Apache Axis • Web services engine

  One final not e before w e begin. The SOAP 1.1 specificat ion is slight ly over 40 pages long. This chapt er is not iceably longer, because t he purpose of t his book is t o be som et hing m ore t han an annot at ed spec or a t ut orial for building Web services. We've t ried hard t o creat e a t horough t reat m ent of Web services for people w ho w ant answ ers t o quest ions t hat begin not only w it h " w hat " and " how " but also wit h " why." To becom e an expert at Web services, you need t o be com fort able dealing w it h t he lat t er t ype of quest ions. We are here t o help.

  So, w hy SOAP? As t his chapt er w ill show , SOAP is sim ple, flexible, and highly ext ensible. Because it is XML based, SOAP is program m ing language, plat form , and hardw are neut ral. What bet t er choice for t he XML prot ocol t hat is t he foundat ion of Web services? To prove t his point , let 's st art t he chapt er by looking at som e of t he earlier w ork t hat inspired SOAP.

  Evolution of XML Protocols

  The enabling t echnology behind Web services is built around XML prot ocols

  XML prot ocols govern how com m unicat ion happens and how dat a is represent ed in XML form at on t he w ire. XML prot ocols can be broadly classified int o t w o generat ions. First - generat ion prot ocols are based purely on XML 1.0. Second- generat ion prot ocols t ake advant age of bot h XML Nam espaces and XML Schem a. SOAP is a second- generat ion XML prot ocol.

First-Generation XML Protocols

  There were m any int erest ing first - generat ion XML prot ocol effort s. They inform ed t he com m unit y of im port ant prot ocol requirem ent s and part icular approaches t o sat isfying t hese requirem ent s. Unfort unat ely, very few of t he first - generat ion XML prot ocols achieved m ult i- vendor support and broad adopt ion. Tw o are w ort h m ent ioning: Web Dist ribut ed Dat a Exchange ( WDDX) and XML- RPC. WDDX WDDX provides a language- and plat form - neut ral m echanism for dat a exchange bet w een applicat ions. WDDX is perfect for dat a syndicat ion and rem ot e B2B int egrat ion

  Technologies, t he Web feed com pany, exposes all it s cont ent t hrough a WDDX- based rem ot e API . Access ht t p: / / m oreover.com / cgi- local/ page?index+ w ddx w it h an XML- aw are brow ser such as I nt ernet Explorer and you w ill get a WDDX packet w it h current headline new s. A sim plified version of t he packet is show n in t he follow ing exam ple. You can see from it t hat t he dat a form at is a recordset ( t abular dat a) w it h t hree fields cont aining t he URL t o t he full art icle, it s headline t ext , and t he publishing source:

  <wddxPacket versi on="1. 0"> <header/> <dat a> <recordset rowCount ="2" f i el dNames="url , headl i ne_t ext , source"> <f i el d name="url "> <st ri ng>ht t p: //c. moreover. com/cl i ck/here. pl ?x22535276</st ri ng> <st ri ng>ht t p: //c. moreover. com/cl i ck/here. pl ?x22532205</st ri ng> </f i el d> <f i el d name="headl i ne_t ext "> <st ri ng>Fi ref i ght ers hol d l i ne i n Wyoming</st ri ng> <st ri ng>US upbeat as Chi na t ensi ons ease</st ri ng> </f i el d> <f i el d name="source"> <st ri ng>CNN</st ri ng> <st ri ng>BBC</st ri ng> </f i el d> </recordset > </dat a> </wddxPacket >

  Allaire Corporat ion ( now Macrom edia, I nc.) creat ed WDDX in 1998. WDDX is current ly support ed in m any environm ent s and is flexible enough t o handle m ost useful dat at ypes ( st rings, num bers, booleans, dat e/ t im e, binary, arrays, st ruct ures, and recordset s) , but it cannot represent arbit rary dat a in XML. I t is an epit om e of t he 80/ 20 rule: flexible enough t o be useful yet sim ple enough t o be broadly support ed. Because WDDX is not bound t o any part icular t ransport , applicat ions can exchange WDDX packet s via HTTP, over e- m ail, or by any ot her m eans. Many applicat ions persist dat a as XML in a relat ional dat abase using WDDX.

  XML-RPC

  XML- RPC is an RPC prot ocol int roduced in t he m arket in 1998 by Userland. XML- RPC support s a set of dat at ypes sim ilar t o t hat support ed by WDDX and uses HTTP as t he underlying t ransport prot ocol. Because of it s sim plicit y, XML- RPC enj oyed good m ult i- vendor support . Here's an exam ple XML- RPC m et hod call and response:

  <met hodCal l > <met hodName>NumberToText </met hodName> <params> <param> <val ue><i 4>28</i 4></val ue> </param> </params> </met hodCal l > . . . <met hodResponse>

  <param> <val ue><st ri ng>t went y- ei ght </st ri ng></val ue> </param> </params> </met hodResponse>

  First-Generation Problems Alt hough first - generat ion XML prot ocols have been and st ill are very useful, t heir sim plicit y and reliance on XML 1.0 alone causes som e problem s.

  First - generat ion prot ocols are not very ext ensible. The prot ocol archit ect s had t o reach agreem ent before any changes w ere im plem ent ed, and t he prot ocol version had t o be revved up in order t o let t ools dist inguish new prot ocol versions from old ones and handle t he XML appropriat ely. For exam ple, w hen XML- RPC and WDDX added support for binary dat a, bot h prot ocols had t o updat e t heir specificat ions, and t he prot ocol im plem ent at ions on all different languages and plat form s support ing t he prot ocols had t o be updat ed. The overhead of const ant ly revising specificat ions and deploying updat ed t ools for handling t he lat est versions of t he prot ocols im posed lim it s on t he speed and scope of adopt ion of first - generat ion prot ocols. Second- generat ion prot ocols address t he issue of ext ensibilit y w it h XML nam espaces.

  The second problem w it h first - generat ion prot ocols had t o do w it h dat at yping. First - generat ion XML prot ocols st uck t o a single Docum ent Type Definit ion ( DTD) t o describe t he represent at ion of serialized dat a in XML. I n general, t hey used j ust a few XML elem ent s. This approach m ade building t ools support ing t hese prot ocols relat ively easy. The t rouble w it h such an approach is t hat t he XML describing t he dat a in prot ocol m essages expressed dat at ype inform at ion and not sem ant ic inform at ion. I n ot her w ords, t o gain t he abilit y t o represent dat a in XML, first - generat ion XML prot ocols w ent w it hout t he abilit y t o preserve inform at ion about t he m eaning of t he dat a. Second- generat ion

  XML prot ocols use XML schem a as a m echanism t o com bine descript ive synt ax wit h dat at ype inform at ion. To sum t hings up, t he need t o provide broad ext ensibilit y w it hout cent ralized st andardizat ion and t he need t o com bine dat at ype inform at ion w it h sem ant ic inform at ion w ere t he driving forces behind t he effort t o im prove upon first - generat ion effort s and t o creat e SOAP, t he de fact o st andard XML prot ocol for m odern Web services and B2B applicat ions.

  Simple Object Access Protocol (SOAP)

  This sect ion looks at t he hist ory, design cent er, and core capabilit ies of SOAP as a m eans for est ablishing t he base on w hich t o build our underst anding of Web services.

The Making of SOAP

  Microsoft st art ed t hinking about XML- based dist ribut ed com put ing in 1997. The goal w as t o enable applicat ions t o com m unicat e via Rem ot e Procedure Calls ( RPCs) on t op of HTTP. DevelopMent or and Userland j oined t he discussions. The nam e SOAP was coined in early 1998. Things m oved forw ard, but as t he group t ried t o involve w ider circles at Microsoft , polit ics st epped in and t he process w as st alled. The DCOM cam p at t he com pany disliked t he idea of SOAP and believed t hat Microsoft should use it s dom inant posit ion in t he m arket t o push t he DCOM w ire prot ocol via som e form of HTTP t unneling inst ead of pursuing XML. Som e XML- focused folks at Microsoft believed t hat t he SOAP idea w as good but t hat it had com e t oo early. Perhaps t hey w ere looking for som e of t he advanced facilit ies t hat could be provided by XML Schem a and Nam espaces. Frust rat ed by t he deadlock, Userland w ent public w it h a cut of t he spec published as XML- RPC in t he

  I n 1999, as Microsoft w as w orking on it s version of XML Schem a ( XML Dat a) and adding support for nam espaces in it s XML product s, t he idea of SOAP gained addit ional m om ent um . I t w as st ill an XML- based RPC m echanism , how ever. That 's w hy it m et w it h resist ance from t he BizTalk ( ht t p: / / w w w .bizt alk.org ) t eam . The BizTalk m odel w as based m ore on m essaging t han RPCs. I t t ook people a few m ont hs t o resolve t heir differences. SOAP 0.9 appeared for public review on Sept em ber 13, 1999. I t w as subm it t ed t o t he

  I ETF as an I nt ernet public draft . Wit h few changes, in Decem ber 1999, SOAP 1.0 cam e t o life. On May 8, 2000 SOAP 1.1 w as subm it t ed as a Not e t o t he World Wide Web Consort ium ( W3C) w it h I BM as a co- aut hor—an unexpect ed and refreshing change. I n addit ion, t he SOAP 1.1 spec w as m uch m ore ext ensible, elim inat ing concerns t hat backing SOAP im plied backing som e Microsoft propriet ary t echnology. This change, and t he fact t hat

  I BM im m ediat ely released a Java SOAP im plem ent at ion t hat w as subsequent ly donat ed t o t he Apache XML Proj ect ( ht t p: / / xm l.apache.org ) for open- source developm ent , convinced even t he great est skept ics t hat SOAP is som et hing t o pay at t ent ion t o. Sun voiced support for SOAP and st art ed w ork on int egrat ing Web services int o t he J2EE plat form . Not long aft er, m any vendors and open- source proj ect s w ere w orking on Web service im plem ent at ions.

  Right before t he XTech 2000 Conference, t he W3C m ade an announcem ent t hat it w as looking int o st art ing an act ivit y in t he area of XML prot ocols: " We've been under pressure from m any sources, including t he advisory board, t o address t he t hreat of fragm ent at ion of and invest igat e t he excit ing opport unit ies in t he area of XML prot ocols. I t m akes sense t o address t his now because t he t echnology is st ill early in it s evolut ion…" ( ht t p: / / list s.w 3.org/ Archives/ Public/ xm l- dist - app/ 2000Feb/ 0006.ht m l ) . On Sept em ber 13, 2000 t he XML Prot ocol w orking group at t he W3C w as form ed t o design t he XML prot ocol t hat w as t o becom e t he core of XML- based dist ribut ed com put ing in t he years t o com e. The group st art ed w it h SOAP 1.1 as a foundat ion and produced t he first w orking draft of SOAP 1.2 on July 9, 2001.

What Should SOAP Do?

  SOAP claim s t o be a specificat ion for a ubiquit ous XML dist ribut ed com put ing infrast ruct ure. I t 's a nice buzzw ord- com pliant phrase, but w hat does it m ean? Let 's parse it bit by bit t o find out w hat SOAP should do.

  XML m eans t hat , as a second- generat ion XML prot ocol, SOAP is based on XML 1.0, XML Schem a, and XML Nam espaces. Dist ribut ed com put ing im plies t hat SOAP can be used t o enable t he int eroperabilit y of rem ot e applicat ions ( in a very broad sense of t he phrase) . Dist ribut ed com put ing is a fuzzy t erm and it m eans different t hings t o different people and in different sit uat ions. Here are som e " facet s" you can use t o t hink about a part icular dist ribut ed com put ing scenario: t he prot ocol st ack used for com m unicat ion, connect ion m anagem ent , securit y, t ransact ion support , m arshalling and unm arshalling of dat a, prot ocol evolut ion and version m anagem ent , error handling, audit t rails, and so on. The requirem ent s for different facet s w ill vary bet w een scenarios. For exam ple, a st ock t icker service t hat cont inuously dist ribut es st ock prices t o a num ber of subscribers w ill have different needs t han an e- com m erce paym ent - processing service. The st ock t icker service w ill probably need no support for t ransact ions and only m inim al, if any, securit y or audit t rails ( it dist ribut es publicly available dat a) . The e- com m erce paym ent - processing service w ill require Cerberean securit y, heavy- dut y t ransact ion support , and full audit t rails. I nfrast ruct ure im plies t hat SOAP is aim ed at low - level dist ribut ed syst em s developers, not developers of applicat ion/ business logic or business users. I nfrast ruct ure product s such as applicat ion servers becom e " SOAP enabled" by including a Web service engine t hat underst ands SOAP. SOAP w orks behind t he scenes m aking sure your applicat ions

  Ubiquit ous m eans om nipresent , universal. On first look, it seem s t o be a m eaningless t erm , t hrow n int o t he phrase t o m ake it sound grander. I t t urns out , how ever, t hat t his is t he m ost im port ant part . The ubiquit y goal of SOAP is a blessing because, if SOAP- enabled syst em s are everyw here on t he I nt ernet , it should be easier t o do dist ribut ed com put ing. Aft er all, t hat 's w hat SOAP is all about . How ever, t he ubiquit y of SOAP is also a curse, because one t echnology specificat ion should be able t o support m any different t ypes of dist ribut ed com put ing scenarios, from t he st ock t icker service t o t he e- com m erce paym ent - processing service. To m eet t his goal, SOAP needs t o be a highly abst ract and flexible t echnology. However, t he m ore abst ract SOAP becom es, t he less support it w ill provide for specific dist ribut ed com put ing scenarios. Furt herm ore, great er abst ract ion m eans m ore risk t hat different SOAP im plem ent at ions w ill fail t o int eroperat e. This is t he et ernal t ug- of- w ar bet w een generalit y and specificit y.

What Is SOAP, Really?

  Like m ost new t echnologies t hat change t he rules of how applicat ions are being developed, Web services and SOAP have som et im es been over- hyped. Despit e t he hype, how ever, SOAP is st ill of great im port ance because it is t he indust ry's best effort t o dat e t o st andardize on t he infrast ruct ure t echnology for cross- plat form XML dist ribut ed com put ing. Above all, SOAP is relat ively sim ple. Hist orically, sim plicit y is a key feat ure of m ost successful archit ect ures t hat have achieved m ass adopt ion. The Web wit h HTTP and HTML at it s core is a prim e exam ple. Sim ple syst em s are easier t o describe, underst and, im plem ent , t est , m aint ain, and evolve. At it s heart , SOAP is a specificat ion for a sim ple yet flexible second- generat ion XML prot ocol. SOAP 1.0 print ed at about 40 pages. The t ext of t he specificat ion has grow n since t hen ( t he aut hors have t o m ake sure t he specificat ion is clear and has no holes) , but t he core concept s rem ain sim ple. Because SOAP is focused on t he com m on aspect s of all dist ribut ed com put ing scenarios, it provides t he follow ing:

  A mechanism for defining the unit of communication. In SOAP, all • information is packaged in a clearly identifiable SOAP message. This is done via a SOAP envelope that encloses all other information. A message can have a body in which potentially arbitrary XML can be used. It can also have any number of headers that encapsulate information outside the body of the message.

  A mechanism for error handling that can identify the source and cause •

of the error and allows for error-diagnostic information to be

exchanged between participants in an interaction. This is done via the notion of a SOAP fault.

  An extensibility mechanism so that evolution is not hindered and • there is no lock-in. XML, schemas, and namespaces really shine here. The two key requirements on extensions are that they can be orthogonal to other extensions and they can be introduced and used

without the need for centralized registration or coordination.

Typically, extensions are introduced via SOAP headers. They can be used to build more complex protocols on top of SOAP.

  

A flexible mechanism for data representation that allows for the

on) as well as a convention for representing abstract data structures such as programming language datatypes in an XML format. A convention for representing Remote Procedure Calls (RPCs) and • responses as SOAP messages, because RPCs are the most common type of distributed computing interaction and because they map so well to procedural programming language constructs. A document-centric approach to reflect more natural document exchange • models for business interactions. This is needed to support the cases in which RPCs result in interfaces that are too fine grained and, therefore, brittle.

A binding mechanism for SOAP messages to HTTP, because HTTP is the • most common communication protocol on the Internet

  Alt hough solid consensus exist s in t he indust ry about t he core capabilit ies of SOAP, t here is considerably less agreem ent on how higher- level issues such as securit y and t ransact ion- m anagem ent should be addressed. Nearly everyone agrees t hat t o t ackle t he broad spect rum of int erest ing problem s w e are faced w it h, w e need t o w ork in parallel on a set of layered specificat ions for XML dist ribut ed com put ing. I ndeed, m any loosely coupled indust ry init iat ives are developing st andards and t echnologies around SOAP. Tracking t hese effort s is like t rying t o shoot at m any m oving t arget s. The aut hors of t his book have t ried our best t o address t he relevant effort s in t his space and t o provide you w it h up- t o- dat e inform at ion. Chapt er 1 show ed how m any of t hese effort s layered around t he not ion of t he Web services int eroperabilit y st ack. Chapt er 5 , " Using SOAP for e- Business," goes int o m ore det ail about t he set of st andards surrounding SOAP t hat enable secure, robust , and scalable ent erprise- grade Web services.

  Now , let 's t ake a look at how Skat esTow n is planning t o use SOAP and Web services.

  Doing Business with SkatesTown

  When Al Rosen of Silver Bullet Consult ing first began his engagem ent w it h Skat esTow n, he focused on underst anding t he e- com m erce pract ices of t he com pany and it s cust om ers. Aft er a series of conversat ions wit h Skat esTown's CTO Dean Caroll, he concluded t he follow ing:

  • SkatesTown's manufacturing, inventory management, and supply chain

  

automation systems are in good order. These systems are easily

accessible by SkatesTown's Web-centric applications. SkatesTown has solid consumer-oriented online presence. Product and • inventory information is fed into the online catalog that is accessible to both direct consumers and SkatesTown's reseller partners via two different sites. Although SkatesTown's order processing system is sophisticated, it is • poorly connected to online applications. This is a pain point for the company because SkatesTown's partners are demanding better integration with their supply chain automation systems.

  SkatesTown's purchase order system is solid. It accepts purchase • orders in XML format and uses XML Schema-based validation to guarantee their correctness. Purchase order item stock keeping units (SKUs) and quantities are checked against the inventory management system. If all items are available, an invoice is created. SkatesTown charges a uniform 5% tax on purchases and the highest of 5% of the total purchase or $20 for shipping and handling.

  Digging deeper int o t he order processing part of t he business, Al discovered t hat it uses a low - t ech approach t hat has a high labor cost and is not suit able for aut om at ion. He not iced one area t hat badly needed aut om at ion: t he process of purchase order subm ission. Purchase orders are sent t o Skat esTow n by e- m ail. All e- m ails arrive in a single m anager's account in operat ions. The m anager m anually dist ribut es t he orders t o several subordinat es. They have t o open t he e- m ail, copy only t he XML over t o t he purchase order syst em , and ent er t he order t here. The syst em w rit es an invoice file in

  XML form at . This file m ust be opened, and t he XML m ust be copied and past ed int o a reply e- m ail m essage. Sim ple m isspellings of e- m ail addresses and cut - and- past e errors are com m on. They cost Skat esTown and it s part ners bot h m oney and t im e. Anot her area t hat needs aut om at ion is t he invent ory checking process. Skat esTow n's part ners used t o subm it purchase orders w it hout having a clear idea w het her all t he it em s w ere in st ock. This oft en caused delayed order processing. Furt her, purchasing personnel from t he part ner com panies w ould engage in long e- m ail dialogs w it h operat ions people at Skat esTow n. This sit uat ion w as not very efficient . To im prove it , Skat esTow n built a sim ple online applicat ion t hat com m unicat es w it h t he com pany's invent ory m anagem ent syst em . Part ners could log in, brow se Skat esTow n's product s, and check w het her cert ain it em s w ere in st ock. The applicat ion int erface is show n in

Figure 3.1 . ( You can access t his applicat ion as Exam ple 1 under Chapt er 3 in t he exam ple

  applicat ion on t his book's Web sit e.) This applicat ion w as a good st art , but now Skat esTow n's part ners are dem anding t he abilit y t o have t heir purchasing applicat ions direct ly inquire about order availabilit y.

Figure 3.1. SkatesTown's online inventory check application. Looking at t he t w o areas t hat m ost needed t o be im proved, Al Rosen chose t o focus on t he invent ory checking process because t he business logic was already present . He j ust had t o enable bet t er aut om at ion. To do t his, he had t o bet t er underst and how t he applicat ion w orked.

  Interacting with the Inventory System

  The logic for int eract ing w it h t he invent ory syst em is very sim ple. Looking t hrough t he Java Server Pages ( JSPs) t hat m ade up t he online applicat ion, Al easily ext ract ed t he key

  /ch3/ex1/inventoryCheck.jsp

  business logic operat ions from . Here is t he process for checking Skat esTown's invent ory:

  i mport bws. BookUt i l ; i mport com.skat est own. dat a. Product ; i mport com.skat est own. backend. Product DB; St ri ng sku = . . . ; i nt quant i t y = . . . ; Product DB db = BookUt i l . get Product DB( . . . ) ; Product p = db. get BySKU( sku) ; bool ean i sI nSt ock = ( p ! = nul l && p. get NumInSt ock( ) >= quant i t y) ;

  Given a SKU and a desired product quant it y, an applicat ion needs t o get an inst ance of t he Skat esTow n product dat abase and locat e a product w it h a m at ching SKU. I f such a product is available and if t he num ber of it em s in st ock is great er t han or equal t o t he desired quant it y, t he invent ory check succeeds. Because m ost of t he exam ples in t his chapt er t alk t o t he invent ory syst em , it is good t o t ake a deeper look at it s im plem ent at ion.

  Note

  A not e of caut ion: t his book's sam ple applicat ions dem onst rat e realist ic uses of Java t echnology and Web services t o solve real business problem s w hile, at t he sam e t im e, rem aining sim ple enough t o fit in t he book's scope and size lim it at ions. Furt her, all t he exam ples are direct ly accessible in m any environm ent s and on all plat form s t hat have a JSP and servlet engine w it hout any sophist icat ed inst allat ion. To m eet t hese som ew hat conflict ing crit eria, som et hing has t o give. For exam ple:

  To keep the code simple, we do as little data validation and error •

checking as possible without allowing applications to break. You

won't find us defining custom exception types or producing long,

readable error messages.

  To get away from the complexities of external system access, we use • simple XML files to store data.

  BookUtil To make deployment easier, we use the • class as a place to go for all operations that depend on file locations or URLs. You can tune the deployment options for the example applications by modifying

  BookUtil some of the constants defined in .

  All file paths are relative to the installation directory of the •

  /resources/

  Skat esTow n's invent ory is represent ed by a sim ple XML file st ored in

  products.xml

  ( see List ing 3.1 ) . By m odifying t his file, you can change t he behavior of m any exam ples. The Java represent at ion of product s in Skat esTow n's syst em s is t he

  com.skatestown.data.Product

  class. I t is a sim ple bean t hat has one propert y for every elem ent under product . Listing 3.1 SkatesTown Inventory Database

  <?xml versi on="1. 0" encodi ng="UTF- 8"?> <product s> <product > <sku>947- TI </sku> <name>Ti t ani um Gl i der</name> <t ype>skat eboard</t ype> <desc>St reet - st yl e t i t ani um skat eboard. </desc> <pri ce>129. 00</pri ce> <i nSt ock>36</i nSt ock> </product > . . . </product s>

  ProductDB

  Skat esTown's invent ory syst em is accessible via t he ( for product dat abase)

  com.skatestown.backend

  class in package . List ing 3.2 shows t he key operat ions it

  Document

  support s. To const ruct an inst ance of t he class, you pass an XML DOM obj ect

  products.xml BookUtil.getProductDB()

  represent at ion of . ( does t his aut om at ically.) Aft er t hat , you can get a list ing of all product s or you can search for a product by it s SKU.

  Listing 3.2 SkatesTown's Product Database Class

  publ i c cl ass Product DB { pri vat e Product [ ] product s; publ i c Product DB( Document doc) t hrows Except i on { // Load product i nf ormat i on } publ i c Product get BySKU( St ri ng sku) { Product [ ] l i st = get Product s( ) ; f or ( i nt i = 0 ; i < l i st . l engt h ; i ++ ) i f ( sku. equal s( l i st [ i ] . get SKU( ) ) ) ret urn( l i st [ i ] ) ; ret urn( nul l ) ; } publ i c Product [ ] get Product s( ) { ret urn product s; } }

  This w as all Al Rosen needed t o know t o m ove forw ard w it h t he t ask of aut om at ing t he invent ory checking process.

  Inventory Check Web Service

  Skat esTow n's invent ory check Web service is very sim ple. The int eract ion m odel is t hat of an RPC. There are t w o input param et ers: t he product SKU ( a st ring) and t he quant it y desired ( an int eger) . The result is a sim ple boolean value—t rue if m ore t han t he desired quant it y of t he product are in st ock and false ot herw ise.

  Choosing a Web Service Engine

  Al Rosen decided t o host all of Skat esTow n's Web services on t he Apache Axis Web service engine for a num ber of reasons:

  • The open-source implementation guaranteed that SkatesTown will not

  

experience vendor lock-in in the future. Further, if any serious

problems were discovered, you could always look at the code to see what is going on. Axis is one of the best Java-based Web services engines. It is better

  • architected and much faster than its Apache SOAP predecessor. The

    core Axis team includes some of the great Web service gurus from

    companies such as HP, IBM, and Macromedia. Axis is also probably the most extensible Web service engine. It can • be tuned to support new versions of SOAP as well as the many types of extensions current versions of SOAP allow. Axis can run on top of a simple servlet engine or a full-blown J2EE • application server. SkatesTown could keep its current J2EE application server without having to switch.

  This com binat ion of fact ors leads t o an easy sell. Skat esTow n's CTO agreed t o have all Web services developed on t op of Axis. Al spent som e t im e on

  ht t p: / / xm l.apache.org/ axis learning m ore about t he t echnology and it s capabilit ies. He

  learned how t o inst all Axis on t op of Skat esTow n's J2EE server by reading t he Axis inst allat ion inst ruct ions.

  Service Provider View

  To expose t he Web service, Al Rosen had t o do t w o t hings: im plem ent t he service backend and deploy it int o t he Web service engine. Building t he backend for t he invent ory check Web service w as sim ple because t he logic w as already available in Skat esTow n's JSP pages ( see List ing 3.3 ) . Listing 3.3 Inventory Check Web Service Implementation

  i mport org. apache. axi s. MessageCont ext ; i mport bws. BookUt i l ; i mport com.skat est own. dat a. Product ; i mport com.skat est own. backend. Product DB;

  • I nvent ory check Web servi ce
  • / publ i c cl ass I nvent oryCheck { /**
  • Checks i nvent ory avai l abi l i t y gi ven a product SKU and * a desi red product quant i t y.
  • @param msgCont ext Thi s i s t he Axi s message processi ng cont ext
  • BookUt i l needs t hi s t o ext ract depl oyment * i nf ormat i on t o l oad t he product dat abase.
  • @param sku product SKU
  • @param quant i t y quant i t y desi red
  • @ret urn t rue|f al se based on product avai l abi l i t y
  • @except i on Except i on most l i kel y a probl em accessi ng t he DB
  • / publ i c st at i c bool ean doCheck( MessageCont ext msgCont ext , St ri ng sku, i nt quant i t y) t hrows Except i on { Product DB db = BookUt i l . get Product DB( msgCont ext ) ; Product prod = db. get BySKU( sku) ; ret urn ( prod ! = nul l && prod. get NumInSt ock( ) >= quant i t y) ; }

  }

  One Axis- specific feat ure of t he im plem ent at ion is t hat t he first argum ent t o t he

  doCheck()

  m et hod is an Axis m essage cont ext obj ect . You need t he Axis cont ext so t hat

  BookUtil

  you can get t o t he product dat abase using t he class. From inside t he Axis m essage cont ext , you can get access t o t he servlet cont ext of t he exam ple Web applicat ion. ( Axis det ails such as m essage cont ext are covered in Chapt er 4 , " Creat ing Web Services." ) Then you can use t his cont ext t o load t he product dat abase from

  resources/products.xml

  . Not e t hat t his param et er w ill not be " visible" t o t he request or of a Web service. I t is som et hing Axis w ill provide you w it h if it not ices it ( using Java reflect ion) t o be t he first param et er in your m et hod. The m essage cont ext param et er w ould not be necessary in a real- w orld sit uat ion w here t he product dat abase w ould m ost likely be obt ained via JNDI . Deploying t he Web service int o Axis is t rivial because Axis has t he concept of a Java Web

  .jws

  Service ( JWS) file. A JWS file is a Java file st ored w it h t he ext ension som ew here in t he ext ernally accessible Web applicat ions direct ory st ruct ure ( anyw here ot her t han

  /WEB-INF

  under ) . JWSs are t o Web services som ew hat as JSPs are t o servlet s. When a request is m ade t o a JWS file, Axis w ill aut om at ically com pile t he file and invoke t he Web service it provides. This is a great convenience for developm ent and m aint enance.

  /ch3/ex2/InventoryCheck.jws

  I n t his case, t he code from List ing 3.3 is st ored as . This aut om at ically m akes t he Web service available at t he applicat ion URL

  appRoot/ch3/ex2/InventoryCheck.jws

  . For t he exam ple applicat ion deployed on t op of Tom cat , t his URL is ht t p: / / localhost : 8080/ bw s/ ch3/ ex2/ I nvent oryCheck.j w s .

  Service Requestor View

  Because SOAP is language and plat form neut ral, t he invent ory check Web service can be accessed from any program m ing environm ent t hat is Web services enabled. There are are available. Service descript ions use t he Web Services Descript ion Language ( WSDL) t o specify in det ail inform at ion about Web services such as t he t ype of dat a t hey require, t he t ype of dat a t hey produce, w here t hey are locat ed, and so on. WSDL is t o Web services w hat I DL is t o COM and CORBA and w hat Java reflect ion is t o Java classes. Web services t hat have WSDL descript ions can be accessed in t he sim plest possible m anner.

  Chapt er 6 , " Describing Web Services," int roduces WSDL, it s capabilit ies, and t he t ools

  t hat use WSDL t o m ake Web service developm ent and usage sim pler and easier. I n t his chapt er, w e w ill have t o do w it hout WSDL.

  List ing 3.4 show s t he prot ot ypical m odel for building Web service client s in t he absence

  of a form al service descript ion. The basic class st ruct ure is sim ple:

  A private member stores the URL where the service can be accessed. Of •

course, this property can have optional getter/setter methods.

A simple constructor sets the target URL for the service. If the URL

  • is well known, it can be set in a default constructor. There is one method for every operation exposed by the Web service. • The method signature is exactly the same as the signature of the Web service operation.

  Listing 3.4 Inventory Check Web Service Client

  package ch3. ex2; i mport org. apache. axi s. cl i ent . Servi ceCl i ent ; /*

  • I nvent ory check web servi ce cl i ent
  • / publ i c cl ass I nvent oryCheckCl i ent { /**
  • Servi ce URL
  • / pri vat e St ri ng url ; /**
  • Poi nt a cl i ent at a gi ven servi ce URL
  • / publ i c I nvent oryCheckCl i ent ( St ri ng t arget Url ) { url = t arget Url ; } /**
  • I nvoke t he i nvent ory check web servi ce
  • / publ i c bool ean doCheck( St ri ng sku, i nt quant i t y) t hrows Except i on { Servi ceCl i ent cal l = new Servi ceCl i ent ( url ) ;

  "", "doCheck", new Obj ect [ ] { sku, new I nt eger( quant i t y) } ) ; ret urn resul t . bool eanVal ue( ) ; } }

  This approach for building Web service client s by hand insulat es developers from t he det ails of XML, t he SOAP m essage form at and prot ocol, and t he API s for invoking Web services using som e part icular client library. For exam ple, users of

  InventoryCheckClient w ill never know t hat you have im plem ent ed t he class using Axis.

  This is a good t hing.

  

Chapt er 4 w ill go int o t he det ails of t he Axis API . Here w e'll briefly look at w hat needs t o

ServiceClient

  happen t o access t he Web service. First , you need t o creat e a obj ect using t he service URL. The service client is t he abst ract ion used t o m ake a Web service

  invoke() ServiceClient

  call. Then, you call t he m et hod of t he , passing in t he nam e of t he operat ion you are t rying t o invoke and an obj ect array of t he t w o operat ion

  String Integer

  param et ers: a for t he SKU and an for t he quant it y. The result w ill be a

  Boolean obj ect .

  That 's all t here is t o invoking a Web service using Axis.

  Putting the Service to the Test /ch3/ex2/index.jsp

Figure 3.2 shows a sim ple JSP page ( ) t hat uses

  InventoryCheckClient

  t o access Skat esTown's Web service. You can experim ent wit h different SKU and quant it y com binat ions and see how Skat esTow n's SW responds. You can check t he responses against t he cont ent s of t he product dat abase in

  /resources/products.xml .

Figure 3.2. Putting the SkatesTown inventory check Web service to the test. claim as an infrast ruct ure t echnology. The m echanism t hat allow s t his t o happen involves m ult iple abst ract ion layers ( see Figure 3.3 ) . Providers and request ors view services as Java API s. I nvoking a Web service requires one or m ore Java m et hod invocat ions. I m plem ent ing a Web service requires im plem ent ing a Java backend ( a class or an EJB, for exam ple) . The Web service view is one of SOAP m essages being exchanged bet w een t he request or and t he provider.

Figure 3.3. Layering of views in Web service invocation.

  These are bot h logical view s in t hat t his is not how t he request or and provider com m unicat e. The only " real" view is t he w ire- level view w here HTTP packet s cont aining SOAP m essages are exchanged bet w een t he request or's applicat ion and t he provider's Web server. The m iracle of soft ware abst ract ion has com e t o our aid once again.

SOAP on the Wire

  The pow ers of abst ract ion aside, really underst anding Web services does require som e know ledge of XML. Just as a highly skilled Java developer has an idea about w hat t he JVM is doing and can use t his know ledge t o w rit e higher perform ance applicat ions, so m ust a Web service guru underst and t he SOAP specificat ion and how SOAP m essages are m oved around bet w een request ors and providers. This does not m ean t hat t o build or consum e sophist icat ed or high- perform ance Web services you have t o w ork w it h raw

  XML—layers can be applied t o abst ract your applicat ion from SOAP. How ever, know ledge of SOAP and t he w ay in w hich a Web service engine t ranslat es Java API calls int o SOAP m essages and vice versa allow s you t o m ake educat ed decisions about how t o define and im plem ent Web services.

  TCPMon Luckily, t he Apache Axis dist ribut ion com es w it h an aw esom e t ool t hat can m onit or t he exchange of SOAP m essages on t he w ire. The apt ly nam ed TCPMon t ool w ill m onit or all t raffic on a given port . You can learn how t o use TCPMon by looking at t he exam ples

  /readme.html inst allat ion sect ion in .

  TCPMon w ill redirect all t raffic t o anot her host and port . This abilit y m akes TCPMon great not only for m onit oring SOAP t raffic but also for t est ing t he book's exam ples w it h a backend ot her t han Tom cat . Figure 3.4 show s TCPMon in act ion on t he invent ory check Web service. I n t his case, t he backend is running on t he Macrom edia JRun J2EE applicat ion server. By default , JRun's servlet engine list ens on port 8100, not on 8080 as Tom cat does. I n t he figure, TCPMon is set up t o list en on 8080 but t o redirect all t raffic t o 8100. Essent ially, w it h TCPMon you can m ake JRun ( or I BM WebSphere or BEA Weblogic) appear t o list en on t he sam e port as Tom cat and run t he book's exam ples w it hout any changes.

  The SOAP Request Here is t he inform at ion t hat passed on t he w ire as a result of t he invent ory check Web service request . Som e irrelevant HTTP headers have been rem oved and t he XML has been form at t ed for bet t er readabilit y but , apart from t hat , no subst ant ial changes have been m ade:

  POST /bws/i nvent ory/I nvent oryCheck. j ws HTTP/1. 0 Host : l ocal host Cont ent - Type: t ext /xml; charset =ut f - 8 Cont ent - Lengt h: 426 SOAPAct i on: "" <?xml versi on="1. 0" encodi ng="UTF- 8"?> <SOAP- ENV: Envel ope SOAP- ENV: encodi ngSt yl e="ht t p: //schemas. xmlsoap. org/soap/encodi ng/" xmlns: xsd="ht t p: //www. w3. org/2001/XMLSchema" xmlns: SOAP- ENV="ht t p: //schemas. xmlsoap. org/soap/envel ope/" xmlns: xsi ="ht t p: //www. w3. org/2001/XMLSchema- i nst ance"> <SOAP- ENV: Body> <doCheck> <arg0 xsi : t ype="xsd: st ri ng">947- TI </arg0> <arg1 xsi : t ype="xsd: i nt ">1</arg1> </doCheck> </SOAP- ENV: Body> </SOAP- ENV: Envel ope>

  Lat er in t he chapt er, w e w ill look in det ail at all part s of SOAP. For now , a quick int roduct ion w ill suffice. The HTTP packet begins w it h t he operat ion, a POST, and t he t arget URL of t he Web service t o be invoked. The host is localhost ( 127.0.0.1) because you are accessing t he exam ple Web service t hat com es w it h t he book from your local m achine. The cont ent

  text/xml

  MI ME t ype of t he request is . This is how SOAP m ust be invoked over HTTP. The cont ent lengt h header is aut om at ically calculat ed based on t he SOAP m essage t hat is

  SOAPAction

  part of t he HTTP packet 's body. The header pert ains t o t he binding of SOAP t o t he HTTP prot ocol. I n som e cases it m ight cont ain m eaningful inform at ion. JWS- based Web service providers don't require it , how ever, and t hat 's w hy it is em pt y. The body of t he HTTP packet cont ains t he SOAP m essage describing t he invent ory check

  SOAP-ENV:Envelope

  Web service request . The m essage is ident ified by t he elem ent . The

  xmlns

  elem ent has t hree : at t ribut es t hat define t hree different nam espaces and t heir

  

SOAP-ENV xsd

  associat ed prefixes: for t he SOAP envelope nam espace, for XML Schem a,

  xsi encodingStyle

  and for XML Schem a inst ances. One ot her at t ribut e, , specifies how dat a in t he SOAP m essage w ill be encoded.

  SOAP-ENV:Envelope SOAP-ENV:Body

  I nside t he elem ent is a elem ent . The body of t he SOAP m essage cont ains t he real inform at ion about t he Web service request . I n t his case, t his elem ent has t he sam e nam e as t he m et hod on t he Web service t hat you w ant t o

  doCheck() ServiceClient

  invoke— . You can see t hat t he Axis obj ect aut o- generat ed

  arg0 arg1

  elem ent nam es— and —t o hold t he param et ers passed t o t he m et hod. This is fine, because no ext ernal schem a or service descript ion specifies how request s t o t he invent ory check service should be m ade. I n lieu of anyt hing like t hat , Axis has t o do it s best in an at t em pt t o m ake t he call. Bot h param et er elem ent s cont ain self- describing

  xsi:type

  dat a. Axis int rospect ed t he Java t ypes for t he param et ers and em it t ed

  java.lang.String

  at t ribut es, m apping t hese t o XML Schem a t ypes. The SKU is a and is

  xsd:string java.lang.Integer

  t herefore m apped t o , and t he quant it y is a and is

  xsd:int

  t herefore m apped t o . The net result is t hat , even w it hout a det ailed schem a or service descript ion, t he SOAP m essage cont ains enough inform at ion t o guarant ee successful invocat ion. The SOAP Response Here is t he HTTP response t hat cam e back from Axis:

  HTTP/1. 0 200 OK Cont ent - Type: t ext /xml; charset =ut f - 8 Cont ent - Lengt h: 426 <?xml versi on="1. 0" encodi ng="UTF- 8"?> <SOAP- ENV: Envel ope SOAP- ENV: encodi ngSt yl e="ht t p: //schemas. xmlsoap. org/soap/encodi ng/" xmlns: xsd="ht t p: //www. w3. org/2001/XMLSchema" xmlns: SOAP- ENV="ht t p: //schemas. xmlsoap. org/soap/envel ope/" xmlns: xsi ="ht t p: //www. w3. org/2001/XMLSchema- i nst ance"> <SOAP- ENV: Body> <doCheckResponse> <doCheckResul t xsi : t ype="xsd: bool ean">t rue</doCheckResul t > </doCheckResponse> </SOAP- ENV: Body> </SOAP- ENV: Envel ope>

  200 OK

  The HTTP response code is because t he service invocat ion com plet ed

  text/xml

  successfully. The cont ent t ype is also . The SOAP m essage for t he response is st ruct ured in an ident ical m anner t o t he one for t he request . I nside t he SOAP body is t he

  doCheckResponse

  elem ent . Axis has t aken t he elem ent nam e of t he operat ion t o invoke and added Response t o it . The elem ent cont ained w it hin uses t he sam e pat t ern but w it h xsi:type

  Again, Axis uses t o m ake t he m essage's dat a self- describing. This is how t he service client knows t hat t he result is a boolean. Ot herwise, you couldn't have cast t he

  call.invoke() java.lang.Boolean result of t o a in List ing 3.4 .

  I f t he m essages seem relat ively sim ple, it is because SOAP is designed w it h sim plicit y in m ind. Of course, as always, som e com plexit y lurks in t he det ails. The next several sect ions w ill t ake an in- dept h look at SOAP in an at t em pt t o uncover and explain all t hat you need t o know about SOAP t o becom e a skilled and successful Web service developer and user.

SOAP Envelope Framework

  The m ost im port ant part t hat SOAP specifies is t he envelope fram ew ork. Alt hough it consist s of j ust a few XML elem ent s, it provides t he st ruct ure and ext ensibilit y m echanism s t hat m ake SOAP so w ell suit ed as t he foundat ion for all XML- based dist ribut ed com put ing. The SOAP envelope fram ew ork defines a m echanism for ident ifying w hat inform at ion is in a m essage, w ho should deal w it h t he inform at ion, and w het her t his is opt ional or m andat ory. A SOAP m essage consist s of a m andat ory envelope w rapping any num ber of opt ional headers and a m andat ory body . These concept s are discussed in t urn in t he following sect ions.

  SOAP Envelope

  SOAP m essages are XML docum ent s t hat define a unit of com m unicat ion in a dist ribut ed

  Envelope

  environm ent . The root elem ent of t he SOAP m essage is t he elem ent . I n SOAP 1.1, t his elem ent falls under t he ht t p: / / schem as.xm lsoap.org/ soap/ envelope/

  Envelope

  nam espace. Because t he elem ent is uniquely ident ified by it s nam espace, it allow s processing t ools t o im m ediat ely det erm ine w het her a given XML docum ent is a SOAP m essage. This cert ainly is convenient , but w hat do you t rade off for t his capabilit y? The biggest t hing you have t o sacrifice is t he abilit y t o send arbit rary XML docum ent s and perform sim ple schem a validat ion on t hem . True, you can em bed arbit rary XML inside t he SOAP

  Body Envelope

  elem ent , but naïve validat ion w ill fail w hen it encount ers t he elem ent at t he t op of t he docum ent inst ead of t he t op docum ent elem ent of your schem a. The lesson is t hat for seam less validat ion of arbit rary XML inside SOAP m essages, you m ust int egrat e XML validat ion w it h t he Web services engine. I n m ost cases, t he Web services engine w ill have t o separat e SOAP- specific from applicat ion- specific XML before validat ion can t ake place.

  Header Body

  The SOAP envelope can cont ain an opt ional elem ent and a m andat ory

  Body

  elem ent . Any num ber of ot her XML elem ent s can follow t he elem ent . This ext ensibilit y feat ure helps w it h t he encoding of dat a in SOAP m essages. We'll discuss it lat er in t his chapt er in t he sect ion " SOAP Dat a Encoding Rules ."

  SOAP Versioning Envelope

  One int erest ing not e about SOAP is t hat t he elem ent does not expose any explicit prot ocol version, in t he st yle of ot her prot ocols such as HTTP ( HTTP/ 1.0 vs.

  <wddxPacket version="1.0"> ... </wddxPacket>

  HTTP/ 1.1) or WDDX ( ) . The designers of SOAP explicit ly m ade t his choice because experience had shown sim ple num ber- based versioning t o be fragile. Furt her, across prot ocols, t here w ere no consist ent rules for det erm ining w hat changes in m aj or versus m inor version num bers t ruly m ean. I nst ead of going t his w ay, SOAP leverages t he capabilit ies of XML nam espaces and defines t he prot ocol version t o be t he URI of t he SOAP envelope nam espace. As a result , t he only m eaningful st at em ent t hat you can m ake about SOAP versions is t hat t hey are t he sam e or different . I t is no longer possible t o t alk about com pat ible versus incom pat ible changes t o t he prot ocol. What does t his m ean for Web service engines? I t gives t hem a choice of how t o t reat SOAP m essages t hat have a version ot her t han t he one t he engine is best suit ed for processing. Because an engine support ing a lat er version of SOAP w ill know about all previous versions of t he specificat ion, it has a range of opt ions based on t he nam espace of t he incom ing SOAP m essage:

  If the message version is the same as any version the engine knows • how to process, the engine can just process the message. If the message version is older than any version the engine knows how • to process, the engine can do one of two things: generate a version mismatch error and/or attempt to negotiate the protocol version with the client by sending some information regarding the versions that it can accept. If the message version is newer than any version the engine knows how • to process, the engine can choose to attempt processing the message

anyway (typically not a good choice) or it can go the way of a

version mismatch error combined with some information about the

versions it understands.

  All in all, t he sim ple versioning based on t he nam espace URI result s in t he fairly flexible and accom m odat ing behavior of Web service engines.

SOAP Headers

  Headers are t he prim ary ext ensibilit y m echanism in SOAP. They provide t he m eans by w hich addit ional facet s can be added t o SOAP- based prot ocols. Headers define a very elegant yet sim ple m echanism t o ext end SOAP m essages in a decent ralized m anner. Typical areas w here headers get involved are aut hent icat ion and aut horizat ion, t ransact ion m anagem ent , paym ent processing, t racing and audit ing, and so on. Anot her w ay t o t hink about t his is t hat you w ould pass via headers any inform at ion ort hogonal t o t he specific inform at ion needed t o execut e a request .

  For exam ple, a t ransfer paym ent service only really needs from and t o account num bers and a t ransfer am ount t o execut e. I n real- w orld scenarios, how ever, a service request is likely t o cont ain m uch m ore inform at ion, such as t he ident it y of t he person m aking t he request , account / paym ent inform at ion, and so on. This addit ional inform at ion is usually handled by infrast ruct ure services ( login and securit y, t ransact ion coordinat ion, billing) out side t he m ain t ransfer paym ent service. Encoding t his inform at ion as part of t he body of a SOAP m essage w ill only com plicat e m at t ers. That is w hy it w ill be passed in as headers.

  A SOAP m essage can include any num ber of header ent ries ( sim ply referred t o as

  Header

  headers) . I f any headers are present , t hey w ill all be children of t he SOAP

  Envelope elem ent , w hich, if present , m ust appear as t he first child of t he SOAP elem ent . Transaction

  The following exam ple shows a SOAP m essage wit h t w o headers, and

  Priority

  . Bot h headers are uniquely ident ified by t he com binat ion of t heir elem ent nam e and t heir nam espace URI :

  <SOAP- ENV: Envel ope xmlns: SOAP- ENV="ht t p: //schemas. xmlsoap. org/soap/envel ope/"

  <SOAP- ENV: Header> <t : Transact i on xmlns: t ="some- URI " SOAP- ENV: must Underst and="1"> 12345 </t : Transact i on> <p: Pri ori t y xmlns: p="some- Ot her- URI "> <Real l yVeryHi gh/> </p: Pri ori t y> </SOAP- ENV: Header> <SOAP- ENV: Body> . . . </SOAP- ENV: Body> </SOAP- ENV: Envel ope>

  The cont ent s of a header ( som et im es referred t o as t he header value) are det erm ined by t he schem a of t he header elem ent . This allow s headers t o cont ain arbit rary XML, anot her exam ple of t he benefit s of SOAP being an XML- based prot ocol. Com pare it t o prot ocols such as HTTP where header values m ust be sim ple st rings, t hus forcing any st ruct ured inform at ion t o be som ehow encoded t o becom e a st ring. For exam ple, cookie values

  cookie1=value1;cookie2=value2

  com e in a sem icolon delim it ed form at , such as . I t is easy t o reach t he lim it s of t hese sim ple encodings. XML is a m uch bet t er w ay t o represent t his t ype of st ruct ured inform at ion.

  mustUnderstand

  1 Also, not ice t he SOAP at t ribut e w it h value t hat decorat es t he Transaction

  elem ent . This at t ribut e indicat es t hat t he recipient of t he SOAP m essage

  Transaction

  m ust process t he header ent ry. I f a recipient does not know how t o process

  mustUnderstand="1"

  a header t agged w it h , it m ust abort processing w it h a w ell- defined error. This rule allow s for robust evolut ion of SOAP- based prot ocols. I t ensures t hat a recipient t hat m ight be unaw are of cert ain im port ant prot ocol ext ensions does not ignore t hem .

  Priority mustUnderstand="1"

  Not e t hat because t he header is not t agged w it h , it can be ignored during processing. Presum ably, t his w ill be OK because a server t hat does not know how t o process m essage priorit ies w ill assum e norm al priorit y. You m ight have not iced t hat t he SOAP body can be t reat ed as a w ell- specified SOAP

  mustUnderstand="1"

  header flagged w it h . Alt hough t his is cert ainly t rue, t he SOAP designers t hought t hat having a separat ion bet w een t he headers and body of a m essage does not com plicat e t he prot ocol and is convenient for readabilit y. Before leaving t he t opic of headers, it is im port ant t o point out t hat , despit e t he obvious need for header ext ensions t o support such basic dist ribut ed com put ing concept s such as aut hent icat ion credent ials or t ransact ion inform at ion, t here hasn't been a broad st andardizat ion effort in t his area, w it h t he except ion of som e securit y ext ensions t hat w e'll review in Chapt er 5 . Som e of t he leading Web service vendors are doing int erest ing work, but t he indust ry as a whole is som e way away from agreeing on core ext ensions t o SOAP. Tw o prim ary forces m aint ain t his unsat isfact ory st at us quo:

  Most current Web service engines do not have a solid extensibility • architecture. Therefore, header processing is relatively difficult

right now. At the time of this writing, Apache Axis is a notable

exception to this rule.

  Market pressure is pushing Web service vendors to innovate in • isolation and to prefer shipping software over coordinating extensions with partners and competitors. Wider Web service adopt ion w ill undoubt edly put pressure on t he Web services com m unit y t o t hink m ore about int eroperabilit y and begin broad st andardizat ion in som e of t hese key areas.

  SOAP Body Body

  The SOAP elem ent im m ediat ely surrounds t he inform at ion t hat is core t o t he SOAP

  Body

  m essage. All im m ediat e children of t he elem ent are body ent ries ( t ypically referred t o sim ply as bodies) . Bodies can cont ain arbit rary XML. Som et im es, based on t he int ent of t he SOAP m essage, cert ain convent ions w ill govern t he form at of t he SOAP body. The convent ions for represent ing RPCs are discussed lat er in t he sect ion " SOAP- based RPCs ." The convent ions for com m unicat ing error inform at ion are discussed in t he sect ion " Error

  Handling in SOAP ." Taking Advantage of SOAP Extensibility

  Let 's t ake a look at how Skat esTow n can use SOAP ext ensibilit y t o it s benefit . I t t urns out t hat Skat esTow n's part ners are dem anding som e t ype of proof t hat cert ain it em s are in Skat esTow n's invent ory. I n part icular, part ners w ould like t o have an e- m ail record of any invent ory checks t hey have perform ed.

  Al Rosen got t he idea t o use SOAP ext ensibilit y in a w ay t hat allow s t he exist ing invent ory check service im plem ent at ion t o be reused w it h no changes. SOAP invent ory

  EMail

  check request s w ill include a header w hose elem ent nam e is belonging t o t he

  http://www.skatestown.com/ns/email

  nam espace. The value of t he header w ill be a sim ple st ring cont aining t he e- m ail address t o w hich t he invent ory check confirm at ion should be sent .

  Service Requestor View

  Service request ors w ill have t o m odify t heir client s t o build a cust om SOAP envelope t hat

  EMail

  includes t he header. List ing 3.5 shows t he necessary changes. The e- m ail t o send confirm at ions t o is provided in t he const ruct or. Listing 3.5 Updated Inventory Check Client

  package ch3. ex3; i mport org. apache. axi s. cl i ent . Servi ceCl i ent ; i mport org. apache. axi s. message. SOAPEnvel ope; i mport org. apache. axi s. message. SOAPHeader; i mport org. apache. axi s. message. RPCEl ement ; i mport org. apache. axi s. message. RPCParam; i mport j avax. xml. parsers. Document Bui l der; i mport j avax. xml. parsers. Document Bui l derFact ory; i mport org. w3c. dom.Document ; i mport org. w3c. dom.El ement ; /*

  • I nvent ory check web servi ce cl i ent
  • / publ i c cl ass I nvent oryCheckCl i ent { /**
  • Servi ce URL

  St ri ng url ; /**

  • Emai l address t o send conf i rmat i ons t o
  • / St ri ng emai l ; /**
  • Poi nt a cl i ent at a gi ven servi ce URL
  • / publ i c I nvent oryCheckCl i ent ( St ri ng url , St ri ng emai l ) { t hi s. url = url ; t hi s. emai l = emai l ; } /**
  • I nvoke t he i nvent ory check web servi ce
  • / publ i c bool ean doCheck( St ri ng sku, i nt quant i t y) t hrows Except i on { // Bui l d t he emai l header DOM el ement Document Bui l derFact ory f act ory = Document Bui l derFact ory. newI nst ance( ) ; Document Bui l der bui l der = f act ory. newDocument Bui l der( ) ; Document doc = bui l der. newDocument ( ) ;

  El ement emai l El em = doc. creat eEl ement NS( "ht t p: //www. skat est own. com/", "EMai l ") ; emai l El em.appendChi l d( doc. creat eText Node( emai l ) ) ; // Bui l d t he RPC request SOAP message SOAPEnvel ope reqEnv = new SOAPEnvel ope( ) ; reqEnv. addHeader( new SOAPHeader( emai l El em)) ; Obj ect [ ] params = new Obj ect [ ] { sku, new I nt eger( quant i t y) , } ; reqEnv. addBodyEl ement ( new RPCEl ement ( "", "doCheck", params) ) ; // I nvoke t he i nvent ory check web servi ce Servi ceCl i ent cal l = new Servi ceCl i ent ( url ) ; SOAPEnvel ope respEnv = cal l . i nvoke( reqEnv) ; // Ret ri eve t he response RPCEl ement respRPC = ( RPCEl ement ) respEnv. get Fi rst Body( ) ; RPCParam resul t = ( RPCParam)respRPC. get Params( ) . get ( 0) ; ret urn ( ( Bool ean) resul t . get Val ue( ) ) . bool eanVal ue( ) ; } } To set a header in Axis, you first need t o build t he DOM represent at ion for t he header. doCheck()

  The code in t he beginning of does t his. Then you need t o m anually const ruct

  SOAPEnvelope

  t he SOAP m essage t hat w ill be sent . This involves st art ing w it h a new

  SOAPHeader

  obj ect , adding a w it h t he DOM elem ent const ruct ed earlier, and, finally,

  RPCElement

  adding an as t he body of t he m essage. At t his point , you can use invoke()

  When t he call is m ade w it h a cust om - built SOAP envelope, t he ret urn value of

  SOAPEnvelope

  is also a obj ect . You need t o pull t he relevant dat a out of t hat envelope by

  RPCElement

  get t ing t he body of t he response, w hich w ill be an . The result of t he

  RPCParam doCheck()

  operat ion w ill be t he first inside t he RPC response. Know ing t hat

  Boolean ret urns a boolean, you can get t he value of t he param et er and safely cast it t o .

  As you can see, t he code is not t rivial, but Axis does provide a num ber of convenience obj ect s t hat m ake working wit h cust om - built SOAP m essages st raight forward. Figure 3.5 shows a UML diagram wit h som e of t he key Axis obj ect s relat ed t o SOAP m essages.

Figure 3.5. Axis SOAP message objects.

  Service Provider View

  The sit uat ion on t he side of t he Axis- based service provider is a lit t le m ore com plicat ed because w e can no longer use a sim ple JWS file for t he service. JWS files are best used for sim ple and st raight forw ard service im plem ent at ions. Current ly, it is not possible t o indicat e from a JWS file t hat a cert ain header ( in t his case t he e- m ail header) should be processed. Al Rosen im plem ent s t hree changes t o enable t his m ore sophist icat ed t ype of service:

  He moves the service implementation from the JWS file to a simple • Java class.

  EMail He writes a handler for the • header.

  He extends the Axis service deployment descriptor with information

  • about the service implementation and the header handler.

  InventoryCheck.jws

  Moving t he service im plem ent at ion is as sim ple as saving as

  InventoryCheck.java /WEB-INF/classes/com/skatestown/services

  in . No furt her changes t o t he service im plem ent at ion are necessary.

  EMail

  Building a handler for t he header is relat ively sim ple, as List ing 3.6 shows. When

  EMail

  t he handler is invoked by Axis, it needs t o find t he SOAP m essage and lookup t he t he handler sends a confirm at ion e- m ail of t he invent ory check. The im plem ent at ion is com plex because t o produce a m eaningful e- m ail confirm at ion, t he handler needs t o see bot h t he request dat a ( SKU and quant it y) and t he result of t he invent ory check. The basic process involves t he following st eps:

  1. Get the request or the response message using getRequestMessage() or getResponseMessage() MessageContext on the Axis object.

  2. Get the SOAP envelope by calling getAsSOAPEnvelope() .

  

3. Retrieve the first body of the envelope and cast it to an RPCElement

because the body represents either an RPC request or an RPC response.

  4. Get the parameters of the RPC element using getParams() .

  5. Extract parameters by their position and cast them to their appropriate type. As seen earlier in Listing 3.5 , the response of an RPC is the first parameter in the response message body.

  Listing 3.6 E-mail Header Handler

  package com.skat est own. servi ces; i mport j ava. ut i l . Vect or; i mport org. apache. axi s. * ; i mport org. apache. axi s. message. *; i mport org. apache. axi s. handl ers. Basi cHandl er; i mport org. apache. axi s. encodi ng. SOAPTypeMappi ngRegi st ry; i mport bws. BookUt i l ; i mport com.skat est own. backend. Emai l Conf i rmat i on; /**

  • EMai l header handl er
  • / publ i c cl ass EMai l Handl er ext ends Basi cHandl er { /**
  • Ut i l i t y met hod t o ret ri eve RPC paramet ers * f rom a SOAP message.
  • / pri vat e Obj ect get Param(Vect or params, i nt i ndex) { ret urn ( ( RPCParam)params. get ( i ndex) ) . get Val ue( ) ; } /**
  • Looks f or t he EMai l header and sends an emai l
  • conf i rmat i on message based on t he i nvent ory check
  • request and t he resul t of t he i nvent ory check
  • / publ i c voi d i nvoke( MessageCont ext msgCont ext ) t hrows Axi sFaul t
t ry { // At t empt t o ret ri eve EMai l header Message reqMsg = msgCont ext . get Request Message( ) ; SOAPEnvel ope reqEnv = reqMsg. get AsSOAPEnvel ope( ) ; SOAPHeader header = reqEnv. get HeaderByName( "ht t p: //www. skat est own. com/", "EMai l " ) ; i f ( header ! = nul l ) { // Mark t he header as havi ng been processed header. set Processed( t rue) ; // Get emai l address i n header St ri ng emai l = ( St ri ng) header. get Val ueAsType( SOAPTypeMappi ngRegi st ry. XSD_STRI NG) ; // Ret ri eve request paramet ers: SKU & quant i t y RPCEl ement reqRPC = ( RPCEl ement ) reqEnv. get Fi rst Body( ) ; Vect or params = reqRPC. get Params( ) ; St ri ng sku = ( St ri ng) get Param(params, 0) ; I nt eger quant i t y = ( I nt eger) get Param(params, 0) ; // Ret ri eve i nvent ory check resul t Message respMsg = msgCont ext . get ResponseMessage( ) ; SOAPEnvel ope respEnv = respMsg. get AsSOAPEnvel ope( ) ;

RPCEl ement respRPC = ( RPCEl ement ) respEnv. get Fi rst Body( ) ;

Bool ean resul t = ( Bool ean) get Param( respRPC. get Params( ) , 0) ; // Send conf i rmat i on emai l Emai l Conf i rmat i on ec = new Emai l Conf i rmat i on( BookUt i l . get ResourcePat h( msgCont ext , "/resources/emai l . l og") ) ; ec. send( emai l , sku, quant i t y. i nt Val ue( ) , resul t . bool eanVal ue( ) ) ; } } cat ch( Except i on e) { t hrow new Axi sFaul t ( e) ; } } /**

  • Requi red met hod of handl ers. No- op i n t hi s case
  • /

  { } }

  I t 's sim ple code, but it does t ake a few lines because several layers need t o be unw rapped t o get t o t he RPC param et ers. When all dat a has been ret rieved, t he handler calls t he e- m ail confirm at ion backend, w hich, in t his exam ple, logs e- m ails " sent " t o

  /resources/email.log .

  Finally, adding deploym ent inform at ion about t he new header handler and t he invent ory check service involves m aking a sm all change t o t he Axis Web services deploym ent

  /resources/deploy.xml descript or. The book exam ple deploym ent descript or is in .

  Working w it h Axis deploym ent descript ors w ill be described in det ail in Chapt er 4 .

  

List ing 3.7 show s t he five lines of XML t hat need t o be added. First , t he e- m ail handler is

  regist ered by associat ing a handler nam e wit h it s Java class nam e. Following t hat is t he descript ion of t he invent ory check service. The service opt ions ident ify t he Java class nam e for t he service and t he m et hod t hat im plem ent s t he service funct ionalit y. The service elem ent has t w o at t ribut es. Pivot is an Axis t erm t hat specifies t he t ype of

  RPCDispatcher InventoryCheck

  service. I n t his case, t he value is , w hich im plies t hat is an RPC service. The response at t ribut e specifies t he nam e of a handler t hat w ill be called aft er t he service is invoked. Because t he book exam ples don't rely on an e- m ail server being present , inst ead of sending confirm at ion t his class w rit es m essages t o a log file in

  /resources/email.log .

  Listing 3.7 Deployment Descriptor for Inventory Check Service

  <! - - Chapt er 3 exampl e 3 servi ces - - > <handl er name="Emai l " cl ass="com.skat est own. servi ces. EMai l Handl er"/> <servi ce name="I nvent oryCheck" pi vot ="RPCDi spat cher" response="Emai l "> <opt i on name="cl assName" val ue="com.skat est own. servi ces. I nvent oryCheck"/> <opt i on name="met hodName" val ue="doCheck"/> </servi ce> Putting the Service to the Test

  Wit h all t hese changes in place, w e are ready t o t est t he im proved invent ory check

  ch3/ex3/index.jsp

  service. There is a sim ple JSP t est harness in t hat is m odeled aft er t he JSP t est harness w e used for t he JWS- based invent ory check service ( see Figure 3.6 ) .

Figure 3.6. Putting the enhanced inventory check Web service to the test. SOAP on the Wire

  Wit h t he help of TCPMon, w e can see w hat SOAP m essages are passing bet w een t he client and t he Axis engine. We are only int erest ed in seeing t he request m essage because

  EMail t he response m essage w ill be ident ical t o t he one before t he header w as added. EMail

  Here is t he SOAP request m essage w it h t he header present :

  POST /bws/servi ces/I nvent oryCheck HTTP/1. 0 Cont ent - Lengt h: 482 Host : l ocal host Cont ent - Type: t ext /xml; charset =ut f - 8 SOAPAct i on: "/doCheck" <?xml versi on="1. 0" encodi ng="UTF- 8"?> <SOAP- ENV: Envel ope SOAP- ENV: encodi ngSt yl e="ht t p: //schemas. xmlsoap. org/soap/encodi ng/" xmlns: xsd="ht t p: //www. w3. org/2001/XMLSchema" xmlns: SOAP- ENV="ht t p: //schemas. xmlsoap. org/soap/envel ope/" xmlns: xsi ="ht t p: //www. w3. org/2001/XMLSchema- i nst ance"> <SOAP- ENV: Header> <e: EMai l xmlns: e="ht t p: //www. skat est own. com/ns/emai l "> conf i rm@part ners. com </e: EMai l > </SOAP- ENV: Header> <SOAP- ENV: Body> <ns1: doCheck xmlns: ns1="Avai l abi l i t yCheck"> <arg0 xsi : t ype="xsd: st ri ng">947- TI </arg0> <arg1 xsi : t ype="xsd: i nt ">1</arg1> </ns1: doCheck>

  </SOAP- ENV: Envel ope>

  There are no surprises in t he SOAP m essage. However, a couple of t hings have changed

  /bws/services/InventoryCheck

  in t he HTTP m essage. First , t he t arget URL is . This is a com binat ion of t w o part s: t he URL of t he Axis servlet t hat list ens for SOAP request s over

  /bws/services

  HTTP ( ) and t he nam e of t he service w e w ant t o invoke

  InventoryCheck SOAPAction

  ( ) . Also, t he header, w hich w as previously em pt y, now cont ains t he nam e of t he m et hod w e w ant t o invoke. The service nam e on t he URL and

  SOAPAction

  t he m et hod nam e in are bot h hint s t o Axis about t he service w e w ant t o invoke. That 's all t here is t o t aking advant age of SOAP cust om headers. The key m essage is one of sim ple yet flexible ext ensibilit y. Rem em ber, t he invent ory check service im plem ent at ion did not change at all!

  SOAP Intermediaries

  So far, w e have addressed SOAP headers as a m eans for vert ical ext ensibilit y w it hin SOAP m essages. There is anot her relat ed not ion, how ever: horizont al ext ensibilit y . Vert ical ext ensibilit y is about t he abilit y t o int roduce new pieces of inform at ion w it hin a SOAP m essage, and horizont al ext ensibilit y is about t arget ing different part s of t he sam e SOAP m essage t o different recipient s. Horizont al ext ensibilit y is provided by SOAP int erm ediaries .

The Need for Intermediaries

  SOAP int erm ediaries are applicat ions t hat can process part s of a SOAP m essage as it t ravels from it s originat ion point t o it s final dest inat ion point ( see Figure 3.7 ) . I nt erm ediaries can bot h accept and forw ard SOAP m essages. Three key use- cases define t he need for SOAP int erm ediaries: crossing t rust dom ains, ensuring scalabilit y, and providing value- added services along t he SOAP m essage pat h.

Figure 3.7. Intermediaries on the SOAP message path.

  Crossing t rust dom ains is a com m on issue faced while im plem ent ing securit y in dist ribut ed syst em s. Consider t he relat ion bet w een a corporat e or depart m ent al net w ork and t he I nt ernet . For sm all organizat ions, it is likely t hat t he I T depart m ent has put m ost com put ers on t he net w ork w it hin a single t rust ed securit y dom ain. Em ployees can see t heir co- w orkers com put ers as w ell as t he I T servers and t hey can freely exchange inform at ion bet w een t hem w it hout t he need for separat e logons. On t he ot her hand, t he corporat e net w ork probably t reat s all com put ers on t he I nt ernet as part of a separat e securit y dom ain t hat is not t rust ed. Before an I nt ernet request reaches t he net w ork, it needs t o cross from it s unt rust w ort hy dom ain t o t he t rust ed dom ain of t he net w ork. Corporat e firew alls and virt ual privat e net w ork ( VPN) gat ew ays are t he Cerberean guards of t he gat es t o t he net w ork's riches. Their j ob is t o let som e request s cross t he t rust dom ain boundary and deny access t o ot hers. Anot her im port ant need for int erm ediaries arises because of t he scalabilit y requirem ent s of dist ribut ed syst em s. A sim plist ic view of dist ribut ed syst em s could ident ify t w o t ypes of ent it ies: t hose t hat request som e w ork t o be done ( client s) and t hose t hat do t he w ork ( servers) . Client s send m essages direct ly t o t he servers wit h which t hey want t o com m unicat e. Servers, in t urn, get som e w ork done and respond. I n t his naïve universe, t here is lit t le need for dist ribut ed com put ing infrast ruct ure. Alas, you cannot use t his m odel t o build highly scalable dist ribut ed syst em s. Take basic e- m ail as an exam ple—t he service w e've grow n t o depend on so m uch in t he

  someone@company.com

  Net era. When sends an e- m ail m essage t o

  m yfriend@london.co.uk , it is definit ely not t he case t hat t heir e- m ail client locat es t he

  m ail server london.co.uk and sends t he m essage t o it . I nst ead, t he client sends t he

  company.com

  m essage t o it s e- m ail server at . Based on t he priorit y of t he m essage and how busy t he m ail server is, t he m essage w ill leave eit her by it self or in a bat ch of ot her m essages. Messages are oft en bat ched t o im prove perform ance. I t is likely t hat t he m essage w ill m ake a few hops t hrough different nodes on t he I nt ernet before it get s t o t he m ail server in London. The lesson from t his exam ple is t hat highly scalable dist ribut ed syst em s ( such as e- m ail) require flexible buffering of m essages and rout ing based not only on m essage param et ers such as origin, dest inat ion, and priorit y but also on t he st at e of t he syst em m easured by param et ers such as t he availabilit y and load of it s nodes as w ell as net w ork t raffic inform at ion. I nt erm ediaries hidden from t he eyes of t he originat ors and final recipient s of m essages perform all t his w ork behind t he scenes.

  Last but not least , you need int erm ediaries so t hat you can provide value- added services in a dist ribut ed syst em . The t ype of services can vary significant ly. Here are a couple of com m on exam ples:

  • Securing message exchanges, particularly when transmitting messages

  through untrustworthy domains, such as using HTTP/SMTP on the Internet. You could secure SOAP messages by passing them through an intermediary that first encrypts them and then digitally signs them.

On the receiving side, an intermediary will perform the inverse

operations—checking the digital signature and, if it is valid,

decrypting the message. Providing message-tracing facilities. Tracing allows the recipient of • messages to find out the exact path that the message went through complete with detailed timings of arrivals and departures to and from intermediaries along the way. This information is indispensable for tasks such as measuring quality of service (QoS), auditing systems, and identifying scalability bottlenecks.

  Intermediaries in SOAP

  As t he previous sect ion has show n, int erm ediaries are an ext rem ely im port ant concept in dist ribut ed syst em s. SOAP is specifically designed w it h int erm ediaries in m ind. I t has sim ple yet flexible facilit ies t hat address t he t hree key aspect s of an int erm ediary- enabled archit ect ure:

  How do you pass information to intermediaries? • How do you identify who should process what?

  • What happens to information that is processed by intermediaries? •

  From t he discussion of int erm ediaries, you can see t hat m ost of t he inform at ion t hat int erm ediaries require is com plet ely ort hogonal t o t he inform at ion cont ained in SOAP not is irrelevant t o t he invent ory check service. Therefore, only inform at ion in SOAP headers can be explicit ly t arget ed at int erm ediaries. The quest ion t hen becom es one of deciding how t o t arget t he recipient of a part icular header. This does not m ean t hat an int erm ediary cannot look at , process, or change t he SOAP m essage body; it cert ainly can do t hat . How ever, SOAP it self defines no m echanism t o inst ruct an int erm ediary t o do t hat . Cont rast t his t o a SOAP m essage explicit ly t arget ing a piece of inform at ion cont ained in a SOAP header at an int erm ediary w it h t he underst anding t hat it m ust at least at t em pt t o process it .

  SOAP-ENV:actor

  All header elem ent s can opt ionally have t he at t ribut e. The value of t he at t ribut e is a URI t hat ident ifies w ho should handle t he header ent ry. Essent ially, t hat URI is t he " nam e" of t he int erm ediary. The special value

  

ht t p: / / schem as.xm lsoap.org/ soap/ act or/ next indicat es t hat t he header ent ry's recipient

  is t he next SOAP applicat ion t hat processes t he m essage. This is useful for hop- by- hop processing required, for exam ple, by m essage t racing. Of course, om it t ing t he act or at t ribut e im plies t hat t he final recipient of t he SOAP m essage should process t he header ent ry. The m essage body is int ended for t he final recipient of t he SOAP m essage.

  The issue of w hat happens t o a header t hat is processed by an int erm ediary is a lit t le t rickier. The SOAP specificat ion st at es, " t he role of a recipient of a header elem ent is sim ilar t o t hat of accept ing a cont ract in t hat it cannot be ext ended beyond t he recipient ." This m eans t hat t he int erm ediary should rem ove any header t arget ed for it t hat it has processed. The int erm ediary is free t o int roduce a new header in t he m essage t hat looks t he sam e but t hen t his const it ut es a cont ract bet w een t he int erm ediary and t he next applicat ion. The goal here is t o reduce syst em com plexit y by requiring t hat cont ract s about t he presence, absence, and cont ent of inform at ion in SOAP m essages be very narrow in scope—from t he originat or of t hat inform at ion t o t he first SOAP applicat ion t hat handles it and not beyond.

Putting It All Together

  To get a bet t er sense of how you m ight use int erm ediaries in t he real w orld, let 's consider t he pot ent ially realist ic albeit cont rived exam ple of Skat esTow n's overall B2B int egrat ion archit ect ure. Please keep in m ind t hat all XML in t he exam ple is purely fict ional—current ly t here isn't a st andardized w ay t o handle securit y and rout ing of SOAP m essages. Skat esTow n needs t o int egrat e various applicat ions in several of it s depart m ent s w it h som e of it s part ners' applicat ions ( see Figure 3.8 ) . Silver Bullet Consult ing st art ed w orking w it h t he purchasing depart m ent building Web services t o aut om at e business funct ions such as checking invent ory. Following t he success of t his engagem ent , Silver Bullet Consult ing has been asked t o use Web services t o aut om at e processes in ot her depart m ent s such as cust om er service. Skat esTown's corporat e I T depart m ent is dem anding cent ralized cont rol over t he ent ry point of all Web service request s t o t he com pany. They also require t hat all SOAP m essages be t ransm it t ed over HTTPS for securit y reasons.

Figure 3.8. SkatesTown's system integration architecture. At t he sam e t im e, individual depart m ent s dem and t hat t heir ow n I T unit s cont rol t he servers t hat run t heir ow n Web services. These servers have t heir ow n t rust dom ains and are sit t ing deep inside t he corporat e net w ork, invisible t o t he out side w orld. To address t his issue, Silver Bullet Consult ing develops a part ner int erface gat ew ay SOAP applicat ion t hat act s as an int erm ediary bet w een t he part ner applicat ions sending SOAP m essages and t he depart m ent - level applicat ions t hat are handling t hem . The gat ew ay applicat ion is host ed on an applicat ion server t hat is visible t o t he part ner applicat ions. This server is m anaged by t he corporat e I T depart m ent . A firew all is configured t o allow access t o t he gat ew ay applicat ion from t he part ner net w orks only. The gat ew ay applicat ion has t he responsibilit y t o validat e part ners' securit y credent ials and t o rout e m essages t o t he appropriat e depart m ent al SOAP applicat ions. Securit y inform at ion and depart m ent server locat ions are available from Skat esTow n's ent erprise direct ory.

  Here is an exam ple m essage t he gat ew ay applicat ion m ight receive:

  POST /bws/i nvent ory/I nvent oryCheck HTTP/1. 0 Host : part nergat eway. skat est own. com Cont ent - Type: t ext /xml; charset ="ut f - 8" Cont ent - Lengt h: nnnn SOAPAct i on: "/doCheck" <?xml versi on="1. 0" encodi ng="UTF- 8"?> <SOAP- ENV: Envel ope SOAP- ENV: encodi ngSt yl e="ht t p: //schemas. xmlsoap. org/soap/encodi ng/" xmlns: xsd="ht t p: //www. w3. org/2001/XMLSchema" xmlns: SOAP- ENV="ht t p: //schemas. xmlsoap. org/soap/envel ope/" xmlns: xsi ="ht t p: //www. w3. org/2001/XMLSchema- i nst ance"> <SOAP- ENV: Header> <t d: Target Depart ment xmlns: t d="ht t p: //www. skat est own. com/ns/part nergat eway"

  SOAP- ENV: must Underst and="1"> Purchasi ng </t d: Target Depart ment > <ai : Aut hent i cat i onI nf ormat i on xmlns: ai ="ht t p: //www. skat est own. com/ns/securi t y" SOAP- ENV: act or="urn: X- Skat esTown: Part nerGat eway" SOAP- ENV: must Underst and="1"> <username>Part nerA</username> <password>LongLi veSOAP</password> </ai : Aut hent i cat i onI nf ormat i on> </SOAP- ENV: Header> <SOAP- ENV: Body> <doCheck> <arg0 xsi : t ype="xsd: st ri ng">947- TI </arg0> <arg1 xsi : t ype="xsd: i nt ">1</arg1> </doCheck> </SOAP- ENV: Body> </SOAP- ENV: Envel ope>

  There are t w o header ent ries. The first ident ifies t he t arget depart m ent as purchasing, and t he second passes t he aut hent icat ion inform at ion of t he m essage originat or, part ner

  mustUnderstand="1"

  A in t his case. Bot h header ent ries are m arked w it h because t hey are crit ical t o t he successful processing of t he m essage. The part ner gat ew ay applicat ion is ident ified by t he act or at t ribut e as t he place t o process t hese. Aft er processing t he m essage, t he part ner gat ew ay applicat ion m ight forw ard t he follow ing m essage:

  POST /bws/servi ces/I nvent oryCheck HTTP/1. 0 Host : purchasi ng. skat est own. com Cont ent - Type: t ext /xml; charset ="ut f - 8" Cont ent - Lengt h: nnnn SOAPAct i on: "/doCheck" <?xml versi on="1. 0" encodi ng="UTF- 8"?> <SOAP- ENV: Envel ope SOAP- ENV: encodi ngSt yl e="ht t p: //schemas. xmlsoap. org/soap/encodi ng/" xmlns: xsd="ht t p: //www. w3. org/2001/XMLSchema" xmlns: SOAP- ENV="ht t p: //schemas. xmlsoap. org/soap/envel ope/" xmlns: xsi ="ht t p: //www. w3. org/2001/XMLSchema- i nst ance"> <SOAP- ENV: Header> <cc: Cl i ent Credent i al s xmlns: cc="ht t p: //schemas. securi t y. org/soap/securi t y" SOAP- ENV: must Underst and="1"> <Cl i ent I D>/Ext ernal /Part ners/Part nerA</Cl i ent I D> </cc: Cl i ent Credent i al s> </SOAP- ENV: Header> <SOAP- ENV: Body> <doCheck> <arg0 xsi : t ype="xsd: st ri ng">947- TI </arg0> <arg1 xsi : t ype="xsd: i nt ">1</arg1>

  </SOAP- ENV: Body> </SOAP- ENV: Envel ope>

  Not e how t he previous t w o header ent ries have disappeared. They w ere m eant for t he gat ew ay applicat ion only. Having ext ract ed t he purchasing depart m ent 's locat ion from t he ent erprise direct ory, t he gat ew ay applicat ion forw ards t he m essage t o

  purchasing.skatestown.com

  . A new header ent ry is m eant for t he final recipient of t he m essage. The ent ry specifies t he securit y ident it y of t he m essage originat or as

  /External/Partners/PartnerA

  . This ident it y w as presum ably obt ained from Skat esTown's securit y syst em following t he successful aut hent icat ion of part ner A. The applicat ions in t he purchasing depart m ent w ill use t his ident it y t o check w het her part ner A is aut horized t o perform t he operat ion request ed in t he SOAP m essage body.

  This exam ple scenario show s t hat int erm ediaries bring significant capabilit ies t o SOAP- enabled applicat ions and can be int roduced and im plem ent ed at a fairly low cost . The invent ory check service im plem ent at ion does not need t o change. The part ner gat ew ay does not need t o know anyt hing about invent ory checking; it only underst ands t he t arget depart m ent and aut hent icat ion headers. I nvent ory check client s only need t o add a couple of headers t o t he m essages t hey are sending t o fit in t he new archit ect ure.

  Error Handling in SOAP

  So far in our exam ples everyt hing has gone according t o plan. Murphy's Law guarant ees t hat t his is not how t hings w ork out in t he real w orld. What w ould happen, for exam ple, if part ner A failed t o aut hent icat e w it h t he part ner gat ew ay applicat ion? How w ill t his except ional condit ion be com m unicat ed via SOAP? The answer lies in t he sem ant ics of

  Fault t he SOAP elem ent .

  Consider t he follow ing possible reply m essage caused by t he aut hent icat ion failure:

  HTTP/1. 0 500 I nt ernal Server Error Cont ent - Type: t ext /xml; charset ="ut f - 8" Cont ent - Lengt h: nnnn <SOAP- ENV: Envel ope xmlns: SOAP- ENV="ht t p: //schemas. xmlsoap. org/soap/envel ope/" SOAP- ENV: encodi ngSt yl e="ht t p: //schemas. xmlsoap. org/soap/encodi ng/"> <SOAP- ENV: Body> <SOAP- ENV: Faul t > <f aul t code>Cl i ent . Aut hent i cat i onFai l ure</f aul t code> <f aul t st ri ng>Fai l ed t o aut hent i cat e cl i ent </f aul t st ri ng> <f aul t act or>urn: X- Skat esTown: Part nerGat eway</f aul t act or> </SOAP- ENV: Faul t > </SOAP- ENV: Body> </SOAP- ENV: Envel ope>

  500 Internal Server

  Before we look at t he XML, not e t hat t he HTTP response code is

  Error

  . This is a required response in t he case of any SOAP- relat ed error by t he HTTP t ransport binding as present ed in t he SOAP specificat ion. Ot her prot ocols w ill have t heir ow n w ay t o report errors. The HTTP SOAP binding is discussed in det ail in t he sect ion " SOAP Prot ocol Bindings ."

  Fault

  The body of t he response cont ains a single elem ent in t he SOAP envelope nam espace. SOAP uses t his m echanism t o indicat e t hat an error has occurred and t o faultcode

  The elem ent m ust be present in all cases. I t provides inform at ion t hat can be used t o ident ify t he specific error t hat occurred. I t is not m eant for hum an consum pt ion.

  faultcode

  The cont ent of t he elem ent is a st ring prefixed by one of t he four values specified by SOAP:

  • VersionMismatch indicates that the namespace of the Envelope element is invalid.
  • MustUnderstand indicates that a required header entry was not understood.
  • Client

  indicates that likely cause of the error lies in the content or formatting of the SOAP message. In other words, the client should probably not re-send the message without making some changes to it.

  • Server indicates that the message failed due to reasons other than

  its content or its format. This leaves the door open for the same message to perhaps succeed at a later time.

  A hierarchical nam espace of values can be obt ained by separat ing fault values w it h t he

  Client.AuthenticationFailure

  dot ( .) charact er. I n our exam ple, is a m ore specific

  Client fault code t han . faultstring

  The elem ent cont ains a hum an- readable m essage ident ifying t he cause of t he fault . I t m ust alw ays be present . Here w e sim ply st at e t hat t he client has failed t o aut hent icat e.

  faultactor

  The elem ent provides inform at ion about w here in t he m essage pat h t he fault occurred. I t m ust be present if t he failure occurred som ew here ot her t han at t he final dest inat ion of t he SOAP m essage. The cont ent of t he elem ent is t he URI of t he act or w here t he error occurred. I n our exam ple, w e ident ify t he part ner gat ew ay applicat ion as t he failure point . What is not show n in t his exam ple is how applicat ion- specific error diagnost ic inform at ion can be exchanged. SOAP provides a sim ple m echanism for t his, as w ell. I f t he fault

  detail

  occurred during t he processing of t he m essage body, an opt ional elem ent can be

  faultactor

  added aft er . There are no rest rict ions on it s cont ent s. This rule has one im port ant except ion: I f t he fault occurred during t he processing of a header ent ry, a

  detail

  elem ent cannot be ret urned. I nst ead, t he header ent ry should be ret urned w it h det ailed error inform at ion cont ained t herein. This is t he m echanism SOAP uses t o det erm ine w het her a fault w as t he result of header versus body processing.

  SOAP Message Processing mustUnderstand

  Now t hat w e have covered headers w it h behavior, int erm ediaries, and error handling, w e can com plet ely define t he rules for SOAP m essage processing. Upon receiving a m essage, a SOAP applicat ion m ust :

  1. Determine whether it understands the version of SOAP that the message

Envelope uses by inspecting the namespace value of the SOAP element

  If the version is unknown, it must discard the message with a VersionMismatch error. Otherwise, it has to move to the next step.

  2. Identify all parts of the message intended for the application.

  

Typically this is done considering the application's role in the message path (intermediary or final recipient) and the values of the

actor global attribute, but other information can be taken into

account as well.

  

3. Verify that all mandatory parts of the message identified in Step 2

are supported by the application. These include mustUnderstand

headers and, in the case of a final recipient, the body. If any

mandatory part cannot be supported, the message is discarded with a MustUnderstand error in the case of headers and an application- specific error in the case of bodies. Otherwise, the application will move to Step 4.

  

4. Process all mandatory parts identified in Step 2 plus any optional

parts that it knows about.

  5. If the application is not the final recipient of the message, it must remove all headers that it has processed before passing the message forward along its path.

  Having covered t he SOAP envelope fram ew ork, int erm ediaries, and error handling, it is now t im e t o m ove t o ot her areas of t he SOAP specificat ion.

  SOAP Data Encoding

  Anot her im port ant area of SOAP has t o do w it h t he rules and m echanism s for encoding dat a in SOAP m essages. So far, our Web service exam ple, t he invent ory check, has dealt only w it h very sim ple dat at ypes: st rings, int egers, and booleans. All t hese t ypes have

  xsi:type

  direct represent at ion in XML Schem a so it w as easy, t hrough t he use of t he at t ribut e, t o describe t he t ype of dat a being passed in a m essage. What w ould happen if our Web services needed t o exchange m ore com plex t ypes, such as arrays and arbit rary obj ect s? What algorit hm should be used t o det erm ine t heir represent at ion in XML form at ? I n addit ion, given SOAP's ext ensibilit y requirem ent s, how can a SOAP m essage specify different encoding algorit hm s? This sect ion addresses such quest ions.

  Specifying Different Encodings

  SOAP provides an elegant m echanism for specifying t he encoding rules t hat apply t o t he

  encodingStyle

  m essage as a w hole or any port ion of it . This is done via t he at t ribut e in t he SOAP envelope nam espace. The at t ribut e is defined as global in t he SOAP schem a; it can appear w it h any elem ent , allow ing different encoding st yles t o be m ixed and

  encodingStyle

  m at ched in a SOAP m essage. An at t ribut e applies t o t he elem ent it decorat es and it s cont ent , excluding any children t hat m ight have t heir ow n

  encodingStyle

  at t ribut e. Therefore, any elem ent in a SOAP m essage can have eit her no encoding st yle specified or exact ly one encoding st yle. The rules for det erm ining t he encoding st yle of an elem ent are sim ple:

  encodingStyle

  1. If an element has the attribute, then its encoding style is equal to the value of that attribute.

  

2. Otherwise, the encoding style is equal to the encoding style of the

encodingStyle

closest ancestor element that has the attribute…

3. …Unless there is no such ancestor, which implies that the element

  SOAP-

  SOAP defines one part icular set of dat a encoding rules. They are ident ified by

  ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding"

  in SOAP

  Envelope

  m essages. You w ill oft en see t his at t ribut e applied direct ly t o t he elem ent in a SOAP m essage. There is no not ion of default encoding in a SOAP m essage. Encoding st yle m ust be explicit ly specified.

  Despit e t he fact t hat t he SOAP specificat ion defines t hese encoding rules, it does not m andat e t hem . SOAP im plem ent at ions are free t o choose t heir ow n encoding st yles. There are cost s and benefit s t o m aking t his choice. A benefit could be t hat t he im plem ent at ions can choose a m ore opt im ized dat a encoding m echanism t han t he one defined by t he SOAP specificat ion. For exam ple, som e SOAP engines already on t he m arket det ect w het her t hey are exchanging SOAP m essages w it h t he sam e t ype of engine and, if so, sw it ch t o a highly opt im ized binary dat a encoding form at . Because t his sw it ch happens only w hen bot h ends of a com m unicat ion channel agree t o it , int eroperabilit y is not hindered. At t he sam e t im e, how ever, support ing t hese different encodings does have an associat ed m aint enance cost , and it is difficult for ot her vendors t o t ake advant age of t he benefit s of an opt im ized dat a encoding.

  SOAP Data Encoding Rules

  The SOAP dat a encoding rules exist t o provide a w ell- defined m apping bet w een abst ract dat a m odels ( ADMs) and XML synt ax. ADMs can be m apped t o direct ed labeled graphs ( DLGs) —collect ions of nam ed nodes and nam ed direct ed edges connect ing t w o nodes. For Web services, ADMs t ypically represent program m ing language and dat abase dat a st ruct ures. The SOAP encoding rules define algorit hm s for execut ing t he follow ing t hree t asks:

  Given meta-data about an ADM, construct an XML schema from it. • Given an instance graph of the data model, we can generate XML that • conforms to the schema. This is the serialization operation.

Given XML that conforms to the schema, we can create an instance

  • graph that conforms to the abstract data model's schema. This is the deserialization operation. Further, if we follow serialization by deserialization, we should obtain an identical instance graph to the one we started with.

  Alt hough t he purpose of t he SOAP dat a encoding is so sim ple t o describe, t he act ual rules can be som ew hat com plicat ed. This sect ion is only m eant t o provide an overview of t opic. I nt erest ed readers should pursue t he dat a encoding sect ion of t he SOAP Specificat ion. Basic Rules The SOAP encoding uses a t ype syst em based on XML Schem a. Types are schem a t ypes.

  Sim ple t ypes ( oft en know n as scalar t ypes in program m ing languages) m ap t o t he

  float positiveInteger string date

  built - in t ypes in XML Schem a. Exam ples include , , , , and any rest rict ions of t hese, such as an enum erat ion of RGB colors derived by

  xsd:string

  rest rict ing t o only " red" , " green" , and " blue" . Com pound t ypes are com posed of several part s, each of which has an associat ed t ype. The part s of a com pound t ype are dist inguished by an accessor . An accessor can use t he nam e of a part or it s posit ion relat ive t o ot her part s in t he XML represent at ion of values. St ruct s are com pound t ypes w hose part s are dist inguished only by t heir nam e. Arrays

  Values are inst ances of t ypes, m uch in t he sam e way t hat a st ring obj ect in Java is an

  java.lang.String

  inst ance of t he class. Values are represent ed as XML elem ent s w hose t ype is t he value t ype. Sim ple values are encoded as t he cont ent of elem ent s t hat have a sim ple t ype. I n ot her w ords, t he elem ent s t hat represent sim ple values have no child elem ent s. Com pound values are encoded as t he cont ent of elem ent s t hat have a com pound t ype. The part s of t he com pound value are encoded as child elem ent s w hose nam es and/ or posit ions are t hose of t he part accessors. Not e t hat values can never be encoded as at t ribut es. The use of at t ribut es is reserved for t he SOAP encoding it self, as you w ill see a bit lat er.

  Values w hose elem ent s appear at t he t op level of t he serializat ion are considered independent , w hereas all ot her values are em bedded ( t heir parent is a value elem ent ) . The follow ing snippet show s an exam ple XML schem a fragm ent describing a person w it h a nam e and an address. I t also shows t he associat ed XML encoding of t hat schem a according t o t he SOAP encoding rules:

  <! - - Thi s i s an exampl e schema f ragment - - > <xsd: el ement name="Person" t ype="Person"/> <xsd: compl exType name="Person"> <xsd: sequence> <xsd: el ement name="name" t ype="xsd: st ri ng"/> <xsd: el ement name="address" t ype="Address"/> </xsd: sequence> <! - - Thi s i s needed f or SOAP encodi ng use; t here may be a need t o speci f y some encodi ng paramet ers, e. g. , encodi ngSt yl e, t hrough t he use of at t ri but es - - > <xsd: anyAt t ri but e namespace="##ot her" processCont ent s="st ri ct "/> </xsd: compl exType> <xsd: el ement name="Address" t ype="Address"/> <xsd: compl exType name="Address"> <xsd: sequence> <xsd: el ement name="st reet " t ype="xsd: st ri ng"/> <xsd: el ement name="ci t y" t ype="xsd: st ri ng"/> <xsd: el ement name="st at e" t ype="USSt at e"/> </xsd: sequence> <! - - Same as above i n Person - - > <xsd: anyAt t ri but e namespace="##ot her" processCont ent s="st ri ct "/> </xsd: compl exType> <xsd: si mpl eType name="USSt at e"> <xsd: rest ri ct i on base="xsd: st ri ng"> <xsd: enumerat i on val ue="AK"/> <xsd: enumerat i on val ue="AL"/> <xsd: enumerat i on val ue="AR"/> <! - - . . . - - > </xsd: rest ri ct i on> </xsd: si mpl eType>

  <! - - Thi s i s an exampl e encodi ng f ragment usi ng t hi s schema - - > <! - - Thi s val ue i s of compound t ype Person ( a st ruct ) - - > <p: Person> <! - - Si mpl e val ue wi t h accessor "name" i s of t ype xsd: st ri ng - - > <name>Bob Smit h</name> <! - - Nest ed compound val ue address - - > <address> <st reet >1200 Rol l i ng Lane</st reet > <ci t y>Bost on</ci t y> <! - - Act ual st at e t ype i s a rest ri ct i on of xsd: st ri ng - - > <st at e>MA</st at e> </address> </p: Person>

  One t hing should be apparent : The SOAP encoding rules are designed t o fit w ell w it h t radit ional uses of XML for dat a- orient ed applicat ions. The exam ple encoding has no m ent ion of any SOAP- specific m arkup. This is a good t hing. Identifying Value Types When full schem a inform at ion is available, it is easy t o associat e values w it h t heir t ypes.

  I n som e cases, how ever, t his is hard t o do. Som et im es, a schem a w ill not be available. I n t hese cases, Web service int eract ion part icipant s should do t heir best t o m ake

  xsi:type

  m essages as self- describing as possible by using at t ribut es t o t ag t he t ype of at least all sim ple values. Furt her, t hey can do som e guessing by inspect ing t he m arkup t o det erm ine how t o deserialize t he XML. Of course, t his is difficult . The only ot her alt ernat ive is t o est ablish agreem ent in t he Web services indust ry about t he encoding of cert ain generic abst ract dat a t ypes. The SOAP encoding does t his for arrays. Ot her t im es, schem a inform at ion m ight be available, but t he cont ent m odel of t he schem a elem ent w ill not allow you t o sufficient ly narrow t he t ype of cont ained values. For

  xsi:type

  exam ple, if t he schem a cont ent t ype is " any" , it again m akes sense t o use as m uch as possible t o specify t he exact t ype of value t hat is being t ransferred. The sam e considerat ions apply w hen you're dealing w it h t ype inherit ance, w hich is allow ed by bot h XML Schem a and all obj ect - orient ed program m ing languages. The SOAP encoding allow s a sub- t ype t o appear in any place w here a super- t ype can appear.

  xsi:type

  Wit hout t he use of , it w ill be im possible t o perform good deserializat ion of t he dat a in a SOAP m essage. Som et im es you won't know t he nam es of t he value accessors in advance. Rem em ber how Axis aut o- generat es elem ent nam es for t he param et ers of RPC calls? Anot her exam ple w ould be t he nam es of values in an array—t he nam es really don't m at t er; only

  xsi:type

  t heir posit ion does. For t hese cases, could be used t oget her w it h aut o- generat ed elem ent nam es. Alt ernat ively, t he SOAP encoding defines elem ent s w it h

  SOAP-ENC:int SOAP-

  nam es t hat m at ch t he basic XML Schem a t ypes, such as or

  ENC:string

  . These elem ent s could be used direct ly as a w ay t o com bine nam e and t ype inform at ion in one. Of course, t his pat t ern cannot be used for com pound t y pes. SOAP Arrays Arrays are one of t he fundam ent al dat a st ruct ures in program m ing languages. ( Can you t hink of a useful applicat ion t hat does not use arrays?) Therefore, it is no surprise t hat t he SOAP dat a encoding has det ailed rules for represent ing arrays. The key requirem ent

  SOAP-ENC:Array is t hat array t ypes m ust be represent ed by a or a t ype derived from it . array. This is one exam ple w here t he SOAP encoding int roduces an at t ribut e and anot her reason w hy values in SOAP are encoded using only elem ent cont ent or child elem ent s.

  arrayType

Table 3.1 shows several exam ples of possible values. The form at of t he

  at t ribut e is sim ple. The first port ion specifies t he cont ained elem ent t ype. This is expressed as a fully qualified XML t ype nam e ( QNam e) . Com pound t ypes can be freely used as array elem ent s. I f t he cont ained elem ent s are t hem selves arrays, t he QNam e is follow ed by an indicat ion of t he array dim ensions, such as [ ] and [ ,] for one- and t w o-

  arrayType

  dim ensional arrays, respect ively. The second port ion of specifies t he size and dim ensions of t he array, such as [ 5] or [ 2,3] . There is no lim it t o t he num ber of array dim ensions and t heir size. All posit ion indexes are zero- based, and m ult idim ensional arrays are encoded such t hat t he right m ost posit ion index changes t he quickest .

Table 3.1. Example SOAP-ENC:arrayType Values

  arrayType Value Description xsd:int[5]

  An array of five integers xsd:int[][5]

  An array of five integer arrays xsd:int[,][5]

  An array of five two-dimensional arrays of integers p:Person[5]

  An array of five people xsd:string[2,3]

  

A 2x3, two-dimensional array of strings

  I f schem a inform at ion is present , arrays w ill t ypically be represent ed as XML elem ent s

  SOAP-ENC:Array

  w hose t ype is or derives from . Furt her, t he array elem ent s w ill have m eaningful XML elem ent nam es and associat ed schem a t ypes. Ot herw ise, t he array represent at ion w ould m ost likely use t he pre- defined elem ent nam es associat ed w it h schem a t ypes from t he SOAP encoding nam espace. Here is an exam ple:

  <! - - Schema f ragment f or array of numbers - - > <el ement name="arrayOf Numbers"> <compl exType base="SOAP- ENC: Array"> <el ement name="number" t ype="xsd: i nt " maxOccurs="unbounded"/> </compl exType> <xsd: anyAt t ri but e namespace="##ot her" processCont ent s="st ri ct "/> </el ement > <! - - Encodi ng exampl e usi ng t he array of numbers - - > <arrayOf Numbers SOAP- ENC: arrayType="xsd: i nt [ 2] "> <number>11</number> <number>22</number> </arrayOf Numbers> <! - - Array encodi ng w/o schema i nf ormat i on - - > <SOAP- ENC: Array SOAP- ENC: arrayType="xsd: i nt [ 2] "> <SOAP- ENC: i nt >11</SOAP- ENC: i nt > <SOAP- ENC: i nt >22</SOAP- ENC: i nt > </SOAP- ENC: Array>

  Referencing Data Abst ract dat a m odels allow a single value t o be referred t o from m ult iple locat ions. Given any part icular dat a st ruct ure, a value t hat is referred t o by only one accessor is considered single- reference , whereas a value t hat has m ore t han one accessor referring t o it is considered m ult i- reference . The exam ples show n so far have assum ed single- reference values. The rules for encoding m ult i- reference values are relat ively sim ple, how ever:

  Multi-reference values are represented as independent elements at the • top of the serialization. This makes them easy to locate in the SOAP message. id

  They all have an unqualified attribute named • of type ID per the

  XML Schema specification. The ID value provides a unique name for the value within the SOAP message. href

  Each accessor to the value is an unqualified • attribute of type

uri-reference per the XML Schema specification. The href values

contain URI fragments pointing to the multi-reference value.

  Here is an exam ple t hat brings t oget her sim ple and com pound t ypes, and single- and m ult i- reference values and arrays:

  <! - - Person t ype w/ mul t i - ref at t ri but es added - - > <xsd: compl exType name="Person"> <xsd: sequence> <xsd: el ement name="name" t ype="xsd: st ri ng"/> <xsd: el ement name="address" t ype="Address"/> </xsd: sequence> <xsd: at t ri but e name="href " t ype="uri Ref erence"/> <xsd: at t ri but e name="i d" t ype="I D"/> <xsd: anyAt t ri but e namespace="##ot her" processCont ent s="st ri ct "/> </xsd: compl exType> <! - - Address t ype w/ mul t i - ref at t ri but es added - - > <xsd: compl exType name="Address"> <xsd: sequence> <xsd: el ement name="st reet " t ype="xsd: st ri ng"/> <xsd: el ement name="ci t y" t ype="xsd: st ri ng"/> <xsd: el ement name="st at e" t ype="USSt at e"/> </xsd: sequence> <xsd: at t ri but e name="href " t ype="uri Ref erence"/> <xsd: at t ri but e name="i d" t ype="I D"/> <xsd: anyAt t ri but e namespace="##ot her" processCont ent s="st ri ct "/> </xsd: compl exType> <! - - Exampl e array of t wo peopl e shari ng an address - - > <SOAP- ENC: Array SOAP- ENC: arrayType="p: Person[ 2] "> <p: Person> <name>Bob Smit h</name> <address href ="#addr- 1"/> </p: Person> <p: Person>

  <address href ="#addr- 1"/> </p: Person> </SOAP- ENC: Array> <p: address i d="addr- 1"> <st reet >1200 Rol l i ng Lane</st reet > <ci t y>Bost on</ci t y> <st at e>MA</st at e> </p: address> id

  The schem a fragm ent s for t he com pound t ypes had t o be ext ended t o support t he and

  href at t ribut es required for m ult i- reference access.

  Odds and Ends The SOAP encoding rules offer m any m ore det ails t hat w e have glossed over in t he int erest of keeping t his chapt er focused on t he core uses of SOAP. Three dat a encoding m echanism s are w ort h a brief m ent ion:

  Null values of a specific type are represented in the traditional XML •

Schema manner, by tagging the value element with xsi:null="1" .

The notion of "any" type is also represented in the traditional XML • xsd:ur-type

  Schema manner via the type. This type is the base for all

schema datatypes and therefore any schema type can appear in its

place. The SOAP encoding allows for the transmission of partial arrays by

  • specifying the starting offset for elements using the SOAP-ENC:offset attribute. Sparse arrays are also supported by tagging array elements with the SOAP-ENC:position attribute. Both of these mechanisms are provided to minimize the size of the SOAP message required to transmit a certain array-based data structure.

  Having covered t he SOAP dat a encoding rules, it is now t im e t o look at t he m ore general problem of encoding different t ypes of dat a in SOAP m essages.

Choosing a Data Encoding

  Because dat a encoding needs vary a lot , t here are m any different w ays t o approach t he problem of represent ing dat a for Web services. To add som e st ruct ure t o t he discussion, t hink of t he decision space as a choice t ree. A choice t ree has yes/ no quest ions at it s nodes and out com es at it s leaves ( see Figure 3.9 ) .

Figure 3.9. Possible choice tree for data encoding. XML Data Probably t he m ost com m on choice has t o do w it h w het her t he dat a already is in ( or can easily be convert ed t o) an XML form at . I f you can represent t he dat a as XML, you only need t o decide how t o include it in t he XML inst ance docum ent t hat w ill represent a m essage in t he prot ocol. I deally, you could j ust m ix it in am idst t he prot ocol- specific XML but under a different nam espace. This approach offers several benefit s. The m essage is easy t o const ruct and easy t o process using st andard XML t ools. How ever, t here is a cat ch. The problem has t o do w it h a lit t le- considered but very im port ant aspect of XML: t he uniqueness rule for I D at t ribut es. The values of at t ribut es of t ype I D m ust be unique in an XML inst ance so t hat t he elem ent s w it h t hese at t ribut es can be convenient ly referred t o using at t ribut es of t ype I DREF, as show n here:

  <Target i d="mai nTarget "/> <Ref erence href ="#mai nTarget "/>

  The problem w it h including a chunk of XML inline ( t ext ually) w it hin an XML docum ent is t hat t he uniqueness of I Ds can be violat ed. For exam ple, in t he follow ing code bot h m essage elem ent s have t he sam e I D. This m akes t he docum ent invalid XML:

  <message i d="msg- 1"> A message wi t h an at t ached <a href ="#msg- 1">message</a>. <at t achment i d="at t achment - 1"> <! - - I D conf l i ct ri ght here - - > <message i d="msg- 1">

  </message> </at t achment > </message>

  And no, nam espaces do not address t he issue. I n fact , t he problem s are so serious t hat not hing short of a change in t he core XML specificat ion and in m ost XML processing t ools can change t he st at us quo. Don't w ait for t his t o happen. You can w ork around t he problem t w o w ays. I f no one w ill ever ext ernally reference specific I Ds w it hin t he prot ocol m essage dat a, t hen your XML prot ocol t oolset can aut om at ically re- w rit e t he I Ds and references t o t hem as you include t he XML inside t he m essage, as follows:

  <message i d="msg- 1"> A message wi t h an at t ached <a href ="#i d- 9137">message</a>. <at t achment i d="at t achment - 1"> <! - - I D has been changed - - > <message i d="i d- 9137"> Thi s i s a t ext ual l y i ncl uded message. </message> </at t achment > </message>

  This approach w ill give you t he benefit s described earlier at t he cost of som e ext ra processing and a slight det eriorat ion in readabilit y due t o t he m achine- generat ed I Ds. I f you cannot do t his, how ever, you w ill have t o include t he XML as an opaque chunk of t ext inside your prot ocol m essage:

  <message i d="msg- 1"> A message wi t h an at t ached message t hat we can no l onger ref er t o di rect l y. <at t achment i d="at t achment - 1"> <! - - Message i ncl uded as t ext - - > &l t message i d="i d- 9137"&gt ; Thi s i s a t ext ual l y i ncl uded message. &l t ; /message&gt ; </at t achment > </message>

  I n t his case, w e have escaped all point y bracket s, but w e also could have included t he w hole m essage in a CDATA sect ion. The benefit of t his approach is t hat it is easy and it w orks for any XML cont ent . How ever, you don't get any of t he benefit s of XML. You cannot validat e, query, or t ransform t he dat a direct ly, and you cannot reference pieces of it from ot her part s of t he m essage. Binary Data So far, w e have discussed encoding opt ions for pre- exist ing XML dat a. How ever, w hat if you are not dealing w it h XML dat a? What if you w ant t o t ransport binary dat a as part of your m essage, inst ead? The com m only used solut ion is good old base64 encoding:

  <SOAP- ENV: Envel ope xmlns: SOAP- ENV="ht t p: //schemas. xmlsoap. org/soap/envel ope/" SOAP- ENV: encodi ngSt yl e="ht t p: //schemas. xmlsoap. org/soap/encodi ng/"> <SOAP- ENV: Body> <x: St orePi ct ure xmlns: x="Some URI "> aG93I G5vDyBi cm73bi Bj b3cNCg== </Pi ct ure> </x: St orePi ct ure> </SOAP- ENV: Body> </SOAP- ENV: Envel ope>

  On t he posit ive side, base64 dat a is easy t o encode and decode, and t he charact er set of base64- encoded dat a is valid XML elem ent cont ent . On t he negat ive side, base64 encoding t akes up nearly 33% m ore m em ory t han pure binary represent at ion. I f you need t o m ove m uch binary dat a and space/ t im e efficiency is a concern, you m ight have t o look for alt ernat ives. ( More on t his in a bit .) You m ignt w ant t o consider using base64 encoding even w hen you w ant t o m ove som e plain t ext as part of a m essage, because XML's docum ent - cent ric SGML origin led t o several awkward rest rict ions on t he t ext ual cont ent of XML inst ances. For exam ple, an

  XML docum ent cannot include any cont rol charact ers ( ASCI I codes 0 t hrough 31) except t abs, carriage ret urns, and line feeds. This lim it at ion includes bot h t he st raight occurrences of t he charact ers and t heir encoded form as charact er references, such as

   . Furt her, carriage ret urns are alw ays convert ed t o line feeds by XML processors.

  I t is im port ant t o keep in m ind t hat not all charact ers you can put in a st ring variable in a program m ing language can be represent ed in XML docum ent s. I f you are not careful, t his sit uat ion can lead t o unexpect ed runt im e errors. Abstract Data Models I f you are not dealing w it h plain t ext , XML, or binary dat a, you probably have som e form of st ruct ured dat a represent ed via an abst ract dat a m odel.

  The key quest ion w hen dealing w it h abst ract dat a m odels and XML is w het her t he out put

  XML form at m at t ers. For exam ple, if you have t o generat e Skat esTow n purchase orders, t hen t he out put form at is clearly im port ant . I f, on t he ot her hand, you j ust w ant t o m ake an RPC call over SOAP t o pass som e dat a t o a Web service, t hen t he exact form at of t he

  XML represent ing your RPC param et ers does not m at t er. All t hat m at t ers is t hat t he Web service engine can decode t he XML and reconst ruct a sim ilar dat a st ruct ure w it h w hich t o invoke t he backend. I n t he lat t er case, it is safe t o use pre- built aut om at ic " dat a t o XML and back" encoding syst em s ( see Figure 3.10 ) . For exam ple, Web service engines have dat a serializat ion/ deserializat ion m odules t hat support t he rules of SOAP encoding. These rules are flexible enough t o represent m ost applicat ion- level dat a t ypes. Suffice t o say, in m any cases you w ill never have t o w orry about t he m echanics of t he serializat ion/ deserializat ion processes.

Figure 3.10. Generic XML serialization/deserialization. The SOAP encoding is a flexible schem a m odel for represent ing dat a—elem ent nam es in t he inst ance docum ent oft en depend on t he t ype and form at of dat a t hat is being encoded. This m odel allow s for a link bet w een t he dat a and it s t ype, w hich enables validat ion. I t is one of t he core reasons w hy XML prot ocols such as SOAP m oved t o t his encoding m odel, as discussed earlier in t he chapt er w hen w e considered t he evolut ion of XML prot ocols.

  I n t he cases w here t he XML out put form at does not m at t er ( t ypically RPC scenarios) , you can rely on t he default rules provided by various XML dat a encoding syst em s. I n m any cases, however, t he XML form at is fixed based on t he specificat ion of a service. A Skat esTow n purchase order subm ission service is a perfect exam ple. From a request or's perspect ive, t he input form at m ust be a PO docum ent and t he out put form at m ust be an invoice docum ent . Request ors are responsible for m apping w hat ever dat a st ruct ures t hey m ight be using t o represent POs in t heir order syst em s t o t he Skat esTow n PO form at . Also, Skat esTown is responsible for always out put t ing responses in it s invoice XML form at .

  There are t w o t ypical approaches t o handling t his scenario. The sim plest one is t o com plet ely delegat e XML processing t o t he applicat ion. I n ot her w ords, t he Web service engine is responsible only for delivering a chunk of XML t o t he Web service im plem ent at ion. Anot her approach involves building and regist ering cust om serializers/ deserializers ( dat at ype m appers) w it h t he Web service engine. The serializers m anipulat e applicat ion dat a t o produce XML. The deserializers m anipulat e t he XML t o generat e applicat ion dat a. You can build t hese serializer/ deserializer m odules t w o w ays: by hand, using t he API s of t he Web service engine; or using a t ool for m apping dat a t o and from XML given a pre- exist ing schem a. These t ools are know n as schem a com pilers ( see Figure 3.11 ) .

Figure 3.11. Serialization/deserialization process with a schema compiler.

  Schem a com pilers are t ools t hat analyze XML schem a and code- generat e serializat ion and deserializat ion m odules specific t o t he schem a. These m odules w ill w ork w it h dat a st ruct ures t uned t o t he schem a. Schem a com pilat ion is a difficult problem , and t his is one reason t here aren't m any excellent t ools in t his space. The Java Archit ect ure for XML Binding ( JAXB) is one of t he proj ect s t hat is t rying t o address t his problem in t he cont ext of t he Java program m ing language ( ht t p: / / j ava.sun.com / xm l/ j axb/ ) . Unfort unat ely, at t he t im e of t his w rit ing, JAXB only support s DTDs and does not support XML Schem a. Chapt er 8 , " I nt eroperabilit y, Tools, and Middlew are Product s," focuses on t he current Web service t ooling for t he Java plat form . I t provides m ore det ails on t hese and ot her im port ant im plem ent at ion effort s in t he space. Linking Data So far, w e have only considered scenarios w here t he encoded dat a is part of t he XML docum ent describing a prot ocol m essage. This can creat e som e problem s for including pre- exist ing XML cont ent and can w ast e space in t he case of base64- encoded binary obj ect s. The alt ernat ive w ould be keeping t he dat a out side of t he m essage and som ehow bringing it in at t he right t im e. For exam ple, an aut o insurance claim m ight carry along several accident pict ures t hat com e int o play only w hen t he insurance claim needs t o be displayed in a brow ser or print ed. You can use t w o general m echanism s in such cases. The first com es st raight out of XML

  1.0. I t involves ext ernal ent it y references, w hich allow cont ent ext ernal t o an XML docum ent t o be brought in during processing. Many people in t he indust ry prefer pure m arkup and t herefore favor a second approach t hat uses explicit link elem ent s t hat com ply w it h t he XLink specificat ion. Bot h m et hods could w ork. Bot h require ext ensions t o t he core Web services t oolset s t hat are available now . I n addit ion, purely applicat ion- based m et hods are available for linking; you could j ust pass a URI know n t o m ean " get t he act ual cont ent here." How ever, t his approach does not scale t o generic dat a encoding m echanism s because it requires applicat ion- level know ledge.

  Ext ernal cont ent can be kept on a separat e server t o be delivered on dem and. I t can also be packaged t oget her w it h t he prot ocol m essage in a MI ME envelope. The SOAP Messages w it h At t achm ent s Not e t o t he W3C ( ht t p: / / w w w .w 3.org/ TR/ 2000/ NOTE- SOAP-

  

at t achm ent s- 20001211 ) defines a m echanism for doing t his. An exam ple SOAP m essage

  w it h an at t achm ent is show n lat er in t he chapt er in t he sect ion " SOAP Prot ocol Bindings ." There are m any, m any w ays t o encode dat a in XML, and w ell- designed XML prot ocols w ill let you plug any encoding st yle you choose. How should you m ake t his im port ant decision? First , of course, keep it sim ple. I f possible, choose st andards- based and well- deployed t echnology. Then, consider your needs and m at ch t hem against som e of t he im port ant facet s of XML dat a encoding described here.

Architecting Distributed Systems with Web Services

  Alt hough SOAP is t ypically dem oed w it h sim ple RPC- based Web services, such as Skat esTow n's invent ory check service, t he SOAP specificat ion does not m andat e any

  part icular com m unicat ion m echanism or int eract ion pat t ern bet w een t he part icipant s of a Web- service– enabled dist ribut ed syst em . Syst em designers basically have com plet e cont rol over t he syst em archit ect ure, choice of com m unicat ion prot ocols, m essage rout ing, int erm ediary configurat ion, and so on. The hard part about having so m uch flexibilit y is t hat w it hout solid experience w it h dist ribut ed syst em s and good j udgm ent , it is easy t o m ake sub- opt im al choices. The m ost com m only asked quest ions about dist ribut ed syst em s based on Web services cent er around a long- running debat e in dist ribut ed com put ing circles regarding t he rules and regulat ions for using RPC and m essaging ( oft en ident ified as Message Orient ed Middlew are—MOM) t o solve problem s. Typically, t he debat e t akes t he unnecessarily polarized form of " MOM vs. RPC." The fact of t he m at t er is t hat bot h m essaging and RPC play significant , albeit different , roles in dist ribut ed com put ing. Bot h approaches cont inue t o be very relevant in t he era of Web services. Unfort unat ely, a lot of confusion exist s about t he m eaning of t he t erm s, t he capabilit ies of m essaging and RPC syst em s, and t he scenarios in w hich t hey are best applied. Service- orient ed archit ect ures fundam ent ally can support bot h m odels. Therefore, t o best follow s is a brief analysis of t he t w o approaches and t heir relat ion t o SOAP and Web services. Given t hat people are generally m ore fam iliar w it h RPCs, w e st art w it h a discussion of m essaging in it s m any form s.

  Messaging

  As a m odel for dist ribut ed com put ing, m essaging refers t o a m echanism for get t ing syst em s t o int eract via t he passing of m essages. A m essage is a single unit of com m unicat ion encapsulat ing som e inform at ion. ( A SOAP m essage is a great exam ple.) This is w here t he differences begin. Messaging m odels can vary significant ly based on t he follow ing crit eria:

  Number of participants and their organization

  • Interaction patterns &b
  • Synchronicity of message exchanges

  Direct versus queued messaging • Quality of service (QoS) • Message format

  • Message Participants There are t hree different w ays t o organize m essaging part icipant s ( see Figure 3.12 ) . The sim plest case is 1- t o- 1 ( point - t o- point ) m essaging, which involves only t w o syst em s. An exam ple could be an e- com m erce scenario w here t he client applicat ion subm it s a purchase order t o a digit al m arket place. I n t his case, t he sender needs t o know w here t o send t he m essage.

Figure 3.12. Messaging patterns. A slight ly m ore com plicat ed organizat ion is 1- t o- m any m essaging, w here t he sender sends a single m essage but copies of it go t o m ult iple recipient s. This is oft en referred t o as publish/ subscribe or t opic- - based m essaging . The idea is t hat t he sender is a publisher t hat sends a m essage t o a " t opic" and t hat t he recipient s are all t he syst em s t hat have subscribed t o receive not ificat ions on t his t opic. E- m ail dist ribut ion list s are a good exam ple of t his t ype of m essaging. The nam e of t he dist ribut ion list is t he t opic, and t he subscribers are all t he e- m ail addresses on t he list . Finally, m any- t o- m any m essaging involves a pat t ern of m essage exchange am ong any num ber of part icipant s. Clearly, in t his case, som e syst em in t he m iddle ( t ypically som e t ype of a w orkflow engine support ing business processes) needs t o direct m essage t raffic. This is described by t he cloud in Figure 3.12 .

  Interaction Patterns There are four com m on m essaging int eract ion pat t erns ( see Figure 3.13 ) . One- w ay ( fire- and- forget ) m essaging involves t he sim ple sending of a m essage from one syst em t o anot her. No response is generat ed at t he applicat ion level. Of course, depending on t he case of request - response m essaging, a response m essage is generat ed for every request m essage. The response m essage is sent from t he t arget of t he request m essage t o it s source. Chapt er 6 describes how request s and responses can be correlat ed and how m ult iple request - response pairs can be organized int o logical " conversat ions."

Figure 3.13. Interaction patterns.

  The ot her t w o int eract ion pat t erns, not ificat ion and not ificat ion- response, are m irror im ages of one- w ay and request - response. They are callback pat t erns. Rat her t han a client syst em pushing m essages t o a server syst em , t he server syst em is pushing m essages t o t he client . The st ock t icker applicat ion you m ight have on your deskt op is a perfect exam ple of not ificat ion com bined w it h publish- subscribe m essaging. Chapt er 6 get s int o m ore det ail about Web service int eract ion pat t erns.

  Synchronicity Messaging can be eit her synchronous or asynchronous. I n synchronous m essaging, a send operat ion does not com plet e unt il t he t arget of t he m essage has finished processing t he m essage. Asy nchronous m essaging is harder t o define. Typically, t he send operat ion w ill ret urn im m ediat ely ( or very quickly) , before t he t arget has processed t he m essage. Response m essages, if any, t ypically arrive via callbacks. Direct vs. Queued Messaging The synchronicit y of m essaging is cont rolled by t he presence of m essaging m iddlew are,

  part icularly queuing syst em s. Direct m essaging w orks w it hout any m iddlew are present . For m essages t o be exchanged, a direct connect ion bet w een t he source and t he t arget ( s) m ust be available. This is w hy it is som et im es referred t o as connect ion- orient ed m essaging You can get som e am ount of asynchronicit y in direct m essaging by using t hreads t o m anage t he sending and receiving of m essages. I ndirect m essaging involves som e t ype of m essage queuing. Queues provide m essage t he chapt er. An e- m ail server is a perfect exam ple of a m essage queuing syst em . When you send an e- m ail m essage, your e- m ail client does not cont act t he e- m ail client of t he person you are t rying t o reach. I nst ead, your e- m ail client sends t he m essage t o a local

  e- m ail server. The server saves t he m essage in som e safe place and wait s for a good m om ent t o send it out . Typically, m any m essages are sent at once. This is t he buffering funct ion. The dispat ch funct ion has t o do w it h t he e- m ail server inspect ing t he t arget e- m ail addresses and deciding where t o forward t he e- m ail m essage. I n som e cases, an e- m ail m essage w ill m ake several hops bet w een e- m ail servers before it arrives at t he dest inat ion e- m ail server w here your m ail client can read it . This configurat ion is so pow erful because it w orks even in t he cases w here m ail client s and even som e m ail servers are offline for long periods of t im e. A m ail server w ill keep t rying t o send e- m ail for several days and w ill st ore received m essages pot ent ially indefinit ely.

Figure 3.14 cont rast s direct m essaging ( t he t opm ost configurat ion) w it h a num ber of

  possible queuing configurat ions. I n t he second and t hird configurat ions, t he queuing syst em act s prim arily as a m essage buffer. For exam ple, if t he receiver is not on t he net w ork, t he m essage w ill st ill be safely st ored in t he queue. The last configurat ion is t he m ost int erest ing, in t hat t he m essage can be m oved from t he local t o t he rem ot e syst em w it hout eit her t he sender or t he receiver being online—t he m essage queuing syst em s can do t he j ob by t hem selves. I n addit ion, t he presence of m ore t han one queuing syst em allow s for flexible m essage dispat ch.

Figure 3.14. Variations of queuing configurations.

  Quality of Service Anot her im port ant aspect of m essaging is qualit y of service ( QoS) . Direct m essaging exhibit s t he QoS param et ers w it h w hich w e are m ost fam iliar, such as securit y and t ransact ion m anagem ent . When queuing is in use, ot her t ypes of QoS becom e available. For exam ple, m essages can be st ored in t he queuing server in various w ays: in m em ory ( t he fast est queuing m echanism but one t hat does not guarant ee against syst em failure) or in som e persist ent st ore, such as a DBMS. Furt her, t ransact ions can guarant ee t hat t he m essage is sent t o t he receiver once and only once or not at all. I n t he case of m essage delivery failure, QoS policy m ight dict at e t hat a failure not ificat ion is sent t o t he m essage sender. I n addit ion, it is com m on QoS delivered t o t he receiver. These t ypes of QoS considerat ions are very relevant t o Web services. Chapt er 5 looks in m ore det ail at som e QoS aspect s. Message Format The last but not least im port ant aspect of m essaging is t he form at of m essage dat a. Most m essaging syst em s allow t he t ransfer of t ext and binary dat a, w hich enables t he easy t ransfer of XML. Som e newer m essaging syst em s t reat XML m essages specially and t ry t o use an opt im ized XML encoding form at . There is also t he not ion of queues t hat can aut om at ically allow only XML m essages t hat com ply wit h cert ain schem a. Som e plat form - focused m essaging syst em s, such as Java Messaging Service ( JMS) m iddleware and Microsoft 's .NET m essaging server, also allow for t he aut om at ic serializat ion of applicat ion dat a ( Java obj ect s in t he case of JMS and Com m on Language Runt im e [ CLR] dat a st ruct ures in t he case of Microsoft ) .

  Messaging Versus RPC

  I f m essaging is all about possibilit ies and variat ions, RPCs are m uch m ore const rained. As t he nam e suggest s, t he goal of RPCs is t o m ake t he invocat ion of rem ot e code seem like a local procedure call ( LPC) . To m ake an RPC call, you need t he follow ing inform at ion:

  A target to invoke

  • An operation name • Optionally, parameters to pass to the operation •

  Therefore, w hereas m essaging is prim arily about dat a ( w hich can be in any conceivable form at ) , RPCs are about com bining specific applicat ion- level dat a w it h rem ot e code. This is t he one fundam ent al difference bet w een m essaging and RPC. A nice side- effect is t hat program m ers using RPC do not have t o w orry about m anually perform ing dat a encoding and decoding—som et hing t hat t ypically has t o happen w hen using m essaging syst em s, especially across program m ing languages and plat form s.

  Anot her w ay t o st at e t he m ain difference bet w een m essaging and RPC is t o not e t hat

  sendMessage() getMessage()

  m essaging deals wit h generic API s such as , , and

  registerMessageResponseCallback()

  , w hereas RPCs deal w it h special- purpose API s t hat vary based on t he int erface of t he t arget t hat is being invoked. For exam ple, if you

  processOrder()

  are t rying t o invoke a rem ot e EJB t hat has a m et hod, you w ill m ost

  processOrder()

  likely call t he m et hod of a local obj ect t hat act s like a proxy t o t he rem ot e EJB. Chapt er 6 discusses t his t opic in m uch m ore det ail. Anot her key difference bet w een RPCs and m essaging is t hat RPCs are direct invocat ions. There is no queuing m echanism ; t he backend m ust be running and it m ust be direct ly accessible at a w ell- know n locat ion. This lim it s t he dispat ch capabilit ies of RPC m iddleware. MOM m essage dispat ch can be m uch m ore flexible. Finally, ext ensive use of RPCs t ends t o result in som ew hat brit t le dist ribut ed syst em s. Because t he API s are fine- grained, even sm all changes in t he dat a being passed around can break t he syst em . Messaging uses m uch rougher- grain dat a exchanges and is t herefore m ore likely t o sust ain sm all changes in t he dat a being exchanged w it hout failure. Apart from t hese key differences, RPCs and m essaging have m any sim ilarit ies:

  RPCs can be implemented on top of a request-response messaging • pattern.

  • Contrary to popular belief, however, RPCs do not have to have a
  • >

    In addition, RPCs do not have to be synchronous. Some systems

    automatically spawn threads to wait in the background for RPC

    respon
  • RPCs and messaging share many of the same QoS requirements such as security and transaction management.
  • Direct, synchronous, 1-to-1 messaging can be simulated via a simple RPC, e.g., void sendMessage(data) .

  request-response messaging pattern. Some systems support one-way RPCs.

  I t should becom e clear by now t hat t he real issue isn't w hich of t he t w o approaches t o dist ribut ed com put ing is bet t er ( t he sim ple int erpret at ion of " m essaging vs. RPC" ) but w hen each approach should be used in t he w orld of Web services. To answ er t his quest ion, aft er w e have m ent ioned so m any possible variat ions of bot h m essaging and RPC, it helps t o est ablish som e st ereot ypes. When w orking w it h Web services, it w ill generally be t he case t hat :

  • RPCs will be direct, synchronous, request-response invocations that
  • Messages will carry XML data. The interaction pattern is most likely to be one-way or request-response. Simple architectures will use direct messaging. The organization of participants will likely be 1-

    to-1. More advanced architectures will be queued and therefore

    asynchronous.

  pass encoded application-level data structures from a client to a target backend that implements the RPC functionality.

  I n bot h cases, m essages w ill be represent ed on t he w ire using SOAP. QoS- relat ed inform at ion t hat is part of t he m essage w ill be represent ed as m essage headers. A good exam ple w ould be an aut hent icat ion header t hat carries a usernam e and passw ord; Chapt er 5 shows an exam ple.

Table 3.2 present s a num ber of benefit s and concerns about using m essaging and RPC.

  Based on t hese and t he current st at e- of- t he- art in Web service m iddlew are and t ooling, w e w ould recom m end t hat you go w it h a sim ple RPC- based solut ion or a direct m essaging solut ion unless disconnect ed operat ion w ill be of benefit , t he syst em requires 1- t o- m any int eract ions, or synchronous operat ion is causing perform ance problem s.

Table 3.2. Pros and Cons of Messaging and RPC for Web Services

Pros Cons

  Direct m essaging

  • The basic messaging APIs are very simple.
  • Any data can be passed.
  • Separates data from the code that operates on it.
  • Applications must perform
Queued m essaging

  manual data encoding/decoding.

  • Same as above, plus…
  • Asynchronicity spreads
  • Same as above plus…
  • Most useful forms of

  the load and improves performance.

  messaging require a queuing infrastructure.

  • Allows for disconnected operation.
  • >Current message queuing products do not interoperate w>Allows for 1-to-many and many-to-many interacti
  • Asynchronicity makes

  programming more difficult.

  RPC

  • Local APIs match backend APIs.
  • Synchronicity makes programming easy.
  • Synchronicity can cause bottlenecks.
  • Backend must be running for RPCs to succeed.
  • >Application data is automatically encoded/deco
  • Only 1-to-1 interactions are supported.
  • Exceptions provide a good error-handling mechanism.
  • >RPC products interoperate reasonably well.

      We w ould expect t hat as m essaging m iddlew are vendors em brace Web services t o a great er ext ent and as m ore Web services becom e increasingly used in t he cont ext of com plex business process w orkflow s, t he im port ance of Web service m essaging w ill grow. Broad st andardizat ion effort s such as ebXML ( ht t p: / / w w w .ebxm l.org ) and Java API for XML Messaging ( JAXM, ht t p: / / j ava.sun.com / xm l/ j axm / index.ht m l ) w ill help speed up t he process.

    SOAP-based RPCs

      So far in t his chapt er w e have present ed several exam ples of SOAP- based RPC w it hout ever m ent ioning t he det ails of represent ing RPCs in SOAP m essages as described by t he SOAP specificat ion. The rules are very sim ple. Recall t hat t o invoke an RPC, you need a t arget URI , an operat ion nam e, som e param et ers, and any am ount of cont ext inform at ion ( such as securit y cont ext ) . Any such cont ext inform at ion is m odeled as SOAP headers. SOAP's RPC binding does not specify how t he t arget URI is going t o be provided. I n ot her w ords, it leaves it up t o t he SOAP processor t o det erm ine how t o dispat ch a SOAP RPC request t o a t arget backend. There are t hree com m on w ays t o do t his dispat ch. Tw o of t hese are HTTP- specific, and t he ot her is based on t he cont ent s of t he SOAP m essage:

      In the case of HTTP, the SOAP processor can dispatch based on the • target URL (as in the inventory check example).

      SOAPAction Alternatively, it may dispatch based on the value of the • HTTP header that comes as part of the HTTP request.

    Alternatively, it can use the value of the namespace URI for the • first element inside the SOAP body

      Most Web services engines do not support any com binat ion of t hese dispat ch m echanism s. Axis can be configured t o w ork w it h any com binat ion. I n t he language of t he SOAP encoding, t he act ual RPC invocat ion is m odeled as a st ruct . The nam e of t he st ruct ( t hat is, t he nam e of t he first elem ent inside t he SOAP body) is ident ical t o t he nam e of t he m et hod/ procedure. This is not a problem , because t he charact er set of XML elem ent s is a superset of t he charact er set of valid ident ifier nam es in program m ing languages. Every in and in- out param et er of t he RPC is m odeled as an accessor w it h a nam e ident ical t o t he nam e of t he RPC param et er and t ype ident ical t o t he t ype of t he RPC param et er m apped t o XML according t o t he rules of t he act ive encoding st yle. The accessors appear in t he sam e order, as do t he param et ers in t he operat ion signat ure. The RPC response is also m odeled as a st ruct . By convent ion, t he nam e of t he st ruct is t he sam e as t he nam e of t he operat ion, w it h Response appended t o it . There are accessors for t he operat ion result and all in- out and out param et ers. The result is t he first accessor, follow ed by t he param et ers in t he order t hey appear in t he operat ion signat ure. By convent ion, t he result elem ent 's nam e is t he sam e as t he nam e of t he operat ion, w it h Result appended t o it . Java developers are not used t o t he concept of in- out or out param et ers because, t ypically, in Java all obj ect s are aut om at ically passed by reference. When using RMI , sim ple obj ect s can be passed by value, but ot her obj ect s are st ill passed by reference. I n t his sense, any m ut able obj ect s ( ones whose st at e can be m odified) are aut om at ically t reat ed as in- out param et ers. I n Web services, t he sit uat ion is different . All param et ers are passed by value. SOAP has no not ion of passing values by reference. This design decision w as m ade in order t o keep SOAP and it s dat a encoding sim ple. Passing values by reference in a dist ribut ed syst em requires dist ribut ed garbage collect ion. This not only com plicat es t he design of t he syst em but also im poses rest rict ions on som e possible syst em archit ect ures and int eract ion pat t erns. For exam ple, how can you do dist ribut ed garbage collect ion in a queued m essaging archit ect ure w hen t he request or and t he provider of a service can bot h be offline at t he sam e t im e? Therefore, for Web services, t he not ion of in- out and out param et ers does not involve passing obj ect s by reference and let t ing t he t arget backend m odify t heir st at e. I nst ead, copies of t he dat a are exchanged. I t is t hen up t o t he service client code t o creat e t he percept ion t hat t he act ual st at e of t he obj ect t hat has been passed in t o t he client m et hod has been m odified. Different Web service client s m ight have different w ays t o do t his. Consider t he follow ing operat ion signat ure:

      bool ean doCheck( i n St ri ng sku, i n i nt quant i t y, out i nt numInSt ock)

      Som e possible SOAP RPC request and response bodies are:

      <! - - RPC request body - - >

      <doCheck> <sku xsi : t ype="xsd: st ri ng">947- TI </sku> <quant i t y xsi : t ype="xsd: i nt ">1</quant i t y> </doCheck> </SOAP- ENV: Body> <! - - RPC response body - - > <SOAP- ENV: Body> <doCheckResponse> <doCheckResul t xsi : t ype="xsd: bool ean">t rue</doCheckResul t > <numInSt ock xsi : t ype="xsd: i nt ">150</numInSt ock> </doCheckResponse> </SOAP- ENV: Body>

      Of course, if a descript ion of t he operat ion is available, you can generat e a schem a for all

      xsi:type

      t he elem ent s in t he SOAP body. Doing so w ould elim inat e t he need t o use everyw here in t he SOAP m essage. Chapt er 6 looks in m ore det ail at t he m echanism s for doing t his. SOAP-based Messaging The t echnical t erm for non- RPC SOAP m essaging is docum ent - cent ric m essaging.

      The nam e com es from t he fact t hat t he dat a sent over SOAP is represent ed as an XML docum ent em bedded inside t he SOAP envelope. Alt hough t he RPC binding for SOAP has a num ber of rules governing t he represent at ion and encoding of operat ion nam es and param et ers, sim ple SOAP m essages have absolut ely no rest rict ions as t o t he inform at ion t hat can be st ored in t heir bodies. I n short , any XML can be included in t he SOAP m essage. The next sect ion of t his chapt er shows an exam ple of SOAP- based m essaging.

      Purchase Order Submission Web Service

      Recall t hat w hen Al Rosen of Silver Bullet Consult ing w as invest igat ing Skat esTow n's e- business processes, he not iced t hat one area t hat badly needed aut om at ion w as purchase order subm ission. Purchase orders and invoices w ere being exchanged over e- m ail, and t hey w ere m anually input int o t he com pany's purchase order syst em .

      Because Skat esTow n already has defined an XML schem a for it s purchase orders and invoices, Al t hinks it m akes sense t o build a purchase order Web service t hat accept s a purchase order as an XML docum ent and ret urns an XML invoice. This service w ould be an exam ple of 1- t o- 1 direct m essaging using a request - response int eract ion pat t ern.

      Purchase Order and Invoice Schemas

      The schem as for Skat esTow n's purchase orders and invoices are explained in det ail in

      Chapt er 2 . List ings 3.8 and 3.9 show exam ple XML docum ent inst ances for bot h.

      Listing 3.8 Example SkatesTown Purchase Order

      <po xmlns="ht t p: //www. skat est own. com/ns/po" i d="50383" submit t ed="2001- 12- 06"> <bi l l To> <company>The Skat eboard Warehouse</company> <st reet >One Warehouse Park</st reet > <st reet >Bui l di ng 17</st reet >

      <st at e>MA</st at e> <post al Code>01775</post al Code> </bi l l To> <shi pTo> <company>The Skat eboard Warehouse</company> <st reet >One Warehouse Park</st reet > <st reet >Bui l di ng 17</st reet > <ci t y>Bost on</ci t y> <st at e>MA</st at e> <post al Code>01775</post al Code> </shi pTo> <order> <i t em sku="318- BP" quant i t y="5">

    <descri pt i on>Skat eboard backpack; f i ve pocket s</descri pt i on>

    </i t em> <i t em sku="947- TI " quant i t y="12">

    <descri pt i on>St reet - st yl e t i t ani um skat eboard. </descri pt i on>

    </i t em> <i t em sku="008- PR" quant i t y="1000"/> </order> </po>

      Listing 3.9 Example SkatesTown Invoice

      <i nvoi ce i nv="ht t p: //www. skat est own. com/ns/i nvoi ce" i d="50383" submit t ed="2001- 12- 06"> <bi l l To> <company>The Skat eboard Warehouse</company> <st reet >One Warehouse Park</st reet > <st reet >Bui l di ng 17</st reet > <ci t y>Bost on</ci t y> <st at e>MA</st at e> <post al Code>01775</post al Code> </bi l l To> <shi pTo> <company>The Skat eboard Warehouse</company> <st reet >One Warehouse Park</st reet > <st reet >Bui l di ng 17</st reet > <ci t y>Bost on</ci t y> <st at e>MA</st at e> <post al Code>01775</post al Code> </shi pTo> <order> <i t em sku="318- BP" quant i t y="5" uni t Pri ce="49. 95">

    <descri pt i on>Skat eboard backpack; f i ve pocket s</descri pt i on>

    </i t em> <i t em sku="947- TI " quant i t y="12" uni t Pri ce="129. 00">

    <descri pt i on>St reet - st yl e t i t ani um skat eboard. </descri pt i on>

    </i t em> <i t em sku="008- PR" quant i t y="1000" uni t Pri ce="0. 00">

      </i t em> </order> <t ax>89. 89</t ax> <shi ppi ngAndHandl i ng>89. 89</shi ppi ngAndHandl i ng> <t ot al Cost >1977. 52</t ot al Cost > </i nvoi ce>

      XML-Java Data Mapping Unfort unat ely, Al Rosen finds out t hat t he act ual Skat esTow n purchase order syst em does not know how t o deal w it h XML. The XML capabilit ies w ere added as an ext ension t o t he syst em by a developer w ho has since left t he com pany. To m ake m at t ers w orse, m uch of t he source code pert aining t o XML processing seem s t o have been lost during an upgrade of t he source cont rol m anagem ent ( SCM) syst em at t he com pany. The PO syst em 's API s work in t erm s of a set of Java beans represent ing concept s such as product , purchase order, invoice, address, and so on. Figure 3.15 shows a UML diagram .

    Figure 3.15. UML model for the PO system's data objects.

      Al know s t hat because he is using SOAP- based m essaging, t he t ask of m apping t he purchase order XML t o Java obj ect s and t he invoice Java obj ect s back t o XML is left ent irely up t o him . Therefore, he im plem ent s a serializer and a deserializer t hat know

      com.skatestown.data

      how t o encode and decode obj ect s from t he package t o and from

      XML. Because t he schem as for purchase orders and invoices are relat ively sim ple, he decides t o do t his by hand rat her t han t o rely on available schem a com piler t ools; he has

      Serializer

      had no experience w it h t hese. The t w o classes t hat he builds are and

      Deserializer com.skatestown.xml

      in t he package. The com bined code size is slight ly over 300 lines of Java code.

      List ing 3.10 show s t he key purchase order deserializat ion m et hods. They use a num ber getValue() getElements()

      of sim ple ut ilit y m et hods such as and t o t raverse t he DOM represent at ion of a purchase order and const ruct a purchase order and all it s cont ained readItem()

      I nvoiceI t em or creat ing addresses, is put in separat e m et hods ( and

      createAddress()

      , respect ively) . This pat t ern for XML t o Java dat a m apping is very sim ple and readable yet flexible t o handle a large variet y of input XML form at s. Listing 3.10 Core Purchase Deserialization Methods

      prot ect ed voi d readDocument ( Busi nessDocument doc, El ement el em) { doc. set I d( I nt eger. parseI nt ( el em.get At t ri but e( "i d" ) ) ) ; doc. set Dat e( el em.get At t ri but e( "submit t ed") ) ; doc. set Bi l l To( creat eAddress( get El ement ( el em, "bi l l To") ) ) ; doc. set Shi pTo( creat eAddress( get El ement ( el em, "shi pTo") ) ) ; } prot ect ed voi d readI t em(POI t em i t em, El ement el em) { i t em.set SKU( el em.get At t ri but e( "sku") ) ; i t em.set Quant i t y( I nt eger. parseI nt ( el em.get At t ri but e( "quant i t y") ) ) ; i t em.set Descri pt i on( get Val ue( el em, "descri pt i on" ) ) ; } prot ect ed Address creat eAddress( El ement el em) { Address addr = new Address( ) ; addr. set Name( get Val ue( el em, "name" ) ) ; addr. set Company( get Val ue( el em, "company" ) ) ; addr. set St reet ( get Val ues( el em, "st reet " ) ) ; addr. set Ci t y( get Val ue( el em, "ci t y" ) ) ; addr. set St at e( get Val ue( el em, "st at e" ) ) ; addr. set Post al Code( get Val ue( el em, "post al Code" ) ) ; addr. set Count ry( get Val ue( el em, "count ry" ) ) ; ret urn addr; } prot ect ed PO _creat ePO( El ement el em) { PO po = new PO( ) ; readDocument ( po, el em); El ement [ ] orderI t ems = get El ement s( el em, "i t em") ; POI t em[] i t ems = new POI t em[orderI t ems. l engt h] ; f or ( i nt i = 0 ; i < i t ems. l engt h; ++i ) { POI t em i t em = new POI t em() ; readI t em(i t em, el em); i t ems[ i ] = i t em; } ret urn po; }

    List ing 3.11 shows t he key invoice serializat ion m et hods. I n t his case, t hey t raverse t he

    addChild()

      Java dat a st ruct ures describing an invoice and use ut ilit y m et hods such as t o const ruct a DOM t ree represent ing an invoice docum ent . Again, shared funct ionalit y such as serializing an address is separat ed in m et hods t hat are called from m ult iple locat ions. Listing 3.11 Core Invoice Serialization Methods

      prot ect ed voi d wri t eDocument ( Busi nessDocument bdoc, El ement el em) { el em.set At t ri but e( "i d", ""+bdoc. get I d( ) ) ; el em.set At t ri but e( "submit t ed", bdoc. get Dat e( ) ) ; wri t eAddress( bdoc. get Bi l l To( ) , addChi l d( el em, "bi l l To") ) ; wri t eAddress( bdoc. get Shi pTo( ) , addChi l d( el em, "shi pTo") ) ; } prot ect ed voi d wri t eAddress( Address addr, El ement el em) { addChi l d( el em, "name", addr. get Name( ) ) ; addChi l d( el em, "company", addr. get Company( ) ) ; addChi l dren( el em, "st reet ", addr. get St reet ( ) ) ; addChi l d( el em, "ci t y", addr. get Ci t y( ) ) ; addChi l d( el em, "st at e", addr. get St at e( ) ) ; addChi l d( el em, "post al Code", addr. get Post al Code( ) ) ; addChi l d( el em, "count ry", addr. get Count ry( ) ) ; } prot ect ed voi d wri t ePOI t em(POI t em i t em, El ement el em) { el em.set At t ri but e( "sku", i t em.get SKU( ) ) ; el em.set At t ri but e( "quant i t y", ""+i t em.get Quant i t y( ) ) ; addChi l d( el em, "descri pt i on", i t em.get Descri pt i on( ) ) ; } prot ect ed voi d wri t eI nvoi ceI t em(I nvoi ceI t em i t em, El ement el em) { wri t ePOI t em(i t em, el em); el em.set At t ri but e( "uni t Pri ce", nf . f ormat ( i t em.get Uni t Pri ce( ) ) ) ; } prot ect ed voi d wri t eI nvoi ce( I nvoi ce i nvoi ce, El ement el em) { wri t eDocument ( i nvoi ce, el em); El ement order = addChi l d( el em, "order") ; I nvoi ceI t em[] i t ems = i nvoi ce. get I t ems( ) ; f or ( i nt i = 0; i < i t ems. l engt h; ++i ) { wri t eI nvoi ceI t em(i t ems[ i ] , addChi l d( order, "i t em") ) ; addChi l d( el em, "t ax", nf . f ormat ( i nvoi ce. get Tax( ) ) ) ; addChi l d( el em, "shi ppi ngAndHandl i ng", nf . f ormat ( i nvoi ce. get Shi ppi ngAndHandl i ng( ) ) ) ; addChi l d( el em, "t ot al Cost ", nf . f ormat ( i nvoi ce. get Tot al Cost ( ) ) ) ; } Service Requestor View

      The PO Web service client im plem ent at ion follow s t he sam e pat t ern as t he invoice checker client s ( see List ing 3.12 ) . The goal of it s API is t o hide t he det ails of Axis- specific

      invoke() InputStream

      API s from t he service request or. Therefore, t he m et hod t akes an for t he purchase order XML and ret urns t he generat ed invoice as a st ring. Alt ernat ively,

      invoke() t he m et hod m ight have been w rit t en t o t ake in and ret urn DOM docum ent s.

      Listing 3.12 PO Submission Web Service Client

      package ch3. ex4; i mport j ava. i o. *; i mport org. apache. axi s. encodi ng. Seri al i zat i onCont ext ; i mport org. apache. axi s. message. SOAPEnvel ope; i mport org. apache. axi s. message. SOAPBodyEl ement ; i mport org. apache. axi s. cl i ent . Servi ceCl i ent ; i mport org. apache. axi s. Message; i mport org. apache. axi s. MessageCont ext ; /**

    • Purchase order submissi on cl i ent
    • / publ i c cl ass POSubmissi onCl i ent { /**
    • Target servi ce URL
    • / pri vat e St ri ng url ; /**
    • Creat e a cl i ent wi t h a t arget URL
    • / publ i c POSubmissi onCl i ent ( St ri ng t arget Url ) { url = t arget Url ; } /**
    • I nvoke t he PO submissi on web servi ce
    • >@param po Purchase order document
    • @ret urn I nvoi ce document
    • @except i on Except i on I /O error or Axi s error
    publ i c St ri ng i nvoke( I nput St ream po) t hrows Except i on { // Send t he message Servi ceCl i ent cl i ent = new Servi ceCl i ent ( url ) ; cl i ent . set Request Message( new Message( po, t rue) ) ; cl i ent . i nvoke( ) ; // Ret ri eve t he response body MessageCont ext ct x = cl i ent . get MessageCont ext ( ) ; Message out Msg = ct x. get ResponseMessage( ) ; SOAPEnvel ope envel ope = out Msg. get AsSOAPEnvel ope( ) ; SOAPBodyEl ement body = envel ope. get Fi rst Body( ) ; // Get t he XML f rom t he body St ri ngWri t er w = new St ri ngWri t er( ) ; Seri al i zat i onCont ext sc = new Seri al i zat i onCont ext ( w, ct x) ; body. out put ( sc) ; ret urn w. t oSt ri ng( ) ; } }

      ServiceClient

      Sending t he request m essage is sim ple. We have t o creat e a from t he t arget URL and set it s request m essage t o a m essage const ruct ed from t he purchase

      Message true

      order input st ream . The second param et er t o t he const ruct or, t he boolean , is an indicat ion t hat t he input st ream represent s t he m essage body as opposed t o t he

      invoke() w hole m essage. Calling sends t he m essage t o t he Web service.

      The second part of t he m et hod has t o do w it h ret rieving t he body of t he response

      E-mail

      m essage. This code should be fam iliar from t he im plem ent at ion of t he header handler. Finally, w e use an Axis serializat ion cont ext t o w rit e t he XML in t he response body int o a

      StringWriter

      . We could have easily got t en t he body as a DOM elem ent by calling is

      getAsDOM()

      m et hod. The t rouble is, t here is no st andard w ay in DOM Level 2 t o convert a DOM elem ent int o a st ring! Java API for XML Processing ( JAXP) defines such a

      javax.xml.transform

      m echanism in it s t ransform at ion API ( package) , but t he m et hod is

      SerializationContext fairly cum bersom e. I t is easiest t o use an Axis obj ect .

      Service Provider View

      The im plem ent at ion of t he purchase order subm ission service is very sim ple ( see List ing

      3.13 ) . Because t his is not an RPC- based service, t he input and out put are bot h XML Document

      docum ent s ( represent ed via DOM obj ect s) . The input docum ent is deserialized t o produce a purchase order obj ect . I t is passed t o t he act ual PO processing backend. I t s im plem ent at ion is not show n here because it has not hing t o do w it h Web services. I t looks up it em prices by t heir SKU, calculat es t ot als based on it em quant it ies, and adds t ax and shipping and handling. The result ing invoice obj ect is serialized t o produce t he result of t he purchase order subm ission service.

      Listing 3.13 Purchase Order Submission Web Service

      package com.skat est own. servi ces; i mport j avax. xml. parsers. *; i mport org. w3c. dom.*; i mport com.skat est own. backend. *; i mport com.skat est own. dat a. *; i mport com.skat est own. xml. *; i mport bws. BookUt i l ; /**

    • Purchase order submissi on servi ce
    • / publ i c cl ass POSubmissi on { /**
    • Submit a purchase order and generat e an i nvoi ce
    • / publ i c Document submit PO( MessageCont ext msgCont ext , Document i nDoc) t hrows Except i on { // Creat e a PO f rom t he XML document

      Document Bui l derFact ory f act ory = Document Bui l derFact ory. newI nst ance( ) ;

      Document Bui l der bui l der = f act ory. newDocument Bui l der( ) ; PO po = Deseri al i zer. creat ePO( i nDoc. get Document El ement ( ) ) ;

      // Get t he product dat abase Product DB db = BookUt i l . get Product DB( msgCont ext ) ; // Creat e an i nvoi ce f rom t he PO POProcessor processor = new POProcessor( db) ; I nvoi ce i nvoi ce = processor. processPO( po) ; // Seri al i ze t he i nvoi ce t o XML Document newDoc = Seri al i zer. wri t eI nvoi ce( bui l der, i nvoi ce) ; ret urn newDoc; } }

      Finally, adding deploym ent inform at ion about t he new service involves m aking a sm all change t o t he Axis Web services deploym ent descript or ( see List ing 3.14 ) . Again,

      Chapt er 4 w ill go int o t he det ails of Axis deploym ent descript ors.

      Listing 3.14 Deployment Descriptor for Purchase Order Submission Service

      <! - - Chapt er 3 exampl e 4 servi ces - - > <servi ce name="POSubmissi on" pi vot ="MsgDi spat cher"> <opt i on name="cl assName" val ue="com.skat est own. servi ces. POSubmissi on"/> <opt i on name="met hodName" val ue="doSubmissi on"/> </servi ce> Putting the Service to the Test ch3/ex4/index.jsp

      A sim ple JSP t est harness in ( see Figure 3.16 ) t est s t he purchase

      /resources/samplePO.xml

      order subm ission service. By default , it loads , but you can m odify t he purchase order on t he page and see how t he invoice you get back changes.

    Figure 3.16. Putting the PO submission Web service to the test.

      SOAP on the Wire

      Wit h t he help of TCPMon, w e can see w hat SOAP m essages are passing bet w een t he client and t he Axis engine:

      POST /bws/servi ces/POSubmissi on HTTP/1. 0 Host : l ocal host Cont ent - Lengt h: 1169 Cont ent - Type: t ext /xml; charset =ut f - 8 SOAPAct i on: "" <?xml versi on="1. 0" encodi ng="UTF- 8"?> <SOAP- ENV: Envel ope SOAP- ENV: encodi ngSt yl e="ht t p: //schemas. xmlsoap. org/soap/encodi ng/" xmlns: xsd="ht t p: //www. w3. org/2001/XMLSchema" xmlns: SOAP- ENV="ht t p: //schemas. xmlsoap. org/soap/envel ope/" xmlns: xsi ="ht t p: //www. w3. org/2001/XMLSchema- i nst ance"> <SOAP- ENV: Body> <po xmlns="ht t p: //www. skat est own. com/ns/po" i d="50383" submit t ed="2001- 12- 06"> . . . </po> </SOAP- ENV: Body> </SOAP- ENV: Envel ope>

      /bws/services/POSubmission

      The t arget URL is . The response m essage sim ply carries an invoice inside it , m uch in t he sam e w ay t hat t he request m essage carries a purchase order. As a result , t here is no need t o show it here.

      That 's all t here is t o t aking advant age of SOAP- based m essaging. Axis m akes it very easy t o define and invoke services t hat consum e and produce arbit rary XML m essages.

    Figure 3.17 show s one w ay t o t hink about t he int eract ion of abst ract ion layers in SOAP

      m essaging. I t is m odeled aft er Figure 3.3 earlier in t he chapt er but includes t he addit ional role of a service developer. As before, t he only " real" on- t he- w ire com m unicat ion happens bet w een t he HTTP client and t he Web server t hat dispat ches a service request t o Axis.

    Figure 3.17. Layering of abstraction for SOAP messaging.

      The abst ract ions at t his level are HTTP packet s. At t he Axis level, t he abst ract ions are SOAP m essages w it h som e addit ional cont ext . For exam ple, on t he provider side, t he t arget service is det erm ined by t he t arget URL of t he HTTP packet . This piece of cont ext inform at ion is " at t ached" t o t he act ual SOAP m essage by t he Axis servlet t hat list ens for HTTP- based Web service request s. The j ob of a service- level developer is t o creat e an abst ract ion layer t hat m aps Java API s t o and from SOAP m essages. During SOAP m essaging, a lit t le m ore w ork needs t o happen at t his level t han w hen doing RPCs. The reason is t hat dat a m ust be m anually encoded and decoded by bot h t he Web service client and t he Web service backend. Finally, at t he t op of t he st ack on bot h t he request or and provider sides sit s t he applicat ion developer w ho is happily insulat ed from t he fact t hat Web services are being used and t hat Axis is t he Web service engine. The applicat ion developer needs only t o underst and t he concept s pert aining t o his applicat ion dom ain—in t his case, purchase orders and invoices.

      SOAP Protocol Bindings

      So far in t his chapt er, w e have only show n SOAP being t ransm it t ed over HTTP. SOAP, how ever, is t ransport - independent and can be bound t o any prot ocol t ype. This sect ion looks at som e of t he issues involved in building Web services and t ransport ing SOAP m essages over various prot ocols.

    General Considerations

      The key issue in deciding how t o bind SOAP t o a part icular prot ocol has t o do w it h ident ifying how t he requirem ent s for a Web service ( RPC or not , int eract ion pat t ern, synchronicit y, and so on) m ap t o t he capabilit ies of t he underlying t ransport prot ocol. I n

      part icular, t he t ask at hand is t o det erm ine how m uch of t he t ot al inform at ion needed t o successfully execut e t he Web service needs t o go in t he SOAP m essage versus som ew here else. As Figure 3.18 show s w it h an HTTP exam ple, m any prot ocols have a packaging not ion. I f SOAP is t o be t ransm it t ed over such prot ocols, a dist inct ion needs t o be m ade bet w een physical ( t ransport - level) and logical ( SOAP) m essages. Cont ext inform at ion can be passed in bot h. I n t he case of HTTP, cont ext inform at ion is passed via t he t arget URI and

      SOAPAction

      t he header. Securit y inform at ion m ight com e as HTTP usernam e and

    Figure 3.18. Logical versus physical messages.

      Som et im es, SOAP m essages have t o be passed over prot ocols w hose physical m essages do not have any m echanism for st oring cont ext . Consider pure socket s- based exchanges. By default , in t hese cases t he physical and t he logical m essage are one and t he sam e. I n t hese cases, you have four opt ions for passing cont ext inform at ion:

      By convention, as in, "When listening on port 12345, I know that I • have to invoke service X." By entirely using SOAP's header-based extensibility mechanism to pass • all context information.

    • By custom-building a very light physical protocol under SOAP

      messages, as in, "The first CRLF delimited line of message will be the target URI; the rest will be the SOAP message." By using a lightweight protocol that can be layered on top of the • physical protocol and can be used to move SOAP messages. Examples of such protocols are Simple MIME Exchange Protocol (SMXP) or Blocks Extensible Exchange Protocol (BEEP).

      As in m ost cases in t he soft w are indust ry, reinvent ing t he w heel is a bad idea. Therefore, t he second and fourt h approaches list ed here t ypically m ake t he m ost sense. The first approach is not ext ensible and can leave you in a t ight spot if requirem ent s change. The approach is t hat you have t o m ake sure t hat all client s int eract ing w it h your Web service w ill be able t o support t he necessary ext ensions. The cost of going w it h t he fourt h approach is t hat it m ight require addit ional infrast ruct ure for bot h request ors and providers.

      Anot her considerat ion t hat com es int o play is t he int eract ion pat t ern support ed by t he t ransport prot ocol. For exam ple, HTTP is a request - response prot ocol. I t m akes RPCs and request - response m essaging int eract ions very sim ple. For ot her prot ocols, you m ight have t o explicit ly m anage t he associat ion of request s and responses. As w e m ent ioned in t he previous sect ion, Chapt er 6 discusses t his t opic in m ore det ail. Cont rary t o popular belief, Web services do not have t o involve st at eless int eract ions. For exam ple, Web services could be designed in a session- orient ed m anner. This is probably not t he best design for a high- volum e Web service, but it could w ork fine in m any cases. HTTP sessions can be leveraged t o provide cont ext inform at ion relat ed t o t he session. Ot herw ise, you w ill have t o use a session I D of som e kind, m uch in t he sam e w ay a m essage conversat ion I D is used.

      Finally, w hen choosing t ransport prot ocols for Web services, t hink carefully about ext ernal requirem ent s. You m ay discover im port ant fact ors ent irely out side t he needs of t he Web service engine. For exam ple, w hen considering Web services over socket s as a higher- perform ance alt ernat ive t o Web services over HTTP ( request s and responses don't have t o go t hrough t he Web server) , you m ight w ant t o consider t he follow ing fact ors:

      If services have to be available over a public unsecured network, is • it an acceptable risk to open a hole through the firewall for Web service traffic? Can clients support SSL to ensure the privacy of messages?

    • Surprisingly, some clients can speak HTTPS but not straight SSL.

      What are the back-end load balancing and failover requirements? • Straight sockets-based communication requires sticky load balancing. You establish a session with one server and you have to keep using this server. This approach potentially compromises scalability and failover, unless steps are taken to build request redirection and

      session persistence and failover capabilities into the system.

      As w it h m ost t hings in t he soft w are indust ry, t here is no single correct approach and no single right answ er. I nvest igat e your requirem ent s carefully and do not be easily t em pt ed by seem ingly excit ing, out - of- t he- ordinary solut ions. The rest of t his sect ion provides som e m ore det ails about how cert ain prot ocols can be used w it h SOAP.

      This chapt er has show n m any exam ples of SOAP over HTTP. The SOAP specificat ion defines a binding of SOAP over HTTP w it h t he follow ing set of rules:

      The MIME media type of both HTTP requests and responses (defined in • the Content-Type HTTP header) must be text/xml. Requests must come as HTTP POST operations. •

      SOAPAction The • header is reserved as a hint to the SOAP processor as to which Web service is being invoked. The value of the header can be any URI; it is implementation-specific.

      Successful SOAP message processing must return an HTTP error code in

    • the 200 range. Typically, this is 200 OK. In the case of an error generated while processing the SOAP message, • the HTTP response code must be 500 Internal Server Error and it must

      

    Fault

    include a SOAP message with a element describing the error.

      I n addit ion t o t hese sim ple rules, t he SOAP specificat ion defines how SOAP m essages can be exchanged over HTTP using t he HTTP Ext ension Fram ew ork ( RFC 2774,

      

    ht t p: / / w w w .norm os.org/ iet f/ rfc/ rfc2774.t xt ) , but t his inform at ion is not very relevant t o

    us.

      I n short , HTTP is t he m ost com m only used m echanism for exchanging SOAP m essages. I t is aided by t he indust ry's experience building relat ively secure, scalable, reliable net w orks t o handle HTTP t raffic and by t he fact t hat t radit ional Web applicat ions and applicat ion servers prim arily use HTTP. HTTP is not perfect , but w e are very good at w orking around it s lim it at ions. For secure m essage exchanges, you can use HTTPS inst ead of HTTP. The m ost com m on ext ension on t op of w hat t he SOAP specificat ion describes is t he use of HTTP usernam es and passw ords t o aut hent icat e Web service client s. Com bined w it h HTTPS, t his approach offers a good- enough level of securit y for m ost e- com m erce scenarios. Chapt er 5 discusses t he role of HTTPS in Web services.

    SOAP Messages with Attachments

      SOAP m essages w ill oft en have at t achm ent s of various t ypes. The prot ot ypical exam ple is an insurance claim form in XML form at t hat has an accident pict ure associat ed wit h it and/ or a scanned copy of t he signed accident report form . The SOAP Messages w it h At t achm ent s specificat ion defines a sim ple m echanism for encoding a SOAP m essage in a MI ME m ult ipart st ruct ure and associat ing t his m essage w it h any num ber of part s ( at t achm ent s) in t hat st ruct ure. These at t achm ent s can be in t heir nat ive form at , which is t ypically binary.

      Wit hout going int o t oo m any det ails, t he SOAP m essage becom es t he root of t he m ult ipart / relat ed MI ME st ruct ure. The m essage refers t o at t achm ent s using a URI w it h

      cid

      t he : prefix, w hich st ands for " cont ent I D" and uniquely ident ifies t he part s of t he MI ME st ruct ure. Here is how t his is done. Not e t hat som e long lines ( such as t he

      Content-Type

      header) have been broken in t w o for bet t er readabilit y:

      MIME- Versi on: 1. 0 Cont ent - Type: Mul t i part /Rel at ed; boundary=MIME_boundary; t ype=t ext /xml; st art ="<cl ai m061400a. xml@cl ai ming- i t . com>" Cont ent - Descri pt i on: Thi s i s t he opt i onal message descri pt i on.

    • MIME_boundary Cont ent - Type: t ext /xml; charset =UTF- 8 Cont ent - Transf er- Encodi ng: 8bi t Cont ent - I D: <cl ai m061400a. xml@cl ai ming- i t . com> <?xml versi on=' 1. 0' ?>
    xmlns: SOAP- ENV="ht t p: //schemas. xmlsoap. org/soap/envel ope/"> <SOAP- ENV: Body> . . <t heSi gnedForm href ="ci d: cl ai m061400a. t i f f @cl ai ming- i t . com"/> . . </SOAP- ENV: Body> </SOAP- ENV: Envel ope>

    • MIME_boundary Cont ent - Type: i mage/t i f f Cont ent - Transf er- Encodi ng: bi nary Cont ent - I D: <cl ai m061400a. t i f f @cl ai ming- i t . com> . . . bi nary TI FF i mage. . .
    • MIME_boundary- -

      One excellent t hing about encapsulat ing SOAP m essages in a MI ME st ruct ure is t hat t he packaging is independent of an act ual t ransport prot ocol. I n a sense, t he MI ME package is anot her logical m essage on t op of t he SOAP m essage. This t ype of MI ME st ruct ure can t hen be bound t o any num ber of ot her prot ocols. The specificat ion defines a binding t o HTTP, an exam ple of w hich is show n here:

      POST /i nsuranceCl ai ms HTTP/1. 1 Host : www. ri sky- st uf f . com Cont ent - Type: Mul t i part /Rel at ed; boundary=MIME_boundary; t ype=t ext /xml; st art ="<cl ai m061400a. xml@cl ai ming- i t . com>" Cont ent - Lengt h: XXXX SOAPAct i on: ht t p: //schemas. ri sky- st uf f . com/Aut o- Cl ai m . . .

      SOAP over SMTP

      E- m ail is pervasive on t he I nt ernet . The im port ant e- m ail- relat ed prot ocols are Sim ple Mail Transfer Prot ocol ( SMTP) , Post Office Prot ocol ( POP) , and I nt ernet Message Access Prot ocol ( I MAP) . E- m ail is a great w ay t o exchange SOAP m essages w hen synchronicit y is not required because:

      E-mail messages can easily carry SOAP messages. • E-mail messages have extensible headers that can be used to transmit • context information outside the SOAP message body.

    • Both sending and receiving of e-mail messages can be configured to

      require authentication. Further, using S/MIME with e-mail provides additional security for a range of applications. E-mail can support one-to-one and one-to-many participant • configurations. E-mail messaging is buffered and queued with reliable dispatch that • automatically includes multiple retries and failed delivery notification. Toget her, t hese fact ors m ake e- m ail a very suit able alt ernat ive t o HTTP for asynchronous Web service m essaging applicat ions.

    Other Protocols

      Despit e it s low- t ech nat ure, FTP can be very useful for sim ple one- way m essaging using Web services. Access t o FTP servers can be aut hent icat ed. Furt her, roles- based rest rict ions can be applied t o part icular direct ories on t he FTP server. When using FTP, SOAP m essages are m apped ont o t he files t hat are being t ransferred. Typically, t he file nam es indicat e t he t arget of t he SOAP m essage.

      I n addit ion, w it h com panies such as Microsoft backing SMXP for t heir Hailst orm init iat ives, t he prot ocol is em erging as a pot ent ial candidat e t o layer on t op of st raight socket - based com m unicat ions for t ransm ission of SOAP m essages. Finally, sophist icat ed m essaging infrast ruct ures such as I BM's MQSeries, Microsoft 's Message Queue ( MSMQ) , and t he Java Messaging Service ( JMS) are w ell- suit ed for t he t ransport of SOAP m essages. Chapt er 5 shows an exam ple of SOAP m essaging using JMS. The key const raint lim it ing t he w ide deploym ent of SOAP bindings t o prot ocols ot her t han HTTP and e- m ail is t he requirem ent of Web service int eroperabilit y. HTTP and e- m ail are so pervasive t hat t hey are likely t o rem ain t he preferred choices for SOAP m essage t ransport for t he foreseeable fut ure.

      Summary

      This chapt er addressed t he fourt h level of t he Web services int eroperabilit y st ack—XML m essaging. I t focused on explaining som e of t he core feat ures of XML prot ocols and SOAP 1.1 as t he de fact o st andard for Web service m essaging and invocat ion. The goal w as t o give you a solid underst anding of SOAP and a first - hand experience building and consum ing Web services using t he Apache Axis engine. To t his end, w e covered, in som e det ail:

      The evolution of XML protocols from first-generation technologies

    • based on pure XML 1.0 (WDDX and XML-RPC) to XML Schema-and Namespace- powered second-generation protocols, of which SOAP is a prime example. The chapter also discussed the motivation and history behind SOAP's creation.

      The simple yet flexible design of the SOAP envelope framework,

    • including versioning and vertical extensibility using SOAP headers. In SOAP, all context information orthogonal to what is in the SOAP body is carried via headers. SOAP's envelope framework allows you to

      design higher-level protocols on top of SOAP in a decentralized

      manner. SOAP intermediaries as the key innovation enabling horizontal • extensibility. Because of intermediaries, Web services can be organized into very flexible system and network architectures and

      value-added services can be provided on top of basic Web service

      messaging.
    • SOAP error handling using SOAP faults. Any robust messaging protocol

      needs a well-designed exception-handling model. With their ability to communicate error information targeted at both software and humans, as well as clearly identifying the source of the error condition, SOAP faults make it possible to integrate SOAP as part of robust, mission-critical systems.

    • Encoding data using SOAP. The chapter covered both SOAP's abstract

      data model encoding and a number of other heuristics for determining an appropriate data representation model for SOAP messages.

    • Using SOAP for both messaging and RPC applications. By design, SOAP

      is independent of all traditional aspects of messaging: participant organization, interaction pattern, synchronicity, and so on. As a result, SOAP can be used for just about any distributed system. This chapter provided some guidelines that help narrow the space of what

    is possible to the space of what makes sense in the real-world

    solutions.

    • Using SOAP over multiple protocols. The SOAP specification mentions an HTTP binding for SOAP, but Web services can be meaningfully bound

      to many other packaging and protocol schemes: MIME packages to

      support attachments, SMTP for scalable asynchronous messaging without the need for special middleware, and many others.

      During t he course of t he chapt er, w e developed t w o m eaningful e- com m erce Web services for Skat esTow n: an invent ory check RPC service ( w it h or w it hout e- m ail confirm at ions) and a purchase order subm ission m essaging service. Our im plem ent at ion on bot h t he server and t he client used design best pract ices for separat ing dat a and business logic from t he det ails of SOAP and XML processing.

      The Road Ahead

      This chapt er focused on t he de fact o st andard prot ocol for Web service invocat ion as of t he t im e of t his w rit ing—SOAP 1.1. ( SOAP 1.2 is st ill in early draft st age.) How ever, m any m ore pieces t o t he puzzle are required t o bring m eaningful Web services- enabled business solut ions online. The rest of t he book w ill com plet e t he Web services puzzle.

      Chapt er 5 focuses on building secure, robust , scalable ent erprise- grade Web services. Chapt er 6 int roduces t he concept of service descript ions and t he Web Services

      Descript ion Language ( WSDL) . Chapt er 7 discusses service regist ries and t he Universal Descript ion, Discovery and I nt egrat ion ( UDDI ) effort . Chapt er 8 review s t he st at e of t he current ly available Web services t ooling. Chapt er 9 looks at t he excit ing w orld of Web service fut ures. This said, t he next chapt er offers a short det our for t hose w ho are t ruly excit ed about building and consum ing ext ensible, high- perform ance Web services—it is about building Web services using t he advanced feat ures of Apache Axis.

      Resources • BEEP—RFC 3080: " The Blocks Ext ensible Exchange Prot ocol Core" ( I ETF, March 2001) .

      Available at ht t p: / / w w w .iet f.org/ rfc/ rfc3080.t xt .

    • DOM Level 2 Core—W3C ( World Wide Web Consort ium ) Docum ent Obj ect Model Level 2 Core ( W3C, Novem ber 2000) . Available at ht t p: / / w w w .w 3.org/ TR/ 2000/ REC- DOM- Level- 2- Core- 20001113 .
    • HTTP ext ensions—RFC 2774: " An HTTP Ext ension Fram ew ork" ( I ETF, February 2000) . Available at ht t p: / / w w w .iet f.org/ rfc/ rfc2774.t xt .
    • HTTP/ 1.1—RFC 2616: " Hypert ext Transfer Prot ocol—HTTP/ 1.1" ( I ETF, January 1997) . Available at ht t p: / / w w w .iet f.org/ rfc/ rfc2616.t xt .
    • JAXP—Java API for XML Processing 1.1 ( Sun Microsyst em s, I nc., February 2001) . Available at ht t p: / / j ava.sun.com / xm l/ xm l_j axp.ht m l .
    • MI ME—RFC 2045: " Mult ipurpose I nt ernet Mail Ext ensions ( MI ME) Part One: Form at of

      I nt ernet Message Bodies" ( I ETF, Novem ber 1996) . Available at ht t p: / / w w w .iet f.org/ rfc/ rfc2045.t xt .

    • SMXP—Sim ple MI ME eXchange Prot ocol ( SMXP) ( First Virt ual, May 1995) . Available at ht t p: / / w uarchive.w ust l.edu/ packages/ first - virt ual/ docs/ sm xp- spec.t xt .
    • XML—Ext ensible Markup Language ( XML) 1.0, Second Edit ion ( W3C, August 2000) . Available at ht t p: / / w w w .w 3.org/ TR/ 2000/ WD- xm l- 2e- 20000814 .
    • XML Nam espaces" Nam espaces in XML" ( W3C, January 1999) . Available at ht t p: / / w w w .w 3.org/ TR/ 1999/ REC- xm l- nam es- 19990114 .
    • XML Schem a Part 1: St ruct ures" XML Schem a Part 1: St ruct ures" ( W3C, May 2001) . Available at ht t p: / / w w w .w 3.org/ TR/ 2001/ REC- xm lschem a- 1- 20010502 .
    • XML Schem a Part 2: Dat at ypes" XML Schem a Part 2: Dat at ypes" ( W3C, May 2001) . Available at ht t p: / / w w w .w 3.org/ TR/ 2001/ REC- xm lschem a- 1- 20010502 .

    Why and What Is Axis?

      Axis is t he lat est version of t he Apache SOAP proj ect . The acronym Axis m eans Apache Ext ensible I nt eract ion Syst em , a fancy w ay of saying it 's a SOAP processor t hat allow s for an assort m ent of pluggable com ponent s t o be configured in a variet y of w ays. We chose t his SOAP processor for a few reasons. First , m ost of t he aut hors of t his book are ( or have been) involved in t he developm ent of Axis from it s incept ion. Second, w e believe t hat Axis's flexibilit y and overall design w ill allow it t o becom e one of t he leading SOAP processors very quickly. And t hird, because it is an Apache open source proj ect , w e believe it w ill gain t he benefit s of having cont ribut ors from a w ide range of backgrounds and com panies, giving it a t echnological edge over ot her SOAP im plem ent at ions. But , only t im e w ill t ell.

      Apache SOAP v2 ( ht t p: / / xm l.apache.org/ soap ) , t he predecessor t o Axis, is a fairly good im plem ent at ion of t he SOAP specificat ion, but it has it s lim it at ions. Alt hough it can be used for deploying Web services, t he perform ance and pluggabilit y of SOAP v2 leave a lot t o be desired. At t he t im e of t his w rit ing, Axis is already quit e a bit fast er t han SOAP v2; and alt hough SOAP v2 provides som e level of pluggabilit y for com ponent s like different kinds of Web services or for different t ransport s , t hese feat ures w ere added as an aft ert hought —t he design deficiencies of t hese feat ures show s t hrough in t heir usabilit y ( or lack t hereof) . SOAP v2 also isn't fully com pliant w it h t he SOAP 1.1 specificat ion.

      I t is im port ant t o not e t hat at t he t im e of t his w rit ing Axis has not yet released it s first version. I t has, how ever, released an alpha version. This alpha version is not com plet e ( or fully SOAP 1.1 spec com pliant ) , but it is funct ional enough for people t o st art kicking t he t ires and get t ing a feel for w het her t he archit ect ure is good. By t he t im e t he first release does com e out ( before t he end of 2001, w e hope) it w ill be fully spec com pliant . so releasing an alpha version is a key m ilest one in Axis' developm ent cycle. This chapt er w ill focus m ainly on t he current funct ionalit y of Axis—w hen appropriat e, how ever, it w ill give insight int o t he possible fut ure feat ures of Axis ( t he design could change) .

    The Axis Architecture

      From t he st art , Axis w as designed w it h a com plet ely open and pluggable archit ect ure. I n it s sim plest form , Axis can be viewed as a t hin layer t hat sit s bet w een t he business logic and t he net w ork t ransport carrying your dat a. As depict ed in Figure 4.1 , Axis is sim ply t he m eans by w hich t he SOAP m essage is t aken from a t ransport ( such as HTTP) and handed t o t he Web service and t he m eans by w hich any response is form at t ed as a SOAP m essage t o t hen be sent back t o t he request or. Alt hough t his m ight seem like an oversim plificat ion, Axis is designed t o be used in a w ide range of environm ent s and by deploym ent engineers w it h varying skill levels. When you're first experim ent ing w it h Web services, or if you don't need com plex configurat ions, Axis by default w ill m ake t he deploym ent of Web services very easy. The " Sim ple Web Services " sect ion w ill describe t his furt her by show ing you how t o quickly t ake Java code and deploy it as a Web service in Axis. How ever, if you need a m ore com plex processing m odel, Axis can be configured t o support t hat , t oo.

    Figure 4.1. Basic overview of Axis.

      Axis Components

      Next , w e're going t o focus on t he various com ponent s of Axis. Each it em in t he follow ing list w ill be discussed in m ore det ail, but here's brief sum m ary of t he key com ponent s:

      Axis Engine — The main entry point into the SOAP processor • Handlers — The basic building blocks inside Axis that link Axis • to existing back-end systems Chain — An ordered collection of handlers (and a handler • itself) Transports— Mechanisms by which SOAP messages flow into and out of

    • Axis Deployment/Configuration— Means through which Web services are made • available through Axis Serializers/Deserializers— Code that will convert native (for • example, Java) datatypes into XML and back

      Axis Engine As you could probably guess, t he Axis engine is t he focal point of t he Axis SOAP processor. The engine's j ob is t o act as t he m ain ent ry point int o Axis' m essage com ponent s. The engine is also responsible for ensuring t hat t he SOAP sem ant ics are

      mustUnderstand

      follow ed—for exam ple, it w ill verify t hat t he checks are properly perform ed. I n t he follow ing sect ions, w e'll discuss t he ot her com ponent s t hat m ake up t he processing m odel, but it is im port ant t o know t hat t he engine is t he piece responsible for coordinat ing t he order in w hich t hose ot her com ponent s are invoked. As w e discuss each of t hese com ponent s, w e'll describe t heir int eract ion w it h t he engine in m ore det ail. During t he design process of Axis, it w as realized t hat it w ould be im possible t o design a SOAP m essage processor in such a w ay t hat it could w ork for t he w ide- ranging uses w e w ant ed for Axis unless it w as flexible enough t o allow deploym ent engineers ( configurat ion adm inist rat ions) t o cont rol t he m essage flow it self. Allow ing people t o t ell Axis w hich m essage processing logic t o perform , in w hat order, and w hen, becam e a clear requirem ent . I t also becam e apparent t hat t here w ould be no w ay of know ing how people w ould w ant t o process t he SOAP m essages. For exam ple, m any people see SOAP as sim ply anot her Rem ot e Procedure Call ( RPC) m echanism —w hich is a valid use. How ever, t here is no reason t he exact sam e SOAP m essage t hat m ight be t reat ed as an RPC m essage by one SOAP processor could not be t reat ed as an XML docum ent and sim ply run t hrough an XSLT processor by anot her. As long t hey bot h adhere t o t he SOAP specificat ion, and of course follow t he sem ant ic rules defined by t he Web service definit ion, exact ly how t he SOAP m essage is processed is w ide open. So, how does Axis handle t hese challenges? Handlers and chains. Handlers and Chains At it s m ost basic level, Axis is all about chaining t oget her pieces of m essage processing logic. Figure 4.1 show s j ust one piece: t he Web service it self. Oft en, you'll need t o perform addit ional processing on t he m essage eit her before or aft er t he Web service it self is invoked. For exam ple, som e logging m ight need t o t ake place, or SOAP headers m ight need t o be processed. You can accom plish t his t w o w ays: Place t his addit ional logic in t he Web service it self or allow for addit ional pieces of code t o be execut ed out side of, but before and aft er, t he Web service. For t his purpose, Axis has t he not ion of chains. Chains are sim ply ordered collect ions of com ponent s ( code) t hat Axis w ill invoke sequent ially and in t he order specified.

      The com ponent s t hat are used t o build t hese chains are called handlers. Each handler has t he opport unit y t o exam ine or m odify t he SOAP m essage in order t o com plet e it s j ob. For exam ple, it is possible t o have a handler in t he chain t hat w ill look for any encrypt ed dat a in t he m essage and decrypt it before t he Web service it self is invoked ( SOAP encrypt ion is explained in m ore det ail in Chapt er 5 , " Using SOAP for e- Business" ) . By m odularizing t he work in t his way, each handler is free t o focus on it s core j ob and not w orry about any possible auxiliary w ork t hat m ight need t o be done, t hereby elim inat ing code duplicat ion. Also, if new pre- or post - processing is needed in t he fut ure, it becom es a sim ple m at t er of plugging new handlers int o t he chain t hrough configurat ion changes t o Axis rat her t han having t o m ake code changes t o t he Web service. This also allow s t hird- part y vendors t o produce Axis handlers t hat can be snapped int o any configurat ion w it hout prior know ledge of t he exact environm ent , configurat ion, or Web service being invoked.

      Handlers are t he basic building blocks inside Axis. Everyt hing, even t he Axis engine and t he chains t hem selves, is a handler. As a result , t he deploym ent engineer is free t o configure Axis in an unlim it ed num ber of w ays. I t is possible for a preprocessing handler shown in Figure 4.2 t o be a chain t hat it self cont ains a collect ion of handlers ( or even m ore chains) . Aside from each handler having access t o t he SOAP m essage, each handler can also be involved in t he product ion of any possible SOAP response m essage. We'll give m ore det ails in t he " Building Handlers " sect ion, but it is w ort h reit erat ing t hat each handler does have access t o ( and can change) t he request m essage and any possible response m essage t hat m ight exist during t he processing flow t hrough t he Ax is

    Figure 4.2. Pre- and post-processing is done by defining a chain.

      Chains are t he m echanism s by w hich handlers are grouped t oget her. The concept is sim ple; a chain is an ordered collect ion of handlers t hat t oget her can be view ed as a single unit of processing. As w it h any good rule, t here is a slight com plicat ion—cert ain t ypes of chains have t he not ion of a pivot point handler, w hich is t he point at w hich t he chain not es t hat it has swit ched from processing t he request SOAP m essage ( request processing) and is now processing t he response SOAP m essage ( response processing) . The need for t his logical split bet w een request , pivot point , and response handlers in a chain w ill be m ade clearer lat er. This pivot point handler also serves as t he one handler in t hese t ypes of chains t hat is t he real reason t he chain exist s—t o dispat ch t he m essage t o t he t arget Web service ( t he ot her handlers are t here for request and response processing of t he m essage) . The m ost com m on use of t his t ype of chain ( also called t arget ed- chain because it is view ed as point ing t o t he pivot point handler) is t he Web service–specific chain. I n Figure 4.2 , a Web service chain has request and response processing handlers defined, but t he pivot point handler invokes t he Web service. Even t hough Axis has, for program m er convenience, defined a part icular kind of chain encapsulat ing t hese t hree pieces, w hen a chain is defined t here is no reason t hat all t hree pieces need t o be used. For exam ple, it is possible t o define a chain t hat is j ust a collect ion of handlers w it hout a specific pivot point —it is t here m erely as a configurat ion opt ion.

    Figure 4.2 show s t hat it is possible t o define a chain of handlers t hat are invoked for a

      part icular Web service. How ever, w hat if chains need t o be invoked for all Web service invocat ions flow ing t hrough Axis? Or, w hat if cert ain chains need t o be invoked only if t he m essage cam e in on HTTP, whereas if t he m essage was delivered via SMTP t hose chains should not be invoked? To support t hese configurat ions, Axis has t he not ion of t ransport specific chains and global chains . As show n in Figure 4.3 , Axis allow s t he definit ion of chains t hat are invoked based on t he t ype of t ransport used in t he delivery of t he SOAP m essage ( t ransport specific chains) and chains t hat should be invoked for all Web services ( global chains) .

    Figure 4.3. Axis includes three different levels of chaining. Transport - specific chains m ight be defined t o process such t hings as t ransport - specific com pression, or aut hent icat ion. The " Configurat ion Met hods " sect ion w ill discuss t he w ay t o deploy chains, but it is im port ant t o not e t hat t ransport specific chains are t arget ed- chains. The request and response sides are clearly separat ed so t hat t he Axis engine know s exact ly w hich subset of handlers t o invoke at t he st art of t he m essage flow and w hich set t o invoke at t he end of t he m essage flow . Alt hough it w as possible t o design Axis so t hat t here w ere t w o com plet ely separat e chains defined ( rat her t han one w it h a request and a response side) , it w as decided t hat because t hey w ould alw ays be used in conj unct ion w it h each ot her, and because it is expect ed t hat t here w ill be a large num ber of t ransport specific chains, it w ould be easier from a usabilit y point of view t o define t hem as one chain w it h t w o sides. Global chains com e in handy in cases when all Web services require t he sam e processing regardless of how t he m essage w as delivered or w hat t he specific Web service it self is— for exam ple, Skat esTow n m ight w ant t o keep a log of all Web service request s, and placing a logging handler in t he global chain becom es a cleaner w ay of deploying it t han placing it in each Web service–specific chain. Unlike t ransport chains t hat use t arget ed- chains, t he global chain is split int o t w o separat e chains. Because, concept ually, t here is only one global chain, it w as decided t hat it w ould be easier for deploym ent engineers t o

      global.request global.response

      define t w o separat ely nam ed chains ( and ) rat her t han one chain w it h t w o sides. We'll discuss t he det ails of how t o nam e chains in t he " Configuring Axis " sect ion. Wit hin t he Axis server- side engine, t he order of chain processing is as follow s:

      

    1. If a transport-specific chain is defined, then the handlers labeled

    as the request handlers defined for that chain are invoked.

      2. If a chain named global.request is defined, then it is invoked.

      3. The Web service–specific chain is invoked. Exactly how the Web service–specific chain is identified is discussed later. As noted before, this chain is a targeted-chain and has three groupings of handlers: the request handlers, the Web service itself (at the pivot point), and the response handlers. They are invoked in that order.

      4. If a chain named global.response is defined, it is invoked.

      

    5. If a transport specific chain is defined, then the handlers labeled as the response handlers defined for that chain are invoked. This processing m odel should allow a deploym ent engineer t o have t he com plet e flexibilit y of placing any handler at any point in t he flow of m essages t hrough t he server Axis engine. I n Figure 4.3 , t he Web service is show n as a handler at t he pivot point in t he Web service– specific chain. One layer of code is not shown: t he dispat cher .

    Figure 4.4 show s a dispat cher as t he pivot point handler in t he Web service–specific

      chain. Like all handlers, t his dispat cher is responsible for act ing as t he bridge bet w een Axis and your business logic. I t is t he j ob of t he dispat cher t o locat e and invoke t he appropriat e piece of code associat ed w it h t he desired Web service. For exam ple, Axis com es wit h an RPCDispat cher w hose j ob is t o convert t he SOAP m essage from

      XML int o Java obj ect s, locat e t he appropriat e Java m et hod t o invoke, invoke it , and convert any possible response dat a back int o XML and place it in t he response SOAP m essage. By having a dispat ch handler do t his w ork, it can be used for any Java Web service invoked. Likew ise, t he Web service it self does not need t o be concerned w it h t he det ails of how t he dat a w as delivered or how t o convert XML int o Java obj ect s; it can concent rat e on doing it s real j ob.

    Figure 4.4. Handlers, acting as dispatchers, are the bridges between Axis and application logic.

      Alt hough dispat chers have been present ed in t he cont ext of invoking t he Web service, any of t he handlers in any of t he chains could be dispat chers. I n ot her words, t here is no reason w hy any of t he request / response processing handlers need t o have t he business logic direct ly inside t hem . Those handlers could be dispat chers t hat ext ract t he necessary dat a from t he SOAP m essage and pass it along t o ext ernal code in t he proper form at . Transports I n order t o com plet e t he overall pict ure of t he Axis archit ect ure, one m ore piece of t he puzzle needs t o be brought in: t ransport s. All t he figures show a single Axis engine w it h a single t ransport delivering t he SOAP m essage; how ever, t his need not be t he case.

    Figure 4.5 show s t hat Axis can support a variet y of t ransport s, not j ust HTTP. Act ually,

      Axis it self doesn't support m ult iple t ransport s. Axis is designed such t hat t he Axis engine can be view ed sim ply as a chunk of code t hat is called w it h an incom ing m essage and ret urns an out going m essage. Transport list eners ( such as servlet s t hat wait for a not part of t he Axis engine. I t is assum ed t hat t he m echanism by w hich t he Axis engine is creat ed ( a new one on each request or shared inst ance) w ill be m anaged by t he t ransport list eners. Axis com es w it h a set of t ransport list eners ( such as t he

      AxisServlet

      ) t hat you can use, but if you require special processing, it is assum ed t hat you w ill m odify t he shipped t ransport list ener t o suit your needs or w rit e a new one.

    Figure 4.5. Multiple transports.

      The role of t he t ransport list ener is t o deliver t he SOAP m essage t o t he Axis engine. This could m ean list ening on port 80 for an HTTP request or w ait ing for a file t o be FTPed t o a cert ain direct ory and t hen handing t hat m essage t o t he Axis engine. Aside from invoking t he Axis engine, t he t ransport list ener m ust also t ell t he Axis engine w hich t ransport w as used—t his allow s Axis t o invoke any t ransport - specific chain t hat m ight have been configured.

      The delineat ion bet w een w het her cert ain processing should be in t he t ransport list ener or in t he t ransport specific chain is an issue left up t o t he deploym ent engineer. For exam ple, in t he HTTP case, t he servlet w ait ing for SOAP request s can also perform any basic HTTP aut hent icat ion checks before invoking t he Axis engine. I t is also perfect ly accept able for t he servlet t o not perform t hat check and leave it up t o a handler on t he t ransport specific chain t o do it . The choice is left open.

      

    List ing 4.1 show s a sam ple t ransport list ener t hat does not hing m ore t han look for a file

    inMsg

      called in t he current direct ory. I f t he file is found, t he t ransport list ener uses it as t he request ing SOAP m essage, calls Axis on it , and t hen places any response back int o a

      outMsg file called .

      Listing 4.1

      FileListener.java i mport j ava. i o. Fi l e; i mport j ava. i o. Fi l eI nput St ream; i mport j ava. i o. Fi l eOut put St ream; i mport j ava. i o. Fi l eNot FoundExcept i on; i mport org. apache. axi s. Axi sFaul t ; i mport org. apache. axi s. Axi sEngi ne; i mport org. apache. axi s. server. Axi sServer; i mport org. apache. axi s. Message; i mport org. apache. axi s. MessageCont ext ; i mport org. apache. axi s. message. SOAPEnvel ope; i mport org. apache. axi s. message. SOAPFaul t El ement ; publ i c cl ass Fi l eLi st ener { publ i c voi d run( ) { t ry {

    // Look f or an i ncoming msg, creat e a new Message obj ect

    Fi l eI nput St ream i nput = new Fi l eI nput St ream("i nMsg") ; Axi sEngi ne engi ne = Axi sServer. get Si ngl et on( ) ; MessageCont ext msgCont ext = new MessageCont ext ( engi ne) ; Message msg = new Message( i nput ) ; t ry { //Set i t as t he "request " message msgCont ext . set Request Message( msg) ; // Set t he Transport msgCont ext . set Transport Name( "f i l e") ; // I nvoke t he Axi s engi ne engi ne. i nvoke( msgCont ext ) ; } cat ch( Except i on e) { // Cat ch any error and st i ck i t i n t he response i f ( ! ( e i nst anceof Axi sFaul t ) ) e = new Axi sFaul t ( e) ; Axi sFaul t af = ( Axi sFaul t ) e; msg = msgCont ext . get ResponseMessage( ) ; i f ( msg == nul l ) { msgCont ext . set ResponseMessage( new Message( af ) ) ; } el se { SOAPEnvel ope env = msg. get AsSOAPEnvel ope( ) ; env. cl earBody( ) ; env. addBodyEl ement ( new SOAPFaul t El ement ( af ) ) ; } } // Cl ose and del et e t he i ncoming message i nput . cl ose( ) ; ( new Fi l e( "i nMsg") ) . del et e( ) ; // Pl ace t he response message i n a f i l e cal l ed "out Msg" msg = msgCont ext . get ResponseMessage( ) ;

    Fi l eOut put St ream out put = new Fi l eOut put St ream("out Msg") ;

    St ri ng resul t = ( St ri ng) msg. get AsSt ri ng( ) ; out put . wri t e( resul t . get Byt es( ) ) ; out put . cl ose( ) ; Syst em.out . pri nt l n( "Processed a request ") ; } cat ch( Except i on exp) { i f ( ! ( exp i nst anceof Fi l eNot FoundExcept i on) ) exp. pri nt St ackTrace( ) ; }

    t ry { Thread. sl eep( 1000 ) ; } cat ch( Except i on e) { } } } st at i c publ i c voi d mai n( St ri ng[ ] args) { ( new Fi l eLi st ener( ) ) . run( ) ; } }

      FileListener run()

      Let 's w alk t hrough t his exam ple. The 's m et hod w ill loop forever

      InputStream w hile w ait ing for a new m essage t o arrive. Once t here, an is creat ed for it . AxisServer getSingleton()

      The list ener w ill t hen ask Axis for an inst ance of an —t he

      MessageContext

      m et hod w ill ret urn t he sam e inst ance each t im e. Next w e creat e a obj ect . This w ill be discussed m ore in t he " Building Handlers " sect ion, but for now it is sim ply an obj ect t hat w ill cont ain all t he dat a ( request and response m essages, m et a- dat a, and so on) about t his current SOAP m essage flow ; it is passed t o each handler as it

      Message

      is invoked. I nside t his obj ect w e place a new obj ect t hat is creat ed by passing in

      InputStream

      t he file's . This w ill be t he request m essage. There's only one m ore t hing t o do before w e invoke t he engine, and t hat 's t o t ell Axis t he nam e of t he t ransport t hat w as

      

    file

      used t o ret rieve t he m essage—in t his case, . When t he engine w ant s t o invoke t he

      file t ransport - specific chain, it w ill look for one nam ed and, if found, invoke it .

      The rest of t he code processes any result from t he engine. We m ust , of course, handle any error condit ions. The Axis engine can t hrow an AxisFault ( see t he " Fault "

      catch

      sect ion) t hat m ust be caught and used t o creat e a response m essage. The block w ill also check t o see if a response m essage already exist s and clear any XML from t he

      Body sect ion if t here is one.

      I n eit her t he successful case or t he fault ing case, t he code w ill t hen get t he response

      String outMsg

      m essage as a , w rit e it out t o a file called , and t hen go look for m ore m essages. Com plet ing t he overall pict ure of w hat t he Axis engine's archit ect ure looks like, w e have Figure 4.6 .

    Figure 4.6. Complete Axis architecture. Alt hough t he final pict ure of t he Axis engine's processing m odel m ight seem a bit com plex, it really is not hing m ore t han defining handlers and chains. Of course, w e've overlooked one very im port ant issue; up t o t his point , t he focus has been on w hat an Axis engine does w hen it is on t he receiving side of t he SOAP m essage pat h ( t he server) . Axis can be used on t he client side, as w ell. Wit h j ust a few slight changes, all t he concept s w e've m ent ioned up t o now apply on t he client as show n in Figure 4.7 .

    Figure 4.7. Axis client architecture.

      I t should be clear t hat alm ost all t he sam e com ponent s t hat appeared on t he server are on t he client as w ell; t hey are j ust invoked in a slight ly different order:

      

    1. The request handlers of the Web service–specific request chain are

    invoked. global.request 2. The chain is invoked.

      3. The transport chain is invoked. Notice that here the entire chain is invoked, not just the request side. There is no need to split the request and response invocations because they would be called one right after the other anyway. Also note that at the pivot point of the transport specific chain is a transport sender ; more on this later.

      4. The global.response chain is invoked.

      5. The response handlers of the Web service–specific response chain are invoked.

      As m ent ioned in St ep 3, t here is som et hing new here: a t ransport sender. A t ransport sender is a handler t hat is responsible for t aking t he request SOAP m essage and sending it t o a SOAP server. For exam ple, one of t he t ransport senders t hat is shipped w it h Axis is an HTTP t ransport sender t hat w ill t ake t he request SOAP m essage, open an HTTP socket connect ion t o t he specified HTTP server, do a POST of t he SOAP m essage, and wait for a response. The response is t hen placed in t he response m essage port ion of t he

      MessageContext obj ect .

      Because t ransport senders are j ust handlers, t hey can be placed in any chain in any configurat ion. So, it is t echnically possible t hat t he t ransport chain shown in Figure 4.7 could have m ult iple t ransport senders if you desire a m ult icast scenario. I t is also possible t hat a t ransport sender could be placed in one of t he chains on t he server such t hat t he response m essage could be sent over a different t ransport t han it was received on ( for exam ple, t he t ransport list ener could be an HTTP servlet , but t he SOAP response m essage could be sent back via SMTP) .

      Locating the Service Chain

      We've t alked about how t here are service- specific chains, but w e haven't yet t ouched on how t he service chain is select ed by t he Axis engine. An int erest ing aspect of SOAP is t hat it doesn't m andat e how t o det erm ine t he exact Web service t o invoke. This m ight seem odd—but it is accurat e. Many different com m on pract ices have been est ablished, and each one is valid. Here are j ust t hree of t he m ore com m on ones:

    • SOAPAction SOAPAction

      — The value of t he HTTP header is used t o m at ch t he service nam e.

    • URL— The URL of the incom ing HTTP request is used to m atch the service nam e.

      For exam ple, if t he URL used t o access Axis w as

      http://localhost:8080/axis/servlet/AxisServlet/MyService

      , t hen t he SOAP

      myService engine w ould look for a service chain called .

    • Nam espace— Perhaps the m ost used m ethod. I t takes the nam espace of the first

      XML elem ent in t he SOAP Body block and t ries t o find a service chain t hat m at ches. Axis could have chosen one m et hod, m ost likely t he nam espace approach, but doing so w ould have lim it ed t he opt ions available t o it s users. I nst ead, Axis let s you choose how global chain t hat can det erm ine w hich service chain t o choose. This handler is free t o use any algorit hm it w ant s t o m ake t his det erm inat ion. How ever, if a service chain has not been select ed by t he t im e t he Axis engine get s t o t he point in it s processing t hat it w ant s t o invoke t he service specific chain, it w ill default t o t he nam espace select ion m et hod.

    XML Parsing

      Axis has been designed and coded w it h a w at chful eye t ow ards perform ance. For t his reason, w hen t ackling t he problem of how t o parse an XML st ream efficient ly, a SAX- based approach was chosen over a DOM- based one. As we discussed in Chapt er 2 , " XML Prim er," SAX XML parsing does not read t he ent ire XML st ream int o m em ory; rat her, it t riggers callbacks based on t he t ypes of XML t okens t hat are encount ered. I t t hen becom es t he responsibilit y of t hose callback rout ines t o do any buffering of dat a or saving of st at e t hat is needed so t hat subsequent callbacks st ill have access t o any previously seen dat a. Even t hough SAX is used for parsing, a DOM- based represent at ion of XML som et im es is used w hen passing around XML blocks—as w ill be seen in t he " Docum ent - Cent ric Services " sect ion. I n various discussions and exam ples in t his chapt er, w e'll need t o t alk about concept s and feat ures in t erm s of using a SAX parser or w rit ing SAX callback rout ines. We assum e t hat you are fam iliar w it h t hese concept s, and w e w ill not explain t he specific det ails of how t o w rit e code ut ilizing a SAX parser in great det ail. Wit h t hat overview of what Axis is and how it works, now we can m ove on t o act ually using it .

      Installing Axis

      I nst alling an Axis server is relat ively sim ple. I n t he servlet engine's direct ory st ruct ure is

      webapps

      a direct ory. This direct ory cont ains t he various Web applicat ions t hat are

      webapps

      deployed. The Axis dist ribut ion includes a direct ory as w ell, and cont ains a

      axis axis webapps

      direct ory nam ed . Copy t he direct ory int o t he servlet engine's

      axis WEB-INF/lib

      direct ory. I n t his new direct ory should be a direct ory. There, you

      axis.jar should place all t he JAR files Axis w ill need t o run. You should already see . xerces.jar

      Current ly, Axis w ill need one only addit ional JAR file: ( available from t he Apache Xerces dist ribut ion at ht t p: / / xm l.apache.org ) or any ot her JAXP- com pliant parser.

      WEB-INF/lib Copy t he parser's JAR file int o t he direct ory. axis/WEB-INF/

      When services are deployed, t he Java class files should be placed in t he

      classes axis/WEB-

      direct ory; or if t here are JAR files, t hey should be placed in t he

      INF/lib

      direct ory. I f you plan t o use t he JWS feat ure of Axis ( see t he " Sim ple Web

      tools.jar

    Services " sect ion) , you w ill also need t o m ake sure t hat t he Java file is eit her

    axis/ WEB-INF/lib in t he direct ory or in your servlet engine's classpat h. axis.jar xerces.jar

      I nst alling t he client is sim ply a m at t er of m aking sure t he and files are in your classpat h.

      Configuring Axis

      There are four different t ypes of configurat ion files. Each w ill cont ain t he sam e t ype of dat a, but t he out erm ost XML elem ent w ill vary:

    • client-config.xml

      — This is t he configurat ion inform at ion for t he Axis engine w hen it is invoked on t he client . This file needs t o be in t he current w orking direct ory of t he client applicat ion. This file has t he form at

      <engi neConf i g>

    • …conf i gurat i on XML…

    • server-config.xml

    • <engi neConf i g>
    • …conf i gurat i on XML…
    • ></engi neConf i g&
    • deploy.xml

      handler_name whose class is given by class_name .The optional name/value pairs are defined by each specific handler and will be available to the handler at runtime.

      Exampl e:

      I n t he first t hree cases, ...configuration XML... sect ion w ill cont ain one of t he follow ing XML elem ent s:

      XML elem ent . Unlike t he first t w o configurat ion files, t he nam e of t his file can be anyt hing. This file has t he form at

      

    undeploy

      w ill rem ove any nam ed resources list ed as im m ediat e child elem ent s of t he

      AdminClient

      t o undeploy resources. The

      AdminClient

      — This is t he file used by t he

      uses a docum ent - cent ric Web service—it t akes t he XML file passed t o it and sends it t o t he Axis server for processing ( m ore lat er) . Unlike t he first t w o configurat ion files, t he nam e of t his file can be anyt hing. This file has t he form at

      is an adm inist rat ive t ool used for deploying and undeploying Axis resources ( such as handlers and chains) . The

      AdminClient

      AdminClient

      t o deploy new handlers, chains, and services. The

      AdminClient

      — This is t he file used by t he

      direct ory in t he HTTP case, or in t he current working direct ory for ot her t ransport s. This file has t he form at

      axis/WEB-INF

      — This is t he configurat ion inform at ion for t he Axis engine w hen it is invoked on t he server. This file needs t o be in t he servlet engine's

    • <m:depl oy xmlns: m="AdminServi ce">
    • …conf i gurat i on XML…
    • ></m:depl oy&
    • undeploy.xml

    • <m:undepl oy xmlns: m="AdminServi ce">
    • …resources t o be removed…
    • </m:undepl oy>
    • handl er
    • <handl er name="handl er_name" cl ass="cl ass_name">
    • [ <opt i on name="opt i on_name" val ue="opt i on_val ue"/>] …
    • </handl er>

    • <! - - Def i ne an EMai l handl er - - >
    • >

      <handl er name="EMai l " cl ass="com.skat est own. servi ces. EMai l Handl er" />

      • Defines a single handler named
      • chai n
      • <chai n name="chai n_name" { f l ow="l i st _of _handl ers" |
      • request ="l i st _of _handl ers" pi vot ="handl er_name"
      • response="l i st _of _handl ers"} >
      • [ <opt i on name="opt i on_name" val ue="opt i on_val ue"/>] …
      • </chai n>

        Exampl e:

      • and t he Emai l handl er f rom chapt er 3 - - >
      • <chai n name="myChai n" f l ow="RPCDi spat cher, Emai l " />
      • Defines a chain called chain_name that consists of either the list of handlers specified in the

        flow attribute or the handlers specified by the request pivot and response attributes combined. The optional name/value pairs will be available to the chain at runtime. There are two reserved chain names: global.request and global.response

        . These names should be used when defining the global chains.

      • servi ce
      • <servi ce name="servi ce_name" [ request ="l i st _of _handl ers"]
      • [ pi vot ="handl er_name"]
      • [ response="l i st _of _handl ers"] >
      • [ <opt i on name="opt i on_name" val ue="opt i on_val ue"/>] …
      • ></servi ce&
      • Example:
      • <! - - Def i ne a servi ce chai n wi t h t he "RPCDi spat cher" at t he pi vot - poi nt
      • and Emai l handl er t o mai l t he response. The cl ass and met hod name
      • t hat t he RPCDi spat cher wi l l use are passed i n as opt i ons - - >
      • <servi ce name="I nvent oryCheck" pi vot ="RPCDi spat cher" response="Emai l ">
      • <opt i on name="cl assName"
      • val ue="com.skat est own. servi ces. I nvent oryCheck"/>
      • <opt i on name="met hodName" val ue="doCheck"/>
      • </servi ce>

        Defines a service chain consisting of the list of handlers specified in the request , pivot , and response attributes combined. The optional name/value pairs will be available to the service at runtime. The name specified here should match the namespace URI of the first body entry of the incoming SOAP request message.

      • t ransport
      • <t ransport name="t ransport _name" [ request ="l i st _of _handl ers"]
      • [ pi vot ="handl er_name"]
      • [ response="l i st _of _handl ers"] >
      • [ <opt i on name="opt i on_name" val ue="opt i on_val ue"/>] …
      • ></t ransport &
      • Example:
      • <! - - Def i ne a t ransport speci f i c chai n t hat wi l l i nvoke a "uudecode"
      • handl er on t he request message and t he "uuencode" handl er on t he
      • response message – t hese wi l l onl y be i nvoked f or t hose messages
      • t hat come i n usi ng t he "f i l e" t ransport - - >
      • <t ransport name="f i l e" request ="uudecode" response="uuencode"/>

        Defines a transport chain consisting of the list of handlers specified in the request , pivot , and response attributes combined. The optional name/value pairs will be available to the transport chain at runtime. The name specified on this definition must match the name of the transport specified by the transport listener on the setTransportName() method.

      • beanMappi ngs
      • <beanMappi ngs>
      • <x: name xmlns: x="namespace_uri " cl assname="cl ass_name" />
      • ></beanMappi ngs&
      • Example:
      • <beanMappi ngs>
      • <x: po xmlns: x="ht t p: //www. skat est own. com/ns/po"
      • cl assname="www. skat est own. com.dat a. PO" />
      • </beanMappi ngs>

      • t ypeMappi ngs
      • <t ypeMappi ngs>
      • <x: name xmlns: x="namespace_uri " t ype="soap_t ype" seri al i zer="cl ass_name"
      • deseri al i zerFact ory="cl ass_name" />
      • </t ypeMappi ngs>
      • <t ypeMappi ngs>
      • <x: PO xmlns: x="ht t p: //www. skat est own. com/ns/po" t ype="po"
      • seri al i zer="seri al i zePO"
      • deseri al i zerFact ory="deseri al i zePOFact ory" />
      • ></t ypeMappi ngs&
      • Defines a mapping between the type found in the SOAP message

        file .

        , and a t ransport chain nam ed

        DoCheck

        , a service chain nam ed

        logger

        I n t his exam ple, t hree resources w ill be undeployed: a handler nam ed

        <m:undepl oy xmlns: m="AdminServi ce"> <handl er name="l ogger" /> <servi ce name="DoCheck" /> <t ransport name="f i l e" /> </m:undepl oy>

        , has a slight ly different form at . I n t his file, you j ust list t he t ypes of resources t o be undeployed and t heir nam es. For exam ple:

        undeploy.xml

        The fourt h configurat ion file,

        ) in the specified snamespace namespace_uri with the specified serializer and deserializer. We'll give more details about

      serializers and deserializers in the " Data Encoding/Decoding "

      section.

        ( soap_type

        Exampl e:

        ) to be used for the bean named name in the namespace namespace_uri . This is

      a convenient way of using the default Java bean serializer and

      deserializer for your Java beans. We'll give more details about

      serializers and deserializers in the " Data Encoding/Decoding "

      section.

        Defines the bean serializer/deserializer class ( class_name

        Configuration Methods server-config.xml

        You can configure t he Axis server t w o w ays: You can m odify t he file direct ly by adding or rem oving t he XML configurat ion dat a, or you can use t he Adm inClient t ool. This t ool let s you rem ot ely m odify t he server's configurat ion. By default , Axis w ill only allow t he Adm inClient t o be run from t he sam e m achine as t he server ( for securit y reasons) , but t his is easily changed ( see t he " Securit y " sect ion) . To run t he Adm inClient , you m ust first creat e an XML file w it h t he list of changes t o be m ade. I nside t his XML file should be j ust t he list of resources ( handlers, chains, services, and so on) t hat should be deployed or undeployed. As previously show n, t he XML's root

        deploy

        elem ent should be nam ed in t he case w here new resources are being added and

        undeploy

        w hen t hey are being rem oved. Once all t he deploym ent inform at ion is placed in an XML file, you can invoke Adm inClient :

        > j ava org. apache. axi s. cl i ent . AdminCl i ent

      • l ht t p: //l ocal host : 8080/axi s/servl et /Axi sServl et depl oy. xml

        Not e t hat t his assum es an HTTP t ransport and t hat t he Axis servlet is available and w ait ing for request s on t he specified URL ( ht t p: / / localhost : 8080/ axis/ servlet / AxisServlet ) . This invocat ion w ill w ork for deploying new resources t o an Axis engine running as a server. To add new resources t o an Axis

        client-config.xml

        client engine, you'll need t o m odify t he file used by t he client Axis engine. This file w ill reside in t he current w orking direct ory. Follow ing is one of t he sam ple XML files from Chapt er 3 t hat is used as input t o t he Adm inClient :

        <m:depl oy xmlns: m="AdminServi ce"> <handl er name="URLMapper" cl ass="org. apache. axi s. handl ers. ht t p. URLMapper"/> <handl er name="Act i onHandl er" cl ass="org. apache. axi s. handl ers. ht t p. HTTPAct i onHandl er"/> <t ransport name="ht t p" request ="URLMapper"/> <! - - Chapt er 3 exampl e 3 servi ces - - > <handl er name="EMai l " cl ass="com.skat est own. servi ces. EMai l Handl er"/> <servi ce name="I nvent oryCheck" pi vot ="RPCDi spat cher" response="EMai l "> <opt i on name="cl assName" val ue="com.skat est own. servi ces. I nvent oryCheck"/> <opt i on name="met hodName" val ue="doCheck"/> </servi ce> <! - - Chapt er 3 exampl e 4 servi ces - - > <servi ce name="POSubmissi on" pi vot ="MsgDi spat cher"> <opt i on name="cl assName" val ue="com.skat est own. servi ces. POSubmissi on"/> <opt i on name="met hodName" val ue="doSubmissi on"/> </servi ce> </m:depl oy>

        Alt hough it is possible t o run t he Adm inClient t ool t o change t he configurat ion

        client-

        inform at ion of t he Axis client engine, it is easier t o sim ply m odify t he

        config.xml file t hat resides in t he current w orking direct ory.

        Once a Web resource is deployed, eit her t o t he client or t he server, it w ill be available unt il it is undeployed—even across servlet engine rest art s. At t he t im e of publicat ion, Axis' deploym ent XML files use a very sim ple XML definit ion form at . Alt hough t his form at w orks for now , it doesn't quit e support t he full feat ures t hat Axis is planning t o have. Event ually, Axis w ill sw it ch t o a new XML form at called Web developm ent , it should be m ore robust t han t he current XML deploym ent file. One ot her advant age is t hat WSDD w ill have a WSDL flavor t hat should allow for Web services t hat are defined in WSDL t o be deployed by having t he WSDD point t o t heir WSDL file. But all of t his is st ill being designed.

        By default , Axis w ill have several handlers, chains, and services aut om at ically deployed.

        server-config.xml appRoot/WEB-INF

        I f a file is not found in t he direct ory by t he Axis server, Axis w ill default t o have t he follow ing pre- deployed:

      • JWSProcessor service— Looks for and processes JWS files ( JWS was briefly discussed in Chapt er 3 , and w ill be discussed in m ore det ail lat er in t his chapt er) .
      • RPCProvider handler— Locates and invokes a Java class m ethod.
      • Adm inService service— Takes as input an XML docum ent that will be interpreted as a deploym ent dat a XML file cont aining t he list of new handlers, chains, and services t o deploy ( or undeploy) .
      • HTTPSender handler— I s used by an Axis client to send a SOAP request to a SOAP server. I t can also be used on t he server side when a m essage should be sent t o anot her SOAP server using HTTP ( for exam ple, an int erm ediary) .

        client-config.xml

        I f a file is not found, t hen Axis w ill default t o having j ust one handler

        HTTPSender pre- deployed: t he , for use in sending a SOAP request over HTTP.

        Security

        Current ly, Axis includes only one m inor securit y feat ure. By default , t he Adm inService w ill only allow deploym ent of new resources from t he sam e m achine running t he Axis

        enableRemoteAdmin

        server. By using t he opt ion on t he Adm inService, resources can be

        server-config.xml

        deployed from any ot her m achine as w ell. The file should be changed as follow s:

        <servi ce name="AdminServi ce" pi vot ="RPCDi spat cher"> <opt i on name="cl assName" val ue="org. apache. axi s. ut i l . Admin"/> <opt i on name="met hodName" val ue="AdminServi ce"/> <opt i on name="enabl eRemot eAdmin" val ue="t rue"/> </servi ce>

        Not e, how ever, t hat securit y can be added t o Axis t hrough t he developm ent of handlers t hat perform t he desired securit y checks. This addit ion is being planned for developm ent in t im e for Axis' first release.

        Simple Web Services

        By far t he easiest and quickest w ay t o deploy a Java Web service is t hrough Axis' Java Web Service ( JWS) facilit y. JWS let s you place a Java file in your Web applicat ion direct ory st ruct ure, and Axis w ill aut om at ically find it , com pile it , and deploy t he m et hods aut om at ically. Using t he exam ple from Chapt er 3 , w e have t he JWS ( or Java) file show n in List ing 4.2 .

        Listing 4.2

        InventoryCheck.jws i mport org. apache. axi s. MessageCont ext ; i mport bws. BookUt i l ; i mport com.skat est own. dat a. Product ; i mport com.skat est own. backend. Product DB;

        /**

      • I nvent ory check Web servi ce
      • / publ i c cl ass I nvent oryCheck { /**
      • Checks i nvent ory avai l abi l i t y gi ven a product SKU and * a desi red product quant i t y.
      • @param msgCont ext Thi s i s t he Axi s message processi ng cont ext
      • BookUt i l needs t hi s t o ext ract depl oyment * i nf ormat i on t o l oad t he product dat abase.
      • @param sku product SKU
      • @param quant i t y quant i t y desi red
      • @ret urn t rue|f al se based on product avai l abi l i t y
      • @except i on Except i on most l i kel y a probl em accessi ng t he DB
      • / publ i c st at i c bool ean doCheck( MessageCont ext msgCont ext , St ri ng sku, i nt quant i t y) t hrows Except i on { Product DB db = BookUt i l . get Product DB( msgCont ext ) ; Product prod = db. get BySKU( sku) ; ret urn ( prod ! = nul l && prod. get NumInSt ock( ) >= quant i t y) ; }

        } .jws

        All you need t o do is place t his file in t he Axis w ebapps direct ory st ruct ure w it h a

        .java

        ext ension inst ead of . So, t o access t his exam ple on t he CD, because it is in t he

        ch3/ex2

        direct ory, t he URL for t his Web service w ould be ht t p: / / localhost : 8080/ bw s/ ch3/ ex2/ I nvent oryCheck.j w s . I t 's as easy as t hat . One im port ant t hing t o rem em ber is t hat all public m et hods w ill be available as Web services. So, use JWS files w it h care.

        Client-Side Programming

        Accessing a Web service from t he client can be ( alm ost ) as easy. I n t he sim plest case of w ant ing t o access an RPC SOAP service, let 's t ake a closer look at t he exam ple from

        Chapt er 3 , shown in List ing 4.3 .

        Listing 4.3

        InventoryCheckClient.java package ch3. ex2; i mport org. apache. axi s. cl i ent . Servi ceCl i ent ; /*

      • I nvent ory check web servi ce cl i ent
      • / publ i c cl ass I nvent oryCheckCl i ent { /**

      • / St ri ng url ; /**
      • Poi nt a cl i ent at a gi ven servi ce URL
      • / publ i c I nvent oryCheckCl i ent ( St ri ng url ) { t hi s. url = url ; } /**
      • I nvoke t he i nvent ory check web servi ce
      • / publ i c bool ean doCheck( St ri ng sku, i nt quant i t y) t hrows Except i on { Servi ceCl i ent cal l = new Servi ceCl i ent ( url ) ; Obj ect [ ] params = new Obj ect [ ] { sku, new I nt eger( quant i t y) , } ; Bool ean resul t = ( Bool ean) cal l . i nvoke( "", "doCheck", params) ; ret urn resul t . bool eanVal ue( ) ; } }

        ServiceClient

        As show n here, a obj ect is needed. This obj ect is used as t he port al t hrough w hich t he client applicat ion connect s w it h t he Web service. The const ruct or t akes

        ServiceClient

        t he URL of t he t arget SOAP server. Once t he obj ect knows where t o find t he service, all t hat is left is t o invoke t he Web service it self. Not ice t hat t he

        client.invoke()

        m et hod call t akes t hree param et ers: t he value of t he HTTP

        SOAPAction

        header, w hich in t his call is j ust an em pt y st ring; t he nam e of t he Web

        doCheck

        service's m et hod t o invoke ( ) ; and an array cont aining t he Java obj ect s

        invoke()

        represent ing t he param et ers for t he m et hod. The ret urn value of t he m et hod is

        Object

        a Java obj ect of t ype , so it w ill need t o be cast t o t he proper ret urn t ype before it is used. Som et im es each param et er passed t o t he m et hod needs t o have a specific nam e associat ed w it h it . For exam ple, som e SOAP servers w ill use t he param et er nam es in t he

        invoke()

        m et hod- m at ching algorit hm . I n t hese cases, a slight change t o t he w ay is called is required:

        Bool ean resul t = ( Bool ean) cal l . i nvoke( "", "doCheck", new Obj ect [ ] { new RPCParam("skuName", sku) , new RPCParam("quant i t y", new I nt eger( quant i t y) ) } ) ;

        RPCParam

        Not ice t hat now inst ead of passing in an array of Java obj ect s, an array of s is

        RPCParam skuName

        passed in, w here each consist s of t he nam e of t he param et er ( and

        quantity sku quantity in t his exam ple) and t he value of t he param et er ( and ) .

        When t alking w it h an Axis server or any ot her SOAP server t hat does explicit t yping of t he XML st ream ( t his m eans t he dat at ype of t he param et ers and ret urn value of t he RPC call is placed in t he SOAP m essage) , t he Axis client can use t hat t yping inform at ion t o know how t o deserialize t he ret urn value. How ever, som e SOAP servers do not do t his; in t his inst ance, t hey are expect ing t he client t o know t he dat at ype t hrough som e ot her m eans ( perhaps WSDL) . When t his occurs, it becom es t he responsibilit y of t he client applicat ion t o t ell t he Axis client w hat t ype t he ret urn value is—w hich j ust requires a couple lines of code. The com plet e client applicat ion looks like List ing 4.4 Listing 4.4

        InventoryCheckClient.java package ch3. ex2; i mport org. apache. axi s. cl i ent . Servi ceCl i ent ; /*

      • I nvent ory check web servi ce cl i ent
      • / publ i c cl ass I nvent oryCheckCl i ent { /**
      • Servi ce URL
      • / pri vat e St ri ng url ; /**
      • Poi nt a cl i ent at a gi ven servi ce URL
      • / publ i c I nvent oryCheckCl i ent ( St ri ng t arget Url ) { url = t arget Url ; } /**
      • I nvoke t he i nvent ory check web servi ce
      • / publ i c bool ean doCheck( St ri ng sku, i nt quant i t y) t hrows Except i on { Servi ceCl i ent cal l = new Servi ceCl i ent ( url ) ; Servi ceDecri pt i on sd = new Servi ceDescri pt i on( "ret urn", t rue) ; sd. set Out put Type( new QName( Const ant s. URI _2001_SCHEMA_XSD, "bool ean") ) ; cal l . set Servi ceDescri pt i on( sd) ; Bool ean resul t = ( Bool ean) cal l . i nvoke( "",

        "doCheck", new Obj ect [ ] { sku, new I nt eger( quant i t y) } ) ; ret urn resul t . bool eanVal ue( ) ; } }

        ServiceDescription

        I n t his exam ple w e've added t he definit ion of a obj ect . This obj ect is used by t he client t o not ify t he Axis client of various pieces of m et adat a about

        OutputType

        t he Web service being invoked. I n t his inst ance w e're defining t he ( ret urn

        boolean

        t ype) of t he m et hod as a using t he 2001 W3C XML Schem a definit ion. The

        ServiceDescription

        const ruct or t akes t w o param et ers: a nam e assigned t o t his obj ect ( ret urn param et er nam es aren't used very m uch as t hey are basically ignored) and an indicat ion of w het her t his service is an RPC service ( t rue indicat es t hat it is) . The only

        ServiceDescription ServiceClient

        ot her code change associat es t his obj ect w it h t he ,

        setServiceDescription() and t his is done t hrough t he m et hod call.

        Advanced Web Service Deployment

        Alt hough JWS files are convenient , som et im es you'll need m ore com plex Web service configurat ions. For exam ple, som e pre- or post - processing m ight be needed for a part icular Web service, or perhaps t he Web service isn't a Java program and a special dispat cher is needed ( m ore on t hese lat er) . I n t hese cases, you can't use JWS files, and

        server-

        you need a m ore robust deploym ent m echanism . This is w hen you'll use t he

        config.xml AdminClient file and t he ( m ent ioned previously) .

        InventoryCheck

        For exam ple, let 's say w e w ant t o deploy t he sam e service in t he JWS scenario, but t his t im e we also want t o have a handler em ail a copy of each response

        AdminClient

        m essage. To do t his, w e m ust first creat e a deploym ent XML file for t he :

        <m:depl oy xmlns: m="AdminServi ce"> <handl er name="emai l " cl ass="com.skat est own. servi ces. EMai l Handl er" /> <servi ce name="I nvet oryCheck" pi vot ="RPCDi spat cher" response="emai l "> <opt i on name="cl assName" val ue="com.skat est own. servi ces. I nvent oryCheck" /> <opt i on name="met hodName" val ue="doCheck" /> </servi ce> </m:depl oy> email

        Not ice t hat w e added a handler called , whose class nam e is

        com.skatestown.services. EMailHandler

        . I n addit ion, a new service chain is defined

        RPCDispatcher RPCDispatcher

        t hat invokes t he and t his new em ail handler. The is t he handler t hat w ill locat e and invoke t he Java m et hod for t he Web service. Not ice t hat in

        className methodName t he definit ion of t he service, w e provide som e opt ions— and .

      RPCDispatchhandler

        These opt ions w ill be used in t he —it w ill creat e a new inst ance of

        com.skatestown.service.InventoryCheck doCheck

        class and t hen invoke t he m et hod ( of course passing in t he param et ers from t he SOAP request m essage) . To deploy t hese

        AdminClient

        new resources, t he is used:

        > j ava org. apache. axi s. cl i ent . AdminCl i ent depl oy. xml InventoryCheck.class axis/WEB-INF/

        Once deployed, w e need t o copy t he file int o t he

        classes direct ory. We should t hen be set t o run t he client .

        Document-Centric Services

        Up t o t his point , our focus has been on t he sim ple RPC case w here t he Web service being invoked is a Java m et hod. This is j ust one w ay t o use SOAP and Axis. As discussed in previous chapt ers, t here is also docum ent - cent ric SOAP processing. I n t his scenario, rat her t han t he SOAP processor convert ing t he XML int o Java obj ect s and t hen calling a m et hod, t he XML is left unt ouched and is sim ply handed t o a m et hod for processing. This m et hod is t hen free t o do w hat ever it w ant s w it h t he XML. Support ing t his approach in Axis is a sim ple m at t er of changing t he dispat cher t hat is used. I n t he RPC case, an

        RPCDispatcher MsgDispatcher

        handler w as used; now a handler m ust be used. This handler w ill locat e t he appropriat e m et hod ( as specified by t he deploym ent inform at ion) and t hen call it , passing in t he request XML SOAP m essage as a param et er. The deploym ent of a docum ent - cent ric service w ill look like t his:

        <servi ce name="POSubmissi on" pi vot ="MsgDi spat cher"> <opt i on name="cl assName" val ue="POSubmissi on"/> <opt i on name="met hodName" val ue="doSubmissi on"/> </servi ce>

        POSubmission This code shows t he deploym ent inform at ion for a service chain called . className

        and t he act ual m et hod t hat should be locat ed and invoked. Unlike t he RPC case, w here t he param et ers t o t he m et hod can be det erm ined by t he needs of t he

        MsgDipatcher

        service, assum es t hat all docum ent - cent ric m et hods have t he sam e m et hod signat ure, as follows:

        publ i c Document doSubmissi on( MessageCont ext msgCont ext , Document xml) t hrows Axi sFaul t ; MessageContext Document

        Not ice t hat t he service t akes t w o param et ers, a and a ( m ore

        MessageContext

        on lat er in t he " Building Handlers " sect ion; for now, j ust know t hat it is Axis- specific dat a t hat is m ade available t o t he service if it needs it ) . The service also

        Document ret urns a obj ect , w hich is used as t he body of t he response SOAP m essage.

        Not ice t hat t he input and out put m essages are W3C Docum ent obj ect s, and not SAX event s—t his is done as a m at t er of convenience for t he handler w rit er. How ever, by t he t im e Axis is released, t he handler m ight have t he opt ion of processing t he SAX event s

        AxisFault

        direct ly. I f an error occurs during processing, t he service should t hrow an ( see t he " Fault s " sect ion) . List ing 4.5 shows a sam ple service ( from Chapt er 3 ) . Listing 4.5

        POSubmission.java package com.skat est own. servi ces; i mport org. w3c. dom.Document ; i mport org. apache. axi s. MessageCont ext ; i mport j avax. xml. parsers. Document Bui l der; i mport j avax. xml. parsers. Document Bui l derFact ory; i mport com.skat est own. dat a. PO; i mport com.skat est own. dat a. I nvoi ce; i mport com.skat est own. backend. Product DB; i mport com.skat est own. backend. POProcessor; i mport com.skat est own. xml. Seri al i zer; i mport com.skat est own. xml. Deseri al i zer; i mport bws. BookUt i l ; /**

      • Purchase order submissi on servi ce
      • / publ i c cl ass POSubmissi on { /**
      • Submit a purchase order and generat e an i nvoi ce
      • / publ i c Document doSubmissi on( MessageCont ext msgCont ext , Document i nDoc) t hrows Except i on { // Creat e a PO f rom t he XML document Document Bui l derFact ory f act ory = Document Bui l derFact ory. newI nst ance( ) ; Document Bui l der bui l der = f act ory. newDocument Bui l der( ) ; PO po = Deseri al i zer. creat ePO( i nDoc. get Document El ement ( ) ) ;

        // Get t he product dat abase Product DB db = BookUt i l . get Product DB( msgCont ext ) ; // Creat e an i nvoi ce f rom t he PO POProcessor processor = new POProcessor( db) ;

        // Seri al i ze t he i nvoi ce t o XML Document newDoc = Seri al i zer. wri t eI nvoi ce( bui l der, i nvoi ce) ; ret urn newDoc; } }

        AdminClient

        To deploy it , w e use t he :

        j ava org. apache. axi s. cl i ent . AdminCl i ent po_depl oy. xml po_deploy.xml

        The file looks like t his:

        <m:depl oy xmlns: m="AdminServi ce"> <servi ce name="ht t p: //www. skat est own. com/ns/po" pi vot ="MsgDi spat cher"> <opt i on name="cl assName" val ue="com.skat est own. servi ces. POSubmissi on"/> <opt i on name="met hodName" val ue="doSubmissi on"/> </servi ce> </m:depl oy>

        Alt hough invoking an RPC Web service is relat ive easy, invoking a docum ent - cent ric Web service requires a lit t le m ore w ork, but not m uch. A corresponding client w ould look like

        List ing 4.6 .

        Listing 4.6 POSubmissionClient.java

        package ch3. ex4; i mport j ava. i o. I nput St ream; i mport j ava. i o. St ri ngWri t er; i mport org. apache. axi s. encodi ng. Seri al i zat i onCont ext ; i mport org. apache. axi s. message. SOAPEnvel ope; i mport org. apache. axi s. message. SOAPBodyEl ement ; i mport org. apache. axi s. cl i ent . Servi ceCl i ent ; i mport org. apache. axi s. Message; i mport org. apache. axi s. MessageCont ext ; /**

      • Purchase order submissi on cl i ent
      • / publ i c cl ass POSubmissi onCl i ent { /**
      • Target servi ce URL
      • / St ri ng url ; /**
      • Creat e a cl i ent wi t h a t arget URL
      • / publ i c POSubmissi onCl i ent ( St ri ng url ) { t hi s. url = url ; }

        /**

      • I nvoke t he PO submissi on web servi ce
      • @param po Purchase order document
      • @ret urn I nvoi ce document
      • @except i on Except i on I /O error or Axi s error
      • / publ i c St ri ng i nvoke( I nput St ream po) t hrows Except i on { // Send t he message Servi ceCl i ent cl i ent = new Servi ceCl i ent ( url ) ; cl i ent . set Request Message( new Message( po, t rue) ) ; cl i ent . get MessageCont ext ( ) . set Target Servi ce( "ht t p: //www. skat est own. com/ns/po") ; cl i ent . i nvoke( ) ; // Ret ri eve t he response body MessageCont ext ct x = cl i ent . get MessageCont ext ( ) ;

        Message out Msg = ct x. get ResponseMessage( ) ; SOAPEnvel ope envel ope = out Msg. get AsSOAPEnvel ope( ) ; SOAPBodyEl ement body = envel ope. get Fi rst Body( ) ; // Get t he XML f rom t he body St ri ngWri t er w = new St ri ngWri t er( ) ; Seri al i zat i onCont ext sc = new Seri al i zat i onCont ext ( w, ct x) ; body. out put ( sc) ; ret urn w. t oSt ri ng( ) ; } }

        ServiceClient

        The exam ple st art s by creat ing a obj ect and gives it t he locat ion of t he

        Message

        SOAP server. Next , it creat es an Axis obj ect . This obj ect w ill cont ain t he act ual

        XML of t he SOAP m essage. As input t o t he const ruct or, it t akes an input st ream ( t he XML

        boolean

        for t he body of t he SOAP envelope) and a indicat ing w het her t his XML input

        true

        st ream is t he ent ire SOAP envelope or j ust t he body— indicat es t hat it is j ust t he

        ServiceClient

        body. The obj ect is t hen t old of t he request m essage t hrough t he

        setRequestMessage()

        m et hod call, and t hen t he Web service it self is invoked. Once t he service is invoked, t he response m essage is obt ained. This allow s for t he client t o access any part of t he response and not j ust t he body. How ever, in t his case, w e ask for t he first

        String body elem ent t o convert it t o a and ret urn it .

      Data Encoding/Decoding

        Sw it ching back t o RPC, so far w e've deferred t he ent ire not ion of how t he dat a is convert ed bet w een Java obj ect s and t he XML. This sect ion w ill go int o t he st eps involved in creat ing cust om ized serializers and deserializers t hat can be used in Axis. Alt hough t he concept of w hat serializers and deserializers do is not t erribly com plex, w rit ing one for Axis requires a good w orking know ledge of how t o use a SAX parser. Chapt er 2 had a good, but brief, discussion of how SAX parsers w ork and how t o use t hem —t his sect ion w ill assum e t hat you are w ell versed enough w it h SAX t hat usage of SAX t erm s, w it hout t he det ails behind t hem , w ill be appropriat e.

        As we discussed in Chapt er 2 , t he concept s of serializers and deserializers are really quit e sim ple—t hey are j ust pieces of code t hat w ill convert dat a ( in it s nat ive st at e, such as a Java obj ect ) int o XML in t he serializing case, and from XML back int o t he dat a's nat ive st at e in t he deserializing case. I f your classes are Java beans, t hen you can use t he Bean serializer and deserializer t hat com es w it h Axis. To do t his, all you have t o do is t ell Axis t o use t he Bean serializer/ deserializer w hen it encount ers your class. For exam ple, on t he client side t he code m ight look like t he follow ing:

        // regi st er t he PurchaseOrder cl ass St ri ng URL = "ht t p: //l ocal host : 8080/axi s/servl et /Axi sServl et "; Servi ceCl i ent cl i ent = new Servi ceCl i ent ( URL) ; QName qn = new QName( "ht t p: //www. skat est own. com/ns/po", "po") ; Cl ass cl s = com.skat est own. dat a. PO. cl ass; cl i ent . addSeri al i zer( cl s, qn, new BeanSeri al i zer( cl s) ) ; cl i ent . addDeseri al i zerFact ory( qn, cl s, BeanSeri al i zer. get Fact ory( ) ) ; addSerializer()

        I n t his code, t he m et hod w ill creat e a serializer associat ion bet w een

        PO http://www.skatestown.com/ns/po

        t he class and it s nam espace, , and t he

        BeanSerializer . Then w e do t he sam e t hing for t he deserializing side. beanMapping

        While on t he server, a w ould need t o be deployed ( for exam ple, in t he XML

        AdminClient

        file passed t o t he ) :

        <beanMappi ngs xmlns: bi d=" ht t p: //www. skat est own. com/ns/po"> <bi d: po cl assname="com.skat est own. dat a. PO"/> </beanMappi ngs>

        BeanSerializer

        How ever, som et im es t he isn't enough, and you'll need an even m ore cust om ized serializer/ deserializer and specialized code t hat m anually exam ines or creat es t he XML. I n t his case, it is j ust a m at t er of writ ing a few Java classes.

        Serializer

        You need a serializing class t hat should im plem ent t he int erface. This int erface has j ust one m et hod:

        publ i c i nt erf ace Seri al i zer ext ends j ava. i o. Seri al i zabl e { publ i c voi d seri al i ze( QName name, At t ri but es at t ri but es, Obj ect val ue, Seri al i zat i onCont ext cont ext ) t hrows I OExcept i on; } name

        This m et hod should, const ruct a block of XML w it h a root elem ent w it h t he given

        attributes value

        and , and t he body should be t he serialized version of . This m et hod

        SerializationContext

        assum es t hat SAX event s w ill be generat ed against t he passed t o

        SerializationContext

        it . The obj ect is a ut ilit y class t hat provides funct ions necessary for w rit ing XML t o a Writ er, including m aint aining nam espace m appings, serializat ion of dat a obj ect s, and aut om at ic handling of m ult i- ref encoding of obj ect graphs.

        DeserializationFactory

        Next , you need a class t hat im plem ent s t he int erface. This int erface has j ust one m et hod, as w ell:

        publ i c i nt erf ace Deseri al i zerFact ory ext ends j ava. i o. Seri al i zabl e { publ i c Deseri al i zer get Deseri al i zer( Cl ass cl s) ; }

        Deserializer

        This m et hod should ret urn an inst ance of t he class. Whet her it ret urns t he sam e inst ance or a new inst ance each t im e is an im plem ent at ion choice—you use a fact ory because t he deserializers are processing SAX event s, so t hey w ill need t o m aint ain som e st at e inform at ion bet w een each SAX event callback. I f a single deserializer exist ed and m ult iple t hreads w ere deserializing obj ect s at t he sam e t im e, t hey w ould override each ot her's w ork.

        deserializer deserializer

        The final class you need t o w rit e is t he class ( t he class t he

        Deserializer

        fact ory ret urns) . This class should ext end t he class. I nside t his class should be any of t he SAX callback m et hods needed t o deserialize t he incom ing SAX event st ream . The exact im plem ent at ion of t hese m et hods is left com plet ely up t o you. The only requirem ent is t hat w hen it is done, t he m et hods set a field in t he base

        Deserializer value

        class called t o t he Java obj ect represent ed by t he XML. As a quick exam ple, Axis com es w it h a Base64 serializer and deserializer. The deserializer is very

        characters()

        sm all, and sim ply im plem ent s t he SAX m et hod:

        st at i c cl ass Base64Deser ext ends Deseri al i zer { publ i c voi d charact ers( char[ ] chars, i nt st art , i nt end) t hrows SAXExcept i on { set Val ue( Base64. decode( chars, st art , end) ) ; } }

        Base64.decode The , m et hod does t he act ual decoding and j ust ret urns a Java obj ect .

        Building Handlers

        Handlers are t he key building blocks of Axis. As previously described, configuring Axis sim ply requires defining t he t ypes of handlers deployed and t he order in w hich handlers are placed in t he chains. A handler is not hing m ore t han a piece of code t hat exam ines som e ( or all) of a SOAP m essage and t hen act s on it . Axis m akes no assum pt ions about w hat each handler does; each one is free t o do as lit t le or as m uch w ork as needed. The specific det ails of how t o w rit e a handler are out side t he scope of t his book; how ever, w e'll give a brief overview here. I f you w ant t o w rit e a handler, you should consult t he Axis docum ent at ion.

        MessageContext

        As each handler is invoked, it is passed a obj ect t hat cont ains all t he inform at ion about t he current st at e of t he processing of t he SOAP m essage. I n part icular,

        

      MessageContext

        som e of t he key pieces of dat a in t he are as follows:

      • requestMessage

        — The SOAP m essage t hat is t he incom ing or request ing m essage. Typically t his is t he m essage t hat handlers before t he pivot point use as input .

      • responseMessage — The SOAP m essage t hat is t he out going or response m essage.

        Typically t his is t he m essage int o w hich handlers aft er t he pivot point w ill place t heir response m essage ( if any) .

      • targetService

        — The nam e of t he service- specific chain t hat w ill be invoked by t he Axis engine. I f a handler's j ob is t o det erm ine w hich Web service is being

        setTargetService()

        called, it needs t o set t his field by calling t he m et hod, passing it t he nam e of t he service- specific chain.

      • bag

        — A Hasht able t hat can be used t o st ore any m et adat a about t he processing of t he current m essage. Handlers can use t his Hasht able t o share inform at ion. For exam ple, one handler can place in it inform at ion t hat anot her handler, lat er in t he chain, can t hen ret rieve and use in it s own processing. This process requires som e out - of- band know ledge bet w een handlers so t hey know w hat key t o use t o st ore and ret rieve t he dat a.

        The logic inside a handler is relat ively st raight forw ard. Each handler, w het her it is on t he request chain, on t he response chain, or t he pivot point handler, can access any of t he placed on t he request or t he response side of a chain—in t his case, request ing t he request or response m essage explicit ly could result in t he w rong m essage being

        getCurrentMessage() MessageContext

        ret urned. For t his reason, a m et hod on t he obj ect w ill ret urn eit her t he request or response m essage, depending on w het her t he handler appears before or aft er t he pivot point . Once a m essage has been obt ained, t he handler is free t o exam ine or process any part of t he m essage. The handler can ask for t he ent ire m essage, t he body of t he m essage, or any specific header. Because t he SOAP specificat ion has very specific rules for t he

        mustUnderstand

        processing of headers, it is im port ant t han any handler t hat does

        processed setProcessed(true)

        process a header set t he flag on t hat header by calling

        SOAPHeader

        on t hat obj ect . Axis w ill use t his inform at ion t o det erm ine w het her t o t hrow

        mustUnderstand mustUnderstand a fault if all t he headers have not been processed.

      Specialized Pivot Point Handlers, a.k.a. Providers

        New t echnology like Web services can be viewed as sim ply a new m eans of accessing exist ing I T asset s. When you're looking at t he w ide variet y of w ays in w hich dat a can be accessed ( servlet s, Web services, Java RMI , and so on) , you can see t hat each of t hem uses a different m echanism for t ransferring t he dat a from one source t o anot her; how ever, t he business logic t hat is execut ed should not change based on t he m eans of dat a t ransport . I n keeping w it h t his separat ion of roles, Axis' handlers w ill t ypically be w rit t en in such a w ay t hat t hey are sim ply t he bridge bet w een Axis and your exist ing business logic. Of course, it is possible t o writ e handlers such t hat all of t he code is cont ained w it hin t he handler it self, but w hen t he next big t hing com es along, chances are it w ould require m ore w ork t han if a clean delineat ion had been kept bet w een t he m eans of t ransport ing t he dat a and t he business logic. This concept is very sim ilar t o how m any people w rit e t heir servlet s or JSPs; t he HTML present at ion logic is in t he JSP, w hereas t he real work is done t hrough accessing beans or som e ext ernal Java code. I n keeping w it h t his separat ion, t he pivot point handlers should be w rit t en such t hat t heir j ob is t o int erpret t he incom ing SOAP m essage, locat e t he business resources needed t o perform t he desired t ask, execut e t he t ask, and t hen place any response dat a int o t he response SOAP m essage. Alt hough w e discuss t his subj ect in t erm s of a pivot point handler, t his sam e design pat t ern can ( and should) be used for any of t he handlers w rit t en no m at t er w here in t he chains t hey appear.

        There is no lim it t o t he t ypes of resources t hat handlers can access. By t he t im e Axis ships it s first release, it should cont ain handlers t hat w ill enable access t o resources such as:

      • Enterprise Java Beans

        Scripting languages through the Bean Scripting Framework • COM objects

      • J2EE connectors • Code fragments in non-Java languages
      • How ever, current ly, Axis is only at an alpha st at e, and only t w o t ypes of handlers com e w it h it : a Java RPC handler and a Java Message handler. The Java RPC handler w ill exam ine t he body of t he request m essage and convert it int o a procedure call. I n ot her w ords, it w ill deserialize t he XML elem ent s in t he body int o individual Java obj ect s ( t he

        body

        m et hod param et ers) and, based on t he m et hod nam e ( also in t he elem ent ) , call from t he procedure call, it w ill be serialized and placed int o t he body of t he response SOAP m essage. ( I t m ight be useful t o exam ine t he code for t his handler—you can find it in t he Axis source in a file called

        org/apache/axis/providers/java/RPCProvider.java

        .) The ot her handler t hat com es w it h Axis is t he Java Message handler. This handler is sim ilar t o t he Java RPC handler in t hat it w ill exam ine t he body of t he request SOAP m essage t o det erm ine w hich Java m et hod t o call. How ever, unlike t he RPC handler, w hich w ill deserialize t he XML int o Java obj ect s, t he Message handler w ill t ake t he XML as is and sim ply pass it along t o t he desired m et hod unt ouched. This approach is useful in a docum ent - cent ric processing m odel—one in w hich t he business logic w ishes t o receive t he dat a in raw XML rat her t han t o have Axis t ry t o do any conversions. As long as it is possible t o w rit e Java code t o access t he desired resource, t here is no reason w hy a handler cannot be w rit t en t o access it —t hus m aking Axis an incredibly flexible and powerful SOAP processor. Of course, som et im es a handler's role is t o perform a t ask t hat is SOAP specific, and in t hat case placing t he logic inside t he handler it self m ight m ake sense. For exam ple, a handler t hat det erm ines w hich Web service t o invoke w ould probably not need t o access any back- end syst em s, but inst ead w ould use j ust t he dat a in t he SOAP m essage. Ult im at ely, t he choice of how t o design and w rit e a handler is not m andat ed by Axis, but rat her is left up t o t he handler w rit er. Axis does not place any rest rict ions on your design choices in hopes t hat t he syst em rem ains flexible and pluggable enough t hat it can be used in a lim it less num ber of configurat ions.

        Faults

        Current ly, Axis has a very sim ple m echanism for dealing w it h error condit ions. The code ( w het her it is t he Web service or som e pluggable com ponent such as a handler) can t hrow an except ion, w hich w ill t hen be caught by t he Axis engine and propagat ed back t o t he t ransport list ener. The t ransport list ener w ill t hen t ypically ret urn it t o t he client ( in t he HTTP case) —but t hat is an im plem ent at ion choice. I f t he except ion t hat is t hrow n is a

        AxisFault

        Java except ion, it w ill be convert ed int o a specialized Axis class, . This class is defined t o cont ain all t he inform at ion t hat w ould go int o a SOAP fault response m essage.

        faultcode Server.generalException detail

        The is set t o , and t he part of t he fault w ill cont ain t he st ack t race. I f you require m ore specialized det ail, t he code t hat t hrow s t he except ion can t hrow an

        AxisFault AxisFault

        direct ly. The class has t w o const ruct ors:

        publ i c Axi sFaul t ( St ri ng code, St ri ng st r, St ri ng act or, El ement [ ] det ai l s) ; publ i c Axi sFaul t ( QFaul t code, St ri ng st r, St ri ng act or, El ement [ ] det ai l s) ; AxisFault faultcode faultstring

        Like t he SOAP fault definit ion, s cont ain , ,

        faultactor faultdetails QFault

        , and fields. The class is a ut ilit y class t hat cont ains t he fully qualified nam e of t he fault code ( nam espace and local nam e) . The

        faultdetails

        field is an array of DOM elem ent s so t hat t he specific XML t hat is cont ained in t he fault can be t ailored t o any specific needs. When Axis is com plet ed, it is expect ed t o include a m ore robust syst em for handling fault s. I n part icular, som e of t he ideas being discussed include:

        The ability to define a mapping between Java exceptions and • AxisFault s The ability to define fault chains where specific chains will be •

        The ability for handlers to have an undo mechanism so that some type • of rollback can be performed in the event of an error

        These ideas are not guarant eed t o be im plem ent ed in t he first release of Axis; t hey are j ust t he current list of ideas being considered.

        Message Patterns

        I t should be obvious t hat Axis is nicely designed t o handle a request / response m essage processing pat t ern. How ever, it is not lim it ed t o t his single m essage- flow pat t ern. As w e

        MessageContext

        st at ed earlier, each handler and service has available t o it a obj ect t hat w ill cont ain bot h t he request and response m essage; how ever, you don't have t o use bot h of t hese m essages. I t is possible t o configure chains of handlers t hat process t he request m essage but produce no response m essage. I n t he HTTP t ransport environm ent , doing so m ight seem st range; but in a non- request / response t ransport ( such as SMTP) , t his is a m uch m ore likely scenario. I n t his one- w ay m essage pat t ern, t he Axis engine can be configured t o use only handlers t hat exam ine t he request m essage and do not use t he response m essage at all. Not e t hat if a handler is invoked t hat does generat e a response SOAP m essage, but t he t ransport list ener chooses not t o do anyt hing w it h t he

        MessageContext

        response SOAP m essage inside t he obj ect , t hen t he response w ill be ignored. Axis assum es t hat t he t ransport list ener know s how t o deal w it h t he response m essage, and if it ignores any response, t hen t hat m ust be t he correct behavior. At t he t im e of t his w rit ing, Axis does not yet support t he not ion of asynchronous m essage processing, but it should by t he t im e of it s first release. I n t his m odel, Axis w ill allow t he client t o asynchronously invoke a Web service and at som e lat er point in t im e request t he response, t hus allow ing t he client t o perform ot her act ions w hile t he Web service is doing it s j ob.

      Building and Deploying an Intermediary

        Alt hough Axis can support t he not ion of a SOAP int erm ediary, Axis it self needs t o do very lit t le t o support it . An int erm ediary is a SOAP processing node t hat does som e w ork based on t he request ing SOAP m essage, but is not t he final dest inat ion of t he m essage; so, it is responsible for forw arding t he m essage t o t he next SOAP processing node in t he m essage pat h. From an Axis configurat ion point of view , t his is a sim ple m at t er of defining a chain t hat has as it s pivot point a Transport Sender handler. This handler w ill det erm ine t he next SOAP processing node in t he m essage pat h and send t he SOAP m essage t o it . I n t his w ay, t he handler is act ing like a SOAP client , so t he sam e client API s norm ally used in w rit ing an Axis client applicat ion can ( and should) be used in t his handler in conj unct ion w it h any server- side API s needed t o process or int erpret t he incom ing SOAP m essage. The SOAP specificat ion requires t hat t w o t hings m ust t ake place in a SOAP int erm ediary: All m essage headers t arget ed for t his int erm ediary ( for exam ple, t he act or at t ribut e on t he header point ing t o a cert ain URI ) are rem oved before t he m essage is sent t o t he next SOAP processing node, and if any of t hose m essage headers are m arked w it h t he

        mustUnderstand=1

        at t ribut e, t hey m ust be underst ood by t his SOAP node or a fault m ust be t hrow n. I n order t o locat e all t he SOAP headers t arget ed for t his act or, a handler can

        SOAPEnvelope

        use t he follow ing m et hod on t he obj ect :

        publ i c Enumerat i on get HeadersByName( St ri ng namespace, St ri ng l ocal Part ) ; SOAPHeader

        This m et hod w ill ret urn an enum erat ion of obj ect s. Once each header is processed, it is very im port ant t hat t he handler not ify t he Axis engine t hat t his header

        setProcessed()

        has been processed by calling t he m et hod: whi l e ( enum.hasMoreEl ement s( ) ) { SOAPHeader header = ( SOAPHeader) enum.next El ement ( ) ; // process header here header. set Processed( t rue) ; }

        Processed

        Set t ing t he flag on t his header indicat es t o Axis t hat t he header has been successfully processed. The Axis engine w ill t hen use t his inform at ion t o det erm ine if any

        mustUnderstand=1

        headers in t he m essage m arked w it h a at t ribut e are unprocessed,

        mustUnderstand and if so t hrow a fault .

        Current ly, in t he alpha release of Axis, int erm ediary support is not com plet e. I n

        part icular, support is not yet included for indicat ing w hich headers should be rem oved before t he m essage should be sent t o t he next SOAP processing node. SOAP V1.2 Axis is w rit t en t o support t he SOAP 1.1 specificat ion. I n t he alpha release, it support s/ im plem ent s alm ost all of t he specificat ion, and by t he t im e t he first release is done, t he ent ire specificat ion w ill be support ed. The W3C XML Prot ocol w orking group is current ly w orking on t he next version of t he SOAP specificat ion ( v1.2) , and m em bers of t he Axis developm ent t eam are const ant ly w at ching t he group's act ivit y t o ensure t hat t hey w ill fully support t hat version of t he specificat ion. As of now , t he changes proposed t o t he SOAP specificat ion are not so sw eeping t hat t hey w ill dram at ically change t he definit ion of SOAP. The group's m ain focus is fixing any am biguit ies or bugs in t he v1.1 specificat ion. How ever, a few changes w ill m ake a SOAP v1.2 m essage incom pat ible wit h a SOAP 1.1 m essage, so t hose int erest ed in wat ching ( or being involved in) t he w orking group's act ivit ies should j oin it s m ailing list . The group's Web sit e is at ht t p: / / w w w .w 3.org/ 2000/ xp/ Group/ .

        Monitoring

        Axis com es w it h a t ool t hat can be useful in m onit oring t he TCP/ I P t raffic bet w een your

        tcpmon

        SOAP client and SOAP server. The t ool is called and can be execut ed by running

        j ava org. apache. axi s. ut i l s. t cpmon

        or

        j ava org. apache. axi s. ut i l s. t cpmon 81 l ocal host 8080

        The first com m and w ill bring up t he t ool and t ake you t o an Adm in page t hat allow s you

        tcpmon

        t o ent er a port num ber on w hich w ill list en, a t arget host , and a t arget port num ber t o w hich t he incom ing request should be rout ed. By sim ply rout ing your SOAP

        tcpmon

        client 's request s t hrough , you w ill be able t o see t he request and response SOAP

        tcpmon

        m essages. The second com m and w ill let you st art by specifying t he list ening port num ber ( 81 in t he previous exam ple) , t he t arget host nam e, and t he port num ber ( localhost and 8080 in t his case) on t he com m and line—t hus bypassing t he Adm in page.

        tcpmon Figure 4.8 shows what looks like.

      Figure 4.8. TCPMonitor can be used to examine the request and response messages. You'll not ice t hat each request / response pair is given it s ow n ent ry t able at t he t op of t he w indow , allow ing you t o select w hich specific flow t o exam ine. Below t he t able is t he

        tcpmon

        request and response dat a. You can save t he dat a t o a file, ask t o t ry t o m ake t he XML look nice ( add linefeeds and spaces) , sw it ch bet w een a side- by- side layout and a t op- bot t om layout , or even ask it t o resend t he request dat a. When resending t he dat a, you are free t o m odify t he dat a in t he request side of t he w indow before resending; t hus, you can m ake a change t o t est a server w it h new XML w it hout having t o change any client code.

      Summary

        Because Axis is st ill under developm ent and only at an alpha st age, you should consult t he Axis Web sit e and docum ent at ion for t he lat est feat ures and API s. We hope t his chapt er has provided you w it h a basic underst anding of w hat Axis is, how it w orks, and how you can use it for new Web services as w ell as leverage it t o access exist ing I T asset s and resources wit h m inim al work. I n Chapt er 5 , we'll focus on how t o use SOAP ( and in part icular Axis) in som e scenarios t hat go beyond sim ply invoking a Web service; t hese scenarios are m ore like t he real w orld and deal w it h t he issues t hat com panies face every day.

      • I n Chapt er 3 , " Sim ple Obj ect Access Prot ocol ( SOAP) ," you saw how SOAP enables applicat ions t o int eract w it h each ot her, and in Chapt er 4 , " Creat ing Web Services," you
      loosely—m ore im port ant ly, in a decent ralized m anner. On t he basis of such an advant age, in t his chapt er w e review a collect ion of t opics t hat are required for st art ing a serious e- Business wit h Web services. First , we consider securit y, assum ing t hat business- t o- business ( B2B) collaborat ion is perform ed in t erm s of SOAP m essaging. We w ill begin by discussing fam iliar t echnologies such as HTTP Basic Aut hent icat ion ( BASI C- AUTH) and Secure Socket Layer ( SSL)

        , t hen m ove t o SOAP- specific securit y, such as SOAP Digit al Signat ure and encrypt ion. We'll also discuss Public Key I nfrast ruct ure( PKI ) as a basis for m any securit y t echnologies. Then, w e shift our focus t o int ranet applicat ions t hat are configured t o process incom ing SOAP m essages, w hich m ight pot ent ially produce response m essages. This approach is called Ent erprise Applicat ion I nt egrat ion ( EAI ) because t ypical ent erprises have a port folio of exist ing applicat ions t hat should be int egrat ed properly t o achieve addit ional business goals. We w ill t ake Ent erprise JavaBeans ( EJBs) , Java Message Service ( JMS) and Java 2 Plat form Ent erprise Edit ion ( J2EE) as a basis for int egrat ing applicat ions.

        Finally, we discuss t echnologies required for high- volum e SOAP servers in t erm s of Qualit y of Service ( QoS) . Perform ance, scalabilit y, and availabilit y are im port ant issues w henever you're developing real applicat ions. We w ill consider how exist ing t echnologies in t hat area are adopt ed for developing scalable SOAP servers.

        Web Services Security

        e- Business relies on inform at ion exchange bet w een t rading part ners over net w orks, oft en t he I nt ernet . Therefore, t here are alw ays securit y risks, because m essages could be st olen, lost , or m odified. Four securit y requirem ent s m ust be addressed t o ensure t he safet y of inform at ion exchange am ong t rading part ners:

        Confidentiality guarantees that exchanged information is protected

      • against eavesdroppers. Authentication guarantees that access to e-Business applications and •

        data is restricted to only those who can provide the appropriate

        proof of identity.

        Integrity refers to assurance that the message was not modified

      • accidentally or deliberately in transit. Non-repudiation guarantees that the sender of the message cannot deny • that he/she sent it.

        Not e t hat t hese requirem ent s are relat ed t o crypt ography because t hey concern how t o prot ect com m unicat ed dat a. Apart from crypt ography, w e m ust also consider prot ect ion of resources such as dat a and applicat ions in such a w ay t hat only appropriat e ent it ies are allowed t o access t he part icular resources. A fift h requirem ent is sum m arized as follow s:

        Authorization is a process to decide whether the identity can access • the particular resource. I n t his sect ion, w e review a collect ion of securit y t echnologies t hat specifically address inform at ion exchange am ong t rading part ners via SOAP m essaging. Figure 5.1 depict s a securit y archit ect ure t hat you should keep in m ind t hroughout t his sect ion.

      Figure 5.1. Security architecture for SOAP messaging.

        We begin by review ing w ell- know n securit y t echnologies: BASI C- AUTH and SSL. They are considered t o be t ransport securit y, as show n in t he figure. Transport securit y is useful t o som e ext ent , but it fails t o ensure non- repudiat ion and is not enough w hen you have t o include t hird- part y int erm ediaries. SOAP securit y provides t ransport - agnost ic securit y m easures. We w ill discuss digit al signat ures and encrypt ion for SOAP m essages. We w ill int roduce a non- repudiat ion service t hat ensures t he delivery of t he m essage w it h a t im est am p. This not ary t hird part y is a good pract ical exam ple of a SOAP int erm ediary

        . Focusing on t he int ernal process w it hin our exam ple com pany, w e w ill describe aut horizat ion t o prot ect resources by giving appropriat e perm issions t o t he accessing ent it y. We w ill m ainly discuss role- based access cont rol and briefly show how it can be im plem ent ed.

        Finally, w e w ill discuss Public Key I nfrast ruct ure ( PKI ) , w hich provides a foundat ion t o a solut ion for t he four risks: confident ialit y, aut hent icat ion, int egrit y, and non- repudiat ion. Alt hough PKI is a solid t echnology basis, it is fairly difficult t o im plem ent and use t hrough Public Key Crypt ography St andards ( PKCS) . We w ill see an em erging st andard, called XML Key Managem ent Services ( XKMS) , w hich enables key m anagem ent via XML.

        Let 's begin by est ablishing t he exam ple scenario w e'll use in our code sam ples

      Example Scenario

        I n our discussion of securit y, we'll cont inue our Skat esTown exam ple. Skat esTown's CTO, Dean Caroll, is beginning t o becom e concerned w it h securit y now t hat t he business is expanding. Skat esTow n is doing business w it h a large num ber of com panies, and m ost of t hem are not Fort une- 500 com panies. Current ly, Skat esTow n's Web services are secured only w it h SSL and BASI C- AUTH. Alt hough Dean not ices t hat t he com binat ion of t he t w o is not enough, he cannot t hink of a bet t er m echanism in t erm s of securit y.

        To ease Dean's concern, Al Rosen of Silver Bullet Consult ing w as asked t o advise Dean about w hat kind of securit y feat ures t o address in t he next developm ent phase. This w as not an easy t ask for Al eit her, because t here are num erous securit y t echnologies and specificat ions. I t is not possible and not m eaningful t o cover all of t hem . Therefore, he select ed a fairly sm all num ber of securit y feat ures and applied t hem t o Skat esTow n's SOAP- based t ransact ions, as w e'll present t hroughout t his chapt er.

      SSL and HTTP Basic Authentication

        The m ost popular securit y m et hod on t he I nt ernet is a com binat ion of BASI C- AUTH and SSL. This m et hod is w idely adopt ed in m any B2C shopping sit es such as Am azon.com ( ht t p: / / w w w .am azon.com ) because it s configurat ion is fairly sim ple, but it st ill provides a necessary securit y level for a sm all am ount of t ransact ions. Here, w e review BASI C- AUTH and SSL w it h exam ples of how t o use t hem w it h Axis.

        HTTP Basic Authentication You probably have experienced being required t o ent er a user I D and passw ord w hile visit ing a Web sit e. BASI C- AUTH is oft en called passw ord aut hent icat ion; it s specificat ion is defined in RFC 2617 ( BASI C- AUTH) . The t ypical BASI C- AUTH int eract ion bet w een a Web brow ser and a Web server is illust rat ed in Figure 5.2 .

      Figure 5.2. Interaction protocol for basic authentication. When t he Web brow ser sends an HTTP request t o access a prot ect ed Web resource, t he Web server ret urns an HTTP response, w hich includes t he error code " 401 Unaut horized" and t he follow ing HTTP header:

        WWW-Aut hent i cat e: Basi c real m="Real m Name" Realm is a nam e given t o a set of Web resources, and it is a unit t o be prot ect ed.

        BASIC-AUTH Basic in front of realm indicat es a t ype of aut hent icat ion—in t his case, .

        Based on t his inform at ion, t he Web brow ser show s a login dialog t o t he user. Then, t he Web brow ser sends an HTTP request again including t he follow ing HTTP header:

        Aut hori zat i on: Basi c credent i al

        Alt hough t he credent ial looks like encrypt ed t ext , it is logically plain t ext because it s form at is sim ply UserNam e: Password encoded wit h Base64 —for exam ple,

        U2thdGVib… SkateboardWarehouse:wsbookexample in Figure 5.2 can be decoded t o .

        The Web server aut hent icat es t he user w it h t he user I D and passw ord included in t he credent ial. I f t he given user I D and passw ord are w srong, " 401 Unaut horized" is ret urned. Moreover, t he Web server has an access cont rol list ( ACL) t hat specifies who can access what and checks whet her t he aut hent icat ed user can access t he Web resource. I f t he check succeeds, t hen " 200 OK" is ret urned; ot herw ise, " 401 Unaut horized" is ret urned. BASIC-AUTH in Axis

        I n t his sect ion, we review how t o use in Axis. On t he server side, have t o m odify t he server program s at all, but change t he server configurat ion. For

        web.xml Tom cat , we only m odify it s configurat ion file, as show n in List ing 5.1 .

        Listing 5.1 Configuration for Basic Authentication in Tomcat

        <web- app> <di spl ay- name>Basi c Aut hent i cat i on Sampl e</di spl ay- name> <servl et > <servl et - name>Axi sServl et Prot ect ed</servl et - name> <di spl ay- name>Apache- Axi s Servl et </di spl ay- name> <servl et - cl ass>org. apache. axi s. t ransport . ht t p. Axi sServl et </servl et - cl ass> </servl et > <servl et - mappi ng> <servl et - name>Axi sServl et Prot ect ed</servl et - name> <url - pat t ern>servi ces/prot ect ed</url - pat t ern> </servl et - mappi ng> <securi t y- const rai nt > <web- resource- col l ect i on> <web- resource- name>Prot ect ed Area</web- resource- name> <! - - Def i ne t he cont ext - rel at i ve URL( s) t o be prot ect ed - - > <url - pat t ern>/servi ces/prot ect ed</url - pat t ern> <! - - I f you l i st ht t p met hods, onl y t hose met hods are prot ect ed - - > <ht t p- met hod>GET</ht t p- met hod> <ht t p- met hod>POST</ht t p- met hod> </web- resource- col l ect i on> <aut h- const rai nt > <! - - Anyone wi t h one of t he l i st ed rol es may access t hi s area - - > <rol e- name>MyCust omer</rol e- name> </aut h- const rai nt > </securi t y- const rai nt > <l ogi n- conf i g> <aut h- met hod>BASI C</aut h- met hod> <real m-name>Prot ect ed Area</real m-name> </l ogi n- conf i g> </web- app> security-constraint web-resource-collection The elem ent defines a realm and ACL. url-pattern

        specifies a collect ion of Web resources, each locat ed at , accessed by an

        POST auth-constraint login- HTTP m et hod like . specifies who can access t he realm . config

        specifies aut hent icat ion m et hod on t he realm —for exam ple, BASI C- AUTH ( indicat ed by BASI C) . On t he client side, w e have t o m ake sure t hat t he user I D and passw ord are properly em bedded in t he HTTP request . Axis provides a basic funct ion for perform ing BASI C-

        POSubmission

        AUTH, so t he developm ent of t he client is fairly easy. List ing 5.2 shows a program t hat can access servers via BASI C- AUTH. Listing 5.2 that Performs Basic Authentication

        POSubmission package ch5. ex1; i mport j ava. i o. *; i mport org. apache. axi s. message. SOAPEnvel ope; i mport org. apache. axi s. message. SOAPBodyEl ement ; i mport org. apache. axi s. cl i ent . Servi ceCl i ent ; i mport org. apache. axi s. Message; i mport org. apache. axi s. MessageCont ext ; /**

      • Purchase order submissi on cl i ent
      • / publ i c cl ass POSubmissi on { /**
      • Target servi ce URL
      • / pri vat e St ri ng url ; pri vat e St ri ng useri d; pri vat e St ri ng password; /**
      • Creat e a cl i ent wi t h a t arget URL
      • /

        publ i c POSubmissi on( St ri ng t arget Url , St ri ng useri d, St ri ng password)

        { t hi s. url = t arget Url ; t hi s. useri d = useri d; t hi s. password = password; } /**
      • I nvoke t he PO submissi on web servi ce
      • @param po Purchase order document
      • @ret urn I nvoi ce document
      • @except i on Except i on I /O error or Axi s error
      • / publ i c St ri ng i nvoke( I nput St ream po) t hrows Except i on { // Send t he message Servi ceCl i ent cl i ent = new Servi ceCl i ent ( url ) ; cl i ent . set Request Message( new Message( po, t rue) ) ; cal l . set ( Transport . USER, useri d) ; cal l . set ( Transport . PASSWORD, password) ; cl i ent . i nvoke( ) ; // Ret ri eve t he response body MessageCont ext ct x = cl i ent . get MessageCont ext ( ) ;

        Message out Msg = ct x. get ResponseMessage( ) ; SOAPEnvel ope envel ope = out Msg. get AsSOAPEnvel ope( ) ; SOAPBodyEl ement body = envel ope. get Fi rst Body( ) ;

        // Get t he XML f rom t he body St ri ngWri t er w = new St ri ngWri t er( ) ; Seri al i zat i onCont ext sc = new Seri al i zat i onCont ext ( w, ct x) ; body. out put ( sc) ; ret urn w. t oSt ri ng( ) ; } }

        POSubmission

        The difference from t he original ( List ing 3.12 ) is show n in bold. Mem ber

        

      userid password ServiceClient

        variables and are added, and t hey are set t o t he obj ect

        invoke()

        in t he m et hod. As you can im agine, t hese values are used t o creat e an

        Authorization

        header, w it h t he base64 encoding of

        SkateboardWarehouse:wsbookexample

        , w hich is included in HTTP request . Unlike t he challenge- response prot ocol in Figure 5.2 , t he HTTP request here is accept ed direct ly

        Authorization because t he header is included. POSubmission

        The new sam ple can be execut ed w it h our exam ple navigat or shipped w it h

        /ch5/ex1/basicauth.jsp

        t his book. Go t o , specify a user I D and passw ord, and click t he Subm it PO but t on ( see Figure 5.3 ) . By ent ering t he values Skat eboardWarehouse and w sbookexam ple, you can successfully subm it t he purchase order. Ot herw ise, you w ill receive an error m essage.

      Figure 5.3. Example navigator GUI for basic authentication.

        Secure Socket Layer (SSL) BASI C- AUTH is useful, but on it s ow n, it is not secure enough because t he user I D and password are virt ually unprot ect ed. That is, an at t acker can easily eavesdrop on t he wire and eit her t ake t he passw ord t o im personat e t he user or t am per w it h t he t ransm it t ed dat a.

        SSL is a prot ocol for t ransm it t ing dat a in a secure w ay using encrypt ion m et hods. Wit h SSL, you can fulfill t hree of t he five securit y requirem ent s m ent ioned earlier: w hich is HTTP over SSL. How ever, ot her applicat ion layer prot ocols such as TELNET and FTP can be perform ed over SSL because SSL is locat ed bet w een t he applicat ion layer and t he t ransport layer ( TCP) . I n order t o est ablish a secure com m unicat ion channel, t he server and client have t o aut hent icat e each ot her. Wit h SSL, t he client can aut hent icat e t he server ( server aut hent icat ion) and vice versa ( client aut hent icat ion) . Current ly, client aut hent icat ion is not com m on because it requires t he client t o have a cert ificat e issued by a cert ificat e aut horit y ( CA) such as VeriSign. I nst ead, client aut hent icat ion is oft en perform ed w it h BASI C- AUTH for client convenience. How ever, in Web services of t he fut ure, not only hum an client s but also business applicat ions w ill also m ake request s, so m ut ual aut hent icat ion by SSL w ill becom e com m on.

        Using SSL with Axis I n t his sect ion, w e review how t o use SSL w it h Axis and address t he com binat ion of SSL server aut hent icat ion and BASI C- AUTH. SSL is based on a public key crypt ography syst em , also called an asym m et rical key crypt ography syst em , in which separat e keys are used for encrypt ion and decrypt ion. I n t he case of server aut hent icat ion, t he server has a privat e key t o decrypt m essages from t he client , and t he client has t he server's public key for encrypt ing m essages it sends aft er t he session is est ablished.

        I n t he case of secret key encrypt ion, m ore effort is required: St orage of t he secret key by each com m unicat ions part ner, as w ell as t he ( init ial) dist ribut ion of t he secret key t o t hose part ners, m ust be secured. This can be a daunt ing and error- prone t ask.

        keytool

        You can creat e privat e and public keys using t he program provided w it h t he

      • genkey keytool

        JDK. I f you add t he opt ion, t he com m and generat es a privat e key and it s public key ( t he com m and is broken here because of print ing const raint s, but it act ually appears on a single line) :

        keyt ool - genkey - keyal g RSA –si gal g MD5wi t hRSA - keysi ze 1024 - al i as Skat esTown - dname "CN=Purchase Order Servi ce, OU=Purchase Order Depart ment , O=Skat esTown, L=. . . , S=NY, C=US" - keypass wsbookexampl e - st orepass wsbookexampl e –keyst ore Skat esTown. ks - st oret ype J KS

        The opt ions are sum m arized in Table 5.1 . The generat ed privat e key and relat ed inform at ion are st ored in a keyst ore file, and keyst ore file inform at ion can also

      • keystore -storetype be specified in t he com m and ( for exam ple, and ) .
      • keyalg -key
      • dname The and opt ions specify t he specificat ion of t he privat e key.
      • alias

        specifies an ident ificat ion ( X.500 Dist inguished Nam e ) for t he key, and indicat es an alias for t he key ( unique w it hin t he keyst ore) . I n addit ion, a passw ord for

      • -keypass

        accessing t he key can be specified wit h ( by default , it is t he sam e as t he keyst ore passw ord) . A public key corresponding t o t he privat e key is also generat ed w it h t his com m and, and is included in a cert ificat e, w hich w ill be published t o t he client . Not e t hat t he cert ificat e it self is described in m ore det ail in PKI sect ion. The cert ificat e m ust be signed in order t o

      • sigalg dem onst rat e int egrit y. The signat ure algorit hm is specified by t he opt ion.
      keytool

        inform at ion cannot be specified w it h . I n t his case, t he cert ificat e is signed by t he privat e key t hat is generat ed, m aking it a self- signed cert ificat e. A self- signed cert ificat e is not pract ical for real use, but is sufficient ly useful for t he purpose of experim ent ing w it h SSL.

      Table 5.1. Options for the Command

        keytool Option Value Meaning

      • keyalg RSA Format of the private key is

        RSA

      • keysize 1024

        Key size is 1024 bits

      • alias SkatesTown

        Key alias is SkatesTown

      • dname CN=Purchase Order

        Identification of the key is CN=Purchase Service

        ,… Order Service, …

      • keypass wsbookexample

        Password for the private key is wsbookexample

      • sigalg MD5withRSA

        Method for signing certificate is MD5 with RSA

      • storepass wsbookexample

        Password for the keystore file is wsbookexample

      • keystore SkatesTown.ks SkatesTown.ks

        Keystore file name is JKS -

        Keystore file type is Java Key Store (JKS) keystoretype keytool

        The generat ed cert ificat e can be ext ract ed w it h t he follow ing com m and:

        keyt ool - export - al i as Skat esTown - f i l e Skat esTown. cer - keyst ore Skat esTown. ks - st orepass wsbookexampl e

        

      SkatesTown.cer

        The ext ract ed cert ificat e is st ored in . Next , we im port t he server cert ificat e t o a client keyst ore using t he follow ing com m and:

        keyt ool - i mport - t rust cacert s - al i as Skat esTown - f i l e Skat esTown. cer - keyst ore Skat eboardWarehouse. ks - st orepass wsbookexampl e - st oret ype J KS

        The client uses t he im port ed cert ificat e t o t rust t he server t hat ow ns t hat cert ificat e. When a client est ablishes a session, t he server sends a server cert ificat e t o t he client . I f t he cert ificat e is a m em ber of t he cert ificat es included in t he client keyst ore, t he client t rust s t he server and so proceeds t o t he session.

        keytool

        We provide a brow ser int erface for w it hin our exam ple navigat or. Visit

        /ch5/ex2/index.jsp keytool

        . I f you specify som e param et ers, com m ands are aut om at ically generat ed and execut ed ( see Figure 5.4 ) . You can creat e keyst ore files, export cert ificat es, and im port t hem t o ot her keyst ore files.

      Figure 5.4. Example navigator GUI for .

        keytool Let 's exam ine t he SSL configurat ion for a Web server ( Tom cat in t his case) . I n t he

        <tomcat-home>/conf/server.xml Connector

        file, you need t o add t he sect ion shown in List ing 5.3 . Listing 5.3 Tomcat Configuration for SSL

        <Connect or cl assName="org. apache. t omcat . servi ce. Pool TcpConnect or"> <Paramet er name="handl er" val ue="org. apache. t omcat . servi ce. ht t p. Ht t pConnect i onHandl er"/> <Paramet er name="port " val ue="8443"/> <Paramet er name="socket Fact ory" val ue="org. apache. t omcat . net . SSLSocket Fact ory"/> <Paramet er name="keyst ore" val ue="c: \ws- book\Skat esTown. ks" /> <Paramet er name="keypass" val ue="wsbookexampl e"/> <Paramet er name="cl i ent Aut h" val ue="f al se"/> </Connect or>

        Parameter port

        HTTPS set t ings are specified in t he elem ent s. The param et er indicat es a

        socketFactory

        port num ber for SSL connect ions. specifies t he Java fact ory class t hat w ill

        keystore keypass

        creat e SSL socket obj ect s. Wit h and , Tom cat can get a privat e key for SSL session. Not e t hat Tom cat assum es ( and hence requires) t hat t he server's keyst ore

        clientAuth

        passw ord is ident ical t o t he privat e key passw ord. Finally, specifies w het her client aut hent icat ion is perform ed. Not e t hat you have t o m odify

        <java_home>/jre/security/java.security

        t o run Tom cat w it h SSL. Refer t o t he sect ion " Java Secure Socket Ext ension " lat er in t his chapt er t o learn how t o m odify t his file and t hen execut e Tom cat . For t he client , you m ust set up Java syst em propert ies t hat are required w hen invoking

        POSubmission

        SSL. List ing 5.4 shows a m odified program . As you can see, t he keyst ore

        

      storetype keystore storepass

        t ype ( ) , keyst ore file nam e ( ) , and keyst ore passw ord ( ) are fed t o t he const ruct or, and t he param et ers are set for syst em propert ies. We w ill review t hese propert ies in t he sect ion " Java Secure Socket Ext ension ." Alt hough we java

        opt ion of t he com m and. I n t hat case, you do not have t o change t he List ing 5.2 program at all. The sect ion " Java Secure Socket Ext ension " w ill show such an alt ernat ive exam ple. Listing 5.4 that Performs Basic Authentication and SSL

        POSubmission package ch5. ex3; i mport j ava. i o. St ri ngBuf f erI nput St ream; i mport j ava. i o. St ri ngWri t er; i mport org. apache. axi s. encodi ng. Seri al i zat i onCont ext ; i mport org. apache. axi s. message. SOAPEnvel ope; i mport org. apache. axi s. message. SOAPBodyEl ement ; i mport org. apache. axi s. cl i ent . Servi ceCl i ent ; i mport org. apache. axi s. cl i ent . Transport ; i mport org. apache. axi s. t ransport . ht t p. HTTPTransport ; i mport org. apache. axi s. Message; i mport org. apache. axi s. MessageCont ext ; i mport org. apache. axi s. encodi ng. Servi ceDescri pt i on; f i nal publ i c cl ass DoOrder { f i nal St ri ng url ; f i nal St ri nt st oret ype; f i nal St ri nt keyst ore; f i nal St ri ng st orepass; f i nal St ri ng ui d; f i nal St ri ng password; publ i c DoOrder( St ri ng url , St ri nt st oret ype, St ri nt keyst ore, St ri ng st orepass, St ri ng ui d, St ri ng password) { t hi s. url = url ; t hi s. st oret ype = st oret ype; t hi s. keyst ore = keyst ore; t hi s. st orepass = st orepass; t hi s. ui d = ui d; t hi s. password = password; } publ i c synchroni zed st at i c St ri ng i nvoke( St ri ng xml) t hrows Except i on { St ri ng[ ] [ ] props = { { "j avax. net . ssl . t rust St ore", keyst ore, } , { "j avax. net . ssl . keySt ore", keyst ore, } , { "j avax. net . ssl . keySt orePassword", st orepass, } , { "j avax. net . ssl . keySt oreType", st oret ype, } , } ; f or ( i nt i = 0; i < props. l engt h; i ++) Servi ceCl i ent cl i ent = new Servi ceCl i ent ( new HTTPTransport ( url , "PO") ) ; cl i ent . set ( MessageCont ext . USERI D, ui d) ; cl i ent . set ( MessageCont ext . PASSWORD, password) ; cl i ent . set Request Message( new Message( new St ri ngBuf f erI nput St ream(xml) , t rue) ) ; cl i ent . i nvoke( ) ;

      Message out Msg = cl i ent . get MessageCont ext ( ) . get ResponseMessage( ) ;

      Servi ceDescri pt i on svc = new Servi ceDescri pt i on( "doOrder", f al se) ; cl i ent . get MessageCont ext ( ) . set Servi ceDescri pt i on( svc) ; SOAPEnvel ope envel ope = out Msg. get AsSOAPEnvel ope( ) ; SOAPBodyEl ement body = envel ope. get Fi rst Body( ) ; St ri ngWri t er wri t er = new St ri ngWri t er( ) ; Seri al i zat i onCont ext ct x = new Seri al i zat i onCont ext ( wri t er, cl i ent . get MessageCont ext ( ) ) ; body. out put ( ct x) ; ret urn wri t er. t oSt ri ng( ) ; } }

        POSubmission /ch5/ex3/index.jsp

        You can execut e w it h BASI C- AUTH and SSL via in t he exam ple navigat or. Specify som e values in t he page, such as t he keyst ore file, keyst ore passw ord, and so on, if you w ant , and t hen click t he Subm it PO but t on ( see Figure 5.5 ) .

      Figure 5.5. Example navigator GUI for basic authentication and SSL. Java Secure Socket Extension There is a st andard API for SSL, called t he Java Secure Socket Ext ension ( JSSE) .

        Tom cat also uses Sun JSSE in it s SSL im plem ent at ion, but no addit ional Tom cat configurat ion is required. How ever, you do have t o configure any Java Runt im e Environm ent ( JRE) t hat w ill run program s using JSSE, including Tom cat w it h SSL enabled. So, in t he case of a Tom cat Web server, t he follow ing JSSE set up applies t o t he server- and client - side.

        I n order t o use JSSE, you m ust first set up a securit y provider . The concept of a securit y provider is defined in t he Java Crypt ographic Archit ect ure ( JCA) . Because we describe JCA lat er, t his sect ion only explains how t o configure it .

        <java-

        The easiest w ay t o set up a securit y provider is t o m odify

        home>\jre\lib\security\java.security

        . The file cont ains a list of at least one

        security.provider.<n>

        provider in t he form . Add t he JSSE securit y provider as follow s:

        securi t y. provi der. 1=sun. securi t y. provi der. Sun securi t y. provi der. 2=com.sun. rsaj ca. Provi der securi t y. provi der. 3=com.sun. net . ssl . i nt ernal . ssl . Provi der jsse.jar jnet.jar

        Next , add t he t hree JSSE JAR files t o t he classpat h: , , and

        jcert.jar <java-

        . Alt ernat ively, t he files m ight be direct ly copied t o t he

        home>\jre\lib\ext direct ory.

        Aft er JSSE configurat ion is finished, t he client program can be execut ed using t he follow ing com m and:

        j ava - Dj ava. prot ocol . handl er. pkgs=com.sun. net . ssl . i nt ernal . www. prot ocol

      • Dj avax. net . ssl . t rust St ore=Skat eboardWarehouse. ks
      • Dj avax. net . ssl . keySt ore=Skat eboardWarehouse. ks
      • Dj avax. net . ssl . keySt orePassword=wsbookexampl e - Dj avax. net . ssl . keySt oreType=j ks Exampl ePOCl i ent - l ht t ps: //l ocal host : 8443/axi s/servl et /Axi sServl et

        You m ight not ice t hat t he t arget prot ocol is changed from HTTP t o HTTPS. The syst em

        java.protocol.handler.pkgs

        propert y enables program s t o handle HTTPS in t he URL class. Ot her syst em propert ies specify inform at ion t o access a client keyst ore. Trust ed cert ificat es in t he client keyst ore are exam ined w hen a server sends it s cert ificat e t o det erm ine w het her t he server is t rust ed.

        The SSL Protocol SSL w as proposed by Net scape Com m unicat ions and has been w idely used since t he explosion of t he World Wide Web, because it is support ed by Net scape Navigat or and Microsoft I nt ernet Explorer. The lat est version of SSL, 3.0, has been present ed t o t he I nt ernet Engineering Task Force ( I ETF) for st andardizat ion. Anot her closely relat ed prot ocol called Transport Layer Securit y prot ocol ( TLS) is current ly on version 1.0, published as RFC 2246. There are no m aj or differences bet w een SSL and TLS. TLS has not yet becom e w idely used, so SSL 3.0 is st ill dom inant .

        Let 's review t he SSL prot ocol in m ore det ail. Figure 5.6 illust rat es how a securit y handshake est ablishes a secure connect ion bet w een t he client and server. Once t he handshake com plet es, t he server and client have a com m on secret key wit h which dat a is encrypt ed and decrypt ed. I n ot her w ords, SSL uses t he public key( s) t o encrypt exchanges for t he sole purpose of generat ing t he shared secret key.

      Figure 5.6. SSL security handshake protocol.

        Despit e t he advant ages of using public key encrypt ion alone, SSL com bines t hem . I t does so because t he public key encrypt ion syst em t akes m ore t im e t o encrypt and decrypt m essages t han t he secret key encrypt ion syst em . Thus, t he com binat ion used by SSL t akes advant age of bot h t he easy m aint enance of public key encrypt ion and t he quicker operat ing speed of secret key encrypt ion. Let 's t ake a closer look at t he SSL handshake prot ocol, again referring t o Figure 5.6 . At phase I , t he client st art s t he handshake, and t hen sends a random num ber, a list of support ed ciphers, and com pression algorit hm s. At phase I I , t he server select s a cipher and a com pression algorit hm and not ifies t he client . Then it sends anot her random num ber and a server cert ificat e ( w hich includes a public key) . At phase I I I , t he client sends a pre- m ast er secret t o t he server, encrypt ing it wit h t he server public key. Finally, t he client m ight send a client cert ificat e. Now t he handshake is com plet ed. The server and t he client each generat e a m ast er secret by com bining t he random num ber t hat t he server sent , t he random num ber t hat t he client sent , and t he pre- m ast er secret . Several secret keys are creat ed from t he m ast er secret . For exam ple, one is used for encrypt ing t ransm it t ed dat a, and anot her is used for calculat ing digest value of t he dat e for int egrit y. SSL ensures aut hent icat ion ( by verifying t he cert ificat es) , confident ialit y ( by encrypt ing repudiat ion is not ensured w it h SSL because t he Message Aut hent icat ion Code ( MAC) value of t ransm it t ed dat a is calculat ed w it h a com m on secret key.

      Digital Signature

        Ret urning t o our exam ple scenario, Dean Caroll now underst ands t hat t he com binat ion of BASI C- AUTH and SSL is a good st art ing point t o secure SOAP- based com m unicat ion w it h t rading part ner. He also underst ands an im m ediat e problem w it h non- repudiat ion.

        Wit hout non- repudiat ion, a com pany can repudiat e it s purchase order even if t he com pany act ually sent t he order request , or t he com pany can claim t hat t he num ber of product s is w rong. Wit h respect t o exchange of XML m essages bet w een t w o part ies, a digit al signat ure provides a m eans t o prove t hat t he sending part y creat ed t he m essage. Al Rosen em phasized t hat t here is already a st able version of t he XML Digit al Signat ure specificat ion, w hich w ill becom e a W3C / I ETF st andard. Furt herm ore, Digit al Signat ure for SOAP, based on t he XML Digit al Signat ure, is published as a W3C Not e .

        SOAP Signature Example Current ly, t he Axis plat form does not include signat ure funct ions, but t he I BM Web Services Toolkit ( WSTK) 2.4 includes signat ure and verificat ion handlers for Axis. These handlers can be em bedded in Axis handler chains, as show n in Figure 5.7 .

      Figure 5.7. Signature and verifier handlers for purchase order processing service.

        I n our purchase order exam ple, t he client sends a purchase order docum ent and receives an invoice docum ent . I n pract ice, t hese t w o docum ent s should be signed; ot herw ise, one of t he part ies can repudiat e t hat it sent t he docum ent .

      Figure 5.7 illust rat es a handler configurat ion t hat causes bot h docum ent s t o be signed

        and verified. The signat ure handler at t he service request or's side signs t he purchase order. On t he service provider's side, t he verifier handler verifies t he signat ure of t he purchase order docum ent . The invoice is signed by t he service provider and verified by t he service request or.

        SOAP-SEC:Signature List ing 5.5 show s a digit ally signed purchase order docum ent .

        includes a signat ure on t he purchase order and specifies a collect ion of param et ers t o creat e t he signat ure. The det ails of t his digit ally signed SOAP m essage are described in t he follow ing sect ion. Listing 5.5 Purchase Order with a SOAP Digital Signature

        <SOAP- ENV: Envel ope xmlns: SOAP- ENV="ht t p: //schemas. xmlsoap. org/soap/envel ope/"> <SOAP- ENV: Header> <SOAP- SEC: Si gnat ure SOAP- ENV: act or="" xmlns: SOAP- ENV="ht t p: //schemas. xmlsoap. org/soap/envel ope/" xmlns: SOAP- SEC="ht t p: //schemas. xmlsoap. org/soap/securi t y/2000- 12"> <dsi g: Si gnat ure xmlns: dsi g="ht t p: //www. w3. org/2000/09/xmldsi g#"> <dsi g: Si gnedI nf o>

      <dsi g: Canoni cal i zat i onMet hod Al gori t hm="ht t p: //www. w3. org/TR/2001/

      REC- xml- c14n- 20010315"/> <dsi g: Si gnat ureMet hod Al gori t hm="ht t p: //www. w3. org/2000/09/ xmldsi g#rsa- sha1"/> <dsi g: Ref erence URI ="#43871"> <dsi g: Transf orms> <dsi g: Transf orm Al gori t hm="ht t p: //www. w3. org/TR/2000/ CR- xml- c14n- 20001026"/> </dsi g: Transf orms> <dsi g: Di gest Met hod Al gori t hm="ht t p: //www. w3. org/2000/09/xmldsi g#sha1"/> <dsi g: Di gest Val ue>. . . Base64- encoded Di gest Val ue. . . </dsi g: Di gest Val ue> </dsi g: Ref erence> </dsi g: Si gnedI nf o> <dsi g: Si gnat ureVal ue> . . . Base64- encoded Si gnat ure Val ue </dsi g: Si gnat ureVal ue> <KeyI nf o xmlns="ht t p: //www. w3. org/2000/09/xmldsi g#"> <KeyVal ue> <RSAKeyVal ue> <Modul us>. . . Base64- encoded Modul us. . . </Modul us> <Exponent >AQAB</Exponent > </RSAKeyVal ue> </KeyVal ue> <X509Dat a> <X509I ssuerSeri al >

      <X509I ssuerName> CN=Purchase Order Servi ce OU=Purchase Order

      Depart ment , O=Skat esTown, L=. . . , S=NY, C=US . . . . Format t ed f or pri nt i ng </X509I ssuerName> <X509Seri al Number>993353832</X509Seri al Number> </X509I ssuerSeri al >

      <X509Subj ect Name> CN=Purchase Order Servi ce, OU=Purchase Order

      Depart ment , O=Skat esTown, L=. . . , S=NY, C=US . . . . Format t ed f or pri nt i ng </X509Subj ect Name> <X509Cert i f i cat e> . . . Base64- encoded X. 509 Cert i f i cat e </X509Cert i f i cat e> </X509Dat a> </KeyI nf o> </dsi g: Si gnat ure> </SOAP- SEC: Si gnat ure> </SOAP- ENV: Header> <SOAP- ENV: Body> <po xmlns="ht t p: //www. skat est own. com/ns/po"

        . . . </po> </SOAP- ENV: Body> </SOAP- ENV: Envel ope>

        The digit al signat ure scenario can be execut ed w it h t he exam ple navigat or. Go t o

        /ch5/ex4/index.jsp

        , specify param et ers if you w ant , and click t he Subm it PO but t on ( see Figure 5.8 ) .

      Figure 5.8. Example navigator GUI for a digital signature.

        Deploym ent descript ors for t he exam ple are show n in List ings 5.6 and

        5.7 . At t he client

      sign

        side, request m essages are signed via t he handler, response m essages are verified

        verify log

        and logged via and handlers ( see List ing 5.6 ) . At t he server side, request m essages are verified and logged, and response m essages are signed ( see List ing 5.7 ) .

        sign

        As you can see in t he list ings, you need t o specify som e param et ers for handlers, such as a keyst ore file, key alias, st ore password, and key password. On t he ot her hand,

        verify t he handler does not require as m uch inform at ion.

        Listing 5.6 Deployment Descriptor for a Digital Signature at the Client

        <depl oy> <handl er name="l og" cl ass="org. apache. axi s. handl ers. LogHandl er"/> <handl er name="si gn" cl ass="com.i bm.wst k. axi s. handl ers. Si gner"> <opt i on name="al i as" val ue="Skat eboardWarehouse"/> <opt i on name="keyPassword" val ue="wsbookexampl e"/> <opt i on name="keySt ore" val ue="C: \home\ryo\wsbook\exampl es\Skat eboardWarehouse. ks" / > <opt i on name="keySt orePassword" val ue="wsbookexampl e"/> </handl er> <handl er name="veri f y" cl ass="com.i bm.wst k. axi s. handl ers. Veri f i er"/>

        <servi ce name="ht t p: //www. skat est own. com/ns/po" request ="si gn, l og" response="l og, veri f y"/> </depl oy>

        Listing 5.7 Deployment Descriptor for a Digital Signature at the Server

        <depl oy> <handl er name="l og" cl ass="org. apache. axi s. handl ers. LogHandl er"/> <handl er name="veri f y" cl ass="com.i bm.wst k. axi s. handl ers. Veri f i er"/> <handl er name="si gn" cl ass="com.i bm.wst k. axi s. handl ers. Si gner"> <opt i on name="al i as" val ue="Skat esTown"/> <opt i on name="keyPassword" val ue="wsbookexampl e"/>

      <opt i on name="keySt ore" val ue="C: \home\ryo\wsbook\exampl es\Skat esTown. ks" />

      <opt i on name="keySt orePassword" val ue="wsbookexampl e"/> </handl er> <servi ce name="ht t p: //www. skat est own. com/ns/po" request ="l og, veri f y" pi vot ="MsgDi spat cher" response="si gn, l og"> <opt i on name="cl assName" val ue="com.skat est own. servi ces. POSubmissi on"/> <opt i on name="met hodName" val ue="doSubmissi on"/> </servi ce> </depl oy>

        SOAP Signature Details

        Signature

        I n t he XML Digit al Signat ure specificat ion ( XML Signat ure) , an elem ent is defined w it h it s descendant s under t he nam espace

        

      ht t p: / / w w w .w 3.org/ 2000/ 09/ xm ldsig# . The SOAP Signat ure specificat ion defines how t o

      Signature

        em bed t he elem ent in SOAP m essages as a header ent ry. You can sign all or part of t he m essage. Furt herm ore, if a m essage has at t achm ent s, t hese t oo can be signed. I n our exam ple, t he body ent ry for t he purchase order is signed. Let 's t ake a closer look at our signed PO exam ple. I n t he exam ple, t he t arget elem ent of t he

        po:po po:po

        signat ure is . Briefly, t he digest value of t he sub- t ree is calculat ed, and t he

        Signature value is signed and included in t he elem ent .

        Let 's first review how t o get t he digest value of t he t arget . The t arget is specified by

        Reference SignedInfo URI

        under t he elem ent . I t s at t ribut e indicat es t he t arget in such a

        id po

        w ay t hat t he at t ribut e of t he elem ent is referenced. The t arget is t ransform ed by

        —t hat is, a canonicalizat ion m et hod for XML. ( XML Canonicalizat ion is a W3C Recom m endat ion t o generat e a canonical form for physically different but logically equivalent XML docum ent s.) Wit h XML- C14N, w e can check w het her XML docum ent s are sem ant ically equivalent using a st andardized code set , t he order of at t ribut es, t ab processing, and so on. The follow ing t w o docum ent s are quit e different at a glance:

        <?xml versi on="1. 0" encodi ng="us- asci i "?> <f oo b="b" a="a" ></f oo> <?xml versi on="1. 0" encodi ng="us- asci i "?> <f oo a="a" b="b"/>

        How ever, w it h XML- C14N, t hey are t ranslat ed int o t he follow ing ident ical docum ent :

        <?xml versi on="1. 0" encodi ng="us- asci i "?> <f oo a="a" b="b"></f oo>

        Aft er t ranslat ion, a digest value is calculat ed w it h an algorit hm specified by t he

        DigestMethod

        elem ent . Here SHA1 is used. The calculat ed value is insert ed in

        DigestValue elem ent , represent ed in Base64 form at .

        SignedInfo

        The value of t he t arget is not signed direct ly. Rat her, t he elem ent is act ually

        CanonicalizationMethod

        signed. An algorit hm specified by t he elem ent —t hat is, XML-

        SignedInfo SignedInfo

        C14N—canonicalizes . The canonicalized is signed w it h an

        SignatureMethod

        algorit hm specified by : RSA- SHA1. This algorit hm calculat es a digest

        SignedInfo

        value of t he subt ree, and t hen signs it w it h a RSA privat e key. The

        

      SignatureValue

        calculat ed value is insert ed int o t he elem ent , represent ed in Base64 form at .

        KeyInfo

        Opt ionally, t he signer can include a elem ent t o at t ach key inform at ion. More specifically, t he exam ple includes an X.509 cert ificat e, w hich cont ains a public key corresponding t o t he privat e key t hat signed t he digest value. Because t he cert ificat e is Abst ract Synt ax Not at ion One ( ASN.1) binary dat a, it s Base64 represent at ion is t here.

        So far, w e have review ed t he XML Signat ure synt ax in t he signat ure processing process. Verificat ion is carried out in t he sam e m anner. First , w e check t he value of t he

        DigestValue

        elem ent according t o XML- C14N and SHA1. Next , w e calculat e a digest

        SignedInfo SignatureValue

        value for t he subt ree t o com pare it w it h t he value in t he elem ent . More precisely, t he signat ure value is decrypt ed w it h t he public key, and t hen com pared t o t he calculat ed value.

      XML Encryption

        SSL is useful for ensuring confident ialit y. How ever, at least t w o problem s exist in t he cont ext of SOAP m essaging. By definit ion, SOAP m essaging can include int erm ediaries, and any of t hem could be ow ned by organizat ions ot her t han t he service request or or t he service provider. The first problem is t hat any of t hese t hird part ies m ight need t o read t he m essage. I nherent ly, t ransport - level securit y solut ions like SSL assum e t hat com m unicat ion occurs only direct ly bet w een t w o part ies. The second problem is t hat SSL encrypt s t he w hole m essage. I n som e cases, you m ight w ant t o encrypt only part s of t he m essage. SOAP Encrypt ion can resolve t hese problem s.

        We now updat e our purchase order docum ent t o include card inform at ion, as show n in

        BillTo CardInfo List ing 5.8 . I nst ead of a elem ent , w e insert so t hat t he service

        request or can pay w it h t he card. When Skat esTow n receives t he docum ent from t he Skat eboard Warehouse, it does not have t o know t he card inform at ion. I nst ead, it could j ust forw ard it t o a credit com pany t o det erm ine if t he Skat eboard Warehouse is reliable in t erm s of t he paym ent . SSL is not sufficient for t his purpose, because Skat esTow n can read t he card inform at ion.

        Listing 5.8 Purchase Order that Includes Card Information

        

      <po xmlns="ht t p: //www. skat est own. com/ns/po- wi t h- card" i d="43871" submit t ed="2001-

      10- 05"> . <cardI nf o> <name>Purchase Order Cl i ent </name> <company>VI SA</company> <expi rat i on>02/2005</expi rat i on> <number>1234123412341234</number>

        <shi pTo> <company>The Skat eboard Warehouse</company> <st reet >One Warehouse Park</st reet > <st reet >Bui l di ng 17</st reet > <ci t y>Bost on</ci t y> <st at e>MA</st at e> <post al Code>01775</post al Code> </shi pTo> <order> <i t em sku="318- BP" quant i t y="5"> <descri pt i on>Skat eboard backpack; f i ve pocket s</descri pt i on> </i t em> <i t em sku="947- TI " quant i t y="12"> <descri pt i on>St reet - st yl e t i t ani um skat eboard. </descri pt i on> </i t em> <i t em sku="008- PR" quant i t y="1000"/> </order> </po>

        At present , t here is no st andard specificat ion for SOAP Encrypt ion. Even t he XML Encrypt ion specificat ion w as published only very recent ly as a W3C Working Draft

        , and so is subj ect t o change. The discussion here is based on t he prelim inary draft of SOAP Encrypt ion included in WSTK 2.4. Aft er our SOAP Encrypt ion review , w e w ill review t he Java Crypt ographic Archit ect ure ( JCA) , w hich provides a basis for im plem ent ing SOAP Encrypt ion and SOAP Signat ure.

        SOAP Encryption: Syntax and Processing Let 's look at an XML Encrypt ion exam ple first . List ing 5.9 is an encrypt ed version of t he purchase order docum ent .

        Listing 5.9 Encrypted Purchase Order Document

        

      <po xmlns="ht t p: //www. skat est own. com/ns/po- wi t h- card" i d="43871" submit t ed="2001-

      10- 05"> <enc: Encrypt edDat a Type="ht t p: //www. w3. org/2001/04/xmlenc#El ement "> <enc: Encrypt i onMet hod Al gori t hm="urn: ni st - gov: aes- 128- cbc"/> <ds: KeyI nf o> <ds: KeyName>Shared key</ds: KeyName> </ds: KeyI nf o> <enc: Ci pherDat a>abCdeF. . . </enc: Ci pherDat a> </enc: Encrypt edDat a> . . . </po>

        This shows t he sim plest case, where t w o part ies share a com m on secret key. Not e t hat

        ds

        nam espace is a prefix for t he XML Digit al Signat ure nam espace. The XML Encrypt ion specificat ion reuses elem ent s from t he XML Digit al Signat ure nam espace as m uch as possible.

        EncryptedData Type

        The elem ent is a root elem ent for t he encrypt ed part , and it s

        EncryptionMethod

        at t ribut e indicat es t hat t he encrypt ed dat a is an XML elem ent . The

        KeyInfo

        elem ent specifies an encrypt ion algorit hm , and specifies a secret key. Based on t he secret key and t he algorit hm , t he card inform at ion is encrypt ed and st ored in t he

        CipherData elem ent .

        List ing 5.10 show s encrypt ion w it h a public key.

        Listing 5.10 Encryption with a Public Key

        

      <po xmlns="ht t p: //www. skat est own. com/ns/po- wi t h- card" i d="43871" submit t ed="2001-

      10- 05"> <enc: Encrypt edDat a Type="ht t p: //www. w3. org/2001/04/xmlenc#El ement "> <enc: Encrypt i onMet hod Al gori t hm="urn: ni st - gov: aes- 128- cbc"/> <ds: KeyI nf o> <enc: Encrypt edKey> <enc: Encrypt i onMet hod Al gori t hm="urn: rsadsi - com:rsa- v2. 0"/> <ds: KeyI nf o> <ds: KeyName>Recei ver' s key</ds: KeyName> </ds: KeyI nf o> <enc: Ci pherDat a>ghI j kL. . . </enc: Ci pherDat a> </enc: Encrypt edKey> </ds: KeyI nf o> <enc: Ci pherDat a>abCdeF. . . </enc: Ci pherDat a> </enc: Encrypt edDat a> . . . </po>

        The idea here is t hat t he sender generat es a random secret key, encrypt s t he key w it h t he receiver's public key, and encrypt s t he dat a w it h t he secret key. Let 's look at

        EncryptedKey EncryptionMethod KeyInfo

        first . specifies t he encrypt ion algorit hm , and specifies t he receiver's public key. Based on t hese elem ent s, a secret key is encrypt ed t o

        CipherData CipherData

        st ore in . Out er com es from an encrypt ion based on t he secret

        EncryptionAlgorithm key and an encrypt ion algorit hm specified by t he out er .

        SOAP-SEC:Encryption

        Let 's m ove on t o SOAP Encrypt ion. SOAP Encrypt ion defines a elem ent , w hich includes a reference t o t he locat ion of t he encrypt ed dat a. List ing 5.11 is a sam ple t hat includes SOAP Encrypt ion. Listing 5.11 SOAP Encryption Example

        <SOAP- ENV: Envel ope xmlns: SOAP- ENV="ht t p: //schemas. xmlsoap. org/soap/envel ope/"> <SOAP- ENV: Header> <SOAP- SEC: Encrypt i on xmlns: SOAP- SEC="ht t p: //schemas. xmlsoap. org/soap/securi t y/2000- 12"> <SOAP- SEC: Mani f est > <SOAP- SEC: Ref erence URI ="#i d- 0"/> </SOAP- SEC: Mani f est > </SOAP- SEC: Encrypt i on> </SOAP- ENV: Header> <SOAP- ENV: Body> submit t ed="2001- 10- 05"> <enc: Encrypt edDat a xmlns: enc="ht t p: //www. w3. org/2000/11/t emp- xmlenc" I d="i d- 0" Type="ht t p: //www. w3. org/2001/04/xmlenc#El ement "> . . . </enc: Encrypt edDat a> . . . </po> </SOAP- ENV: Body> </SOAP- ENV: Envel ope> po

        Id

        The encrypt ed is included in t he SOAP body, adding an at t ribut e t o t he

        EncryptedData Id SOAP-SEC:Reference

        elem ent . The at t ribut e is referred t o by w it hin

        SOAP-SEC:Encryption t he header ent ry.

        The encrypt ion header is int ended t o be a direct ive t o SOAP int erm ediaries. Wit h

        actorURI

        , you can specify a part icular SOAP int erm ediary. Therefore, you can t ell t he int erm ediary t o decrypt t he dat a, specifying w here t he encrypt ed dat a is locat ed. Thus, you can em bed encrypt ion and decrypt ion m et hods int o t he SOAP m essaging pat h in a flexible m anner.

        Java Cryptography Architecture and Java Cryptography Extension I n order t o im plem ent SOAP Signat ure and SOAP Encrypt ion w it h Java, you need t o underst and Java Crypt ography Archit ect ure ( JCA) and Java Crypt ography Ext ension ( JCE)

        . JSSE is also developed on t op of JCA/ JCE. I n t his sect ion, w e review JCA/ JCE in m ore det ail t o help you underst and t he crypt ography archit ect ure of Java. JCA and JCE incorporat e public key t echnologies. JCA provides a fram ew ork for accessing and developing core crypt ographic funct ions. I m plem ent at ion and algorit hm independence is addressed so t hat applicat ions are insulat ed from crypt ographic det ails. I n ot her w ords, crypt ographic im plem ent at ion and algorit hm s can be changed w it hout m odifying any applicat ion program s. JCA provides an API for digit al signat ure, m essage digest , key m anagem ent , cert ificat e m anagem ent , and access cont rol, as well as a basic securit y fram ework. The JCE API provides encrypt ion and key exchange. The separat ion of t he JCA and JCE API s st em s from export regulat ions by t he Unit ed St at es Com m erce Depart m ent .

        <java-

        I n t he sect ion on SSL, we discussed how t o configure t he

        home>\jre\lib\security\java.security

        file t o use SSL. As w e m ent ioned, each securit y provider is specified in t he follow ing form at :

        securi t y. provi der. <n>=<Securi t y Provi der Cl ass> The num ber indicat es a priorit y, and t he right side specifies a securit y provider class. java.security.Provider

        Each provider class is a subclass of and support s som e or all part s of Java securit y algorit hm s, such as DSA, RSA, MD5, or SHA- 1. For SSL, w e added t he t hird line, as follow s:

        securi t y. provi der. 1=sun. securi t y. provi der. Sun securi t y. provi der. 2=com.sun. rsaj ca. Provi der securi t y. provi der. 3=com.sun. net . ssl . i nt ernal . ssl . Provi der

        When a securit y algorit hm is required, providers are asked w het her t hey support t he

        part icular algorit hm according t o t he priorit y. For exam ple, if SHA1w it hRSA is required, t he second provider is chosen. Alt hough t he second and t hird providers bot h support it , t he second one has higher priorit y. I f SSL is required, t he t hird provider is chosen because only it support s SSL.

        So far, w e have review ed t ransport - layer securit y ( BASI C- AUTH and SSL) and SOAP- level securit y ( SOAP Signat ure and SOAP Encrypt ion) . You m ight ask: Why do w e need SOAP- level securit y in addit ion t o t ransport - level securit y like SSL? The reason is relat ed t o t he SOAP int erm ediary concept . As w e review ed in Chapt er 3 , SOAP m essages can t ravel t o m ult iple host s, pot ent ially relying on different t ransport s such as HTTP and SMTP

        . This indirect and t ransport - agnost ic nat ure of SOAP im plies t hat t ransport - layer securit y alone is insufficient . On t he ot her hand, you m ight ask: I s t ransport - layer securit y unnecessary? I n t heory, w e could provide a com plet e set of SOAP securit y feat ures w it h w hich t ransport - layer securit y w ould no longer be needed. How ever, t his approach w ill discard exist ing securit y infrast ruct ure t o som e ext ent , and is t herefore not accept able. SOAP- level securit y should be considered com plem ent ary t o t ransport - layer securit y. For exam ple, suppose t hat you w ant t o send a signed m essage t o a dest inat ion, ensuring confident ialit y. No int erm ediary exist s, and no elem ent - w ise encrypt ion is required. I n t his case, w hy not sim ply use a com binat ion of SOAP Signat ure and SSL? We should com bine SOAP- level and t ransport - layer securit y properly considering t he environm ent and applicat ion requirem ent s.

      Notary Service

        BASI C- AUTH/ SSL, SOAP Signat ure, and SOAP Encrypt ion are a proper set of t echnologies w it h w hich you can generally fulfill t he four basic securit y requirem ent s: confident ialit y, aut hent icat ion, int egrit y, and non- repudiat ion. How ever, t here is a furt her requirem ent : non- repudiat ion of m essage receipt . At t he client side, for exam ple, if Skat esTow n receives a purchase order docum ent from Skat eboard Warehouse, it should ret urn an invoice docum ent . Then, it st art s processing t he order—t hat is, shipping product s in t he order. How ever, Skat eboard Warehouse m ight not receive t he invoice because of net w ork t rouble, or it m ight claim t hat t he invoice w as not delivered. Or, if t he invoice delivery t akes m ore t han 10 days, Skat eboard Warehouse can, by policy, consider t he order unplaced or m isplaced.

        We w ant t o ensure t hat t he m essage has been received at t he dest inat ion, and t o know w hen it w as received. I n t he cont ext of SOAP, it m ight be a good idea t o include a not ary service as a SOAP int erm ediary bet w een t he t rading part ies, as show n in Figure 5.9 . The not ary service provider is t rust ed by bot h Skat esTow n and t heir cust om ers. When t here is a disagreem ent on m essage delivery bet w een t w o part ies, t he not ary service can arbit rat e t he problem on t he basis of it s log dat abase.

      Figure 5.9. Notary service as SOAP intermediary. From a business perspect ive, t his st ruct ure is beneficial for t hree part ies. Trading part ies can perform business t ransact ions safely sim ply by cont ract ing wit h t he not ary service. The not ary service can earn m oney according t o t he t ransact ion volum e. The only problem here is w het her t he not ary service is a real t rust ed part y. A num ber of not ary services have em erged already, such as VeriSign. Most of t hem aim solely at t rust ed st orage of dat a such as m edical records. However, once t hey are t rust ed widely, t hey could play t he role of a not ary in our business st ruct ure. What is t he benefit of SOAP in Figure 5.9 ? We could develop t he sam e business st ruct ure w it hout SOAP. Flexibilit y is t he m ain benefit . The Axis archit ect ure allow s t rading part ners t o focus com plet ely on building business- level service request or and service provider applicat ions, w it h t he caveat t hat t hey m ust respect ively produce and consum e

        XML docum ent s. At configurat ion t im e, handlers, pot ent ially including handlers t o invoke int erm ediaries, can be deployed at t he request or and/ or provider side t o enhance funct ionalit y or securit y of t he m essage send and receipt . When t hese ext ra handlers are added, t he request or and provider applicat ions do not have t o change at all. This show s t he flexibilit y of SOAP- based developm ent using Axis.

      Authorization

        So far, we have exam ined securit y t echnologies wit h which Web services can aut hent icat e users and prot ect t ransm it t ed dat a from eavesdropping or alt erat ion by inappropriat e part ies. From a t echnology point of view , net w ork securit y relies on crypt ographic m et hods, such as m essage digest s, digit al signat ures, and m essage encrypt ion. Aut horizat ion, t he securit y aspect covered in t his sect ion, is different from t he ot hers because it is not based on crypt ography.

        Aut horizat ion denot es grant ing aut horit y, including grant ing access t o resources based upon access right s. The purpose is t o cont rol access over resources, such as Web resources, dat abases, and so on. Perhaps t he m ost basic im plem ent at ion of t his idea is t he access cont rol list ( ACL) , which defines a m apping from ent it ies t o resources t hat can be accessed by each ent it y. A slight ly m ore sophist icat ed m odel is role- based access cont rol ( RBAC) , w hich m aps ent it ies t o roles and t hen roles t o resources. This m odel sim ply adds one ext ra layer of abst ract ion t o t he ACL m odel. Three t ypes of aut horizat ion m et hods are relevant for our SOAP archit ect ure. URL aut horizat ion cont rols access t o Web resources such as HTML pages and servlet s. Java

        Services ( JAAS) package. Finally, an aut hent icat ed ent it y m ight be issued a st andardized set of securit y assert ions t hat describe access right s for t hat ent it y and can be shared am ong t rading part ners. These t hree m et hods are exam ined in det ail in t he rem ainder of t his sect ion.

        URL Authorization We have already reviewed som e aspect s of URL aut horizat ion in BASI C- AUTH in t he Axis sect ion. Tom cat provides a m eans t o define user ident it ies, user- role m apping, and role-

        

      <TOMCAT>/conf/tomcat-user.xml

        resource m apping. The file cont ains t hese m appings as show n in List ing 5.12 . Listing 5.12 Tomcat User File Configuration

        <t omcat - users>

      <user name="Skat eboardWarehouse" password="wsbookexampl e" rol es="MyCust omer" />

      <user name="WeMakeI t " password="wsbookexampl e" rol es="MySuppl i er" /> <user name="Bot h" password="wsbookexampl e" rol es="MyCust omer, MySuppl i er" /> tomcat-users user

        The elem ent includes a collect ion of users, and defines a user ident it y, passw ord, and any roles assigned t o it . List ing 5.13 illust rat es access cont rol for servlet s. Listing 5.13 Configuration of Access Control over Servlets

        <web- app> <di spl ay- name>Basi c Aut hent i cat i on Sampl e</di spl ay- name> <servl et > <servl et - name>Pri ceCheckServl et </servl et - name> <servl et - cl ass>com.sams. xxxx. Pri ceCheckServl et </servl et - cl ass> </servl et > <servl et > <servl et - name>POServl et </servl et - name> <servl et - cl ass>com.sams. xxxx. POServl et </servl et - cl ass> </servl et > <servl et - mappi ng> <servl et - name>POServl et </servl et - name> <url - pat t ern>/servl et /j ust sampl e/POServl et </url - pat t ern> </servl et - mappi ng> <servl et - mappi ng> <servl et - name>Pri ceCheckServl et </servl et - name> <url - pat t ern>/servl et /j ust sampl e/Pri ceCheckServl et </url - pat t ern> </servl et - mappi ng> <securi t y- const rai nt > <web- resource- col l ect i on> <web- resource- name>Prot ect ed Area</web- resource- name> <url - pat t ern>/servl et /j ust sampl e/POServl et </url - pat t ern> <ht t p- met hod>POST</ht t p- met hod> </web- resource- col l ect i on> <aut h- const rai nt > <rol e- name>MyCust omer</rol e- name > </aut h- const rai nt > </securi t y- const rai nt >

        <aut h- met hod>BASI C</aut h- met hod> <real m-name>Prot ect ed Area</real m-name> </l ogi n- conf i g> </web- app>

        The sam ple here is quit e different from t he one in t he sect ion " SSL and Basic

        

      Aut hent icat ion " because w e have different servlet s for price checking and purchase order

        processing. Because Axis has a rout er servlet , all applicat ion classes are accessed t hrough t he rout er. How ever, if w e prepare a servlet for each applicat ion class, cont rolling access t o each of t hem is fairly sim ple, as t he exam ple dem onst rat es. Access Control for Java Classes How can w e perform aut horizat ion of individual Web services w it hin t he rout er servlet in Axis? We have t o cont rol access t o Java classes t his t im e. Let 's exam ine JAAS aut horizat ion over Java classes.

        JAAS is an ext ension of t he Java 2 Securit y Archit ect ure ( J2SA) . Hist orically, Java securit y has focused on securit y for m obile code such as Applet s. I n J2SA t erm s, perm issions are grant ed t o a codebase, t he origin of t he code t hat is being execut ed.

        <TOMCAT>/conf/tomcat.policy List ing 5.14 is an excerpt from .

        Listing 5.14 Permission Declaration in a Tomcat Policy File

        // Tomcat get s al l permissi ons grant codeBase "f i l e: ${ t omcat . home} /l i b/- " { permissi on j ava. securi t y. Al l Permissi on; } ; grant codeBase "f i l e: ${ t omcat . home} /cl asses/- " { permissi on j ava. securi t y. Al l Permissi on; } ; // Exampl e webapp pol i cy // By def aul t we grant read access on webapp di r and // wri t e i n workdi r grant codeBase "f i l e: ${ t omcat . home} /webapps/exampl es" { permissi on j ava. net . Socket Permissi on "l ocal host : 1024- ", "l i st en"; permissi on j ava. ut i l . Propert yPermissi on "*", "read"; } ;

        The first and second declarat ions show t hat Tom cat syst em classes are given all

        

      grant

        perm issions. On t he ot her hand, t he t hird st at em ent shows t hat t he Tom cat exam ple Web applicat ions can only list en t o localhost : 1024 and read propert ies. I n ot her w ords, t hey cannot list en t o ot her host s or port s, read or w rit e files, or do any act ion ot her t han t hose specified.

        Code- based aut horizat ion is useful. But in t he case of SOAP Messaging using Axis, w e need aut horizat ion based on t he ent it y t hat is t he origin of t he request , also called t he ( aut hent icat ed) request or. Figure 5.10 illust rat es how a JAAS- based aut horizat ion m echanism can be added t o Apache Axis. Ent it ies including bold lines are JAAS obj ect s.

      Figure 5.10. Authorization for Axis with JAAS. The cent ral dat a st ruct ure in JAAS is t he subj ect . A subj ect is any ent it y ( such as a person or com pany) , and it is represent ed by a collect ion of securit y- relat ed propert ies such as user I D, group, roles, em ployee num ber, and so on. These propert ies are called principals in J2SA. JAAS perform s t w o m aj or t asks: aut hent icat ion and aut horizat ion. The subj ect is discovered and a subj ect w it h associat ed principals is produced at t he aut hent icat ion phase, and t hen t he subj ect is ret rieved and exam ined, or consum ed, at t he aut horizat ion phase t o decide w het her t he subj ect can perform t he request ed act ion.

        LoginContext

        Let 's review Figure 5.10 m ore closely. I n Axis Engine, we first creat e a

        login

        and perform t o st art aut hent icat ion. I t st art s processing t he order—t hat is, shipping product s in t he order. The follow ing is a sam ple code:

        Logi nCont ext l c = nul l ; t ry { Subj ect subj ect = new Subj ect ( ) ; Hasht abl e hash = new Hasht abl e( ) ; hash. put ( "ht t p. username", useri d) ; //t hi s val ue shoul d be t aken f rom t he Axi s

      MessageCont ext hash. put ( "ht t p. password", password) ; // t hi s val ue i s al so f rom t he

      message cont ext subj ect . get Publ i cCredent i al s( ) . add( hash) ; l c = new Logi nCont ext ( "Axi sLogi n", subj ect ) ; l c. l ogi n( ) ; } cat ch ( Except i on l e) { }

        The idea here is t hat an init ial subj ect is creat ed including BASI C- AUTH inform at ion. The user I D m ight be m apped t o anot her I D for t he preceding st eps. When you invoke

        LoginContext.login() LoginModule

        , a is creat ed and invoked, at w hich t im e it creat es

        AxisLogin

        and at t aches principals t o t he subj ect ( in t he case of t he login m odule, t hese are Axis- specific principals) . But t hese login m odules are pluggable, so w e can assum e

        MyCustomer

        t hat , given our previous scenario, t he role w ill be added t o t he subj ect if t he HTTP usernam e w as Skat eboard Warehouse.

        Subject.doAs()

        When invoking t he service, w e call so t hat only aut horized subj ect s w ill be able t o perform t he operat ion. The act ual invocat ion looks like t his: new Axi sPri vi l egedAct i on( uri , met hod) ) ; run()

        This invocat ion leads us t o t he invocat ion of t he m et hod in

        AxisPrivilegedAction run()

        . Wit hin t he m et hod, access perm ission on t he associat ed resource ( specified by a URI and m et hod in t he previous program ) is checked, and t he

        AccessControlException

        t arget m et hod is invoked only if no is t hrow n. You can

        PrivilegedAction

        im plem ent classes in any way. For exam ple, we could have a role-

        <role, uri, method>

        act ion m apping dat abase cont aining t riples like , and our act ion class could check t he dat abase t o aut horize t he given request . I f t he dat abase has a

        <MyCustomers,supplier:po,processpo>

        t riple of t he form , a request t o perform a purchase order by Skat eboard Warehouse should be allow ed.

        We have now explored how t o creat e an Axis aut horizat ion m echanism using JAAS. As w e address ent erprise applicat ion int egrat ion, w e also need t o consider aut horizat ion in t he EJB securit y m odel. This t opic w ill be covered in t he sect ion, " J2EE Securit y Model " .

      Security Assertions

        So far, we have reviewed how t o perform aut horizat ion on a single part y. However, in an open e- Business w orld, m any unfam iliar business ent it ies m ight need t o access our Web services. I n t his case, it is not desirable t o set up usernam es and passw ords in t he Web server configurat ion for every possible ent it y. I n order t o address aut horizat ion in t his case, t he idea of a securit y assert ion is being discussed and st andardized. I n t his sect ion, w e review t he concept of a securit y assert ion, referring t o t he archit ect ure m ode of t he Securit y Assert ion Markup Language ( SAML) . We w on't review SAML synt ax because t he current synt ax is subj ect t o change.

        SAML defines an XML docum ent layout specifying t he following securit y assert ions:

        Authentication assertion • Attribute assertion • Decision assertion •

        These assert ions are produced by t heir respect ive aut horit ies. I n som e cases, t he aut horit ies are locat ed w it hin t he sam e com pany t hat host s t he Web service, but t hey could be locat ed anyw here on t he I nt ernet . Especially in t he lat t er case, int eroperabilit y is im port ant , and t hus SAML is defined in t he XML form at .

      Figure 5.11 illust rat es how t w o part ies can int eract w it h each ot her via a securit y

        POClient

        assert ion aut horit y. First , sends a request t o t he aut horit y w it h a user I D and passw ord. The aut horit y aut hent icat es t he request or, and issues a docum ent t hat cont ains aut hent icat ion and at t ribut e assert ions. For exam ple, t he docum ent says t he request or is t he Skat eboard Warehouse, and t he com pany is ranked AA ( very good) .

        POClient POService

        sends a purchase order at t aching t he securit y assert ion t o as a

        POService

        SOAP header. Then, perform s aut horizat ion, com plet ely relying on t he received assert ion.

      Figure 5.11. Interaction with security assertion authority. A securit y assert ion docum ent is a kind of t icket . The ident it y of t he carrier is not aut hent icat ed by t he receiver. This im plies t he possibilit y of a single sign- on for dist ribut ed, m ult ipart y I nt ernet services. Furt herm ore, t he t icket idea also ensures t he anonym it y of t he request or, because t he request or does not have t o show it s ident it y t o t he t arget service. We can expect t hat st andardized securit y assert ions w ill have a big im pact on business because w it h t hem , com panies no longer have t o m anage aut hent icat ion inform at ion on all com panies t hey t rade inform at ion wit h. The current world of e- Business consist s solely of t ransact ions am ong fam iliar com panies. Given t rust ed t hird part ies t o play t he role of assert ion aut horit ies, an open- ended, m ore flexible, and m ore scaleable e- Business infrast ruct ure is possible. St andardized securit y assert ions via convent ions like SAML provides a t echnology basis t o accom plish such a business st ruct ure.

      Public Key Infrastructure and Key Management To com plet e t he securit y discussion, t his sect ion covers Public Key I nfrast ruct ure ( PKI )

        So far, w e have assum ed t hat w e can obt ain t he public key represent ing a given ent it y for purposes of encrypt ion and digit al signat ure. How ever, how can w e know t he public key is aut hent ic and really represent s t he ent it y w hose nam e is on it ? PKI provides a basis t o ensure t he aut hent icit y of all ret rieved public keys.

        The process t hat ensures key aut hent icit y is key m anagem ent , w hich breaks dow n int o regist rat ion and ret rieval. Recent ly, t he XML Key Managem ent Specificat ion ( XKMS) has been published. Direct ly accessing PKI requires users t o do secure key generat ion and exchange on t heir ow n, but key m anagem ent is m uch sim pler w it h XKMS.

        I n t he rest of t his sect ion, w e give an overview of PKI , review ing it s key const ruct s, and present t he XKMS st andard for key m anagem ent . Public Key Infrastructure PKI seem s com plicat ed because it com bines a large num ber of t echnologies and order t o m anage cert ificat es, t here needs t o be an issuer( s) of cert ificat es, called a cert ificat e aut horit y, and a st ored collect ion of cert ificat es, called a cert ificat e reposit ory. These t hree const ruct s are cent ral in PKI . A cert ificat e is a proof of ident it y. Wit h a cert ificat e, you can relat e an ent it y t o it s public key. Because t he cert ificat e it self is digit ally signed, you can t rust it s cont ent s as long as you can t rust t he issuer. The X509 Cert ificat e, w hich is t he m ost popular cert ificat e form at , w ill be described in m ore det ail lat er.

        A cert ificat e aut horit y ( CA) is an ent it y t hat issues cert ificat es. I f you can t rust t he CA, you can t rust cert ificat es issued by t he CA. PKI assum es a fairly sm all num ber of CAs ( such as VeriSign) and allow s a CA t o issue cert ificat es for ot her CAs. As a result , cert ificat es are organized int o a hierarchy, as show n in Figure 5.12 . The root is called a root CA, int erm ediary nodes are called subordinat e CAs, and t erm inal nodes are called end ent it ies. The pat h for an end ent it y t o a root CA is called a cert ificat e pat h . I f t w o end ent it ies have a com m on CA, t hey can est ablish t rust w it h each ot her.

      Figure 5.12. PKI trust model.

        A cert ificat e reposit ory ( CR) is a public dat abase from w hich end ent it ies can get cert ificat es. Alt hough CRs are oft en developed on t op of a Light w eight Direct ory Access Prot ocol ( LDAP) server, t hey can be developed in any w ay ( for exam ple, based on an HTTP server) . Furt herm ore, it is st ill very com m on t o om it t he CR in real cases, such as when cert ificat es are exchanged via floppy disks. I n addit ion, cert ificat es can be revoked for various reasons. For exam ple, privat e keys warn everyone not t o accept t he associat ed cert ificat e as proof of ident it y in such cases. End ent it ies m ust check t he CRL as w ell as t he cert ificat e pat h.

        Let 's t ake a closer look at X.509 Cert ificat e Version 3. I t s m ain const ruct s are sum m arized as follow s:

      • Version— Version of X.509 Certificate, such as version 3.
      • Serial Num ber— A unique identifier for the issuer.
      • Signature— Algorithm for digital signature, such as Sha1WithRSAEncryption.
      • I ssuer— I D of the issuer specified by Distinguished Nam e ( DN) , such as "C= JP,

        ST= Kanagaw a, L= Yam at o, O= I BM, OU= TRL, CN= CA Adm in/ Em ail= caadm in@j p.ibm .com " • Validity— Duration of validity, specified by start and end dates.

      • Subj ect— I D of the owner, specified by DN.
      • Subj ect Public Key I nfo— Public key and its algorithm . A typical exam ple of an algorit hm is RSAEncrypt ion.

        You m ight not ice t hat an X.509 Cert ificat e defines only t he t echnical det ails of t he cert ificat e concept —for exam ple, t hat t he ow ner ( subj ect ) and t he public key are relat ed, and t he relat ionship is digit ally signed.

        XML Key Management Specification (XKMS) From an applicat ion point of view , our im m ediat e concern should be how t o m anage cert ificat es and public keys. PKI defines a collect ion of operat ions on cert ificat es, such as ret rieval, regist rat ion, backup, revocat ion, recovery, and so on. Wit h XKMS, applicat ions can int eract using PKI wit hout focusing on t he m yriad of fine det ails in PKI such as ASN.1.

        XKMS w as published as a W3C Not e in March 2001 by VeriSign, Microsoft , and WebMet hods. XKMS has t w o m aj or com ponent s: XML Key I nform at ion Service Specificat ion ( X- KI SS) , and XML Key Regist rat ion Service Specificat ion ( X- KRSS) . One of t he m ain goals of XKMS is t o com plem ent t he em erging W3C st andards, such as XML Digit al Signat ure and XML Encrypt ion. Act ually, key inform at ion is represent ed by t he

        ds:KeyInfo elem ent defined by XML Digit al Signat ure.

        Let 's exam ine X- KI SS w it h a digit al signat ure exam ple. List ing 5.15 is a m odified SOAP m essage including a digit al signat ure. Listing 5.15 SOAP Digital Signature with a Distinguished Name

        <SOAP- ENV: Envel ope xmlns: SOAP- ENV="ht t p: //schemas. xmlsoap. org/soap/envel ope/"> <SOAP- ENV: Header> <SOAP- SEC: Si gnat ure SOAP- ENV: act or="" SOAP- ENV: must Underst and="1" xmlns: SOAP- ENV="ht t p: //schemas. xmlsoap. org/soap/envel ope/" xmlns: SOAP- SEC="ht t p: //schemas. xmlsoap. org/soap/securi t y/2000- 12"> <dsi g: Si gnat ure xmlns: dsi g="ht t p: //www. w3. org/2000/09/xmldsi g#"> <dsi g: Si gnedI nf o> . . .

        <dsi g: Si gnat ureVal ue> . . . Base64- encoded Si gnat ure Val ue. . . </dsi g: Si gnat ureVal ue> <dsi g: KeyI nf o xmlns="ht t p: //www. w3. org/2000/09/xmldsi g#"> <dsi g: KeyName>CN=Purchase Order Cl i ent , OU=Purchase Depart ment , O=Skat eboardWarehouse, L=. . . , S=NY, C=US </dsi g: KeyName> </dsi g: KeyI nf o> </dsi g: Si gnat ure> </SOAP- SEC: Si gnat ure> </SOAP- ENV: Header> <SOAP- ENV: Body> <t : po i d="43871" submit t ed="2001- 10- 05"> <t : nonce>2001- 10- 05T12: 13: 14Z</t : nonce> . . . . </t : po> </SOAP- ENV: Body> </SOAP- ENV: Envel ope>

        KeyName KeyInfo

        The elem ent under specifies only t he DN of t he cert ificat e ow ner, and t here is no longer any det ailed cert ificat e inform at ion. For signat ure verificat ion, w e need t he public key. The key value of t he public key can be ret rieved via X- KI SS, as in List ing 5.16 .

        Listing 5.16 Query for Retrieving a Key Value

        <SOAP- ENV: Envel ope xmlns: SOAP- ENV="ht t p: //schemas. xmlso ap. org/soap/envel ope/"> <SOAP- ENV: Body> <Locat e xmlns="ht t p: //www. xkms. org/schema/xkms- 2001- 01- 20"> <Query> <KeyI nf o xmlns="ht t p: //www. w3. org/2000/09/xmldsi g#"> <KeyName>CN=Purchase Order Cl i ent , OU=Purchase Depart ment , O=Skat eboardWarehouse, L=. . . , S=NY, C=US</KeyName> </KeyI nf o> </Query> <Respond> <st ri ng>KeyVal ue</st ri ng> </Respond> </Locat e> </SOAP- ENV: Body> </SOAP- ENV: Envel ope>

        Locate KeyInfo

        The elem ent includes a query on , and a form at of t he response. This

        KeyName

        m essage request s a public key for t he DN specified by t he elem ent . List ing 5.17 shows it s response. Listing 5.17 Response for the Key Value Query

        <SOAP- ENV: Envel ope xmlns: SOAP- ENV="ht t p: //schemas. xmlsoap. org/soap/envel ope/" > <SOAP- ENV: Body> <Locat eResul t xmlns="ht t p: //www. xkms. org/schema/xkms- 2001- 01- 20"> <Resul t >Success</Resul t > <Answer> <KeyI nf o xmlns="ht t p: //www. w3. org/2000/09/xmldsi g#">

        <DSAKeyVal ue> <P> /X9TgR11Ei l S30qcLuzk5/YRt 1I 870QAwx4/gLZRJ mlFXUAi Uf t ZPY1Y+r/ F9bow9sbVWzXgTuAHTRv8mZgt 2uZUKWkn5/oBHsQI sJ Pu6nX/rf GG/g7V+f GqKYVDwT7g/ bTxR7DAj VUE1oWkTL2df OuK2HXKu/yI gMZndFI Acc= </P> <Q>l 2BQj xUj C8yykrmCouuEC/BYHPU=</Q> <G> 9+GghdabPd7LvKt cNrhXuXmUr7v6OuqC+VdMCz0HgmdRWVeOut RZT+ZxBxCBgLRJ Fn Ej 6EwoFhO3zwkyj Mim4TwWeot Uf I 0o4KOuHi uzpnWRbqN/C/ohNWLx+2J 6ASQ7zKTx vqhRkI mog9/hWuWfBpKLZl 6Ae1Ul ZAFMO/7PSSo= </G> <Y> Q9N/x1cj 2LSaV9ZdKPl 0Sl 9HhqbBdl oc/AvxvY41sQREau9s/HmPwFdTgn6i RCdXrg Y2Hai QYOl Bdt 09UW+q2Xj vY1vdrWhXl xy8VdSFEdMCl a926o38i gZj FqXF0LOl BKTK LQTsCzWWxDB6sK8LkvaUi kUFpudYa/rWP562GUI = </Y> </DSAKeyVal ue> </KeyVal ue> </KeyI nf o> </Answer> </Locat eResul t > </SOAP- ENV: Body> </SOAP- ENV: Envel ope>

        KeyValue

        The value of t he public key is included in elem ent . Wit h t his value, w e can verify t he signat ure of t he init ial SOAP m essage. As show n in t he exam ple, X- KI SS helps applicat ions obt ain crypt ographic key inform at ion. I n addit ion t o key value ret rieval, it can be used t o validat e a binding bet w een a key nam e and key value. I t is also useful for get t ing key inform at ion from an X.509 cert ificat e. I n a com plem ent ary w ay, X- KRSS provides key regist rat ion, revocat ion, and recovery services. Alt hough w e review ed int eract ions bet w een applicat ions and XKMS servers, how do

        XKMS servers int eract wit h PKI ent it ies such as CAs and CRs? Unfort unat ely, XKMS is j ust an int erface, and t herefore it does not prescribe how XKMS servers should behave. XKMS could be used t o support cert ificat e- less keys w hen full- feat ured PKI is not required. How ever, XKMS is m ost valuable if XKMS servers provide a light w eight int erface t o PKI . I n t hat case, a XKMS server could cache t he cert ificat e pat h and CRL w hen it receives a key regist rat ion or ret rieval request , and t hen periodically check t he CRL t o keep it s dat abase up- t o- dat e. One of t he im port ant aspect s of XKMS is t hat key m anagem ent funct ions are provided in t erm s of Web services. I n t his way, com plex cert ificat e processing logic is abst ract ed aw ay from applicat ions and int o server- side com ponent s. Furt herm ore, key m anagem ent could be adm inist ered at a single point w it hin an ent ire ent erprise. This is advant ageous

      How to Get Started with Security

        So far, Dean Caroll of Skat esTown has a pret t y good underst anding of t he securit y archit ect ure for SOAP and t he t echnologies available in t his area. The accept ance and m at urat ion of each t echnology is quit e different , how ever. For exam ple, BASI C- AUTH and SSL are w idely accept ed, and adopt ing t hem is not a problem . On t he ot her hand, t he new SAML proposal does not even have an init ial specificat ion.

        Al Rosen suggest s t hat Skat esTow n should begin w it h digit al signat ures in addit ion t o BASI C- AUTH and SSL. A signat ure is im m ediat ely required for non- repudiat ion, and XML Signat ure is now a proposed recom m endat ion. Al also recom m ends adding encrypt ion and aut horizat ion once digit al signat ures are in place.

        A w orking group has j ust been form ed for XML Encrypt ion, so it s specificat ion can st ill change drast ically. As for aut horizat ion, w e are not sure w het her JAAS will be broadly accept ed. We need t o see how it converges w it h t he EJB aut horizat ion m odel, as w e described in t he " EJB Securit y" sect ion. SAML and non- repudiat ion services are under discussion, and t hey are w ort h keeping an eye on. Finally, alt hough t here are few XKMS product s, you should t ry one of t hem ; WSTK 2.4 includes a dem onst rat ion. XKMS can drast ically decrease t he w orkload t o int egrat e your syst em s w it h PKI .

      Enterprise Application Integration

        I n real business sit uat ions, it is not sufficient t o develop Web applicat ions w it h servlet s alone. I nt egrat ion of exist ing applicat ions and business processes is m ore im port ant . Skat esTow n has a num ber of legacy applicat ions such as order m anagem ent , invent ory m anagem ent , and delivery syst em s, and is eager t o int egrat e t hem . This process is called Ent erprise Applicat ion I nt egrat ion ( EAI ) . A basis for EAI m ust be int eract ion m odels t hat support synchronous and/ or asynchronous int eract ions am ong applicat ions. The int eract ion m odels should include coordinat ion of t ransact ions over applicat ions and a secure execut ion environm ent . Robust ness, flexibilit y, and scalabilit y are also required t o im plem ent t he m odels. I n t his sect ion, we describe Java 2 Ent erprise Edit ion ( J2EE) as a vehicle t o perform EAI . Ent erprise Java Beans ( EJBs) provide a m essage- orient ed and obj ect - orient ed com ponent int eract ion m odel t hat support s bot h synchronous and asynchronous int eract ions. J2EE is a fram ew ork t o int egrat e EJBs and ot her Web applicat ion com ponent s such as t he servlet cont ainer. Wit h J2EE, a request t o a servlet can be perform ed w it hin a t ransact ion cont ext in a secure m anner. The rest of t his sect ion is st ruct ured as follows: First , we review a t ypical SOAP server archit ect ure for EAI on t he basis of J2EE. Transact ions and reliable m essaging are respect ively described in t he cont ext of t he SOAP server archit ect ure. Finally, w e review t he J2EE securit y m odel, referring t o t he previous sect ion.

      SOAP Server Based on J2EE

        The J2EE specificat ion addresses t he developm ent of new business services t hat com bine m any of t he new , best - of- breed applicat ions w hile leveraging previous invest m ent s in legacy syst em s. Because t hese services are archit ect ed as m ult it ier applicat ions including Web client s, Web servers, servlet cont ainers, applicat ion servers, and dat abases, t he m ain goal of J2EE is t o reduce t he cost and com plexit y of developing t hese m ult it ier services, result ing in services t hat can be rapidly deployed and easily enhanced. Accordingly, J2EE is a m et a- specificat ion over a collect ion of exist ing Java st andards as follow s:

      • Servlet— The HTTP server- side API to process HTTP requests and to return HTTP responses.
      • Java Server Page ( JSP) — A text- based solution to process a request to create a response. More specifically, you can include Java program s in HTML docum ent s.
      • Enterprise Java Beans ( EJB) — A standard com ponent architecture for building dist ribut ed obj ect - orient ed applicat ions, especially st rongly com bined w it h dat abase syst em s.
      • Java Database Connectivity ( JDBC) — The API for connectivity with database syst em s.
      • Java Message Service ( JMS) — A standard API for m essaging that supports reliable point - t o- point m essaging, as w ell as t he publish- subscribe m odel.
      • Java Nam ing and Directory I nterface ( JNDI ) — The standard API for nam ing and direct ory access.
      • JavaMail— The standard API to send e- m ail notifications.
      • JavaBeans Activation Fram ework ( JAF) — A fram ework to handle an arbitrary piece of dat a, such as MI ME byt e st ream s. The JavaMail API uses t he JAF API , so it m ust be included as w ell.

        We w ill not exam ine all t hese specificat ions. Rat her, w e'll consider how t o archit ect a SOAP server on t op of J2EE. Figure 5.13 show s an init ial cut of t he SOAP server archit ect ure t hat t akes int o account EAI . I n t his archit ect ure, t he front - end is an HTTP server, and a servlet cont ainer sit s next t o it . The server host s a SOAP engine ( for exam ple, Axis) , w hich is t he heart of a SOAP server. At t he back end, w e m ight have an applicat ion server—t hat is, an EJB cont ainer, dat abase, or collect ion of business applicat ions.

      Figure 5.13. SOAP server on J2EE architecture. I n t he sim plest case, we only have a Java program wit hin a servlet cont ainer as in m ost exam ples m ent ioned so far. The Java program can access a dat abase via JDBC, or invoke a business applicat ion via JMS. An applicat ion can be provided as an EJB ( host ed by t he applicat ion server) . The EJB can invoke a dat abase, a business applicat ion, or even anot her EJB obj ect host ed by anot her applicat ion server. One of key feat ures of J2EE is t ransact ion support . The next sect ion describes t ransact ions in t erm s of t he pat h of SOAP engines, EJB obj ect s, and dat abases. I n addit ion, reliable m essaging is discussed, especially t aking JMS int o account . J2EE provides a securit y m odel t hat includes aut horizat ion t o EJB. The J2EE securit y m odel is also discussed, clarifying furt her requirem ent s for t he SOAP server.

        Transaction Processing

        So far, our purchase order exam ple had been sim plified so t hat w e could focus on addressing SOAP feat ures. How ever, in realit y, t he process is m uch m ore com plicat ed because w e m ight have t o int egrat e m ult iple applicat ions, dat a, and even business processes. I n t his sect ion, w e ext end t he purchase order exam ple t o include a t ransact ion , w hich is a w idely used com put at ional m odel for const ruct ing reliable and available dist ribut ed applicat ions.

        Product Order

        We include t w o dat abases in our purchase order exam ple: and . The

        Product dat abase st ores product inform at ion, such as nam e, t ype, and descript ion.

        Furt herm ore, invent ory m anagem ent is perform ed w it h t his dat abase so t hat only

        Order

        product s in st ock are sold. The dat abase records purchase orders t hat are accept ed.

        Product Order

        We have t o ext end our purchase order program t o int egrat e t he and dat abases. There are t w o operat ions in t his new cont ext :

        1. Update the Product database to reduce the amount of inventory on hand based on how many of each product the customer orders.

        2. Update the Order database to add a record of the purchase order.

        How ever, sim ply execut ing t hese operat ions sequent ially is not sufficient because t he applicat ion m ight fail j ust aft er com plet ing t he first operat ion. I n t his case, t he st ock

        Product

        num ber in t he dat abase is decreased, but t he order is not recorded. The result of t he applicat ion should be all or not hing—t hat is, all of t he operat ions m ust com plet e, or none of t he operat ions should be allow ed t o com plet e. Such a requirem ent is called at om icit y and is one of key propert ies of t ransact ion processing. I n addit ion t o at om icit y, t ransact ions should have t hree ot her propert ies: consist ency, isolat ion, and durabilit y. These propert ies w ill be described m ore in det ail aft er w e review how our program can be im plem ent ed w it h EJB.

        Wit h EJB, dat a resources are represent ed as Java obj ect s, and t ransact ion processing over t he obj ect s is ensured. Figure 5.14 illust rat es an overview of t he purchase order

        Product

        program , w hich incorporat es dat abases w it h EJB. A obj ect in t he EJB cont ainer

        Order

        corresponds t o a record in t he product t able. I n t he sam e m anner, an obj ect corresponds t o a record in t he order t able. These EJB obj ect s are called Ent it y Beans because t hey represent ent it ies in dat a resources.

      Figure 5.14. Purchase order processing with EJB.

        POProcess

        On t he ot her hand, t he obj ect reads and updat es dat a in a dat abase on behalf of t he client . A Session Bean is an EJB obj ect t hat perform s business logic on behalf

        POProcess

        of a client in a dist ribut ed, t ransact ional cont ext . When t he obj ect receives a

        Product Order

        client request , it reads and updat es dat abases via and obj ect s. Alt hough it is com plicat ed t o updat e t he dat e on m ult iple resources during t ransact ion processing, t he EJB cont ainer provides a sim ple w ay t o perform t ransact ions. Let 's review our EJB obj ect s. When providing EJB obj ect s, we m ust im plem ent a hom e classes should be provided, as list ed in Table 5.2 . Not e t hat Cont ainer Managed Persist ence ( CMP) w ill be described in m ore det ail in t he exam ples.

      Table 5.2. EJB Classes for Purchase Order Program

        

      EJB Type Home Interface Remote Interface Component Implementation

      ProductHome Product ProductBean

        CMP Entity Bean OrderHome Order OrderBean

        CMP Entity Bean

      POProcessHome POProcess POProcessBean

        Session Bean

        Let 's t ake a closer look at som e of t hese EJBs. List ing 5.18 is t he definit ion of t he

        Product Product

        EJB. is an int erface for a product , so it defines a collect ion of m et hods

        SKU Name Type POProcess

        t o get and set dat a fields, such as , , , and so on. uses t his int erface t o look up and updat e t he fields. Listing 5.18 Definition of the Product Interface

        publ i c i nt erf ace Product ext ends j avax. ej b. EJ BObj ect { St ri ng get SKU( ) t hrows j ava. rmi. Remot eExcept i on; voi d set SKU( St ri ng newVal ue) t hrows j ava. rmi. Remot eExcept i on; St ri ng get Name( ) t hrows j ava. rmi. Remot eExcept i on; voi d set Name( St ri ng newVal ue) t hrows j ava. rmi. Remot eExcept i on; St ri ng get Type( ) t hrows j ava. rmi. Remot eExcept i on; voi d set Type( St ri ng newVal ue) t hrows j ava. rmi. Remot eExcept i on; St ri ng get Desc( ) t hrows j ava. rmi. Remot eExcept i on; voi d set Desc( St ri ng newVal ue) t hrows j ava. rmi. Remot eExcept i on; i nt get Pri ce( ) t hrows j ava. rmi. Remot eExcept i on; voi d set Pri ce( i nt newVal ue) t hrows j ava. rmi. Remot eExcept i on; i nt get I nSt ock( ) t hrows j ava. rmi. Remot eExcept i on; voi d set I nSt ock( i nt newVal ue) t hrows j ava. rmi. Remot eExcept i on; } ProductBean Product

        is t he im plem ent at ion of ; t herefore, it defines t he set / get m et hods and dat a fields for t hem . I n addit ion, it im plem ent s a collect ion of m et hods defined by

        EntityBean ejbCreate ebjLoad ejbActivate

        t he int erface, such as , , , and so on ( see

        

      List ing 5.19 ) . These m et hods are derived from an EJB obj ect lifecycle m odel. The lifecycle

        m odel is beyond t he scope of t his book, so int erest ed readers should refer t o t he EJB specificat ion. Listing 5.19 Class

        ProductBean publ i c cl ass Product Bean i mpl ement s Ent i t yBean { pri vat e j avax. ej b. Ent i t yCont ext ent i t yCont ext = nul l ; publ i c St ri ng sku; publ i c i nt pri ce; publ i c St ri ng name; publ i c St ri ng t ype; publ i c St ri ng desc; publ i c i nt i nSt ock; publ i c voi d ej bAct i vat e( ) t hrows j ava. rmi. Remot eExcept i on { } publ i c St ri ng ej bCreat e( j ava. l ang. St ri ng sku) t hrows j avax. ej b. Creat eExcept i on, j ava. rmi. Remot eExcept i on t hi s. sku = sku; ret urn sku; } publ i c voi d ej bLoad( ) t hrows j ava. rmi. Remot eExcept i on { } publ i c voi d ej bPassi vat e( ) t hrows j ava. rmi. Remot eExcept i on { } publ i c voi d ej bPost Creat e( j ava. l ang. St ri ng argProduct I d) t hrows j ava. rmi. Remot eExcept i on { } publ i c voi d ej bRemove( ) t hrows j ava. rmi. Remot eExcept i on, j avax. ej b. RemoveExcept i on { } publ i c voi d ej bSt ore( ) t hrows j ava. rmi. Remot eExcept i on { } publ i c j avax. ej b. Ent i t yCont ext get Ent i t yCont ext ( ) { ret urn ent i t yCont ext ; } publ i c voi d set Ent i t yCont ext ( j avax. ej b. Ent i t yCont ext ct x) t hrows j ava. rmi. Remot eExcept i on { ent i t yCont ext = ct x; }

      publ i c voi d unset Ent i t yCont ext ( ) t hrows j ava. rmi. Remot eExcept i on {

      ent i t yCont ext = nul l ; } publ i c St ri ng get SKU( ) { ret urn sku; } publ i c voi d set SKU( St ri ng newVal ue) { t hi s. sku = newVal ue; } publ i c St ri ng get Name( ) { ret urn name; } publ i c voi d set Name( St ri ng newVal ue) { t hi s. name = newVal ue; } publ i c St ri ng get Type( ) { ret urn t ype; } publ i c voi d set Type( St ri ng newVal ue) { t hi s. t ype = newVal ue; } publ i c St ri ng get Desc( ) { ret urn t hi s. desc; } publ i c voi d set Desc( St ri ng newVal ue) { t hi s. desc = newVal ue; } publ i c i nt get Pri ce( ) { ret urn pri ce;

      publ i c voi d set Pri ce( i nt newVal ue) { t hi s. pri ce = newVal ue; } publ i c i nt get I nSt ock( ) { ret urn i nSt ock; } publ i c voi d set I nSt ock( i nt newVal ue) { t hi s. i nSt ock = newVal ue; } }

        Product ProductBean

        As you can see, defining and is pret t y easy, because doing so is

        Product

        alm ost t he sam e as creat ing ordinary Java program s. Now , how do you relat e t o t he dat abase? You do not have t o change t he program at all; rat her, you can define t he m apping t o dat abase at deploym ent t im e. I t is w ort hw hile t o m ent ion t hat EJB program s are deployed w it h deploym ent descript ors, each of w hich declares all t he EJB's ext ernal dependencies ( such as t he nam es of resources t hat t he EJB uses) .

        Product

      List ing 5.20 is a definit ion for excerpt ed from t he deploym ent descript or of our

        Product persisence-type

        applicat ion. As you can see, it defines t hat is a CMP bean ( see elem ent ) , specifying w hich fields of t he CMP bean are m anaged by t he EJB cont ainer. Not e t hat how t hese fields are persist ed is left t o each vendor. I t also m ust be not ed t hat

        List ing 5.20 is an EJB 1.1 st yle deploym ent descript or t hat is different from t he form at defined for EJB 2.0.

        Listing 5.20 Deployment Descriptor for the Product EJB

        <ent i t y> <di spl ay- name>Product </di spl ay- name> <ej b- name>Product </ej b- name> <home>Product Home</home> <remot e>Product </remot e> <ej b- cl ass>Product Bean</ej b- cl ass> <persi st ence- t ype>Cont ai ner</persi st ence- t ype> <pri m-key- cl ass>j ava. l ang. St ri ng</pri m-key- cl ass> <reent rant >Fal se</reent rant > <cmp- versi on>1. x</cmp- versi on> <cmp- f i el d> <descri pt i on>no descri pt i on</descri pt i on> <f i el d- name>name</f i el d- name> </cmp- f i el d> <cmp- f i el d> <descri pt i on>no descri pt i on</descri pt i on> <f i el d- name>t ype</f i el d- name> </cmp- f i el d> <cmp- f i el d> <descri pt i on>no descri pt i on</descri pt i on> <f i el d- name>i nSt ock</f i el d- name> </cmp- f i el d> <cmp- f i el d> <descri pt i on>no descri pt i on</descri pt i on> <f i el d- name>pri ce</f i el d- name>

        <cmp- f i el d> <descri pt i on>no descri pt i on</descri pt i on> <f i el d- name>desc</f i el d- name> </cmp- f i el d> <cmp- f i el d> <descri pt i on>no descri pt i on</descri pt i on> <f i el d- name>sku</f i el d- name> </cmp- f i el d> <pri mkey- f i el d>sku</pri mkey- f i el d> <securi t y- i dent i t y> <descri pt i on></descri pt i on> <use- cal l er- i dent i t y></use- cal l er- i dent i t y> </securi t y- i dent i t y> </ent i t y>

      Product ProductHome ProductBeans home remote ejb-

        , , and are specified w it h , , and

        class persistence-type Container

        elem ent s. specifies a t o indicat e t hat t his ent it y

        field-name cmp-field

        bean is CMP. The elem ent under indicat es a dat a field t hat is

        ProductBean included in and w ill appear as a colum n nam e in a dat abase t able.

        Order Product

        Because t he definit ion of is inherent ly t he sam e as , we m ove on t o t he

        POProcess POProcessBean.order() session bean. I t s core port ion can be found in .

        POProcessBean List ing 5.21 is a port ion of .

        Listing 5.21 POProcessBean Class

        publ i c cl ass POProcessBean i mpl ement s Sessi onBean {

      publ i c Order order( St ri ng shi pI d, St ri ng bi l l I d, St ri ng sku, i nt quant i t y) t hrows POProcessExcept i on { t ry { Product product = product Home. f i ndByPri maryKey( sku) ; i f ( quant i t y>product . get I nSt ock( ) ) { t hrow( new POProcessExcept i on( "St ock i s not enough") ) ; } product . set I nSt ock( product . get I nSt ock( ) - quant i t y) ; Order order = orderHome. creat e( ""+Syst em.current Ti meMil l i s( ) ) ; Syst em.out . pri nt l n( "order cl ass: " + order. get Cl ass( ) ) ; order. set Bi l l To( bi l l I d) ; order. set Shi pTo( shi pI d) ; order. set SKU( sku) ; order. set Product Name( product . get Name( ) ) ; order. set Quant i t y( quant i t y) ; i nt t ot al =quant i t y*product . get Pri ce( ) ; order. set Tot al Pri ce( t ot al ) ; i f ( t ot al >MAX_TOTAL) { t hrow( new POProcessExcept i on( "Exceed t he max charge ( "+MAX_TOTAL+") ") ) ; } ret urn order; } cat ch( POProcessExcept i on e) { mySessi onCont ext . set Rol l backOnl y( ) ; t hrow e; } cat ch( Remot eExcept i on e) { t hrow new EJ BExcept i on( "Fai l i n Order. order: " +e. get Message( ) ) ; } cat ch( Creat eExcept i on e) { t hrow new EJ BExcept i on( "Fai l i n Order. order: " +e. get Message( ) ) ; } cat ch( Fi nderExcept i on e) { t hrow new EJ BExcept i on( "Fai l i n Order. order: " +e. get Message( ) ) ; } } }

        I n plain t erm s, t he processes here are as follow s: 1. Find a product based on a given SKU ID.

        inStock

        2. Update the data field if the order quantity exceeds the stocked products.

        3. Create an order based on the given request and the product information.

        4. Place the order only if the total charge is less than a value MAX_TOTAL ( ).

        The sequence of operat ions is perform ed w it hin a t ransact ion cont ext alt hough you see

        UserTransaction

        very few inst ruct ions relat ed t o t ransact ions. I f you use class, you

        begin() commit()

        invoke t he m et hod t o st art a t ransact ion, t he m et hod t o com plet e it ,

        rollback()

        and t he m et hod t o abort it . How ever, explicit ly com it t ing and rolling back t ransact ions is not a good pract ice. Rat her, you are st rongly advised t o use cont ainer- m anaged t ransact ions inst ead. I f you t ake t his approach, operat ions are perform ed aut om at ically in a t ransact ional cont ext . Only if you w ant t o allow rollback should you

        setRolebackOnly() SessionContext invoke m et hod of t he class as shown in t he list ing.

        MAX_TOTAL Product

        For exam ple, if t he t ot al charge is m ore t han , t he updat e on and t he

        Order creat ion of t he obj ect is undone.

      ACID and Two-Phase Commit

        So far, w e have only m ent ioned at om icit y. Now , w e w ill review t he four t ransact ion propert ies know n as ACI D ( At om icit y, Consist ency, I solat ion, and Durabilit y) , and w e w ill discuss t he popular t w o- phase com m it t ransact ion prot ocol. At om icit y ensures t hat a com put at ion w ill eit her t erm inat e norm ally, updat ing t he involved dat a resources in t he int ended w ay, or abort , updat ing not hing. I n ot her w ords, no int erm ediat e sit uat ion can exist w here dat a resources are part ially updat ed. This propert y should be ensured even if t here is a syst em failure. I n our exam ple w it hout at om icit y, if w e encount ered a syst em failure, w e w ould have a sit uat ion in w hich t he product dat abase is updat ed, but t he order dat abase is not updat ed.

        Consist ency ensures t hat only consist ent - st at e changes t o dat a resources occur despit e concurrent access and syst em failures. I n our case, w e have t he follow ing const raint over t he product and order dat abases:

        ([initial stock]-[current stock])*price == [total charge in The consist ency propert y relies on applicat ion program s t o som e ext ent , unlike ot her propert ies, because const raint s on dat a are not explicit ly represent ed. More specifically, such const raint s are em bedded in applicat ion logic; t herefore, a t ransact ion m anagem ent syst em cannot m onit or t hem .

        I solat ion ensures t hat concurrent com put at ions do not int erfere w it h each ot her. I n ot her words, t he result of concurrent execut ion of t ransact ions should be equivalent t o t he case

        inStock Product

        of sequent ial execut ion. I n our exam ple, t he field of is crit ical dat a, so it requires isolat ion. Assum e t hat t he st ock is 10, and t w o t ransact ions are execut ed, each of w hich requires 8 product s. Wit hout proper isolat ion, or a locking m echanism , bot h t ransact ions w ould successfully t erm inat e as long as t hey bot h sat isfy t he at om icit y const raint . Durabilit y ensures t hat once t he t ransact ion t erm inat es norm ally, it s result is st ored perm anent ly. Generally speaking, t erm inat ion of a t ransact ion does not m ean t he com plet ion of a dat abase updat e; rat her, it m eans t hat necessary inform at ion for updat ing is recorded. Therefore, t his propert y is relat ed t o recovery from failure.

        The t w o- phase com m it ( TPC) [ gl] prot ocol is a broadly accept ed solut ion for ensuring t he ACI D propert ies over dist ribut ed dat a resources. The TPC prot ocol defines t w o t ypes of m essages: " prepare" and " com m it " . To com plet e a t ransact ion, t hese m essages are sent t o all dat a resources. How ever, t he prepare and com m it m essages are never m ixed; t herefore, t he com plet ion phase is com prised of t w o phases: t he prepare and com m it phases. This sim ple principle is t he basis for various t ransact ion t heories.

        EJB wraps TPC prot ocols carefully so t hat applicat ion program m ers can develop t ransact ion processing easily and safely. Cont ainer- m anaged t ransact ion is a t ypical exam ple t o sim plify developm ent . I n sum m ary, EJB let s you develop t ransact ion processing properly w it hout w orrying about t he det ails of t ransact ion t heories.

        Executing EJB from Axis I n t his sect ion, w e execut e t he EJB version of t he purchase order w it h Axis. Go t o

        /ch5/ex5/index.jsp

        in t he exam ple navigat or. Through t he page, you can specify t he shipping I D, billing I D, SKU, and quant it y, and issue a purchase order ( see Figure 5.15 ) . As long as t he dat abase indicat es t hat sufficient quant it y exist s t o fill t he order, you receive an invoice. Ot herw ise, you receive an error m essage.

      Figure 5.15. Example navigator GUI to invoke EJB purchase order. List ing 5.22 show s a SOAP client program for t he purchase order.

        Listing 5.22 Client Code for Invoking an EJB Service

        publ i c cl ass POProcessCl i ent { pri vat e St ri ng url ; pri vat e St ri ng urn; publ i c POProcessCl i ent ( St ri ng t arget Url , St ri ng servi ceUrn) { url = t arget Url ; urn = servi ceUrn; } publ i c OrderDat a order( St ri ng shi pi d, St ri ng bi l l i d, St ri ng sku, i nt quant i t y) t hrows Except i on { Servi ceCl i ent cl i ent = new Servi ceCl i ent ( endpoi nt URL) ; OrderDat a order = ( OrderDat a) cl i ent . i nvoke( urn, "order", new Obj ect [ ] { shi pi d, bi l l i d, sku, new I nt eger( quant i t y) } ) ; ret urn order; } }

        As you can see, t here is no difference from ordinary Rem ot e Procedure Call ( RPC) invocat ions at t he client side. At t he server side, som e Universal Resource Nam e

        urn:X-SkatesTown:EJBPOService

        ( URN) such as is bound t o an EJB obj ect of t he

        POProcess urn

        class inst ead of a Java obj ect . I f t he m em ber variable in POProcessClient

        urn:X-SkatesTown:EJBPOService

        is , t he RPC request from t he client is dispat ched t o t he EJB obj ect as in an ordinary RPC invocat ion.

        Let 's exam ine how w e can use EJB w it h SOAP engines. Our m ot ivat ion for int roducing EJB w as t o carry out EAI . EJB obj ect s can be published ext ernally t hrough a SOAP engine. The exam ple in t his sect ion has dem onst rat ed t hat you can int egrat e m ult iple dat abases even w hen t hey are dist ribut ed in a com plicat ed configurat ion. How ever, you m ight also w ant t o int egrat e ot her kinds of applicat ions. For exam ple, you m ight have an invent ory m anagem ent applicat ion inst ead of t he product dat abase in our exam ple. I n som e cases, you can use a Bean- Managed Persist ence ( BMP) Ent it y Bean inst ead of a CMP Ent it y Bean.

        Furt herm ore, t he J2EE Connect or Archit ect ure Specificat ion has been released and is m uch m ore sophist icat ed t han t he BMP Ent it y Bean for im proving EAI . Alt hough t he J2EE Connect or Archit ect ure can be view ed as a generalizat ion of JDBC connect ion pooling, it provides a good fram ew ork t o int egrat e legacy applicat ions, addressing connect ion pooling, t ransact ions, and securit y. I f you're going t o perform EAI , you should check out J2EE Connect or Archit ect ure.

        Once you underst and EJB t ransact ion processing capabilit y, a quest ion arises: Can t he SOAP engine be im proved w it h EJB? Axis current ly provides a SOAP engine t hat w orks on t op of t he servlet cont ainer. Let 's exam ine how t o m ove t he SOAP engine t o an EJB cont ainer.

      Figure 5.16 illust rat es an archit ect ure w here a SOAP engine is locat ed w it hin an EJB

        cont ainer. Because request s are sent via various t ransport s, t here m ight be different t ypes of list eners, such as SMTP List eners, FTP List eners, and HTTP List eners. An HTTP List ener is developed as a servlet . Each list ener delegat es t he incom ing request t o t he EJB cont ainer via t he Rem ot e Met hod I nvocat ion over I nt ernet I nt er- ORB ( RMI - I I OP) prot ocol . Once a request is received, t he SOAP engine does not consult t he t ransport list ener again in t he processing of t hat request .

      Figure 5.16. SOAP Engine within EJB Container

        Wit hin t he SOAP engine, t here are five handlers t o process t he request . First , t he digit al

        POProcess

        signat ure of t he m essage is verified, t hen t he m essage is logged, and t he EJB

        POProcess

        is invoked t o process t he purchase order in t he m essage. The response from , an invoice, is digit ally signed and logged before being ret urned t o t he request or.

        I n pract ice, t he SOAP engine w ould be im plem ent ed as a St at eless Session Bean and w ould invoke t he handler chain from t he EJB. I f you use cont ainer m anaged t ransact ions, a t ransact ion st art s aut om at ically w hen t he SOAP engine is invoked. So, at om icit y over t he updat e of t hree dat abases is ensured w it hin t he t ransact ion cont ext . This archit ect ure is especially useful in t he case of a syst em failure. The syst em m ight fail during execut ion of t he signat ure handler in Figure 5.16 . I n t hat case, w e cannot ret urn an invoice t o t he request or, and w e m ight w ant t o roll back t he previous operat ions. This archit ect ure allow s us t o roll back t he t ransact ion aut om at ically so t hat w e do not have t o w orry about com plicat ed recovery sequences. A SOAP engine w it hin a servlet can handle norm al errors t hat are t ypically recognized by Java except ions. How ever, it cannot handle syst em failures properly because such an engine does not record enough inform at ion for recovery. On t he ot her hand, t he EJB- based archit ect ure is robust against syst em failure in t he sense t hat a recovery sequence is aut om at ically and properly carried out by t he EJB cont ainer.

        Transactions over the Internet Dean Caroll of Skat esTow n now realizes t he advant ages of using t ransact ions t o int egrat e legacy applicat ions. Transact ions ensure t hat applicat ion dat a is consist ent ly updat ed and sim plify error handling t rem endously. How ever, he has one lingering concern: Can w e use t he t ransact ion processing m odel for B2B collaborat ion over I nt ernet ? There are som e st andardizat ion effort s for m odeling t ransact ion processing ont o B2B. Transact ion I nt ernet Prot ocol ( TI P) provides a sim plified t w o- phase com m it prot ocol. TI P does not require a very large infrast ruct ure, but it has not garnered broader support because of it s com plexit y. XML Transact ion Aut horit y Markup Language ( XAML) is anot her effort for represent ing t ransact ion prot ocol in XML. I t was announced in Oct ober 2000, but so far no specificat ion has been published.

        What is t he key difficult y in m anaging t ransact ions over t he I nt ernet ? We need t o keep t he t w o- phase com m it m ent ( TPC) prot ocol in m ind. According t o t he TPC prot ocol, a t ransact ion m anager sends prepare m essages t o resource m anagers, and event ually receives OK m essages from t hem . Once a resource m anager sends t he OK m essage, it has t o w ait for a com m it or abort m essage from t he t ransact ion m anager. This suggest s t hat t he resource m anager m ight have t o w ait a w hile for t he m essage. Wit hin an int ranet , w e can expect each syst em t o be st able, and t hus t he net w ork t o be st able. How ever, w e cannot expect t he sam e level of st abilit y w hen relying on ot her com panies' syst em s using t he I nt ernet .

        A m ore pract ical approach is t o inst ead use com pensat ion t ransact ions, which have proper t ransact ion m odels for t he I nt ernet . I n our purchase order exam ple, w e can reconst ruct t he archit ect ure t o use com pensat ion t ransact ions by including t w o t ransact ions ( product and order dat abases updat ed w it h different t ransact ions) . Assum e t hat t he product dat abase is successfully updat ed, but som e problem occurs during t he order creat ion. I n t hat case, we issue a com pensat ion t ransact ion t o cancel t he updat e on t he product dat abase. Alt hough ACI D propert ies are not ensured here, m any real cases can be covered w it h t his prot ocol.

      Reliable Messaging

        The EJB archit ect ure int egrat es obj ect - orient ed program m ing w it h t ransact ion processing in an elegant w ay. I t s dist ribut ed obj ect archit ect ure relies on a client - server m odel w here t he client sends a request and w ait s for a response from a server synchronously. This synchronous invocat ion m odel fit s int o t ransact ion processing m odel w e have t horoughly review ed. How ever, t he synchronous m odel has several lim it at ions t hat are crucial for EAI .

        Mainly, t he problem s are relat ed t o com m unicat ion bet w een t he client and server. Wit h a synchronous m odel, when a com m unicat ion failure occurs, t he client receives an error m essage. Accordingly, t he client m ust send t he ident ical request t o t he server lat er. I n som e cases, t he client m ight not w ant t o ret ry, but w ould prefer t o have som eone send t he request w hen com m unicat ion is rest ored.

        This problem can be resolved by m essage queuing , w here t he client put s a m essage on a queue, and t he server get s a m essage from t he queue. The m essage in t he queue is oft en recorded in persist ent st orage; t herefore, t he m essage is sure t o be sent t o t he server. Thus, m essage queuing is oft en called reliable m essaging or guarant eed m essage delivery . Furt herm ore, m essage queuing is closely relat ed t o t ransact ion processing because t he queue can be considered a t ransact ion resource.

        Let 's exam ine Java Message Service ( JMS) , w hich is a st andard API for m essage queuing syst em s. First , w e w ill updat e our purchase order exam ple t o include JMS. Then, w e w ill exam ine t he EJB 2.0 Message- driven Bean , w hich is asynchronously invoked t o handle t he processing of incom ing JMS m essages as in JMS applicat ions. Finally, w e consider how t o adopt JMS as a SOAP t ransport . Message Queuing with JMS We could m ake our purchase order program m ore funct ional by assum ing t hat t here is an order m anagem ent syst em inst ead of an order dat abase. Figure 5.17 illust rat es t his ext ension including a m essage queue front - ending t he order m anagem ent syst em .

        POProcess

        put s order inform at ion in t he queue, and proceeds t o t he nex t operat ion w it hout blocking. On t he ot her hand, t he order m anagem ent syst em asynchronously get s t he inform at ion from t he queue t o record t he order inform at ion.

      Figure 5.17. Application integration with message queue. Listing 5.23 Class

        POProcessBeanJMS publ i c cl ass POProcessBeanJ MS i mpl ement s Sessi onBean { publ i c OrderDat a order( St ri ng shi pI d, St ri ng bi l l I d, St ri ng sku, i nt quant i t y) t hrows POProcessExcept i on { t ry { Product product = product Home. f i ndByPri maryKey( sku) ; i f ( quant i t y > product . get I nSt ock( ) ) { t hrow new POProcessExcept i on( "St ock i s not enough") ; } product . set I nSt ock( product . get I nSt ock( ) - quant i t y) ; OrderDat a order = new OrderDat a( "" + Syst em.current Ti meMil l i s( ) ) ; order. set Bi l l To( bi l l I d) ; order. set Shi pTo( shi pI d) ; order. set SKU( sku) ; order. set Product Name( product . get Name( ) ) ; order. set Quant i t y( quant i t y) ; i nt t ot al = quant i t y * product . get Pri ce( ) ; order. set Tot al Pri ce( t ot al ) ; queueConnect i onFact ory = ( QueueConnect i onFact ory) j ndi Cont ext . l ookup( "QueueConnect i onFact ory") ; queue = ( Queue) j ndi Cont ext . l ookup( queueName) ; queueConnect i on = queueConnect i onFact ory. creat eQueueConnect i on( ) ; queueSessi on = queueConnect i on. creat eQueueSessi on( f al se, Sessi on. AUTO_ACKNOWLEDGE) ; queueSender = queueSessi on. creat eSender( queue) ; Obj ect Message message = queueSessi on. creat eObj ect Message( ) ; message. set Obj ect ( order) ; queueSender. send( message) ; i f ( t ot al > MAX_TOTAL) { t hrow new POProcessExcept i on( "Exceed t he max charge ( " + MAX_TOTAL + ") ") ; } ret urn order; } cat ch( POProcessExcept i on e) { mySessi onCont ext . set Rol l backOnl y( ) ; t hrow e; } cat ch( Remot eExcept i on e) { t hrow new EJ BExcept i on( "Fai l i n Order. order: " +e. get Message( ) ) ; } cat ch( Except i on e) { t hrow new EJ BExcept i on( "Fai l i n Order. order: " +e. get Message( ) ) ; } } }

        Order OrderData

        Not e t hat t he ent it y bean is replaced by a Java class . The t ypical w ay

        QueueConnectionFactory 1. Look up and a queue via JNDI.

        

      2. Create a connection and a session object to access a queue manager.

        3. Create a queue sender object.

        4. Create a message object and send it.

        Because queues can be t ransact ion resources, t hey adhere t o t ransact ion m anagem ent .

        order()

        More specifically, w hen t he m et hod is invoked in List ing 5.23 , a t ransact ion st art s aut om at ically. Then, only when t he m et hod successfully exit s is a com m it m essage sent t o t he queue m anager. The m essage is t hen placed int o t he queue w here t he server can get it .

        OrderManagementListener

        Let 's look at t he server side, nam ely , w hich is t he front end

        OrderManagementListener

        of t he order m anagem ent syst em . List ing 5.24 is an class t hat get s order m essages from t he queue. Listing 5.24 Class

        OrderManagementListener publ i c cl ass OrderManagement Li st ener i mpl ement s MessageLi st ener { publ i c st at i c voi d mai n( St ri ng[ ] args) { . . . . . . . . . . . . . . . . . . t ry { j ndi Cont ext = new I ni t i al Cont ext ( ) ; queueConnect i onFact ory = ( QueueConnect i onFact ory) j ndi Cont ext . l ookup( "QueueConnect i onFact ory") ; queue = ( Queue) j ndi Cont ext . l ookup( queueName) ; queueConnect i on = queueConnect i onFact ory. creat eQueueConnect i on( ) ; queueSessi on = queueConnect i on. creat eQueueSessi on( f al se, Sessi on. AUTO_ACKNOWLEDGE) ; queueRecei ver = queueSessi on. creat eRecei ver( queue) ; queueConnect i on. st art ( ) ; queueRecei ver. set MessageLi st ener( t hi s) ; . . . . . .

        } cat ch ( Except i on e) { } f i nal l y { i f ( queueConnect i on ! = nul l ) { t ry { queueConnect i on. cl ose( ) ; } cat ch ( J MSExcept i on e) { } } } } publ i c voi d onMessage( j avax. j ms. Message msg) { i f ( msg i nst anceof Obj ect Message) { Obj ect Message message = ( Obj ect Message) msg; OrderDat a order = ( OrderDat a) message. get Obj ect ( ) ; // i nvoke order management syst em } el se {

        } } }

        Unlike on t he client side, a queue receiver obj ect is creat ed t o get m essages from t he

        OrderData

        queue. We ext ract an obj ect from a JMS m essage, t hen invoke t he order m anagem ent syst em w it h t he order dat a. Again, t he m essage is received only w hen a t ransact ion is com m it t ed at t he client side. You can int egrat e applicat ions in a loosely coupled and ext ensible m anner w it h m essage queuing. First , t he client does not have t o know w ho receives t he m essage. Second, even if t he server is not available because of a server failure or com m unicat ion problem , t he client can st ill cont inue t o send request s as long as t he queue is available. I n addit ion, load balancing is also possible by sim ply adding replicat ions of t he server. Message-driven Bean One of m ain im provem ent s in EJB 2.0 is t he int roduct ion of t he Message- driven Bean ( MDB) . MDB im proves t he program m ing of t he server side alt hough it does not affect t he client side at all.

        OrderManagementListener

        Let 's look at again. I t is a st andalone Java program ; t herefore, t ransact ion m anagem ent is not provided at all. You m ight w ant t o invoke your order m anagem ent syst em wit hin a t ransact ion cont ext . MDBs m eet such a requirem ent .

        OrderManagementMDB List ing 5.25 is . The funct ionalit y is t he sam e as OrderManagementListener

        , but t here is no code t o set up a queue connect ion and session. I n ot her words, basic operat ions for get t ing a m essage from t he queue are perform ed by an EJB plat form ; accordingly, MDB j ust receives t he dispat ched m essages.

        onMessage()

        More im port ant ly, t he m et hod is execut ed in a t ransact ional cont ext . Not e t hat if t ransact ion rolls back, t he m essage receipt is also rolled back ( in ot her w ords, t he m essage is put back on t he queue) . Listing 5.25 Class

        OrderManagementMDB publ i c cl ass OrderManagement MDB i mpl ement s MessageDri venBean { publ i c voi d onMessage( Message i nMessage) { Obj ect Message msg = nul l ; t ry { i f ( i nMessage i nst anceof Obj ect Message) { msg = ( Obj ect Message) i nMessage; OrderDat a order = ( OrderDat a) msg. get Obj ect ( ) ; // I nvoke order management syst em } el se { } } cat ch ( Except i on e) { } } } onMessage() Alt hough OrderManagem ent MDB defines four m et hods, only is show n here. OrderManagementListener

        I n cont rast t o , a procedure for receiving m essages from t he

        OrderData

        queue is not necessary. So, t his class can focus on ext ract ing t he obj ect and invoking t he order m anagem ent syst em . MDB is convenient ; how ever, w e need an EJB cont ainer for perform ing it . On t he ot her

        OrderManagementListener hand, t he JMS client can be a st andalone Java program like .

        I n som e cases, you m ight use JMS direct ly ( you m ight not have a proper EJB cont ainer in

        JMS As a SOAP Transport Because SOAP is t ransport - agnost ic, you can use JMS for it s t ransport inst ead of HTTP. Furt herm ore, t he concept of an int erm ediary suggest s t hat SOAP m essages can be rout ed t o m ult iple nodes via different t ransport s. Figure 5.18 illust rat es a possible configurat ion t hat cont ains bot h concept s. I nt er- com pany com m unicat ion is perform ed via HTTP( S) . The receiver com pany has a SOAP int erm ediary t hat receives SOAP m essages via HTTP and forw ards t hem t o backend applicat ions via JMS. The key idea here is t hat t he ext ernal firew all allow s HTTP t o pass, w hereas t he int ernal firew all allow s only JMS.

      Figure 5.18. SOAP messaging that includes both HTTP and JMS.

        This configurat ion is t ypical for several reasons. First , you can augm ent m essage processing by adding funct ions t o an int erm ediary w it hout changing t he backend applicat ions. For exam ple, you m ight add digit al signat ure verificat ion and logging funct ions t here. Even in t hat case, you do not have t o change t he backend applicat ions. I n addit ion, som e com panies do not w ant t o accept HTTP t hrough t heir int ernal firew all for securit y reasons. However, st rict ly speaking, sim ply elim inat ing HTTP does not necessarily im prove t he securit y level. The int erm ediary also plays a role of securit y dom ain boundary; for exam ple, credent ial m apping from ext ernal I Ds t o int ernal I Ds is perform ed. SOAP JMS t ransport is necessary especially for ent erprise cust om ers. Alt hough Axis does not current ly support JMS t ransport , a prot ot ype im plem ent at ion is provided in our

        JMSSender exam ples. List ing 5.26 is an excerpt from t he class for t he request or side.

        Listing 5.26 Class

        JMSSender publ i c cl ass J MSSender ext ends Basi cHandl er { pri vat e voi d sendMessage( MessageCont ext msgCont ext , St ri ng messageTxt ) t hrows Axi sFaul t { Byt esMessage msg; queueConnect i on = queueFact ory. creat eQueueConnect i on( ) ; queueSessi on = queueConnect i on. creat eQueueSessi on( f al se, Sessi on. AUTO_ACKNOWLEDGE) ; queueSender = queueSessi on. creat eSender( queue) ; msg = queueSessi on. creat eByt esMessage( ) ; msg. wri t eUTF( messageTxt ) ; TemporaryQueue repl yTo = queueSessi on. creat eTemporaryQueue( ) ; msg. set J MSRepl yTo( repl yTo) ; queueSender. send( msg) ; queueConnect i on. st art ( ) ; QueueRecei ver recei ver = queueSessi on. creat eRecei ver( repl yTo) ; j avax. j ms. Message repl yMsg = recei ver. recei ve( ) ; i f ( repl yMsg i nst anceof Byt esMessage) { St ri ng repl yTxt = ( ( Byt esMessage) repl yMsg) . readUTF( ) ; org. apache. axi s. Message respMsg = new org. apache. axi s. Message( repl yTxt ) ; msgCont ext . set ResponseMessage( respMsg) ; } cl oseConnect i on( ) ; } cat ch ( J MSExcept i on e) { t hrow new Axi sFaul t ( "J MSSender. sendMessage", "J MSExcept i on: " + e, nul l , nul l ) ; } } . . . . . . } sendMessage()

        The m et hod in t he class im plem ent s a synchronous request / response by com bining t w o JMS m essages. I t creat es a t em porary queue for a response, set s it as t he reply- t o queue in t he request m essage, and sends t he m essage t o a request queue. Then, it w ait s unt il a response m essage is delivered t o t he t em porary queue.

        JMSListener List ing 5.27 is a port ion of t he class for t he service provider side.

        Listing 5.27 Class

        JMSListener publ i c cl ass J MSLi st ener i mpl ement s MessageLi st ener { publ i c voi d onMessage( j avax. j ms. Message msg) { Byt esMessage byt esMsg = nul l ; org. apache. axi s. Message respMessage = nul l ; MessageCont ext msgCont ext = nul l ; St ri ng msgTxt = nul l ; Axi sEngi ne engi ne = Axi sServer. get Si ngl et on( ) ; msgCont ext = new MessageCont ext ( engi ne) ; t ry { i f ( ! msg i nst anceof Byt esMessage) { // do error handl i ng . . . . . . } byt esMsg = ( Byt esMessage) msg; repl yQueue = ( Queue) ( byt esMsg. get J MSRepl yTo( ) ) ; msgTxt = byt esMsg. readUTF( ) ; org. apache. axi s. Message soapMessage = new org. apache. axi s. Message( msgTxt ) ; msgCont ext . set Request Message( soapMessage) ; msgCont ext . set Transport Name( t ransport Name) ; engi ne. i nvoke( msgCont ext ) ; respMessage = msgCont ext . get ResponseMessage( ) ; St ri ng respSt ri ng = respMessage. get AsSt ri ng( ) ; Byt esMessage repl y = sessi on. creat eByt esMessage( ) ; repl y. wri t eUTF( respSt ri ng) ; sender. send( repl y) ; } cat ch ( Except i on e) { // do error handl i ng } } } onMessage()

        The cent ral m et hod in t his class is . Here, w e get t he reply queue from t he incom ing m essage and creat e a queue sender for ret urning t he response. Main

        engine.invoke()

        processing is invoked w it h . Finally, w e respond via t he t em porary queue creat ed by t he sender.

        /ch5/ex6/index.jsp

        To execut e SOAP over JMS, visit in t he exam ple navigat or ( see

      Figure 5.19 ) . Like ot her pages, specify som e param et ers and click t he Subm it PO but t on.

      Figure 5.19. Example navigator GUI for SOAP over JMS.

        Reliable Messaging on the Internet I n addit ion t o t ransact ions, Skat esTow n's Dean Caroll w ant s t o use ot her m eans t o reliably t ransm it m essages over t he I nt ernet . Unfort unat ely, despit e som e ongoing previous analysis of securit y t echnologies, w e can approach t his issue at t he t w o levels: m essaging and t ransport . An exam ple of a m essaging- level approach can be found in t he ebXML Transport ,

        MessageHeader

        Rout ing and Packaging ( ebXML TRP) specificat ion. I t defines t he elem ent , w hich is present as a child of t he SOAP header elem ent ; t his elem ent can cont ain a collect ion of param et ers t o perform reliable m essaging in a t ransport - agnost ic m anner. Alt hough t his specificat ion is w ell described, it is unfort unat ely not broadly accept ed at t his m om ent .

        JMS, as described in t his sect ion, is an approach for reliable m essaging. How ever, it requires t ransport product s ot her t han HTTP, such as I BM MQ Series. Recent ly, I BM announced HTTPR t o provide HTTP w it h reliabilit y and asynchronicit y feat ures. There is som e com m onalit y bet w een TRP and HTTPR m odels; for exam ple, t hey bot h assum e m essage handlers are present at t he sender and receiver sides. Accordingly, t heir prot ocols are sim ilar. The big difference is w het her t heir param et ers are defined as a SOAP header ent ry or HTTP headers. HTTPR is I BM propriet ary, so w het her it w ill be w idely accept ed is not cert ain.

        J2EE Security Model

        So far, we have reviewed t ransact ion processing aspect s of J2EE, focusing part icularly on EJB and JMS. I n addit ion t o t ransact ion processing, J2EE especially addresses securit y. We have already review ed securit y t echnologies such as SSL, digit al signat ures, and encrypt ion. I n t his sect ion, w e review an end- t o- end securit y m odel provided in J2EE.

      Figure 5.20 depict s J2EE securit y archit ect ure, which is based on a role- based access

        cont rol ( RBAC) . The HTTP server or servlet cont ainer aut hent icat es a request or, assigning roles t o it . Wit hin t he servlet cont ainer, access t o Web resources is aut horized based on a URL perm ission list ( not show n in t he figure) . Wit hin t he EJB cont ainer, access t o EJB obj ect s is aut horized based on a m et hod perm ission list . Perm ission list s are m appings bet w een roles and t arget obj ect s: Web resources and EJB obj ect s.

      Figure 5.20. J2EE security architecture.

        RBAC is flexible because role assignm ent rules and perm ission list s can be independent ly defined. There is a t rick here: A credent ial cont aining a user I D t ravels along t he m et hod invocat ion pat h, w hich can span m ult iple EJB cont ainers, and roles are assigned t o t he request or at each cont ainer for aut horizat ion. This concept is especially useful w hen t he syst em configurat ion is ext rem ely com plex. J2EE requires com pliant plat form s t o support t he follow ing t hree aut hent icat ion m et hods:

        HTTP basic authentication • SSL client authentication • Form-based authentication

      • Not e t hat w e w ill not discuss t he t hird m et hod because t he client is not a brow ser, but a st andalone applicat ion. Authorization in J2EE Using BASI C- AUTH, let 's review how user I Ds and roles are defined in J2EE. The follow ing

        application.xml

        is an excerpt from , w hich is a deploym ent descript or for t he overall J2EE applicat ion:

        <appl i cat i on> . . . <securi t y- rol e> <rol e- name>GoodCust omer</rol e- name> </securi t y- rol e> </appl i cat i on>

        GoodCustomer

        The role is used in t he J2EE applicat ion. J2EE does not prescribe any

        part icular m eans for user definit ion and user- role m apping. The follow ing is a plat form - dependent form at ext ract ed from Sun's J2EE Reference I m plem ent at ion:

        <j 2ee- ri - speci f i c- i nf ormat i on> <server- name></server- name> <rol emappi ng> <rol e name="GoodCust omer"> <pri nci pal s> <pri nci pal > <name>ABCRet ai l er</name> </pri nci pal > </pri nci pal s> </rol e> </rol emappi ng> . . . . . . </j 2ee- ri - speci f i c- i nf ormat i on> role

        Wit h t his form at , you can enum erat e user I Ds w it hin t he elem ent . A principal

        ABCRetailer

        indicat es a user or a user group. I n t his exam ple, user can have a role

        GoodCustomer .

        Let 's t ake a look at m et hod perm ission definit ion for EJB obj ect s. The following is an

        ejb.xml

        excerpt from , w hich is a deploym ent descript or for EJBs:

        <ej b- j ar> <di spl ay- name>OrderEj b</di spl ay- name> <ent erpri se- beans> </ent erpri se- beans>

        <securi t y- rol e> <rol e- name>GoodCust omer</rol e- name> </securi t y- rol e> <met hod- permissi on> <rol e- name>GoodCust omer</rol e- name> <met hod> <ej b- name>POProcess</ej b- name> <met hod- i nt f >Remot e</met hod- i nt f > <met hod- name>order</met hod- name> <met hod- params> <met hod- param>j ava. l ang. St ri ng</met hod- param> <met hod- param>j ava. l ang. St ri ng</met hod- param> <met hod- param>j ava. l ang. St ri ng</met hod- param> <met hod- param>i nt </met hod- param> </met hod- params> </met hod> </met hod- permissi on> </assembl y- descri pt or> </ej b- j ar> security-role

        The elem ent includes a collect ion of roles t hat are referenced som ew here

        method-permission role in t his file. indicat es who can access t he t arget m et hod wit h . role-name

        specifies t he role nam e for t his m et hod perm ission, in t his case,

        GoodCustomer .

        Relation to JAAS You m ight not ice t hat t here is som e com m onalit y bet w een J2EE RBAC and JAAS, w hich w e review ed in Sect ion " Access Cont rol for Java Classes ." A J2EE credent ial cont ains a user I D and roles. On t he ot her hand, a JAAS subj ect cont ains a user I D and principals. So, w e can provide a m apping bet w een roles in J2EE credent ial and principals in a JAAS subj ect . Thus, t he J2EE credent ial and t he JAAS subj ect converge in t heory.

        A pot ent ial scenario for using JAAS in J2EE is described as follow s ( ht t p: / / w w w .research.ibm .com / j ournal/ sj / 401/ koved.ht m l ) :

        

      "The EJB container issues a Subject.doAs( ) call to establish

      the credentials before invoking the EJB object. Through the EJB

      object's internal actions (e.g., through the ORB), AccessController.checkPermission( ) is called to determine whether the caller is authorized for the method."

        This indicat es t hat EJB aut horizat ion could be im plem ent ed w it h JAAS. Alt hough t here is no st andard for t his purpose, JSR 115 m ight resolve t his J2EE and JAAS m igrat ion issue. Once t he issue is resolved, we could provide a securit y fram ework t hat accept s credent ials ( such as BASI C- AUTH, SSL client aut hent icat ion, or digit al signat ures) and aut horizes access t o Web resources, Java classes, and EJB.

      Quality of Service

        Sophist icat ed e- Business Web services should be able t o provide various levels of qualit y according t o cust om er requirem ent s and choices. The Qualit y of Service ( QoS) concept originat ed in t he com m unicat ions indust ry, based on t he port ion of sent packet s t hat is alt hough applicat ions involving banking or air t icket reservat ion are st ill not allow ed t o perform erroneous operat ions or st op operat ions. This sect ion describes an archit ect ure for ent erprise SOAP servers, paying special at t ent ion t o QoS for e- Business applicat ions. We provide an overview of t he archit ect ure for t he ent erprise SOAP server, follow ed by a det ailed t reat m ent of t he various aspect s of QoS.

      Enterprise SOAP Server

        I n t he sect ion " Ent erprise Applicat ion I nt egrat ion ," w e review ed how t o int egrat e exist ing applicat ions w it h t he J2EE archit ect ure. The t ypical configurat ion is com prised of a Web server, a servlet cont ainer, som e EJB Cont ainers, Dat abases, and backend applicat ions. The Web server, Servlet cont ainer and EJB Cont ainers port ion of t his configurat ion is relat ed t o int egrat ion. This port ion is t erm ed Web Service Cont ainer ( WSC) for t he sake of discussion in t his sect ion. What happens if a WSC receives a large num ber of request s, beyond it s capacit y t o process t hem ? I t is likely t hat t he WSC w ill t ake it self offline or, w orse yet , one com ponent ( such as t he Web server) w ill crash t he com put er t hat it is running on. A know n t echnique t o avoid such a sit uat ion is t o prepare clones of t he original WSC for load- balancing. Once you int roduce clones, t he configurat ion becom es fairly com plicat ed. Therefore, you need a solid archit ect ure t o m anage various aspect s of t he w hole syst em , such as t he st at us of each com ponent and securit y.

      Figure 5.21 illust rat es an archit ect ural overview of an ent erprise SOAP server. At t he

        heart of t his archit ect ure is a collect ion of Web Services Cont ainers ( WSCs) . Each WSC invokes backend syst em s, such as t he order m anagem ent syst em , and dat abases. For t he sake of sim plificat ion, assum e t hat t he backend syst em s and dat abases are at least as scalable as t he WSCs. For exam ple, dat abases are configured int o a Dat a Area Net w ork in w hich dat a replicat ion is aut om at ically perform ed in preparat ion for a possible fail- over.

      Figure 5.21. An architecture for an enterprise SOAP server. Load- balancing, for inst ance, w ould be perform ed by a Round- Robin Dom ain Nam e Service ( RR- DNS) and a TCP Rout er , which dispat ches an incom ing SOAP m essage t o one of t he WSCs. A syst em m onit or checks t he st at us of each com ponent in each WSC and m ight st art up anot her WSC clone w hen t he load becom es t oo high, for exam ple. I n t his com plex configurat ion, m anaging end- t o- end securit y is a difficult t ask.

        I n t he ent erprise SOAP server archit ect ure, t here is a single secure dom ain w here all securit y inform at ion is m anaged; t his inform at ion is t he basis for all securit y decisions. Not e t hat t he archit ect ure for t he ent erprise SOAP server show n in Figure 5.21 is not necessarily t he best archit ect ure. To com e up wit h t he best archit ect ure, t he business and syst em requirem ent s m ust be considered. How ever, t he archit ect ure in Figure 5.21 does clearly show w hat aspect s should be considered for t he purpose of developing an e- Business QoS. Each aspect is discussed in det ail in t he following sect ions.

      High Availability

        Availabilit y is an obvious QoS requirem ent because users generally expect t hat services are alw ays, or very nearly alw ays, available. I f a service is frequent ly unavailable, users st op relying on it s service provider. An airline t icket reservat ion syst em , for exam ple, requires 99% availabilit y; t he service can be unavailable for only t w o hours per w eek.

        Load- balancing is a m eans t o achieving high availabilit y, especially in t erm s of increasing t he scalabilit y of t he syst em . As show n in Figure 5.21 , it com bines t w o t echniques: RR- DNS and t he TCP Rout er. A Dom ain Nam e Service ( DNS) m aps dom ain nam es ( host nam es) t o I P addresses, and t he round- robin variet y of DNS allow s a host nam e t o m anner, m eaning t hat consecut ive request s are assigned t o t he available I P addresses in a pre- det erm ined sequence, repeat ing it self at t he end of t he sequence. HTTP redirect is oft en used inst ead of RR- DNS for t he sam e purpose. When a client accesses a server, t he server responds wit h a redirect inst ruct ion t o one of t he available host s. One disadvant age of t his approach is t hat URLs of t he t arget host s are visible and t hen are pot ent ially st ored on t he client side ( such as in a brow ser's recent URL list or a bookm ark) , and t he client m ight direct ly access t his URL in subsequent request s. Thus, t he purpose of load- balancing m ight be defeat ed.

        Using TCP rout ers, you can configure clust ers t o scale up processing pow er. A TCP rout er forw ards incom ing request s t o WSCs. Alt hough t he rout er's nam e and I P address are public, t he addresses of WSCs are hidden from t he client . The TCP rout er could use a load- based algorit hm t o select a t arget WSC, or sim ply adopt t he round- robin process. There are m any com m ercially available TCP rout ers, such as I BM Net w ork Dispat cher ( ND) . ND can run on several operat ing syst em s, such as Windows, AI X, and Solaris, and can forw ard up t o 10,000 m essages per second w hen it runs on an em bedded OS. I n addit ion t o t he TCP rout er approach, you can use a t echnique called Net w ork Address Translat ion ( NAT) . NAT dynam ically edit s a part icular I P packet header t o change t he dest inat ion address, and edit s t he ret urn packet in t he sam e m anner. Cisco Local Direct or is an exam ple of a com m ercial product for NAT. Scaling up t he syst em wit h load- balancing t echniques m ight decrease t he risk of syst em failure, but syst em failure can st ill occur. But WSC clones, in addit ion t o being used t o increase scalabilit y, can also serve as a backup of t he original WSC, t aking over t he processing w hen t he WSC fails. This int roduces t he syst em propert ies of redundancy ( using clones for possible backup) and fault t olerance ( perform ing an aut om at ed procedure in case of fail- over) .

        Anot her issue relat ed t o syst em failure is recovery. Generally speaking, recovery requires t he syst em t o perform a com plicat ed recovery sequence. For exam ple, som e kind of st at us indicat or m ight be recorded at cert ain checkpoint s, and t he recovery process m ight rely on t he st at us hist ory. How ever, because t he SOAP server uses t ransact ion processing, t here need not be such a com plicat ed recovery sequence in t he ent erprise server archit ect ure. By definit ion, operat ions w it hin a t ransact ion cont ext are com m it t ed or abort ed. Therefore, in t he event of a syst em failure, t he EJB cont ainers w ill perform m ost of t he recovery sequence on behalf of applicat ions.

        System Management

        I n order t o com plet ely fulfill t he requirem ent for high availabilit y, syst em m anagem ent m ust also be considered. Because t he configurat ion of real e- Business syst em s is fairly com plex, as shown in Figure 5.21 , t here needs t o be a syst em at ic m eans t o m anage t he w hole syst em . I deally, t here w ould be a single point of m anagem ent , from w hich even syst em resources at ot her sit es can be m anaged. Syst em m anagem ent m ight include t he following t asks:

        Monitoring the status of system resources • Sending alert information to system administrators • Remotely configuring, deploying, and controlling system resources

      • Automatically resolving system resource issues if possible •

        Typically, syst em m anagem ent requires agent s, each of w hich m onit ors one or m ore syst em resources and cont inuously sends inform at ion t o t he syst em m onit or. Because sending t oo m uch inform at ion unduly consum es net w ork bandw idt h, a proper filt ering

        The syst em m onit or in Figure 5.21 is a cent ral cont roller t o perform syst em m anagem ent . On t he basis of t he inform at ion sent by agent s, t he syst em m onit or cont rols syst em resources: I t st art s/ st ops a resource, adds a resource, or changes t he configurat ion of a resource. Generally, syst em adm inist rat ors int eract wit h t he syst em m onit or t o rem ot ely cont rol syst em resources. Opt ionally, t he syst em m onit or could adj ust aut om at ically w it hout consult ing t he syst em adm inist rat or w hen cert ain know n problem s are det ect ed. Of course, t his is possible only w hen you provide t he syst em m onit or w it h a rem edy procedure in advance.

        Several t ypes of syst em resources need t o be m onit ored: net w ork devices, operat ing syst em s, dat abases, applicat ion servers, applicat ions, and so on. Net w ork device m anagem ent is easy t o im plem ent in t he sense t hat t here is a st andard specificat ion of net w ork m anagem ent , called Sim ple Net w ork Managem ent Prot ocol ( SNMP) , and a large num ber of devices support SNMP. On t he ot her hand, syst em soft w are and m iddlew are packages each have t heir ow n m anagem ent t ools. For exam ple, operat ing syst em s m ight collect values of key syst em param et ers, such as applicat ion st at uses, num ber of users logged in, j obs in a print queue, syst em load, free disk space, and ot her propert ies. I n t his case, t ot al syst em m anagem ent vendors should provide an agent t o ret rieve t hese OS param et ers and report t hem t o t heir syst em m onit or.

        The applicat ion m onit or is t he hardest t ask because applicat ion- specific agent s have t o be developed. I n t he case of t he ent erprise SOAP server, a syst em m onit or agent m ust be placed in t he Axis engine. WSTK 2.4 provides a bet a im plem ent at ion of syst em m anagem ent for Apache SOAP. I t can collect t he follow ing inform at ion:

        Total number of SOAP services deployed • Total number of RPC calls to all services combined • Total number of successful invocations of each service

      • Average response/transaction time for successful requests •

        The im plem ent at ion of t his SOAP syst em m anagem ent is based on t he Java Managem ent Ext ension ( JMX) . Wit h JMX, you can const ruct and m aint ain resource obj ect s t hat cont ain key param et ers, and em bed agent s t o m onit or t he values of t hose param et ers.

        WSTK 2.4 w ill be ext ended t o include addit ional feat ures, such as operat ions t o change t he behavior of a service and syst em adm inist rat or not ificat ion when cert ain crit eria are m et . I n sum m ary, syst em m anagem ent is a com plex t ask because different t ypes of syst em resources, locat ed at pot ent ially m any different sit es, need t o be m onit ored and cont rolled from one point . Alt hough som e aspect s, such as net w ork m anagem ent , already have w ell- developed solut ions, em erging areas have not been organized for syst em m anagem ent . One im m ediat e problem is t hat t here is no st andard w ay t o m anage J2EE plat form s. How ever, t here is ongoing discussion t ow ard t he goal of st andardizing J2EE Managem ent in JSR 77.

      Enterprise Security

        A com plex syst em configurat ion requires an int egrat ed securit y archit ect ure. Middleware applicat ions, such as Web servers, applicat ion servers, and dat abases, provide t heir own respect ive securit y funct ions. How ever, t he securit y funct ions should be int egrat ed in a cent ralized m anner, as show n in t he previous sect ion. I n addit ion, highly confident ial inform at ion, such as privat e keys, m ust be prot ect ed. This cent ralized approach also cont ribut es t o t he prot ect ion of t he single secure dom ain. The securit y server in Figure 5.21 is an aggregat ion of com m ercial securit y product s. I t has a user regist ry in an LDAP server t hat m anages user I Ds, passwords, cert ificat es, securit y at t ribut es, roles, and so on. I n t his archit ect ure, t he Web server neit her st ores nor checks user I Ds and passw ords, but rat her delegat es user aut hent icat ion t o t he securit y server. I n addit ion t o t he user regist ry, t he securit y server can m anage access cont rol rules for aut horizat ion and a t able for m apping user I Ds bet w een different securit y dom ains. For exam ple, when users need t o access a backend legacy syst em , t heir I nt ernet I Ds m ight be m apped t o I Ds for t he legacy syst em . On t he ot her hand, t he securit y Web services show n in Figure 5.21 address XML- and SOAP- level securit y issues. As described earlier, SOAP digit al signat ure and encrypt ion handlers are provided in t he form of Java classes and em bedded in t he Axis engine. How ever, t his configurat ion requires privat e keys t o be dist ribut ed t o t he original and all clone nodes.

        XKMS suggest s m anaging public and privat e keys in a single reposit ory and accessing t hat reposit ory via SOAP m essages. You can apply t his Web services approach t o t he signat ure and encrypt ion handlers. First , m anageabilit y of securit y handlers is im proved because t hey are sim ply invoked from various Axis nodes. Second, m anageabilit y of securit y inform at ion is im proved because it is prot ect ed in a secure dom ain. I n fut ure developm ent , a m ore com prehensive collect ion of securit y services, such as t im er and aut horizat ion handlers, m ight be specified and provided in addit ion t o signat ure and encrypt ion. Thus, som e of t he funct ions in t he securit y server could becom e securit y Web services.

      Summary

        This chapt er discussed how you can perform serious e- Business funct ions wit h Web services. Aft er reading t his chapt er, you know t hat t here are m any em erging st andards in t his area, w it h w hich you can bring Web services t o t he real w orld. Of course, it 's im port ant t o keep your eyes on st andardizat ion act ivit ies in W3C, OASI S , and t he Java Com m unit y Processes know n as Java Specificat ion Request s ( JSR) . How ever, it is ext rem ely hard t o follow all t he act ivit ies. One reasonable approach is t o clarify first w hat you w ant in your business and syst em s in order t o narrow dow n t he act ivit ies and st andards you m ust m onit or.

        You should now have a fairly solid pict ure of securit y st andards. Alt hough som e t echnologies are under developm ent , you can m ake your Web services secure t o som e ext ent w it h SSL, BASI C- AUTH, and digit al signat ures. Ot her t echnologies should be chosen aft er paying part icular at t ent ion t o how t hey have m at ured and how m uch you need t hem in your business. St andards in Ent erprise Applicat ion I nt egrat ion ( EAI ) are in som e sense m at ure because t hey are based on a long hist ory of syst em int egrat ion evolut ion including t ransact ions, reliable m essaging, dist ribut ed obj ect s, securit y, and so on. However, you m ust also know t hat im port ant concept s like t ransact ions and reliable m essaging cannot be applied t o B2B easily on t he I nt ernet . We are eagerly aw ait ing st andardizat ion effort s in t his area.

        Anot her issue addressed here w as how t o fit Web services t echnologies and st andards int o EAI environm ent s. For exam ple, BASI C- AUTH has been int egrat ed int o t he J2EE archit ect ure, so aut horizat ion on EJB obj ect s can be perform ed based on it . How ever, how do w e perform aut horizat ion on ordinary Java obj ect s? Can w e perform aut horizat ion if w e aut hent icat e a request or w it h a digit al signat ure? When adopt ing a Web services t echnology, you also have t o consider how it can be int egrat ed int o your exist ing EAI environm ent . We also review ed exam ples of core Web services. XKMS is t he best exam ple here. Because it is difficult t o access PKI , Web services for PKI m ust be appreciat ed. As we envisioned in Figure 5.21 , ot her securit y funct ions w ould be provided as Web services, such as signat ure and encrypt ion services. I n t he sam e m anner, work is underway on publishing syst em m anagem ent funct ions as Web services. Once such Web services are provided, cust om ers can underst and t he syst em st at us of t he service provider. This could be a good basis for QoS im provem ent in a decent ralized m anner.

        Resources

      • ASN.1" I nform at ion Technology—Abst ract Synt ax Not at ion One ( ASN.1) : Specificat ion of Basic Not at ion" ( I TU- T Recom m endat ion X.680, 1997) . I SO/ I EC 8824- 1: 1998.
      • Base64" Mult ipurpose I nt ernet Mail Ext ensions ( MI ME) Part One: Form at of I nt ernet

        Message Bodies" ( I ETF, Novem ber 1996) . Available at ht t p: / / w w w .iet f.org/ rfc/ rfc2045.t xt .

      • BASI C- AUTH—RFC 2617: " HTTP Aut hent icat ion: Basic and Digest Access Aut hent icat ion" ( I ETF, June 1999) . Available at ht t p: / / w w w .iet f.org/ rfc/ rfc2617.t xt .

        Canonical XML" Canonical XML Version 1.0" ( W3C, March 2001) . Available at ht t p: / / w w w .w 3.org/ TR/ 2001/ REC- xm l- c14n- 20010315 .

      • CRL" I nt ernet X.509 Public Key I nfrast ruct ure Cert ificat e and CRL Profile" ( I ETF, January 1999) . Available at ht t p: / / w w w .iet f.org/ rfc/ rfc2459.t xt .
      • ebXML TRP—Message Service Specificat ion ebXML Transport , Rout ing & Packaging Version 1.0 ( UN/ CEFACT and OASI S, May 2001) . Available at ht t p: / / w w w .ebxm l.org/ specs/ .
      • EJB—Ent erprise JavaBeans Specificat ion, Version 2.0 ( Sun Microsyst em s, August 2001) . Available at ht t p: / / j ava.sun.com / product s/ ej b/ .
      • HTTPR" A Prim er for HTTPR: An overview of t he Reliable HTTP Prot ocol" ( I BM, July 2001) . Available at ht t p: / / w w w - 106.ibm .com / developerw orks/ w ebservices/ library/ w s- pht t / .
      • I ETF—The I nt ernet Engineering Task Force. Available at ht t p: / / w w w .iet f.org/ .
      • J2EE—Java 2 Plat form Ent erprise Edit ion Specificat ion, v1.3 ( Sun Microsyst em s, August 2001) . Available at ht t p: / / j ava.sun.com / j 2ee/ .
      • J2EE Connect or—J2EE Connect or Archit ect ure Specificat ion, Version 1.0. ( Sun Microsyst em s, August 2001) . J2EE Connect or Specificat ion ( Sun Microsyst em s) . Available at ht t p: / / j ava.sun.com / j 2ee/ .
      • J2EE MGMT" JSR 77: J2EE Managem ent " ( JCP, Sept em ber 2001) . Available at ht t p: / / j cp.org/ j sr/ det ail/ 77.j sp .
      • JAAS—Java Aut hent icat ion and Aut horizat ion Service ( Sun Microsyst em s) . Available at ht t p: / / j ava.sun.com / product s/ j aas/ .
      • JAF—JavaBeans Act ivat ion Fram ew ork Specificat ion, Version 1.0a ( Sun Microsyst em s, May 1999) . Available at ht t p: / / j ava.sun.com / product s/ j avabeans/ glasgow / j af.ht m l .
      • JASPCFC—JSR 115: Java Aut horizat ion Service Provider Cont ract for Cont ainers ( JCP, April 2001) . Available at ht t p: / / j cp.org/ j sr/ det ail/ 115.j sp .

      • JavaMail—JavaMail 1.2 ( Sun Microsyst em s, Decem ber 2000) . Available at ht t p: / / j ava.sun.com / product s/ j avam ail/ .
      • JCE—Java Crypt ography Ext ension ( JCE) ( Sun Microsyst em s) . Available at ht t p: / / j ava.sun.com / product s/ j ce/ .
      • JMX—Java Managem ent Ext ensions I nst rum ent at ion and Agent Specificat ion, v1.0 ( Sun Microsyst em s, July 2000) . Available at ht t p: / / j ava.sun.com / product s/ JavaManagem ent / .
      • JNDI —Java Nam ing and Direct ory I nt erface 1.2 ( Sun Microsyst em s) . Available at ht t p: / / j ava.sun.com / product s/ j ndi/ .
      • JSP—JavaServer Pages Specificat ion Version 1.2 ( Sun Microsyst em s, Sept em ber 2001) . Available at ht t p: / / j ava.sun.com / product s/ j sp/ .
      • JSSE—Java Secure Socket Ext ension ( Sun Microsyst em s) . Available at ht t p: / / j ava.sun.com / product s/ j sse/ .
      • OASI S—Organizat ion for t he Advancem ent of St ruct ured I nform at ion St andards. Available at ht t p: / / w w w .oasis- open.org/ .
      • PKCS" Public- Key Crypt ography St andards" ( RSA Laborat ories) . Available at ht t p: / / w w w .rsalabs.com / pkcs/ .
      • PKI —I nt ernet X.509 Public Key I nfrast ruct ure Cert ificat e Managem ent Prot ocols ( I ETF, March 1999) . Available at ht t p: / / w w w .iet f.org/ rfc/ rfc2510.t xt .
      • RMI - I I OP" Rem ot e Met hod I nvocat ion ( RMI ) over I nt ernet I nt er- Orb Prot ocol ( I I OP) " ( Sun Microsyst em s) . Available at ht t p: / / j ava.sun.com / product s/ rm i- iiop/ .
      • SAML" Securit y Assert ion Markup Language" ( OASI S) . Available at ht t p: / / w w w .oasis- open.org/ com m it t ees/ securit y/ .
      • Servlet —Java Servlet Specificat ion Version 2.3 ( Sun Microsyst em s, Sept em ber 2001) . Available at ht t p: / / j ava.sun.com / product s/ servlet / .
      • SNMP" I nt roduct ion t o Version 3 of t he I nt ernet - st andard Net w ork Managem ent Fram ew ork" ( I ETF, April 1999) . Available at ht t p: / / w w w .iet f.org/ rfc/ rfc2570.t xt .
      • SOAP Signat ure" SOAP Securit y Ext ensions: Digit al Signat ure" ( W3C, February 2001) . Available at ht t p: / / w w w .w 3.org/ TR/ SOAP- dsig/ .
      • SSL—The SSL Prot ocol Version 3.0 ( Net scape Com m unicat ions, Novem ber 1996) . Available at ht t p: / / hom e.net scape.com / eng/ ssl3/ draft 302.t xt .
      • TI P—Transact ion I nt ernet Prot ocol Version 3.0 ( W3C, July 1998) . Available at ht t p: / / w w w .iet f.org/ rfc/ rfc2371.t xt .
      • TLS—RFC 2246: " The TLS Prot ocol Version 1.0" ( I ETF, January 1999) . Available at ht t p: / / w w w .iet f.org/ rfc/ rfc2246.t xt .
      • VeriSign—VeriSign, I nc. Available at ht t p: / / w w w .verisign.com / .
      • WSTK—I BM Web Services Toolkit 2.4 ( I BM, Sept em ber 2001) . Available at ht t p: / / w w w .alphaw orks.ibm .com / t ech/ w ebservicest oolkit .
      • X.500 Dist inguished Nam e" I nform at ion t echnology—Open Syst em s I nt erconnect ion—

        The Direct ory: Overview of Concept s, Models and Services" ( I TU- T Recom m endat ion X.500, 1997) . I SO/ I EC 9594- 1: 1998.

      • XAML—Transact ion Aut horit y Markup Language. Available at ht t p: / / w w w .xam l.org/ .
      • XKMS—XML Key Managem ent Specificat ion ( W3C, March 2001) . Available at ht t p: / / w w w .w 3.org/ TR/ xkm s/ .
      • XML Encrypt ion" XML Encrypt ion Synt ax and Processing WG Working Draft " ( W3C, June 2001) . Available at ht t p: / / w w w .w 3.org/ TR/ 2001/ WD- xm lenc- core- 20010626/ .
      • XML Signat ure" XML- Signat ure Synt ax and Processing" ( W3C, August 2001) . Available at ht t p: / / w w w .w 3.org/ TR/ 2001/ PR- xm ldsig- core- 20010820/ .

      • Well Defined Service • History of IDLs • Web Services Definition Language (WSDL) • WSDL and Java • Future Service Description Efforts
      • To t his point , w e have described XML and posit ioned it as t he underpinnings of t he SOAP m essaging prot ocol. Given t hat XML is a self- describing, hum an- readable represent at ion of dat a, isn't t hat enough t o m ake a SOAP m essage also self- describing? I f so, t hen w hy do w e need an approach for service descript ions? We'll answ er t his quest ion in t his chapt er.

        Why Service Descriptions?

        Let 's look at t his problem from t he service request or's perspect ive. A cust om er of

        POSubmission

        Skat esTow n w ant s t o invoke t he service. How does t he cust om er know what kind of m essage t o send? Sure, t hey know t o use SOAP, but SOAP is t he form at of t he envelope; SOAP it self does not clarify w hat m essage t o act ually put int o t he envelope. The cust om er needs t o underst and w hat XML t o put int o t he body of t he SOAP envelope, what form at t he response m essage m ight com e in, and whet her a response is t o be expect ed. The cust om er also needs t o know w hat m essaging prot ocol t o use t o send t he m essage and w hat net w ork address t o send t he m essage t o. One w ay for t he cust om er t o det erm ine w hat XML t o send is t o exam ine a t ext ual descript ion of t he service published on t he Skat esTow n Web sit e. Alt hough doing so is sim ple, it does allow som e pot ent ial problem s. The t ext ual descript ion m ight not be t erribly precise and can allow t he cust om er's developers t o m isint erpret t he specificat ion. This result s in t oo m uch t rial and error on t he cust om er's part t o get t he m essage form at right .

        Anot her approach is t o include sam ple m essage form at s in t he docum ent at ion. The developer can t hen observe t he sam ples and m odify t hem t o suit his/ her com pany's needs. This approach is slight ly bet t er in t hat t he developer can get t he m essage form at developm ent . I f each Web service required analysis, design, and coding t o invoke, t he Web services approach w ould quickly pass int o t he dust bin of t echnology hist ory. To m ake t he j ob of invoking Web services easier for t he service request or, w e need a form al m echanism t o describe t he service. This form al approach provides unam biguous specificat ion of w hat t he service request or needs t o do in order t o invoke t he Web service. As a result of t he form alit y of t he service descript ion, soft w are t ool developers can provide t ooling t o aut om at e t he developm ent of code t o invoke Web services.

      Role of Service Description in a Service-Oriented Architecture

        Service descript ion is key w it hin a service- orient ed archit ect ure ( SOA) . A service descript ion is involved in each of t he t hree operat ions of SOA: publish, find, and bind. Recall t he SOA approach, depict ed in Figure 6.1 . The service provider publishes a service descript ion t o one or m ore service regist ries. The descript ion of t he service is published in service regist ries, not t he act ual code for t he Web service it self. The service provider uses a service descript ion t o t ell t he service request or everyt hing it needs t o know in order t o properly underst and how t o invoke t he Web service.

      Figure 6.1. Service-oriented architecture.

        Sim ilarly, t he service descript ion is cent ral t o t he find operat ion. The service request or uses aspect s of t he service descript ion; for exam ple, you m ight be looking for a Web service t hat im plem ent s a part icular purchase order st andard, as t he basis for t he find query t o a service regist ry. ( I n Chapt er 7 , " Discovering Web Services," we discuss service regist ries at lengt h and describe t he find and publish operat ions in m ore det ail.) The result of t he find operat ion is ult im at ely a service descript ion m ade available t o t he service request or.

        Why does t he service provider publish a service descript ion? To com m unicat e t o service request ors how t o invoke a Web service. Why does a service request or w ant t o get hold of a service descript ion? Because it describes exact ly w hat needs t o happen at t he bind m essage form at needs t o be delivered t o w hat net w ork address in order t o invoke a Web service.

      Well Defined Service

        What m akes a good service descript ion? What aspect s of t he Web service m ust be described in order for t he Web service t o be considered sufficient ly defined? Subm issions t o t he W3C ( ht t p: / / w w w .w 3.org/ 2001/ 03/ WSWS- popa/ paper51 ) have described a st ack of Web services descript ion st andards t hat describe various aspect s of a Web service. Det ails based on t his st ack are depict ed in Figure 6.2 .

      Figure 6.2. The service description stack.

        The layers of t he service descript ion st ack can be divided int o t w o broad groups: funct ional layers and non- funct ional layers. The bot t om t hree layers are funct ional in nat ure, in t hat t hey describe det ails of how t he Web service is invoked, w here it is t hat t hey do not direct ly inform t he m echanism s of invocat ion, but rat her provide ot her det ails t hat influence w het her a service request or w ould choose t o invoke t he Web service.

      Functional Description

        The bot t om , funct ional layers of t he service descript ion st ack define t he int erface definit ion language ( I DL) equivalent of t he service descript ion. The int erface descript ion language layers for Web service descript ion serve t he sam e funct ion as I DLs in ot her dist ribut ed com put ing approaches ( see t he sect ion " Hist ory of I DLs " ) . Let 's exam ine t he relat ionships bet w een t hese layers. Fundam ent ally, it is t he funct ional descript ion of t he Web service t hat det erm ines w hat t he service request or needs t o do in order t o invoke a Web service. Like m ost t hings in Web services, XML is at t he basis of service descript ion. XML is t he t ype definit ion t hat is exploit ed, by default , in t he service im plem ent at ion and service int erface definit ion layers of t he st ack. As w e saw in Chapt er 3 , " Sim ple Obj ect Access Prot ocol ( SOAP) ," XML describes t he dat at ypes for t he elem ent s t hat flow w it hin t he SOAP m essage, and in part icular, w it hin t he SOAP payload, w hich need t o be form at t ed by t he service request or and int erpret ed by t he service provider. Much of t he effort w it hin a Web services infrast ruct ure goes int o properly encoding and decoding XML elem ent s t o/ from nat ive program m ing language obj ect s. The service im plem ent at ion definit ion and t he service int erface definit ion bot h use t he Web Services Descript ion Language ( WSDL) st andard. We w ill describe t he WSDL language in m ore det ail lat er in t his chapt er in t he " Web Services Definit ion Language ( WSDL) " sect ion. The service im plem ent at ion definit ion describes w here t he service is locat ed, or m ore precisely, t o w hich net w ork address t he m essage m ust be sent in order t o invoke t he Web service. The service int erface definit ion describes exact ly w hat m essage needs t o be sent and how t o use t he various I nt ernet st andard m essaging prot ocols and encoding schem es in order t o form at t he m essage in a m anner accept able t o t he service provider.

      Non-Functional Description

        The I DL level descript ion em bodied by t he funct ional descript ion layers of t he service descript ion st ack is very im port ant , but t here is m ore t hat should be described about a Web service. What do w e m ean by t he t erm non- funct ional descript ion? Basically, t hese layers can be charact erized in cont rast t o t he funct ional layers. Whereas t he funct ional layers describe w here t o send t he m essage, w hat t he m essage synt ax needs t o look like, and how t o use t he prot ocols and encoding schem es, t he non- funct ional descript ion addresses w hy a service request or should invoke t he Web service—for exam ple, w hat business funct ion t he Web service addresses and how it fit s int o a broader business process. A non- funct ional descript ion also gives m ore det ails about w ho t he service provider is. For exam ple, does t he service provider provide audit ing and ensure privacy? You can use t he Web Services Endpoint Language ( WSEL) t o describe t he environm ent or endpoint w hich host s t he Web service. Charact erist ics of t he host ing environm ent could include t he securit y policy in place at t he service provider, w hat levels of qualit y of service are available t o support Web service invocat ion, w hat kind of privacy policy is enforced by t he service provider, and so on. At one level, you can t hink of t he non- funct ional descript ion layers as descript ions of t he Web service t hat do not affect t he on t he synt ax of t he m essage, relat ed t o ort hogonal ext ensions of t he m essage ( for exam ple, param et ers relat ed t o a required securit y prot ocol) , but t he core shape of t he payload of t he m essage is derived from t he funct ional descript ion. At t his point , WSEL is not a concret e proposal, but rat her a vague not ion of requirem ent expressed w it hin t he Web services com m unit y. As w e w ill exam ine in Chapt er 7 , t he UDDI service regist ry also has im pact on t he cert ain non- funct ional aspect s of t he service descript ion. I n part icular, t he t axonom y schem e support ed by UDDI is anot her m echanism by w hich a service provider can describe w hat kind of service is being provided and w hat business funct ion it support s.

      Aggregation/Orchestration Description

        The Web Services Flow Language ( WSFL) is one t echnique t o describe how a collect ion of Web services can be arranged or orchest rat ed int o a higher level business process. WSFL addresses it em s like t he proper order in w hich t o invoke a set of Web services.

        Essent ially, WSFL describes how t hese individual Web services fit int o a bigger pict ure, such as a business process or a m ult i- part y, m ult i- operat ion long running t ransact ion. Anot her approach, developed by Microsoft , is t he XLANG language, part of t he .NET init iat ive ( ht t p: / / w w w .got dot net .com / t eam / xm l_w sspecs/ xlang- c/ default .ht m ) . A t hird approach, Business Process Markup, sponsored by a consort ium ( BPMI ,

        ht t p: / / w w w .bpm i.org/ bpm l- spec.esp ) also exist s in t he m arket place. To dat e, none of t hese approaches has em erged as a dom inant st andard in t his space.

      Stack Summary

        Current ly, m ost of t he w ork has been devot ed t o est ablishing and evolving t he I DL- level of t he service descript ion st ack. The WSDL approach has only recent ly been est ablished, and it cont inues t o gain adopt ion w it h bet t er runt im e support and t ooling support from m ult iple vendors and use by developers.

        The st andards relat ed t o t he non- funct ional descript ion are st ill in t heir infancy. WSEL is only briefly m ent ioned as part of t he WSFL specificat ion. There is no ot her publicly available inform at ion on WSEL. The sam e is t rue for aggregat ion/ orchest rat ion; WSFL it self rem ains as a proposal in t he area, and has yet t o undergo t he rigors of subm ission and m odificat ion t hrough an open st andards body such as t he W3C. We expect t hat st andards in t hese layers of t he service descript ion st ack w ill cont inue t o evolve and m at ure. To sum m arize, a Web service is described using a com binat ion of t echniques. A Web service's descript ion is used t o unam biguously answ er several quest ions about t he Web service. These quest ions and how t hey are addressed are sum m arized in Table 6.1 .

      Table 6.1. Roles of Each Layer of the Service Description Stack

      Question Where Addressed

        Who Non-functional description What Service interface Where Service implementation Why Non-functional description How Service interface

        For t he rem ainder of t his chapt er, let 's focus on t he use of t he WSDL st andard as t he funct ional descript ion of a Web service. Tow ard t he end of t he chapt er, in t he " Web

        Services Endpoint Language ( WSEL) " sect ion, w e w ill briefly revisit t he non- funct ional layers of t he service descript ion st ack.

      History of IDLs

        Before w e dive int o t he WSDL discussion, a lit t le background m ight be helpful. Every dist ribut ed com put ing approach has a m echanism for describing com ponent s. Let 's exam ine a brief hist ory of I DLs. I nt erface definit ion languages ( I DLs) have a long hist ory in dist ribut ed com put ing. The m aj or use of I DL cam e as part of t he Open Soft w are Foundat ion's Dist ribut ed Com put ing Environm ent ( DCE) in it s specificat ion on RPC in 1994. DCE I DL w as a breakt hrough concept t hat quickly spread t o ot her dist ribut ed com put ing init iat ives, such as Obj ect Managem ent Group's ( OMG) CORBA I DL and Microsoft 's COM I DL and COM ODL ( Obj ect Definit ion Language) . As w it h m ost such t echnologies, t he various flavors of I DL are slight ly different and, t herefore, m ore or less incom pat ible. All hopes are now on WSDL t o bring unit y back t o t his crucial area of dist ribut ed com put ing, at least in t he area of Web services.

        Most people used t o developing sim ple soft ware frown when t hey first hear about I DL. They say, " Why bot her defining t he int erfaces of any soft w are operat ions? Just get a point er/ reference t o an obj ect or a funct ion and m ake t he call." The reason is t hat , if a soft w are syst em has even t he slight est am ount of het erogeneit y, t his sim ple approach w on't w ork. Let 's consider som e possibilit ies:

        It can be difficult to obtain a reference to the target that • implements the operation you want to call. For example, the target

      could be in another executable on the same machine or on another

      machine.

        The function/method calling convention varies significantly between • programming languages or even based on compilation parameters, such as the level of optimization. If even the slightest difference exists between the invoker's and the target's environments, it is likely that the call will fail. Data encoding rules vary considerably between programming languages • (strings in Pascal are length-prefixed while they are null-terminated in C/C++) and platforms (numbers can be represented in little- vs. big-endian format).

        The best w ay t o approach t hese problem s, given t hat soft w are im plem ent at ions and deploym ent s are, and w ill forever be, highly het erogeneous, is t o agree on a bridging st rat egy. This st rat egy est ablishes com m on ground in t he m iddle ( t he bridge) w it hout w orrying about how t he roads at t he endpoint s are const ruct ed. I n dist ribut ed com put ing, a bridging st rat egy involves t w o part s:

        1. Agreeing on how to make an invocation: the mechanics of naming, activation, data encoding, error handling, and so on. This is what

      distributed computing standards such as DCE, CORBA, and COM do.

        2. Specifying what to call: the operation names, their signatures, return types, and any exceptions that they might generate. This is the job of IDL.

        I n a t ypical dist ribut ed com put ing archit ect ure, a t ool called an I DL com piler com bines t o code- generat e t he pieces t hat m ake t he bridge w ork. The client t hat w ant s t o invoke operat ions w ill use a client proxy ( som et im es called a client st ub) . The proxy has t he sam e int erface as t he operat ion provider. I t can be used as a local obj ect on t he client . The proxy im plem ent at ion know s how t o encode and m arshal t he invocat ion dat a t o t he operat ion provider and how t o capt ure t he operat ion result and ret urn it t o t he client . The operat ion provider w ill w rap it s im plem ent at ion inside a skelet on ( som et im es called a server st ub) im plem ent at ion t hat is code- generat ed by t he I DL com piler. The skelet on know s how t o capt ure t he dat a sent by t he proxy and pass it t o t he act ual im plem ent at ion. I t also know s how t o package t he result of operat ions and send it back t o t he client . Proxies and skelet ons are helped by a lot of sophist icat ed dist ribut ed com put ing m iddlew are. A key part of t he st ory is t hat proxies and skelet ons need not be generat ed by t he sam e I DL com pilers, as long as t hese com pilers are follow ing t he sam e dist ribut ed com put ing convent ions. This is t he pow er of I DL—it describes everyt hing t hat is necessary t o m ake invocat ion possible in a dist ribut ed environm ent . DCE I DL specified flat funct ion int erfaces. There was no not ion of obj ect inst ance cont ext w hen m aking calls. CORBA I DL changed t hat by adding m any im port ant ext ensions t o

        I DL. CORBA I DL is t he de fact o I DL st andard on non- Microsoft environm ent s. I t is also st andardized int ernat ionally as I SO/ I EC 14750. CORBA I DL is purely declarat ive; it provides no im plem ent at ion det ails. I t defines a rem ot e obj ect API concisely ( t he spec is less t han 40 pages long) and covers key issues such as nam ing, com plex t ype definit ion, in/ out / in- out param et ers and except ions. The synt ax is rem iniscent of C+ + w it h som e addit ional keyw ords t o cover addit ional concept s. The follow ing is a brief exam ple of a CORBA I DL specificat ion for an account and an int erest account :

        modul e Account s { i nt erf ace Account { readonl y at t ri but e st ri ng number; readonl y at t ri but e f l oat bal ance; except i on I nsuf f uci ent Funds ( st ri ng det ai l ) ; f l oat debi t ( i n f l oat amount ) rai ses ( I nsuf f i ci ent Funds) ; f l oat credi t ( i n f l oat amount ) ; } i nt erf ace I nt erest Account : Account { readonl y at t ri but e f l oat rat e; } }

        The inform at ion in t he I DL file is self- describing and very readable. You can also see t hat

        I DL support s t he not ion of inherit ance, w hich m akes it convenient t o describe obj ect - orient ed dist ribut ed syst em s. I n fact , CORBA I DL even support s t he not ion of m ult iple

        MyPetTurtle Pet Animal int erface inherit ance as in deriving from bot h and .

        I n a CORBA- enabled environm ent , t he previous I DL above can be used t o invoke t he CORBA obj ect via dynam ic invocat ion from a script ing language, generat e proxies for client access t o t he obj ect , generat e skelet ons for t he act ual account im plem ent at ion t o be plugged int o t he CORBA m iddlew are, regardless of it s act ual im plem ent at ion language, and st ore inform at ion about t he im plem ent at ion in an int erface reposit ory ( a cent ral st ore of m et adat a about CORBA com ponent s' int erfaces) . For various hist orical reasons, Microsoft used t o have t w o versions of I DL. COM I DL w as closely based on DCE I DL, alt hough it lacked som e of t he advanced feat ures support ed by COM. COM ODL had support for t hese feat ures but w as incom pat ible w it h COM I DL. Clearly, t hat w as an odd st at e of affairs, and Microsoft fixed t hings a few years ago w hen it m erged t he t w o I DL languages. The follow ing exam ple show s a som ew hat sim plified

        Account InterestAccount

        version of t he and int erfaces in Microsoft 's I DL:

        [ obj ect , uui d( E9FF28F4- B79F- 469A- B2D9- 477FF19873A0) , dual ] i nt erf ace I Account : I Di spat ch { [ propget , i d( 1) ] HRESULT bal ance( [ out , ret val ] f l oat *pVal ) ; [ i d( 2) ] HRESULT debi t ( i n f l oat amount , [ out , ret val ] f l oat *pVal ) ; [ i d( 3) ] HRESULT credi t ( i n f l oat amount , [ out , ret val ] f l oat *pVal ) ; } ; [ obj ect , uui d( 5B93E296- 4FF5- 4A6C- A64E- 51A7B6C20B6C) , dual ] i nt erf ace I I nt erest Account : I Account { [ propget , i d( 1) ] HRESULT rat e( [ out , ret val ] f l oat *pVal ) ; } ; [ uui d( 22AE9E3F- DC3C- 478E- BC00- 13A735D57167) , versi on( 1. 0) ] l i brary Account Li b { [ uui d( 0D1630F9- C4E0- 46A6- BCDF- A9B752DBDD94) ] cocl ass Account { [ def aul t ] i nt erf ace I Account ; } ; [ uui d( F949F2A1- 18C1- 4010- A062- 6B8DF49D4BCE) ] cocl ass I nt erest Account { [ def aul t ] i nt erf ace I I nt erest Account ; } ; } ;

        Needless t o say, Microsoft 's ODL is not synt ax- com pat ible, or even concept - com pat ible,

        [ name(value), ... ]

        At t ribut es prefix elem ent s using t he form at . The convent ion is t o prefix int erface nam es w it h a capit al I . To support dynam ic invocat ion from script ing

        

      IDispatch

        languages, int erfaces m ust inherit from and m et hods need t o ident ify t heir

        

      id

        locat ion in dynam ic dispat ch t ables w it h t he at t ribut e. COM does not support except ions. Error inform at ion is com m unicat ed via t he ret urn value of a m et hod, w hich

        HRESULT

        m ust be an ( an int eger w it h w ell- defined error codes) . Therefore, t he real ret urn

        [out, retval]

        value of a m et hod is ident ified as in t he I DL. Finally, COM support s a t rue

        IAccount

        IInterestAccount

        separat ion of int erfaces ( and ) from im plem ent at ions

        Account InterestAccount coclass

        ( and ) . The lat t er are ident ified by t he keyword in t he account library. COM uses UUI Ds exclusively t o regist er int erfaces and im plem ent at ion classes under unique nam es. Apart from t hese differences, COM obj ect s can be used exact ly like CORBA obj ect s.

        Program m ers w orking w it h m odern languages, such as Java, C# , and any ot her .NET Com m on Language Runt im e ( CLR) languages have t he luxury of being able t o engage in dist ribut ed com put ing applicat ions t ypically w it hout having t o w orry m uch about I DL. Has

        I DL becom e irrelevant in t hese cases? Not at all! I DL is not present on t he surface, but I DL concept s are w orking behind t he scenes. Bot h Java and t he CLR languages are fully int rospect able. This m eans t hat a com piled language com ponent carries com plet e m et adat a about it self, such as inform at ion about it s parent class, propert ies, m et hods, and any support ed int erfaces. This inform at ion is sufficient t o replace t he need for an explicit I DL descript ion of t he com ponent . That is w hy, for exam ple, Java developers can invoke t he RMI com piler direct ly on t heir obj ect w it hout having t o generat e I DL first . How ever, in t he cases w here t hese languages need t o int eroperat e w it h com ponent s built using ot her program m ing languages, t here is no subst it ut e for I DL. I n short , separat ing int erfaces from im plem ent at ions is t he only guarant eed m echanism for ensuring t he pot ent ial for int eroperabilit y across program m ing languages, plat form s, m achines, address spaces, m em ory m odels and obj ect versions. On t he Web, w here het erogeneit y is t he rule, t his is m ore im port ant t han ever.

      Web Services Definition Language (WSDL)

        The Web Services Definit ion Language ( WSDL) is a proposed st andard t o describe t he t echnical invocat ion synt ax of a Web service. WSDL w as subm it t ed t o t he W3C for st andardizat ion by I BM, Microsoft , and ot hers in Sept em ber 2000. The current version of t he specificat ion, WSDL 1.1, is available at ht t p: / / w w w .w 3.org/ TR/ w sdl .

        A WSDL service descript ion is an XML docum ent conform ant t o t he WSDL schem a definit ion. As w e assert ed earlier, a WSDL docum ent is not a com plet e service descript ion, but rat her it covers t he low er levels of t he service descript ion st ack—t he raw t echnical descript ion of t he service's int erface. WSDL is t he I DL for Web services. Essent ially, a WSDL descript ion describes t hree fundam ent al propert ies of a Web service:

        What a service does—the operations (methods) the service provides • How a service is accessed—details of the data formats and protocols

      • necessary to access the service's operations Where a service is located—details of the protocol-specific network • address, such as a URL WSDL Information Model
      The WSDL inform at ion m odel t akes full advant age of t he separat ion bet w een abst ract specificat ions and concret e im plem ent at ions of t hese specificat ions. This reflect s t he split bet w een service int erface definit ion ( abst ract int erface) and service im plem ent at ion definit ion ( concret e endpoint ) discussed previously in t he cont ext of t he service descript ion st ack. The descript ion of t he endpoint 's capabilit ies is t he abst ract int erface specificat ion represent ed in WSDL by a port Type . A binding m echanism , represent ed in

        binding

        WSDL by a elem ent , is used t o m ap t he abst ract definit ion of t he Web service t o a specific im plem ent at ion using a part icular m essaging prot ocol, dat a encoding m odel, and underlying com m unicat ion prot ocol. When t he binding is com bined w it h an address w here t he im plem ent at ion can be accessed, t he abst ract endpoint has becom e a concret e endpoint t hat service request ors can invoke. This com binat ion is represent ed by a

        port WSDL elem ent .

        An abst ract int erface can support any num ber of operat ions . An operat ion is defined by t he set of m essages t hat define it s int eract ion pat t ern. For t he abst ract concept s of m essage and operat ion, concret e count erpart s are specified

        binding in t he elem ent .

        Like all good applicat ions of XML, t he WSDL schem a defines several high level or m aj or elem ent s in t he language. Let 's t ake a look at Web service descript ion in t erm s of t he m aj or elem ent s in WSDL:

      • portType

        — A Web service's abst ract int erface definit ion ( t hink Java int erface

        operation

        definit ion) w here each child elem ent defines an abst ract m et hod signat ure.

      • message

        — Defines a set of param et ers referred t o by t he m et hod signat ures or

        part

        operat ions. A m essage can be furt her decom posed int o s ( t hink det ailed m et hod param et er form at definit ions) .

      • types

        — Defines t he collect ion of all t he dat a t ypes used in t he Web service as referenced by various m essage part elem ent s ( t hink base dat a t ypes; t hink XML) .

      • binding

        — Cont ains det ails of how t he elem ent s in an abst ract int erface

        portType

        ( ) are convert ed int o a concret e represent at ion in a part icular com binat ion of dat a form at s and prot ocols ( t hink encoding schem es; t hink SOAP over HTTP) .

      • port

        — Expresses how a binding is deployed at a part icular net w ork endpoint ( t hink det ails about a part icular server on a part icular net w ork locat ion; t hink place w here you specify HTTP URL) .

      • service

        — A poorly nam ed elem ent . A nam ed collect ion of port s ( t hink arbit rary bag of Web services, for exam ple, t he port s associat ed w it h st eps in a m ult ist ep business t ransact ion) .

        portType message type

        So t he ( w it h det ails from t he and elem ent s) describes t he w hat

        binding port service

        of t he Web service. The elem ent describes t he how , and t he and elem ent s describe t he w here of t he Web service.

      Figure 6.3 show s t he relat ionship bet w een t hese elem ent s in WSDL.Figure 6.3. The WSDL information model. The figure show s one possible view of t he organizat ion of t he WSDL inform at ion m odel. You can see a clear relat ionship bet w een t he abst ract and concret e not ions of m essage

        

      portType binding

        and operat ion as cont ained in t he and elem ent s. The w ords in bold on t he diagram signify t he t erm s from t he WSDL specificat ion. The elem ent nam es used in WSDL are som ew hat confusing because no consist ent nam ing convent ion allow s you t o dist inguish bet w een abst ract and concret e concept s. You sim ply have t o m em orize w hich elem ent s represent abst ract concept s and w hich elem ent s represent concret e concept s. At first glance, WSDL seem s t o be quit e com plicat ed. Part of t his appearance is due t o t he fact oring chosen by t he WSDL aut hors. This com plexit y feels a lot like t he com plexit y observed w it h a highly norm alized relat ional dat a m odel. Alt hough t he sam e inform at ion can be m ore succinct ly expressed, t he flexibilit y t hat result s from t he fact oring in WSDL is occasionally quit e necessary. So, j ust as you m ight have learned t o cope wit h underst anding highly norm alized relat ional m odels, pract ice w it h reading WSDL docum ent s w ill help you t o focus on t he im port ant aspect s of a Web service descript ion.

      Origin of WSDL

        WSDL w as not t he first I DL language for Web services. I BM had developed a language called Net w ork Accessible Service Specificat ion Language ( NASSL) t o furt her early int ernal adopt ion of SOAP. Meanw hile, Microsoft had developed SOAP Cont ract Language ( SCL) , w hich it self w as an evolut ion of Microsoft 's earlier at t em pt at a SOAP I DL called Service Definit ion Language.

        I BM and Microsoft realized t hat having com pet ing I DLs in t he SOAP space w ould hinder rapid adopt ion of Web services. WSDL is t he result of hard w ork and com prom ise in m erging NASSL and SCL. As a result of t his m erger, a single

        To m ake WSDL a st andard, I BM, Microsoft , and several ot her com panies brought it forw ard t o t he W3C for st andardizat ion.

      Elements of the WSDL Language

        Let 's t ake a closer look at t he elem ent s of a WSDL descript ion. Alt hough w e exam ine t hese elem ent s in det ail, t he good new s is t hat you don't have t o becom e an expert in WSDL. The soft w are indust ry cont inues t o churn out t ools t o generat e WSDL from exist ing I T asset s like COM obj ect s and Ent erprise Java Beans ( EJBs) and t o generat e client - side st ubs or proxies ( access m echanism helper classes) from WSDL on t he service request or side t o ease t he burden of invoking Web services. Lat er in t his chapt er, w e w ill t ake a closer look at t he WSDL t ooling available in Axis. How ever, by review ing WSDL, you w ill get a good background in case t he t ools don't generat e exact ly t he WSDL or Java t o fit your part icular circum st ances. None of t he t ools t o dat e support t he ent ire breadt h of WSDL feat ures. For som e t im e t o com e, WSDL descript ions w ill need t o be hand craft ed, and client and Web service im plem ent at ion code w ill have t o be m anually developed. The best w ay t o learn WSDL is t o exam ine a collect ion of WSDL docum ent s. An excellent regist ry of WSDL docum ent s can be found at t he salcent ral Web services brokerage ( ht t p: / / w w w .salcent ral.com ) or t he xm et hods Web sit e ( w w w .xm et hods.net ) . Go t o eit her of t hese sit es and brow se t he collect ion of WSDL docum ent s found t here. Aft er a lit t le pract ice, reading a WSDL docum ent w ill becom e as fam iliar as reading Java code. So, w hat does a WSDL descript ion look like? Let 's discuss t he WSDL language in t he cont ext of t w o WSDL exam ples. I n t he follow ing sect ions, w e w ill discuss how t he various elem ent s of t he WSDL language are used t o describe t w o of Skat esTow n's Web services. Example WSDL Documents

        priceCheck

        We w ill exam ine t he WSDL descript ion for t he ( relat ively sim ple) service

        priceCheck

        provided by Skat esTow n. The service w as added by Al Rosen in response t o

        inventoryCheck

        grow ing dem and from cust om ers t o ext end t he Web service t o include price inform at ion as w ell as availabilit y. You w ill see in Chapt er 7 how t his service prepares Skat esTow n t o part icipat e in dynam ic e- m arket places.

        priceCheck inventoryCheck

        The Web service is an ext ension of t he Web service, allow ing a request or t o det erm ine t he price of one of Skat esTow n's product s. The response is a price and t he num ber of unit s of t hat it em current ly available from invent ory.

        priceCheck The ent ire WSDL docum ent is shown in List ing 6.1 .

        Listing 6.1 The WSDL Document

        priceCheck <?xml versi on="1. 0"?> <def i ni t i ons name="Pri ceCheck" t arget Namespace="ht t p: //www. skat est own. com/servi ces/Pri ceCheck" xmlns: pc="ht t p: //www. skat est own. com/servi ces/Pri ceCheck" xmlns: avai l ="ht t p: //www. skat est own. com/ns/avai l abi l i t y" xmlns: xsd="ht t p: //www. w3. org/2001/XMLSchema" xmlns: soap="ht t p: //schemas. xmlsoap. org/wsdl /soap/" xmlns="ht t p: //schemas. xmlsoap. org/wsdl /"> <! - - Type def i ni t i ons - - > <t ypes> xmlns: xsd="ht t p: //www. w3. org/2001/XMLSchema"> <xsd: compl exType name="avai l abi l i t yType"> <xsd: sequence> <xsd: el ement name="sku" t ype="xsd: st ri ng"/> <xsd: el ement name="pri ce" t ype="xsd: doubl e"/>

      <xsd: el ement name="quant i t yAvai l abl e" t ype="xsd: i nt eger"/>

      </xsd: sequence> </xsd: compl exType> </xsd: schema> </t ypes> <! - - Message def i ni t i ons - - > <! - - A Pri ceCheckRequest i s si mpl y an i t em code ( sku) - - > <message name="Pri ceCheckRequest "> <part name="sku" t ype="xsd: st ri ng"/> </message>

      <! - - A Pri ceCheckResponse consi st s of an avai l abi l i t y st ruct ure, - - >

      <! - - def i ned above. - - > <message name="Pri ceCheckResponse"> <part name="resul t " t ype="avai l : avai l abi l i t yType"/> </message> <! - - Port t ype def i ni t i ons - - > <port Type name="Pri ceCheckPort Type"> <operat i on name="checkPri ce"> <i nput message="pc: Pri ceCheckRequest "/> <out put message="pc: Pri ceCheckResponse"/> </operat i on> </port Type> <! - - Bi ndi ng def i ni t i ons - - > <bi ndi ng name="Pri ceCheckSOAPBi ndi ng" t ype="pc: Pri ceCheckPort Type"> <soap: bi ndi ng st yl e="rpc" t ransport ="ht t p: //schemas. xmlsoap. org/soap/ht t p"/> <operat i on name="checkPri ce"> <soap: operat i on soapAct i on=""/> <i nput > <soap: body use="encoded" namespace=

      "ht t p: //www. skat est own. com/servi ces/Pri ceCheck"

      encodi ngSt yl e= "ht t p: //schemas. xmlsoap. org/soap/encodi ng/"/> </i nput > <out put > <soap: body use="encoded" namespace=

      "ht t p: //www. skat est own. com/servi ces/Pri ceCheck"

        "ht t p: //schemas. xmlsoap. org/soap/encodi ng/"/> </out put > </operat i on> </bi ndi ng> <! - - Servi ce def i ni t i on - - > <servi ce name="Pri ceCheckServi ce"> <port name="Pri ceCheck" bi ndi ng="pc: Pri ceCheckSOAPBi ndi ng"> <soap: address l ocat i on= "ht t p: //l ocal host : 8080/axi s/servi ces/Pri ceCheck"/> </port > </servi ce> </def i ni t i ons>

        This WSDL docum ent w ill com e up again in Chapt er 7 when we discuss how WSDL docum ent s are published and found in a UDDI regist ry. The second exam ple w oven int o t he next sect ions illust rat es m ore sophist icat ed uses of WSDL ( but by no m eans is it t he m ost com plicat ed use) . We have included t he ent ire WSDL file in List ing 6.2 , but don't panic; w e explain t he business purpose of t his Web service and each part of t he WSDL in subsequent paragraphs. For now , j ust t ake a quick glance at it , and let t he explanat ions clarify any quest ions. Refer back t o t his list ing frequent ly. Listing 6.2 The WSDL Document

        StockAvailableNotification <?xml versi on="1. 0" ?> <def i ni t i ons name="St ockAvai l abl eNot i f i cat i on" t arget Namespace= "ht t p: //www. skat est own. com/servi ces/St ockAvai l abl eNot i f i cat i on" xmlns: xsd="ht t p: //www. w3. org/2000/10/XMLSchema" xmlns: reg="ht t p: //www. skat est own. com/ns/regi st rat i onRequest " xmlns: soap="ht t p: //schemas. xmlsoap. org/wsdl /soap/" xmlns: soapenc="ht t p: //schemas. xmlsoap. org/soap/encodi ng/" xmlns="ht t p: //schemas. xmlsoap. org/wsdl /"> <! - - Type def i ni t i ons f rom t he regi st rat i on schema- - > <t ypes> <xsd: schema t arget Namespace= "ht t p: //www. skat est own. com/ns/regi st rat i onRequest " xmlns: xsd="ht t p: //www. w3. org/2000/10/XMLSchema" xmlns="ht t p: //www. skat est own. com/schemas/ns/regi st rat i onRequest "> <xsd: compl exType name="regi st rat i onRequest "> <xsd: sequence> <xsd: el ement name="i t ems"> <xsd: compl exType name="ArrayOf I t em"> <compl exCont ent > <rest ri ct i on base="soapenc: Array"> <at t ri but e ref ="soapenc: arrayType" wsdl : arrayType="xsd: st ri ng[ ] "/>

        </compl exCont ent > </compl exType> </xsd: el ement > <xsd: el ement name="address" t ype="xsd: uri Ref erence"/> <xsd: el ement name="t ransport " def aul t ="ht t p: //schemas. xmlsoap. org/soap/smtp" minOccurs="0"> <xsd: si mpl eType> <xsd: rest ri ct i on base="xsd: uri Ref erence"> <xsd: enumerat i on val ue="ht t p: //schemas. xmlsoap. org/soap/ht t p"/> <xsd: enumerat i on val ue="ht t p: //schemas. xmlsoap. org/soap/smtp"/> </xsd: rest ri ct i on> </xsd: si mpl eType> </xsd: el ement >

      <xsd: el ement name="cl i ent Arg" t ype="xsd: st ri ng" minOccurs="0"/>

      </xsd: sequence> </xsd: compl exType> <xsd: si mpl eType name="correl at i onI D"> <xsd: rest ri ct i on base="xsd: st ri ng"> <! - - some appropri at e rest ri ct i on - - > </xsd: rest ri ct i on> </xsd: si mpl eType> </xsd: schema> </t ypes> <! - - Message def i ni t i ons - - > <message name="St ockAvai l abl eRegi st rat i onRequest "> <part name="regi st rat i on" el ement ="reg: regi st rat i onRequest "/> <part name="expi rat i on" t ype="xsd: t i meI nst ant "/> </message> <message name="St ockAvai l abl eRegi st rat i onResponse"> <part name="correl at i onI D" t ype="reg: correl at i onI D"/> </message> <message name="St ockAvai l abl eRegi st rat i onError"> <part name="errorSt ri ng" t ype="xsd: st ri ng"/> </message> <message name="St ockAvai l abl eExpi rat i onError"> <part name="errorSt ri ng" t ype="xsd: st ri ng"/> </message>

        <part name="t i meSt amp" t ype="xsd: t i meI nst ant "/> <part name="correl at i onI D" t ype="reg: correl at i onI D"/> <part name="i t ems" t ype="reg: i t ems"/> <part name="cl i ent Arg" t ype="xsd: st ri ng"/> </message> <message name="St ockAvai l abl eExpi rat i onNot i f i cat i on"> <part name="t i meSt amp" t ype="xsd: t i meI nst ant "/> <part name="correl at i onI D" t ype="reg: correl at i onI D"/> <part name="i t ems" t ype="reg: ArrayOf I t em"/> <part name="cl i ent Arg" t ype="xsd: st ri ng"/> </message> <message name="St ockAvai l abl eCancel l at i on"> <part name="correl at i onI D" t ype="reg: correl at i onI D"/> </message> <! - - Port t ype def i ni t i ons - - > <port Type name="St ockAvai l abl eNot i f i cat i onPort Type"> <! - - Regi st rat i on Operat i on - - > <operat i on name="regi st rat i on"> <i nput message="St ockAvai l abl eRegi st rat i onRequest "/> <out put message="St ockAvai l abl eRegi st rat i onResponse"/> <f aul t message="St ockAvai l abl eRegi st rat i onError" name="St ockAvai l abl eNot i f i cat i onErrorMessage"/> <f aul t message="St ockAvai l abl eExpi rat i onError" name="St ockAvai l abl eExpi rat i onError"/> </operat i on> <! - - Not i f i cat i on Operat i on - - > <operat i on name="not i f i cat i on"> <out put message="St ockAvai l abl eNot i f i cat i on"/> </operat i on> <! - - Expi rat i on Not i f i cat i on Operat i on - - > <operat i on name="expi rat i onNot i f i cat i on">

      <out put message="St ockAvai l abl eExpi rat i onNot i f i cat i on"/> </operat i on> <! - - Cancel l at i on Operat i on - - > <operat i on name="cancel l at i on"> <i nput message=" St ockAvai l abl eCancel l at i on"/> </operat i on> </port Type> <! - - Bi ndi ng def i ni t i ons - - > <bi ndi ng name="St ockAvai l abl eNot i f i cat i onSOAPBi ndi ng" t ype="St ockAvai l abl eNot i f i cat i onPort Type"> t ransport ="ht t p: //schemas. xmlsoap. org/soap/ht t p"/> <document at i on> Not e: t he request or must i nvoke t he regi st rat i on operat i on f i rst . </document at i on> <operat i on name="regi st rat i on"> <soap: operat i on soapAct i on=

      "ht t p: //www. skat est own. com/St ockAvai l abl eNot i f i cat i on/regi st rat i on">

      <i nput > <soap: header message="St ockAvai l abl eRegi st rat i onRequest " part ="expi rat i on" use="encoded"

      namespace="ht t p: //www. skat est own. com/ns/regi st rat i onRequest "

      encodi ngSt yl e="ht t p: //schemas. xmlsoap. org/soap/encodi ng/"/> <soap: headerf aul t message="St ockAvai l abl eExpi rat i onError" part ="errorSt ri ng" use="encoded"

      namespace="ht t p: //www. skat est own. com/ns/regi st rat i onRequest "

      encodi ngSt yl e="ht t p: //schemas. xmlsoap. org/soap/encodi ng/"/> </soap: header> <soap: body part s="regi st rat i on" use="l i t eral " st yl e="document "/> </i nput > <out put > <soap: body use="encoded" namespace="ht t p: //www. skat est own. com/ns/regi st rat i onRequest " encodi ngSt yl e="ht t p: //schemas. xmlsoap. org/soap/encodi ng/"/> </out put > <f aul t name="St ockAvai l abl eNot i f i cat i onErrorMessage"> <soap: f aul t name="St ockAvai l abl eNot i f i cat i onErrorMessage" namespace="ht t p: //www. skat est own. com/ns/regi st rat i onRequest " encodi ngSt yl e="ht t p: //schemas. xmlsoap. org/soap/encodi ng/"/> </f aul t > </operat i on> <operat i on name="not i f i cat i on"> <out put > <soap: body use="encoded" namespace="ht t p: //www. skat est own. com/ns/regi st rat i onRequest " encodi ngSt yl e="ht t p: //schemas. xmlsoap. org/soap/encodi ng/"/> </out put > </operat i on> <operat i on name="cancel l at i on"> <soap: operat i on soapAct i on=

      "ht t p: //www. skat est own. com/St ockAvai l abl eNot i f i cat i on/cancel l at i on">

      <i nput > <soap: body use="encoded" namespace="ht t p: //www. skat est own. com/ns/regi st rat i onRequest " encodi ngSt yl e="ht t p: //schemas. xmlsoap. org/soap/encodi ng/"/>

        </operat i on> </bi ndi ng> <! - - Servi ce def i ni t i on - - > <servi ce name="St ockAvai l abl eNot i f i cat i onServi ce"> <port name="St ockAvai l abl eNot i f i cat i onPort " bi ndi ng=" St ockAvai l abl eNot i f i cat i onSOAPBi ndi ng"> <soap: address l ocat i on= "ht t p: //www. skat est own. com/axi s/servi ces/St ockNot i f i cat i on"/> </port > </servi ce> </def i ni t i ons>

        StockAvailableNotification

        The Web service is provided by Skat esTow n t o support

        RegistrationRequest

        product ordering. The schem a defines t he dat a t ypes. I n

        part icular, t his Web service is used w hen a cust om er places an order w it h Skat esTow n, but one or m ore of t he it em s is not current ly available from Skat esTow n's invent ory. The purpose of t his service is t o allow cust om ers of Skat esTow n t o regist er t o be not ified w hen all t he product s in t heir order are once again available for sale from invent ory. This Web service has four operat ions. The first operat ion allow s t he cust om er t o regist er for a not ificat ion. This is a request / response operat ion. The cust om er invokes t his service, passing in a collect ion of it em num bers ( for out of st ock product num bers) , net w ork address, ( default is an e- m ail address) an opt ional t ransport t ype ( valid values are

        " " ht t p: / / schem as.xm lsoap.org/ soap/ ht t p and

        " " client ht t p: / / schem as.xm lsoap.org/ soap/ sm t p ) , and a argum ent t oken of t ype string client

        . The argum ent t oken is opaque t o t he service; it is a request or- specific

        client correlat ion ident ifier. The argum ent is ret urned by t he not ificat ion operat ion.

        This operat ion also includes an expirat ion t im e t o be included in t he m essage ( as a

        soap:header , as w e w ill discover) .

        The norm al response of t his operat ion is a provider- side correlat ion id ( a st ring) . The possible fault m essages include:

        Invalid product number (one of the product numbers does not

      • correspond to a product in SkatesTown's product catalog)

        smtp http Invalid transport (some value other than • or was specified) Invalid expiration (this appears as a • soap : headerfault if the

      original expiration time header was invalid in some way; we will

      describe soap:headerfault elements in more detail in the section

      " SOAP Fault and HeaderFault Formatting "). notification notification

        The second operat ion, , uses t he t ransm ission prim it ive in WSDL ( w e'll t alk about t ransm ission prim it ives in m ore det ail lat er) . This m essage is sent from Skat esTow n t o t he request or's address indicat ed in t he regist rat ion operat ion. This m essage indicat es a t im est am p, t he provider- side correlat ion I D est ablished in t he regist rat ion m essage, t he it em num bers from t he regist rat ion expirationNotification notification

        The t hird operat ion, , also uses t he t ransm ission prim it ive in WSDL. This m essage is sent from Skat esTow n t o t he request or's address w hen t he expirat ion period indicat ed on t he original regist rat ion operat ion expires. This m essage indicat es a t im est am p, t he provider- side correlat ion I D est ablished in t he regist rat ion m essage, t he it em num bers from t he regist rat ion m essage, and t he request or- specific correlat ion I D.

        The fourt h operat ion is a one- w ay operat ion for cancellat ion of t he not ificat ion. I t allow s t he request or t o abandon it s int erest in t he not ificat ion. The cancellat ion m essage is sim ply t he provider- side correlat ion I D.

        priceCheck

        Now , let 's exam ine t he WSDL language elem ent by elem ent , using t he WSDL

        StockAvailableNotification

        t o show t he sim ple, t ypical use and t he exam ple t o show m ore sophist icat ed WSDL use.

        PortType

        The best st art ing point t o underst anding a Web service using a WSDL docum ent is t he

        portType portType

        elem ent . The elem ent describes t he int erface t o a Web service. This

        portType

        is t he m ost succinct descript ion of w hat t he service does; underst and t he , and you underst and w hat t he Web service does. The rest of t he elem ent s in t he WSDL

        

      portType

        definit ion are essent ially det ails t hat t he depends upon; w e w ill exam ine t hem in lat er sect ions.

        portType priceCheck

        The in t he service descript ion looks like t his:

        <! - - Port t ype def i ni t i ons - - > <port Type name="Pri ceCheckPort Type"> <operat i on name="checkPri ce"> <i nput message="Pri ceCheckRequest "/> <out put message="Pri ceCheckResponse"/> </operat i on> </port Type> portType

        A WSDL docum ent can cont ain zero or m ore definit ions. Typically, m ost WSDL

        portType

        docum ent s cont ain a single . This convent ion separat es out different Web service int erface definit ions int o different docum ent s. This granularit y of separat ion is good for reasons of reuse, and when we discuss how UDDI can be used t o regist er WSDL docum ent s, t his best pract ice w ill becom e apparent .

        portType name priceCheck

        A elem ent has a single at t ribut e. I n our case, t he Web

        portType PriceCheckPortType

        service cont ains a of nam e . Oft en, you w ill see t he nam e

        portType nameOfWebServicePortType

        of t he follow t his pat t ern: . I f t here are m ult iple

        portType portType s in a WSDL file, each m ust have a different nam e.

        Pret t y sim ple so far, but sim ple, w ell- fact ored Web services oft en result in a sim ple

        portType

        looking . Much of t he det ail is in t he rest of t he elem ent s in t he WSDL

        portType

        definit ion, and as far as t he elem ent is concerned, t he det ail is in t he collect ion of operat ion child elem ent s. Just as a Java int erface definit ion is com prised m ainly of

        portType

        m et hod signat ures, t he int erest ing part of a definit ion is t he collect ion of operat ion elem ent s it cont ains.

        Operation operation

        An elem ent in WSDL is t he equivalent of a m et hod signat ure in Java. An operat ion defines a m et hod on a Web service, including t he nam e of t he m et hod and t he input param et ers and t he out put or ret urn t ype of t he m et hod.

        PriceCheck portType checkPrice

        The describes one operat ion, nam ed ( cleverly) . The

        portType StockAvailableNotification

        for t he service defines four operat ions:

        registration notification expirationNotification cancellation , , , and . checkPrice

        The operat ion defines an input m essage and out put m essage. I f w e invoke

        checkPrice priceCheckRequestMessage

        t he operat ion w it h a ( w e'll see w hat exact ly t hese m essages look like in t he next sect ion) , t he Web service w ill ret urn a

        priceCheckResponseMessage . operation operation

        That is all t here is t o an elem ent . The elem ent s define a com binat ion of input , out put , and fault m essages. The WSDL specificat ion defines four different com binat ions of input , out put , and fault m essages. WSDL uses t he t erm t ransm ission prim it ive t o describe t hese com binat ions. Chapt er 3 int roduced t hese concept s as int eract ion pat t erns. We now revisit t hese concept s in t he cont ext of how t o use WSDL t o describe t hese pat t erns.

        Request-Response Style of Operation This is t he m ost com m on form of operat ion. The request - response operat ion defines an input m essage, out put m essage, and an opt ional collect ion of fault m essages. Because m any Web services are deployed using SOAP over HTTP, request - response is t he m ost

        checkPrice

        com m on form of operat ion t ype found in WSDL docum ent s. The operat ion is a request - response operat ion as is t he regist rat ion operat ion from t he

        StockAvailableNotification

        service. Request - response m essages can be inform at ional, ret rieving inform at ion about som e obj ect represent ed by a Web service; or a request - response operat ion can be behavioral, w here t he m essage changes t he st at e of t he service provider and inform at ion about t he new st at e is included in t he response. The

        checkPrice

        operat ion is an inform at ional st yle m essage. The regist rat ion operat ion is a behavior service, because it updat es t he provider's server w it h new inform at ion about a

        stockAvailable request or w ait ing on a event t o fire. checkPrice

        Alt hough does not use it , t he request - response t ransm ission prim it ive allow s t he service provider t o list t he possible fault m essages t hat can appear in response t o a

        fault message

        Web service invocat ion. The elem ent is used w it hin t he

        StockAvailableNotificationPortType

        as part of t he regist rat ion operat ion's definit ion:

        <port Type name="St ockAvai l abl eNot i f i cat i onPort Type"> <! - - Regi st rat i on Operat i on - - > <operat i on name="regi st rat i on"> <i nput message="St ockAvai l abl eRegi st rat i onRequest "/> <out put message="St ockAvai l abl eRegi st rat i onResponse"/> <f aul t message="St ockAvai l abl eRegi st rat i onError" name="St ockAvai l abl eNot i f i cat i onErrorMessage"/> <f aul t message="St ockAvai l abl eExpi rat i onError" name="St ockAvai l abl eExpi rat i onError"/> </operat i on> Fault

        elem ent s m ust be nam ed, and t he nam e m ust be unique am ong all t he fault

        fault

        elem ent s defined for t he operat ion. Like t he input and out put elem ent s, t he elem ent uses a m essage elem ent t o describe t he dat a cont ent s of t he fault . One-way Style of Operation

        output fault

        A one- w ay operat ion does not have an elem ent ( or a elem ent for t hat m at t er) . A one- w ay operat ion is like a dat a sink. A one- w ay m essage w ould be used t o change st at e of t he service provider. Clearly a one- w ay m essage is useless for inform at ional purposes ( no response is sent back t o t he request or) .

        StockAvailableNotification

        The cancellat ion operat ion from t he service is a one- w ay operat ion:

        <! - - Cancel l at i on Operat i on - - > <operat i on name="cancel l at i on"> <i nput message=" St ockAvai l abl eCancel l at i on"/> </operat i on>

        Because m any Web services are accessed t hrough SOAP over HTTP, m any one- w ay m essages end up being request - response m essages, w it h t he response being a sim ple HTTP- level acknow ledgem ent of t he m essage. The operat ion does not m odel t he acknow ledgem ent or t ransport - level m essage flow for a couple of reasons. First , t he det ails of t he t ransport prot ocol is a det ail of t he binding elem ent , not t he operat ion elem ent . Second, no applicat ion- level sem ant ic is t ransm it t ed in response t o t he Web service invocat ion. Notification Style of Operation A not ificat ion operat ion is like a one- w ay push from t he service provider. Out put m essages are pushed t o t he service request or as t he result of som e event on t he service provider side, such as a t im e- out or operat ion com plet ion. The not ificat ion operat ion in

        StockAvailableNotification

        t he Web service is a not ificat ion t ype of operat ion; Skat esTow n pushes a m essage t o t he request or w hen a part icular it em is once again in st ock. The not ificat ion st yle of int eract ion is com m only used in syst em s built around asynchronous m essaging. Alt hough syst em s wit h asynchronous m essaging m ight be a lit t le harder t o concept ualize and im plem ent , t hey are m uch m ore loosely coupled, and, t herefore, are easier t o m aint ain; oft en t his flexibilit y adds robust ness t o t he syst em .

        Given t he not ificat ion operat ion is a one- w ay push m essage, how does Skat esTow n know w here t o push t he out put m essages t o? Not hing in t he WSDL specificat ion describes t his direct ly. This correlat ion sem ant ic m ust be described by ot her m eans. One m echanism used t o address t his problem is t o have a net w ork address ( a URL or e- m ail address) as a param et er in anot her m essage.

        StockAvailableNotification

        I n t he case of t he Web service, Skat esTown has creat ed t he regist rat ion operat ion show n in List ing 6.2 for j ust t he purpose of det erm ining w here t o send a not ificat ion m essage. The service request or m ust invoke t he regist rat ion operat ion first , and t hen t he not ificat ion operat ion w ill be able t o send a m essage t o t he request or. The ordering requirem ent of t hese operat ions—t hat is, t he fact t hat t he regist rat ion operat ion m ust be invoked in order t o receive not ificat ion m essages—cannot be described in WSDL. Pot ent ially, t his ordering sem ant ic m ight be represent ed in t he WSEL language ( described briefly lat er in t his chapt er) . At t his point , Skat esTow n m ust describe t his sem ant ic using prose. The follow ing docum ent at ion elem ent appears w it h

        portType

        t his :

        <document at i on> Not e: t he request or must i nvoke t he regi st rat i on operat i on f i rst . </document at i on>

        Solicit-Response Style of Operation A solicit - response operat ion m odels a push operat ion sim ilar t o a not ificat ion operat ion. How ever, unlike t he not ificat ion st yle of operat ion, t he solicit - response operat ion expect s an input ( response) from t he service request or in response t o t he solicit - response out put flow . A solicit - response operat ion could look like t his:

        <port Type name="someName"> <operat i on name="exampl eSol i ci t Response"> <out put message="pushThi s"/>

        <f aul t name="someFaul t Name" message="f aul t PushedToRequest or"/> </operat i on> </port Type>

        Out put and fault flow s are pushed t o t he service request or as t he result of som e event on t he service provider side, such as a t im e out or operat ion com plet ion. The solicit - response st yle of operat ion has t he sam e problem as t he not ificat ion st yle of operat ion: w here t o push t he out put / fault m essages. Again, t he solut ion is t he sam e as w e discussed w it h t he not ificat ion st yle of operat ion. The only w ay t o t ell t he difference bet w een a request - response operat ion and a solicit - response operat ion is t he ordering of t he input and out put elem ent s. I n request - response, t he input child elem ent com es first . I n solicit - response, t he out put child elem ent com es first .

        Rounding Out the Operation Element The current st at e of t he WSDL t ooling really em phasizes request - response and one- w ay m essages. Because solicit - response m essages require som e sort of correlat ion or regist rat ion t o associat e t he m essage w it h som et hing m eaningful t o t he request or, t hey require a level of associat ion t hat is beyond t he sim ple sem ant ics represent ed by WSDL. The operat ion- ordering sem ant ic could not be enforced in generat ed code. Sim ilarly, a not ificat ion m essage requires a preceding regist rat ion m essage from t he service request or. Again, t his correlat ion sem ant ic cannot be direct ly represent ed in WSDL. Most t ools do not support solicit - response or not ificat ion. For t hat m at t er, m ost t ools support only request - response.

        operation

        Let 's consider a couple of final det ails relat ed t o t he elem ent . The WSDL

        name specificat ion allow s t he input , out put , and fault m essages t o have a at t ribut e. name input output

        Typically, t his at t ribut e is not specified by t he designer on and elem ent s. This det ail is oft en t oo m uch clut t er in t he WSDL docum ent ( as if a WSDL docum ent is not already t oo clut t ered! ) . And besides, WSDL provides default values for

        priceCheck

        t hese nam es based on t he operat ion nam e. For exam ple, w e repeat our exam ple, t his t im e filling in t he default values t hat WSDL w ould have supplied:

        <! - - Port t ype def i ni t i ons - - > <port Type name="Pri ceCheckPort Type"> <operat i on name="checkPri ce"> <i nput name="checkPri ceRequest " message="Pri ceCheckRequest "/> <out put name="checkPri ceResponse" message="Pri ceCheckResponse"/> </operat i on> </port Type> name input output Typically, t he at t ribut e of t he and elem ent doesn't add m uch.

        Furt her, you w ill find t hat m any WSDL designers already encode t his inform at ion int o t he

        input

        nam es of t he m essage elem ent s t hey define. I f you do add a nam e t o an or

        output input output

        elem ent , t his nam e m ust be unique am ong all t he and elem ent s

        portType input output

        w it hin t he . Table 6.2 describes t he default nam es for and

        XXX elem ent s, for an operat ion nam ed .

      Table 6.2. Defaults for and Elements for Operation

        Input Output

      XXX Input Output

        XXXRequest

        XXXResponse Request-Response

        XXX Not applicable One-Way

        XXXSolicit

        XXXResponse Solicit-Response

        XXX Fault fault

        elem ent s, of course, require a nam e, because several elem ent s can be associat ed w it h any operat ion and t he fault nam e is used t o dist inguish bet w een t he

        binding

        collect ion of possible fault s. This is part icularly im port ant in t he elem ent , w hich

        fault

        describes t he m apping bet w een t he elem ent and t he w ay t he fault is present ed in a prot ocol- specific fashion.

        parameterOrder

        WSDL also let s you specify a at t ribut e on an operat ion. The

        parameterOrder

        operat ion is used only for RPC- st yle operat ions. This is a bit of a

        portType

        layering violat ion in t he specificat ion, because t he is abst ract , and it s nat ure as an RPC or docum ent - cent ric m essage is revealed in t he binding elem ent . Furt her, t his elem ent is inform at ional only, and is com plet ely opt ional, even for operat ions t hat are

        binding

        described as RPC w it hin t he elem ent . The only purpose of t his at t ribut e is t o provide a m echanism t o describe t he original param et er ordering of t he RPC funct ion as a list of part nam es ( w e w ill see part nam es discussed in t he follow ing " Message " sect ion) separat ed by spaces.

        priceCheckRequest

        So far, we have not defined what we m ean by a m essage, or any of t he m essages for t hat m at t er. These are sim ply abst ract m essages. The com posit ion of

        message an abst ract m essage is det ailed in a elem ent , described next .

        Message

        A m essage is a very sim ple concept . A m essage is a collect ion of part s. A WSDL

        message message

        docum ent can cont ain zero or m ore elem ent s. Each elem ent can be used as an input m essage, out put m essage, or fault m essage w it hin an operat ion.

        priceCheck

        What is a m essage? Let 's t ake a look at t he m essages defined in t he WSDL:

        <! - - Message def i ni t i ons - - > <! - - A Pri ceCheckRequest i s si mpl y an i t em code ( sku) - - > <message name="Pri ceCheckRequest "> <part name="sku" t ype="xsd: st ri ng"/> </message> <! - - A Pri ceCheckResponse consi st s of an avai l abi l i t y st ruct ure, - - > <! - - def i ned above. - - > <message name="Pri ceCheckResponse"> <part name="resul t " t ype="avai l : avai l abi l i t yType"/> </message>

        PriceCheckRequest message

        The first m essage, , is a sim ple elem ent . Recall t hat

        PriceCheckRequest checkPrice

        is used as t he input m essage t o t he operat ion. All

        message

        elem ent s m ust have a nam e, and t hat nam e m ust be unique am ong all t he

        message elem ent s defined in t he WSDL docum ent .

        PriceCheckRequest part item part

        The m essage defines one elem ent nam ed . A elem ent is m ade up of t w o propert ies: t he nam e of t he part and t he t ype of t he part . The

        name part message

        at t ribut e m ust be unique am ong all t he child elem ent s of t he

        type type

        elem ent . The propert y of t he part is defined as eit her a at t ribut e ( a

        simpleType complexType element

        , from t he XSD schem a t ype syst em ) or an at t ribut e ( also defined using t he XSD schem a t ype syst em ) . We w ill exam ine t ypes in m ore det ail in t he next sect ion. Oft en, t he nam e of t he part says it all, and you need not dive int o t he det ails of how t he t ypes associat ed w it h t he part are m odeled. As w e w ill see lat er, t he

        method it em part w ill t urn int o a param et er in t he service invocat ion. PriceCheckRequest I n t he exam ple, t he t ype of t he part nam ed it em is a sim ple st ring.

        The XML com m ent above t he elem ent definit ion ( w e could have used a WSDL

        documentation

        elem ent ) indicat es t hat t he st ring is t o be int erpret ed as an it em code. Of range t hat an it em code should be const rained t o. How ever, w e didn't m ake t hat choice here.

        message priceCheck

        The only ot her elem ent defined in t he WSDL is

        PriceCheckResponse PriceCheckResponse

        . The m essage describes t he form at of t he

        checkPrice

        out put m essage of t he operat ion. Like it s com panion m essage,

        PriceCheckResponse result

        defines a single part . The

        part is slight ly m ore int erest ing

        avail

        because it s t ype is a com plex t ype defined in t he nam espace corresponding t o t he : prefix. That 's it for sim ple m essages. You can see t hat t he separat ion of m essages from t he operat ion is ext rem ely w ell fact ored, but som ew hat overkill for t his kind of sim ple exam ple. Many WSDL docum ent s do not require t he full pow er achieved by fact oring m essages from operat ions and decom posing m essages int o part s. The part s m echanism in WSDL is used t o allow a m essage t o be decom posed int o sm aller unit s or part s. Each part can be m anifest ed in different ways in t he various net w ork prot ocols. This m apping bet w een part s and prot ocol- specific com ponent s is described in

        binding header

        t he elem ent . Som e part s of t he m essages can appear as SOAP elem ent s. Som e part s can be m apped t o HTTP headers. Som e part s can be used as individual param et ers in an RPC m essage. You really cannot underst and t he t rue use of a part unt il you look at how t he abst ract not ion of t he part is m apped int o a concret e dat a

        binding represent at ion. This m apping is t he responsibilit y of t he elem ent . StockAvailableNotification

        is an exam ple of a com plex, m ult ipart m essage:

        <message name="St ockAvai l abl eNot i f i cat i on"> <part name="t i meSt amp" t ype="xsd: t i meI nst ant "/> <part name="correl at i onI D" t ype="reg: correl at i onI D"/> <part name="i t ems" t ype="reg: i t ems"/> <part name="cl i ent Arg" t ype="xsd: st ri ng"/> </message>

        We w ill exam ine how different part s are m odeled as different com ponent s of a m essage in t he " SOAP Header Form at t ing " sect ion. Type

        message part

        We have seen t he elem ent in WSDL, and t he elem ent s t hat are cont ained w it hin it . How ever, som e of t he t ypes used in t hese exam ple WSDL docum ent s need furt her discussion. The default t ype syst em in WSDL is XML Schem a ( XSD) . This approach is useful t o

        types

        describe m ost of t he t ype used in t he m essages t o invoke a Web service. The

        priceCheck

        elem ent in t he WSDL is pret t y t ypical of t he use of t his elem ent :

        <! - - Type def i ni t i ons - - > <t ypes> <xsd: schema t arget Namespace="ht t p: //www. skat est own. com/ns/avai l abi l i t y" xmlns: xsd="ht t p: //www. w3. org/2001/XMLSchema"> <xsd: compl exType name="avai l abi l i t yType"> <xsd: sequence> <xsd: el ement name="sku" t ype="xsd: st ri ng"/> <xsd: el ement name="pri ce" t ype="xsd: doubl e"/> <xsd: el ement name="quant i t yAvai l abl e" t ype="xsd: i nt eger"/> </xsd: sequence>

        </xsd: schema> </t ypes> types The cont ent s of t he elem ent look very m uch like a schem a definit ion using XSD. types

        Many organizat ions already have XML schem as defined. Because t he elem ent in WSDL is defined t o cont ain one or m ore schem a definit ion elem ent s, WSDL repurposes work already done in XML. Business obj ect s already m odeled in XML can be used as part s of t he m essage elem ent s and, t herefore, used t o define t he input and out put elem ent s for t he Web services' operat ions.

        priceCheck types

        For t he WSDL, t he availabilit y t ype is defined using a elem ent from

        PriceCheckResponse

        WSDL. Recall t hat t he availabilit y t ype w as used as part of t he m essage. This is all st andard XML schem a work t hat we covered in Chapt er 2 , " XML Prim er." WSDL is quit e flexible in t he t ype syst em used. Alt hough XML Schem a is t he predom inant

        types

        t ype syst em used, t he elem ent allow s you t he flexibilit y t o describe a com plet ely

        

      types extensibility

        different t ype syst em . The elem ent has an elem ent t hat let s you describe anot her t ype syst em , say t he Java t ype syst em , and define all t he m essages in t erm s of t his t ype syst em . Consider, how ever, t hat deviat ing from t he XML Schem a t ype syst em increases t he chances t hat m ore service request ors w ill be unable t o invoke your Web service. There are several variant s of XML Schem a; schem a has been under developm ent by t he W3C for several years. The XML Schem a version referenced in t he list ings is

        ht t p: / / w w w .w 3.org/ 2001/ XMLSchem a . You m ight also encount er ot her versions of types definitions

        schem a used in elem ent s ( and as w e w ill see lat er in t he elem ent , t oo) : ht t p: / / w w w .w 3.org/ 2000/ 10/ XMLSchem a and oft en

        ht t p: / / w w w .w 3.org/ 1999/ XMLSchem a . These declarat ions have subt le im plicat ions on

        som e sophist icat ed use of t he XML Schem a language. Consult advanced resources on XML schem a for m ore det ail.

        types

        The elem ent is essent ially a place for t he WSDL docum ent t o define som e user-

        message

        defined XML t ypes for lat er use in t he elem ent s. A WSDL docum ent can have at

        types types

        m ost one elem ent in a docum ent . When a elem ent appears in a WSDL docum ent , it t ypically cont ains a single schem a definit ion elem ent , alt hough it is legal t o have m ore t han one schem a definit ion elem ent . You w ill t ypically see m ult iple schem a definit ion elem ent s if t he Web service is using dat at ypes defined elsew here in m ult iple schem as. Let 's t ake a closer look at t he w ay t he it em s t ype is defined w it hin Skat esTow n's

        registrationRequest

        schem a. Norm ally, t o define a t ype t hat cont ains a repeat ing group of elem ent s, you w ould use t he follow ing st yle of XML schem a:

        <xsd: compl exType name="regi st rat i onRequest "> <xsd: sequence> <xsd: el ement name="i t ems" t ype="xsd: st ri ng" maxOccurs="unbounded" />

        How ever, in WSDL, repeat ing groups such as t his m ust be m odeled using t he array dat a t ype from t he SOAP encoding nam espace

        xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"

        ( ) . This is anot her j arring exam ple w here an aspect of t he m essage encoding ( really t he dom ain of t he

        binding

        elem ent , as w e w ill see in t he next sect ion) im poses it self on t he base dat at yping m echanism in WSDL. This is an art ifact of t he com m on use of WSDL t o m odel SOAP m essages. So, regardless of w het her your Web service uses SOAP, you need t o use t he array dat at ype from t he SOAP encoding nam espace t o m odel repeat ing groups. The

        registrationRequest

        follow ing snippet show s t he t ype:

        <xsd: sequence> <xsd: el ement name="i t ems"> <xsd: compl exType name="ArrayOf I t em"> <compl exCont ent > <rest ri ct i on base="soapenc: Array"> <at t ri but e ref ="soapenc: arrayType" wsdl : arrayType="xsd: st ri ng[ ] "/> </rest ri ct i on> </compl exCont ent > </compl exType> </xsd: el ement >

        

      ArrayOfXXX

        XXX

        By convent ion, t he nam e of t he t ype is , w here is t he base t ype of t he elem ent s t hat are t o appear in t he repeat ing group. The t ype it self is an ext ension of t he

        Array arrayType

        base t ype in t he SOAP encoding nam espace. WSDL adds an at t ribut e t o let you form ally declare t he exact base t ype of t he repeat ing group ( in t his case, it is

        []

        sim ply t he st ring base t ype from XML schem a) . Not e t hat t he charact ers also specify t he array has a single dim ension. That 's it for t ypes. Essent ially, t he com plexit y is in m odeling XML, not in m odeling WSDL.

        Binding PriceCheck StockAvailableNotification

        We have seen t hat t he and services define several operat ions, and w e have som e idea about t he sort s of XML elem ent s t hat t hese operat ions need as input and produce for out put . How ever, t o t his point , w e st ill do not know how t o form at t he m essage t o invoke t hese operat ions. We haven't seen anyt hing in t he WSDL descript ion t hat relat es t o SOAP headers, SOAP bodies, SOAP encoding, and

        portType message type

        so on. The , , and elem ent s define t he abst ract or reusable port ion of t he WSDL definit ion. I s t his service invoked by a SOAP m essage, or a sim ple HTTP POST of an XML payload? I s t his an RPC invocat ion or a docum ent - cent ric m essage

        binding

        invocat ion? These det ails are given by one or m ore elem ent s associat ed w it h t he

        portType . binding

        The elem ent in WSDL t ells t he service request or how t o form at t he m essage in a

        portType binding

        prot ocol- specific m anner. Each can have one or m ore elem ent s

        portType binding

        associat ed wit h it . For a given , a elem ent can describe how t o invoke operat ions using a single m essaging/ t ransport prot ocol, like SOAP over HTTP, SOAP over SMTP, a sim ple HTTP POST operat ion, or any ot her valid com binat ion of net w orking and m essaging prot ocol st andards.

        binding priceCheck

        Let 's t ake a look at t he elem ent in t he WSDL:

        <! - - Bi ndi ng def i ni t i ons - - > <bi ndi ng name="Pri ceCheckSOAPBi ndi ng" t ype="pc: Pri ceCheckPort Type"> <soap: bi ndi ng st yl e="rpc" t ransport = "ht t p: //schemas. xmlsoap. org/soap/ht t p"/> <operat i on name="checkPri ce"> <soap: operat i on soapAct i on=""/> <i nput > <soap: body use="encoded" namespace="ht t p: //www. skat est own. com/servi ces/Pri ceCheck" encodi ngSt yl e="ht t p: //schemas. xmlsoap. org/soap/encodi ng/"/> </i nput >

        <soap: body use="encoded" namespace="ht t p: //www. skat est own. com/servi ces/Pri ceCheck" encodi ngSt yl e="ht t p: //schemas. xmlsoap. org/soap/encodi ng/"/> </out put > </operat i on> binding PriceCheckSOAPBinding

        The nam e of t his elem ent is . The nam e m ust be

        binding

        unique am ong all t he elem ent s defined in t he WSDL docum ent . Convent ionally,

        portType

        t he nam e of t he binding com bines t he nam e w it h t he nam e( s) of t he

        type portType

        prot ocol( s) t o w hich t he binding m aps. The at t ribut e ident ifies w hich t his

        binding

        binding describes. Because WSDL uses nam e referencing t o link t he elem ent t o

        portType portType

        a , you can now see w hy nam e uniqueness is so im port ant . We w ill

        port

        see t he sam e is t rue for binding nam e uniqueness w hen w e discuss how t he

        binding elem ent references a elem ent .

        Typically, m ost WSDL docum ent s cont ain only a single binding. The reason is sim ilar t o

        portType

        why convent ional WSDL docum ent s cont ain a single elem ent : convenience of reuse.

        binding priceCheck portType

        Now , w hich prot ocol is t his elem ent m apping t he t o? We

        binding

        need t o look for clues inside t he elem ent ( besides t he nam ing convent ion, of

        soap:binding

        course) . The first clue is t he prefix of t he first child elem ent , . This is a pret t y st rong hint t hat t his binding is relat ed t o t he SOAP m essaging prot ocol. So, t he

        PriceCheckSOAPBinding priceCheck portType

        elem ent describes how t he ( rem em ber,

        priceCheck is an abst ract service int erface definit ion) is expressed using SOAP. priceCheck

        How are t he SOAP aspect s of t he service invocat ion described in t his

        binding

        elem ent ? WSDL defines a very clever ext ensibilit y convent ion t hat allow s t he

        binding

        elem ent t o be ext ended, w it h elem ent s from different XML nam espaces, t o describe bindings t o any num ber of m essaging and t ransport prot ocols. Pick a m essaging/ t ransport prot ocol set , find t he WSDL convent ion t hat corresponds t o t hat pair, and fill in t he det ails. The WSDL spec defines t hree st andard binding ext ensions for SOAP/ HTTP, HTTP GET/ POST, and SOAP w it h MI ME at t achm ent s. All sort s of act ivit ies are underw ay t o define addit ional binding convent ions.

        PriceCheckSOAPBinding

        The elem ent show n earlier decorat es t he elem ent s from t he

        priceCheck portType

        in four w ays ( invocat ion st yle, SOAPAct ion, input m essage appearance, and out put m essage appearance) , as explained in t he follow ing sect ions. This is a pret t y st raight forw ard use of t he SOAP binding ext ension convent ion described in t he WSDL specificat ion. The SOAP binding st yle also specifies t he w ay SOAP headers, SOAP fault s, and SOAP headerfault s should be form at t ed. These addit ional aspect s of t he SOAP binding convent ion are illust rat ed in t he

        StockAvailableNotificationSOAPBinding .

        Invocation Style The first use of t he SOAP binding ext ension indicat es t he st yle of invocat ion:

        <soap: bi ndi ng st yl e="rpc" t ransport ="ht t p: //schemas. xmlsoap. org/soap/ht t p"/>

        This declarat ion applies t o t he ent ire binding. I t indicat es t hat all operat ions for t he

        priceCheck portType style

        are defined in t his binding as SOAP m essages. Furt her, t he at t ribut e indicat es t hat operat ions w ill follow t he rem ot e procedure call ( RPC) convent ions on t he SOAP body as defined in t he SOAP specificat ion. This default can be

        operation

        explicit ly overridden by a st yle declarat ion in a child elem ent . The ot her

        style document

        alt ernat ive value for t he at t ribut e is , m eaning t he body of t he SOAP m essage is t o be int erpret ed as st raight XML, m ore of a docum ent - cent ric m essage send

        document

        t han a rem ot e procedure call. The default value of t his at t ribut e is . The

        StockAvailableNotification document

        regist rat ion operat ion from t he service uses a st yle for t he input flow .

        transport

        The at t ribut e t ells you t hat t he request or m ust send t he SOAP m essage using HTTP. Ot her possible values for t his at t ribut e could include

        

      ht t p: / / schem as.xm lsoap.org/ soap/ SMTP/ , ht t p: / / schem as.xm lsoap.org/ soap/ ft p/ , and so

      on.

        SOAPAction The second use of t he SOAP binding ext ension is:

        <operat i on name="checkPri ce"> <soap: operat i on SOAPAct i on=""/> SOAPAction

        This declarat ion indicat es t he value t hat should be placed in t he HTTP header

        priceCheck

        as part of t he HTTP m essage carrying t he service invocat ion m essage. As we

        SOAPAction

        discussed in Chapt er 3 , t he purpose of t he header is t o describe t he int ent of

        checkPrice

        t he m essage. I n t he case of t he operat ion, t he WSDL t ells t he service

        SOAPAction

        request or t o put an em pt y st ring as t he value for t he header. Alt hough an

        SOAPAction em pt y st ring is a valid value for , it is not t erribly helpful for t he SOAP rout er. SOAPAction

        Not e t hat a header w it h value of em pt y st ring indicat es t hat t he URI of t he

        SOAPAction

        request is t he place w here t he int ent of t he m essage is t o be found. I f t he value is com plet ely em pt y, no int ent of t he m essage is t o be found. Bet t er convent ions

        SOAPAction

        w it h SOAP w ould require t he request or t o put an int erest ing value as t he t o help som e SOAP rout ers dispat ch t he m essage t o t he appropriat e Web service. The

        StockAvailableNotification

        operat ions in t he service use t his convent ion:

        <operat i on name="regi st rat i on"> <soap: operat i on soapAct i on= "ht t p: //www. skat est own. com/St ockAvai l abl eNot i f i cat i on/regi st rat i on">

        and

        <operat i on name="cancel l at i on"> <soap: operat i on soapAct i on= "ht t p: //www. skat est own. com/St ockAvai l abl eNot i f i cat i on/cancel l at i on"> portType

        This shows t hat different operat ions in t he sam e can be assigned different

        SOAPAction binding notification

        headers by t he elem ent . Not e t hat t he and

        expirationNotification soap:operation

        operat ion elem ent s do not have child elem ent s. These operat ions are not invoked using SOAP over HTTP by t he request or.

        SOAPAction

        Not e, how ever, t hat t he sem ant ics of t he header are quit e cont roversial. As of t his w rit ing, t he XML Prot ocol Working Group of t he W3C is considering rem oving t he

        SOAPAction

        HTTP header concept from t he XML Prot ocol ( t he follow- up t o SOAP) . This is anot her reason w hy t he URL dispat ch is very popular, especially w it h t hings like Axis JWS files. This t echnique is dem onst rat ed in all t he exam ples in Chapt er 3 . We recom m end using t he URL of t he m essage t o express t he int ent of t he m essage.

        soap:operation

        This elem ent can also be used t o override t he default st yle specified in

        soap:binding style

        t he elem ent 's at t ribut e. I n t he case of t he

        StockAvailableNotificationSOAPBinding rpc

        , t he default st yle is . How ever, t he

        registration

        operat ion overrides t his default t o use t he docum ent st yle for it s input m essage:

        <operat i on name="regi st rat i on"> <soap: operat i on

        "ht t p: //www. skat est own. com/St ockAvai l abl eNot i f i cat i on/regi st rat i on"> . . . <soap: body part s="regi st rat i on" use="l i t eral " st yl e="document "/>

        Input Message Appearance

        priceCheck

        The t hird use of t he SOAP binding ext ension in t he WSDL docum ent

        checkPrice

        describes exact ly how t he input m essage t o t he appears in t he part s of t he SOAP m essage:

        <i nput > <soap: body use="encoded" namespace="ht t p: //www. skat est own. com/servi ces/Pri ceCheck" encodi ngSt yl e="ht t p: //schemas. xmlsoap. org/soap/encodi ng/"/> </i nput >

        I n t his case, it is a pret t y sim ple m apping. The ent ire input m essage,

        PriceCheckRequest portType checkPrice

        ( rem em ber, from t he declarat ion for t he

        use="encoded"

        operat ion) is declared t o be abst ract in t his case ( ) . This m eans t hat t he

        XML defining t he input m essage and it s part s are in fact abst ract , and t he real, concret e represent at ion of t he dat a is t o be derived by applying t he encoding schem e indicat ed in

        encodingStyle

        t he at t ribut e. This is a long- w inded w ay t o say t hat t he m essage should

        body

        appear as part of t he SOAP elem ent and t hat t he SOAP engine on t he service provider's net w ork w ill deserialize t he inform at ion from XML t o anot her form at ( such as Java t ypes) using t he encoding st yle defined in t he SOAP specificat ion.

        soap:body

        The declarat ion also int eract s wit h t he st yle of t he operat ion. Because t he

        checkPrice checkPrice

        operat ion w as declared as RPC st yle, t he part s of t he input

        SOAP:body m essage w ill appear as child elem ent s of t he elem ent in t he SOAP m essage.

        Furt her, t hese part s w ill appear as param et ers in t he st yle of t he RPC convent ion defined by t he SOAP specificat ion. Here is an exam ple SOAP m essage t hat conform s t o t he

        checkPrice

        pat t ern t his binding elem ent describes for t he input of t he operat ion:

        <?xml versi on="1. 0" encodi ng="UTF- 8"?> <SOAP- ENV: Envel ope xmlns: SOAP- ENV="ht t p: //schemas. xmlsoap. org/soap/envel ope/" xmlns: xsd="ht t p: //www. w3. org/2001/XMLSchema" xmlns: xsi ="ht t p: //www. w3. org/2001/XMLSchema- i nst ance"> <SOAP- ENV: Body> <ns3: checkPri ce xmlns: ns3="ht t p: //www. skat est own. com/servi ces/Pri ceCheck"> <sku xsi : t ype="xsd: st ri ng">947- TI </sku> </ns3: checkPri ce> </SOAP- ENV: Body> </SOAP- ENV: Envel ope>

        Output Message Appearance The fourt h use of t he SOAP binding ext ension in our exam ple describes exact ly how t he

        checkPrice

        out put m essage of should appear. Not hing new is int roduced w it h t his exam ple. For com plet eness, here is an exam ple response t hat corresponds t o t he pat t ern

        binding checkPrice

        described in t he elem ent for t he out put of t he operat ion:

        <?xml versi on="1. 0" encodi ng="UTF- 8"?> <SOAP- ENV: Envel ope SOAP- ENV: encodi ngSt yl e="ht t p: //schemas. xmlsoap. org/soap/encodi ng/" xmlns: SOAP- ENV="ht t p: //schemas. xmlsoap. org/soap/envel ope/" xmlns: xsd="ht t p: //www. w3. org/2001/XMLSchema"

        <SOAP- ENV: Body> <ns3: checkPri ceResponse xmlns: ns3="ht t p: //www. skat est own. com/servi ces/Pri ceCheck"> <checkPri ceResul t href ="#i d0"/> </ns3: checkPri ceResponse> <mul t i Ref i d="i d0" xsi : t ype="ns5: Avai l abi l i t yType" xmlns: ns5="ht t p: //www. skat est own. com/ns/avai l abi l i t y"> <quant i t yAvai l abl e xsi : t ype="xsd: i nt ">36 </quant i t yAvai l abl e> <pri ce xsi : t ype="xsd: doubl e">129. 0 </pri ce> <sku xsi : t ype="xsd: st ri ng">947- TI </sku> </mul t i Ref > </SOAP- ENV: Body> </SOAP- ENV: Envel ope>

        SOAP Header Formatting The SOAP ext ension also defines t he w ay SOAP headers are described in WSDL. The

        StockAvailableNotification

        not ificat ion operat ion w it hin t he Web service allow s an expirat ion t o be carried in t he input m essage as a SOAP header. This is described in

        binding operation

        t erm s of SOAP w it hin t he elem ent 's child elem ent :

        <operat i on name="regi st rat i on"> <soap: operat i on soapAct i on= "ht t p: //www. skat est own. com/St ockAvai l abl eNot i f i cat i on/regi st rat i on"> <i nput > <soap: header message="St ockAvai l abl eRegi st rat i onRequest " part ="expi rat i on" use="encoded" namespace="ht t p: //www. skat est own. com/ns/regi st rat i onRequest " encodi ngSt yl e="ht t p: //schemas. xmlsoap. org/soap/encodi ng/"/> soap:header

        The elem ent indicat es t hat t he expirat ion part of t he

        StockAvailableRegistrationRequest

        m essage appears as a SOAP header. The

        soap:header soap:body

        at t ribut es of t he elem ent are sim ilar t o t he elem ent . Not e t hat only t he " expirat ion" part of t he m essage appears in t he header. The rest of t he m essage appears in t he body of t he SOAP m essage. SOAP and Formatting

        Fault HeaderFault soap:fault

        The ext ension is an addit ional facilit y described by t he SOAP binding

        

      priceCheck

        ext ension t hat does not appear in t he WSDL, but does appear in t he

        StockAvailableNotification soap:fault

        WSDL. The ext ension describes how a fault elem ent ( like t he one described in t he regist rat ion operat ion in t he

        StockAvailableNotificationPortType

        ) is m apped int o SOAP. A use of t his ext ension is show n here:

        <operat i on name="regi st rat i on"> . . . <f aul t name="St ockAvai l abl eNot i f i cat i onErrorMessage"> <soap: f aul t name="St ockAvai l abl eNot i f i cat i onErrorMessage" namespace="ht t p: //www. skat est own. com/ns/regi st rat i onRequest "

        </f aul t > soap:fault soap:body

        The ext ension has t he sam e at t ribut es as t he ext ension. The fault m essage m ust have a single part . SOAP requires t hat any errors generat ed by t he SOAP engine w hen processing a SOAP header m ust be com m unicat ed back t o t he request or in t he form of a header, not in t he

        MustUnderstand

        body of a fault m essage. fault s are com m unicat ed t his w ay, for

        soap:headerfault

        exam ple. The SOAP ext ension in WSDL defines t he elem ent for j ust

        soap:headerfault

        t his purpose. A elem ent is used t o describe how t he

        StockAvailableExpirationError

        is expressed in SOAP, as a fault header t hat could pot ent ially flow t o com m unicat e errors relat ed t o how t he request or form at s t he expirat ion header. The follow ing exam ple show s how WSDL m odels t his sit uat ion:

        <operat i on name="regi st rat i on"> <soap: operat i on soapAct i on= "ht t p: //www. skat est own. com/St ockAvai l abl eNot i f i cat i on/regi st rat i on"> <i nput > <soap: header message="St ockAvai l abl eRegi st rat i onRequest " . . . <soap: headerf aul t message="St ockAvai l abl eExpi rat i onError" part ="errorSt ri ng" use="encoded" namespace="ht t p: //www. skat est own. com/ns/regi st rat i onRequest " encodi ngSt yl e="ht t p: //schemas. xmlsoap. org/soap/encodi ng/"/> . . . soap:headerfault soap:header

        The elem ent is associat ed w it h t he definit ion t hat m ight be in error, not as part of a fault or out put m essage part of t he operat ion. Example

        SMTPBinding

        As a slight variant on t he SOAP binding t hem e, consider t he possibilit y of sending a

        priceCheck

        request using e- m ail. Skat esTow n could provide an addit ional SMTP binding

        priceCheck portType priceCheck

        t o t he , allow ing a cust om er t o e- m ail a request and

        priceCheck receive as a reply e- m ail t he response m essage. priceCheck portType

        Not m uch changes w it h t his new binding. Of course, t he and t he m essages and t ypes it references do not change. What does change is addit ional

        binding port service port service

        , , and elem ent s ( w e w ill discuss and elem ent s in separat e sect ions lat er) . The biggest changes include use of a different URI for t he

        transport soap:binding

        at t ribut e of t he elem ent t o indicat e SMTP is t he t ransport

        location soap:address

        m echanism . Also, t he form at of t he at t ribut e in t he child elem ent of t he port is different , reflect ing an e- m ail address form at of t he locat ion. Anot her change is t he use of lit eral form for t he input and out put m essage. I t is a nat ural exchange t o have an XML docum ent it self as t he e- m ail m essage and response going bet w een Skat esTow n and it s cust om er. Not hing precludes using RPC over SMTP; t his is a m at t er of your choice:

        <! - - Bi ndi ng def i ni t i ons - - > <bi ndi ng name="Pri ceCheckSMTPBi ndi ng" t ype="pc: Pri ceCheckPort Type"> <soap: bi ndi ng st yl e="document " t ransport ="ht t p: //schemas. xmlsoap. org/soap/smtp"/> <operat i on name="checkPri ce"> <i nput > <soap: body use="l i t eral "/>

        <out put > <soap: body use="l i t eral "/> </out put > </operat i on> </bi ndi ng> <! - - Servi ce def i ni t i on - - > <servi ce name="Pri ceCheckSMTPServi ce"> <port name="Pri ceCheckSMTP" bi ndi ng="Pri ceCheckSMTPBi ndi ng"> <soap: address l ocat i on="mai l t o: pri ceCheck@skat est own. com"/> </port > </servi ce>

      binding

        And t hat is pret t y m uch it for t he WSDL elem ent and t he SOAP ext ensions t o t he

        binding WSDL elem ent . priceCheck

        So, we now know t hat t he only form at support ed for t he and

        StockAvailableNotification

        services is SOAP, and w e know how t he abst ract t ypes should be m apped int o concret e obj ect s. We now have ( alm ost ) all t he det ails needed t o invoke t hese Web services. At t his point , w e know w e m ust use a SOAP m essage

        checkPrice

        som et hing like t he follow ing t o invoke t he operat ion:

        HTTP/1. 0 200 OK Cont ent - Type: t ext /xml; charset =ut f - 8 Cont ent - Lengt h: 719 Set - Cooki e2: J SESSI ONI D=6321f mkki 1; Versi on=1; Di scard; Pat h="/axi s" Set - Cooki e: J SESSI ONI D=6321f mkki 1; Pat h=/axi s Servl et - Engi ne: Tomcat Web Server/3. 2. 3 ( J SP 1. 1; Servl et 2. 2; J ava 1. 3. 0; Windows 2000 5. 0 x86; j ava. vendor=I BM Corporat i on) <?xml versi on="1. 0" encodi ng="UTF- 8"?> <SOAP- ENV: Envel ope SOAP- ENV: encodi ngSt yl e="ht t p: //schemas. xmlsoap. org/soap/encodi ng/" xmlns: SOAP- ENV="ht t p: //schemas. xmlsoap. org/soap/envel ope/" xmlns: xsd="ht t p: //www. w3. org/2001/XMLSchema" xmlns: xsi ="ht t p: //www. w3. org/2001/XMLSchema- i nst ance"> <SOAP- ENV: Body> <ns3: checkPri ceResponse xmlns: ns3="ht t p: //www. skat est own. com/servi ces/Pri ceCheck"> <checkPri ceResul t href ="#i d0"/> </ns3: checkPri ceResponse> <mul t i Ref i d="i d0" xsi : t ype="ns5: Avai l abi l i t yType" xmlns: ns5="ht t p: //www. skat est own. com/ns/avai l abi l i t y"> <quant i t yAvai l abl e xsi : t ype="xsd: i nt ">36 </quant i t yAvai l abl e> <pri ce xsi : t ype="xsd: doubl e">129. 0 </pri ce> <sku xsi : t ype="xsd: st ri ng">947- TI </sku>

        </SOAP- ENV: Body> </SOAP- ENV: Envel ope>

        The only m issing piece is t he net w ork address; w hat URL do w e send t he m essage t o?

        port service These det ails are given in t he and elem ent s.

        Port port

        The elem ent in WSDL is very sim ple. I t s only purpose is t o specify t he net w ork

        port

        address of t he endpoint host ing t he Web service. More precisely, t he elem ent

        binding Port associat es a single prot ocol- specific address t o an individual elem ent .

        elem ent s are nam ed, and t he nam e m ust be unique am ong all t he port s w it hin a WSDL

        port priceCheckSOAPBinding

        docum ent . The elem ent for t he is:

        <port name="Pri ceCheck" bi ndi ng="pc: Pri ceCheckSOAPBi ndi ng"> <soap: address l ocat i on= "ht t p: //l ocal host : 8080/axi s/servl et /Axi sServl et /Pri ceCheck"/> </port >

        This binding indicat es t he URL t o w hich SOAP m essages should be sent in order t o invoke

        priceCheck soap:address

        t he operat ions over SOAP. Not e t he elem ent ; t his is anot her

        binding

        aspect of t he SOAP ext ension t o WSDL. Most of t he ext ension is in t he elem ent ,

        binding and t his is t he only part of t he ext ension out side t he elem ent . port

        That 's it for t he elem ent . We w ould be all done w it h our exam inat ion of t he WSDL

        port Port

        elem ent s except t hat t he elem ent does not st and alone. elem ent s are children

        service of t he elem ent .

        Service

      service port

        The purpose of t he elem ent is t o cont ain a set of relat ed elem ent s. Not hing

        service

        m ore. Alt hough a WSDL docum ent can cont ain a collect ion of elem ent s,

        service service

        convent ionally a WSDL docum ent cont ains a single elem ent . Each elem ent is nam ed, and each nam e m ust be unique am ong all t he services in t he WSDL

        service priceCheck

        docum ent . The following shows t he ent ire elem ent for t he Web service:

        <! - - Servi ce def i ni t i on - - > <servi ce name="Pri ceCheckServi ce"> <port name="Pri ceCheck" bi ndi ng="Pri ceCheckSOAPBi ndi ng"> <soap: address l ocat i on= "ht t p: //www. skat est own. com/axi s/servi ces/Pri ceCheck "/> </port > </servi ce>

        That 's it . I t seem s like quit e a lot of bot her t o w ast e all t hese elem ent s t o express a

        service

        group of port s. Why w ould a designer group several port s t oget her int o a elem ent ?

        service portType

        One reason is t o group t he port s relat ed t o t he sam e int erface ( ) but

        priceCheck portType

        expressed by different prot ocols ( bindings) . For exam ple, if t he w as im plem ent ed in t w o w ays, one using SOAP over HTTP and anot her using SOAP over

        service

        SMTP, a single elem ent could cont ain t he port describing t he URL for t he SOAP/ HTTP net w ork endpoint and t he port describing t he e- m ail address for t he SOAP/ SMTP net w ork endpoint .

        portType

        Anot her reason m ight be t o group relat ed but different s t oget her. For exam ple,

        StockAvailabilityNotification

        if t he designer of t he Web service had chosen t o split

        portType

        out t he not ificat ion operat ion int o a separat e ( cert ainly j ust ifiable) , t hen it

        That is t he bulk of t he im port ant elem ent s in a WSDL definit ion. We now exam ine a few ot her m iscellaneous elem ent s t hat appear in a WSDL docum ent .

        Definitions definitions definitions

        The root elem ent of a WSDL docum ent is a elem ent . A

        definitions

        elem ent cont ains all of t he ot her WSDL elem ent s. A elem ent can cont ain:

        Optionally, one • types element message

        Zero or more • elements Zero or more

      • portType elements (conventionally just one)

        

      Zero or more • binding elements (conventionally just one, for the

      portType element) Zero or more elements (again, usually just one) • service definitions documentation

        The elem ent m ight also cont ain a elem ent ( w e'll t alk about

        import import

        t his in t he next sect ion) and zero or m ore elem ent s ( w e'll t alk about t he

        documentation elem ent aft er t he elem ent ) . definitions name

        The elem ent it self cont ains a at t ribut e ( t he nam e usually corresponds t o t he nam e of t he Web service it self) and t he usual XML nam espace declarat ions. The

        definitions priceCheck

        follow ing is t he elem ent from t he WSDL:

        <?xml versi on="1. 0"?> <def i ni t i ons name="Pri ceCheck" t arget Namespace="ht t p: //www. skat est own. com/servi ces/Pri ceCheck" xmlns: pc="ht t p: //www. skat est own. com/servi ces/Pri ceCheck" xmlns: avai l ="ht t p: //www. skat est own. com/ns/avai l abi l i t y" xmlns: xsd="ht t p: //www. w3. org/2001/XMLSchema" xmlns: soap="ht t p: //schemas. xmlsoap. org/wsdl /soap/" xmlns="ht t p: //schemas. xmlsoap. org/wsdl /"> . . . </def i ni t i ons> name xmlns:pc xmlns:avail

        Except for t he value of t he at t ribut e and t he and declarat ions, you w ill see t his pat t ern at t he beginning of every WSDL docum ent . For WSDL docum ent s t hat declare t ypes w it h repeat ing groups ( arrays) , you w ill also see t he SOAP encoding nam espace declarat ion here.

        Documentation documentation

        You have seen t he elem ent before. I t w as used t o com m unicat e t he relat ionship bet w een t he regist rat ion operat ion and t he not ificat ion operat ion in t he

        StockAvailabilityNotification documentation

        Web service. The elem ent can cont ain any com binat ion of t ext or ot her child elem ent s. Any ot her WSDL elem ent can cont ain a

        documentation elem ent , usually as t he first child elem ent .

        Conventional Use of the Import Element import

        WSDL defines an addit ional elem ent t hat allow s WSDL docum ent s t o be linked

        import import

        t oget her. The elem ent let s you reuse WSDL docum ent s. Really, an elem ent binds a net w ork locat ion t o an XML nam espace. The follow ing line show s t he

        import

        definit ion of an elem ent in WSDL:

        As described previously, m any developers split t heir WSDL designs int o t w o part s, each

        types

        placed in a separat e docum ent . The service int erface definit ion, cont aining t he ,

        message portType binding

        , , and elem ent s, appears in one file. The service int erface definit ion encapsulat es t he reusable com ponent s of a service descript ion. You can t hen place t his file, for exam ple, on a w ell- know n Web sit e ( on an e- m arket place, for exam ple) for everyone t o view . Each organizat ion t hat w ant s t o im plem ent a Web service conform ant t o t hat w ell- know n service int erface definit ion w ould describe a service

        port service

        im plem ent at ion definit ion, cont aining t he and elem ent s, describing how t hat com m on, reusable, service int erface definit ion w as, in fact , im plem ent ed at t he net w ork endpoint host ed by t hat organizat ion. ( You w ill see in Chapt er 7 t hat t his split is very im port ant for regist ering WSDL Web service definit ions in UDDI .) Figure 6.4 out lines how t he m aj or elem ent s in WSDL are divided bet w een t he service int erface definit ion and t he service im plem ent at ion definit ion.

      Figure 6.4. Service implementation definition, service interface definition, and WSDL elements.

        poSubmission

        The designers at Skat esTow n used t his t echnique for t he WSDL. The

        poSubmission poSubmission

        WSDL is a service descript ion for t he SOAP service you saw in Chapt er 3 . I t uses schem a definit ions from Chapt er 2 . The service int erface definit ion

        poSubmission

        for t he service int erface definit ion file appears as follow s:

        <?xml versi on="1. 0" ?> <def i ni t i ons name="poSubmissi on" t arget Namespace= xmlns: xsd="ht t p: //www. w3. org/2001/XMLSchema" xmlns: po="ht t p: //www. skat est own. com/ns/po" xmlns: i nv="ht t p: //www. skat est own. com/ns/i nvoi ce" xmlns: soap="ht t p: //schemas. xmlsoap. org/wsdl /soap/" xmlns="ht t p: //schemas. xmlsoap. org/wsdl /"> <! - - Type def i ni t i ons - - > <t ypes>

      <xsd: schema t arget Namespace="ht t p: //www. skat est own. com/ns/i nvoi ce" . . . >

      <! - - rest of i nvoi ce schema def i ni t i on f rom chapt er 2 - - > <i ncl ude schemaLocat i on="ht t p: //www. skat est own. com/ns/i nvoi ce. xsd"/> </xsd: schema> <xsd: schema t arget Namespace="ht t p: //www. skat est own. com/ns/po" . . . > <! - - rest of purchaseOrder schema def i ni t i on f rom chapt er 2 - - > <i ncl ude schemaLocat i on="ht t p: //www. skat est own. com/ns/po. xsd"/> </xsd: schema> </t ypes> <! - - Message def i ni t i ons - - > <message name="poSubmissi onRequest "> <part name="purchaseOrder" el ement ="po: po"/> </message> <message name="poSubmissi onResponse"> <part name="i nvoi ce" el ement ="i nv: i nvoi ce"/> </message> <! - - Port t ype def i ni t i ons - - > <port Type name="poSubmissi onPort Type"> <operat i on name="doSubmissi on"> <i nput message="poSubmissi onRequest "/> <out put message="poSubmissi onResponse"/> </operat i on> </port Type> <! - - Bi ndi ng def i ni t i ons - - > <bi ndi ng name="poSubmissi onSOAPBi ndi ng" t ype="poSubmissi onPort Type"> <soap: bi ndi ng st yl e="document " t ransport ="ht t p: //schemas. xmlsoap. org/soap/ht t p"/> <operat i on name="pl acePO"> <soap: operat i on soapAct i on= "ht t p: //www. skat est own. com/servi ces/poSubmissi on/submit PO"/> <i nput > <soap: body part s="purchaseOrder" use="l i t eral "/> </i nput > <out put > <soap: body part s="i nvoi ce" use="l i t eral "/>

        </operat i on> </bi ndi ng> </def i ni t i ons> include po

        Not e t he use of t he XML Schem a t ag, im port ing t he elem ent s defined in t he

        invoice and schem a definit ions.

        This WSDL file is a t ypical pat t ern for a sim ple docum ent - cent ric SOAP service. The m essages are sim ple docum ent inst ances; t he SOAP binding indicat es t he use of lit eral encoding—no deserializat ion of t he XML m essage int o program m ing language–specific obj ect s w ill occur.

        This service int erface definit ion can be reused by m any organizat ions. This is especially t rue if t he dat a form at s ( t he purchase order and invoice schem as) are indust ry st andard.

        poSubmission

        The inform at ion specific t o how Skat esTow n im plem ent s t he service

        poSubmissionService

        int erface is cont ained in t he service im plem ent at ion definit ion file:

        <?xml versi on="1. 0" ?> <def i ni t i ons name="poSubmissi onServi ce" t arget Namespace= "ht t p: //www. skat est own. com/servi ces/POSubmissi onServi ce. wsdl " xmlns: xsd="ht t p: //www. w3. org/2001/XMLSchema" xmlns: pop= "ht t p: //www. skat est own. com/servi ces/i nt erf aces/poSubmissi on. wsdl " xmlns: soap="ht t p: //schemas. xmlsoap. org/wsdl /soap/" xmlns="ht t p: //schemas. xmlsoap. org/wsdl /"> <i mport namespace= "ht t p: //www. skat est own. com/servi ces/i nt erf aces/poSubmissi on. wsdl " l ocat i on= "ht t p: //www. skat est own. com/servi ces/i nt erf aces/poSubmissi on. wsdl "/> <! - - Servi ce def i ni t i on - - > <servi ce name="poSubmissi onServi ce"> <port name="poSubmissi onSOAPPort " bi ndi ng="pop: poSubmissi onSOAPBi ndi ng"> <soap: address l ocat i on= "ht t p: //www. skat est own. com/axi s/servi ces/submit PO"/> </port > </servi ce> </def i ni t i ons>

        This t echnique is a nice separat ion of concerns. The service im plem ent at ion docum ent is quit e succinct and cont ains inform at ion t hat is t ruly specific t o t he im plem ent at ion of t his t ype of service by Skat esTow n. Anot her convent ion, som et im es follow ed by WSDL designers, is t o separat e t he binding from t he service int erface definit ion. I t rem ains quit e cont roversial t hat t he service

        binding binding

        int erface definit ion includes, by convent ion, t he elem ent . Aft er all, t he

        SOAPAction

        elem ent , w hen used w it h t he SOAP ext ensions t o WSDL, includes t he

        operation

        at t ribut e in t he elem ent . This really has m ore t o do w it h im plem ent at ion t han reusable descript ion. As you w ill see in Chapt er 7 , part of t he argum ent t o keep t he

        binding

        elem ent in w it h t he ot her reusable elem ent s w as due t o t he convent ion of WSDL Extension Mechanism

        The WSDL language allow s each of t he WSDL elem ent s t o be ext ended w it h elem ent s from ot her nam espaces. The language specificat ion furt her defines st andard ext ensions for SOAP, HTTP GET/ POST operat ions, and MI ME at t achm ent s. You have seen t he use of t he SOAP ext ension ext ensively in t he previous sect ions of t his chapt er. We w ill briefly describe t he ot her t w o ext ension fram ew orks here. WSDL Descriptions of HTTP GET/POST Web Services

        priceCheck

        I m agine a variant on t he Web service t hat w as t uned t o support Web

        priceCheck

        brow sers. This variant on t he Web service w ould use URL encoding t o

        GET

        include t he it em num ber as part of t he service request using HTTP . An invocat ion of

        GET

        t his service could look like an HTTP m essage sent t o t he following URL:

        http://www.skatestown.com/checkPrice?item=xxx1234 . priceCheck binding

        The WSDL definit ion w ould be ext ended t o include a new elem ent :

        <! - - Bi ndi ng def i ni t i ons - - > . . . <bi ndi ng name="Pri ceCheckHTTPGet Bi ndi ng" t ype="Pri ceCheckPort Type"> <ht t p: bi ndi ng verb="GET"/> <operat i on name="checkPri ce"> <ht t p: operat i on l ocat i on="checkPri ce"/> <i nput > <ht t p: url Encoded/> </i nput > <out put > <mime: cont ent t ype="t ext /xml"/> </out put > </operat i on> </bi ndi ng> binding

        The first HTTP ext ension is show n as t he first child of t he elem ent . This elem ent

        GET POST indicat es t hat t he verb is used ( t he ot her opt ion w as t he verb) . operation

        The second HTTP ext ension is show n as t he first child of t he elem ent . This elem ent indicat es t hat t he service is t o be invoked at t he relat ive URI locat ion. This is t o

        port

        be com bined w it h t he absolut e URI locat ion indicat ed in t he elem ent ( w e'll review t hat short ly) .

        input

        The t hird HTTP ext ension is show n as t he first child of t he elem ent . This elem ent indicat es t hat t he part s of t he input m essage are encoded in t he request URI as

        GET

        nam e/ value pairs, w here t he HTTP param et er nam es correspond t o t he WSDL

        checkPrice

        m essage part nam es. Recall t hat t he input m essage t o t he operat ion is t he

        PriceCheckRequest item

        m essage, and it has only one part : a st ring nam ed . This m eans

        ?item= t hat t he value of t he input w ill appear in t he URI , follow ing t he st ring . output

        The fourt h HTTP ext ension is shown as t he first child of t he elem ent . This

        priceCheckResponse elem ent indicat es t hat t he m essage w ill appear as XML t ext . priceCheck

        The last t hing required is t o updat e t he service elem ent of t he WSDL t o

        http:address priceCheckHTTPGetBinding

        include a port describing t he of t he . This updat e is show n in t he follow ing list ing:

        <! - - Servi ce def i ni t i on - - > <servi ce name="Pri ceCheckServi ce">

        <port name="Pri ceCheckBrowserPort " bi ndi ng="Pri ceCheckHTTPGet Bi ndi ng"> <ht t p: address l ocat i on="ht t p: //www. skat est own. com/"/> </port > . . . priceCheck http:address

        Here t he URL of t he service is given using t he WSDL

        binding

        ext ension. Just like t he SOAP ext ension, m ost of t he HTTP ext ension is in t he elem ent ( w here you w ould expect it ) , and t he only rem aining piece is an ext ension t o t he

        port elem ent expressing t he endpoint net w ork address in a prot ocol- specific m anner.

        POST

        The HTTP ext ension also specifies how t o express t he input m essage as HTTP using

        FORM-POST urlReplacement

        and how t o express t he input using . Refer t o t he WSDL specificat ion for m ore det ail. WSDL Descriptions of Web Services Incorporating MIME WSDL also support s a st andard ext ension t o describe m essage part s as MI ME. We covered SOAP w it h MI ME at t achm ent s in Chapt er 3 . This ext ension w ould be used if t he designers at Skat esTow n decided t o include ( in addit ion t o t he norm al SOAP response) a

        priceCheck

        GI F or JPEG im age of t he part queried in a service invocat ion. To support

        priceCheck

        t his addit ion, t he follow ing changes w ould be necessary in t he WSDL. First , t he response m essage w ould be updat ed t o include t he new part :

        <message name="Pri ceCheckResponse"> <part name="resul t " t ype="avai l : avai l abi l i t y"/> <part name="pi ct ure" t ype="xsd: bi nary"/> </message>

        This change does not exercise t he MI ME ext ension st andard, because t he MI ME

        binding

        ext ensions are only w it hin t he elem ent . How ever, t he only change necessary in

        binding

        t he elem ent is t o indicat e t hat t he out put is m odeled as m ult ipart MI ME, w it h

        result picture

        t he part appearing as one MI ME part , t he SOAP body; t he appears in

        binding

        anot her MI ME part as GI F or JPEG. The following list ing shows t he elem ent w it h t hese changes:

        <! - - Bi ndi ng def i ni t i ons - - > <bi ndi ng name="Pri ceCheckSOAPBi ndi ng" t ype="Pri ceCheckPort Type"> <soap: bi ndi ng st yl e="rpc" t ransport ="ht t p: //schemas. xmlsoap. org/soap/ht t p"/> <operat i on name="checkPri ce"> <soap: operat i on SOAPAct i on=""/> <i nput > <soap: body use="encoded" namespace="ht t p: //www. skat est own. com/ns/avai l abi l i t y" encodi ngSt yl e="ht t p: //schemas. xmlsoap. org/soap/encodi ng/"/> </i nput > <out put > <mime: mul t i part Rel at ed> <mime: part > <soap: body use="encoded" namespace="ht t p: //www. skat est own. com/servi ces/Pri ceCheck" encodi ngSt yl e="ht t p: //schemas. xmlsoap. org/soap/encodi ng/"/> </mime: part > <mime: part > <mime: cont ent part ="pi ct ure" t ype="i mage/gi f "/>

        </mime: part > </mime: mul t i part Rel at ed> </out put > </operat i on> </bi ndi ng> output

        Really, t he only t hing t hat has changed is w it hin t he elem ent ( added definit ions

        mime:content picture are in bold) . Not e t he duplicat e elem ent s w it h t he part nam ed .

        When you see t hem , you are t o int erpret t hem as alt ernat ive form at s, one of w hich m ight appear. We have exam ined t he WSDL st andard for service descript ion, but how does it address aut om at ing t he invocat ion of Web services by t he service request or? The next sect ion exam ines one approach: using WSDL t o creat e Java int erfaces or proxies t o invoke Web services. We w ill also t alk about how t o generat e WSDL from exist ing Java code.

        WSDL and Java

        I n t his sect ion, w e review t he relat ionship bet w een Java and WSDL. As you w ill see in

        Chapt er 8 , " I nt eroperabilit y, Tools, and Middlew are Product s," m any Web services

        developm ent and/ or runt im e environm ent s include WSDL t ooling support . We review t he t ooling support in Axis ( alpha 2 release) for generat ing service im plem ent at ion code based on a WSDL, and t he t ooling support for generat ing a WSDL docum ent from a Java im plem ent at ion of a service.

        Deriving Code from WSDL

        Because WSDL is an I DL- level service descript ion language, it is a good idea t o m ake sure t hat it accurat ely represent s t he service it describes. You have t w o choices: Eit her you can m anually design and code t he service based on your underst anding of a WSDL docum ent , or you can use a t ool t o generat e as m uch of t he code for t he service as possible. Al Rosen used t he WSDL2j ava program in Axis t o generat e t he code im plem ent ing t he

        priceCheck

        service. Al ent ered t he follow ing in his com m and line:

        j ava org. apache. axi s. wsdl . Wsdl 2j ava - - verbose - - skel et on - - messageCont ext - - package ch6. ex1

      • out put c: \book\ch6\ex1c: \book\ch6\ex1\pri cecheck. wsdl

        The out put of t he com m and w as:

        Parsi ng XML Fi l e: c: \book\ch6\ex1\pri cecheck. wsdl Usi ng package name: ch6. ex1 Generat i ng port Type i nt erf ace: Pri ceCheckPort Type. j ava Generat i ng server- si de Port Type i nt erf ace: Pri ceCheckPort TypeAxi s. j ava Generat i ng cl i ent - si de st ub: Pri ceCheckSOAPBi ndi ngSt ub. j ava Generat i ng server- si de skel et on: Pri ceCheckSOAPBi ndi ngSkel et on. j ava Generat i ng t ype i mpl ement at i on: Avai l abi l i t yType. j ava Generat i ng t ype i mpl ement at i on hol der: Avai l abi l i t yTypeHol der. j ava Generat i ng servi ce cl ass: Pri ceCheckServi ce. j ava Generat i ng depl oyment document : depl oy. xml Generat i ng depl oyment document : undepl oy. xml

        Let 's t ake a look at each one of t hese files generat ed by t he WSDL t ooling in Axis and

        priceCheck

        discuss how t hese files w ere generat ed from t he WSDL definit ion of t he priceCheck

        service. We w ill also discuss t he st eps Al Rosen t ook t o quickly get t he service running and t est ed. Overview of the Files Generated by WSDL2Java The Axis WSDL t ooling generat es files for use on t he client and t he server. For t he client , Axis generat es t hree files:

        An interface definition for each element • portType PriceCheckPortType.java

        ( in our case) A client-side stub class for each

      • binding element

        ( PriceCheckSOAPBindingStub.java in our case)

      • A factory-pattern style class for each service

        ( PriceCheckService.java in our case) portType

        The int ent ion of t he - based int erface is t o specify t he int erface t he client applicat ion should use t o int eract w it h t he Web service via t he client - side st ub. The binding- based client - side st ub is a proxy for t he Web service in t he client 's program m ing language and runt im e environm ent . The service- based fact ory class ret urns a client - side st ub inst ance com plet e w it h a net w ork endpoint address. For t he server, Axis generat es t hree files:

        portType A modified interface file for each •

        , specific for use by the Axis engine ( PriceCheckPortTypeAxis.java in our case) A server-side skeleton based on each • binding element

        ( PriceCheckSOAPBindingSkeleton.java in our case) A server-side "empty" service implementation file for each • binding PriceCheckSOAPBindingImpl.java element ( in our case)

      • messageContext

        The server- side int erface is generat ed only if t he opt ion is used ( w e'll t alk about t his opt ion a lit t le lat er) . Ot herw ise, t he server- side int erface is t he sam e as t he client - side int erface. This int erface specifies t he int erface t he server expect s t he t arget Web service t o im plem ent . The server- side skelet on is invoked by t he Axis engine and is responsible for invoking t he t arget Web service. The ext ra level of indirect ion is not needed in m any cases; how ever, w hen t here are in/ out and m ult iple out param et ers, t he server- side skelet on com es int o play. For each com plex t ype defined, t w o encoding classes are generat ed: one defining a basic Java im plem ent at ion of t he st ruct ure defined by t he com plex t ype

        AvailabilityType.java

        ( in our case) and a class t o im plem ent RPC in, in/ out , and out

        AvailabilityTypeHolder.java param et er sem ant ics ( in our case) . deploy.xml

        Finally, t he Axis t ooling generat es a deploym ent descript or file called t hat

        undeploy.xml

        can be used t o deploy t he service t o an Axis server. A sym m et ric is generat ed t o undeploy t he service from t he Axis server. Let 's t ake a look at t he det ails of t he files generat ed by t he Axis WSDL t ooling from t he

        priceCheck.wsdl exam ple.

        Generating Classes for Serialization/Deserialization

        priceCheck.wsdl

        <! - - Type def i ni t i ons - - > <t ypes> <xsd: schema t arget Namespace="ht t p: //www. skat est own. com/ns/avai l abi l i t y" xmlns: xsd="ht t p: //www. w3. org/2001/XMLSchema"> <xsd: compl exType name="avai l abi l i t yType"> <xsd: sequence> <xsd: el ement name="sku" t ype="xsd: st ri ng"/> <xsd: el ement name="pri ce" t ype="xsd: doubl e"/> <xsd: el ement name="quant i t yAvai l abl e" t ype="xsd: i nt eger"/> </xsd: sequence> </xsd: compl exType> </xsd: schema> </t ypes> availabilityType AvailabilityType.java

        From t he com plex t ype, t he encoding class

        priceCheck.wsdl

        is generat ed. Because only one com plex t ype elem ent is defined in , only one encoding class is generat ed.

        AvailabilityType.java

        The class defines a st raight forw ard Java represent at ion of t he

        availabilityType

        com plex t ype. The nam e of t he class is derived from t he value of t he

        name complexType

        at t ribut e of t he elem ent . The class it self defines one public inst ance variable for each of t he child elem ent s in t he t ype:

        publ i c cl ass Avai l abi l i t yType i mpl ement s j ava. i o. Seri al i zabl e { pri vat e St ri ng sku; pri vat e doubl e pri ce; pri vat e i nt quant i t yAvai l abl e;

        The nam es of t he inst ance variables are from t he nam es of t he child elem ent s of t he

        availabilityType com plex t ype.

        The Axis WSDL t ooling also generat es a public no- arg const ruct or

        publ i c Avai l abi l i t yType( ) { }

        and a public const ruct or cont aining param et ers for each of t he inst ance variables generat ed:

        publ i c Avai l abi l i t yType( St ri ng sku, doubl e pri ce, i nt quant i t yAvai l abl e) { t hi s. sku = sku; t hi s. pri ce = pri ce; t hi s. quant i t yAvai l abl e = quant i t yAvai l abl e; }

        Finally, t he Axis WSDL t ooling generat es a pair of accessor m et hods ( one get m et hod and one set m et hod) for each inst ance variable. For exam ple, t he accessor m et hods for t he

        sku

        inst ance variable are as follow s:

        publ i c St ri ng get Sku( ) { ret urn sku; } publ i c voi d set Sku( St ri ng sku) { t hi s. sku = sku; }

        AvailabilityType

        That 's it for t he encoding class for . The ot her Java classes generat ed

        availabilityType

        by t he Axis WSDL t ooling use t his class t o m anipulat e elem ent s. This class is also used as part of t he BeanMapping deployed w it h t his service. We w ill discuss t his a lit t le lat er in t he sect ion on generat ing t he deploym ent XML.

        

      availabilityType

        Anot her file w as generat ed for t he com plex t ype:

        AvailabilityTypeHolder.java

        . This file is used t o im plem ent t he behavior of in/ out and m ult iple out param et ers in an RPC- st yle Web service. We'll exam ine t he role of holder classes w hen w e exam ine t he in/ out and m ult iple out param et ers in m ore det ail. As

        priceCheck

        it t urns out , does not have any in/ out param et ers and only has one out

        AvailabilityTypeHolder.java param et er, so t he file is not used.

        As of t he Axis alpha- 2 release, t he Axis WSDL t ooling is at a very early st age. The Axis WSDL t ooling w ill generat e encoding classes for com plex t ypes and even handle elem ent s referencing ot her com plex t ypes. Axis support s t he com m on sim ple t ypes from XML Schem a ( but not all of t he sim ple t ypes) and does not support t he use of t he XML Schem a ext ension m echanism t o base new t ypes from exist ing t ypes. Axis WSDL t ooling also does not support nest ing of com plex t ypes.

        Generating the Client Stub Factory, Stub, and Interface The client st ub is a class t hat encapsulat es t he det ails of t he SOAP and net w orking prot ocol layers from t he applicat ion. The client st ub present s an int erface based on t he

        portType

        t o t he applicat ion. The applicat ion does not need t o know anyt hing about SOAP, HTTP, or any of t hose low er- level det ails. The applicat ion invokes t he int erface and ret rieves a response in t erm s of Java m et hod invocat ion and Java dat a t ypes.

        priceCheck portType

        The int erface generat ed for t he is show n here:

        publ i c i nt erf ace Pri ceCheckPort Type ext ends j ava. rmi. Remot e { publ i c Avai l abi l i t yType checkPri ce( St ri ng sku) t hrows j ava. rmi. Remot eExcept i on; } portType

        The int erface closely reflect s t he definit ion:

        <! - - Port t ype def i ni t i ons - - > <port Type name="Pri ceCheckPort Type"> <operat i on name="checkPri ce"> <i nput message="pc: Pri ceCheckRequest "/> <out put message="pc: Pri ceCheckResponse"/> </operat i on> </port Type> portType

        The nam e of t he int erface class is derived from t he nam e of t he . The only

        checkPrice checkPrice

        m et hod signat ure, , reflect s t he fact t hat only one operat ion, ,

        portType input output

        w as defined for t he . The signat ure of t he m et hod reflect s t he , ,

        fault String

        and elem ent s of t he operat ion. The input param et er, a param et er nam ed

        sku PriceCheckRequest

        , reflect s t he m essage definit ion for t he :

        <message name="Pri ceCheckRequest "> <part name="sku" t ype="xsd: st ri ng"/> </message>

        AvailabilityType

        The ret urn t ype of t he m et hod, , reflect s t he m essage definit ion for

        PriceCheckResponse

        :

        <message name="Pri ceCheckResponse">

        </message> AvailabilityType This is t he first use for t he encoding t ype w e discussed earlier.

        The client applicat ion, t hen, can be coded t o t hat int erface. I n t he sim ple

        PriceCheckTest

        class, we see t he invocat ion lines

        Pri ceCheckServi ce pcs = new Pri ceCheckServi ce( ) ; Pri ceCheckPort Type pcpt = pcs. get Pri ceCheck( ) ; Avai l abi l i t yType at = pcpt . checkPri ce( args[ 0] ) ; args[0]

        w here is a st ring ( t hat should correspond t o a valid st ock keeping unit [ SKU] )

        PriceCheckService

        t aken from t he com m and line. I n t his case, t he applicat ion uses t he t o creat e an inst ance of t he client st ub populat ed w it h t he endpoint address of t he

        priceCheck

        Web service. ( We'll discuss t he client st ub in m ore det ail short ly.) The

        PriceCheckService

        fact ory could be used in m any ot her ways—for exam ple, t o det erm ine t he endpoint address of t he Web service im plem ent at ion from a UDDI lookup.

        portType

        Regardless of t he m et hod used t o derive a client st ub, t he rem ains t he sam e, allow ing t he client applicat ion t o rely on coding t o t hat int erface. The bindings m ight be different , eit her point ing t o different Web services at different endpoint addresses, or perhaps even using different net w ork t ransport s, such as e- m ail. Perhaps t he Web service is a local m et hod call w it hin t he sam e JVM. The client applicat ion is insulat ed from

        portType

        t hese changes because it is coding t o an int erface defined by a . This level of loose coupling bet w een t he request or's applicat ion and t he service provider m akes Web services really great !

        PriceCheckTest The com plet e class is present ed in List ing 6.3 .

        Listing 6.3 The Class

        PriceCheckTest package ch6. ex1; i mport j ava. t ext . NumberFormat ; publ i c cl ass Pri ceCheckTest { publ i c st at i c voi d mai n( St ri ng[ ] args) { i f ( args. l engt h ! = 1) { Syst em.err. pri nt l n( "Usage: Pri ceCheckTest sku") ; Syst em.exi t ( 1) ; } t ry{ Pri ceCheckServi ce pcs = new Pri ceCheckServi ce( ) ; Pri ceCheckPort Type pcpt = pcs. get Pri ceCheck( ) ; Avai l abi l i t yType at = pcpt . checkPri ce( args[ 0] ) ; NumberFormat df = NumberFormat . get CurrencyI nst ance( ) ; Syst em.out . pri nt l n( "One " + args[ 0] + " cost s: " + df . f ormat ( at . get Pri ce( ) ) + ". ") ; Syst em.out . pri nt l n( "There are " + at . get Quant i t yAvai l abl e( ) + " avai l abl e. ") ; } cat ch ( Except i on e) { Syst em.err. pri nt l n( "Somet hi ng wrong wi t h t he Pri ceCheck request ") ;

        e. pri nt St ackTrace( ) ; } } }

        PriceCheckService PriceCheck

        The class, generat ed from t he service elem ent in t he WSDL, is st raight forward. The com plet e class is shown in List ing 6.4 . Listing 6.4 The Class

        PriceCheckService package ch6. ex1; publ i c cl ass Pri ceCheckServi ce{ // Use t o get a proxy cl ass f or Pri ceCheck pri vat e f i nal j ava. l ang. St ri ng Pri ceCheck_address = "ht t p: //l ocal host : 8080/axi s/servi ces/Pri ceCheck"; publ i c Pri ceCheckPort Type get Pri ceCheck( ) { j ava. net . URL endpoi nt ; t ry { endpoi nt = new j ava. net . URL( Pri ceCheck_address) ; } cat ch ( j ava. net . Mal f ormedURLExcept i on e) { ret urn nul l ; // unl i kel y as URL was val i dat ed i n wsdl 2j ava } ret urn get Pri ceCheck( endpoi nt ) ; } publ i c Pri ceCheckPort Type get Pri ceCheck( j ava. net . URL port Address) { t ry { ret urn new Pri ceCheckSOAPBi ndi ngSt ub( port Address) ; } cat ch ( org. apache. axi s. Seri al i zat i onExcept i on e) { ret urn nul l ; // ??? } } } priceCheck

        The nam e of t he class is derived from t he nam e of t he service found in t he WSDL. The net w ork address used

        pri vat e f i nal j ava. l ang. St ri ng Pri ceCheck_address = "ht t p: //l ocal host : 8080/axi s/servi ces/Pri ceCheck"; soap:address

        is derived from t he elem ent of t he port :

        <port name="Pri ceCheck" bi ndi ng="pc: Pri ceCheckSOAPBi ndi ng"> <soap: address l ocat i on="ht t p: //l ocal host : 8080/axi s/servi ces/Pri ceCheck"/> </port >

        The client applicat ion uses t he client st ub generat ed by Axis t o invoke a Web service using a part icular binding m echanism . The Axis WSDL t ooling generat es a client st ub for each binding elem ent found in t he WSDL docum ent . The client st ub class has t he sam e

        binding portType

        nam e as t he elem ent and im plem ent s t he int erface defined for t he

        binding PriceCheckSOAPBindingStub

        nam ed in t he elem ent . A com plet e list ing for t he appears in List ing 6.5 . Listing 6.5 The PriceCheckSOAPBindingStub Class

        package ch6. ex1; i mpl ement s Pri ceCheckPort Type{ pri vat e org. apache. axi s. cl i ent . Servi ceCl i ent cal l = new org. apache. axi s. cl i ent . Servi ceCl i ent ( new org. apache. axi s. t ransport . ht t p. HTTPTransport ( ) ) ;

      pri vat e j ava. ut i l . Hasht abl e propert i es = new j ava. ut i l . Hasht abl e( ) ;

      publ i c Pri ceCheckSOAPBi ndi ngSt ub( j ava. net . URL endpoi nt URL) t hrows org. apache. axi s. Seri al i zat i onExcept i on { t hi s( ) ; cal l . set ( org. apache. axi s. t ransport . ht t p. HTTPTransport . URL, endpoi nt URL. t oSt ri ng( ) ) ; } publ i c Pri ceCheckSOAPBi ndi ngSt ub( ) t hrows org. apache. axi s. Seri al i zat i onExcept i on { t ry { org. apache. axi s. ut i l s. QName qn1 = new org. apache. axi s. ut i l s. QName( "ht t p: //www. skat est own. com/ns/avai l abi l i t y", "Avai l abi l i t yType") ; Cl ass cl s = Avai l abi l i t yType. cl ass; cal l . addSeri al i zer( cl s, qn1, new org. apache. axi s. encodi ng. BeanSeri al i zer( cl s) ) ; cal l . addDeseri al i zerFact ory( qn1, cl s, org. apache. axi s. encodi ng. BeanSeri al i zer. get Fact ory( ) ) ; } cat ch ( Throwabl e t ) { t hrow new org. apache. axi s. Seri al i zat i onExcept i on ( "Avai l abi l i t yType", t ) ; } } publ i c voi d _set Propert y( St ri ng name, Obj ect val ue) { propert i es. put ( name, val ue) ; } // From org. apache. axi s. wsdl . St ub publ i c Obj ect _get Propert y( St ri ng name) { ret urn propert i es. get ( name) ; } // From org. apache. axi s. wsdl . St ub publ i c voi d _set Target Endpoi nt ( j ava. net . URL address) { cal l . set ( org. apache. axi s. t ransport . ht t p. HTTPTransport . URL, address. t oSt ri ng( ) ) ; }

      publ i c j ava. net . URL _get Target Endpoi nt ( ) { t ry { ret urn new j ava. net . URL( ( St ri ng) cal l . get ( org. apache. axi s. t ransport . ht t p. HTTPTransport . URL) ) ; } cat ch ( j ava. net . Mal f ormedURLExcept i on mue) { ret urn nul l ; // ??? } } // From org. apache. axi s. wsdl . St ub publ i c synchroni zed voi d set Mai nt ai nSessi on( bool ean sessi on) { cal l . set Mai nt ai nSessi on( sessi on) ; } // From j avax. naming. Ref erenceabl e publ i c j avax. naming. Ref erence get Ref erence( ) { ret urn nul l ; // ??? } publ i c Avai l abi l i t yType checkPri ce( St ri ng sku) t hrows j ava. rmi. Remot eExcept i on{ i f ( cal l . get ( org. apache. axi s. t ransport . ht t p. HTTPTransport . URL) == nul l ) { t hrow new org. apache. axi s. NoEndPoi nt Except i on( ) ; } cal l . set ( org. apache. axi s. t ransport . ht t p. HTTPTransport . ACTI ON, "") ; Obj ect resp = cal l . i nvoke( "ht t p: //www. skat est own. com/servi ces/Pri ceCheck", "checkPri ce", new Obj ect [ ] { new org. apache. axi s. message. RPCParam("sku", sku) } ) ; i f ( resp i nst anceof j ava. rmi. Remot eExcept i on) { t hrow ( j ava. rmi. Remot eExcept i on) resp; } el se { ret urn ( Avai l abi l i t yType) resp; } } }

        ServiceClient

        Most of t he client st ub code is generat ed t o m anipulat e t he , which, as you saw in Chapt er 4 , is t he m aj or int erface bet w een client applicat ions and t he Axis engine on t he request or side. Propert ies t hat are set include t he t ransport and t he net w ork address of t he service ( given as a param et er, from t he client applicat ion or t he

        ServiceClient

        st ub fact ory class) . The client st ub also configures t he wit h serializers

        complexType

        and deserializers for each involved in t he binding ( t hat is, derived from t he

        portType

        ) using t he encoding classes discussed earlier:

        org. apache. axi s. ut i l s. QName qn1 = new org. apache. axi s. ut i l s. QName

        Cl ass cl s = Avai l abi l i t yType. cl ass; cal l . addSeri al i zer ( cl s, qn1, new org. apache. axi s. encodi ng. BeanSeri al i zer ( cl s) ) ; cal l . addDeseri al i zerFact ory ( qn1, cl s, org. apache. axi s. encodi ng. BeanSeri al i zer. get Fact ory ( ) ) ;

        These serializers and deserializers are very im port ant because t hey are t he part of t he Axis engine t hat is responsible for convert ing som et hing t hat looks like t his

        <ns3: checkPri ceResponse xmlns: ns3="ht t p: //www. skat est own. com/servi ces/Pri ceCheck"> <checkPri ceResul t href ="#i d0"/> </ns3: checkPri ceResponse> <mul t i Ref i d="i d0" xsi : t ype="ns5: Avai l abi l i t yType" xmlns: ns5="ht t p: //www. skat est own. com/ns/avai l abi l i t y"> <quant i t yAvai l abl e xsi : t ype="xsd: i nt ">36 </quant i t yAvai l abl e> <pri ce xsi : t ype="xsd: doubl e">129. 0 </pri ce> <sku xsi : t ype="xsd: st ri ng">947- TI </sku> </mul t i Ref >

        AvailabilityType quantityAvailable price sku

        int o an inst ance of , w it h t he , , and inst ance variables properly set . Finally, t he core purpose of t he client st ub is t o provide an im plem ent at ion of each

        portType

        operat ion defined in t he int erface generat ed from t he . I n t he

        PriceCheckSOAPBindingStub checkPrice

        , t here is one m et hod im plem ent at ion: . This

        ServiceClient

        m et hod is responsible for gat hering t he param et ers, using t he t o invoke t he Web service, and ret urn t he m arshaled result back t o t he client applicat ion:

        publ i c Avai l abi l i t yType checkPri ce( St ri ng sku) t hrows j ava. rmi. Remot eExcept i on{ i f ( cal l . get ( org. apache. axi s. t ransport . ht t p. HTTPTransport . URL) == nul l ) { t hrow new org. apache. axi s. NoEndPoi nt Except i on( ) ; } cal l . set ( org. apache. axi s. t ransport . ht t p. HTTPTransport . ACTI ON, "") ; Obj ect resp = cal l . i nvoke( "ht t p: //www. skat est own. com/servi ces/ Pri ceCheck", "checkPri ce", new Obj ect [ ] { new org. apache. axi s. message. RPCParam("sku", sku) } ) ; i f ( resp i nst anceof j ava. rmi. Remot eExcept i on) { t hrow ( j ava. rmi. Remot eExcept i on) resp; } el se { ret urn ( Avai l abi l i t yType) resp; } }

        And t hat is it for t he Java code generat ed for use on t he client side. Generating the Server Skeleton and Interface

        The server- side int erface can t ake one of t w o form s, depending on w het her t he Web service im plem ent at ion needs cont ext inform at ion t o be passed t o it . Many Web service im plem ent at ions are st andalone; t hey need no inform at ion from t he Axis engine relat ing t o t he cont ext of t he request ( inform at ion about t he request or, t ransport specific inform at ion like t he servlet cont ext , ot her environm ent propert ies, and so on) . I n t his

        

      portType

        case, t he client - side int erface based on is sufficient . However, for cases where

      • messageContext

        cont ext is required from t he Axis engine, you should use t he opt ion on t he Wsdl2j ava, generat ing a server- side int erface. The server- side int erface generat ed

        priceCheck from t he WSDL appears in List ing 6.6 .

        Listing 6.6 The PriceCheckPortTypeAxis Interface

        package ch6. ex1; publ i c i nt erf ace Pri ceCheckPort TypeAxi s ext ends j ava. rmi. Remot e { publ i c Avai l abi l i t yType checkPri ce( org. apache. axi s. MessageCont ext ct x, St ri ng sku) t hrows j ava. rmi. Remot eExcept i on; } portType

        The server- side int erface has t he nam e of t he appended w it h t he st ring Axis;

        PriceCheckPortTypeAxis.java

        for exam ple, . This int erface is sim ilar t o t he client - side int erface, except t hat each m et hod signat ure includes as it s first param et er a

        MessageContext

        param et er, allow ing t he Web service im plem ent at ion access t o t he

        MessageContext

        environm ent t hrough t his obj ect . Using is a good w ay t o encapsulat e access t o inform at ion such as t he t ransport . The dow nside of doing t his is t hat your Web service im plem ent at ion is t ied very closely t o Axis. Al Rosen chose t his approach for t he

        priceCheck

        Web service because he used t he sam e m et hod t o get at t he

        ProductDatabase InventoryCheck

        as t he Web service, and t hat m et hod uses

        MessageContext .

        The server- side skelet on is quit e sim ple. One such class is defined for each binding elem ent in t he WSDL docum ent , as show n in List ing 6.7 . Listing 6.7 The Interface

        PriceCheckSOAPBindingSkeleton package ch6. ex1; publ i c cl ass Pri ceCheckSOAPBi ndi ngSkel et on{ pri vat e Pri ceCheckPort TypeAxi s i mpl ; publ i c Pri ceCheckSOAPBi ndi ngSkel et on( ) { t hi s. i mpl = new Pri ceCheckSOAPBi ndi ngI mpl ( ) ; } publ i c Pri ceCheckSOAPBi ndi ngSkel et on( Pri ceCheckPort TypeAxi s i mpl ) { t hi s. i mpl = i mpl ; } publ i c Obj ect checkPri ce( org. apache. axi s. MessageCont ext ct x, St ri ng sku) t hrows j ava. rmi. Remot eExcept i on { Obj ect ret = i mpl . checkPri ce( ct x, sku) ; ret urn ret ; } }

        The skelet on defines a couple of sim ple const ruct ors, allowing it t o be associat ed wit h an im plem ent at ion of t he server- side int erface—t hat is, an im plem ent at ion of t he Web

        PriceCheckSOAPBindingImpl

        nam ed by default . A sam ple

        PriceCheckSOAPBindingImpl.java

        file is also generat ed, w it h t rivial cont ent s:

        package ch6. ex1; publ i c cl ass Pri ceCheckSOAPBi ndi ngI mpl i mpl ement s Pri ceCheckPort TypeAxi s { publ i c Avai l abi l i t yType checkPri ce( org. apache. axi s. MessageCont ext ct x, St ri ng sku) t hrows j ava. rmi. Remot eExcept i on { t hrow new j ava. rmi. Remot eExcept i on ( "Not Yet I mpl ement ed") ; } } portType The skelet on generat es an im plem ent at ion m et hod for each operat ion in t he .

        Each operat ion is t he sam e, invoking t he corresponding m et hod in t he act ual Web service im plem ent at ion class.

        checkPrice PriceCheckSOAPBindingSkeleton

        The im plem ent at ion in t he is quit e sim ple:

        publ i c Obj ect checkPri ce( org. apache. axi s. MessageCont ext ct x, St ri ng sku) t hrows j ava. rmi. Remot eExcept i on { Obj ect ret = i mpl . checkPri ce( ct x, sku) ; ret urn ret ; }

        How ever, for Web services t hat involve in/ out and out param et ers, t he im plem ent at ion of t he skelet on operat ion becom es m uch t rickier. In/out and Multiple Out Parameters I n cert ain RPC sit uat ions, WSDL can specify m essage part s t hat appear on bot h t he input m essage and out put m essage; t hese t ranslat e t o in/ out param et ers. Furt her, WSDL can specify an out put m essage w it h m ore t han one part . I n/ out and m ult ipart out put m essages pose an int erest ing problem for t ranslat ing WSDL t o Java. Consider t he follow ing exam ple WSDL:

        <wsdl : message name="i nmsg"> <wsdl : part name="i n1" t ype="i n"/> <wsdl : part name="i nout 1" t ype="i nout "/> </wsdl : message> <wsdl : message name="out msg"> <wsdl : part name="i nout 1" t ype="i nout "/> <wsdl : part name="out 1" t ype="out "/> <wsdl : part name="out 2" t ype="out "/> </wsdl : message> <wsdl : port Type name="pt 1"> <wsdl : operat i on name="op1"> <wsdl : i nput message="i nmsg"/> <wsdl : out put message="out msg"/> </wsdl : operat i on> op1 inout1

        The operat ion nam ed has a m essage part nam ed appearing in bot h t he input m essage and out put m essage. Furt her, you w ill not ice t hat t he out put m essage of t he

        inout1

        operat ion has t hree out put part s: t he part , and t w o part s t hat appear only in t he

        out1 out2 out put m essage, and .

        How is it possible in Java t o have a param et er t hat is bot h on t he input and t he out put , or t o have m ult iple out put values? This is w here t he holder classes com e in. As w e have seen, Axis WSDL t ooling generat es holder classes for each of t he input , out put , and in/ out param et ers. The classes generat ed w hen t his WSDL file w as processed

        InHolder.Java InOutHolder.Java OutHolder.Java

        included , , and . These holder classes are sim ple: They cont ain a value of t he given underlying t ype and provide a sim ple const ruct or. Now , t he skelet on generat ed for t he follow ing binding

        <wsdl : bi ndi ng name="pt 1SOAPBi ndi ng1" t ype="pt 1"> <soap: bi ndi ng st yl e="rpc" t ransport ="ht t p: //schemas. xmlsoap. org/soap/ht t p"/> <wsdl : operat i on name="op1"> <soap: operat i on soapAct i on="op1"/> <wsdl : i nput > <soap: body use="encoded" namespace="someNamespace" encodi ngSt yl e="ht t p: //schemas. xmlsoap. org/soap/encodi ng/"/> </wsdl : i nput > <wsdl : out put > <soap: body use="encoded" namespace="someNamespace" encodi ngSt yl e="ht t p: //schemas. xmlsoap. org/soap/encodi ng/"/> </wsdl : out put > </wsdl : operat i on> </wsdl : bi ndi ng>

        looks like t his:

        publ i c Obj ect op1( org. apache. axi s. MessageCont ext ct x, I n i n1, I nout i nout 1) t hrows j ava. rmi. Remot eExcept i on { I nout Hol der i nout 1Hol der = new I nout Hol der( i nout 1) ; Out Hol der out 2Hol der = new Out Hol der( ) ; Obj ect ret = i mpl . op1( ct x, i n1, i nout 1Hol der, out 2Hol der) ; org. apache. axi s. server. ParamLi st l i st = new org. apache. axi s. server. ParamLi st ( ) ; l i st . add( new org. apache. axi s. message. RPCParam("out 1", ret ) ) ; l i st . add( new org. apache. axi s. message. RPCParam ( "i nout 1", i nout 1Hol der. _val ue) ) ; l i st . add( new org. apache. axi s. message. RPCParam ( "out 2", out 2Hol der. _val ue) ) ; ret urn l i st ; }

        Not e t he w ay t he t arget Web service is dispat ched. Holder obj ect s are creat ed for t he in/ out and t he second out param et er and passed t o t he im plem ent at ion. The

        InoutHolder

        m odifies t he value in t he t hat is passed. All t hree values are passed back t o

        RPCParam t he request or as s.

        Consider t he t est program show n in List ing 6.8 . Listing 6.8 The In/Out and Out Parameter Test Program

        package ch6. ex5; publ i c cl ass Test { publ i c st at i c voi d mai n( St ri ng[ ] args) { i f ( args. l engt h ! = 2) { Syst em.err. pri nt l n( "Usage: Test i nt 1 i nt 2") ; Syst em.err. pri nt l n ( "Mul t i pl i es i nt 1 by i nt 2 and ret urns t hat as out parm,") ; Syst em.err. pri nt l n( "Adds val ue of i nt 1 t o i nt 2 ( as i nout parm)") ; Syst em.err. pri nt l n ( "Adds new val ue of i nout parm wi t h t he resul t of t he mul t i pl i cat i on"

      • "t o produce ret urn val ue. ") ; Syst em.exi t ( 1) ; } t ry{ i nt i nt 1 = I nt eger. val ueOf ( args[ 0] ) . i nt Val ue( ) ; i nt i nt 2 = I nt eger. val ueOf ( args[ 1] ) . i nt Val ue( ) ; pt 1 st ub = new I n_Out _Parm() . get I n_Out _Test _Port ( ) ; I n i n1 = new I n( i nt 1) ; I nout Hol der i nout 1 = new I nout Hol der( new I nout ( i nt 2) ) ; Out Hol der out 2 = new Out Hol der( ) ;

        Out res = st ub. op1 ( i n1, i nout 1, out 2) ; Syst em.out . pri nt l n( i nt 1 + "*" + i nt 2 + " = " + out 2. _val ue. get E3( ) ) ; Syst em.out . pri nt l n( i nt 1 + "+" + i nt 2 + " = " + i nout 1. _val ue. get E2( ) ) ; Syst em.out . pri nt l n( i nt 1 + "*" + i nt 2 + " + " + i nt 1 + "+"

      • i nt 2 + " = " + res. get E3( ) ) ; } cat ch ( Except i on e) { Syst em.err. pri nt l n( "Somet hi ng wrong wi t h t he Test servi ce") ;

        e. pri nt St ackTrace( ) ; } } }

        When t his is run w it h t he com m and

        j ava ch6. ex5. Test 2 3

        The follow ing SOAP m essage is generat ed:

        POST /axi s/servl et /Axi sServl et /I n_Out _Test _Port HTTP/1. 0 . . .

        <SOAP- ENV: Envel ope xmlns: SOAP- ENV="ht t p: //schemas. xmlsoap. org/soap/envel ope/" xmlns: xsd="ht t p: //www. w3. org/2001/XMLSchema" xmlns: xsi ="ht t p: //www. w3. org/2001/XMLSchema- i nst ance"> <SOAP- ENV: Body> <ns3: op1 xmlns: ns3="someNamespace"> <i n1 href ="#i d0"/> <i nout 1 href ="#i d1"/> </ns3: op1> <mul t i Ref i d="i d1" xsi : t ype="ns6: I nout " xmlns: ns6="anot herNamespace"> <e2 xsi : t ype="xsd: i nt ">3 </e2> </mul t i Ref >

      <mul t i Ref i d="i d0" xsi : t ype="ns10: I n" xmlns: ns10="anot herNamespace">

      <e1 xsi : t ype="xsd: i nt ">2 </e1> </mul t i Ref > </SOAP- ENV: Body> </SOAP- ENV: Envel ope>

        A sam ple Web service im plem ent at ion of t his service looks like List ing 6.9 . Listing 6.9 Example In/Out and Out Parameter Web Service Implementation

        package ch6. ex5; i mport j ava. rmi. Remot eExcept i on; i mport org. apache. axi s. MessageCont ext ; publ i c cl ass pt 1SOAPBi ndi ng1I mpl i mpl ement s pt 1Axi s { /**

      • @see pt 1Axi s#op1( MessageCont ext , I n, I nout Hol der, Out Hol der)
      • mul t i pl y t he val ue of i nout by i n and t oss i t i nt o out 2
      • add i n t o i nout and t oss t hat i nt o i nout
      • ret urn t he t ot al of i nout and out 2
      • / publ i c Out op1( MessageCont ext ct x, I n i n1, I nout Hol der i nout 1, Out Hol der out 2) t hrows Remot eExcept i on { out 2. _val ue = new Out ( ) ; out 2. _val ue. set E3( i n1. get E1( ) *i nout 1. _val ue. get E2( ) ) ; i nout 1. _val ue. set E2( i nout 1. _val ue. get E2( ) + i n1. get E1( ) ) ; ret urn new Out ( i nout 1. _val ue. get E2( ) + out 2. _val ue. get E3( ) ) ; } /**

      • / publ i c Out op1( I n i n1, I nout Hol der i nout 1, Out Hol der out 2) t hrows Remot eExcept i on { out 2. _val ue = new Out ( ) ; out 2. _val ue. set E3( i n1. get E1( ) *i nout 1. _val ue. get E2( ) ) ; i nout 1. _val ue. set E2( i nout 1. _val ue. get E2( ) + i n1. get E1( ) ) ; ret urn new Out ( i nout 1. _val ue. get E2( ) + out 2. _val ue. get E3( ) ) ; } }

        This is a sim ple program t hat t akes t he input value and increm ent s t he in/ out value by t hat am ount . Furt her, it ret urns in one out put param et er t he product of t he in and t he original in/ out value, and in t he " real" out put of t he m essage, ret urns t he sum of t he new ly increm ent ed in/ out value and t he ot her out put param et er. I t is a useless funct ion, but it illust rat es t he in/ out and m ult iple out sit uat ions in a sim ple fashion.

      This program produces t he follow ing out put SOAP response: HTTP/1. 0 200 OK. .

        <?xml versi on="1. 0" encodi ng="UTF- 8"?> <SOAP- ENV: Envel ope SOAP- ENV: encodi ngSt yl e=ht t p: //schemas. xmlsoap. org/soap/encodi ng/ xmlns: SOAP- ENV=ht t p: //schemas. xmlsoap. org/soap/envel ope/ xmlns: xsd=ht t p: //www. w3. org/2001/XMLSchema xmlns: xsi ="ht t p: //www. w3. org/2001/XMLSchema- i nst ance"> <SOAP- ENV: Body> <ns3: op1Response xmlns: ns3="someNamespace"> <out 1 href ="#i d0"/> <i nout 1 href ="#i d1"/> <out 2 href ="#i d2"/> </ns3: op1Response> <mul t i Ref i d="i d2" xsi : t ype="ns7: Out " xmlns: ns7="anot herNamespace"> <e3 xsi : t ype="xsd: i nt ">6 </e3> </mul t i Ref > <mul t i Ref i d="i d1" xsi : t ype="ns11: I nout " xmlns: ns11="anot herNamespace"> <e2 xsi : t ype="xsd: i nt ">5 </e2> </mul t i Ref > <mul t i Ref i d="i d0" xsi : t ype="ns15: Out " xmlns: ns15="anot herNamespace"> <e3 xsi : t ype="xsd: i nt ">11 </e3> </mul t i Ref > </SOAP- ENV: Body> </SOAP- ENV: Envel ope> multiref

        Not e t he w ay t he elem ent is used t o cont ain t he holder values back t o t he request or. The t est program show n in List ing 6.8 t hen t akes t hese values from t he ret urned holder classes and print s t he follow ing out on t he screen:

        2+3 = 5 2*3 + 2+3 = 11

        This w ould have been ext rem ely t ricky t o do m anually, but it w as not hing for t he Axis WSDL t ooling.

        priceCheck Now , back t o our exam ple.

        Generating the Deployment XML I n order for t he Axis engine t o know about a service, t he service needs t o be deployed. The current m echanism of deploying services in Axis is t hrough a deploym ent descript or,

        deploy.xml

        a file. I nst ruct ions on how t o deploy a Web service are included in generat ed

        deploy.xml com m ent s at t he beginning of t he file. deploy.xml

        A file is generat ed t o deploy all t he Web services defined in a WSDL

        service port

        docum ent . A elem ent is generat ed for each elem ent in t he WSDL file. The

        deploy.xml priceCheck.wsdl file generat ed from is show n in List ing 6.10 .

        Listing 6.10 The File Generated from

        deploy.xml priceCheck.wsdl <! - - - - > <! - - Use t hi s f i l e t o depl oy some handl ers/chai ns and servi ces - - > <! - - Two ways t o do t hi s: - - > <! - - j ava org. apache. axi s. ut i l s. Admin depl oy. xml - - > <! - - f rom t he same di r t hat t he Axi s engi ne runs - - > <! - - or - - > <! - - j ava org. apache. axi s. cl i ent . AdminCl i ent depl oy. xml - - > <! - - af t er t he axi s server i s runni ng - - > <! - - Thi s f i l e wi l l be repl aced by WSDD once i t ' s ready - - > <m:depl oy xmlns: m="AdminServi ce"> <! - - Servi ces f rom Pri ceCheckServi ce WSDL servi ce - - > <servi ce name="Pri ceCheck" pi vot ="RPCDi spat cher"> <opt i on name="cl assName" val ue="Pri ceCheckSOAPBi ndi ngSkel et on"/> <opt i on name="met hodName" val ue=" checkPri ce"/> </servi ce> <beanMappi ngs xmlns: avai l ="ht t p: //www. skat est own. com/ns/avai l abi l i t y"> <avai l : Avai l abi l i t yType cl assname= "Avai l abi l i t yType"/> </beanMappi ngs> </m:depl oy> style

        The value of t he pivot handler is det erm ined by t he value of t he elem ent of t he

        soap:operation RPC RPCDispatcher document

        elem ent ; generat es , and generat es

        MsgDispatcher option className

        . An elem ent w it h t he nam e is generat ed for t he binding referenced by t he port . The act ual value is set t o t he nam e of t he skelet on Java

        methodName option

        file. The elem ent cont ains a list of m et hods, one for each operat ion in t he binding, each separat ed by a space. This deploym ent t ells t he Axis engine t o

        PriceCheckSOAPBindingSkeleton checkPrice invoke t he class using t he operat ion.

        ( Not e t hat t he deploym ent file has been m odified t o reflect t he package nam es w here t he act ual class files have been placed.)

        deploy.xml

        The file also cont ains a collect ion of serializers associat ed wit h t he Web

        AvailabilityType.Java

        service, associat ing an encoding class, in t his case , w it h t he

        <beanMappi ngs xmlns: avai l ="ht t p: //www. skat est own. com/ns/avai l abi l i t y"> <avai l : Avai l abi l i t yType cl assname="Avai l abi l i t yType"/> </beanMappi ngs>

        The Axis WSDL t ooling also generat es a docum ent t o undeploy t he Web service. This

        undeploy.xml service

        docum ent is called . The undeploy cont ains a elem ent for each

        service

        port in t he WSDL docum ent ; t his corresponds t o t he elem ent s generat ed in t he

        deploy.xml undeploy.xml priceCheck.wsdl

        file. The file generat ed from is show n in List ing 6.11 . Listing 6.11 The File Generated from

        

      undeploy.xml priceCheck.wsdl

      <! - - - - > <! - - Use t hi s f i l e t o undepl oy some handl ers/chai ns and servi ces - - > <! - - Two ways t o do t hi s: - - > <! - - j ava org. apache. axi s. ut i l s. Admin undepl oy. xml - - > <! - - f rom t he same di r t hat t he Axi s engi ne runs - - > <! - - or - - > <! - - j ava org. apache. axi s. cl i ent . AdminCl i ent undepl oy. xml - - > <! - - af t er t he axi s server i s runni ng - - > <! - - Thi s f i l e wi l l be repl aced by WSDD once i t ' s ready - - > <m:undepl oy xmlns: m="AdminServi ce"> <! - - Servi ces f rom Pri ceCheckServi ce WSDL servi ce - - > <servi ce name="Pri ceCheck" pi vot ="RPCDi spat cher"> </servi ce> </m:undepl oy>

        Putting It All Together: A Running PriceCheck Service The previous sect ions described t he WSDL t ooling in Axis, but w hat st eps m ust Al Rosen

        priceCheck

        t ake t o get t he service running?

        priceCheck.wsdl

        The first st ep, of course, is t o acquire WSDL. Al Rosen creat ed t he file by hand. I n t he next sect ion, w e w ill discuss w ays t o generat e WDSL from exist ing code, and in Chapt er 7 , w e w ill see how t o get a WSDL descript ion from a services regist ry like UDDI .

        Wsdl2java

        Al t hen issued t he com m and show n previously t o invoke t he Axis WSDL t ooling. This st ep generat ed t he files w e discussed earlier. Not e t hat Al used t he follow ing opt ions:

      • skeleton , telling WSDL2java to generate server-side files

        (skeleton, deploy.xml , and undeploy.xml)

      • messageContext priceCheck

        , because Al knew the actual Web service would use code from the InventoryCheck Web service that needed this parameter

      • package , to add package declarations to each
      • output , to put the generated files in the proper directory

        priceCheck

        Next , Al creat ed an im plem ent at ion of a service,

        PriceCheckSOAPBindingImpl.java

        generat ed file. This is t he nam e of t he class t he

        PriceCheckSOAPBindingSkeleton is coded t o invoke.

        Listing 6.12 An Implementation of the Web Service

        PriceCheck package ch6. ex1; i mport org. apache. axi s. MessageCont ext ; i mport bws. BookUt i l ; i mport com.skat est own. dat a. Product ; i mport com.skat est own. backend. Product DB; /**

      • Pri ceCheck Web servi ce, based on I nvent ory Web Servi ce
      • Creat ed by i mpl ement i ng a Pri ceCheckSOAPBi ndi ngI mpl
      • / publ i c cl ass Pri ceCheckSOAPBi ndi ngI mpl i mpl ement s Pri ceCheckPort TypeAxi s, Pri ceCheckPort Type { /**
      • Checks pri ce and quant i t y avai l abl e gi ven a product SKU
      • @param msgCont ext Thi s i s t he Axi s message processi ng cont ext
      • BookUt i l needs t hi s t o ext ract depl oyment * i nf ormat i on t o l oad t he product dat abase.
      • @param sku product SKU
      • * @ret urn A st ruct ure i ndi cat i ng pri ce and quant i t y f or t he sku

      • @except i on Except i on most l i kel y a probl em accessi ng t he DB
      • /

        publ i c Avai l abi l i t yType checkPri ce ( MessageCont ext msgCont ext , St ri ng sku)

        t hrows j ava. rmi. Remot eExcept i on{ Product DB db = nul l ; t ry{ db = BookUt i l . get Product DB( msgCont ext ) ; } cat ch ( Except i on e) { t hrow new j ava. rmi. Remot eExcept i on( e. get Message( ) ) ; } Product prod = db. get BySKU( sku) ; i f ( prod == nul l ) { t hrow new j ava. rmi. Remot eExcept i on( "Product sku: " + sku + " not f ound. ") ; }

        Avai l abi l i t yType at = new Avai l abi l i t yType( ) ; at . set Sku( sku) ; at . set Quant i t yAvai l abl e( prod. get NumInSt ock( ) ) ; at . set Pri ce( prod. get Uni t Pri ce( ) ) ; ret urn at ; } publ i c Avai l abi l i t yType checkPri ce ( St ri ng sku) t hrows j ava. rmi. Remot eExcept i on{

        "Need t o generat e WSDL wi t h - messageCont ext opt i on! ") ; } }

        InventoryCheck This im plem ent at ion is based on t he Web service you saw in Chapt er 3 . sku

        The input param et er is used t o ret rieve t he product record from t he product

        Availability

        dat abase. From t his inform at ion, an obj ect is creat ed, filled in w it h values, and ret urned t o t he request or.

        .class

        The next st ep is t o deploy t he Web service t o a server. I n t his case, Al m oved t he

        webApps

        files t o a direct ory under his Web applicat ion server and st art ed t he server. Al

        deploy.xml

        t hen updat ed t he file t o m ake sure t he proper pat h st ruct ure w as reflect ed in

        className beanMappings

        t he opt ion elem ent and t he elem ent s. ( Not e t hat t his st ep w as

      • –package AdminClient

        required even t hough Al used t he opt ion.) Al t hen invoked t he ,

        deploy.xml

        follow ing t he inst ruct ions in t he com m ent s found in t he file, deploying t he

        priceCheck Web service t o Axis. The Web service is now available t o request ors. PriceCheckTest sku

        The client applicat ion ( show n in List ing 6.3 ) sim ply t akes a from t he

        priceCheck

        com m and line and uses t he generat ed client - side st ub t o invoke for t he Web

        priceCheck service. The result s of t he are t hen print ed t o t he console.

        For exam ple, if Al ran t he com m and

        j ava ch6. ex1. Pri ceCheckTest 947- TI

        t he out put could look like t his: One 947- TI cost s: $129. 00.

        There are 36 avai l abl e.

        That 's it for generat ing Java and XML from WSDL. The point here is t hat t ooling allow ed Al Rosen t o focus on t he business applicat ion and not w orry about t he int ricacies of SOAP and Axis. Al focused on creat ing t he WSDL descript ion for t he Web service, t he act ual business logic im plem ent ing t he Web service, and a sim ple t est client . The Axis WSDL t ooling generat ed t he rest based on t he WSDL descript ion of t he Web service.

        Summarizing WSDL to Java

      Table 6.3 sum m arizes t he part s of a WSDL docum ent t hat m ap t o different pieces of t he generat ed Java and deploym ent XML.Table 6.3. How WSDL Elements Map to Generated Java and Deployment XML

      WSDL Generated Java/XML Example Elements

        <types> each

      • AvailabilityType.java

        Generate a • complexType serializer/deserial izer class

        AvailabilityType Holder.java Generate a holder class

      • Configure the

        serviceClient in the client stub with serializers/deseria lizers Generate a • BeanMapping in the deploy.xml file <portType>

      • PriceCheckPortType.java

        Generate a client- • side interface class

        PriceCheckPortTypeAxis. java Generate a server- side interface class each operation

      • Becomes a method
      • AvailabilityType checkPrice(String sku)..

        signature in the interface each input part

      • Becomes an input
      • AvailabilityType checkPrice(String sku)..

        parameter to the interface method each output

      • First part becomes

        part the return type of the method

      • AvailabilityType checkPrice(String sku)..

        Subsequent parts • become method parameters represented by holder classes for the type defined by the part fault each Generates a class Does not appear in • • PriceCheck element defining a Java exception of the same name Generates a Java • exception added to the method signature

        <binding>

      • PriceCheckSOAPBinding Stub.java

        Generates a client- •

        Generates a server- • side skeleton PriceCheckSOAPBinding Skeleton.java • Generates a pair of • option elements PriceCheckSOAPBinding Impl.java • ( className and methodName ) in the deploy.xml file each

      • call.set(HTTPTransport. ACTION, " ");

        Sets the SOAPAction • soap:operation property of the ServiceClient in the client stub from the value of the soapAction attribute Sets the handler in

      • deploy.xml

        based on the value of soap:style

      • Generates an

        implementation method in the client-side stub Generates a • skeleton method in the server-side skeleton Generates an entry • deploy.xml in the methodList <port>

      • endpointURL

        Sets the • = " http://localhost:8080/axis/servlet/AxisS endpointURL in the heck "; service class from soap:address the element

      • Generates one

        service element in deploy.xml Generates one

      undeploy.xml <service>

      • PriceCheckService.java

        Generates one • service class Generates one • deploy.xml file Generates one

      • undeploy.xml file

        Deriving WSDL from Code

        We m ent ioned in t he previous sect ion t hat Al Rosen needed t o m anually creat e t he

        priceCheck

        WSDL definit ion. For applicat ions t hat already exist , t here are alt ernat ive approaches t o com ing up w it h t he WSDL definit ion. Axis WSDL t ooling can generat e a WSDL docum ent from a Java class. Axis m akes available t he WSDL for any deployed service. You can exam ine t he WSDL by

        get ?WSDL invoking t he service using HTTP ( from a Web brow ser) w it h t he param et er.

        InventoryCheck Figure 6.5 show s t he WSDL generat ed by Axis for t he service.

      Figure 6.5. Generating the WSDL for the Web service.

        InventoryCheck

        The WSDL for t he service is generat ed by visit ing all t he chains and handlers deployed for t he service, including service- specific chains, t ransport - specific chains, and global chains. Doing so ensures t hat each com ponent of t he deploym ent is incorporat ed int o t he WSDL for t he Web service.

        The core WSDL is generat ed based on t he Java class definit ion, defining t he operat ions and m essages t hat are core t o any WSDL descript ion. Ot her det ails, such as t he

        SOAPAction value, are also det erm ined by t he deploym ent .

        Much w ork cont inues in t he area of generat ing WSDL from Java and ot her program m ing language art ifact s, such as EJBs, dat abase schem as, and so on. This is anot her area of Web services t hat is seeing a lot of effort in st andardizat ion and t ooling. We w ill see som e exam ples of ot her Web services environm ent s and t ooling in Chapt er 8 .

        Future Service Description Efforts

        WSDL is t he basis for service descript ion, but it is not t he only com ponent . WSDL describes det ails of invocat ion synt ax. There is m ore t o describe about a Web service t han j ust t he I DL- level det ails. At t his point , higher level descript ion m echanism s layered on t op of WSDL are st ill em erging; no st andards exist in t his space.

      Web Services Endpoint Language (WSEL)

        As part of t he Web Services Flow Language ( WSFL) specificat ion ( ht t p: / / w w w .ibm .com / soft w are/ solut ions/ w ebservices/ pdf/ WSFL.pdf ) , I BM hint ed at a new language, based on WSDL, t o describe non- funct ional charact erist ics of a Web service. I BM calls t his language Web Services End- point Language ( WSEL) .

        The purpose of WSEL is t o form ally m odel non- funct ional charact erist ics of a Web service—t hings like qualit y of service ( QoS) st at em ent s, privacy policy, audit ing policy, and so on. These it em s do not direct ly affect t he synt ax of t he m essage ( cert ainly not t he core part of t he m essage) , but t hey can affect w het her t he service request or chooses t o collaborat e w it h a part icular service provider. This level of service descript ion is especially im port ant for asynchronous m essage flow s. For exam ple, a WSEL- specified propert y of t he Web service could include t he expect ed response t im e, possible durat ion est im at es for t he int eract ion, or num ber of accept able ret ries. This w ould be t he basis upon w hich t he request or could est ablish t im e- out behavior and safely assum e t hat t he collaborat ion w ill not com plet e and execut e what ever rollback or com pensat ion m echanism is associat ed wit h t he int eract ion. Ot her st andards are em erging in t his space, not direct ly based on WSDL, including w ork done surrounding t he collaborat ion prot ocol profile and agreem ent m arkup language ( cppML) from t he ebXML effort ( ht t p: / / w w w .ebxm l.org/ specs/ ebCCP.pdf ) , and DAML- S from t he dam l.org group ( ht t p: / / w w w .dam l.org/ services/ dam l- s/ 2001/ 05/ ) .

        Wat ch t his space. End- point m odeling is one of t he next big areas for st andardizat ion w it hin Web services.

      Web Services Flow Language (WSFL)

        The final layer of t he service descript ion st ack is t he flow layer or orchest rat ion layer. I t is t his layer of specificat ion t hat t he WSFL addresses. WSDL is used t o describe t he det ailed inform at ion necessary t o invoke a Web service; a single Web service, WSDL has no not ion of sequencing several Web service invocat ions or ordering t he operat ion invocat ions w it hin a single Web service. The Web Services Flow Language ( WSFL) builds upon t he w ork in WSDL, describing how t o organize and orchest rat e a series of Web services invocat ions int o an overall business process or w orkflow . You w ould use WSFL t o m odel long- running m ult ist ep business collaborat ions bet w een m ult iple business part ners.

        I BM published t he WSFL specificat ion in May 2001. I t is I BM's int ent ion t o part ner w it h ot her organizat ions t o st andardize WSFL. There are ot her m echanism s t o organize and orchest rat e Web services. Microsoft , for exam ple, defines a sim ilar language called

        Web services orchest rat ion or w het her t hey ult im at ely w ill converge t o one st andard. This book, how ever, w ill briefly describe how WSFL can be used as part of t he overall service descript ion st ack.

        WSFL is an XML language som ewhat sim ilar t o WSDL. WSFL is used t o orchest rat e, or organize, t he sequencing of Web services invocat ions. Wit h WSFL, you can:

        Describe a business process that is composed of a sequence of

      • activities, some or all of which might be Web services Describe the business process itself as a Web service, specifying the • relationships between various role players in the workflow

        The excit ing aspect of WSFL is t hat it allow s new , higher- level Web services t o be creat ed by com bining or orchest rat ing ot her Web services. So, t he m ore Web services t hat are creat ed, t he m ore possibilit ies t here exist for orchest rat ing t hem int o m ore pow erful Web services. This enables a net w ork effect t o occur, m aking Web services a very pow erful concept for business process int egrat ion.

        portType

        WSFL leverages t he elem ent from WSDL t o define t he basic com ponent or act ivit y int erface in t he w orkflow syst em . The business process is t hen m odeled as a st at e m achine, w here act ivit ies are m odeled as Web service invocat ions and t he invocat ions are sequenced by st at e t ransit ion event s ( cont rol flow ) . Event ually, as m ore organizat ions adopt Web services and publish Web services for part ner consum pt ion over

        portType

        t he I nt ernet , w e w ill see st andard or service int erface definit ions em erge, t hereby allow ing organizat ions t o incorporat e and int egrat e t heir part ners' business processes int o t heir ow n w orkflow s. Unt il t hese st andard service int erface definit ions begin em erging, w e w ill see WSFL used predom inant ly for orchest rat ing int ernal business processes and act ivit ies. So, w at ch t he Web services orchest rat ion space, t oo. The final piece of t he Web services puzzle w ill appear w hen it is possible t o m odel a business process, including sequencing, com pensat ion m echanism s, branching, and so on, using a st andard support ed by a variet y of t hird- part y t ooling. Furt herm ore, because Web services t echnology fost ers process int egrat ion bet w een business part ners, Web services orchest rat ion st andards w ill allow an organizat ion t o form alize how it collaborat es w it h it s business part ners.

        Completion Criteria for Web Services Standardization Efforts

        Wit h t he advent of WSEL and WSFL augm ent ing WSDL, w e observe a very im port ant pat t ern em erging. Given t he assert ion t hat all Web services t echnologies m ust follow t he nam ing pat t ern WS* L, w e can conclude t hat w hen 26 specificat ions are st andardized, one for each let t er of t he alphabet , t hen Web services w ill be " done" .

      Summary

        We began t his chapt er w it h a quest ion: How does t he request or know w hat m essage form at should be used t o invoke a Web service? We m ot ivat ed t he role of service descript ion w it hin a service- orient ed archit ect ure and explained how service descript ion w as t he basis for t he publish, find, and bind operat ions. We review ed t he charact erist ics of a w ell- defined service and out lined a service descript ion st ack. The basis of a w ell- defined service is an I DL- level descript ion of it s int erface, described using t he Web using Web service descript ions for several of Skat esTow n's services. We also review ed how WSDL relat es t o Java program m ing language art ifact s, including building Java client - side proxies and server- side skelet ons from a WSDL definit ion and generat ing WSDL definit ions from exist ing Java program asset s. We concluded t his chapt er by discussing t he fut ure direct ion of t he Web service descript ion st ack, in part icular t he st andardizat ion effort s around t he Web Services Endpoint Language ( WSEL) and t he Web Services Flow Language ( WSFL) . I n t he next chapt er, w e w ill review t he role of service regist ries in a service orient ed archit ect ure, and in part icular, out line t he role of t he Universal Descript ion Discovery and I nt egrat ion ( UDDI ) st andard.

      • The Role of Service Discovery

        The Role of Registries

      • UDDI • Private UDDI Registries • What's New in UDDI Version 2.0? • Using WSDL with UDDI •

        This chapt er int roduces t he t opic of discovering Web services and, in part icular, t he role of a services regist ry in a service- orient ed archit ect ure. We discuss several alt ernat ives t o service regist ries, and in part icular focus on t he Universal Descript ion, Discovery and I nt egrat ion ( UDDI ) st andard. Aft er explaining t he core API s in UDDI Version 1.0 and highlight ing t he im port ant API s in UDDI Version 2.0, w e discuss t he role of UDDI as a privat e services regist ry, including t he convent ion of st oring WSDL service descript ions in a UDDI regist ry.

        We also int roduce som e business part ners of Skat esTown and discuss how a service regist ry such as UDDI can be used t o help int egrat e t heir Web services. I n t he last sect ion, w e'll int roduce sam ple Java code t hat gives an exam ple of how t hese part ners can be pulled t oget her in a sam ple supply chain.

      The Role of Service Discovery

        I n previous chapt ers, w e have exam ined SOAP and service descript ion m echanism s. But , how does t he request or know w here t o send t he SOAP m essage? What kind of m essage should t he request or send t o properly invoke t he Web service? These quest ions can be addressed by t he Web service's descript ion. I n a service- orient ed archit ect ure, Web services m et adat a ( especially it s service descript ion) is key t o m aint aining loose coupling bet w een service request ors and service providers.

        I n Chapt er 6 , " Describing Web Services," w e discussed Web Services Descript ion Language ( WSDL) , t he m ost popular m echanism of service descript ion for Web services. But in order for a Web service t o be invoked, it m ust be discovered som ehow . How w as t he business part ner discovered, est ablishing t he pot ent ial relat ionship bet w een service request or and service provider? How did t he service request or find out about t he services provided by a service provider? How did t he request or obt ain t he WSDL service descript ion from t he service provider? Addressing t hese quest ions is t he role of t he

      The Role of Registries

        As w e look at t he evolut ion of obj ect program m ing and com ponent program m ing m odels, it is clear t hat t he concept of an obj ect or com ponent regist ry is an essent ial elem ent in t he fram ew ork, facilit at ing t he discovery and t he use of com ponent s. I m agine t rying t o w rit e Java code w it hout having access t o a brow sable set of JavaDocs, or w orking in Sm allt alk wit hout having access t o a class browser. I f you consider t he Web services concept as an evolut ion of com ponent program m ing, it follow s t hat for t he purpose of service discovery, you need t o have access t o regist ries of business and service descript ions t hat can be brow sed and queried.

        Recall t he service- orient ed archit ect ure from Chapt er 1 , repeat ed here in Figure 7.1 .

      Figure 7.1. Service-oriented architecture.

        I n a service- orient ed archit ect ure, t he service provider publishes t he service descript ion of a Web service t o a service regist ry. The service request or queries t he service regist ry ( t hrough a find operat ion) t o ret rieve one or m ore service descript ions t hat m eet cert ain crit eria, fulfilling a st ep w it hin t he applicat ion's business processes. The service descript ion cont ains sufficient inform at ion t o allow a service request or t o bind t o and invoke t he Web service.

      Service Discovery at Design Time and Runtime

        I t is im port ant t o not e t hat service discovery can happen at applicat ion design t im e or at runt im e. At applicat ion design t im e, a hum an designer, t hrough a brow ser or ot her user int erface, perform s a find operat ion on a service regist ry, exam ines t he result of t he find, and incorporat es t he service descript ion ret urned by t he find int o applicat ion logic. We discussed in Chapt er 6 som e of t he t ooling t hat can consum e WSDL service descript ions and generat e code for int egrat ion w it h t he applicat ion.

        I n m any cases, t he service int erface definit ion is used t o build a proxy t hat t he applicat ion logic uses t o invoke t he Web service and consum e it s response. The act ual service im plem ent at ion, including net w ork locat ion and ot her propert ies, such as w hich net w ork prot ocol t o use, is left unbound at design t im e, t o be det erm ined at runt im e. At runt im e, t hen, t he applicat ion it self issues a find operat ion against t he service regist ry t o locat e one or m ore service im plem ent at ion definit ions t hat m at ch t he service int erface definit ion used by t he applicat ion. Based on applicat ion logic such as best price, best t erm s, and so on, t he applicat ion chooses w hich Web service from am ong t he result s of t he find operat ion t o invoke, ext ract s net w ork locat ion and ot her inform at ion from t he service im plem ent at ion definit ion, and invokes t he Web service.

        Multiple Mechanisms of Service Discovery

        The role of t he service regist ry in a service- orient ed archit ect ure can be fulfilled by several different m echanism s. Recall t hat t he purpose of t he regist ry is t o provide m echanism s by w hich t he service provider can deliver service descript ion( s) t o service request ors.

      Figure 7.2 illust rat es a cont inuum of service descript ion t echniques.Figure 7.2. Kinds of service registries.

        There is a t rade- off here bet w een sim plicit y of t he regist ry m echanism and t he sophist icat ion of t he publishing/ searching t echniques. Let 's briefly discuss each of t hese point s on t he cont inuum . The sim plest approach is for t he service provider t o direct ly send t he service descript ion t o t he service request or. This approach uses t ried- and- t rue t echniques such as e- m ail, FTP, or even " sneaker- net " t o file- t ransfer t he service descript ion t o t he service request or. This approach is useful, part icularly if t he service request or already has a business relat ionship w it h t he service provider. This approach is very sim ple—in fact , t here really is no regist ry per se; m anual t echniques using net w ork prot ocols im plem ent t he publish and find operat ions. How ever, t he approach is not very dynam ic and cert ainly provides lit t le opport unit y for anonym it y. I f for som e reason t he descript ion of t he service changes, it becom es m ore difficult for t he service provider t o com m unicat e t his t o any and all service request ors t hat use t hat service. This approach does not yield very loosely coupled syst em s; t he applicat ion m ust be rew orked in order t o change w hich business part ner's Web service is invoked. Of course, t he service request or could cache t he service descript ions in som e sort of

        Many Web services runt im es, including Axis, provide a m echanism by w hich t he Web Service descript ion can be ret rieved using a sim ple HTTP GET operat ion. I n Chapt er 6 , we show ed how t he ?WSDL param et er can be used t o ret urn t he WSDL for any Web service deployed t o Axis.

        The second approach uses basic Web t echniques t o publish and advert ise Web service descript ions t o a Web sit e. I n t his case, t he Web sit e act s as a service regist ry, and t he publish operat ion is sim ply an act of Web publicat ion. A sim ple brow ser can ret rieve a list of service descript ions and t he find operat ion is com plet e. Sim ple t echniques such as t hese provide t he basics of a find operat ion, and in m any cases t his basic approach is sufficient for t he request or t o obt ain t he service descript ion.

        Techniques such as I BM's ADS or Microsoft 's .NET DI SCO provide im provem ent s on t he sim ple HTTP GET. Wit h t his t echnique, t he service provider publishes service descript ions t o one or m ore Web sit es, using one of t he ADS or DI SCO convent ional file form at s. The service provider t hen com m unicat es t he URL of one of t hese Web sit es t o pot ent ial service request ors. I n fact , even t hat st ep is not necessary, because DI SCO and ADS have been built w it h Web craw lers in m ind. So, j ust as Web craw ling built up direct ories of t he World Wide Web, so could Web craw lers build up direct ories for t he " Web service" Web. Wit h ADS or DI SCO, t he service request or uses HTTP GET t o do a find operat ion. The result of t he find operat ion is a list of service descript ions. I t is now up t o t he service request or t o det erm ine w hich of t he Web services is pert inent t o t he business t ask at hand and invoke t hat Web service. Alt hough t his approach does rem ove som e of t he updat e concerns for t he service provider, it st ill doesn't give t he service request or m uch ext ra inform at ion about t he purpose of t he Web service, nor does it give m uch addit ional inform at ion about t he service provider. The t hird approach is a reposit ory of WSDL docum ent s. This is sim ilar in spirit t o t he previous kind of service regist ry in t hat it uses HTTP GET as t he prim ary m eans by w hich t he service request or ret rieves t he service descript ion. How ever, a WSDL reposit ory, such as SalCent ral ( w w w .salcent ral.com ) , addit ionally offers im proved facilit ies for t he service request or, such as not ificat ion when a service descript ion has changed. SalCent ral also offers good searching t ools, including a rudim ent ary cat egorizat ion t echnique. XMet hods ( w w w .xm et hods.com ) is anot her exam ple of a public regist ry of WSDL docum ent s. The m ost sophist icat ed approach t o service regist ries is Universal Descript ion Discovery and I nt egrat ion ( UDDI ) ( ht t p: / / w w w .uddi.org ) . UDDI provides very sophist icat ed publish and find capabilit ies. UDDI includes m uch m ore inform at ion t han j ust t he service descript ion, including business m et adat a and t axonom ies of businesses and services. UDDI not only answ ers t he quest ion, " Where is t he Web service locat ed?" UDDI also addresses quest ions such as, " How does t he request or know w hat business is providing t he service?" Unlike t he ot her t echniques, UDDI does not depend on any one part icular m echanism of service descript ion.

        As we saw in Chapt er 1 , " Web Services Overview ," t he Web services com m unit y in t he W3C has described t w o layers in t he service discovery st ack: an inspect ion layer and a discovery ( UDDI ) layer. So far, no st andard has been proposed or em erged at t he inspect ion layer. We expect t hat som et hing in t his space w ill em erge t o augm ent UDDI at t he sim pler end of t he spect rum .

        Because t here is only one st andard for service discovery, t his chapt er w ill focus on t he UDDI specificat ion for service regist ry and how it is used. We w ill exam ine UDDI by review ing it s API and m aj or dat a st ruct ures found in Version 1.0 of t he UDDI specificat ion. Throughout t he chapt er, w e discuss t he im port ant role of t he UDDI

        Business Regist ry ( w w w .uddi.org ) . We also exam ine t he role of privat ely host ed UDDI regist ries as different im plem ent at ions of t he UDDI specificat ion, addressing different service discovery needs. Having covered t hese roles, we can discuss t he new feat ures int roduced in UDDI Version 2.0. We w ill conclude t his chapt er w it h an explanat ion of t he best pract ices for regist ering WSDL- based Web service descript ions in UDDI .

        Scenario Updates

        As Skat esTown sells m ore skat eboards, it s net w ork of suppliers expands. Let 's exam ine som e of t he new part ners Skat esTow n now deals w it h:

        The Sports Equipment Manufacturing Consortium (SEMC) is a self-funded

      • consortium of the major manufacturers of sports equipment, whose

        mission is to establish a set of e-Business standards for this

        industry. SkatesTown belongs to the consortium and has started

        implementing and using the SEMC standards. WeMakeIt Inc. is a large manufacturer of industrial components. Its
      • business is to be a components supplier to a wide variety of different finished goods manufacturers. WeMakeIt Inc. manufactures a

        large range of components in its manufacturing sites in the USA,

        Europe, and Asia. Of particular interest to SkatesTown, WeMakeIt Inc. manufactures a line of small nylon wheels and wheel bearings ideal for skateboards. Joanna Pravard is the lead Web services developer for WeMakeIt Inc. Joanna is responsible for all of WeMakeIt Inc.'s

        Web services technologies, including its UDDI registries and its

        entry in the UDDI Business Registry.

        A recently created e-marketplace, called e-Torus, has formed to

      • provide efficient buying and selling of wheels and wheel bearings components to finished goods manufacturers. As part of the e- marketplace, e-Torus runs a private UDDI registry listing all the

        manufacturers of wheels, bearings, and related components. This

        private UDDI is also a place where service interface standards are established for the marketplace, making B2B buying and selling of these components more efficient and less error prone. Al Rosen of Silver Bullet Consulting "discovered" e-Torus and got • SkatesTown to use their e-marketplace services. It is through e-Torus that SkatesTown established its business relationship with WeMakeIt Inc. Some smaller manufacturers, competing with WeMakeIt Inc. in the small • wheels and related components e-marketplace, are also briefly introduced to illustrate the benefits of dynamic bind operations. This list includes wheel manufacturers, MakeCircles Inc. and

        WheelsMadeHere.

      UDDI

        I n early 2000, as t he idea of Web services began gaining m om ent um w it hin t he com m unit y, it becam e clear t hat Web services regist ries w ere going t o be essent ial for t he concept t o becom e pract ical. Furt herm ore, in view of t he m ovem ent t ow ards open st andards in t he com m unit y, anyt hing but a st andard int erface and search m echanism for t hese regist ries w ould be unaccept able. Such a regist ry st andard w ould have t o be endorsed by several, if not all, of t he large soft w are providers, and adopt ed by t he various indust ries. Thus, t he UDDI init iat ive, t he result of several m ont hs of collaborat ion bet w een represent at ives from Ariba, I BM, and Microsoft st art ing in t he spring of 2000, w as born and form ally announced on Sept em ber 6, 2000. Support for UDDI has expanded beyond t he original t hree com panies. Current ly, t he UDDI proj ect ( ht t p: / / w w w .uddi.org ) involves a com m unit y of m ore t han 310 com panies. The purpose of UDDI is t o facilit at e service discovery bot h at design t im e and dynam ically at runt im e. Consequent ly, t he UDDI proj ect runs a public online business ( and corresponding services) regist ry, w hich first w ent live on May 2, 2001. This regist ry is referred t o as t he UDDI Business Regist ry. The UDDI Business Regist ry act ually consist s of t w o replicat ed regist ries current ly host ed by t w o com panies ( I BM and Microsoft ) called t he UDDI Operat ors . Hew let t - Packard has j oined t he Operat ors group but has not released it s regist ry as of t his w rit ing. More regist ry Operat ors are expect ed t o j oin t he Operat ors group. Becom ing a UDDI regist ry Operat or involves som e st rict agreem ent s about dat a replicat ion, dat a privacy, and policies. From a regist ered business perspect ive and from a user perspect ive, t he requirem ent is t hat different Operat or regist ries should be t heoret ically indist inguishable. Businesses can regist er w it h any UDDI Operat or, and t heir inform at ion w ill be replicat ed t o t he ot her Operat ors' regist ries. As a result , users can search any Operat or sit e and find businesses regardless of which Operat or t hese businesses used t o regist er. There are, how ever, som e subt le issues involved w it h t he decision as t o w hich Operat or t o use t o regist er your business. For exam ple, som e Operat ors m ight ask for addit ional opt ional inform at ion t hat is not required by UDDI ( such as surveys or m arket ing inform at ion) . This inform at ion is not replicat ed t o ot her Operat ors. Anot her fact t o keep in m ind is t hat once you regist er wit h an Operat or, all updat es t o your inform at ion m ust be perform ed t hrough t hat Operat or. This is t he case because different Operat ors im plem ent different securit y and aut hent icat ion policies, so aut hent icat ion inform at ion cannot be easily replicat ed.

        UDDI is m ore t han a business and services regist ry, however. I t also defines a set of dat a st ruct ures and an API specificat ion for program m at ically regist ering and finding businesses, services, bindings, and service t ypes. I n t ypical Web services scenarios, Web service providers w ill w ant t o publish t heir business and service descript ions t o a regist ry, and service request ors, w het her at design t im e or runt im e, w ill w ant t o query t he regist ry for service descript ions. The UDDI API specificat ion, t herefore, provides a set of publicat ion API s t o regist er services and inquiry API s t o find services. These w ill be explored in t he follow ing sect ions, as Skat esTow n decides t o st art using UDDI t o regist er it self and find business part ners. I n addit ion t o providing a program m at ic API , UDDI regist ry Operat ors each provide a Web- based user int erface for regist ering, m anaging, and finding businesses and services in t he regist ry. These Web sit es provide a subset of t he program m at ic API and are relat ively self- explanat ory, once you have m ast ered t he concept s int roduced in t his chapt er. Their use w ill be covered in t he sect ion " Using t he UDDI Web Brow ser

        I nt erface ." As of t his w rit ing, I BM had it s UDDI Web sit e at ht t p: / / w w w .ibm .com / services/ uddi and Microsoft at ht t p: / / uddi.m icrosoft .com . Of

        course, all t he operat or nodes are accessible from ht t p: / / w w w .uddi.org .

        I n t his sect ion, w e'll first exam ine som e t ypical requirem ent s for a regist ry of m et adat a, defining som e t ypical dat a elem ent s and operat ions. We w ill t hen provide an overview of t he UDDI dat a st ruct ures and API , relat ing t hem t o t he original requirem ent s. We w ill also explore som e com m on UDDI operat ions t hat can be perform ed t hrough t he Web brow ser- based int erface t o UDDI , as provided by t he m ain UDDI Operat ors. I n doing so, w e w ill int roduce t he m ain t hem e of t he Skat esTow n scenario t hat w ill be used t hroughout t his chapt er. The UDDI Registry Requirements: Overview Regist ries in general, w het her for soft w are com ponent s, services, or ot herw ise, have som e basic requirem ent s:

        A set of data structure specifications for the metadata to be stored • in the registry A set of Create, Read, Update, Delete (CRUD) operation specifications • for storing, deleting, and querying the data in the registry

        Com m on regist ry requirem ent s for t he m et adat a are:

        Ownership and containment (I usually own the data I publish, and all • the subdata that is contained within, unless I reassign ownership.) Categorization (Data can be classified in one or more categories, • mainly to facilitate searching and organization.) A logical referencing mechanism (I can use references as pointers to • other parts of the registry.)

        Com m on regist ry requirem ent s for t he operat ions are:

        Authentication for operations that change information and for public

      • registries Open access for read and query operations
      • The regist ry part of UDDI is no different : I t has an inform at ion m odel t hat represent s t he dat a st ruct ure specificat ions and an API for t he operat ion specificat ions. The UDDI inform at ion m odel w as designed t o be flexible and ext ensible t o allow for any user defined service descript ion m odels. Because t he UDDI specificat ion is an ongoing process of refinem ent and ext ension, t he bulk of t his chapt er w ill describe UDDI Version 1.0 ( V1) , available at t he UDDI Web sit e. Fut ure versions w ill only ext end t he current version w it h m ore funct ionalit y, w hile t aking care of issues such as replicat ion, versioning, and securit y. The sect ion " What 's New in V2 " w ill describe t he UDDI ext ensions proposed in V2. The UDDI Data Structures: Overview Version 1.0 of t he UDDI specificat ion allows ent it ies such as businesses and organizat ions t o regist er public inform at ion about t hem selves and det ails of t he services t hey offer. I t also allow s ent it ies such as businesses, st andards bodies, and indust ry groups t o regist er inform at ion about t he t ypes of services t hey have defined, about st andards and abst ract ions, and t o refer t o t hem by t heir assigned ident ifiers. I n effect , it is as if UDDI is offering t w o different regist ries: a business regist ry and a reference t ype regist ry.
      Correspondingly, UDDI has at it s core t w o fundam ent al root dat a st ruct ures:

        businessEntity and t Model .

        The businessEntity Data Structure Business ent it y inform at ion is concept ually divided int o w hat 's com m only know n as Whit e, Yellow , and Green pages:

        White pages contain general contact information about the entity. The • SkatesTown entry would contain its name, address, and contact information such as phone, fax, and e-mail. Yellow pages contain classification information about the types and • location of the services the entity offers. Again, for SkatesTown, this could be their classification as a sports equipment manufacturer and retailer, and as a skateboard manufacturer and retailer.

        Green pages contain information about the details of how to invoke

      • the offered services. If SkatesTown were to offer its catalog online,

        its Green pages entry would have a reference to its catalog URL.

        I t is im port ant t o not e t hat t his is a concept ual m odel only, and t hat UDDI does not specify any part icular st orage m odel. Concept ually, how ever, an ent it y's Whit e pages ent ry w ill cont ain classificat ion inform at ion t hat point s t o it s place in t he various Yellow pages, and an ent it y's business service ent ries w ill cont ain im plem ent at ion inform at ion t hat point s t o ent ries in t he Green pages. This is reflect ed in t he det ails of t he

        businessEntity businessEntity

        st ruct ure ( see Figure 7.3 ) . The elem ent , in addit ion t o

        businessServices

        various cont act , ident ifier, and t axonom y inform at ion, cont ains a

        businessService businessService

        elem ent , w hich is a cont ainer for elem ent s. A

        bindingTemplates

        elem ent in t urn cont ains a elem ent , w hich is a cont ainer for

        bindingTemplate bindingTemplate tModel elem ent s. Finally, ent ries point t o ent ries.

        The det ails of t hese st ruct ures w ill be explored in t he next sect ions.

      Figure 7.3. UDDI information model. The Data Structure

        tModel tModel The ot her im port ant st ruct ure in t he UDDI inform at ion m odel is t he elem ent .

        Ent ries in t he Green pages, w here invocat ion det ails are described, are act ually business- specific binding det ails for service t ypes and ot her abst ract ions defined elsew here. These reusable abst ract ions are referred t o as t echnology m odels, and t heir corresponding

        tModel

        UDDI dat a st ruct ure is t he elem ent . This elem ent allow s indust ry groups, st andards bodies, and individual businesses t o specify reusable abst ract definit ions of service t ypes t hat ot hers can use and com bine, creat ing, in effect , a signat ure for a service.

        I n t he UDDI ident ificat ion schem e, each inst ance of t he four t ypes of ent ries is assigned a unique ident ifier by t he UDDI node upon init ial regist rat ion. I n addit ion, according t o t he

        businessService

        UDDI cont ainm ent schem e, each inst ance of a cont ained st ruct ure (

        bindingTemplate

        and ) holds a key reference t o it s cont aining ent it y ( in t his case,

        businessEntity businessService and , respect ively) in a st rict parent - child relat ionship.

        These ident ifiers are Universal Unique I dent ifiers ( UUI Ds) t hat follow t he OSF Dist ribut ed Com put ing Environm ent ( DCE) convent ions ( ht t p: / / w w w .osf.org/ onlinepubs/ 9629399/ apdxa.ht m ) . They follow t he fam iliar 8- 4- 4- 4-

        tModel

        12 pat t ern ( such as F775A3A6- FF3E- 4B85- B1DE- F0F99D0E2C6D) . I n addit ion,

        uuid references are given t he : URN qualifier.

        Finally, it w as deem ed im port ant t hat privat e ( t hat is, non- Operat or but ot herw ise UDDI

        businessEntity

        com pat ible) UDDI regist ries be able t o ext end t he st ruct ure t o include

        businessEntityExt

        dat a for t heir ow n purposes. To t his end, t he st ruct ure was specified. UDDI regist ry Operat ors, how ever, w ill not provide ext ensions in t heir publicly online available business ent it y dat a. The UDDI API: Overview

        I n addit ion t o defining t he dat a st ruct ures t o be st ored in t he regist ry, t he UDDI specificat ion provides t w o m ain t ypes of API operat ions: t he Publicat ion API and t he I nquiry API . These API s define a set of 20 SOAP m essages over HTTP or HTTPS t hat m ust be underst ood by any UDDI - conform ant regist ry. The SOAP body of t he API m essages and responses are XML st ruct ures defined in t he UDDI specificat ion. The Publicat ion API is an aut hent icat ed set of operat ions t hat allow s organizat ions t o publish inform at ion, w het her business, service, im plem ent at ion, or service t ype specificat ion, t o t he UDDI regist ry. Aside from requiring an aut hent icat ion t oken and t he use of t he HTTPS prot ocol in t he aut hent icat ed operat ions, UDDI does not specify an aut hent icat ion m et hod. I nst ead, each Operat or m ust provide t heir ow n aut hent icat ion m echanism .

        The I nquiry API is a non- aut hent icat ed public set of operat ions t hat allow s users t o ext ract inform at ion out of t he UDDI regist ry. I nquiries can follow t w o different pat t erns:

        find

        a brow sing pat t ern t o find general inform at ion ( t he operat ions) , usually follow ed by

        get_Detail a drill- dow n pat t ern t o find specific det ail inform at ion ( t he operat ions) . businessEntity businessService

        Corresponding t o t he four st ruct ure t ypes ( , ,

        bindingTemplate tModel save_business

        , and ) , UDDI provides four save operat ions ( ,

        save_service save_binding save_tModel

        , , and ) , four delet e operat ions

        delete_business delete_service delete_binding delete_tModel

        ( , , , and ) , four find

        find_business find_service find_binding find_tModel

        operat ions ( , , , and ) and four

        get_Detail get_businessDetail get_serviceDetail

        operat ions ( , ,

        get_bindingDetail get_tModelDetail , and ) ; see Table 7.1 .

      Table 7.1. The CRUD API messages Defined by the UDDI Spec

      Business Service Binding tModel

        save_business save_service save_binding save_tModel Save/Update delete_business delete_service delete_binding delete_tModel

        Delete find_business find_service find_binding find_tModel

        Find get_businessDetail get_serviceDetail get_bindingDetail get_tModelDetail

        GetDetail You can use t he save operat ions t o creat e a new ent ry or t o updat e an exist ing one.

        When creat ing a new ent ry, t he ent ry ident ificat ion key param et er is not supplied in t he call, but inst ead is assigned by t he Operat or and ret urned in t he Operat or's response. To updat e an exist ing ent ry, t his Operat or- assigned key is supplied in t he call. The delet e operat ions t ake t he Operat or assigned keys as param et ers and rem ove t he

        delete_tModel

        corresponding ent ries from t he regist ry. The operat ion is an except ion t hat w ill be discussed in t he sect ion " The Delet e Operat ions ." The find operat ions are passed a set of search crit eria and generally ret urn a ( possibly em pt y) list st ruct ure cont aining inform at ion about ent ries t hat m at ch t he search crit eria.

        get_detail

        The operat ions are passed a list of ident ifiers and ret urn det ailed inform at ion about t he ent ries referred t o by t he supplied keys. The API provides one addit ional

        get_detail get_businessDetailExt

        operat ion, , t o allow t he ret rieval of ext ended business inform at ion from non- Operat or nodes t hat im plem ent t hese ext ensions. I n addit ion, because t he Publicat ion API is a set of aut hent icat ed operat ions, w here aut hent icat ion is t oken- based, t he API provides t w o aut hent icat ion operat ions,

        get_authToken discard_authToken and . getRegisteredInfo

        Finally, is an aut hent icat ed operat ion t hat ret urns all t he

        businessEntity tModel and keys regist ered by an accredit ed user.

        I n t he next sect ions, w e w ill cover in det ail t he UDDI dat a st ruct ures and API and go t hrough exam ples as Skat esTow n regist ers it s inform at ion so t hat pot ent ial client s can locat e it , and so t hat it can locat e pot ent ial suppliers. I t is im port ant t o not e t hat it is possible t o perform m ost of t he Publicat ion and I nquiry

        find get_Details

        API funct ions ( such as som e and operat ions) t hrough t he individual Operat ors' Web sit es. The next sect ion w ill go t hrough such an exam ple w hile int roducing one of t he m ain scenarios t hat w ill be used t hroughout t he chapt er. I n addit ion t o being m ore com plet e and pow erful t han w hat 's available t hrough t he brow ser int erface, how ever, t he API is int ended t o allow businesses t o perform all t he operat ions program m at ically, in order t o facilit at e dynam ic ( runt im e) service discovery. Keep t hat in m ind as w e go t hrough t he next exam ples.

        Using the UDDI Web Browser Interface Before w e exam ine t he API in det ail, it w ill be useful t o briefly explore t he brow ser int erface t o UDDI . UDDI Operat ors, as part of t heir responsibilit y t o t he UDDI consort ium , have each provided a free public Web- based int erface t o t heir UDDI business regist ries. This int erface allow s organizat ions t o regist er t heir businesses, along w it h cont act inform at ion and services provided. Service t ype definit ions can also be ent ered ( t hese w ill be covered in m ore det ail lat er in t he sect ion " The UDDI t Model Concept " ) .

        I n t his next exam ple, Skat esTow n w ill regist er it s business and t he cont act inform at ion of Dean Carroll, t he com pany's chief t echnology officer. I t w ill also regist er it s online cat alog as an HTTP- based Web service, and classify it under t he Nort h Am erican I ndust ry Classificat ion Syst em ( NAI CS) t axonom y ( w e w ill discuss t axonom ies in m ore det ail in t he sect ion " More on Classificat ion and Cat egorizat ion " ) . Alt hough t his basic exam ple w ill be explored in m ore det ail and expanded significant ly t hroughout our discussion of t he UDDI API , it provides t he m ain t hem e for t he UDDI usage m odel.

        The first st ep in using t he UDDI regist ries is t o regist er an I D and obt ain an aut hent icat ion t oken. Bot h I BM ( ht t ps: / / w w w -

        3.ibm .com / services/ uddi/ prot ect / regist ry.ht m l ) and Microsoft

        ( ht t p: / / uddi.m icrosoft .com / regist er.aspx ) regist ries require a usernam e and passw ord as a m et hod of aut hent icat ion. I n t he follow ing exam ple Dean Carroll, Skat esTow n CTO, w ill use t he I BM Test regist ry.

      Figure 7.4 show s t he regist rat ion page. Dean ent ers skat est ow n as t he user I D and fills

        out t he rest of t he required inform at ion. Once regist ered, Dean can st art t he process of adding a new business ent ry. Having ent ered t he business nam e, he t hen has t he opt ion of ent ering a business descript ion, business cont act inform at ion, and business locat or inform at ion, w hich allow s ot her users t o find Skat esTow n t hrough a variet y of keyw ord searches on t he Add New Business Web page.

      Figure 7.4. The UDDI Registration Web page. A variet y of cont act inform at ion can be ent ered, including descript ions, phone num bers,

        e- m ail addresses, and m ailing addresses. Finally, t he business is cat egorized by ent ering locat or inform at ion. The UDDI Version 1.0 specificat ion provides a set of pre- det erm ined t axonom ies t o be used for t his purpose ( see t he sect ion " More on Classificat ion and

        

      Cat egorizat ion " ) . For t his inst ance, Dean w ill use t he NAI CS t axonom y and drill dow n t o

      t he 33992 cat egory, " Sport ing and At hlet ic Goods Manufact uring" ( see Figure 7.5 ) .

      Figure 7.5. The NAICS Category 33992 Selection Web page. The next st ep is t o ent er a Web service regist rat ion. I n t his case, Dean w ill regist er t he online Check Order St at us Web service provided by Skat esTow n. The service regist rat ion page allow s for a variet y of inform at ion t o be ent ered about t he service, including a descript ion ( w hat is t his service?) , access point inform at ion ( how do I invoke it ?) and locat or inform at ion ( w hat kind of service is it ?) .

        Figures 7.6 and 7.7 show a high- level view of all t he Skat esTow n business and service inform at ion t hat w as ent ered, respect ively.

      Figure 7.6. The UDDI Business Details Web page.Figure 7.7. The UDDI Service Details Web page. I t is int erest ing t o not ice t hat in bot h cases, t he UDDI regist ry has generat ed unique keys for t he business ent ry and t he service ent ry. I n addit ion, it has generat ed a URL for t he business descript ion ( under t he t it le Discovery URL) t hat ret urns t he follow ing XML docum ent , describing t he Skat esTow n UDDI business ent ry:

        <?xml versi on="1. 0" encodi ng="ut f - 8" ?> <busi nessDet ai l generi c="1. 0" xmlns="urn: uddi - org: api " operat or="www. i bm.com/servi ces/uddi " t runcat ed="f al se"> <busi nessEnt i t y aut hori zedName="0100003BG0" operat or="www. i bm.com/servi ces/uddi " busi nessKey="ED88D790- AA0E- 11D5- 98D0- 0004AC49CC1E"> <di scoveryURLs> <di scoveryURL useType="busi nessEnt i t y"> ht t p: //www- 3. i bm.com/servi ces/uddi /t est regi st ry/uddi get ? busi nessKey=ED88D790- AA0E- 11D5- 98D0- 0004AC49CC1E </di scoveryURL> </di scoveryURLs> <name>Skat esTown</name> <cont act s> <cont act useType="CTO"> <personName>Dean Carrol l </personName> </cont act > </cont act s> <busi nessServi ces> busi nessKey="ED88D790- AA0E- 11D5- 98D0- 0004AC49CC1E"> <name>Check Order St at us</name> <descri pt i on xml: l ang="en">Check your order st at us onl i ne </descri pt i on> <bi ndi ngTempl at es> <bi ndi ngTempl at e bi ndi ngKey="C8061C60- AA10- 11D5- 98D0- 0004AC49CC1E" servi ceKey="C8013A60- AA10- 11D5- 98D0- 0004AC49CC1E"> <descri pt i on xml: l ang="en"> Thi s i s a web based ( ht t p) order st at us servi ce </descri pt i on> <accessPoi nt URLType="ht t p"> ht t p: //www. skat est own. com/servi ces/orderSt at us</accessPoi nt > <t Model I nst anceDet ai l s> <t Model I nst anceI nf o t Model Key="UUI D: 68DE9E80- AD09- 469D- 8A37- 088422BFBC36"> </t Model I nst anceI nf o> </t Model I nst anceDet ai l s> </bi ndi ngTempl at e> </bi ndi ngTempl at es> <cat egoryBag> <keyedRef erence t Model Key="UUI D: C0B9FE13- 179F- 413D- 8A5B- 5004DB8E5BB2" keyName="Sport i ng and At hl et i c Goods Manuf act uri ng" keyVal ue="33992"> </keyedRef erence> </cat egoryBag> </busi nessServi ce> </busi nessServi ces> <cat egoryBag> <keyedRef erence t Model Key="UUI D: C0B9FE13- 179F- 413D- 8A5B- 5004DB8E5BB2" keyName="Sport i ng and At hl et i c Goods Manuf act uri ng" keyVal ue="33992"> </keyedRef erence> </cat egoryBag> </busi nessEnt i t y> </busi nessDet ai l >

        We w ill be seeing m ore of t his t ype of XML docum ent as w e expand on t he exam ple in t he next sect ions, by exploring t he UDDI dat a st ruct ure and API .

        The UDDI Concept tModel

        Before w e begin publishing m ore services t o UDDI , w e need t o explore t he concept of a

        tModel in det ail, because it is essent ial t o how services are described.

        What Is a ?

        tModel

        I n order t o invoke a service, you som et im es need t o know a large am ount of det ail in t erm s of docum ent form at s, t ransport prot ocols, input and out put param et ers, URNs, business process, and so on. These det ails in general could be supplied in t he descript ion of t he service im plem ent at ion. I n Chapt er 6 , List ing 6.1 , you saw an exam ple of a WSDL abst ract reusable inform at ion ( t he service int erface definit ion) and concret e im plem ent at ion inform at ion ( t he service im plem ent at ion definit ion) . I f soft w are engineering has t aught us one t hing in t he last decade, it is t he pow er of abst ract ion and re- use. Suppose t hat anot her com pany belonging t o t he sam e SEMC consort ium w ere t o im plem ent an ident ical service. I t w ould have t o repeat t he sam e bulk of inform at ion in it s WSDL docum ent , w it h t he only difference being t he endpoint address for t he im plem ent at ion of it s SOAP service. Suppose, how ever, t hat t he SEMC consort ium w ere t o abst ract out t he service int erface definit ion of t he WSDL docum ent and publish it as a consort ium st andard. This w ould enable bot h com panies ( and any ot her com pany in t he consort ium ) t o reference t hat abst ract definit ion and only have t o supply t heir concret e im plem ent at ion endpoint . That abst ract service int erface definit ion is, in essence, a

        tModel perfect exam ple of a .

        I n general, t hese t ypes of service specificat ions could be applicable in several different places for different services, or for different bindings for t he sam e service. They can also be specified by an indust ry consort ium as w e saw in t he exam ples, a st andards body, or a large corporat ion for t he use by it s suppliers. Thus conform ance t o a know n and

        tModel

        predefined set of specificat ions becom es very im port ant . The concept is t he m echanism for such abst ract ions. I t allows various ent it ies ( businesses, st andards bodies, indust ry groups, and so on) t o publish abst ract specificat ions t o be used by ot her ent it ies in im plem ent ing services. I n our previous exam ples, t he SEMC w ould regist er it s

        tModel

      ht t p: / / w w w .sem c- consort ium .org/ BP/ PriceCheck specificat ion as a , w hich w ould

        be assigned a unique ident ifier key and be referenced by all businesses in t he

        SkatesTown

        consort ium , such as . I n addit ion, client s w ant ing t o find businesses t hat conform t o t hat SEMC specificat ion can query t he regist ry for businesses referencing t hat

        tModel .

        How to Use s

        tModel tModel

        I t is im port ant t o st ress t hat based on t he UDDI specificat ion, a could define j ust about anyt hing: I t consist s of a key, a nam e, a descript ion, and a URL. This sim plicit y is a pow erful concept , but it can also be a double- edged sw ord. On t he one hand, because

        tModel

        of t he sim plicit y in defining a , you can define anyt hing you w ant , even if it 's not useful t o or reusable by anyone else. On t he ot her hand, if used properly, you can use

        tModel

        s t o specify t he st andards and t em plat es t hat w ill be used in t he next generat ion of e- Business on t he Web.

        tModel

        Throughout t he UDDI dat a st ruct ures, s are used as references. By convent ion, t he UDDI specificat ion suggest s t w o m ain uses for t hem . The prim ary use is in defining w hat is called a t echnical fingerprint . This refers t o any t echnical specificat ions or pre-

        tModel

        arranged agreem ent s on how t o conduct business. For exam ple, s can be creat ed by indust ry groups such as Roset t aNet ( ht t p: / / w w w .roset t anet .org ) , or by com panies w ishing t o st andardize t he w ay t hey deal w it h suppliers. Our exam ples illust rat e how Skat esTow n and MyTurningWheels are using a specificat ion defined by anot her ent it y, nam ely SEMC.

        tModel

        The ot her m ain use for s is in defining nam espaces t o be used in t he

        identifierBag categoryBag

        and st ruct ures. This w ill be covered in m ore det ail in t he sect ion " More on Classificat ion and Cat egorizat ion ." The Structure

        tModel tModel

        As we already discussed, t he st ruct ure is very sim ple. I n general, an ent it y t hat act s as a reference needs a nam e, a descript ion, som e reference m at erial t hat describes

        tModel

        t he det ails of it s use, and a resolvable, unique ident ifier. This is t rue of a UDDI . I t has a key, a nam e, a descript ion, an opt ional descript ive overview docum ent , and som e cat egorizat ion and ident ificat ion inform at ion ( see Figure 7.8 ) . tModel

        at t ribut es are as follow s:

      • tModelKey tModel

        — The unique ident ifier for t he . I t is assigned by t he UDDI Operat or and cannot be edit ed or m odified. For t his reason, it should not be

        tModel tModel

        supplied in t he original regist rat ion. When a new is regist ered, t he

        

      tModelKey

        UDDI Operat or assigns a unique in t he form of a UUI D and ret urns t hat key in t he response. This key can t hen be used in subsequent queries and updat es.

      • operator

        — The cert ified nam e of t he Operat or t hat ow ns t he UDDI node t o w hich

        tModel

        t he is regist ered. I t is originally assigned by t he UDDI Operat or and cannot be edit ed or m odified by t he ent it y. For t his reason, it should not be supplied in t he original regist rat ion.

      • authorizedName

        — The nam e provided by t he Operat or t o t he aut hent icat ed user

        tModel

        w ho regist ered t he . I t is originally assigned by t he UDDI Operat or and cannot be edit ed or m odified by t he ent it y. For t his reason, it should not be supplied in t he original regist rat ion.

        tModel

        elem ent s are as follow s:

      • name tModel — Required. The 's na
      • description

        tModel — Opt ional repeat ing. Text ual descript ion of t he .

      • overviewDoc

        tModel

        — Opt ional. I n addit ion t o it s basic inform at ion, a st ruct ure

        overviewDoc overviewDoc

        m ight cont ain an opt ional elem ent . The st ruct ure is

        tModel

        used t o provide an overview descript ion of t he and it s int ended use. I t has

        overviewURL

        an opt ional repeat ing st ring descript ion elem ent and an opt ional t hat should be used t o point t o a docum ent t hat provides a descript ion and a t echnical

        tModel

        specificat ion of t he . I t is suggest ed t hat t his docum ent be HTML based and suit able for ret rieval in a brow ser t hrough t he HTTP GET operat ion.

      • identifierBag tModel

        — Opt ional. This elem ent allow s s t o be ident ified by associat ing t hem w it h a predefined ident ificat ion nam espace, such as defined by an indust ry group, or provided by UDDI ( such as t he Dun & Bradst reet Dat a Universal Num bering Syst em D- U- N- S® ) . This is done t hrough a set of

        keyedReference

        elem ent s, each of w hich is a key/ value pair. The ident ificat ion

        tModel

        inform at ion can be very useful w hen you're searching for a part icular in t he UDDI regist ry. I dent ifiers w ill be discussed in m ore det ail in t he sect ion " More

        on Classificat ion and Cat egorizat ion ."

        tModel

      • categoryBag

        — Opt ional. This is t he m echanism by w hich s can be cat egorized w it hin various t axonom ies, eit her provided by indust ry groups, or provided by UDDI . UDDI Operat ors w ill init ially support t hree t axonom ies. Cat egorizat ion w ill be discussed in m ore det ail in t he sect ion " More on

        Classificat ion and Cat egorizat ion ."

        More on Classification and Categorization As w e previously st at ed, one of t he m ain obj ect ives of t he UDDI regist ries is t he discovery of services, w het her st at ically ( design t im e) or dynam ically ( runt im e) . This ent ails a form of search t hrough a large space of ent ries. I n a reasonably populat ed regist ry, depending on t he search m echanism , t his could ret urn a very large set of hit s. An early requirem ent for UDDI , t herefore, w as a w ay t o perform int elligent searches. Unt il t he sem ant ic problem ( see Chapt er 9 , " Fut ure Concept s" ) is addressed in a sat isfact ory m anner, t he best current m echanism t o facilit at e such searches is t hrough t axonom ic cat egorizat ion and classificat ion. Cat egorizat ion is t he process of creat ing cat egories, w hereas classificat ion is t he process of assigning obj ect s t o t hese predefined cat egories ( or classes) . There are several t ypes of classificat ion schem es ( such as t he Library of Congress Classificat ion used in m ost libraries) , but for a large space such as businesses and services, t he m ost useful ones are hierarchical in nat ure. I n general, hierarchies are very pow erful for organizing dat a ( consider XML! ) . One of t he m ost pow erful exam ples of t he im port ance of hierarchical classificat ion in t he age of t he Web is Yahoo! I n addit ion t o a search engine, Yahoo! offers an ext ensive classificat ion schem e. For exam ple, t o find m anufact urers of skat eboards, you w ould nat urally t raverse t he Yahoo! classificat ion t ree t o get t o

        Business_and_Economy/Shopping_and_Services/Sports/ Skateboarding/Deck_and_Truck_Manufacturers/

        . I t can be argued t hat t he first - generat ion Web ( t he inform at ion Web of HTML and CGI pages) did not at t ain it s pot ent ial unt il t he Yahoo! classificat ion schem e becam e available. Sim ilarly, a regist ry such as UDDI w ould be very difficult t o use w it hout som e classificat ion schem es.

        The first version of UDDI includes in it s core specificat ions t hree predefined classificat ion schem es: t he Nort h Am erican I ndust ry Classificat ion Syst em ( NAI CS) for classifying businesses by indust ry ( ht t p: / / w w w .nt is.gov/ product / naics.ht m ) , t he Universal St andard Product s and Services Classificat ion ( UNSPSC) for product and service classificat ions ( ht t p: / / eccm a.org/ unspsc ) , and t he I SO 3166 st andard for geographic locat ion classificat ions ( ht t p: / / w w w .din.de/ grem ien/ nas/ nabd/ iso3166m a ) . I n order t o t ake advant age of t hese schem es, businesses need t o provide t he relevant classificat ion

        categoryBag inform at ion as t hey regist er t heir ent ries. This is done t hrough t he elem ent . keyedReference

        This elem ent cont ains a set of elem ent s ( see Figure 7.9 ) , each of which

        tModelKey tModelKey

        has at t ribut es form ing a nam e/ value pair and an opt ional . The is a sim ple but pow erful ext ension m echanism t hat act s as a nam espace qualifier for t he values specified in t he nam e/ value pair. For exam ple, if Skat esTow n w ant ed t o classify it s business using t he Yahoo! classificat ion schem e, ( assum ing t hat Yahoo has regist ered

        tModel

        t he schem e as a w it h an assigned key of 3D4EC875- E54F- 4D8D- 9CBF-

        keyedReference

        346D48BCAD9C) , t he com pany could add t he follow ing t o it s categoryBag tModel

        , using t he reference t o t he Yahoo! classificat ion as a nam espace for it s cat egory:

        <keyedRef erence keyName="Yahoo Busi ness Taxonomy" keyVal ue="Busi ness_and_Economy/Shoppi ng_and_Servi ces/Sport s/ Skat eboardi ng/Deck_and_Truck_Manuf act urers" t Model Key="UUI D: 3D4EC875- E54F- 4D8D- 9CBF- 346D48BCAD9C"/> Figure 7.9. The structure. keyedReference keyedReference identifierBag

        Anot her im port ant use for t he elem ent is in t he

        identifierBag categoryBag

        st ruct ure. The is very sim ilar t o t he const ruct in st ruct ure in

        keyedReference

        t hat it is a cont ainer for a set of elem ent s. I nst ead of cat egorizat ion

        identifierBag

        inform at ion, how ever, t he ( as it s nam e im plies) is used t o provide ident ificat ion inform at ion. This m echanism allow s regist ered ent it ies, w het her businesses

        tModel

        or s, t o be associat ed wit h som e declared ident ificat ion schem e, such as a t ax I D or an indust ry group I D, in a consist ent m anner. This, in t urn, provides a richer cont ext and an addit ional m echanism for searching across UDDI ent ries.

        tModel

        As an exam ple, consider t hat t he D- U- N- S num ber is defined as a in t he UDDI Taxonom y nam espace ( see t he sect ion " UDDI Core tModel " ) . I n a sim ilar m anner, e- Torus can define it s own business regist ry under t his m odel. Businesses in t he e- Torus

        tModel

        m arket place can ident ify t hem selves using t hat as a nam espace. The det ails of

        tModel

        t he e- Torus Regist ry Num ber w ould look like t his ( it is of t ype ident ifier in t he UDDI Type t axonom y) :

        <t Model t Model Key="uui d: F2390501- A240- 4470- 8A5A- 6088EE5B1A14"> <name>et : e- Torus- regi st ry</name> <descri pt i on xml: l ang="en">e- Torus Regi st ry Number</descri pt i on> <cat egoryBag> <keyedRef erence keyName=" Uni que i dent i f i ers f or member compani es" keyVal ue="i dent i f i er" t Model Key="uui d: C1ACF26D- 9672- 4404- 9D70- 39B756E62AB4"/> </cat egoryBag> </t Model >

        This m eans t hat businesses t hat w ant t o provide t heir e- Torus Regist ry Num ber as ident ificat ion for search purposes can do so by adding keyed reference point ing t o t his

        tModel categoryBag

        in t heir . You w ill see such exam ples in t he sect ion " The Business

        Ent it y St ruct ure ."

        The Structure

        save_tModel tModel

        Organizat ions or businesses can define, creat e, and publish t heir ow n s using t he

        save_tModel save_tModel

        operat ion. A m essage needs t o be const ruct ed w it h a

        save_tModel body tModel

        st ruct ure in t he elem ent of t he SOAP envelope, and t he st ruct ure cont ained wit hin ( see Figure 7.10 ) .

      Figure 7.10. The message structure.

        save_tModel

      • authInfo

        inform at ion as described in t he sect ion " The

        save_tModel operat ion.

        elem ent s should not bot h be included in t he sam e

        tModel

        and

        uploadRegister

        st ruct ure, resolvable t hrough an HTTP GET operat ion. The

        tModel

        — Opt ional repeat ing. This is a URL t hat point s t o an XML docum ent cont aining a valid

        t Model Dat a St ruct ure ." One or m ore st ruct ures can be regist ered in t his m anner in t he sam e call.

        tModel

        get_authToken operat ion w here t here is no ot her Operat or- specific m echanism .

        — Required. All Publicat ion API operat ions are aut hent icat ed because t hey creat e or m odify business inform at ion. Supplying an aut hent icat ion t oken in t his elem ent provides aut hent icat ion. The t oken is obt ained from t he UDDI node Operat or eit her by an Operat or- specific m echanism or t hrough t he

        has t he follow ing elem ent s:

        "1.0" . save_tModel

        , w hich is required. This at t ribut e is present on all t he UDDI API operat ions. As t he UDDI specificat ion grow s and is m odified, Operat or sit es w ill have t o m anage versions of t he API , and w ill be required t o support all current versions. The generic at t ribut e specifies t he version of t he API t o w hich a part icular operat ion belongs. I n UDDI V1 operat ions, t his is t he st ring

        generic

        has a s