Aoyon Chowdhury Parag Choudhary
Java APIs for XML K I C K S TA RT
800 East 96th Street, Indianapolis, Indiana 46240
Java APIs for XML Kick Start Copyright © 2003 by Sams Publishing All rights reserved. No part of this book shall be reproduced, stored in a retrieval system, or transmitted by any means, electronic, mechanical, photocopying, recording, or otherwise, without written permission from the publisher. No patent liability is assumed with respect to the use of the information contained herein. Although every precaution has been taken in the preparation of this book, the publisher and author assume no responsibility for errors or omissions. Nor is any liability assumed for damages resulting from the use of the information contained herein.
Executive Editor Michael Stephens Acquisitions Editor Todd Green Development Editor Tiffany Taylor Managing Editor Charlotte Clapp Project Editor Andy Beaster
International Standard Book Number: 0-672-32434-2 Library of Congress Catalog Card Number: 2002105432
Copy Editors Seth Kerney
Printed in the United States of America
Lindsey Rue
First Printing: October 2002
Indexer
05
04
03
02
4
3
2
1
Sandy Henselmeier Proofreader
Trademarks
Bob LaRoche
All terms mentioned in this book that are known to be trademarks or service marks have been appropriately capitalized. Sams Publishing cannot attest to the accuracy of this information. Use of a term in this book should not be regarded as affecting the validity of any trademark or service mark.
Technical Editors Brian Keaton Alan Moffet Media Developer Dan Scherf
Warning and Disclaimer Every effort has been made to make this book as complete and as accurate as possible, but no warranty or fitness is implied. The information provided is on an “as is” basis. The author and the publisher shall have neither liability nor responsibility to any person or entity with respect to any loss or damages arising from the information contained in this book.
Team Coordinator Lynne Williams Interior Designer Gary Adair Cover Designer Aren Howell Page Layout Ayanna Lacey Cheryl Lynch Graphics Oliver Jackson Tammy Graham
Contents at a Glance Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 Part I
JAX Basics
1
Using XML for Electronic Data Interchange. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2
Components of Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Part II
JAXP: Java API for XML Processing
3
Implementing Simple APIs for XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
4
Advanced Use of SAX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
5
The Document Object Model
6
XSLT and XPath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Part III
JAXM: Java API for XML Messaging
7
Messaging Fundamentals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
8
Creating Client Implementations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
Part IV
JAXR and JAX-RPC
9
Registry Fundamentals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
10
JAXR Implementations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
11
Working with JAX-RPC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
Part V
JAX in the Real World and the Future
12
Case Study: Deploying a Web Service Using JAX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
13
Looking Ahead: JAXB and Beyond . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343 Appendixes
A
Installing the JAX APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
B
XML: A Quick Tour . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357 Index
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
Table of Contents Introduction
1
How This Book Is Organized . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 Source Code and Updates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 Part I 1
JAX Basics Using XML for Electronic Data Interchange
5
XML and EDI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 Java and XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 XML and Java APIs for XML: A Quick Look . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 2
Components of Web Services
15
Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Web Services and B2B Communication: The Evolving Scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Components of Web Service Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SOAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SOAP Message Exchange Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SOAP Message Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SOAP and HTTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Understanding the SOAP Envelope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Understanding the SOAP Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Understanding the SOAP Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . UDDI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . UDDI Data Structure Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The publisherAssertion Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . UDDI APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . WSDL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . WSDL Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . JAX and Web Services: The Great Car Parts Company Scenario . . . . . . . . . . Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
15 16 17 19 20 21 22 23 24 25 25 26 28 28 29 29 33 34
Part II 3
JAXP: Java API for XML Processing Implementing Simple APIs for XML
37
The Packages in JAXP for Using SAX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 The org.xml.sax Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 The org.xml.sax.ext Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 The org.xml.sax.helpers Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 The javax.xml.parsers Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 The Key JAXP Classes and Interfaces for SAX Support . . . . . . . . . . . . . . . . . . . . . . . . 42 The SAXParserFactory Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 The SAXParser Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 The DefaultHandler Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 The ContentHandler Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 The ErrorHandler Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 The DTDHandler Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 The EntityResolver Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 The JAXP and Reference Implementation JAR Files . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 Setting Up JAXP and the JAXP Reference Implementation . . . . . . . . . . 47 Creating a SAX-Parsing Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 Creating the CarParts.xml File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 Using a SAX Parser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 Importing the JAXP Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 Extending the DefaultHandler Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 Setting Up the SAX Parser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 Handling the ContentHandler Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 Handling Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 Handling Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 Handling Processing Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 Handling Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 Handling a DTD and Entities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 Using a Validating Parser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
vi
Java APIs for XML Kick Start
4
Advanced Use of SAX
75
Identifying Document and Event Locations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 Handling Lexical Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 Updating the CarParts.xml File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 Importing the LexicalHandler Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 Implementing the LexicalHandler Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 Configuring XMLReader for Lexical Handling . . . . . . . . . . . . . . . . . . . . . . . . . . 84 Implementing Methods of the LexicalHandler Interface . . . . . . . . . . . . . . 85 Customizing External Entity Resolution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 Modifying the CarParts.xml File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 Using the EntityResolver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 Handling Namespaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 Generating SAX Events from a Text File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 Creating the SampleMailMessage.txt File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 Creating the SAX Parser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 Creating the Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 5
The Document Object Model
117
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 The DOM and the JAXP Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 The org.w3c.dom Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 The javax.xml.parsers Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122 Creating a DOM Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 The CarParts.xml File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 Sequence of Steps in Implementing a DOM Parser . . . . . . . . . . . . . . . . . . . 125 Importing the JAXP Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 Creating the MyDOMHandler Class Declaration . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 Accessing the DOM Parser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 Handling Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 Accessing XML Data Using DOM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 Accessing DTD Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 Determining Element Node Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 Randomly Accessing an Element Node and Its Attributes . . . . . . . . . . 137 Accessing an Element’s Text Node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140 Managing Data Using DOM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141 Creating Element Nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142 Creating Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
Contents
Creating Text Nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147 Normalizing the DOM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149 Deleting Nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152 6
XSLT and XPath
153
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153 The XSLT Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 The javax.xml.transform Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 The javax.xml.transform.dom Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157 The javax.xml.transform.dom Package Interface . . . . . . . . . . . . . . . . . . . . . . . . 157 The javax.xml.transform.sax Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157 The javax.xml.transform.stream Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158 Using XSLT with DOM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159 Sequence of Steps in Using XSLT with DOM . . . . . . . . . . . . . . . . . . . . . . . . . . . 159 Importing the JAXP Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159 Creating the DOM Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160 Setting Up the XSLT Transformer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163 Handling Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164 Generating the Transformed XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165 Using XSLT with SAX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167 Using SAX-Specific XSLT APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167 Importing the JAXP and Other Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167 Creating the InputSource Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168 Setting Up the XSLT Transformer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168 Handling Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169 Generating the Transformed XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170 SAX or DOM? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173 XPath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173 XPath Nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174 XPath Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176 XPath Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178 XPath Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179 Transforming XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182 Creating the XSLT Stylesheet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184 Creating the MyXSLTTransformer Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
vii
viii
Java APIs for XML Kick Start
Part III 7
JAXM: Java API for XML Messaging Messaging Fundamentals
195
JAXM Message Exchange Categories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196 Asynchronous Inquiry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196 Asynchronous Update with Acknowledgment . . . . . . . . . . . . . . . . . . . . . . . . . 197 Synchronous Update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197 Synchronous Inquiry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198 Fire-and-Forget Messaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198 Interoperability with Other Messaging Applications . . . . . . . . . . . . . . . . . . . . . . . . 199 JAXM and SOAP Messaging Styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200 SOAP Message with Attachments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200 SOAP Message Without Attachments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201 JAXM Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201 JAXM Client Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201 Messaging Providers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202 The JAXM Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204 The javax.xml.messaging Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204 The javax.xml.soap Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207 8
Creating Client Implementations
209
Standalone Client Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209 Importing the Packages and Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210 Getting a Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211 Creating the SOAP Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212 Populating the SOAP Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212 Creating the URLEndpoint Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214 Sending the Message and Getting the Response . . . . . . . . . . . . . . . . . . . . . . 214 Client with Messaging Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217 Creating the Servlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217 Creating the Web Form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224 Creating the web.xml File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226 Creating the sampledoc.txt File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227 Deploying the JAXM Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
Contents
Part IV 9
JAXR and JAX-RPC Registry Fundamentals
233
Existing Registries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233 Registry Uses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234 Registry Use Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234 The Registry Information Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235 The UDDI Information Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236 The ebXML Information Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237 The JAXR Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239 The JAXR Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239 JAXR Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240 RegistryService Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240 Capability-Specific Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240 JAXR Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240 Diverse Registries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241 The JAXR Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241 The javax.xml.registry.infomodel Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242 The javax.xml.registry Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247 10
JAXR Implementations
249
The JWSDP Registry Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249 Publishing Data to a Registry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250 Creating the MyOrganizationPublisher.java Application . . . . . . . . . . . . . 251 Importing the Required Packages and Classes . . . . . . . . . . . . . . . . . . . . . . . . . 251 Writing the Plumbing Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252 Connecting to the Registry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252 Publishing Data to the Registry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255 Querying Data from a Registry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263 Creating the MyRegistryQuery.java Application . . . . . . . . . . . . . . . . . . . . . . . . 263 Writing the Plumbing Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263 Connecting to the Registry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264 Querying the Registry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265 Deleting Data from Registry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271 Creating the MyDataDeleter.java Application . . . . . . . . . . . . . . . . . . . . . . . . . . . 271 Writing the Plumbing Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272 Connecting to the Registry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273 Deleting Data from the Registry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
ix
x
Java APIs for XML Kick Start
11
Working with JAX-RPC
279
JAX-RPC Working Mechanism . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280 Constituents of a JAX-RPC Server and Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282 JAX-RPC Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283 The javax.xml.rpc Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284 The javax.xml.rpc Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284 The javax.xml.rpc Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284 The javax.xml.rpc Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285 The xrpcc Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285 The config.xml File Syntax When Starting with RMI Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286 The config.xml File Syntax When Starting with a WSDL Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287 The Types Supported by JAX-RPC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287 Java Types Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288 Application Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288 Unsupported Java Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289 The CarPartRequest Web Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289 Creating the Service Definition Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290 Creating the Service Definition Interface Implementation Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291 Creating the config.xml File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291 Creating the web.xml File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293 Deploying the Web Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294 The CarPartRequestClient Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296 Running the CarPartRequestClient Application . . . . . . . . . . . . . . . . . . . . . . . . 298 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298 Part V 12
JAX in the Real World and the Future Case Study: Deploying a Web Service Using JAX
301
Case Study Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301 Order of Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302 Setting Up the JWSDP Registry Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302 Creating Applications That Register Supplier Information to the Registry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303 Writing the BestDealsonAccessoriesRegistryPublisher.java Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303
Contents
Developing the Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342 13
Looking Ahead: JAXB and Beyond
343
Java Architecture for XML Binding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343 JAXB Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344 Binding Compiler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345 Binding Runtime Framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346 Binding Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347 JDOM 1.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347 XML Trust Service APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348 XML Digital Signature APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348 XML Digital Encryption APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348 XML Transactioning API for JAVA (JAXTX) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348 ebXML CPP/A APIs for Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348 Streaming API for XML (StAX) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349 Java APIs for WSDL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349 Appendixes A
Installing the JAX Pack
353
Java XML Pack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353 Java Web Services Developer Pack (JWSDP) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354 JAX XML Pack or JWSDP? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354 Getting and Installing JWSDP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354 B
XML: A Quick Tour
357
What Is XML? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358 A Sample XML Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358 The XML Declaration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360 Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360 The Root Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361 Processing Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361 Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362 Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363 Character References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363
xi
xii
Java APIs for XML Kick Start
Entity References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363 Predefined Entities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364 Internal Entities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364 External Entities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365 CDATA Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366 Document Type Definition (DTD) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366 The Document Type Declaration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368 Declaring Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369 Element Content Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369 Character Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370 Declaring Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371 Attribute Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371 Attribute Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371 Default Attribute Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374 Index
375
About the Authors Aoyon Chowdhury is a senior member of the technical staff at Cadence Design Systems, Inc. He has more than seven years of experience in systems analysis and design, programming, systems administration, and technical writing. Parag Choudhary has been consulting on software architectures for over 10 years with international consulting firms and independently. He has experience in a variety of application domains, from banking and insurance applications to electronic design automation software. He has skills in networking software and databases across different platforms including Unix, IBM Mainframe, and AS/400. He has expertise in object-oriented distributed application architectures and Internet technologies. He currently works in R&D at Cadence Design Systems, Inc.
Dedications To my parents for all the caring and one special friend who has been my inspiration. —Aoyon Chowdhury To my daughter, Ruhi, who brings joy to my life. —Parag Choudhary
Acknowledgments This is, without a doubt, the most difficult part. There have been so many people involved in making this possible that we will inevitably miss somebody (although we are giving our best shot here in trying not to). So, a big thanks in advance to all who made this possible, and a sincere apology to those people we may have inadvertently missed. First, we would like to thank SMN Kumail, who introduced us to Sams Publishing. We are especially thankful and impressed with the people at Sams Publishing, namely: Anindo Dey, Todd Green, Andy Beaster, Tiffany Taylor, Alan Moffet, Brian Keeton, Lindsey Rue, Seth Kerney, and others who made this project worthwhile and fun all the way through. Finally, we would like to thank our respective family, friends, and colleagues in Cadence, without whose support this book would not have been possible.
We Want to Hear from You! As the reader of this book, you are our most important critic and commentator. We value your opinion and want to know what we’re doing right, what we could do better, what areas you’d like to see us publish in, and any other words of wisdom you’re willing to pass our way. As an Executive Editor for Sams, I welcome your comments. You can email or write me directly to let me know what you did or didn’t like about this book—as well as what we can do to make our books better. Please note that I cannot help you with technical problems related to the topic of this book. We do have a User Services group, however, where I will forward specific technical questions related to the book. When you write, please be sure to include this book’s title and author as well as your name, email address, and phone number. I will carefully review your comments and share them with the author and editors who worked on the book. Email: Mail:
[email protected]
Michael Stephens, Executive Editor Sams Publishing 800 East 96th Street Indianapolis, IN 46240 USA
For more information about this book or another Sams title, visit our Web site at www.samspublishing.com. Type the ISBN (excluding hyphens) or the title of a book in the Search field to find the page you’re looking for.
Introduction I
n the technology world, change is the only constant. With change has come the possibility of doing business in better, faster, more effective, and cheaper ways. First, the Internet revolutionized the way the world communicated. It brought forward a whole new way in which business information and transaction was done. The enterprises with services to offer had a whole new way to publish information. The purchasing companies benefited in terms of the amount of information they had at their disposal, thereby helping them make prudent decisions. The beauty of the whole thing was that it no longer mattered what platforms and operating systems the enterprises used. The TCP/IP + HTTP + HTML combination ensured that any machine with the TCP/IP protocol stack and a browser could connect to and access any site on the Internet. Although the TCP/IP+HTTP combination helped accomplish machine independence as far as publishing and reading Web pages was concerned, the platform-dependency of the applications that actually ran on the Web server remained a problem. For example, an application that was developed for a Windows NT Web server could not be used on a Unix-based Web server. You had to port the application by recompiling the application on the required operating system/hardware. This problem was solved by the development of the Java programming language. Java made it possible to write a program once and run it on any operating system or hardware. Even as Java made write-once/run anywhere applications possible, HTML ensured that any Web browser could read data and display it to the user in a consistent manner. It was soon apparent that the real power of the Internet would be realized only when heterogeneous machines connected to the Internet could exchange data and perform business transactions. A mechanism was required by which applications residing on different machines could exchange data with each other in a consistent way. XML was developed to meet this requirement. XML provided a text-based way in which to define your own information structure, and through the use of DTDs and schemas, you could ensure that all applications that exchange an XML document have a common understanding of the data contained in the XML document. So, while Java provided portability of code, XML enabled the portability of data. It was inevitable that the wonderful people involved in the development of Java would come out with APIs that would enable application developers to develop XML-based applications. These APIs absolve developers from having to understand the nuances and eccentricities of the XML language itself. Thus, as a developer, you
2
Java APIs for XML Kick Start
can concentrate completely on business logic, rather than on the XML syntax. At the time of this writing, the released APIs were geared to enable developers to create and deploy a special type of XML-enabled application called Web services. This book teaches you how to use the Java APIs for XML (JAX). The book is structured in such a way that you can either read it from cover to cover, or only a specific section. Each API is explained using simple and easy-to-follow examples.
How This Book Is Organized Each of this book’s parts are described using simple and easy-to-follow sample applications. The first part covers the basics you’ll need to learn before you can start using JAX. These include understanding the constituent components of the Web service architecture: SOAP, UDDI, and WSDL. Also covered in this part is an overview of the specific APIs. The second part describes the Java APIs for XML Processing (JAXP), covering the SAX, DOM, and XSLT specifications. The XML processing specifications enable an application to parse an XML document in different ways. The third part describes the Java APIs for XML Messaging (JAXM). These APIs make it possible for applications to programmatically create and send SOAP messages. The fourth part covers the Java APIs for XML Registries (JAXR) and Remote Procedure Calls (JAX-RPC). These APIs provide the necessary mechanism for applications to connect to UDDI-based registries and submit, manage, and query data. JAX-RPC enables applications to perform remote procedure calls over the Internet. The fifth part describes a case study that shows how the components of JAX work together to create a successful Web service. This part also has brief descriptions of the Java Architecture for XML Binding (JAXB) and upcoming APIs that will provide even more flexibility in developing XML-based applications using Java. Finally, there are two appendixes: The first appendix describes how to download and install JAX, and the second provides a quick overview of XML.
Source Code and Updates Visit http://www.samspublishing.com for updates and to download the source code and examples presented in this book. From the home page, type this book’s ISBN (0672324342) into the search field and click on Search to access information about the book and a direct link to the source code.
PART I JAX Basics IN THIS PART 1 Using XML for Electronic Data Interchange 2 Components of Web Services
1 Using XML for Electronic Data Interchange I
n an evolution that lasted almost a decade, the Internet world saw the use of HTML in the creation of billions of Web pages of information for human consumption. Towards the end of the HTML evolution, the pundits of technology saw another vision of the evolution of Internet—computers collaborating over the Internet. The billions of pages of information on the Internet might be too much for a single human to understand, but computers could definitely assist organizations to leverage this information. Although HTML is perfect for human consumption, it is unusable as an Electronic Data Interchange (EDI) standard for communications between two or more computers. This has given birth to Extensible Markup Language (XML). Like HTML, it is also a subset of the SGML standard, but unlike HTML, it is tailored for machine consumption. In this chapter, you will learn about the relationship between XML, EDI, and Java. This chapter will also describe the Java APIs that are available for building XMLenabled applications.
XML and EDI Today XML is an industry-standard, extensible, systemindependent way of representing and exchanging data. This is achieved in two ways: • The use of a tagging mechanism in which the tags indicate the content and structure of the data they enclose. For example, the following code shows how the information about a book is stored in an XML document:
IN THIS CHAPTER • XML and EDI • Java and XML
6
CHAPTER 1
Using XML for Electronic Data Interchange
Java APIs for XML Aoyon Chowdhury and Parag Choudhary 1234 sams 40
The and the tags tell a parser that the information between them is about a book. The other tags specify the book’s author, ISBN number, publisher, and price. Similarly, you can define and use your own tags to describe your content. The fact that the tags are user-defined is what gives XML its extensibility. • The portability of data is ensured by the use of DTDs, or XML Schemas. DTDs describe the tags, and the order in which they can appear in an XML document. These provide a consistent understanding of the XML data by different applications. For example, the DTD for our book would be as follows: book (name, author, isbn, publisher, price) > name (#PCDATA) > author(#PCDATA) > isbn (#PCDATA) > publisher(#PCDATA) > price(#PCDATA) >
Therefore, any application, when given the bookList XML file along with the bookList DTD, can process the document as per the rules specified in the DTD. This implies that applications residing on different platforms and operating systems can share data with each other, as long as they agree on the format and the structure of the content. XML is fast becoming the communication medium of choice for enterprises sharing data within their own departments or with other enterprises. The Internet world is also seeing a new breed of applications called Web services. These applications can share information between enterprises using XML as the communication medium and Internet protocols as the backbone.
Java and XML
Java and XML The Java platform is an ideal platform for developing XML-based applications such as Web services. This is because of the following reasons: • Java provides a rich set of capabilities to do object-oriented programming without the complexity found in languages such as C++. • Java provides a rich set of standardized classes. • Java is portable. • Java provides an extension mechanism to extend the functionality of the core platform. • Java provides extensions for component development and reuse. • The J2EE platform provides the necessary support for security, scalability, and so on, that is required for deploying and supporting Web services.
XML and Java APIs for XML: A Quick Look The Java platform has an extended framework that provides standardized APIs to handle XML data and build Web services. These APIs are available through two downloadable packs: the Java Web Services Developer Pack (JWSDP) and the Java XML Pack. The Java XML Pack contains the core APIs that enable you to build XML-based applications. The JWSDP is a superset of the two. It contains the Java XML Pack and other components such as the Tomcat Web server and the ant build tool that simplify the process of developing and deploying Web services using the Java platform. The core APIs that enable you to develop XML-based applications are as follows: • Java API for XML Processing (JAXP) • Java Architecture for XML Binding (JAXB) • Java API for XML Messaging (JAXM) • Java API for XML-based RPC (JAX-RPC) • JavaAPI for XML Registries (JAXR) The first two APIs (JAXP and JAXB) are essentially document-oriented, in the sense that they work directly with XML documents. The remaining three APIs (JAXM, JAXR, and JAX-RPC) are procedure-oriented. This means that these APIs are useful in developing business procedures where XML is
7
8
CHAPTER 1
Using XML for Electronic Data Interchange
used as the primary information exchange medium. For example, JAXM enables you to do business messaging over the Internet using the SOAP protocol. The Java APIs for XML have two very important features, which make them the ideal choice for developing XML-based applications: • Complete adherence and support to industry standards developed by standards bodies and industry consortia such as W3C, UDDI, and so on. This implies that applications based on these APIs will be interoperable with all other applications based on these standards. These applications could have been developed in any language, including but not limited to Java. • Flexibility and ease of use to developers. For example, when using JAXP to process an XML document, you can choose between either SAX or DOM, and at runtime decide which implementation of parser to use. Also, using JAXB, you can very easily create Java objects from an XML DTD, manipulate them, and write back as an XML document without needing to write complex parsing and processing code. Let us now look at each of the APIs in a little more detail. JAXP One of the document-centric APIs, JAXP provides the means by which you can parse, manipulate, and transform XML documents from within a Java application. JAXP supports the Simple API for XML (SAX) 2.0 and Document Object Model (DOM) 2.0 parser standards for processing XML documents, along with the XSLT standards for transforming XML documents to other XML documents and display formats such as HTML. The JAXP support for SAX enables you to parse the XML document as events, thereby making the parsing of XML documents extremely fast. The support for DOM standard ensures that the XML data can be loaded in memory as data-objects that can be manipulated in the Java application. The XSLT support ensures that you can translate the XML document into another XML document with completely different tags, apply stylesheets, and write out XML documents in different formats such as HTML, WML, and so on. But then why use JAXP? After all, there are a number of SAX, DOM, and XSLT parsers, all of which have their own published APIs that can be used as well. To answer this question, let us first look at the issues involved in using a parser-specific API set. When using a parser-specific API set, you need to be aware of the issues that might arise when using vendor-dependent APIs.
Java and XML
For example, in any application that uses a SAX parser, you need to get an instance of the SAX parser class. If you were using the Xerces parser, then you need to explicitly import the org.apache.xerces.parsers.SAXParser class to get access to the SAX parser. This affects the portability of the code, because the code cannot be run or compiled on a platform that does not have the Xerces parser. Another situation where the code could break is if there is a change in the packaging structure of the Xerces parser. Also, after the application’s release, there might be a new and more optimized version of the parser available. To handle these changes, you need to edit the source code and recompile. Not a very rosy picture, to say the least. Now imagine a situation in which you do not have to do any of the previously mentioned tasks and can still use any parser of your choice, and have the capability to change the parser at runtime. This is exactly what JAXP provides. JAXP provides a platform-independent and consistent set of APIs for using the SAX, DOM, and XSLT parsers. Additionally, the JAXP architecture has a pluggability layer that enables JAXP to use any SAX, DOM, or XSLT parser of your choice at runtime. JAXP also provides support for XML namespaces, thereby ensuring that there is no conflict when processing XML documents that have elements from different DTDs. Additionally, if you’re using the DOM parser, JAXP provides a method to bootstrap a DOM Document object from an XML document. At the time of this writing, this feature was not available in any of the DOM 2.0 parsers. JAXB Another of the document-centric APIs for XML is JAXB. Before beginning the discussion about the JAXB API, let us look at the need that it fills. An XML document that follows a DTD can be thought of as an instance of the DTD. This is analogous to a Java object being an instance of a class. Also, the Java programming language provides a standard and convenient way to access and manipulate objects. Therefore, it would greatly simplify things if there were a mechanism by which the XML data can be represented as objects in a Java application. In that case you could concentrate on developing applications that use the XML data, rather than spending time on writing code for parsing and processing XML documents. The JAXB API fills this need. By means of a schema compiler and a runtime framework, it provides a two-way mapping between XML documents and Java objects. By providing a DTD and a binding schema, the schema compiler generates the required Java classes from the schema. A binding schema is an XML document that contains instructions on how to bind a schema to classes, such as what data type to bind an attribute value to in the generated class. For example, you can bind the content of the element Date to the DATE data type in the generated class.
9
10
CHAPTER 1
Using XML for Electronic Data Interchange
As a developer, you can use these generated classes to create the object tree representing the data hierarchy of the XML document, and manipulate the objects as you would do normally for any Java objects. The JAXB API also provides the necessary mechanism to regenerate the XML from the object tree. There are other benefits of using JAXB as well. First, the generated classes contain all the necessary code to parse XML documents based on the schema. This saves you the time you would have spent writing XML-parsing code, which can be used to write an application that does something useful with the XML data. Secondly, the JAXB API provides structure and content validation in the generated code. This is possible because JAXB writes out Java code from the XML DTD. Therefore, by using an appropriate binding schema, you can decide on the data types for each of the elements in a schema. This type of validation is not possible in a DTD. For example, you might have an element called Date. In a DTD, there is no way to validate that the content between and is a date value, and not junk. But when using JAXB, you can ensure that the data type for the Date element is only of type Date. Thirdly, applications using JAXB are faster, and JAXB is more convenient to use than the SAX and DOM parsers. Being serial processors by design, the SAX parsers are fast. But they do not store the information obtained from the XML document in memory. The DOM parsers, on the other hand, store the entire XML document in memory. This allows the XML document to be manipulated. However, because it loads the contents into memory and also contains a lot of tree manipulation features, it makes your applications slower. The JAXB API provides the best of both worlds. It is as fast as the SAX parser, and also creates an in-memory data object representation of the XML document. It is faster than DOM because it does not contain the tree manipulation features of DOM. The manipulation of the objects is left to the application. Finally, applications based on JAXB are extensible. This is because JAXB generates Java classes, which can be subclassed for providing additional features. JAXM JAXM enables developers to write applications that generate XML messages based on industry standard SOAP 1.1 and SOAP with Attachment specifications. The messages are delivered using standard Internet transport mechanisms such as HTML, SMTP, FTP, and so on. Simple Object Access Protocol (SOAP) is an XML-based protocol that enables programs running on heterogeneous hardware and software in a distributed environment to communicate with each other and do remote procedure calls (RPCs). All
Java and XML
communications in the Web service architecture are done via SOAP. SOAP is discussed in greater detail in Chapter 2, “Components of Web Services.” JAXM is extensible by design. This is made possible through the use of profiles. A profile is a specific implementation of SOAP, such as ebXML, which is based on SOAP 1.1 and SOAP with Attachments specifications. The SOAP specification itself is a very basic packaging model and provides no specific addressing scheme or message identification information. A profile, being a specific implementation, provides the necessary information, such as the packaging model, addressing scheme, and so on. For example, the ebXML profile specifies how a SOAP header has to be created with the addressing and message identification information. An application that implements JAXM is called the JAXM client. Normally, a business also uses a messaging provider, which takes care of processes such as message routing, message delivery, and so on. A message provider that supports JAXM is called the JAXM provider. A JAXM client can either directly send a SOAP message, or use the JAXM provider. In case the JAXM provider is used, the JAXM client sends a SOAP message to its JAXM provider, which transmits the SOAP message to the recipient’s provider. The recipient’s message provider then forwards the message to the recipient client. When a messaging provider is used, a JAXM client can act both as a client and a server. This implies that a JAXM client can send and receive SOAP messages and process them. For example, consider three JAXM clients, B and C. A sends a SOAP message to B. In this case, A acts as the client and B as the server. B processes the message and forwards the message to C. In this scenario, C is the server, and B is the client. A JAXM client can also directly send messages to the recipient application. In this scenario, the JAXM client can only send SOAP messages and accept responses for the sent message. It cannot act as a server to process SOAP messages sent from other clients. Because it’s based on W3C standards, a JAXM client can communicate with any application that is capable of producing and consuming SOAP messages. A JAXM message itself is made up of two parts: the required SOAP part and the optional attachment part. The SOAP part is the standard SOAP envelope that contains the Header and the Body elements. The content of the message is stored in the Body element. All non-XML content of the message is stored in the attachment part of the message. JAXR Registries are the yellow pages of the Internet. They are Web-based services that enable companies to register information about the products and services they offer. Using registries, businesses can query and discover other businesses with which they want to do business.
11
12
CHAPTER 1
Using XML for Electronic Data Interchange
A company (called the seller) that is providing certain services registers itself with a registry. A company (called the buyer) desirous of a particular product or service looks in the registry for the service and finds the seller. The buyer and seller then agree on a mutually agreeable collaborative process, which might include the DTD for their industry’s standards, after which the buyer can access and use the services hosted by the seller. The purpose of registries is to facilitate the growth of e-business. At the time of this writing, there are several standards for registries, such as the Organization for the Advancement of Structured Information Standards (OASIS), the Electronic Business using eXtensible Markup Language (ebXML), the eCo Framework, Universal Description, Discovery, and Integration (UDDI), and so on. These registries are either based on open standards or are promoted by industry consortiums. These registries provide their own APIs, which you can use to manage and query information in the registries. NOTE The registry standards exist to facilitate and promote e-commerce through the use of XML. A detailed discussion about these standards is beyond the scope of this book. However, you can access the Web sites for these standards to find out more about them: • OASIS —http://www.oasis-open.org • ebXML—http://www.ebxml.org • eCO Framework —http://www.commerce.net/projects/ currentprojects/eco/ • UDDI —http://www.uddi.org
As with the SAX or DOM APIs, using a registry-specific API set results in code changes and recompilation if you need to change over from one registry to another. So, similar to JAXP, JAXR provides a convenient and standard API to access the registries over the Internet. Figure 1.1 shows how JAXR enables you to access diverse registries.
Clients
JAXR
ebXML
FIGURE 1.1
UDDI
Accessing different registries using JAXR.
Other
Summary
Therefore, JAXR can be used in a Java application to publish business information in public registries and query the registries for information in a standard manner. JAX-RPC RPC (Remote Procedure Calls) is the mechanism by which an application executes procedures on remote systems. RPC is a complex process, and RPC over the Internet brings its own set of complexities because of the heterogeneous systems on which applications are hosted. JAX-RPC provides a mechanism by which applications can make RPC using the XML-based protocol, SOAP. SOAP is a natural choice because the specification provides mechanisms for representing remote procedure calls. The API ensures that RPC and its responses are done using SOAP messages over the HTTP protocol. When using JAX-RPC, you do not need to worry about the complexities of RPC such as data marshaling and unmarshaling. As with other Java RPC APIs, such as RMI and CORBA/IDL, JAX-RPC hides the complexity from you, thereby enabling you to concentrate on the business logic rather than plumbing code. Also, because the JAX-RPC is based on W3C standards such as SOAP and HTTP, an application using JAX-RPC can also access Web services that are not running on the Java platform.
Summary In this chapter, you’ve learned how EDI is done using XML, and why Java is the natural choice for developing XML-based applications. You’ve also learned about the features of Java APIs for XML. In the next chapter, you will learn about Web services and their architectural components. You will learn about the role that the Java APIs for XML play in developing Web services.
13
2 Components of Web Services
IN THIS CHAPTER • Web Services • SOAP • UDDI • WSDL
In the last few years, the Java programming language, with its ease of use and portability, has revolutionized the way computing is done over the Internet. Simultaneously, the advent of XML, along with the development and acceptance of XML-based standards for different industries, has made it possible to exchange information between enterprises running on heterogeneous operating systems and hardware. The use of XML to do business over the Internet has been made possible with applications called Web services. This chapter is an attempt to describe Web services. You will learn the business necessity that has led to the development of Web services. You will also learn about the components that make up the Web services architecture. Then, each of the components of the Web service architecture will be described in some detail. The chapter will conclude with a case study on how the Java APIs for XML can be leveraged in the Web services environment to meet a company’s business needs.
Web Services Web services are software components that can be executed over the Internet via XML interfaces. These software components are accessed through specific transport protocols, such as HTTP, SMTP, FTP, and so on. The software components have the ability to exchange data and information with each other across firewalls and different platforms without requiring human intervention. But why do we need Web services? To answer this question, let us look at the changing scenario of business-tobusiness (B2B) communication.
• JAX and Web Services: The Great Car Parts Company Scenario
16
CHAPTER 2
Components of Web Services
Web Services and B2B Communication: The Evolving Scenario All businesses have suppliers and consumers. It is critical for the success of a business to have effective communication systems with its business counterparts. Let us consider a business, Great Car Parts Company, that sells various car parts and accessories. Owing to market demands, it decides to add car mobile phone chargers to its list. In the classic B2B communication model, somebody in the procurement department, we’ll say Jack, will look in the yellow pages to find companies that deal in car mobile phone chargers. After the companies are identified, Jack will send out information requests to the various companies. The suppliers will in turn send the price list to Great Car Parts Company, where Jack will scan through the rival price lists and then reach a decision on from whom to buy the chargers. This process is obviously time consuming and error-prone. From a business perspective, it would be tremendously beneficial if somehow all this communication and decision-making could be done programmatically. This implies that Great Car Parts Company will have application programs that can somehow find the companies that sell the car mobile phone chargers, and then access their databases for price information. However, there are issues in accessing the information systems of other enterprises. The information systems in most enterprises are unique, both in terms of the hardware and operating systems in use, as well as the logical schema of the information. Therefore, it is possible that while Great Car Parts Company has its information systems running on a Windows NT platform, the company from which it plans to procure chargers, let’s say We Sell Chargers Inc., could be running on Unix. Also, the way information is stored in We Sell Chargers Inc. could be very different from the way information is stored in the databases of Great Car Parts Company. Therefore, there has to be a system in place to ensure that different enterprises can access and exchange data with each other. One of the first attempts at computer-to-computer integration has been through the use of Electronic Data Interchange and value added networks. However, this often translates to programming solutions being written to access proprietary and incompatible middlewares. Such solutions are time consuming, expensive to set up, and difficult to maintain, thus making it impractical for most businesses. Most small companies like our Great Car Parts Company rely on largely manual methods for doing B2B communications. The advent of the Web brought two big changes in the B2B communication model. The simplicity of the HTML markup scheme and quick proliferation of Web browsers ensured that companies could publish information in a platform-independent manner. This also saw a part of the communication process being moved out of the human domain into programming solutions.
Web Services
Going back to our Great Car Parts Company example, after looking in the yellow pages, Jack can now go to the Web sites of the competing vendors and get the price lists from the Web. Although this saves a substantial amount of time, it still requires a human to interface with the Web sites. Of course, to help Jack, one can write programs that parse the contents of a Web page, but there are inherent issues with that. It is important to remember that the Web was, by design, created for presenting data to humans. Therefore, although Jack can easily differentiate data from presentation in a Web page, it’s rather painful to write a program to do the same. And even if you did write the program, a small change in the Web page could mean a lot of rework for the programmer of the parsing application. Therefore, what is needed is a way in which an application can programmatically look up company information that meets its business needs, communicate with those companies and get the desired data, all without human intervention. Using XML interfaces, the Web services architecture fulfills this necessity for computer-tocomputer, or more appropriately, application-to-application communication. Returning to our example, in a pure Web services-enabled situation, an application would look up a Web registry to locate the companies that supply the car mobile phone chargers. Then the application would send a query to the companies for the price list. The companies will have Web applications that will respond to the request for price information and provide the data in a previously agreed upon format. The data received from each company would be parsed by an application in Great Car Parts Company to get the price data from each of the companies. Another application might then compare the prices, and depending on the algorithm, automatically place an order with a particular vendor. At the end of this chapter, we will see how JAX might be used to develop Web services. Now that a Web service has been defined, we need to understand the main components of the Web service architecture and how they work with each other.
Components of Web Service Architecture The Web service architecture has three main components: • A service provider—A service provider is the organization that develops the Web service. A service provider is also responsible for creating and hosting the service descriptions, such as its location, transport protocol, message formats, and so on. For example, We Sell Chargers Inc. could develop and deploy a Web service that responds to the queries received from different companies about charger prices. • A service registry—A service registry is analogous to the yellow pages. It is essentially a publicly searchable information exchange mechanism, in which service providers register and publish their company information and Web
17
18
CHAPTER 2
Components of Web Services
service descriptions. A service requestor can search the registry to find the desired Web service. For example, We Sell Chargers Inc. will need to register itself with a registry to ensure that companies that are looking for charger sellers can find it. • A service requestor—A service requestor is an application, Web service, or even a human who wants to use a particular Web service. For example, the application program at Great Car Parts Company that looks up the service registry is a typical example of a service requestor. As shown in Figure 2.1, these three components perform three operations on a Web service, called publish-find-bind. Service Provider Bind
Service Requestor
FIGURE 2.1
Publish
Find
Service Registry
The publish-find-bind operations.
The service provider creates the Web service application using a language such as Java. Next, using XML, the service provider needs to create the service description file for the Web service. After the application has been developed and the service description file has been created, the service provider publishes the service description to a registry. Next, the service requestor, which wants to run the specific Web service, queries the registry and finds the service description for the Web service. Based on the information gathered from the service registry, the requestor connects to the service provider hosting the Web service using a bind operation, then runs the Web service. All the communication between the service provider, registry, and service requestor is done using XML over some standard Internet protocol, such as HTTP. The physical representations of the publish-find-bind paradigm are the three XMLbased protocols, namely WSDL, UDDI, and SOAP. Figure 2.2 shows how the three protocols are related to each other. Let’s now look at each of the three XML-based protocols in more detail.
SOAP
Service Provider Data Exchange Using XML Inside SOAP Wrappers Service Requestor
FIGURE 2.2
Service Description Using WSDL
Query for Service Using XML Inside SOAP Wrapper
Service Registry (UDDI)
The Web Services Protocol Stack.
SOAP Simple Object Access Protocol (SOAP) is an XML-based protocol that allows programs running on heterogeneous hardware and software in a distributed environment to exchange data with each other, and to do remote procedure calls (RPC). All communication in the Web services architecture is done via SOAP. NOTE At the time of this writing, both SOAP 1.1 and SOAP with Attachments specifications have been submitted to the W3C as Notes. You can access the SOAP 1.1 specification at http://www.w3.org/TR/SOAP/. The SOAP with Attachments Note can be accessed at http://www.w3.org/TR/ SOAP-attachments. Although the SOAP 1.1 and SOAP with Attachments specifications are submitted with the W3C as Notes, a Working Draft on SOAP 1.2 has also been submitted. An excellent place to find out about the SOAP 1.2 specification is at http://www.w3.org/TR/soap12-part0/.
For those who are familiar with CORBA, SOAP can be considered similar to the IIOP protocol. The protocol consists of three parts: • An envelope, which is an XML document that defines a framework for describing the message, such as what is in the message, who it is meant for, and whether any processing is necessary or not. • A set of data encoding rules that describe a way to encode a collection of either simple or compound values. Simple values include simple data types such as int, float, and so on, and built-in data types such as arrays of bytes and enumerations. Compound values include structures such as arrays, and other complex types as defined in the XML Schema specifications. The encoding rules also specify the rules for object serialization. The rules for object serialization provide the support for doing RPCs. • A convention for representing remote procedure calls and responses.
19
20
CHAPTER 2
Components of Web Services
Although SOAP can be used in combination with a variety of protocols, the primary transport mechanisms used by SOAP are the common Internet protocols, such as HTTP and SMTP. There are two reasons for choosing the common Internet protocols as the transport mechanism: • The common Internet protocols are installed on every major operating system. • Because HTTP requests pass through firewalls, programs that use SOAP to communicate can communicate with programs residing in different platforms. Having gotten an idea of what SOAP is about, let’s now look at what it means to say that the components of a Web service talk to each other using SOAP. A Web application generates the information it wants to exchange in an XML file encoded as a SOAP message, and transmits it using some Internet protocol, such as HTTP. The responding application processes the SOAP message and sends the necessary response back to the requesting application in a SOAP message. As it’s possible that the applications are behind firewalls, the SOAP specification ensures that the HTTP header is specially encoded to allow a SOAP message to pass through firewalls. Let’s now look at the SOAP message exchange model.
SOAP Message Exchange Model SOAP messages can traverse various nodes before reaching the intended final destination. Each intermediate node has to process the SOAP message. The order in which the SOAP message is processed by a node is as follows: 1. The node identifies all the parts of the SOAP message that it is expected to
process. 2. The application at the processing node verifies that all mandatory parts that
were identified are supported. If they are supported, then the SOAP message is processed. This decision is reached depending on the value of a mustUnderstand attribute of the Header element. If the server fails to process the SOAP message, then it must throw a fault. The processor might also choose to ignore optional parts identified in step 1. This does not affect the outcome of the processing of the SOAP message. 3. If the node that is currently processing the SOAP message is not the ultimate
destination, then it removes the parts it has processed and forwards the message. Although SOAP messages are essentially one-way transmissions, SOAP implementations can use the unique characteristics of the network in which they are traveling. For example, in SOAP messages with HTTP bindings, the SOAP response message can be delivered as an HTTP response message using the same connection through which
SOAP
the request was received. The request-response mechanisms and the encoding capability provided by the SOAP specification enable it to do RPCs. The following is an example of a SOAP request-response message embedded in an HTML request. We will use this example to explain how SOAP works with HTTP and the semantics of a SOAP message itself.
SOAP Message Example Examples of a SOAP request and response embedded in HTTP are displayed in Listing 2.1 and Listing 2.2, respectively. LISTING 2.1
SOAP Request
POST /BookPrice HTTP/1.1 Host: xxx.xxx.xxx.xxx Content-Type: text/xml; charset=”utf-8” Content-Length: nnnn SOAPAction: “http://xxxx.xxxx/xxxx” 1234 0789725673
LISTING 2.2
SOAP Response
HTTP/1.1 200 OK Content-Type: text/xml; charset=”utf-8” Content-Length: nnnn 5 40
We will use the SOAP request and response listings to explain how SOAP is used over HTTP in detail.
SOAP and HTTP From Listing 2.1, you can see that the SOAP HTTP request was as follows: POST /BookPrice HTTP/1.1 Host: xxx.xxx.xxx.xxx Content-Type: text/xml; charset=”utf-8” Content-Length: nnnn SOAPAction: “http://xxxx.xxxx/xxxx”
Under the binding element, there is a SOAP WSDL extension element called soap:binding. This element determines the binding style (rpc or document) and the transport mechanism (SOAP over HTTP, SMTP, and so on). In our example, the binding style is rpc, and the transport mechanism is SOAP over HTTP. Next, for each operation that the Web service provides, you need to specify the value of the SOAPAction HTTP header. This is achieved by using the operation element, with the name attribute having the value as that of the operation defined earlier. Within this operation element, you need to add the SOAP WSDL extension element operation, with the soapAction attribute specifying the HTTP header that the client sends when it invokes the Web service. Finally, you need to specify the data encoding style for the input and output messages. This is done using the input and output elements, with a soap:body SOAP WSDL extension element. The value of the encodingStyle attribute of the soap:body SOAP WSDL extension element shows that the encoding style is as described in the SOAP 1.1 specification.
JAX and Web Services: The Great Car Parts Company Scenario Let’s now look at how the Great Car Parts Company can leverage the Web services environment and the Java APIs for XML to meet its business needs. Recall that the Great Car Parts Company has decided to add mobile phone chargers to the list of items it sells. To buy the chargers, it discovers wholesalers for chargers, gets their price lists, decides on the best bid, and places procurement orders. In the Web services scenario, Jack, the procurement person, asks the company’s information services team to design and develop a procurement application for him. The information services team decides to use Java and JAX to develop the procurement application.
33
34
CHAPTER 2
Components of Web Services
This is how the procurement application works: 1. The application uses JAXR to send a query to the UDDI registry to find whole-
salers for chargers. 2. The UDDI registry receives the request and applies the search criteria specified
in the JAXR code. 3. The result, containing the list of wholesalers, is sent back to the client as a
SOAP message. 4. Using the results of the query, the application uses JAXM to request price lists
from the different companies. 5. Upon receiving the request, the wholesalers do a JAX-RPC on the manufac-
turer’s Web service to find out about stock availability and possible price fluctuations. 6. Based on the response to the JAX-RPC, the wholesalers respond back to Great
Car Parts Company’s requesting application with the prices in an XML document. 7. The application uses JAXP to parse the price lists and decide on the company
that quotes the lowest price as the chief supplier. 8. The application creates an XML-based order form containing the number of
mobile phone chargers it wants to buy. 9. A JAXM message is created, and the order form is attached to it. This JAXM
message is then sent to the company, which acknowledges the receipt of the order via JAXM. Now that the procurement part has been taken care of, the Great Car Parts Company has to update its Web site to reflect the new item, as well as the selling price. To do so, a combination of JSP and JAXP is used. The JSP page uses JAXP to get the price information from the lowest bidder’s XML price sheet, raises the figure by 20%, then displays the price as an HTML page.
Summary In this chapter, you learned about Web services and their architectural components. You learned about the structure and composition of SOAP messages and WSDL documents, and how these XML documents help in doing RPCs and other B2B communication over the Internet. You learned about the UDDI registry specification and how it helps in the publishing and discovery of Web services. You also learned about how JAX helps in creating and using Web services. This information will come in handy whenever you want to create and deploy Web services.
PART II JAXP: Java API for XML Processing IN THIS PART 3 Implementing Simple APIs for XML 4 Advanced Use of SAX 5 The Document Object Model 6 XSLT and XPath
3 Implementing Simple APIs for XML An XML document is essentially a text document that is meaningful only when an application can process it and get the desired data. There are three standards by which an XML document can be processed: Simple APIs for XML (SAX), Document Object Model (DOM), and XSL Transformations (XSLT). SAX is a public domain API that uses an event-driven mechanism to parse XML documents. This implies that the parser reads an XML document, and each time it recognizes a valid XML syntax (such as \common\lib location.
Setting Up JAXP and the JAXP Reference Implementation After you have downloaded the JWSDP and run the installer, you need to set up the JAXP and JAXP reference implementation JAR files so the Java compiler can find the necessary library files when compiling your application. Setting up the JAR files depends on the version of JDK being used. Java 1.2 or Java 1.3 If you are using Java 1.2 or 1.3, you can make the JAR files available in one of the following two ways: • To make the JAR files available as standard extensions, place all the JAR files in the /jre/lib/ext location. • To make the JAR files available through the classpath mechanism, you can either add the JAR files to the classpath environment variable, or use the -classpath option.
CAUTION You should follow only one of the two mechanisms as suggested here, not a mixture of both. This is because the way the compiler works is that only the referenced classes are loaded from the ext directory, and classpath settings are not considered when calculating references. But when the classpath is searched, the ext directory is not searched because all ext classes are expected to have been loaded. Therefore, splitting the JAR files between the two locations can create a situation where a class referenced on the classpath has not been loaded from the ext directory, after which it cannot be found. This will lead to compilation errors.
Java 1.4 As of this version, Xalan libraries are part of the standard Java 1.4 platform. However, because the Xalan libraries are developed and released independent of Java versions, newer versions of the libraries may be available for use before newer versions of Java are released. In fact, the Xalan libraries that are part of the JWSDP download pack are newer than the ones that are included with the Java 1.4 platform. Naturally, you would want to use the latest libraries while compiling and running your application.
47
48
CHAPTER 3
Implementing Simple APIs for XML
Because the Xalan libraries are part of the core JVM, using the –classpath option to indicate the path of the newer libraries will not work. This is because if a library is available in the core JVM, the compiler will always use it and ignore the settings specified in the –classpath option. To overcome this problem, Java 1.4 provides the Endorsed Standards Override Mechanism, which lets you override the core libraries of the Java 1.4 platform. To do so, you need to place the updated libraries in the /jre/lib/endorsed location. Therefore, for the Java 1.4 version, place all the JAR files except jaxp-api.jar in the /jre/lib/endorsed location.
The jaxp-api.jar file need not be put into the endorsed location, because it is released by Sun and is not an endorsed standard. This file can stay where it is: in the /common/lib location.
There is another way by which you can ensure that the newer JAR files are added to the JVM dynamically when you execute the application. This is achieved by setting the appropriate values in the java.endorsed.dirs system property. Setting this property ensures that specified JAR files will be searched before the core classes of the JVM. However, you need to remember that there is no fixed order in which the JAR files will be searched. Therefore, you need to ensure that when using this property, there are no overlaps of classes defined in the JAR files.
Creating a SAX-Parsing Application Now that the JAXP APIs are set up, let’s begin the task of creating an application that uses a SAX parser to parse an XML file.
Creating the CarParts.xml File In this chapter, an XML file that describes the parts of a car will be used as an example. The XML file will be named CarParts.xml. To create it, open the text editor of your choice, copy the following code, and save the file as CarParts.xml:
Creating a SAX-Parsing Application
Before proceeding to write the application code, let’s briefly examine the XML file. The first line
identifies the file as an XML document. The next line
Next, the application needs to be updated with the error-handling code: 1. Create a class that implements the ErrorHandler interface. For our example, we will call the class MyErrorHandler. 2. Register the class with the XMLReader by using the setErrorHandler() method. 3. Put a try-catch block around the parse() method to catch the exceptions. You need to catch the SAXExceptions and SAXParseExceptions to handle all
parsing errors. To create the class that implements the ErrorHandler interface, add the lines shown in Listing 3.5.
Creating a SAX-Parsing Application
LISTING 3.5
Implementing ErrorHandler
public class MyXMLHandler extends DefaultHandler{ public static void Main(String[] args) throws exception { ……….. } static class MyErrorHandler implements ErrorHandler { public void fatalError(SAXParseException saxException) { System.out.println(“Fatal Error occurred “+ saxException); } public void error(SAXParseException saxException) { System.out.println(“Error occurred “+ saxException); } public void warning(SAXParseException saxException) { System.out.println(“warning occurred “+ saxException); } } } //End of MyXMLHandler
You created an internal static class MyErrorHandler, which implements the ErrorHandler interface. The three methods of the ErrorHandler interface will now handle all types of errors that are generated while parsing an XML document. Next, the class is to be registered with the XMLReader. To do so, add the following lines in bold to the application: /*XML Reader is the interface for reading an XML document using callbacks*/ XMLReader xmlReader = saxParser.getXMLReader(); /*set the error handler*/ xmlReader.setErrorHandler(new MyErrorHandler()); xmlReader.setContentHandler(new MyXMLHandler());
Finally, the try-catch block needs to be put around the parse() method. To do so, add the lines of code displayed in Listing 3.6.
55
56
CHAPTER 3
LISTING 3.6
Implementing Simple APIs for XML
Adding the try-catch Block
xmlReader.setContentHandler(new MyXMLHandler()); try{ /*Parse an XML document - the document is read and overridden ➥ callbacks in the MyXMLHandler are invoked*/ xmlReader.parse(“CarParts.xml”); } catch (SAXParseException saxException) { /* If there are errors in XML data are trapped and location is displayed*/ System.out.println(“\n\nError in data.xml at line:” ➥+saxException.getLineNumber()+ ➥”(“+saxException.getColumnNumber()+”)\n”); System.out.println(saxException.toString()); } catch (SAXException saxEx) { /* If there are errors in XML data, the detailed ➥message of the exception is displayed*/ System.out.println(saxEx.getMessage()); } } //end of main method
Now the application is capable of handling all the possible types of errors that can be generated while parsing an XML document. NOTE The code discussed here is available in the example02 folder. This folder also contains the sample CarParts.xml file.
Compile and run the application. The output should be similar to the following: -----Reading the document data.xml with MyXMLHandler-----Start Element-> carparts Start Element-> engine Fatal Error occurred org.xml.sax.SAXParseException: Expected “” ➥to terminate element starting on line 5. Error in data.xml at line:6(-1) org.xml.sax.SAXParseException: Expected “” to terminate element ➥starting on line 5.
Creating a SAX-Parsing Application
As displayed in the listing, when the parser gets a fatal error, it throws a SAXParseException and calls the fatalError() method. So far, the parsing application can process the elements in the XML file and handle the parsing errors. Next, you will enable the application to handle element attributes.
Handling Attributes The existing CarParts.xml file does not have any element attributes. To add attributes, update the XML file as in Listing 3.7. The element attributes that are to be added are displayed in bold. LISTING 3.7
Adding Element Attributes
After updating the XML file, update the application code to handle the attributes. There is no separate callback method per se for attributes. When the startElement() method is invoked, the list of attributes for the element is passed to the method as an Attributes object. The attributes can be accessed in three different ways: • By the attribute index • By the namespace-qualified name • By the qualified (prefixed) name In our application, the attributes are accessed by the attribute index and by the qualified (prefixed) name. The application logic is as follows: When the startElement() method is called, the application will look for an attribute called price. If the
57
58
CHAPTER 3
Implementing Simple APIs for XML
attribute named price is found, the value of the attribute is printed and the remaining attributes are ignored. If the price attribute is not found, all the attributes and their values are printed. The printing of all attributes is handled through a function named printAllAttributes(). This method takes the Attributes object as its only parameter. First, the startElement() method is to be updated according to this logic. To do so, add the lines displayed in bold in Listing 3.8. LISTING 3.8
Accessing Element Attributes
public void startElement(String namespaceURI, String localName, String qualifiedName, Attributes elementAttributes) { System.out.println(“Start Element-> “+qualifiedName); /* Get the index of price attributes*/ int indexOfPrice=elementAttributes.getIndex(“price”); /* If a price attribute does not exist ➥then all the attributes are printed out*/ /* Note that in the sample the attribute name ➥is case sensitive so all attributes of carstereo get printed out*/ if(-1==indexOfPrice) printAllAttributes(elementAttributes); else System.out.println(“\tPrice= “+ ➥elementAttributes.getValue(“price”)); }
Next, add the code for the printAllAttributes() method. To do so, add the lines displayed in bold. public void printAllAttributes(Attributes elementAttributes) { System.out.println(“\tTotal Number of Attributes: “+ ➥elementAttributes.getLength()); for(int i=0;i carparts Total Number of Attributes: 0 Start Element-> engine Price= 3500 End Element-> engine Start Element-> carbody Total Number of Attributes: 2 Attribute: type = Tallboy Attribute: color = blue End Element-> carbody Start Element-> wheel Price= 120 End Element-> wheel Start Element-> carstereo Total Number of Attributes: 3 Attribute: manufacturer = MagicSound Attribute: model = T76w Attribute: Price = 500 End Element-> carstereo End Element-> carparts End Document: ----------------Finished Reading ➥the document---------------------
Next, the application will be enhanced to handle the processing instructions.
Handling Processing Instructions Processing instructions are declarations in which you can provide specific instructions for specific applications.
59
60
CHAPTER 3
Implementing Simple APIs for XML
The format for a processing instruction is , where target is the application that is expected to do the processing, and data is the information for the application to process. Add the lines displayed in bold in Listing 3.10 to add a processing instruction to the CarParts.xml file. Note that in addition to the processing instruction, a new element called Supplier is also being added. LISTING 3.10
Adding a Processing Instruction to CarParts.xml
Here the target application is called supplierformat, and the data that the supplierformat application has to process is format=”X13” version=”3.2”. The processing instructions are handled through the processingInstruction() callback method defined in the ContentHandler interface. In MyXMLHandler, override the processingInstruction() method to display the name of the target application and the data. Both of these are passed as parameters to the processingInstruction() method. To enhance the application to handle processing instructions, add the lines displayed in bold in Listing 3.11. LISTING 3.11
Implementing the processingInstruction()Method
public void endElement(String namespaceURI, String localName, String qualifiedName) { System.out.println(“End Element-> “+qualifiedName); }
Creating a SAX-Parsing Application
LISTING 3.11
Continued
public void processingInstruction(java.lang.String target, java.lang.String data) { System.out.println(“Processing Instruction-> on target: “+ ➥target+ “\n\t\t\t and data: “+data); } public void endDocument() { System.out.println(“End Document: \n---------------➥Finished Reading the document---------------\n”); }
This overrides the processingInstruction() method to display the name of the target application and the data that it will process. NOTE The code discussed here is available in the example04 folder. This folder also contains the sample CarParts.xml file.
Compile and run the application. The output should be similar to Listing 3.12. LISTING 3.12
Output of MyXMLHandler with Processing Instructions
Start Document: -----Reading the document CarParts.xml with MyXMLHandler-----Start Element-> carparts Total Number of Attributes: 0 Processing Instruction-> on target: supplierformat and data: format=”X13” version=”3.2” Start Element-> supplier Total Number of Attributes: 2 Attribute: name = Car Parts Heaven Attribute: URL = http://carpartsheaven.com End Element-> supplier Start Element-> engine Price= 3500 End Element-> engine Start Element-> carbody Total Number of Attributes: 3 Attribute: id = C32
61
62
CHAPTER 3
Implementing Simple APIs for XML
LISTING 3.12
Continued
Attribute: type = Tallboy Attribute: color = blue End Element-> carbody Start Element-> wheel Price= 120 End Element-> wheel Start Element-> carstereo Total Number of Attributes: 4 Attribute: id = C2 Attribute: manufacturer = MagicSound Attribute: model = T76w Attribute: Price = 500 End Element-> carstereo End Element-> carparts End Document: ----------------Finished Reading ➥the document---------------------
The application at this point is capable of processing the elements and their attributes. It can also handle processing instructions and exceptions thrown by the SAX parser. Next, the application will be updated to handle the content that is present between the tags.
Handling Characters We will make the following two changes to the CarParts.xml: • The CarParts.xml will be enhanced to handle multiple entries of engines, wheels, car bodies, and stereos. • Add content between the tags. To make the changes in the CarParts.xml file, add the lines displayed in bold in Listing 3.13. LISTING 3.13
Adding Data to Tags
Creating a SAX-Parsing Application
LISTING 3.13
Continued
Engine 1 Car Body 1 Wheel Set 1 Car Stereo 1
Here you’ve introduced four new elements (engines, carbodies, wheels, and carstereos) to store multiple entries of engines, car bodies, wheels, and car stereos. You’ve also added the content between the engine, carbody, wheel, and carstereo tags. These are required to demonstrate a specific behavior of the characters() callback method. Next, the application needs to be updated to handle the content between the tags. The content between the tags is handled by overriding the characters() callback method of the ContentHandler interface. To override the characters() method to display the content between the tags, add the lines listed in bold in Listing 3.14. LISTING 3.14
Implementing the characters() Method
public void endElement(String namespaceURI, String localName, String qualifiedName) { System.out.println(“End Element-> “+qualifiedName);
63
64
CHAPTER 3
Implementing Simple APIs for XML
LISTING 3.14
Continued
} public void characters(char[] ch, int start, int length) { System.out.println(“Characters: “ + new String(ch,start,length)); } public void endDocument() { System.out.println(“\n End Document: ----------------Finished ➥Reading the document---------------------\n”); }
This overrides the characters() method to display the text between the tags. NOTE The code discussed here is available in the exampl02A01 folder. This folder also contains the sample CarParts.xml file.
Compile and run the program. The output should be similar to Listing 3.15. LISTING 3.15
Output of MyXMLHandler with characters() Method
Start Document: -----Reading the document CarAPrts.xml with MyXMLHandler-----Start Element-> carparts Total Number of Attributes: 0 Characters: Characters: Start Element-> supplier Total Number of Attributes: 2 Attribute: name = Car Parts Heaven Attribute: URL = http://carpartsheaven.com Characters: End Element-> supplier Characters: Start Element-> engines Total Number of Attributes: 0
Creating a SAX-Parsing Application
LISTING 3.15
Continued
Characters: Start Element-> engine Price= 3500 Characters: Engine 1 Characters: End Element-> engine Characters: End Element-> engines Characters: Start Element-> carbodies Total Number of Attributes: 0 Characters: Start Element-> carbody Total Number of Attributes: 3 Attribute: id = C32 Attribute: type = Tallboy Attribute: color = blue Characters: Car Body 1 Characters: End Element-> carbody Characters: End Element-> carbodies Characters: Start Element-> wheels Total Number of Attributes: 0 Characters: Start Element-> wheel Price= 120 Characters: Wheel Set 1
65
66
CHAPTER 3
Implementing Simple APIs for XML
LISTING 3.15
Continued
Characters: End Element-> wheel Characters: End Element-> wheels Characters: Start Element-> carstereos Total Number of Attributes: 0 Characters: Start Element-> carstereo Total Number of Attributes: 4 Attribute: id = C2 Attribute: manufacturer = MagicSound Attribute: model = T76w Attribute: Price = 500 Characters: Car Stereo 1 Characters: End Element-> carstereo Characters: End Element-> carstereos Characters: End Element-> carparts End Document: ----------------Finished Reading ➥the document---------------------
Notice that in the output, the characters() method is called between two elements, even if the element contains child elements and no text. For example, the characters() method is called between the carbodies and carbody elements, even though the carbodies element does not contain text and only contains the carbody child element. This happens because, by default, the parser assumes that any element that it sees contains text. As you will see later, using a DTD can ensure that the parser is able to distinguish which elements contain text and which elements contain child elements.
Creating a SAX-Parsing Application
Handling a DTD and Entities So far, what we have seen is an XML document without a Document Type Definition (DTD). A DTD describes the structure of the content of an XML document. It defines the elements and their order and relationship with each other. A DTD also defines the element attributes and whether the element and/or attributes are mandatory or optional. You can use a DTD to ensure that the XML document is well-formed and valid. See Appendix B, “XML: A Quick Tour,” to learn more about DTDs. Next we will create a DTD for our CarParts.xml file and update our application to handle the DTD. To add the DTD to the CarParts.xml file, add the lines displayed in bold in Listing 3.16. Note that in the DTD, we defined two entities (companyname and companyweb) and used them in the name and URL attributes of the supplier element. Entities are analogous to a macro, and they’re a good way to represent information that appears multiple times in an XML document. LISTING 3.16
The DTD for CarParts.xml
carparts (supplier,engines,carbodies,wheels,carstereos)> engines (engine+)> carbodies (carbody+)> wheels (wheel+)> carstereos (carstereo+)> supplier EMPTY> supplier name CDATA #REQUIRED URL CDATA #REQUIRED
> ]> Engine 1 Car Body 1 Wheel Set 1
Creating a SAX-Parsing Application
LISTING 3.16
Continued
Car Stereo 1
Run the application with the updated CarParts.xml file. NOTE The code discussed here is available in the exampl02A02 folder. This folder also contains the sample CarParts.xml file.
The output should be similar to Listing 3.17. LISTING 3.17
Output of MyXMLHandler with DTD
Start Document: -----Reading the document CarParts.xml with MyXMLHandler-----Start Element-> carparts Total Number of Attributes: 0 Start Element-> supplier Total Number of Attributes: 2 Attribute: name = Heaven Car Parts (TM) Attribute: URL = http://carpartsheaven.com Characters: End Element-> supplier Start Element-> engines Total Number of Attributes: 0 Start Element-> engine Price= 3500 Characters: Engine 1 Characters: End Element-> engine End Element-> engines Start Element-> carbodies
69
70
CHAPTER 3
Implementing Simple APIs for XML
LISTING 3.17
Continued
Total Number of Attributes: 0 Start Element-> carbody Total Number of Attributes: 3 Attribute: id = C32 Attribute: type = Tallboy Attribute: color = blue Characters: Car Body 1 Characters: End Element-> carbody End Element-> carbodies Start Element-> wheels Total Number of Attributes: 0 Start Element-> wheel Price= 120 Characters: Wheel Set 1 Characters: End Element-> wheel End Element-> wheels Start Element-> carstereos Total Number of Attributes: 0 Start Element-> carstereo Total Number of Attributes: 4 Attribute: id = C2 Attribute: manufacturer = MagicSound Attribute: model = T76w Attribute: Price = 500 Characters: Car Stereo 1 Characters: End Element-> carstereo End Element-> carstereos End Element-> carparts End Document: ----------------Finished Reading ➥ the document---------------------
Creating a SAX-Parsing Application
Notice that with the DTD in place, the characters() method is now called only for those elements that have text following them. It is no longer called for the elements that have only child elements. However, if you want to get the whitespace between the elements that have child elements, you will need to override the ignorableWhitespace() method of the ContentHandler interface. One of the possible scenarios in which you may override the ignorbaleWhitespace() method is when your application has to process an XML file to generate another human-readable XML file. Overriding the ignorableWhitespace() method will help retain the formatting of the XML document. Also, the companyname and the companyweb entities have been resolved and replaced with their values in the output. So far, we have been using a nonvalidating parser to parse the XML document. A nonvalidating parser can check whether a document is well-formed. However, it cannot determine whether the document is valid with respect to the DTD. For this, a validating parser is required.
Using a Validating Parser To generate a validating parser, add the lines listed in bold: static public void main(String[] args) throws Exception { ...... /*Create a SAX Parser Factory*/ SAXParserFactory parseFactory = SAXParserFactory.newInstance(); /*Set to generate Validating SAX Parser */ parseFactory.setValidating(true); /*Obtain a validating SAX Parser */ SAXParser saxParser = parseFactory.newSAXParser(); ...... }
The setValidating() method sets the parser to validate the XML document as it is being parsed. All other instances of the parser created from this instance of the factory will also be validating. NOTE The code discussed here is available in the exampl02A03 folder. This folder also contains the sample CarParts.xml file.
Compile and run the program. The output should be similar to Listing 3.18.
71
72
CHAPTER 3
Implementing Simple APIs for XML
LISTING 3.18
Output of MyXMLHandler with Parser in Validating Mode
Version 2A03.0 of MyXMLHandler in example02A03 Start Document: -----Reading the document CarParts.xml with MyXMLHandler-----Start Element-> carparts Total Number of Attributes: 0 Start Element-> supplier Total Number of Attributes: 2 Attribute: name = Heaven Car Parts (TM) Attribute: URL = http://carpartsheaven.com Characters: Error occurred org.xml.sax.SAXParseException: ➥The content of element type “supplier” must match “EMPTY”. End Element-> supplier Start Element-> engines Total Number of Attributes: 0 Start Element-> engine Price= 3500 Characters: Engine 1 Characters: End Element-> engine End Element-> engines Start Element-> carbodies Total Number of Attributes: 0 Start Element-> carbody Total Number of Attributes: 3 Attribute: id = C32 Attribute: type = Tallboy Attribute: color = blue Characters: Car Body 1 Characters: End Element-> carbody End Element-> carbodies Start Element-> wheels Total Number of Attributes: 0 Start Element-> wheel Price= 120
Creating a SAX-Parsing Application
LISTING 3.18
Continued
Characters: Wheel Set 1 Characters: End Element-> wheel End Element-> wheels Start Element-> carstereos Total Number of Attributes: 0 Error occurred org.xml.sax.SAXParseException: Attribute ➥”price” is required and must be specified for element type “carstereo”. Error occurred org.xml.sax.SAXParseException: ➥Attribute “Price” must be declared for element type “carstereo”. Start Element-> carstereo Total Number of Attributes: 4 Attribute: id = C2 Attribute: manufacturer = MagicSound Attribute: model = T76w Attribute: Price = 500 Characters: Car Stereo 1 Characters: End Element-> carstereo End Element-> carstereos End Element-> carparts End Document: ----------------Finished Reading ➥the document---------------------
Notice that the parser generates two errors related to the price attribute of the carstereo element. Going back to the CarParts.xml file, you will notice that while the DTD defines the attribute as price, the actual XML document itself has it listed as Price. Therefore, by using a combination of DTD and a validating parser, you can ensure that your XML document is both well-formed and valid.
73
74
CHAPTER 3
Implementing Simple APIs for XML
Summary In this chapter you learned about the SAX packages and the key JAXP libraries and classes that are required for creating and using a SAX parser. You also learned to set up JAXP for different versions of Java, and created an application that uses a SAX parser. In the next chapter, we’ll explore more advanced uses of SAX.
4 Advanced Use of SAX
IN THIS CHAPTER • Identifying Document and
Event Locations • Handling Lexical Events
SAX provides a number of interfaces and classes with which you can build complex XML-enabled applications. This chapter covers the more advanced uses of SAX, such as working with the document locators, processing lexical information, customizing the external entity resolution process, and the handling of namespaces. You will also learn how to generate SAX events on a standard text file.
Identifying Document and Event Locations The SAX package contains an interface called Locator. This interface provides methods with which you can associate an event with its location in the document. Specifically, by using the methods of the Locator interface, you can find out the following information: • The public identifier (URN) of the document being parsed • The system identifier (URL) of the document being parsed • The line number in the XML document where a particular event occurred • The column number in the XML document where a particular event occurred
• Customizing External Entity Resolution • Handling Namespaces • Generating SAX Events from a Text File
76
CHAPTER 4
Advanced Use of SAX
URN VERSUS URL A URN is an Internet resource that is persistent and location-independent. A URL is a type of URN. For example, an URN could look like the following: urn:def://turbo_engines In this scheme, def could be a registry of all dictionaries in the Internet, and turbo_engines the specific term whose meaning you wanted to find. The result of using this URN could be the whole result set of definitions from all dictionaries. The important part is that as a user you do not need to worry about the server names or exact location of the resources. A URL, on the other hand, requires that you know where a resource is located and its filename. For example, consider this hypothetical URL that will get the meaning of the term turbo_engine from the samsdictionary Web site: http://www.samsdictionary.com/turbo_engine.htm In this case, you need to know the name of the server, the path to the file, its name and suffix.
This information can be used by an application in various ways. For example, the URL information can be used to find something relative to the current document. You can think of this in the way a Web browser resolves an anchor tag such as somelink. The browser uses the location of the current document to find linktoFile. Similarly, the line number information can be used to print diagnostic messages. The Locator object is passed to the application by using the setDocumentLocator() method of the ContentHandler interface. This method takes an instance of the Locator object as its only parameter. The application can then use the instance of the Locator object to find out the location of any ContentHandler event. It is important to remember that the setDocumentLocator() method is called only once at the beginning of the parse. Therefore, if the application needs to find out the location of other ContentHandler events, it needs to save the reference to the Locator object when the setDocumentLocator() method is called. You will now enhance the MyXMLHandler to do the following: • Display the URL of the XML document being parsed. • Display the line numbers in the XML document at which the ContentHandler events are generated. To do so, add the lines of code displayed in bold in Listing 4.1.
Identifying Document and Event Locations
LISTING 4.1
Using Locator
public class MyXMLHandler extends DefaultHandler { Locator l1; public void setDocumentLocator(Locator l) { System.out.println(“Locator :” + l.getSystemId() + “\n”); l1 = l; }
public void startElement(String namespaceURI, String localName, String qualifiedName, Attributes elementAttributes) { System.out.println(“Location of event at line number:” + ➥l1.getLineNumber()); System.out.println(“Start Element-> “+qualifiedName); ............................. }
Here we’ve declared a reference to the Locator object to store the Locator object that will be passed by the parser. Next, in the setDocumentLocator() method, the getSystemId() method of the Locator object is used to get the URL of the CarParts.xml file, and the Locator object is assigned to the reference to the Locator object that was declared earlier. Finally, in the startElement() method, the saved Locator object is used to get the line number in the XML file wherever a ContentHandler event is occurring. The line number is then displayed in the output. NOTE The code discussed so far is available in the example0401 folder. This folder also contains the sample CarParts.xml file.
Compile and run the program. The result of using the Locator object is displayed in bold in Listing 4.2.
77
78
CHAPTER 4
LISTING 4.2
Advanced Use of SAX
Output of MyXMLHandler Application with Locator
Version 2A03.0 of MyXMLHandler in example02A03 Locator :file:///D:/sams_work/Java Api/Chapter 4➥SAX APIs - Advanced Use/Example0401/CarParts.xml
Start Document: ----➥Reading the document CarParts.xml with MyXMLHandler-----Location of event at line number :47 Start Element-> carparts Total Number of Attributes: 0 Location of event at line number :49 Start Element-> supplier Total Number of Attributes: 2 Attribute: name = Heaven Car Parts (TM) Attribute: URL = http://carpartsheaven.com Characters: End Element-> supplier Location of event at line number :51 Start Element-> engines Total Number of Attributes: 0 Location of event at line number :52 Start Element-> engine Price= 3500 Characters: Engine 1 Characters: End Element-> engine End Element-> engines Location of event at line number :56 Start Element-> carbodies Total Number of Attributes: 0 Location of event at line number :57
Identifying Document and Event Locations
LISTING 4.2
Continued
Start Element-> carbody Total Number of Attributes: 3 Attribute: id = C32 Attribute: type = Tallboy Attribute: color = blue Characters: Car Body 1 Characters: End Element-> carbody End Element-> carbodies Location of event at line number :61 Start Element-> wheels Total Number of Attributes: 0 Location of event at line number :62 Start Element-> wheel Price= 120 Characters: Wheel Set 1 Characters: End Element-> wheel End Element-> wheels Location of event at line number :66 Start Element-> carstereos Total Number of Attributes: 0 Location of event at line number :67 Start Element-> carstereo Total Number of Attributes: 4 Attribute: id = C2 Attribute: manufacturer = MagicSound Attribute: model = T76w Attribute: Price = 500 Characters: Car Stereo 1 Characters:
79
80
CHAPTER 4
LISTING 4.2
Advanced Use of SAX
Continued
End Element-> carstereo End Element-> carstereos End Element-> carparts End Document: ---------------➥Finished Reading the document---------------------
Handling Lexical Events Lexical information in an XML document implies information that pertains to the text of the XML itself. In an XML document, the CDATA section, comments, and the references to parsed entities constitute the lexical information. Normally, the CDATA section is used in an XML document when you want to store text that is not be parsed. This happens when an element contains large sections of text that might include special characters, and it is inconvenient to replace each occurrence with an appropriate entity reference. The CDATA section is analogous to the tags of HTML. For example, to put the following text in an XML file, you will need to escape every occurrence of , and &; otherwise, the parser will generate errors: >>>>>>>>>>>>>>>>SAMS Publishing is the &best& ]>
Handling Lexical Events
LISTING 4.4
Continued
&companyname; Engine 1 Car Body 1 Wheel Set 1 Car Stereo 1 >>>>>>>> ➥>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>SAMS Publishing is the &best& ➥ carbody Total Number of Attributes: 3 Attribute: id = C32 Attribute: type = Tallboy Attribute: color = blue Characters: Car Body 1 Characters: End Element-> carbody End Element-> carbodies Location of event at line number :23 Start Element-> wheels Total Number of Attributes: 0 Location of event at line number :24 Start Element-> wheel Price= 120 Characters: Wheel Set 1 Characters: End Element-> wheel End Element-> wheels Location of event at line number :28
Customizing External Entity Resolution
LISTING 4.6
Continued
Start Element-> carstereos Total Number of Attributes: 0 Location of event at line number :29 Start Element-> carstereo Total Number of Attributes: 4 Attribute: id = C2 Attribute: manufacturer = MagicSound Attribute: model = T76w Attribute: Price = 500 Characters: Car Stereo 1 Characters: End Element-> carstereo End Element-> carstereos Location of event at line number :33 Start Element-> forCDATA Total Number of Attributes: 0 Starting CDATA Section Characters: Special Text: >>>>>>>>>>>>>>>>> ➥SAMS Publishing is the &best& red xxxxxx 200 yyy 1200
Now assume that the price has two different definitions on how it should be processed. This can occur if the stereo vendors are different. In such a case, although the element name is the same, the two price elements belong to different definitions. To allow such cases, in which the XML data is referring to multiple DTDs, the namespace feature is used. NOTE By default, if no namespaces are defined, all the elements and attributes belong to a single default namespace.
A namespace essentially maps an element prefix to a URI, which uniquely resolves the tag to a specific DTD. This is how the price element problem could be solved: Assume that the DTD for describing the stereo is detailed in www.carstereo.com/DTD/carstereo.dtd. So, with namespaces, the XML document will look like this: red xxxxxx 200 yyy 1200
Handling Namespaces
With the namespaces enabled, the ambiguity caused by similar tags in an XML document is resolved. To understand how the SAX APIs handle namespaces, you will now modify the CarParts.xml file and the MyXMLhandler application. For the sake of brevity and clarity of code and output, use the CarParts.xml file and MyXMLHandler.java application located in the example03 folder as the source and modify them. First, you will modify the CarParts.xml file and introduce namespaces. To do so, add the lines listed in bold in Listing 4.10. LISTING 4.10
Introducing Namespaces into CarParts.xml
ALFA37D
Next, modify the MyXMLHandler.java application to handle the namespaces. For an application to handle namespaces, the parser needs to be set as namespace aware. This is done by the setNamespaceAware() method of the SAXParserFactory class. To make a parser namespace aware, add the line listed in bold in Listing 4.11.
99
100
CHAPTER 4
Advanced Use of SAX
LISTING 4.11
Making MyXMLHandler Namespace Aware
static public void main(String[] args) throws Exception { System.out.println(“\nVersion 0404.0 of MyXMLHandler in example0404\n”); /*Create a SAX Parser Factory*/ SAXParserFactory parserFactory = SAXParserFactory.newInstance(); /*enable namespacing*/ parserFactory.setNamespaceAware(true); /*Obtain a SAX Parser */ SAXParser saxParser = parserFactory.newSAXParser(); .......... }
By default, the startElement() and endElement() methods take the namespaceURI as one of their parameters. Therefore, an application that needs to process namespace information can use it directly. For the MyXMLHandler application, you will display the namespaces. To do so, add the lines listed in bold in Listing 4.12. LISTING 4.12
Displaying Namespaces
public void startElement(String namespaceURI, String localName, String qualifiedName, Attributes elementAttributes) { System.out.println(“Start Element-> “+” ➥[“+namespaceURI+”]”+qualifiedName); /* Get the index of price attributes*/ int indexOfPrice=elementAttributes.getIndex(“price”); /* If a price attribute does not exist then all ➥the attributes are printed out*/ /* Note that in the sample the attribute name is ➥case sensitive so all attributes ➥ of carstereo get printed out*/ if(-1==indexOfPrice) printAllAttributes(elementAttributes); else
Handling Namespaces
LISTING 4.12
Continued System.out.println(“\tPrice= “+ ➥elementAttributes.getValue(“price”));
} public void endElement(String namespaceURI, String localName, String qualifiedName) { System.out.println(“End Element-> “+” [“+namespaceURI+”]”+ ➥qualifiedName); }
NOTE The code discussed here is available in the example0404 folder. This folder also contains the sample CarParts.xml file.
You can now compile and run the program. The output should be similar to the listing shown in Listing 4.13, with the namespace occurrences displayed in bold. LISTING 4.13
Output of MyXMLHandler with Namespace Processing
Version 0404.0 of MyXMLHandler in example0404 Start Document: -----Reading CarParts.xml with MyXMLHandler-----Start Start Start Start
Element-> []carparts Element-> []engines Element-> [http://enginesonline.com]engine Element-> [http://enginesonline.com]mpfiengine Attribute: [http://enginespecs.com]enginespecs:documentation = ALFA37D Start Element-> [http://enginesregistration.com]registration:number End Element-> [http://enginesregistration.com]registration:number End Element-> [http://enginesonline.com]mpfiengine End Element-> [http://enginesonline.com]engine Start Element-> []engine Start Element-> []mviengine End Element-> []mviengine End Element-> []engine End Element-> []engines Start Element-> []carbody
101
102
CHAPTER 4
Advanced Use of SAX
LISTING 4.13
Continued
End Element-> []carbody Start Element-> []wheel End Element-> []wheel Start Element-> []carstereo End Element-> []carstereo End Element-> []carparts End Document: ----------------Finished Reading the document-------------------
Generating SAX Events from a Text File So far, you have learned how to parse an XML file and handle events generated by a SAX parser. In this section, you will learn how to use the SAX events to process a text file. To understand how to use SAX events to process a text file, you must do the following: 1. Create a text file containing a hypothetical email message. 2. Create a SAX parser that generates callback events for each of the elements of
the email message. The application implementing the SAX parser will handle the callback events. 3. Create the application that will use the SAX parser.
Let’s look at each of these steps in detail.
Creating the SampleMailMessage.txt File The first step is to create the text file containing the mail message. As is normally the case with mail messages, it will have the following entries: • From • To • CC • BCC • Subject • MailBody
Generating SAX Events from a Text File
To create the text file, open the text editor of your choice, enter the following code, and save the file as SampleMailMessage.txt: From:
[email protected] To:
[email protected] CC:
[email protected] BCC:
[email protected] Sent:04/01/2001 Subject:Your Books MailBody:Hi, We think your books are great and are of great ➥ value to all readers. Thanks and keep the good work going.
As shown, the hypothetical mail message is from
[email protected]. It is sent to
[email protected] complimenting the quality of their books.
[email protected] and
[email protected] are on the CC and BCC lists, respectively. The SAX parser you are going to write will generate callback events for each of the elements of the mail message: From, To, CC, BCC, Sent, Subject, and MailBody.
Creating the SAX Parser The next step is to create the parser. The parser will be named MySAXEventGenerator. To create it, you’ll need to do the following: 1. Import the necessary packages. 2. Implement the XMLReader interface. 3. Create ContentHandler, String, and Attributes variables. 4. Implement the parse() method. In the parse() method, iterate over the file
and generate callback methods for each of the elements of the mail message. 5. Implement the other methods of the XMLReader interface. For this example,
having do-nothing methods will suffice.
Importing the Packages The first step is to import the packages necessary for the SAX parser program to compile successfully. To create the SAX parser, the SAX packages and the io packages must be imported. The SAX packages define the interfaces and methods required for the SAX parser, and the io package is needed for the input/output operations.
103
104
CHAPTER 4
Advanced Use of SAX
To begin creating a SAX parser named MySAXEventGenerator, launch a text editor and create a file called MySAXEventGenerator.java. To import the packages, add the following lines: import java.io.*; import org.xml.sax.*; import org.xml.sax.helpers.AttributesImpl;
Here we’ve imported the io and SAX packages, which contain the necessary methods and interfaces for creating the SAX parser. Implementing the XMLReader Interface The next step is to create the class declaration and implement the XMLReader interface. The XMLReader interface provides the necessary methods to read a document using callbacks. To create the class declarations and implement the XMLReader interface, add the following line of code listed in bold: import java.io.*; import org.xml.sax.*; import org.xml.sax.helpers.AttributesImpl;
public class MySAXEventGenerator implements XMLReader {
Instantiating the Variables Next, we’ll instantiate the String and Attributes variables. Start by declaring a reference to ContentHandler, and instantiate String and an Attributes variable. The ContentHandler reference will store the instance of the ContentHandler class when the SAX parser is called from an application. The String variable will be used to pass the namespaceURI parameter, and the Attributes variable will be used to pass the Attributes parameter in the startElement and endElement callback methods. To instantiate the variables, add the lines of code shown in bold in Listing 4.14. LISTING 4.14
Instantiating Variables
import java.io.*; import org.xml.sax.*; import org.xml.sax.helpers.AttributesImpl;
Generating SAX Events from a Text File
LISTING 4.14
Continued
public class MySAXEventGenerator implements XMLReader { ContentHandler handler; // There are no namespaces and no attributes used in this example String nsURI = “”; // NamespaceURI Attributes atts = new AttributesImpl();
Here we’ve declared the reference to the ContentHandler and instantiated the String and Attributes variables. Notice that they are all null. This is because the calling application will use the setContentHandler() method of the XMLReader interface to set the reference to the ContentHandler. Also, there are no namespace and attributes in the document to be parsed. Implementing the parse() Method Next we’ll implement the methods of the XMLReader interface. We’ll begin by implementing the parse() method, because it does almost all the work for this application. As the name suggests, the parse() method parses the document from any valid input stream. We’ll set the parse() method to do the following: 1. Ensure that the calling application has provided a valid ContentHandler reference. This is required to handle the callback methods generated by the parse()
method. 2. For efficiency reasons, convert InputStream to a BufferedReader. 3. Read the first line from the SampleMailMessage.txt file. 4. Invoke the startDocument() callback method. 5. If the line read from the SampleMailMessage.txt file contains From, To, CC, BCC, Sent, Subject, or MailBody, invoke the startElement(), characters(), and endElement() callback methods. Because each element generates the startElement(), characters(), and endElement() callbacks, we’ll create a method called output() that takes the element name and its content as a para-
meter and then invokes the callback method. 6. After the file has been read completely, invoke the endDocument() callback
method. To do these tasks, add the lines of code listed in bold in Listing 4.15.
105
106
CHAPTER 4
Advanced Use of SAX
LISTING 4.15
Implementing the parse() Method
Attributes atts = new AttributesImpl(); // Parse the input public void parse(InputSource input) throws IOException, SAXException { try { // Get an efficient reader for the file if (handler==null) { throw new SAXException(“No content handler”); } java.io.Reader r = input.getCharacterStream(); BufferedReader br = new BufferedReader(r); String line = br.readLine(); //Invoke the startDocument method handler.startDocument(); do { if (line.startsWith(“From:”)) { output(“From:”, line); } else if (line.startsWith(“To:”)) { output(“To:”, line); } else if (line.startsWith(“CC:”)) { output(“CC:”, line); } else if (line.startsWith(“CC:”)) { output(“BCC:”, line); } else if (line.startsWith(“Sent:”)) { output(“Sent:”, line); } else if (line.startsWith(“Subject:”)) { output(“Subject:”, line); }
Generating SAX Events from a Text File
LISTING 4.15
Continued
else if (line.startsWith(“MailBody:”)) { output(“MailBody:”, line); } } while (null != (line = br.readLine())); handler.endDocument(); } catch (IOException ioex) { System.out.println(ioex.getMessage()); } catch (SAXException saxEx) { /* If there are errors in the data, the detailed message ➥of the exception is displayed*/ System.out.println(saxEx.getMessage()); } } void output(String name, String line) throws SAXException { int textLength = line.length() - name.length(); handler.startElement(nsURI, name, name, atts); handler.characters(line.toCharArray(), name.length(), textLength); handler.endElement(nsURI, name, name); }
In the output() method, the name of the element (such as From, To, and so on) is taken as both the qualified name and local name and then passed to the startElement() and endElement() methods. The nsURI String and the atts Attributes objects that we had instantiated earlier are also passed on as the parameters. These will be used when invoking the startElement() and endElement() methods. In the characters() method, the line read from the file is converted to a character array and passed on as a parameter. The length of the element name and the difference between the length of the line read from the file and the length of the element is passed on as the start position in the array and the number of characters to be read from the array.
107
108
CHAPTER 4
Advanced Use of SAX
Implementing Other Methods Next we’ll need to implement the other methods of the XMLReader interface. For this application, other than the getContentHandler() and the setContentHandler() methods, we’ll simply implement the other methods of the XMLReader interface as do-nothing methods: • setContentHandler(ContentHandler handler) • getContentHandler() • setErrorHandler(ErrorHandler handler) • getErrorHandler() • parse() • parse(InputSource input) • parse(java.lang.String systemId) • getDTDHandler() • getEntyityResolver() • setEntityResolver(EntityResolver resolver) • setDTDHandler(DTDHandler handler) • getProperty(java.lang.String name) • setProperty(java.lang.String name, java.lang.Object value) • setFeature() • getFeature(java.lang.String name) To implement these methods, add the lines listed in bold in Listing 4.16. LISTING 4.16
Implementing the XMLReader Methods
void output(String name, String line) throws SAXException { ....... } // Enable the application to register a content event handler. public void setContentHandler(ContentHandler handler) { this.handler = handler; }
Generating SAX Events from a Text File
LISTING 4.16
Continued
// Return the current content handler. public ContentHandler getContentHandler() { return this.handler; } // Enable the application to register an error event handler. public void setErrorHandler(ErrorHandler handler) { } // Return the current error handler. public ErrorHandler getErrorHandler() { return null; } // Parse an XML document from a system identifier (URI). public void parse(String systemId) throws IOException, SAXException { } //Return the current DTD handler. public DTDHandler getDTDHandler() { return null; } //Return the current entity resolver. public EntityResolver getEntityResolver() { return null; } // Enable the application to register an entity resolver. public void setEntityResolver(EntityResolver resolver) { } // Enable the application to register a DTD event handler. public void setDTDHandler(DTDHandler handler) { } // Get value of a property. public Object getProperty(String name) { return null; } // Set the value of a property. public void setProperty(String name, Object value) { }
109
110
CHAPTER 4
Advanced Use of SAX
LISTING 4.16
Continued
// Set the state of a feature. public void setFeature(String name, boolean value) { } // Get the value of a feature. public boolean getFeature(String name) { return false; } }
We have now successfully created the SAX parser.
Creating the Application The next and final step is to create the application that uses the SAX parser to parse the text file. To create the application, you need to do the following: 1. Import the JAXP classes. 2. Extend the DefaultHandler class. 3. Get an instance of the parser. 4. Set the ContentHandler. 5. Convert the File object to an InputSource object. 6. Call the parse() method. 7. Override the necessary callback methods.
Importing the Packages Launch a text editor and start creating the application that parses the SampleMailMessage.txt file. Name the application MySAXEventGeneratorReader.java. MySAXEventGeneratorReader is a simple application that parses the SampleMailMessage.txt file and displays the structure on the command window. The first step is to import the packages necessary for the application to access the SAX and JAXP APIs. In the MySAXEventGeneratorReader.java file, add the following lines: import import import import
javax.xml.parsers.*; org.xml.sax.*; org.xml.sax.helpers.*; java.io.*;
Generating SAX Events from a Text File
Extending the DefaultHandler Class Next, we need to write the class declaration by extending the DefaultHandler class and entering the main() method: public class MySAXEventGeneratorReader extends DefaultHandler { static public void main(String[] args) throws Exception {
We’ve extended the DefaultHandler because the ContentHandler interface needs to be implemented to handle the callback methods generated by the parser. After extending the DefaultHandler class, we simply need to override the ContentHandler interface methods that are required. Creating an Instance of the SAX Parser Now we’ll create an instance of the SAX parser that we’ve implemented. To do so, add the following line of code to the main() method: MySAXEventGenerator mySAXEventGenerator = new MySAXEventGenerator();
Setting the ContentHandler Now the event handler needs to be registered with the SAX parser. To register an instance of the ContentHandler interface, add the following lines of code: static public void main(String[] args) throws Exception { ......... MySAXEventGenerator mySAXEventGenerator = new MySAXEventGenerator(); mySAXEventGenerator.setContentHandler(new MySAXEventGeneratorReader());
In this case, it will be the instance of the application itself, because it extends the DefaultHandler class. Converting the File Object to an InputSource Object The next step is to convert the file object that is to be parsed to an InputSource object, because the parse() method takes the InputSource object as its only parameter. Converting the File object to an InputSource object is a three-step process. First, you need to convert the File object to a FileReader object. Next, the FileReader object has to be converted to a BufferedReader object. Finally, the BufferedReader object has to be converted into the InputSource object.
111
112
CHAPTER 4
Advanced Use of SAX
To convert the File object to an InputSource object, add the lines of code listed in bold: static public void main(String[] args) throws Exception { ......... mySAXEventGenerator.setContentHandler(new MySAXEventGeneratorReader()); File f = new File(“SampleMailMessage.txt”); FileReader fr = new FileReader(f); BufferedReader br = new BufferedReader(fr); InputSource inputSource = new InputSource(br);
Next, invoke the parse() method. Invoking the parse() Method The parse() method parses the InputSource object and generates the necessary callbacks. To invoke the parse() method, add the lines of code listed in bold in Listing 4.17. LISTING 4.17
Invoking the parse() Method
static public void main(String[] args) throws Exception { ......... InputSource inputSource = new InputSource(br); try{ /*Parse an XML document - the document is read and overridden callbacks ➥in the MySAXEventGeneratorReader are invoked*/ mySAXEventGenerator.parse(inputSource); } catch (SAXParseException saxException) { /* If errors in XML data are trapped and location is displayed*/ System.out.println(“\n\nError in data.xml at ➥line:”+saxException.getLineNumber()+ ➥”(“+saxException.getColumnNumber()+”)\n”); System.out.println(saxException.toString()); } catch (SAXException saxEx) { /* If there are errors in XML data, the ➥detailed message of the exception is displayed*/
Generating SAX Events from a Text File
LISTING 4.17
Continued
System.out.println(saxEx.getMessage()); } } //End of main
After the parsing is started, events are generated whenever an element such as From, To, and so on, is found. To handle these, we’ll need to override the necessary callback methods. Overriding the Callback Methods Looking into the SAX parser code, you will find that the only callback methods that the SAX parser is generating are the startDocument(), startElement(), endElement(), characters(), and endDocument() methods. Therefore, you need to override these five methods in the application. To override these methods, add the lines of code listed in bold in Listing 4.18. LISTING 4.18
Implementing the Callback Methods
} //End of main public void startDocument() { System.out.println(“\n Start Document: -----Reading SampleMailMessage ➥ with MySAXEventGeneratorReader------\n”); } public void startElement(String namespaceURI, String localName, String qualifiedName, Attributes elementAttributes) { System.out.println(“Start Element-> “+qualifiedName); } public void characters(char[] ch, int start, int length) { System.out.println(“Characters: “ + new String(ch,start,length)); } public void endElement(String namespaceURI, String localName, String qualifiedName) { System.out.println(“End Element-> “+qualifiedName); }
113
114
CHAPTER 4
Advanced Use of SAX
LISTING 4.18
Continued
public void endDocument() { System.out.println(“\n End Document: ----------------Finished ➥Reading the document---------------------\n”); } }
NOTE The code discussed here is available in the example0405 folder. This folder also contains the sample CarParts.xml file.
You can now compile and run the program. The output should be similar to the listing shown in Listing 4.19. LISTING 4.19
Output of MySAXEventGeneratorReader
Version 1.0 of MySAXEventGeneratorReader
Start Document: -----Reading SampleMailMessage with ➥MySAXEventGeneratorReader-----Start Element-> From: Characters:
[email protected] End Element-> From: Start Element-> To: Characters:
[email protected] End Element-> To: Start Element-> CC: Characters:
[email protected] End Element-> CC: Start Element-> Sent: Characters: 04/01/2001 End Element-> Sent: Start Element-> Subject: Characters: Your Books End Element-> Subject: Start Element-> MailBody:
Summary
LISTING 4.2
Continued
Characters: Hi, We think your books are great and are of great value to ➥all readers. Thanks and keep the good work going. End Element-> MailBody: End Document: ----------------Finished Reading the document-------------------
We’ve successfully created a SAX parser that generates SAX events from a text file.
Summary In this chapter, you learned about the advanced use of SAX. You also learned to generate SAX events from a simple text file. Later in Chapter 6, “XSLT and XPATH, “ you will see how the simple text file can be transformed into an XML document. These will help you develop complex XML-enabled applications.
115
5 The Document Object Model
IN THIS CHAPTER • Overview • The DOM and the JAXP Packages • Creating a DOM Application
The Document Object Model (DOM) is an API set defined by the W3C DOM Working Group for building an object representation of the contents of an XML file. The JAXP specification endorses the DOM standards and provides a standard, consistent, and vendor-independent API set with which you can create and work in a DOM created from a parsed XML document. This chapter explains how JAXP enables you to process an XML document using a DOM-based parser. This chapter is divided into four sections. The first section explains the DOM APIs included with JAXP and the JAXP package that enables the use of DOM. The remaining three sections take you through a step-by-step process to implement the APIs in an application to process an XML document using a DOM parser.
Overview The DOM object representation is in the form of a tree structure, in which each node of the tree represents a component of the XML document. For example, consider the XML document (CarParts.xml) that describes car parts shown in Listing 5.1. LISTING 5.1
The CarParts.xml File
• Accessing XML Data Using DOM • Managing Data Using DOM
118
CHAPTER 5
LISTING 5.1
The Document Object Model
Continued
Engine 1 CarBody 1 Wheels 1
A graphical representation of the DOM for CarParts.xml is displayed in Figure 5.1.
Document
Comments
FIGURE 5.1
CarParts
DocType
engine
carbody
wheel
car stereo
Engine 1
CarBody 1
Wheels 1
Carstereo 1
Graphical representation of the DOM for the CarParts.xml file.
In the DOM, each entry in the XML file is a node. For each unique constituent element of an XML file, there is a node type. So, a DOM representation of an XML file will contain zero or one doctype nodes, one document element node, and zero or more processing instruction nodes, comment nodes, element nodes, and so on. The document element node is the root of the element tree of the XML document. All other elements of the XML document come under this node. Note that in a DOM structure, data for elements exist as text nodes. For example, in the preceding XML file, the data (Carstereo1) for the carstereo element will be stored in a text node under the carstereo element node. Similarly, the attributes of an element are also nodes, called the attribute nodes. However, the attribute nodes are not part of the document tree. This is because for efficiency reasons the attributes are treated as properties of elements, rather than individual nodes. Table 5.1 shows the node types as defined in the DOM specification along with the node name, value, attribute, and type information.
Overview
TABLE 5.1
Node Types
Node
nodeName()
nodeValue()
Attributes
NodeType()
Attr
Name of the attribute
null
2
CDATASection
#cdata-section
null
4
Comment
#comment
null
8
Document
#document
Value of the attribute Contents of the CDATA section Content of the comment null null
9 11
null
null #documentfragment null null
null null null
NamedNodeMap 1 null 6 null 5
null
null
12
Entire content excluding the target Content of the text node
null
7
DocumentFragment
DocumentType
Document
10
type name Element
Tag name
Entity
Entity name
EntityReference
Name of entity reference
Notation
Notation name
ProcessingInstruction
Target
Text
#text
null
This is very different from the approach the SAX parser takes. As you recall from the discussions in the earlier chapter, the SAX parser is event-based. The SAX parser throws callback methods whenever an XML component, such as the start of an element, is found in the document. This approach makes it very useful for applications that do serial processing of XML, such as Web applications that use XML data for creating HTML documents. Because there is no in-memory representation of the data, a SAX parser is very light on the resources. However, because it’s event-based, an application based on SAX cannot modify the XML data or randomly access parts of an XML document. For example, an application based on the SAX parser cannot add its own element tags or modify the content of an element. Also, it is difficult to use SAX if you have to write application code that depends on the relationship between entities in an XML document. The creation of the in-memory representation of the XML document makes it possible for applications to randomly access any part of the document and modify it. However, because it loads the entire XML document in the memory, DOM is very resource-heavy and might have performance issues with large documents. So, when you have to build applications that modify XML data, or traverse the document multiple times in any order, DOM is the API of choice.
119
120
CHAPTER 5
The Document Object Model
The DOM and the JAXP Packages The DOM APIs are developed and maintained by the W3C DOM Working Group. JAXP endorses the DOM Level 2 Core recommendations by including by reference the packages that contain the DOM APIs. JAXP also contains a package that enables the use of any DOM Level 2-compliant parser to be used in an application. You can learn more about DOM Level 2 specifications at http://www.w3.org/TR/DOM-Level2-Core/. The JAXP package for supporting DOM and the DOM APIs is defined in the following packages: • org.w3c.dom • javax.xml.parsers
The org.w3c.dom Package The org.w3c.dom package contains the interfaces that define the DOM APIs. These interfaces represent the different node types supported by DOM specifications. These interfaces provide a number of methods with which you can access and work with different node types. The package also contains one exception. The following list describes the interfaces contained in this package: • Attr—Represents an attribute of an Element object. This interface declares the methods with which you can get various information about an attribute and set its value. It is important to remember that while in an XML document, an attribute can have tokenized types, and the DOM specification treats all attribute values as strings. • CDATASection—Represents the contents stored in the CDATA section of an XML document. The text contained in the CDATA section is available in the DOMString attribute of the Text node. This interface defines no methods. • CharacterData—Declares the methods for accessing character data in the DOM. Note that there is no DOM object represented by CharacterData. This is because the actual representation of the character data for an element or attribute is done by the Text interface. However, the Text interface inherits the CharacterData interface to use the methods to work with the character data. • Comment—Represents the contents of a comment in an XML document. • Document—Represents the complete XML document. You can think of this interface as the root of the document tree, and the primary access point for all data in the document. It declares a number of create methods with which an application can create the different types of DOM nodes. This interface also defines a number of get methods with which an application can access the different nodes in a DOM.
The DOM and the JAXP Packages
• DocumentFragment—Represents a lightweight document. This interface is useful when you want to move or rearrange parts of a document as a result of user commands such as cut. An interesting feature of DocumentFragment is that when a DocumentFragment is inserted into a Document or a Node, it is the children of the DocumentFragment that are inserted, and not the DocumentFragment itself. Therefore, by using a DocumentFragment that contains multiple nodes, an application can use a single insert call to insert all the nodes of the DocumentFragment under a specific Node. • DocumentType—Represents the doctype attribute of an XML document. This interface has methods with which you can access the public and system IDs of the DTD for the XML document, as well as the list of entities and notations defined for the document. • DOMImplementation—Defines methods with which you can create a document of a specified doctype, create a DocumentType node, and query whether a DOM implementation implements a particular feature. • Element—Declares methods with which you can access and modify the attributes of a specific element. This interface also declares methods with which the descendant elements can be accessed. • Entity—Represents both parsed and unparsed entities in an XML document. It is important to remember that in the non-validating mode, some XML processors might not process entity declarations made in the external subset or declared in external parameter entities. When an entity is processed, the Entity node’s child node will contain the replacement text. An Entity node and its child nodes are all read-only. • EntityReference—Represents an entity reference in an XML document. Note that character references and references to predefined entities are expanded by the processor while building the DOM. This implies that the characters are represented by their Unicode equivalent rather than by an entity reference. It is also possible that instead of providing the EntityReference objects, the XML processor might instead completely expand references to entities while building the DOM. • NamedNodeMap—Represents a collection of nodes that can be accessed by name or a number. However, it is important to remember that the objects in this collection are not stored in any particular order. • Node—Represents a single node in the document tree, and is the primary data type for the DOM. The Node interface provides methods with which an application can determine the node types and their values and attributes. This interface also provides the methods that enable the traversal across the DOM tree, and to add and remove nodes from the DOM. All interfaces, except for DOMImplementation, NamedNodeMap, and NodeList, inherit the Node interface.
121
122
CHAPTER 5
The Document Object Model
• NodeList—Provides the abstraction of an ordered collection of nodes. However, this interface does not define or constrain how this collection is implemented. This interface declares two methods with which the number of nodes in a node list can be determined, and a specific Node from the node list can be accessed. You will see later in the chapter that the Node and the NodeList interfaces are closely coupled. For example, the getChildNodes() method of the Node interface returns a NodeList containing all the children of the Node. The item(int index) method of the NodeList interface can then be used to access a specific Node. • Notation—Provides methods with which the public ID and the system ID of the notation can be accessed. The Notation node is a read-only node. A notation is a mechanism by which an unparsed entity is declared in an XML document. To find out more about notations and unparsed entities, see the section “Handling Unparsed Entities” in Chapter 4, “Advanced Use of SAX.” • ProcessingInstruction—Declares three methods with which the target of the processing instruction can be accessed, and by which the data for the processing instruction can be accessed or set. • Text—Represents the character data of an element or the value of an attribute. As mentioned earlier, this interface inherits from the CharacterData interface, along with the Node interface. The org.w3c.dom package contains the following exception: • DOMException—A DOMException is raised when it is impossible to perform an operation. This could be a result of logical reasons such as loss of data, or physical reasons, such as when the installation itself becomes unstable. For example, as per the DOM specification, a text node cannot have child nodes. If an application tries to insert a child node under the text node, a DOMException is thrown. This is a type of logical error.
The javax.xml.parsers Package The javax.xml.parsers package contains the classes that enable an application to process the XML documents using either SAX or DOM parsers. The classes contained in this package that support DOM are as follows: • DocumentBuilder—This class defines the API to get the DOM Document object from the XML document being parsed. A Document can be thought of as the root of a document tree, which provides access to the document’s data.
Creating a DOM Application
• DocumentBuilderFactory—This abstract class defines a factory API that enables applications to obtain a parser using the DocumentBuilder class. The parser can then produce DOM object trees from an XML document.
Creating a DOM Application In our context, a DOM application is a Java application that implements the javax.xml.parsers and org.w3c.dom packages to process an XML document by creating a DOM from it. You will create such an application and call it MyDOMHandler.java. The XML file you will use is the same CarParts.xml file that we used to explain the workings of a SAX parser.
The CarParts.xml File The CarParts.xml file is displayed in Listing 5.2. LISTING 5.2
The CarParts.xml File
]> &companyname; Engine 1 Engine 2 Car Body 1
123
124
CHAPTER 5
LISTING 5.2
The Document Object Model
Continued
Wheel Set 1 Car Stereo 1 >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> ➥>>>>>>>>>>>>SAMS Publishing is the &best& ➥ ➥ Heaven Car Parts (TM) Engine 1 Engine 2 ➥Engine 3 contd Car Body 1 Wheel Set 1 ➥>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>SAMS Publishing is the ➥ &best& . Text Nodes The character data is grouped into text nodes. The text nodes always contain the text in the normalized form. By design, as much of the character data as possible is put in a text node, with the minimum being one character. A text node cannot have a text node as a child node. Each character contained in the CDATA section is treated as a character data. For example, the ]]> entry will appear as > in the text node. Therefore, when writing out XML from text nodes, it is important to remember to escape such characters, by either using entity references or CDATA sections. The string-value of the text node is the character data.
XPath Expressions XPath expressions are evaluated to return one of the four data types discussed earlier. The expression itself can be a location path, which selects a set of nodes relative to the context node. An expression can also contain functions and wildcards that can be used to filter the set of nodes. Using Location Paths XPath models the XML as a tree of nodes. This hierarchical structure is analogous to the hierarchical directory structure that exists on your machines. The addressing mechanism of the XML tree is similar to that of the notation used for accessing a
XPath
hierarchical directory structure. And, as when you’re specifying a path to a directory, both absolute and relative location paths can be used. Like directory addressing, the following notations hold true: • The forward slash (/) is used as the path separator. • The absolute path from the root of the document starts with /. • .. represents the parent of the current node. • . represents the current node. For example, /carparts/supplier will be the path address to the supplier element under the carparts element. It is important to remember that while XPath provides the addressing mechanism, it is the XSLT specification that uses XPath addressing to match a pattern and select all occurrences for template implementation. For example, while XPath simply specifies the path to the supplier element, XSLT specification will ensure that all supplier elements under the carparts element are selected and returned as a node-set. Here are some examples of location paths: • /carparts matches all top-level carparts entries. • supplier matches the supplier element under the current context node. • //supplier matches all supplier elements in a document, regardless of their location. • /carparts/carbody//supplier matches all supplier elements under the /carparts/carbody context. An important point to remember is that the names in the XPath specification refer to elements. To access the attributes, you need to use an @ prefix. For example, to select the manufacturer attribute of the carstereo element, you will use //carstereo/@manufacturer. Filtering XPath Expression Selections The XPath specification provides functions, wildcards, operators, and index addressing mechanisms with which you can filter the pattern-matching expressions. Here are some examples: • * selects all child elements of the context node. • @* selects all the attributes of the context node. • supplier[1] selects the first supplier child element node under the current context node.
177
178
CHAPTER 6
XSLT and XPath
• //engines/engine[last()] selects the last engine child element node of the engines element node. • */engines selects all the engines grandchildren nodes of the current context node. • /carparts/supplier[3]/suppliername[1] selects the first suppliername child element node of the third supplier element node under the carparts node. • engine[@type=”Alpha37”] selects all engine child nodes of the current context node that have the attribute type with value Alpha37. • engine[@type=”Alpha37”][5] selects the fifth engine child node of the current context node that has the attribute type with value Alpha37. • engine[5] [@type=”Alpha37”] selects the fifth engine child node of the current context node if that child has a type attribute with value Alpha37. • engines[enginename] selects the engines child element node of the current context node that has one or more enginename child element nodes. • engines[enginename = “Engine 1”] selects the engines child element node of the current context node that has one or more enginename child element nodes with string-value equal to Engine 1. • engine[@id and @type] selects all engine child element nodes of the current context node that have both id and type attributes.
XPath Operators The XPath specification provides a number of operators with which you can create or modify expressions. These operators are listed in Table 6.1 in their order of precedence. TABLE 6.1
XPath Operators
Operators
Operator Function
|
This operator is used to match multiple elements. For example, carengine|supplier selects all carengine and supplier elements. These operators return the or/and of two Boolean values. These operators return the equal or not equal for Booleans, strings, and numbers. These operators return the less than, greater than, less than or equal to, and greater than or equal to for numbers. These are mathematical operators and return the result of the operation on two numbers.
or, and =, != , = + ,- ,* , div, mod
XPath
The operators are all left-associative. For example, 5>4>3 is the same as (5>4)>3, evaluating to false. Also, the expressions can be grouped in parentheses. Note that this operation is not supported in Java. In Java, you cannot use a Boolean result with a relational operator. For example, trying to evaluate (5>4)> 3 will throw an error in a Java program. However, XPath behaves more like C in this case.
XPath Functions XPath provides a number of functions. These functions can be used to select a collection of nodes, a string, a number, or a Boolean value. The functions are a convenient way of selecting data types. For example, carengine/text() will select the string-value of the carengine nodes. The XPath specification divides the functions into four categories: • Node-set functions • String functions • Boolean functions • Number functions
Node-Set Functions The node-set functions select and return a node-set, a number, or a string. The functions are listed in Table 6.2. TABLE 6.2
Node-Set Functions
Node-Set Function
Description
last()
This function returns the index of the last element. For example, /carengine[last()] selects the last carengine element. This function returns the index position. For example, /carengine[position() = 2] will select the second carengine element of the context node. The context node is the point of reference node from where the XSLT parser counts or looks for the elements. This function returns the count of elements. For example, /carengine[count[supplier]] returns the number of supplier element nodes under the carengine node. This function returns the node with the specified ID. For example, id(“E129”) selects the node with the unique ID E129. This function returns the local part of the expanded name of the node specified in the argument. This function returns the namespace URI of the expanded name of the node specified in the argument. This function returns the QName of the node specified in the argument.
Position()
count(node-set)
id(object)
local-name(node-set)
namespace-uri(node-set)
name(node-set)
179
180
CHAPTER 6
XSLT and XPath
String Functions The functions in Table 6.3 work on strings. TABLE 6.3
String Functions
String Function
Description
string(object)
This function converts an object to a string. The string returned will be as follows: • A string-value is returned for a node-set. • If the object is a special Not a Number numeric value, NaN is returned. • String “0” is returned for 0. • String “Infinity” is returned for positive infinity. • String “-Infinity” is returned for negative infinity. • Integer values are returned as their number equivalents, but in a string form. For example, -01 will be returned as “-1”. • Decimal values are returned as their number equivalents in string form. For example, –02.02 will be returned as “-2.02”. • “false” is returned for Boolean value false. • “true” is returned for Boolean value true. This function returns the concatenation of its arguments. This function returns true if the first string starts with the second string. Otherwise, the function returns false. This function returns true if the second string is contained in the first string. Otherwise, the function returns false. This function returns the start of first string before the second string occurs in it. For example, substringbefore(“I am the best”, “the”) returns “I am “. This function returns the remainder of the first string after the second string occurs in it. For example, substringafter(“I am the best”, “the”) returns “ best”. This function returns the substring from the numbered position to the end number. The number of the first character of the string is 1. For example, substring(“abcdef”, 2, 4) will return “bcd”. This function returns the number of characters in the string. If there are no arguments specified, the size of the context node’s string value is returned.
concat(string, string,…) starts-with(string, string)
contains(string, string)
substring-before(string,string)
substring-after(string,string)
substring(string, number, number)
string-length(string)
XPath
TABLE 6.3
Continued
String Function
Description
Normalize-space(string)
This function returns the normalized string-value of the specified string. This implies that leading and the trailing whitespaces are trimmed, and a sequence of whitespace characters is replaced by a single whitespace. If no string is provided, then the string-value of the context node is normalized. This function converts the first string, replacing the occurrences of the characters in the second string with the corresponding characters from the third string. For example, translate(“bar”,”abc”,”ABC”) returns the string BAr.
Translate(string,string,string)
Boolean Functions The functions in Table 6.4 operate on Boolean values. TABLE 6.4
Boolean Functions
Boolean Function
Description
boolean(object)
This function converts its arguments to Booleans according to the following rules: • A number is true if it is a non-zero number. • A node set is true if it is non-empty. • A string is true if it is non-empty. This function returns true if its argument is false. Otherwise, it returns true. This function returns true. This function returns false. This function returns true if the language of the context node is the same as (or a sublanguage of) the specified language. The language of the context node is specified by the xml:Lang
not(Boolean)
true() false() lang(string)
attribute. For example, lang(“en”) is true for .
Numeric Functions The functions in Table 6.5 work on numbers.
181
182
CHAPTER 6
XSLT and XPath
TABLE 6.5
Numeric Functions
Numeric Function
Description
Number(object)
This function converts the object to a number by the following rules: • A string that consists of optional whitespace, followed by an optional minus sign, followed by a number, followed by whitespace, is converted to the IEEE 754 number that is nearest (according to the IEEE 754 round-to-nearest rule) to the mathematical value represented by the string; any other string is converted to NaN. • True is converted to 1. • False is converted to 0. • A node-set is converted to a string, and then converted to a number by the IEEE 754 round-to-nearest rule. The conversion of a node-set to a string is done by applying the same rules as followed by the string() function when converting a node-set to a string. This function returns the sum of the numeric value of each node of the given node-set. The numeric value of each node is arrived at by the same rules as discussed in the previous item. This function returns the largest integer that is not greater than the specified number. This function returns the smallest integer that is greater than the specified number. This function returns the integer closest to the specified number.
Sum(node-set)
Floor(number)
Ceiling(number)
Round(number)
Transforming XML So far in this chapter you have learned about the XSLT and XPath basics, and how to use the transformation classes with DOM and SAX. This section will teach you how to create an XSLT stylesheet and use the transformation classes to transform an XML document into another with a very different structure and tag names. As before, the CarParts.xml file will be used as the source XML document. You will need to write an XSLT stylesheet that will contain the transformation information. You will also need to write a small Java application that will use CarParts.xml and the XSLT stylesheet to do the transformation and show the transformed XML on the screen. First, let’s look at what the transformed CarParts.xml should look like. The transformed XML should appear as follows:
Transforming XML
--> Heaven Car Parts (TM) Engine 1 Car Body 1 Wheel Set 1 Car Stereo 1 >>>>>>>>>>>>>>>>>>>>>>>>>>>> ➥>>>>>>>>>>>>>>>>>>>SAMS Publishing is the &best& ➥ command will be used. To use them, add the following lines:
Transforming XML
This XML is checking out the format with our suppliers>
A stylesheet contains a number of templates that are defined using the tag. Each template has a match attribute that selects the elements to which the template will be applied. The selection of elements is done as per the XPath addressing mechanism that was described earlier in the chapter. In this case, the processing-instruction() function ensures that the processing instruction is chosen. The command copies the matched elements to the transformed XML. The command is used to specify the comment in the transformed XML. Next you need to transform the carparts, supplier, and engines elements to carcomponents, componentsupplier, and car_engines, respectively. To do that, add the following lines of code: xsl:template match=”carparts”>
Now the engine element needs to be copied over with only the id attribute. To copy the element, you will use the command. To copy the id attribute, you will create a new template, and then call that template from within the template that matches the engine element. To do so, add the following lines:
185
186
CHAPTER 6
XSLT and XPath
Next you will add the stylesheet information for transforming the carbodies, carbody, wheels, wheel, carstereos, and carstereo elements. To do so, add these lines:
Creating the MyXSLTTransformer Application
Finally you will add stylesheet information to transform the forCDATA element to for_CDATA, and add an attribute called Type. To add the attribute, you will use the command. Add the following lines to transform the forCDATA element and add the attribute: FreeText
You’ve now successfully created the XSLT stylesheet. Next, you need to write the Java application that will use the stylesheet to transform the CarParts.xml file.
Creating the MyXSLTTransformer Application MyXSLTTransformer is a simple Java application that uses a DOM parser to create a Document object from the CarParts.xml file. This Document object is converted to a DOMSource object and used by the Transformer object as the source. Because the output is to be displayed on the screen, System.out is used as the output of the transformation. The Transformer object itself is created by using the CarParts.xsl
stylesheet. First you need to import the necessary packages and classes. To do so, add the following lines of code: import import import import
javax.xml.parsers.DocumentBuilder; javax.xml.parsers.DocumentBuilderFactory; javax.xml.parsers.FactoryConfigurationError; javax.xml.parsers.ParserConfigurationException;
187
188
CHAPTER 6
import import import import import import import import import import import import
XSLT and XPath
org.xml.sax.SAXException; org.xml.sax.SAXParseException; org.w3c.dom.Document; org.w3c.dom.DOMException; javax.xml.transform.Transformer; javax.xml.transform.TransformerException; javax.xml.transform.TransformerFactory; javax.xml.transform.TransformerConfigurationException; javax.xml.transform.dom.DOMSource; javax.xml.transform.stream.StreamSource; javax.xml.transform.stream.StreamResult; java.io.*;
Next, provide the class declaration and the main() method. To do so, add these lines of code: public class MyXSLTTransformer { static Document document; public static void main (String argv []) {
Now the CarParts.xml file needs to be parsed to create a Document object. To do so, add the lines of code shown in bold: public static void main (String argv []) {
DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();
try { File stylesheet = new File(“CarParts.xsl”); File datafile = new File(“CarParts.xml”); DocumentBuilder builder = factory.newDocumentBuilder(); document = builder.parse(datafile);
Now you need to create the Transformer object. To do so, add the lines of code shown in bold:
Creating the MyXSLTTransformer Application
document = builder.parse(datafile); // Use a Transformer for output TransformerFactory tFactory = TransformerFactory.newInstance(); StreamSource stylesource = new StreamSource(stylesheet); Transformer transformer = tFactory.newTransformer(stylesource);
The next step is to create the DOMSource and the StreamResult objects. To do so, add the lines of code shown in bold: Transformer transformer = tFactory.newTransformer(stylesource); DOMSource source = new DOMSource(document); StreamResult result = new StreamResult(System.out); transformer.transform(source, result);
Finally, you will insert the try-catch block to handle the exceptions that may occur—add the lines of code shown in bold in Listing 6.4. LISTING 6.4
Adding Exception-Handling Code
try { File stylesheet = new File(“CarParts.xsl”); File datafile = new File(“CarParts.xml”); DocumentBuilder builder = factory.newDocumentBuilder(); document = builder.parse(datafile); // Use a Transformer for output TransformerFactory tFactory = TransformerFactory.newInstance(); StreamSource stylesource = new StreamSource(stylesheet); Transformer transformer = tFactory.newTransformer(stylesource); DOMSource source = new DOMSource(document); StreamResult result = new StreamResult(System.out); transformer.transform(source, result); } catch (SAXParseException saxException) { /* If there are errors in XML data ➥ are trapped and location is displayed*/ System.out.println(“\n\nError in CarParts.xml at ➥ line:”+saxException.getLineNumber()+”(“
189
190
CHAPTER 6
XSLT and XPath
LISTING 6.4
Continued
➥+saxException.getColumnNumber()+”)\n”); System.out.println(saxException.toString()); } catch (SAXException saxEx) { /* If there are errors in XML data, the detailed ➥message of the exception is displayed*/ System.out.println(saxEx.getMessage()); } catch (ParserConfigurationException pce) { // Parser with specified options can’t be built pce.printStackTrace(); } catch (IOException ioe) { // I/O error ioe.printStackTrace(); } catch (TransformerConfigurationException tcex) { System.out.println(tcex.getMessageAndLocation()); } catch (TransformerException te) { System.out.println(te.getMessageAndLocation()); }
} // main }
The application is now ready to transform CarParts.xml. NOTE The code discussed here is available in the example0603 folder. This folder also contains the sample CarParts.xml file.
Compile and run the application. The output should be similar to Listing 6.5.
Summary
LISTING 6.5
Output of MyXSLTTransformer Application
--> Heaven Car Parts (TM) Engine 1 Car Body 1 Wheel Set 1 Car Stereo 1 >>>>>>>>>>>>>>> ➥>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>SAMS Publishing is the &best& ➥ oracle
To create a standalone client, you need to do the following: 1. Import the necessary packages and classes. 2. Get an instance of the SOAPConnectionFactory class. This is a factory class that
enables an application to create a connection to the Web service. 3. Get the SOAPConnection object. A SOAPConnection object represents a point-to-
point connection. A standalone client can use only a point-to-point connection and engage in a request-response messaging. You will use the SOAPConnectionFactory’s createConnection() method to get the SOAPConnection object. 4. Create the SOAP message using the combination of MessageFactory and SOAPMessage classes. 5. Access the empty SOAP message and add the necessary elements. 6. Create a URLEndpoint object to connect to the UDDI registry. 7. Use the SOAPConnection object to send the SOAP message to the registry. 8. Display the SOAP message that is sent and the reply that is received in
response to the query to the registry.
Importing the Packages and Classes Like all Java programs, the MyJAXMClient application will also begin with importing the required packages and classes. To do so, open a text editor of your choice and enter the following lines of code: import javax.xml.soap.*; import javax.xml.messaging.URLEndpoint; import java.io.*;
Standalone Client Implementation
public class MyJAXMClient{ public static void main(String[] args) { try {
The javax.xml.soap package contains the necessary classes and interfaces that enable an application to create a SOAP message. The javax.xml.messaging.URLEndpoint class provides the URL required by the application to provide a direct connection to the Web service. As said before, JAXM clients that do not use a messaging provider can only do a point-to-point connection with a Web service. The classes of java.io package enable the application to do I/O operations. Other than importing the required classes and packages, the class declaration for the program is also provided. Next, you need the JAXM client application to get a connection.
Getting a Connection A JAXM client can get a connection by creating either a SOAPConnection or a ProviderConnection object. However, the clients that do not use a messaging provider can only use the SOAPConnection object. To get a SOAPConnection object, enter the following lines of code shown in bold: public static void main(String[] args) { try { // Create the connection and the message factory. SOAPConnectionFactory scf = SOAPConnectionFactory.newInstance(); SOAPConnection connection = scf.createConnection(); } catch (Exception ex) { ex.printStackTrace(); } } }
The SOAPConnectionFactory is a factory class that enables the creation of a SOAPConnection object. Using a factory class to create a class instance provides the necessary loose coupling between the application and the selection of a particular class to instantiate at runtime. This allows you to write code once and then use a vendor-specific class at runtime. To get an instance of the SOAPConnectionFactory, use the newInstance() method. This method returns a SOAPConnectionFactory instance. Once you have the instance, call the createConnection() method of the SOAPConnectionFactory instance. Next, you will learn how to create the SOAP message.
211
212
CHAPTER 8
Creating Client Implementations
Creating the SOAP Message A SOAP message is created using the MessageFactory class. To do so, add the lines of code shown in bold in the following: SOAPConnection connection = scf.createConnection(); // Create a message MessageFactory msgFactory = MessageFactory.newInstance(); SOAPMessage msg = msgFactory.createMessage();
You use the createMessage() method of the MessageFactory class to create a SOAPMessage object. A SOAPMessage object has the following parts: • A SOAPPart—The object that represents the SOAP-specific portion of a SOAP message. • A SOAPEnvelope—The object that represents the envelope element of the SOAP messages. • A SOAPHeader—The object that represents the Header element of a SOAP message. By default this object is empty when a SOAPMessage is created from MessageFactory. • A SOAPBody—The object that represents the body element of a SOAP message. Similar to the SOAPHeader object, this object is created empty. After the SOAPMessage object has been created, the next step is to populate the object.
Populating the SOAP Message Populating the SOAP message implies adding necessary content to the Header and Body elements. To populate the empty SOAPMessage object, you need to do the following: 1. Get the SOAPEnvelope object. 2. From the SOAPEnvelope object, get the SOAPBody object. 3. In the SOAPBody object, add the SOAPBody elements and attributes, if any. 4. Under the SOAPBody element, add the child elements.
Standalone Client Implementation
To do the previously mentioned tasks, enter the lines of code shown in bold in the following: SOAPMessage msg = msgFactory.createMessage(); // Get the SOAP envelope in the message SOAPEnvelope envelope = msg.getSOAPPart().getEnvelope(); // Get the soap body SOAPBody body = envelope.getBody(); //Add Body element Name bodyName = envelope.createName ➥(“find_business”, “”,”urn:uddi-org:api”); Name genericAttribute = envelope.createName(“generic”); Name maxRowsAttribute = envelope.createName(“maxRows”); SOAPBodyElement bodyElement = body.addBodyElement(bodyName); // Add attributes bodyElement.addAttribute(genericAttribute, “1.0”); bodyElement.addAttribute(maxRowsAttribute, “100”);
//Adding Child Elements and its text node Name companyName = envelope.createName(“name”); bodyElement.addChildElement(companyName).addTextNode(args[1]); msg.saveChanges(); System.out.println(“The Outgoing SOAP Message :\n”); msg.writeTo(System.out);
First, the getEnvelope() method is used to get the SOAPEnvelope object from the SOAPPart object. Next, you create the Name objects for the body element and its attributes. Note that in our example, we are actually executing an rpc call on the UDDI registry, by executing the find_business method of the UDDI specification. This method takes the maxRows and generic as its two parameters. The value of the maxRows parameter limits the number of results returned. The generic parameter defines the version of the UDDI specification. Therefore, you created the Name objects with find_business, generic, and maxRows as parameters.
213
214
CHAPTER 8
Creating Client Implementations
NOTE To learn more about the Publish and the Inquiry APIs, see http://www.uddi.org/pubs/ ProgrammersAPI-V2.00-Open-20010608.pdf.
Next, you add the name child element. This element is another parameter of the find_business method. The value of this parameter of the find_business method is the name of the business that you want the information for. For example, if you want information about Microsoft, the value of the name element will be Microsoft. The find_business method returns the businessList structure for the company that the query was run for. The value of the name element will be picked up at runtime as a command-line argument. After populating the SOAP message, you called the saveChanges() method to save the SOAP message, and used the writeTo() method of the SOAPMessage object to write out the SOAP message on the screen. Next, you need to create the URLEndpoint object for the URL that points to the UDDI registry, which is implemented as a Web service.
Creating the URLEndpoint Object The registry that will be used is a test registry located at http://www3.ibm.com/services/uddi/testregistry/inquiryapi. To create a URLEndpoint object from this URL, enter the following line of code shown in bold: msg.writeTo(System.out); URLEndpoint endpoint = new URLEndpoint ➥(“http://www-3.ibm.com/services/uddi/testregistry/inquiryapi”);
Next, the SOAP message needs to be sent.
Sending the Message and Getting the Response The SOAP message is sent to the specified Web service by using the call() method of the SOAPConnection object. Because a standalone client can only do requestresponse type messaging, the call() method returns a SOAPMessage object that contains the response to the query. The application is blocked until the call method returns a SOAPMessage object. After the SOAPMessage object is obtained, it is a good idea to close the connection, because connections tend to be resource-intensive. Add the lines of code shown in bold to send the message, get the reply, print the received reply, and then close the connection:
Standalone Client Implementation
URLEndpoint endpoint = new URLEndpoint ➥(“http://www-3.ibm.com/services/uddi/testregistry/inquiryapi”); SOAPMessage reply = connection.call(msg, endpoint); System.out.println(“\n Received reply from: “+endpoint); reply.writeTo(System.out); connection.close(); } catch (Exception ex) { ex.printStackTrace(); } } }
You have now successfully created a standalone JAXM client to connect to a registry, send the registry a find_business query, and display the information the registry returns about an organization. NOTE The code discussed so far is available in the example1001 folder.
To compile and run the application to get information about companies that have oracle in their name, use the following command: java MyJAXMClient oracle
The output is displayed in Listing 8.1. LISTING 8.1
Output of MyJAXMClient Application
The Outgoing SOAP Message : oracle
215
216
CHAPTER 8
LISTING 8.1
Creating Client Implementations
Continued
Received reply from: http://www-3.ibm.com/services/uddi/testregistry/inquiryapi Oracle oracle powers the internet Oracle Corporation Oracle Corporation provides the software and services for e-business. Oracle.com Oracle Store Oracle Technology Network E-Business Network
Client with Messaging Provider
Notice that the result is a SOAP message that contains the businessList structure for two companies that have oracle in their name. You learned to create a standalone JAXM client that does JAXM messaging without a messaging provider. Next, you will learn to create a JAXM application that uses a messaging provider.
Client with Messaging Provider A messaging provider and a client that uses a messaging provider are required to run in a container such as the reference J2EE container provided with Apache-Tomcat. In this section, you will create a JAXM client that will demonstrate the features that you can use when a messaging provider is used. The JAXM client will be a servlet, which will process the data sent to it from a Web form. The servlet will use the default messaging provider available through the JAXM reference implementation, and use the messaging provider’s support for ebXML to create an ebXML message from the submitted data. The ebXML message will then be sent as a one-way message. The steps involved in implementing the client with a messaging provider are as follows: 1. Create the Web form. 2. Create the servlet, MyJAXMClientWithProvider, that will process the data posted
from the Web form. 3. Create the web.xml file for installing the servlet in the Tomcat Web server. 4. Create the sampledoc.txt that will be used as an attachment. 5. Install the servlet and the Web form in the Tomcat server.
Let us begin by creating the most critical piece of them all, the MyJAXMClientWithProvider servlet.
Creating the Servlet As mentioned before, the MyJAXMClientWithProvider servlet is the JAXM client that will use the data it receives from a Web form to create an ebXML message, and send it to the default messaging provider as a one-way message. The sequence of steps to create the servlet is as follows: 1. Import the packages and classes. 2. Get the connection at the time of servlet initialization.
217
218
CHAPTER 8
Creating Client Implementations
3. In the doPost() method, get the ebXML profile and create an empty ebXML
SOAP message. 4. Populate the ebXML message with the data received from the Web form. 5. Create an attachment to the ebXML message. 6. Send the message and create a logfile that saves the ebXML message that was
sent.
Importing the Packages and Classes Open a text editor and create a file called MyJAXMClientWithProvider.java and enter the following lines of code: import import import import import import import import
java.net.*; java.io.*; javax.servlet.http.*; javax.servlet.*; javax.xml.messaging.*; javax.xml.soap.*; javax.activation.*; com.sun.xml.messaging.ebxml.*;
public class MyJAXMClientWithProvider extends HttpServlet { }
The java.net classes are used to create the URL object for the file that will be attached to the SOAP message. The java.io classes will be used for the I/O operations of the servlet. The javax.servlet classes are required for accessing the servletrelated functionality. The javax.xml.messaging classes are required for the provider connection. The javax.xml.soap classes are required to access the message factory class. The javax.activation classes are required for creating the attachment to the SOAP message. You also created the class declaration for the MyJAXMClientWithProvider servlet. Next, you need to create the connection at servlet initialization. Getting the Connection To get the connection, enter the following lines of code: public class MyJAXMClientWithProvider extends HttpServlet {
private ProviderConnectionFactory pcf; private ProviderConnection pc;
Client with Messaging Provider
private MessageFactory mf = null;
public void init(ServletConfig servletConfig) throws ServletException { super.init( servletConfig ); try { pcf = ProviderConnectionFactory.newInstance(); pc = pcf.createConnection(); } catch(Exception e) { System.out.println(“”+e.getMessage()); } }
First, you created references to the instances of the ProviderConnectionFactory, ProviderConnection, and MessageFactory classes. These classes will be required to create a connection with the messaging provider and then create a SOAP message. Next, in the init() method of the servlet, the createConnection() method is called to provide the connection to the messaging provider. The init() method is called in the life cycle of the servlet. Next, the ebXML profile will be received from the messaging provider and an empty ebXML message will be created. Creating an ebXML Message A messaging provider can support a number of profiles. To find the profiles supported by a messaging provider, you need to get a ProviderMetadata object of the messaging provider. This object encapsulates various information about the messaging provider. You use the getSupportedProfiles() method of the ProviderMetadata object to find support for a particular profile, such as the ebXML profile, and then use the name of the profile to create a message factory for creating ebXML messages. The messaging provider that comes with JAXM reference implementation supports ebXML and SOAP-RP profiles. To get the ebXML profile and create an empty ebXML message, enter the lines of code shown in bold: public void doPost(HttpServletRequest req, HttpServletResponse resp) throws ServletException {
219
220
CHAPTER 8
Creating Client Implementations
try { // Create a message factory. if (mf == null) { ProviderMetaData metaData = pc.getMetaData(); String[] supportedProfiles = metaData.getSupportedProfiles(); String profile = null; for(int i=0; i < supportedProfiles.length; i++) { if(supportedProfiles[i].equals(“ebxml”)) { profile = supportedProfiles[i]; break; } } mf = pc.createMessageFactory(profile); }
// Create a message from the message factory. EbXMLMessageImpl ebxmlMsg = (EbXMLMessageImpl)mf.createMessage();
First, the getMetaData() method of the ProviderConnection instance is used to get the ProviderMetadata object. Then, the getSupportedProfiles() method for the ProviderMetaData object is used to access the array of profiles supported by the messaging provider. This array is searched for ebxml, and if found, the createMessageFactory() method is called with the ebxml string as its parameter. This creates a MessageFactory object that will produce SOAPMessage objects for the given profile. Finally, the createMessage() method is called to create a SOAPMessage object that conforms to the ebXML profile. Note that the SOAPMessage object is typecasted to the EbXMLMessageImpl class to support ebXML messages. This class is part of the JAXM reference implementation. The ebXML message that is returned by the createMessage() object is empty and needs to be populated to get any real work done. NOTE Note that in our sample code, the messaging provider is expected to provide support for ebXML. However, this might not be the case for all messaging providers. Therefore, it’s good programming practice to provide code that can handle the situation in which the messaging provider does not provide support for a specific profile.
The next step is to populate the empty ebXML message.
Client with Messaging Provider
Populating the ebXML Message In an ebXML message, you first need to provide the sender and the receiver information. This is done by using the Party objects. The information is stored in the Header of the message and determines the message delivery sequence. Additionally, in an ebXML message, you need to specify the service, reference to message ID, CPA ID, conversation ID, action, manifest, reference, schema, and description information. For example, you will use the receiver address provided with the default implementation. The service, reference to message ID, CPA ID, conversation ID, action, and description information will be taken from the Web form. To populate the ebXML message, add the lines of code shown in bold: EbXMLMessageImpl ebxmlMsg = (EbXMLMessageImpl)mf.createMessage();
ebxmlMsg.setSender(new Party(“http://localhost:8080/chap10”)); ebxmlMsg.setReceiver(new Party(“http://www.wombats.com/remote/ ➥sender”)); String srvc = req.getParameter(“Service”); Service service = new Service(srvc); String ref2msgId = req.getParameter(“ref2msgid”); ebxmlMsg.setRefToMessageId(ref2msgId); String cpaid = req.getParameter(“cpaid”); ebxmlMsg.setCPAId(cpaid); String conversationId = req.getParameter(“conversationId”); ebxmlMsg.setConversationId(conversationId); ebxmlMsg.setService(service); String action = req.getParameter(“Actn”); ebxmlMsg.setAction(action); Manifest manifest = new Manifest(“manifest”, “1.0”); Reference ref = new Reference(“pay01”, “cid:pay01”, “http://somecompany.org/purchaseordermodel”); Schema schema = new Schema( “http://somecompany.org/purchaseordermodel. ➥xsd”, “1.0”); ref.setSchema(schema); Description desc = new Description(“en-us”); String descptn = req.getParameter(“Descptn”);
221
222
CHAPTER 8
Creating Client Implementations
desc.setText(descptn); ref.setDescription(desc); manifest.addReference(ref); ebxmlMsg.setManifest(manifest);
Note that the constructor to the Party object in the setReceiver() method takes the http://www.wombats.com/remote/sender URI as its parameter. This is the default URI provided with the JWSDP download for sending ebXML messages using a message provider. This URI actually resolves to the following URL: http://127.0.0.1:8081/jaxm-provider/receiver/ebxml. NOTE You can also create your own endpoint mappings for ebXML providers. To do so, you need to use the JAXM Provider Administration Tool provided with the JWSDP download. You can access it by going to the http://localhost:8080/index.html and then clicking on the JAXM Provider Administration Tool link.
Next, using the getParameter() method, you processed the service, references to message ID, CPA ID, conversation ID, action, and description information received from the Web form. You also added the manifest, reference, and schema information to the ebXML message. NOTE The values set in examples are shown for demonstration purposes only and are not necessarily correct or available.
Next, you will add an attachment to the ebXML message. Creating Attachments The SOAP with Attachments specification makes it possible to add attachments to SOAP messages. This is especially useful when you want to add non-XML documents, such as images and so on, to a SOAP message. By default, the SOAPPart object in the SOAPMessage object can store only XML content. To store attachments, you need to create AttachmentPart objects from the SOAPMessage object, add content to the AttachmentPart objects, and then add them to the SOAPMessage object. The SOAPMessage object provides a createAttachment() method with which the AttachmentPart object can be created. After the AttachmentPart object is created, you need to populate it with header information and other content.
Client with Messaging Provider
An AttachmentPart object has multiple headers, so setting the Content-Type header is mandatory. The other headers, such as Content-Id, Content-Location, and so on, are optional. The content in an AttachmentPart object can be set by one of the two styles, either using the setContentMethod() of the attachment object or using the JavaBeans Activation Framework (JAF) DataHandler object. In the MyJAXMClientWithProvider servlet, the DataHandler object is used to create an attachment. You will add http://localhost:8080/chap10/sampledoc.txt as the attachment object to the ebXML message. To add the attachment to the ebXML message, enter the lines of code shown in bold: ebxmlMsg.setManifest(manifest); URL url = new URL(“http://localhost:8080/chap10/sampledoc.txt”); AttachmentPart ap = ebxmlMsg.createAttachmentPart(new DataHandler(url)); ap.setContentType(“text/plain”); // Add the attachment part to the message. ebxmlMsg.addAttachmentPart(ap);
In this code, you created a URL object of the http://localhost:8080/chap10/sampledoc.txt resource that is to be added as an attachment. Next, you used the createAttachment() method with the DataHandler
object representing the URL as its parameter. This created the attachment part and set the content to the URL in one shot. Next, you set the content type to text/plain because the sampledoc.txt contains a string. Finally, you added the attachment part object to the ebXML message. The next and final step is to send the message and create the logfile to save the ebXML message that was sent. You also need to ensure that the user is notified that the message has been sent. Sending the Message To send the message, you need to use the send() method of the ProviderConnection object. This method sends the message and returns immediately. The send() method needs only the ebXML message as its parameter because the destination address is already stored in the header of the message.
223
224
CHAPTER 8
Creating Client Implementations
To send the message, create the logfile to save the ebXML message that was sent, and notify the user that the message has been sent, enter the lines of code shown in bold in the following: ebxmlMsg.addAttachmentPart(ap); //Send the message pc.send(ebxmlMsg); //Log the message FileOutputStream sentFile = ➥new FileOutputStream(“outputofMyJAXMClientWithProvider.log”); ebxmlMsg.writeTo(sentFile); sentFile.close(); //Inform the user String startHTML = “ Message delivered to provider. You can see ➥ the message that has been sent at ➥ /outputofMyJAXMClientWithProvider.log file”; OutputStream os = resp.getOutputStream(); os.write(startHTML.getBytes()); os.flush(); os.close(); } catch(Throwable e) { e.printStackTrace(); } } }
You successfully wrote the servlet to process data from a Web form, created an ebXML message from it, and used a messaging provider to send a one-way message. Compile the servlet and keep it ready for deployment. Next, you will create the Web form that will post the necessary information to the servlet.
Creating the Web Form For the sake of simplicity, create a simple Web form and name it index.html. The form should appear as shown in Figure 8.1.
Client with Messaging Provider
FIGURE 8.1
The index.html Web form.
The source for the index.html file is shown in Listing 8.2. LISTING 8.2
Source for index.html
<STRONG>Example of JAXM Client With Messaging Provider
| <STRONG>Service | |
225
226
CHAPTER 8
LISTING 8.2
Creating Client Implementations
Continued
| <STRONG>Conversation ID | |
| <STRONG>CPA ID | |
| <STRONG>Reference to Message ID | |
| <STRONG>Action | |
| <STRONG>Description | |
| |
➥
Note that the value of the action field is senderwithprovider. This is the name by which the MyJAXMClientWithProvider servlet is mapped. This mapping is done through the web.xml file, which you will be creating next.
Creating the web.xml File The web.xml file is the configuration file for a Web application. It defines things such as the servlet name and its mapping to the actual class, session configuration, supported MIME types, and so on. For the sake of simplicity, the web.xml file for our example will only contain the servlet mappings. The web.xml file is displayed in Listing 8.3. LISTING 8.3
The web.xml File
MyJAXMClientWithProvider MyJAXMClientWithProvider 2
MyJAXMClientWithProvider /senderwithprovider
Creating the sampledoc.txt File The sampledoc.txt file contains the content that the ebXML message will add as an attachment. It is a simple text file that is displayed as follows: This is a sample text to show that any type of file can be attached to a soap ➥message.
227
228
CHAPTER 8
Creating Client Implementations
Now you are ready to deploy the servlet in the Tomcat container and see the JAXM client in operation.
Deploying the JAXM Client Let’s take a look at the components we have created so far to see the JAXM client in action: • The index.html Web form that posts data to the MyJAXMClientWithProvider servlet. • The MyJAXMClientWithProvider servlet that processes the data posted from index.html. • The web.xml configuration file. • The sampledoc.txt file that is to be used as an attachment.
NOTE The code discussed so far is available in the example1002 folder.
You will now deploy these files to get the application up and running. The following steps are what you need to do: 1. Shut down Tomcat if it is running. 2. Create a folder called chap10 under the webapps folder. 3. Copy the index.html and sampledoc.txt files under the chap10 folder. 4. Create a folder called WEB-INF under the chap10 folder. 5. Copy the web.xml file under the WEB-INF folder. 6. Create a folder called classes under the WEB-INF folder. 7. Copy the MyJAXMClientWithProvider.class file to the WEB-INF folder. 8. Copy the client.xml file from the example1002 location to the WEB-INF folder.
This XML file is required to resolve the endpoints to specific URLs. 9. Start up Tomcat.
You are now all set to launch the JAXM client. To do so, launch a Web browser and go to http://localhost:8080/chap10.
Client with Messaging Provider
This will display the index.html on the browser window. Enter the data in the fields and submit the form. The servlet will create the ebXML message from the submitted data and send the message. An example of the ebXML message that was sent is shown in Listing 8.4. LISTING 8.4
Output of MyJAXMClientWithProvider
------=_Part_2_5670484.1022764118409 Content-Type: text/xml SendMessage ebxml http://localhost:8080/chap10 http://www.wombats.com/remote/sender http://somecompany.com/ProcurementOrderPact.xml 20020530-001 ProcurementOrder New Procurement fdd4965a-5d67-4f52-9cce-9998d6efc237
[email protected] 1022764117738
229
230
CHAPTER 8
LISTING 8.4
Creating Client Implementations
Continued
Procurement for Car Parts ------=_Part_2_5670484.1022764118409 Content-Type: text/plain This is a sample text to show that any type ➥ of file can be attached to a soap message. ------=_Part_2_5670484.1022764118409--
Summary In this chapter, you learned to create the two types of JAXM clients: the standalone client that does not use a JAXM provider, and the JAXM client that uses a messaging provider. Depending on your business needs, you can now create JAXM applications and send and consume SOAP messages.
PART IV JAXR and JAX-RPC IN THIS PART 9 Registry Fundamentals 10 JAXR Implementations 11 Working with JAX-RPC
9 Registry Fundamentals
IN THIS CHAPTER • Existing Registries • Registry Uses • Registry Use Model
An important reason for the success of e-commerce has been the growth of B2B interactions between enterprises via the use of Web services. However, for B2B interactions to be successful, there has to be a mechanism by which a business can discover another business that is interested in doing business with it, and then they must agree on a process that they both understand. A registry provides the necessary mechanism by which enterprises can publish, discover, and use Web services, thereby enabling B2B interactions in a dynamic fashion. In this chapter, you will learn about the various roles that a registry performs, and the use model that businesses follow for using a registry. You will also learn about the JAXR architecture, and the JAXR packages that enable an application to dynamically connect to any registry and work with it.
Existing Registries There are a number of registries in existence that are promoted by either standards bodies or industry consortia. Some of the prominent registry specifications are UDDI and ebXML. The UDDI standard is promoted by a consortium of more than 200 companies, with players such as Microsoft and Oracle. Another prominent registry specification, ebXML, is a joint effort sponsored by the standards bodies OASIS and UN/CEFAT. Another project of interest is the eCo Framework. These registries, while providing similar services, are diverse in terms of capabilities and APIs. This leads to the issue that programs written for a specific registry cannot be directly used for another without significant code changes and recompilation. For example, an application written to
• The Registry Information Model • The JAXR Specification • The JAXR Architecture • The JAXR Packages
234
CHAPTER 9
Registry Fundamentals
interact with the UDDI registry cannot be directly used to work with the ebXML registry. You will have to edit code to change UDDI-specific code to ebXML-specific code and then recompile the program. This is obviously troublesome, and against the core write-once-run-everywhere spirit of Java. JAXR provides a solution to this problem. The JAXR specification provides a general purpose API set that enables an application to dynamically access any registry without needing to change code. Similar to JAXP, this capability is achieved by providing a pluggability layer.
Registry Uses A registry has a variety of uses: • As electronic white, yellow, and green pages—A registry provides a variety of information about an enterprise and the Web service that it makes available for B2B interactions. The information made available through a registry includes the name, business identifiers, contact information, industry codes, product classifications, and technical information about services. • As a database of static data—A registry contains data and metadata. This includes information about specific business process standards in XML format, such as the RosettaNet PIP34A standard for purchase orders, and the XML schemas that define the structure of the XML documents that are exchanged between two enterprises in a B2B interaction. • As a bulletin board—A registry can be used as a bulletin board. This implies that it can be used to publish and exchange dynamic information, such as event notifications, price updates, discount information, special offers, and so on.
Registry Use Model A registry has two types of users: sellers and buyers. A seller is an organization that creates a Web service and publishes it in the registry. A buyer is an organization that queries the registry to find and engage the seller in a business collaboration. Figure 9.1 shows how seller and buyer organizations use a registry to engage in B2B collaborations. First, a vertical standards organization such as RosettaNet defines a specification for a particular business process. These specifications include information such as the XML structure that is to be followed by the organizations that use the specification. This ensures that organizations involved in the business engagement have a common understanding of the documents that are exchanged in the B2B communication. These specifications are then submitted to the registry.
The Registry Information Model
1
Core components and process specs in XML
ebXML Registry
Request Business Details 2 Seller Company
4
3
Develop Web Services Register Web Services Details and Company Profile 5 Web Services
Query the Registry by Classification etc. 8 6
Agree on the Business Process to be Used
Download process specs and core 7 components Buyer Company
XML Docs
9
FIGURE 9.1
Registry use model.
A seller company queries the registry for a specification applicable to its business domain. Upon finding the necessary information, the seller company downloads it. The seller company also downloads the core components that define the XML elements used in business documents, such as address, contact, and so on. Using the downloaded specifications and the core components, the seller company then develops the necessary Web service(s). After the Web services have been developed at the seller’s site, the seller registers the information about itself and the services it provides into the registry. To ensure that buyers can easily discover the services and products offered by the seller, the seller organization can also choose to classify the products and services it offers under different classifications and concepts. Next, the buyer company connects to the registry and browses to find the required services. After it finds the required services, it downloads the specifications and core components, and similar to the seller company, builds an application that uses these standards and components. This is important, because the buyer and seller can only do business when they understand each other’s language, which is facilitated by following the same standards and core components. After the buyer company has created its local system, it negotiates with the seller company on the chosen collaborative process and begins exchanging the business documents in the form of XML documents.
The Registry Information Model Registries like UDDI and ebXML are essentially storehouses in which information about participant businesses is stored. And as with all information storage mechanisms,
235
236
CHAPTER 9
Registry Fundamentals
these registries have information models that model the types of information that can be created and stored. Although the registries store similar information for a business entity, the information models they follow are very different.
The UDDI Information Model The UDDI registry specification declares that all UDDI-compliant registries must support the information models described in the following sections. businessEntity
Information about a business is stored in the businessEntity element. The information set consists of different elements containing the unique identifier for the business, the name of the business, a description of the business, a list of categories and identifiers that describe the business, and a URL pointing to more information about the business. The businessEntity element contains the businessService, bindingTemplate, and tModel elements. Conceptually, you can think of businessEntity information as the yellow-page entry for the organization. This enables applications to search for businesses by industry, product, or geography. For example, the name element of the businessEntity structure will store the name of the business. Similarly, the description element will contain the description of the business. The businessEntity element contains within it the contact element, which in turn contains elements that describe the contact information of the business. For example, the personName element stores the name of a person who can be contacted, and the phone element stores the phone numbers for the business. Similarly, the email element is used to store the email address of the business. businessService
Analogous to information contained in the green pages, this data structure contains information about the business services offered by the business entity and the technical descriptions of the Web services. The businessService structure represents a logical service classification; that is, it represents the Web services that are related to a business process or service category. Similar to the businessEntity element, the businessService element also has name and description elements, in which you can define the name of the service and its description. It also contains the bindingTemplate entity, which is described in the following section. bindingTemplate The bindingTemplate entity’s data structure contains the technical Web service
descriptions. These are the actual pieces of information that an application uses to connect and execute a Web service. The information includes the URL, binding key, and tModelInstance details.
The Registry Information Model
tModel The bindingTemplate entity provides the technical information needed to execute a
Web service. However, simply knowing the URL is only one part of the process. The invoking application should also know other technical details, such as the format of the data supported by the Web service, protocols, security issues, the format of the response, and so on. Such technical specifications are represented by the tModels. The tModel element contains the pointer to technical specifications. Therefore, by referencing a specific tModel, a Web service guarantees that it is compatible with the technical specifications as laid out in the referenced tModel. publisherAssertion A single businessEntity is often not sufficient to represent all the business processes
performed by large organizations. Therefore, such businesses publish many businessEntity structures. However, because they are part of the same business or enterprise, they are related. The publisherAssertion entity provides the capability with which one business can make visible in a UDDI registration its relationship with another business entity. The UDDI specification also provides two APIs—the Publish API and the Inquiry API—with which you can add information to these information models and query them.
The ebXML Information Model The ebXML registry specification describes its information model as classes. Some of the important classes in the ebXML information model are described in the following list. • RegistryObject—This is an abstract base class that provides the metadata information for the registry objects. Almost all objects in the ebXML object model extend this object. • Slot—The Slot object provides the functionality by which attributes can be added to the instances of the RegistryObjects. For example, if a company wants to add a Warranty Disclaimer attribute to each of the submitted RegistryObject instances, it can do so by adding a Slot with the name Warranty_Disclaimer, and a value containing the disclaimer statement. • Association—These objects are used to define associations between objects stored in the information model. • ExternalIdentifier—Instances of this object provide additional identifier information to an instance of the RegistryObject class. Examples of additional identifier information include DUNS number, Social Security number, and so on.
237
238
CHAPTER 9
Registry Fundamentals
• ExternalLink—An ExternalLink object enables a company submitting some document to the registry to associate some external content to the submitted content. For example, if a company is submitting a DTD to the registry, it might want to associate the link to its home page with the DTD. It is important to remember that the content modeled by the ExternalLink object is not managed by the registry, and can therefore be changed, modified, or moved at any time. • ClassificationScheme—These instances provide the capability to classify or categorize the instances of the RegistryObject instances. Classification schemes can be defined to the registry either externally or internally. An example of the external classification is the North American Industry Classification System (NAICS). This classification provides a scheme by which businesses and services are classified by the industry to which they belong. • ClassificationNode—These instances are used to define tree structures under a ClassificationScheme, where each node in the tree is a ClassificationNode and the root is the ClassificationScheme. For example, different industries, such as HealthCare, Automotive, and so on, are ClassificationNodes under the Industry classification scheme. • Classification—These instances are used to classify the RegistryObject instances. • RegistryPackage—These instances are RegistryObject instances that group together the logically related RegistryObject instances. • AuditableEvent—These instances provide the mechanism to do audit trails for RegistryObject instances. • User—These instances provide information about the registered users of the registry. • PostalAddress—The PostalAddress class models the postal address information of an organization. • EmailAddress—Similar to the PostalAddress class, this class models the information structure of an email address. • Organization—These instances provide information about the organization that is submitting data to the registry. • Service—These instances provide information about the Web services. • ServiceBinding—A ServiceBinding instance provides the information on how to access a specific interface of a Service instance. Multiple ServiceBinding instances can exist for a Service.
The JAXR Architecture
• SpecificationLink—A SpecificationLink provides the necessary link between a ServiceBinding and one of its technical specifications that describes how to use the service with that ServiceBinding. For example, a ServiceBinding might have a SpecificationLink instance that describes how to access the service using a WSDL document or a CORBA IDL document.
The JAXR Specification As is obvious from the descriptions of the UDDI and ebXML specifications, the information model and capabilities between the registries vary greatly. The JAXR specification is an attempt to support the diverse registry specifications. As shown in Figure 9.2, the JAXR specification is a combination of the best features of the various registry specifications.
OASIS
eCo Framework
JAXR
UDDI
ebXML
ISO 11179
FIGURE 9.2
JAXR: A combination of the best features of the different registries.
The JAXR specification is a generic API set that provides the capability to work with the various registries. However, because JAXR is a superset of capabilities of the different registries, not all API methods are supported by all registries.
The JAXR Architecture Figure 9.3 shows the JAXR architecture and its core components, which are described in the following sections.
239
240
CHAPTER 9
Registry Fundamentals
JAXR Client
RegistryService Interface C1
C2
Cn
Capability Specific Interfaces
JAXR Pluggable Provider ebXML Provider
UDDI Provider
ebXML/SOAP
ebXML
FIGURE 9.3
Other Providers
Registry Specific JAXR Provider
UDDI/SOAP
UDDI
Other
The JAXR architecture.
JAXR Client The JAXR client is a Java program that uses the JAXR API to access a registry via a JAXR provider. RegistryService
Interface
The RegistryService interface is the main interface implemented by a JAXR provider. This interface provides a number of methods with which a JAXR client can determine the capability provided by the JAXR provider.
Capability-Specific Interfaces The capability-specific interfaces implemented by a JAXR provider provide various registry capabilities, such as life cycle management and query management. Life cycle management includes the activities that deal with the capability to create, update, or delete registry objects. Query management includes the activities dealing with querying the registry for information.
JAXR Provider A JAXR provider is an application that implements the JAXR specification to access an existing registry provider, such as UDDI or ebXML. A JAXR provider is the combination of a JAXR pluggable provider and registry-specific JAXR providers. The JAXR pluggable provider implements the registry-independent features of JAXR. This enables it to provide an abstraction layer that a JAXR client can use in a registryneutral way to connect to any underlying registry.
The JAXR Packages
The registry-specific JAXR providers implement JAXR in a registry-specific manner. A registry-specific JAXR provider plugs into the pluggable provider layer, accepts JAXR requests from the JAXR clients, and translates them into equivalent registry-specific requests. The registry-specific JAXR provider then sends the request to the particular registry using registry-specific API calls. The registry processes the request and sends back a registry-specific response to the registry-specific JAXR provider, which in turn translates the response to an equivalent JAXR response that is to be delivered to the JAXR client. As mentioned before, the JAXR specification provides an API that includes the best features of all the prominent registries. However, the different registries are in a different level of evolution, and therefore have varying capabilities. This implies that not all methods provided in the JAXR specification can be executed on all registries. For example, unlike ebXML registries, the UDDI registry specification does not support the notion of majorVersion and minorVersion. Therefore, an attempt to execute the setMajorVersion method on a UDDI registry will throw an exception. To handle such a situation, the JAXR specification categorizes its API methods into two capability profiles, called level 0 and level 1. The level 0 methods provide the basic registry capabilities, whereas level 1 methods provide more advanced registry capabilities. A JAXR provider must declare the capability level for its implementation of the JAXR API. A JAXR client can discover the capability level of a JAXR provider by invoking methods of the CapabilityProfile interface implemented by the JAXR providers. By default, all JAXR providers need to provide level 0 support, with support for level 1 optional. It is important to note that JAXR providers for UDDI must support level 0 capabilities, whereas JAXR providers for ebXML must be level 1-compliant. Also, the clients written to use only level 0 methods are portable and can be used by any JAXR provider.
Diverse Registries Figure 9.3 also shows various registries, such as the UDDI- and ebXML-based registries, that are used as part of the JAXR architecture.
The JAXR Packages The JAXR API comes in two packages: • The javax.xml.registry.infomodel package • The javax.xml.registry package
241
242
CHAPTER 9
Registry Fundamentals
The javax.xml.registry.infomodel Package The javax.xml.registry.infomodel package contains the interfaces that represent the information model followed by JAXR. The information model resembles the ebXML information model, with additional enhancements to support the UDDI specification. The javax.xml.registry.infomodel Interfaces The interfaces of the javax.xml.registry.infomodel are described in the following list: • RegistryObject—The RegistryObject interface is the basic interface extended by the other interfaces of the JAXR information model, such as Association, Classification, Organization, and so on. RegistryObject can have several attributes, such as its classification, associations, and so on. RegistryObject provides several methods with which you can add and get such metadata information about a registry object. • Association—The Association interface represents the association of a RegistryObject instance with another RegistryObject instance. For example, consider two ClassificationScheme instances, where one instance supercedes the other. In this case, the newer ClassificationScheme instance, called the source object, will have a supercedes association type with the older ClassificationScheme instance, called the target object. • AuditableEvent—The instances of the AuditableEvent interface provide a mechanism to maintain an audit trail of registry objects. An AuditableEvent instance can be created when a JAXR client creates, updates, deletes, or deprecates a registry object. A complete audit trail for a registry object can be obtained by using the collection of AuditableEvent instances associated with the RegistryObject instance. It is important to note that all the methods defined in this interface are level 1 methods. Therefore, these methods cannot be invoked on a UDDI registry. • Classification—The Classification interface is used to classify the instances of registry objects, such as by industry, product, and geographical location. A registry object can have more than one classification instance associated with it. • ClassificationScheme—A ClassificationScheme instance represents a taxonomy used to classify or categorize RegistryObject instances. A taxonomy is an orderly classification of objects according to their presumed natural relationships. For example, the North American Industry Classification System (NAICS) is a classification scheme used to classify businesses and services to which they belong.
The JAXR Packages
The ClassificationSchemes (also called taxonomies) can be either internal or external to the registries. A ClassificationScheme that is internal to the registry is called an Internal Taxonomy, and one external to the registry is called an External Taxonomy. • Concept—The Concept instance represents a notion that could be anything. One use of the Concept interface is to represent the ClassificationScheme (or taxonomy) elements and their structural relationship with each other in order to describe an internal taxonomy. The Concept interface is used to create a tree structure in which the ClassificationScheme is the root of the tree, and each node of the tree is a Concept instance. For example, consider the Geography classification scheme. In this, Geography will be the root of the tree, and the continents such as Asia and Europe would be instances of the Concept instance. • EmailAddress—As the name suggests, the EmailAddress interface represents the email address. • Slot—The Slot interface provides a way to dynamically add attributes to a registry object at runtime. • ExtensibleObject—The ExtensibleObject interface enables the registry objects to be extensible in nature. The methods provided by this interface enable a registry object to add, delete, or query for slots. This interface is extended by almost all the interfaces of the JAXR information model. • ExternalIdentifier—The ExternalIdentifier interface is a mechanism to provide identification information to a registry object. Examples of identifications include Social Security number, DUNS number, and so on. • ExternalLink—The ExternalLink interface provides a mechanism to associate external content with a registry object. The external content is essentially a URI that can be set and accessed by using the methods of this interface. • ExtrinsicObject—The ExtrinsicObject interface represents the metadata for a repository item about which the registry might not have any prior knowledge. Examples of such items include a WSDL document, or an XML schema document. It is important to note that all the methods defined in this interface are level 1 methods. Therefore, these methods cannot be invoked on a UDDI registry. • InternationalString—The InternationalString interface is used to provide internationlization support for the String type. An instance of the InternationalString interface contains a collection of LocalizedString interfaces, which in turn contain a String value that is specific to a particular Locale and character set.
243
244
CHAPTER 9
Registry Fundamentals
• Key—The Key interface represents a unique key identifying a registry object. This key is normally created by the registry, and is returned after the organization is submitted to the registry. • LocalizedString—The LocalizedString interface is a wrapper interface that associates a String with a Locale and character set. This interface is used by the InternationalString interface. • Organization—The Organization interface models the information about an organization that is submitting data to the registry. An Organization instance may have address and contact attributes. • PersonName—The PersonName interface models the name of a person. • PostalAddress—The PostalAddress interface provides the mechanism to store and access the postal address information. The PostalAddress interface is a reusable entity. At the time of this writing, this interface is used to provide information for a User and an Organization. • RegistryEntry—Some objects in the registry need to store additional metadata over and above what can be stored using the RegistryObject interface. Such objects are modeled using the RegistryEntry interface. Examples of additional metadata include version information and a stability indicator for the information. • RegistryPackage—The RegistryPackage interface represents a group of logically related registry objects. A registry object can be a member of any number of packages, and a package can contain any number of registry objects. • Service—The Service interface models the BusinessService datastructure as described in the UDDI specification. This interface provides information on services, such as Web services offered by an Organization. • ServiceBinding—The ServiceBinding interface models the BindingTemplate datastructure as described in the UDDI specification. This interface represents the technical information on a specific way to access a specific interface offered by the Service instance. This interface can have multiple SpecificationLink interfaces. • SpecificationLink—The SpecificationLink interface provides a mechanism to link between a ServiceBinding and one of its technical specifications that describes how to use the service using ServiceBindings. For example, a SpecificationLink instance might describe how to access a Web service using a WSDL document. • TelephoneNumber—The TelephoneNumber interface models a telephone number.
The JAXR Packages
• User—The User interface provides information about the registered users of the registry. A User is always affiliated with an Organization. • Versionable—The Versionable interface models the behavior common to those classes that can create versions of their instances. It is important to note that all the methods defined in this interface are level 1 methods. Therefore, none of these methods can be invoked on a UDDI registry.
The javax.xml.registry Package The javax.xml.registry package contains 14 interfaces, 1 class, and 7 exceptions with which you can manage and query data in a registry. The javax.xml.registry Interfaces The interfaces of the javax.xml.registry package are described in the following list: • BulkResponse—The BulkResponse interface is returned by several methods; these methods perform an operation with a collection of objects and also return a collection of objects. For example, the saveObjects method of the LifeCycleManager interface that saves data to the registry returns a BulkResponse. • BusinessLifeCycleManager—The BusinessLifeCycleManager interface defines several methods with which you can create and manage some high-level interfaces of the information model. These interfaces are Organization, Service, ServiceBinding, and Concept. It is important to note that the BusinessLifeCycleManager interface is similar in terms of functionality to LifeCycleManager interface, but is provided separately for the convenience of UDDI developers. This interface is similar to the Publisher API of UDDI. • BusinessQueryManager—The BusinessQueryManager interface defines several methods that provide the capability to query for the high-level interfaces of an information model. These interfaces are Organization, Service, ServiceBinding, and Concept. • CapabilityProfile—The CapabilityProfile interface defines the methods with which an application can determine whether a JAXR provider is level 0or level 1-compliant. • CataloguedObject—The CataloguedObject interface is a wrapper interface. It wraps the RegistryEntry object and the RepositoryItem that it catalogues.
245
246
CHAPTER 9
Registry Fundamentals
• Connection—The Connection interface represents the session of a JAXR client with a registry such as UDDI by using a JAXR provider. This interface defines several methods with which an application can determine the state information for a specific connection. • DeclarativeQueryManager—The DeclarativeQueryManager interface defines methods with which an application can use a declarative query language to query on a registry. At the time of this writing, the only supported declarative query languages are SQL-92 and OASIS ebXML Registry Filter Queries. • Federation—The Federation interface is a special implementation of the Connection interface. This interface defines a single connection to multiple registry providers. The Federation connection is used to perform a query on multiple registry providers while treating them as a single logical registry provider. • FindQualifier—The FindQualifier interface defines several constants that identify behaviors that affect the behavior of the find methods. For example, the constant SORT_BY_NAME_ASC will ensure that the data returned by find methods is in ascending order. • JAXRResponse—The JAXRResponse interface represents the response of any JAXR request. • LifeCycleManager—The LifeCycleManager interface provides the necessary methods to create and manage data in a registry. • Query—The Query interface encapsulates a query in a declarative query language, such as SQL. • QueryManager—QueryManager provides a common base interface for the other two query managers: BusinessQueryManager and DeclarativeQueryManager. • RegistryService—The RegistryService interface is the main interface implemented by a JAXR provider. This interface provides a number of get methods with which a JAXR client can find out the various capability-specific interfaces implemented by the JAXR provider.
The javax.xml.registry Class The javax.xml.registry package contains the abstract base class ConnectionFactory, which is a factory class for enabling a JAXR client to connect to a JAXR provider. The javax.xml.registry Exceptions The exceptions of the javax.xml.registry package are described in the following list:
Summary
• InvalidRequestException—InvalidRequestException is thrown when a JAXR client attempts to invoke an invalid API method. • JAXRException—JAXRException is the parent exception class. This exception represents all JAXR-related exceptions. • UnexpectedObjectException—UnexpectedObjectException is thrown when the object passed on as a parameter to a method call is of an invalid type. For example, UnexpectedObjectException is raised if an application passes a collection of organization objects to the saveServiceBindings method, instead of the required collection of bindings objects. • UnsupportedCapabilityException—UnsupportedCapabilityException is raised whenever a JAXR client tries to invoke a method not supported by the CapabilityProfile implemented by the JAXR provider. For example, the UDDI registries do not support the notion of majorversion and minorversion. Therefore, the UnsupportedCapabilityException is raised if an application tries to invoke the setMajorVersion method on a UDDI registry. • DeleteException—DeleteException is raised if a problem is encountered when deleting a registry object. • FindException—FindException is raised when an error is encountered while trying to query a registry. • SaveException—SaveException is raised when an error is encountered while trying to save data to a registry.
Summary In this chapter, you learned about the various roles a registry performs and the use model that businesses follow for using a registry. You also learned about the JAXR architecture and the JAXR packages that enable an application to dynamically connect to and work with any registry.
247
10 JAXR Implementations J
AXR clients are the J2SE applications that implement the Java API for XML-based Registries (JAXR). Using this API, a Java application can connect to UDDI-based registries and submit, query, and manage information about organizations. At this point in time there are several test registries available from IBM, Microsoft, Hewlett-Packard, and SAP to which you can connect, publish, and query data. In this chapter, you will learn to write applications that will connect to a UDDI registry and publish, query, and delete data from it.
The JWSDP Registry Server The JWSDP Registry Server is a UDDI Version 2-compliant registry server provided with the JWSDP download pack. The registry server is implemented as a servlet hosted in the Tomcat Web server. A database based on an Xindice database is used to store the registry data. This database is also shipped with the JWSDP download. You will be using the JWSDP Registry Server to run the applications created in this chapter. The JWSDP Registry Server can be used only after starting the Tomcat Web server and the Xindice database. Go to Start, Programs, Java Web Services Developer Pack 1.0, Start Tomcat to start the Tomcat Web server. To start the Xindice database, select Start, Programs, Java Web Services Developer Pack 1.0, Start Xindice. After both the Tomcat Web server and the Xindice server are up, you can use the JWSDP Registry Server.
IN THIS CHAPTER • The JWSDP Registry Server • Publishing Data to a Registry • Querying Data from a Registry • Deleting Data from Registry
250
CHAPTER 10
JAXR Implementations
NOTE There are a number of other registries that can be accessed by JAXR to publish, query, and manage information: • Microsoft—http://uddi.rte.microsoft.com/ • IBM—http://www-3.ibm.com/services/uddi/v2beta/protect/registry.html • Hewlett-Packard—http://uddi.hp.com/ • SAP—http://udditest.sap.com/ • Systinet—http://www.systinet.com/index.php?nav=/products/wasp_uddi/ overview
• Glue—http://www.theindelectric.com
Now let’s start developing the applications that use JAXR to access and work with UDDI-based registries. Because the JWSDP registry is empty, you need to populate it with data before you can run queries. Therefore, the first application you will be creating will demonstrate how to publish data to a registry. Next, you will build an application that will query the registry to get the required information. The chapter will conclude with an application that shows how to delete information from a registry.
Publishing Data to a Registry An organization publishes the information about itself to a registry. This enables other organizations to query the registry, get information about the companies whose information is published in the registry, and engage in business with them. To understand how to publish data to a registry, you will write an application called MyOrganizationPublisher.java. This application will publish the data about a fictitious company called The Great Car Parts Company. The first requirement to publish or modify information to a registry is to obtain a valid user ID and password from the registry. The JWSDP Registry Server provides the default user ID/password pair of testuser/testuser. You will be using this user ID/password pair in your applications. After you have the user ID and password, you need to do the following in your application to publish data to a registry: 1. Create a connection with the registry. 2. Using the user ID and password, set the credentials with the registry. 3. Create an Organization object and populate it with Name, Description, Key, PrimaryContact, and a collection of Classification, Service, and ServiceBindings objects. 4. Save the organization to the registry.
Publishing Data to a Registry
Now let’s get down to actually developing the MyOrganizationPublisher.java application. In the application, you will do the following: • Import the necessary classes. • Create a method called connect that creates a connection with the registry. • Create a method called publishdata that publishes data to the registry.
Creating the MyOrganizationPublisher.java Application To create the MyOrganizationPublisher.java application, select a text editor and create an empty text file called MyOrganizationPublisher.java. In the file, enter the following lines of code to declare the MyOrganizationPublisher application: public class MyOrganizationPublisher { public static void main(String[] args) { } }
Importing the Required Packages and Classes Next you will import the required classes. You need to enter the following packages and classes: • javax.xml.registry.*—The classes of the javax.xml.registry package are required to create a connection to the registry, and to obtain the interface that enables you to access the information stored in the JAXR information model. • javax.xml.registry.infomodel.*—The classes of the javax.xml.registry.infomodel package enable you to access the elements of a registry. In using the classes of this package, you model the information that is to be published in the registry. • java.net.*—The classes of the java.net package enable you to connect to network devices. • java.security.*—The classes of the java.security package enable you to build the password authentication mechanism. • java.util.*—The java.util package provides a number of utility classes such as Collection and Iterator. As you will see later, most of the JAXR methods take Collection objects as parameters or return Collection objects. Therefore, the classes of the java.util package are required to create the parameters and store the return values from the JAXR methods.
251
252
CHAPTER 10
JAXR Implementations
To import the classes, enter the following lines of code shown in bold: import import import import import
javax.xml.registry.*; javax.xml.registry.infomodel.*; java.net.*; java.security.*; java.util.*;
public class MyOrganizationPublisher {
Writing the Plumbing Code Now you will write the necessary plumbing code for the application. In the MyOrganizationPublisher application, you need to define the following: • A null Connection object. This will be used to hold the reference to the Connection object obtained from the instance of the ConnectionFactory class. You will be using this to make the connect method, which will have the required code to make a connection to the registry server. • The publishdata method, which will have the required code to publish data to the registry. To accomplish these tasks, enter the following lines of code shown in bold: public class MyOrganizationPublisher { Connection connection = null;
public static void main(String[] args) { MyOrganizationPublisher mop = new MyOrganizationPublisher(); mop.connect(); mop.publishdata(); }
Connecting to the Registry With the plumbing code done, let’s write the code to connect to the registry. Similar to what you have done so far for the other APIs, a connection to a registry is obtained using a connection factory. However, unlike the other APIs, you need to perform one extra step before you can create a connection to the registry service.
Publishing Data to a Registry
The extra step is to set six properties: the URLs to the publish and query registries, the HTTP proxy host and port address for accessing the query service, and the HTTPS proxy host and port address for accessing the publish service: • javax.xml.registry.queryManagerURL—This property specifies the URL of the query manager service in the registry to which the application is connecting. • javax.xml.registry.lifeCycleManagerURL—This property specifies the URL for the life cycle manager service in the registry. The life cycle manager service enables you to publish and manage data in the registry. • com.sun.xml.registry.http.proxyHost—This property specifies the HTTP proxy host that will be used to connect to registries outside your enterprise’s firewall. The HTTP proxy host is used when you are accessing the registry for queries. • com.sun.xml.registry.http.proxyPort—This property specifies the HTTP proxy port to connect to registries outside your enterprise’s firewall. Typically, the port value is 8080. • com.sun.xml.registry.https.proxyHost—This property specifies the HTTPS proxy host that will be used to connect to registries outside your enterprise’s firewall. The HTTPS proxy host is used when you are accessing the registry for publishing or editing data. • com.sun.xml.registry.https.proxyPort—This property specifies the HTTPS proxy port to connect to registries outside your enterprise’s firewall. Typically, the port value is 8080. As you will be using the JWSDP Registry Server, the URLs to the publish and query registries are the same. However, the URLs for other UDDI-based registries might be different. You might recall that the UDDI specification describes two API sets for publishing and inquiring: publish APIs and inquiry APIs. Following that naming convention, the IBM and the Microsoft registries have different URLs for inquiry and publishing services. For example, the IBM registry has the following URLs for inquiry and publishing, respectively: http://www-3.ibm.com/services/uddi/v2beta/inquiryapi https://www-3.ibm.com/services/uddi/v2beta/protect/publishapi
Also, because the JWSDP Registry Server is within the firewall, the proxy host and port address will be empty. Here again, in case you want to access registries outside your firewall, you will need to specify the proxy host and port address.
253
254
CHAPTER 10
JAXR Implementations
Coming back to the code for the connect method, you need to do the following: 1. Define two String objects to hold the URL values for the JWSDP Registry
Server query and publish services. For the JWSDP registry service, the URL for both the publish and inquiry services is the same. 2. Define four String objects for storing the proxy host and port values for the
HTTP and HTTPS connections. 3. Create a Properties object and store the properties. 4. Set the properties on the ConnectionFactory instance. 5. Create the connection to the registry.
To accomplish these tasks, enter the lines of code shown in Listing 10.1. LISTING 10.1
The connect Method
public void connect() { String queryURL = “http://localhost:8080/registry-server/RegistryServerServlet”; String publishURL = “http://localhost:8080/registry-server/RegistryServerServlet”; String String String String
httpProxyHost = “”; httpProxyPort = “”; httpsProxyHost = “”; httpsProxyPort = “”;
Properties props = new Properties(); props.setProperty(“javax.xml.registry.queryManagerURL”, queryUrl); props.setProperty(“javax.xml.registry.lifeCycleManagerURL”, publishUrl); props.setProperty(“com.sun.xml.registry.http.proxyHost”, httpProxyHost); props.setProperty(“com.sun.xml.registry.http.proxyPort”, httpProxyPort); props.setProperty(“com.sun.xml.registry.https.proxyHost”, httpsProxyHost); props.setProperty(“com.sun.xml.registry.https.proxyPort”, httpsProxyPort);
Publishing Data to a Registry
LISTING 10.1
Continued
try { ConnectionFactory factory = ConnectionFactory.newInstance(); factory.setProperties(props); connection = factory.createConnection(); System.out.println(“Created connection to registry”); } catch (Exception e) { e.printStackTrace(); } }
Now that the connection to the registry server has been made, let’s write the code for the publishdata method, which takes care of publishing data to the registry.
Publishing Data to the Registry Publishing data to the registry implies creating an Organization object, populating the object, submitting the object to the registry, saving the submitted data, and obtaining the organization key generated by the registry when the data is saved. For this example, you will use the following information to populate the Organization object:
• Company Name: The Great Car Parts Company • Description: Suppliers of high quality car accessories • Contact Person Name: Jack • Telephone Number: (800) 555-111 • Contact Email Address:
[email protected] • Classification Scheme To Be Used: NAICS • Classified As: Car Parts and Accessories • Service: CarPartRequest • Service Description: Order car parts • Service Binding URI: http://greatcarpartcompany.com:8080/CarPartRequest/ • Service Binding Description: Binding for CarPartRequest Service
255
256
CHAPTER 10
JAXR Implementations
To do all this, you need to do the following in the publishdata method: 1. Get a reference to the RegistryService object. 2. From the RegistryService object, obtain the instances of the BusinessLifeCycleManager and BusinessQueryManager objects. The BusinessLifeCycleManager object enables the creation of the Organization
object and its constituent objects that are submitted to the registry. The BusinessQueryManager enables you to run queries on the registry service. 3. Create a PasswordAuthentication object with the default user ID/password combination of testuser/testuser. Using the PasswordAuthentication object,
set the credentials with the registry. 4. Create an Organization object and populate it with Name, Description, Key, PrimaryContact, and a collection of Classification, Service, and ServiceBindings objects. 5. Save the organization to the registry. 6. Get the key generated by the registry when an organization is saved. This key is
required when you want to modify registry data. To get the instances of the interfaces, enter the following lines of code: public void publishdata() { String username = “testuser”; String password = “testuser”; RegistryService rsrvc = null; BusinessLifeCycleManager bsnslfcmgr = null; BusinessQueryManager bqrymgr = null; try { rsrvc = connection.getRegistryService(); bsnslfcmgr = rsrvc.getBusinessLifeCycleManager(); bqrymgr = rsrvc.getBusinessQueryManager(); System.out.println(“Got registry service, query “ + “manager, and life cycle manager”);
Next you need to set the credentials with the registry. To do so, enter the following lines of code shown in bold:
Publishing Data to a Registry
System.out.println(“Got registry service, query manager, and ➥life cycle manager”); // Get authorization from the registry PasswordAuthentication passwdAuth = new PasswordAuthentication(username, password.toCharArray()); Set creds = new HashSet(); creds.add(passwdAuth); connection.setCredentials(creds); System.out.println(“Security credentials established”);
Note that you created a Set object and populated it with the PasswordAuthentication object. This was required because the setCredentials method of the Connection object takes a Set object as its parameter. Next you will create an Organization object and provide a description for it. To do so, enter the following lines of code shown in bold: System.out.println(“Security credentials established”); // Create organization name and description Organization orgn = bsnslfcmgr.createOrganization(“The Great Car Parts Company”); InternationalString descn = bsnslfcmgr.createInternationalString(“Suppliers of high ➥quality car accessories”); orgn.setDescription(descn); System.out.println(“Description about the organization added”);
The next step is to create an Organization object. To do so, enter the following bold lines of code: System.out.println(“Security credentials established”); // Create organization, specify name and description Organization orgn = bsnslfcmgr.createOrganization(“The Great Car Parts Company”); InternationalString descn = bsnslfcmgr.createInternationalString(“Suppliers of high ➥quality car accessories”); orgn.setDescription(descn); System.out.println(“Description about the organization added”);
257
258
CHAPTER 10
JAXR Implementations
The Organization object needs to be populated with contact details. To do so, enter the following lines of code shown in bold: System.out.println(“Security credentials established”); // Create organization, specify name and description Organization orgn = bsnslfcmgr.createOrganization(“The Great Car Parts Company”); InternationalString descn = bsnslfcmgr.createInternationalString(“Suppliers of high ➥quality car accessories”); orgn.setDescription(descn); System.out.println(“Description about the organization added”); // Enter the Contact Person Name User primaryContact = bsnslfcmgr.createUser(); PersonName pName = bsnslfcmgr.createPersonName(“Jack”); primaryContact.setPersonName(pName); // Enter primary contact phone number TelephoneNumber telNo = bsnslfcmgr.createTelephoneNumber(); telNo.setNumber(“(800) 555-1111”); Collection phoneNums = new ArrayList(); phoneNums.add(telNo); primaryContact.setTelephoneNumbers(phoneNums); // Enter primary contact email address EmailAddress emailAdd = bsnslfcmgr.createEmailAddress(“
[email protected]”); Collection emailAddresses = new ArrayList(); emailAddresses.add(emailAdd); primaryContact.setEmailAddresses(emailAddresses); // Set primary contact for organization orgn.setPrimaryContact(primaryContact); System.out.println(“Primary contact details added”);
Now you will specify the classification scheme under which to classify the organization. In our case, it is the NAICS classification scheme. To do that, you will first query the registry to get the NAICS classification scheme, and then classify the organization within the NAICS classification scheme.
Publishing Data to a Registry
To do so, enter the lines of code shown here in bold: System.out.println(“Primary contact details added”); // Set classification scheme to NAICS ClassificationScheme cScheme = bqrymgr.findClassificationSchemeByName(null, “ntis-gov:naics”); // Create and add classification Classification classification = (Classification) bsnslfcmgr.createClassification(cScheme, “Car Parts and Accessories”, “123456”); Collection classifications = new ArrayList(); classifications.add(classification); orgn.addClassifications(classifications); System.out.println(“Classification added”);
Note that you use the findClassificationSchemeByName method of the BusinessQueryManager interface to query the registry for NAICS classification. Next you will specify the services that the organization provides. For each service, there will be a ServiceBinding object that describes how to access the service. This description consists of the textual description, an access URI, and an optional specification link. To do so, add the lines of code shown here in bold: System.out.println(“Classification added”); // Create services and service Collection services = new ArrayList(); Service service = bsnslfcmgr.createService(“CarPartRequest”); InternationalString desc = bsnslfcmgr.createInternationalString(“Order Car Parts”); service.setDescription(desc); // Create service bindings Collection serviceBindings = new ArrayList(); ServiceBinding binding = bsnslfcmgr.createServiceBinding(); descn = bsnslfcmgr.createInternationalString(“Binding for ➥CarPartRequest service”); binding.setDescription(descn); // turn off address validation binding.setValidateURI(false);
259
260
CHAPTER 10
JAXR Implementations
binding.setAccessURI(“http://greatcarpartcompany.com:8080/ ➥CarPartRequest/”); serviceBindings.add(binding); // Add service bindings to service service.addServiceBindings(serviceBindings); // Add service to services, then add services to organization services.add(service); orgn.addServices(services); System.out.println(“Services added”);
Note that JAXR attempts to check the validity of the access URI by default. Because in this case it is a hypothetical URI, you do not want JAXR to validate the address. To do so, you would use the setValidate method with the false parameter. After you have added the services and their service bindings, you are ready to save the Organization object to the registry. To save the Organization object, you use the saveOrganizations method of the BusinessLifeCycleManager interface. The saveOrganizations method returns a BulkResponse object. The BulkResponse object contains a collection of objects. Depending upon whether the save was successful, the BulkResponse will contain the keys generated by either the registry or exception objects. To save the Organization object and determine the status of the save operation, enter the lines of code listed in bold here: System.out.println(“Services added”); // Add organization and submit to registry // Retrieve key if successful Collection orgs = new ArrayList(); orgs.add(orgn); //Iterator for keys or exception Iterator itr; BulkResponse response = bsnslfcmgr.saveOrganizations(orgs); Collection exceptions = response.getExceptions(); if (exceptions == null) { System.out.println(“Organization saved”); Collection keys = response.getCollection(); itr = keys.iterator(); if (itr.hasNext()) { javax.xml.registry.infomodel.Key orgKey =
Publishing Data to a Registry
(javax.xml.registry.infomodel.Key) itr.next(); String id = orgKey.getId(); System.out.println(“Organization key is “ + id); } } else { itr = exceptions.iterator(); Exception exception = null; while (itr.hasNext()) { exception = (Exception) itr.next(); System.err.println(“Failed to save because: “ + exception.toString()); } } } catch (Exception e) { e.printStackTrace(); } finally { // At end, close connection to registry if (connection != null) { try { connection.close(); } catch (JAXRException je) {} } } }
NOTE The code discussed so far in this chapter is available in the MyJAXRExample folder.
You are now all set to compile and run the MyOrganizationPublisher application. To compile the application, specify the following command at the command prompt: javac -classpath .;d:\jwsdp-1_0\common\lib\jaxr-ri.jar;d:\jwsdp-1_0\common\lib\ ➥jaxr-api.jar;d:\jwsdp-1_0\common\lib\jaxrpc-ri.jar;d:\jwsdp-1_0\common\ ➥lib\jaxrpc-api.jar;d:\jwsdp-1_0\common\lib\activation.jar;d:\jwsdp-1_0\ ➥common\lib\dom4j.jar;d:\jwsdp-1_0\common\lib\jaxm-api.jar;d:\jwsdp-1_0\ ➥common\lib\jaxm-client.jar;d:\jwsdp-1_0\common\lib\log4j.jar;d:\jwsdp-1_0\ ➥common\lib\mail.jar;d:\jwsdp-1_0\common\lib\xalan.jar;d:\jwsdp-1_0\common\ ➥lib\xerces.jar;d:\jwsdp-1_0\common\lib\ ➥jaxp-api.jar-d . MyOrganizationPublisher.java
261
262
CHAPTER 10
JAXR Implementations
NOTE To build the application, you can also use the buildclient.bat batch file available in the MyJAXRExample folder. The syntax to run the buildclient.bat file is as follows: buildclient MyOrganizationPublisher.java
To run the application, enter the following at the command prompt: java -DuseSOAP=true -classpath .;d:\jwsdp-1_0\common\endorsed\xalan.jar; ➥d:\jwsdp-1_0\common\endorsed\dom.jar; ➥d:\jwsdp-1_0\common\endorsed\sax.jar;d:\jwsdp-1_0\common\endorsed\ ➥xercesImpl.jar;d:\jwsdp-1_0\common\endorsed\xsltc.jar;d:\jwsdp-1_0\common\ ➥lib\jaxr-ri.jar;d:\jwsdp-1_0\common\lib\jaxr-api.jar;d:\jwsdp-1_0\common\ ➥lib\jaxrpc-ri.jar;d:\jwsdp-1_0\common\lib\jaxrpc-api.jar;d:\jwsdp-1_0\ ➥common\lib\activation.jar;d:\jwsdp-1_0\common\lib\dom4j.jar;d:\jwsdp-1_0\ ➥common\lib\jaxm-api.jar;d:\jwsdp-1_0\common\lib\jaxm-client.jar;d:\ ➥jwsdp-1_0\common\lib\log4j.jar;d:\jwsdp-1_0\common\lib\mail.jar;d:\ ➥jwsdp-1_0\common\lib\xalan.jar;d:\jwsdp-1_0\common\lib\xerces.jar;d:\ ➥jwsdp-1_0\common\lib\jaxp-api.jar;d:\jwsdp-1_0\common\lib\commons-logging. ➥jar;d:\jwsdp-1_0\common\lib\soap.jar;d:\jwsdp-1_0\common\lib\ ➥castor-0.9.3.9-xml.jar; MyOrganizationPublisher
NOTE To run the application, you can also use the buildclient.bat batch file available in the MyJAXRExample folder. The syntax to run the runclient.bat file is as follows: runclient MyOrganizationPublisher
The output of the application would be similar to the following code: Created connection to registry Got registry service, query manager, and life cycle manager Security credentials established Description about the organization added Primary contact details added Classification added Services added Organization saved Organization key is eeb543f8-5dee-b543-8407-30aeb62c40bd Note that the organization key generated by the UDDI registry might be different.
Querying Data from a Registry
Querying Data from a Registry So far in the chapter, you’ve learned how to save information about an organization into a registry. In this section, you will learn to write an application that queries a registry for information about organizations. The application you will write will be named MyRegistryQuery.java. It will take a string as the parameter and then search the registry for all organizations that have the specified string in their names. Similar to the MyOrganizationPublisher application, you will import the necessary classes, create a connect method to connect to the registry, and create a runQuery method to do the actual querying on the registry.
Creating the MyRegistryQuery.java Application To create the MyRegistryQuery application, select a text editor and create an empty text file called MyRegistryQuery.java. Enter the following lines of code in the file to import the classes, and declare the MyRegistryQuery application: import import import import
javax.xml.registry.*; javax.xml.registry.infomodel.*; java.net.*; java.util.*;
public class MyRegistryQuery {
Note that you do not need to have a user ID and password to run a query against a registry. Therefore, unlike the MyOrganizationPublisher application, there is no need to import the java.security package in the MyRegistryQuery application.
Writing the Plumbing Code Now you will write the necessary plumbing code for the application. In the MyRegistryQuery application, you need to define the following: • A null Connection object. This will be used to hold the reference to the Connection object obtained from the instance of the ConnectionFactory class. • Because the application needs a string as the parameter, you need to specify code to check it. In case the parameter is not specified, the program should exit. • A default constructor for the MyRegistryQuery class. You will use this constructor to instantiate the MyRegistryQuery class and make calls to the connect and runQuery methods from within the application.
263
264
CHAPTER 10
JAXR Implementations
• The connect method, which will have the required code to make a connection to the registry server. • The runQuery method, which will have the required code to run the query on the registry. To accomplish these tasks, enter the following lines of code shown in bold: public class MyRegistryQuery { Connection connection = null;
public static void main(String[] args) { if (args.length < 1) { System.out.println(“Usage: runclient “ + “MyRegistryQuery string”); System.exit(1); } String queryString = new String(args[0]); System.out.println(“Query string is “ + queryString); MyRegistryQuery mrq = new MyRegistryQuery(); mrq.connect(); mrq.runQuery(queryString); }
Connecting to the Registry Next you will write the code that enables the application to connect to the registry. The code for connecting to the registry (the connect method) is very similar to the one that you wrote for MyOrganizationPublisher, and is shown in Listing 10.2. The only difference is that because you will only be querying the registry, there is no need to define the system properties for HTTPS connections. These properties need to be defined only when you access the registry for publishing data or for the modification of data.
Querying Data from a Registry
LISTING 10.2
The connect Method
public void connect() {
String queryURL = “http://localhost:8080/registry-server/RegistryServerServlet”; String publishURL = “http://localhost:8080/registry-server/RegistryServerServlet”; String httpProxyHost = “”; String httpProxyPort = “”;
Properties props = new Properties(); props.setProperty(“javax.xml.registry.queryManagerURL”, queryURL); props.setProperty(“com.sun.xml.registry.http.proxyHost”, httpProxyHost); props.setProperty(“com.sun.xml.registry.http.proxyPort”, httpProxyPort); try { // Create the connection, ConnectionFactory factory = ConnectionFactory.newInstance(); factory.setProperties(props); connection = factory.createConnection(); System.out.println(“Connection created to the registry”); } catch (Exception e) { e.printStackTrace(); } }
Now that the connection to the registry server has been made, let’s write the code for the runQuery method that takes care of querying the registry.
Querying the Registry A JAXR client queries the registry to get information about the organizations that have published data in the registry. The BusinessQueryManager interface provides a
265
266
CHAPTER 10
JAXR Implementations
number of find methods with which an application can get different types of information from the registry. For example, the findOrganizations method returns a list of organizations that meet the criteria specified in the search string, such as the name of the organization. Similarly, the findServices method returns the set of services published by an organization. In the MyRegistryQuery application, a string is passed as a command-line parameter. The application then searches for the organizations that have the specified string appearing in their names. To build this query, you need to do the following: 1. Get a reference to the RegistryService object. 2. From the RegistryService object, obtain the instance of and BusinessQueryManager object. The BusinessQueryManager enables you to run
queries on the registry service. 3. Use one of the constants of the FindQualifier interface to determine the
sorting and pattern-matching criteria. For example, you can determine whether the searched data should be sorted by name in an ascending or descending order. 4. Use the string supplied from the command line as the name pattern against
which to match. 5. Call the findOrganization method with the combination of FindQualifiers
and name patterns as parameters. 6. Iterate over the BulkResponse object received as a result of the findOrganization method and display the organization data.
To get the instances of the interfaces, enter the following lines of code: public void runQuery(String qString) { RegistryService rsvrc = null; BusinessQueryManager bsnsqrymgr = null; try { // Get registry service and query manager rsvrc = connection.getRegistryService(); bsnsqrymgr = rsvrc.getBusinessQueryManager(); System.out.println(“Got registry service and “ + “query manager”);
Querying Data from a Registry
Next you need to specify the FindQualifier constants and the name pattern. The findOrganiation method takes these as the parameters to query the registry. However, the findOrganization method takes these as Collection objects. So, you need to first convert the FindQualifier and name pattern to Collection objects. To do so, enter the code shown here in bold: System.out.println(“Got registry service and “ + “query manager”); // Specify the find qualifiers and name patterns Collection findQualifiers = new ArrayList(); findQualifiers.add(FindQualifier.SORT_BY_NAME_DESC); Collection namePatterns = new ArrayList(); namePatterns.add(“%” + qString + “%”);
Note that the query string is wrapped in a pair of % characters. This ensures that the query returns all those organizations that have the specified query string anywhere in their name. Next you need to invoke the findOrganizations method. This method returns a BulkResponse object. To invoke the findOrganizations method, enter the following lines of code: namePatterns.add(“%” + qString + “%”); // Find organizations that match the name pattern containing ➥the query string BulkResponse response = bsnsqrymgr.findOrganizations(findQualifiers, namePatterns, null, null, null, null);
The BulkResponse object contains a collection of objects. You need to get the collection of objects from the BulkResponse object. You need to iterate over the Collection object to get the organization details. To do so, enter the lines of code as shown in Listing 10.3. LISTING 10.3
Iterating Over the Collection to Get the Organization Details
Collection orgs = response.getCollection(); // Display information about the organizations found Iterator iter = orgs.iterator(); if (!(iter.hasNext())) { System.out.println(“There are no organizations which match the ➥supplied pattern”);
267
268
CHAPTER 10
LISTING 10.3
JAXR Implementations
Continued
} else while (iter.hasNext()) { Organization orgn = (Organization) iter.next(); //System.out.println(“Organization name: “ + getName(orgn)); System.out.println(“Organization name: “ + orgn. ➥getName().getValue()); System.out.println(“Organization description: “ + orgn.getDescription().getValue()); System.out.println(“Organization key id: “ + orgn. ➥getKey().getId()); // Display contact information such as contact person’s name, ➥phone number etc User prmrycont = orgn.getPrimaryContact(); if (prmrycont != null) { PersonName prmrycontName = prmrycont.getPersonName(); System.out.println(“ Contact name: “ + prmrycontName.getFullName()); Collection phoneNums = prmrycont.getTelephoneNumbers(null); Iterator phoneiter = phoneNums.iterator(); while (phoneiter.hasNext()) { TelephoneNumber number = (TelephoneNumber) phoneiter.next(); System.out.println(“ Phone number: “ + number.getNumber()); } Collection emailadd = prmrycont.getEmailAddresses(); Iterator emailiter = emailadd.iterator(); while (emailiter.hasNext()) { EmailAddress eAd = (EmailAddress) emailiter.next(); System.out.println(“ Email Address: “ + eAd.getAddress()); } } // Display service and binding information Collection services = orgn.getServices(); Iterator srvciter = services.iterator(); while (srvciter.hasNext()) { Service srvc = (Service) srvciter.next(); System.out.println(“ Service name: “ + srvc.getName().getValue());
Querying Data from a Registry
LISTING 10.3
Continued System.out.println(“ Service description: “ + srvc.getDescription().getValue()); Collection serviceBindings = srvc.getServiceBindings(); Iterator srvcbndgiter = serviceBindings.iterator(); while (srvcbndgiter.hasNext()) { ServiceBinding sb = (ServiceBinding) srvcbndgiter.next(); System.out.println(“ Binding “ + “Description: “ + sb.getDescription().getValue()); System.out.println(“ Access URI: “ + sb.getAccessURI()); } } // Print spacer between organizations System.out.println(“ --- “);
} } catch (Exception e) { e.printStackTrace(); } finally { // At end, close connection to registry if (connection != null) { try { connection.close(); } catch (JAXRException je) {} } } }
NOTE The code discussed in this section is available in the MyJAXRExample folder.
You can now compile and run the MyRegistryQuery application. To compile the application, enter the following command at the command prompt:
269
270
CHAPTER 10
JAXR Implementations
javac -classpath .;d:\jwsdp-1_0\common\lib\jaxr-ri.jar;d:\jwsdp-1_0\common\lib\ ➥jaxr-api.jar;d:\jwsdp-1_0\common\lib\jaxrpc-ri.jar;d:\jwsdp-1_0\common\ ➥lib\jaxrpc-api.jar;d:\jwsdp-1_0\common\lib\activation.jar; ➥d:\jwsdp-1_0\common\lib\dom4j.jar;d:\jwsdp-1_0\common\lib\jaxm-api.jar; ➥d:\jwsdp-1_0\common\lib\jaxm-client.jar;d:\jwsdp-1_0\common\lib\log4j.jar; ➥d:\jwsdp-1_0\common\lib\mail.jar;d:\jwsdp-1_0\common\lib\xalan.jar; ➥d:\jwsdp-1_0\common\lib\xerces.jar;d:\jwsdp-1_0\common\lib\jaxp-api.jar -d . MyRegistryQuery.java
NOTE To build the client, you can also use the buildclient.bat batch file available in the MyJAXRExample folder. The syntax to run the buildclient.bat file is as follows: buildclient MyRegistryQuery.java
Currently the registry server has data for only one company: The Great Car Parts Company. So, we will run the application and search for companies that have the string Car in their names. To run the application, enter the following at the command prompt: java -DuseSOAP=true -classpath .;d:\jwsdp-1_0\common\endorsed\xalan.jar; ➥d:\jwsdp-1_0\common\endorsed\dom.jar;d:\jwsdp-1_0\common\endorsed\sax.jar; ➥d:\jwsdp-1_0\common\endorsed\xercesImpl.jar;d:\jwsdp-1_0\common\endorsed\ ➥xsltc.jar;d:\jwsdp-1_0\common\lib\jaxr-ri.jar;d:\jwsdp-1_0\common\lib\ ➥jaxr-api.jar;d:\jwsdp-1_0\common\lib\jaxrpc-ri.jar;d:\jwsdp-1_0\common\ ➥lib\jaxrpc-api.jar;d:\jwsdp-1_0\common\lib\activation.jar;d:\jwsdp-1_0\ ➥common\lib\dom4j.jar;d:\jwsdp-1_0\common\lib\jaxm-api.jar;d:\jwsdp-1_0\ ➥common\lib\jaxm-client.jar;d:\jwsdp-1_0\common\lib\log4j.jar;d:\jwsdp-1_0\ ➥common\lib\mail.jar;d:\jwsdp-1_0\common\lib\xalan.jar;d:\jwsdp-1_0\common\ ➥lib\xerces.jar;d:\jwsdp-1_0\common\lib\jaxp-api.jar;d:\jwsdp-1_0\common\ ➥lib\commons-logging.jar;d:\jwsdp-1_0\common\lib\soap.jar;d:\jwsdp-1_0\ ➥common\lib\castor-0.9.3.9-xml.jar; MyRegistryQuery Car
NOTE To run the application, you can also use the buildclient.bat batch file available in the MyJAXRExample folder. The syntax to run the runclient.bat file is as follows: runMyRegistryQuery MyORegistryQuery Car
Deleting Data from Registry
The output should be similar to the following: Query string is Car Connection created to the registry Got registry service and query manager Organization name: The Great Car Parts Company Organization description: Suppliers of high quality car accessories Organization key id: eeb543f8-5dee-b543-8407-30aeb62c40bd Contact name: Jack Phone number: (800) 555-1111 Email Address:
[email protected] Service name: CarPartRequest Service description: Order Car Parts Binding Description: Binding for CarPartRequest service Access URI: http://greatcarpartcompany.com:8080/CarPartRequest/ ---
Deleting Data from Registry So far you have learned how to publish data to a registry and how to query a registry for information. You will now learn how to delete data from a registry. You can only delete data that you have submitted. A registry does not allow the deletion of information about organizations that are published by other users. The BusinessLifeCycleManager interface provides several delete methods with which you can remove information about an organization. For example, the deleteService method enables you to delete services associated with an organization. You will write an application called MyDataDeleter.java that will take as a command-line argument a string containing the key generated by the registry when the organization was saved. The application will delete the organization that matches the key value sent as the command-line parameter. Similar to the MyOrganizationPublisher application, you will import the necessary classes, create a connect method to connect to the registry, and a delete method to do the actual deletion of data on the registry.
Creating the MyDataDeleter.java Application To create the MyDataDeleter application, select a text editor and create an empty text file called MyDataDeleter.java. In the file, enter the following lines of code to import the classes and declare the MyDataDeleter application:
271
272
CHAPTER 10
import import import import import
JAXR Implementations
javax.xml.registry.*; javax.xml.registry.infomodel.*; java.net.*; java.security.*; java.util.*;
public class MyDataDeleter {
Writing the Plumbing Code Next you will write the necessary plumbing code for the application. In the MyDataDeleter application, you need to define the following: • A null Connection object. This will be used to hold the reference to the Connection object obtained from the instance of the ConnectionFactory class. • Because the application needs a string as the parameter, you need to specify code to check it. In case the parameter is not specified, the program should exit. • A default constructor for the MyDataDeleter class. You will be using the constructor to create an instance of the MyDataDeleter class and make calls to the connect and delete methods from within the application. • The connect method, which will have the required code to make a connection to the registry server. • The delete method, which will have the required code to delete data from the registry. To complete these tasks, enter the lines of code shown here in bold: public class MyDataDeleter { Connection connection = null;
public static void main(String[] args) { if (args.length < 1) { System.out.println(“Usage: runclient MyDataDeleter keyString”); System.exit(1); }
Deleting Data from Registry
String keyStr = new String(args[0]); System.out.println(“Key string is “ + keyStr); MyDataDeleter mdd = new MyDataDeleter(); mdd.connect(); mdd.delete(keyStr); }
Connecting to the Registry Next you will write the code that enables the application to connect to the registry. The code for connecting to the registry (the connect method) is the same as the code that you wrote for MyOrganizationPublisher. For your convenience it is shown again in Listing 10.4. LISTING 10.4
The connect Method
public void connect() { String queryURL = “http://localhost:8080/registry-server/ ➥RegistryServerServlet”; String publishURL = “http://localhost:8080/registry-server/ ➥RegistryServerServlet”; String String String String
httpProxyHost = “”; httpProxyPort = “”; httpsProxyHost = “”; httpsProxyPort = “”;
Properties props = new Properties(); props.setProperty(“javax.xml.registry.queryManagerURL”, queryURL); props.setProperty(“javax.xml.registry.lifeCycleManagerURL”, publishURL); props.setProperty(“com.sun.xml.registry.http.proxyHost”, httpProxyHost);
273
274
CHAPTER 10
LISTING 10.4
JAXR Implementations
Continued
props.setProperty(“com.sun.xml.registry.http.proxyPort”, httpProxyPort); props.setProperty(“com.sun.xml.registry.https.proxyHost”, httpsProxyHost); props.setProperty(“com.sun.xml.registry.https.proxyPort”, httpsProxyPort); try { ConnectionFactory factory = ConnectionFactory.newInstance(); factory.setProperties(props); connection = factory.createConnection(); System.out.println(“Created connection to registry”); } catch (Exception e) { e.printStackTrace(); } }
Now let’s write the code for the delete method.
Deleting Data from the Registry The delete method, which contains the code for deleting data from the registry, will take as a parameter a string that contains the key for the organization that needs to be deleted. To do this, you need to do the following: 1. Get a reference to the RegistryService object. 2. From the RegistryService object, obtain instances of the BusinessLifeCycleManager and BusinessQueryManager objects. The BusinessLifeCycleManager object enables the creation of the Organization
object and its constituent objects that are submitted to the registry. The BusinessQueryManager enables you to run queries on the registry service. 3. Create a PasswordAuthentication object with the default user ID/password combination of testuser/testuser. Using the PasswordAuthentication object,
set the credentials with the registry. 4. Using the createKey method of the BusinessLifeCycleManager interface,
create a key from the specified string.
Deleting Data from Registry
5. Using the deleteOrganizations method of the BusinessLifeCycleManager
interface, delete the organization that has the specified key value. 6. Verify that the organization has been successfully deleted.
To get the instances of the interfaces, enter the following lines of code: public void delete(String keystring) { RegistryService rsvrc = null; BusinessLifeCycleManager blcmgr = null; javax.xml.registry.infomodel.Key key = null; String username = “testuser”; String password = “testuser”; try { rsvrc = connection.getRegistryService(); blcmgr = rsvrc.getBusinessLifeCycleManager(); System.out.println(“Got registry service and business life ➥cycle manager”);
Next you need to set the credentials with the registry. To do so, enter the lines of code shown here in bold: System.out.println(“Got registry service and business life cycle manager”); // Get authorization from the registry PasswordAuthentication passwdAuth = new PasswordAuthentication(username, password.toCharArray()); Set creds = new HashSet(); creds.add(passwdAuth); connection.setCredentials(creds); System.out.println(“Security credentials established”);
Now you will create the key from the string specified in the command-line argument. Once the key is obtained, you’ll invoke the deleteOrganization method to delete the organization with the specified key. To do so, enter the lines of code shown here in bold:
275
276
CHAPTER 10
JAXR Implementations
System.out.println(“Security credentials established”); key = blcmgr.createKey(keystring); String id = key.getId(); System.out.println(“Id of the organization to be deleted :” + id); Collection keys = new ArrayList(); keys.add(key); BulkResponse response = blcmgr.deleteOrganizations(keys);
Finally, you need to verify that the deletion was successful. To do this, you’ll check whether any exception was thrown when the deleteOrganizations was called. If no exception was thrown, the deletion was successful. To verify the deletion, enter the following lines of code shown here in bold: BulkResponse response = blcmgr.deleteOrganizations(keys); Collection exceptions = response.getExceptions(); if (exceptions == null) { System.out.println(“Organization deleted”); } else { Iterator excIter = exceptions.iterator(); Exception exception = null; while (excIter.hasNext()) { exception = (Exception) excIter.next(); System.err.println(“Exception on delete: “ + exception.toString()); } } } catch (Exception e) { e.printStackTrace(); } finally { // At end, close connection to registry if (connection != null) { try { connection.close(); } catch (JAXRException je) {} } } } }
Deleting Data from Registry
NOTE The code discussed here is available in the MyJAXRExample folder.
You can now compile and run the MyDataDeleter application. To compile the application, enter the following command at the command prompt: javac -classpath .;d:\jwsdp-1_0\common\lib\jaxr-ri.jar; ➥d:\jwsdp-1_0\common\lib\jaxr-api.jar;d:\jwsdp-1_0\common\lib\ ➥jaxrpc-ri.jar;d:\jwsdp-1_0\common\lib\jaxrpc-api.jar; ➥d:\jwsdp-1_0\common\lib\activation.jar;d:\jwsdp-1_0\common\lib\ ➥dom4j.jar;d:\jwsdp-1_0\common\lib\jaxm-api.jar; ➥d:\jwsdp-1_0\common\lib\jaxm-client.jar;d:\jwsdp-1_0\common\lib\log4j.jar; ➥d:\jwsdp-1_0\common\lib\mail.jar;d:\jwsdp-1_0\common\lib\xalan.jar; ➥d:\jwsdp-1_0\common\lib\xerces.jar;d:\jwsdp-1_0\common\lib\jaxp-api.jar ➥-d . MyDataDeleter.java
NOTE To build the client, you can also use the buildclient.bat batch file available in the MyJAXRExample folder. The syntax to run the buildclient.bat file is as follows: buildclient MyDataDeleter.java
Currently the registry server has data for only one company, The Great Car Parts Company, so you will run the application and delete the record for it. To run the application, enter the following at the command prompt (the key value might be different in your case. Enter the key value that you got while saving the organization information): java -DuseSOAP=true -classpath .;d:\jwsdp-1_0\common\endorsed\xalan.jar; ➥d:\jwsdp-1_0\common\endorsed\dom.jar;d:\jwsdp-1_0\common\endorsed\sax.jar; ➥d:\jwsdp-1_0\common\endorsed\xercesImpl.jar;d:\jwsdp-1_0\common\endorsed\ ➥xsltc.jar;d:\jwsdp-1_0\common\lib\jaxr-ri.jar;d:\jwsdp-1_0\common\lib\ ➥jaxr-api.jar;d:\jwsdp-1_0\common\lib\jaxrpc-ri.jar;d:\jwsdp-1_0\common\ ➥lib\jaxrpc-api.jar;d:\jwsdp-1_0\common\lib\activation.jar;d:\jwsdp-1_0\ ➥common\lib\dom4j.jar;d:\jwsdp-1_0\common\lib\jaxm-api.jar;d:\jwsdp-1_0\ ➥common\lib\jaxm-client.jar;d:\jwsdp-1_0\common\lib\log4j.jar;d:\jwsdp-1_0\ ➥common\lib\mail.jar;d:\jwsdp-1_0\common\lib\xalan.jar;d:\jwsdp-1_0\common\ ➥lib\xerces.jar;d:\jwsdp-1_0\common\lib\jaxp-api.jar;d:\jwsdp-1_0\common\ ➥lib\commons-logging.jar;d:\jwsdp-1_0\common\lib\soap.jar;d:\jwsdp-1_0\ ➥common\lib\castor-0.9.3.9-xml.jar; ➥ MyDataDeleter eeb543f8-5dee-b543-8407-30aeb62c40bd
277
278
CHAPTER 10
JAXR Implementations
NOTE To run the application, you can also use the buildclient.bat batch file available in the MyJAXRExample folder. The syntax to run the runMyDataDeleter.bat file is as follows: runMyDataDeleter MyDataDeleter eeb543f8-5dee-b543-8407-30aeb62c40bd
The output should be similar to the following: Key string is eeb543f8-5dee-b543-8407-30aeb62c40bd Created connection to registry Got registry service and business life cycle manager Security credentials established Id of the organization to be deleted :eeb543f8-5dee-b543-8407-30aeb62c40bd Organization deleted
Summary This concludes the chapter on how to create JAXR-based applications. Using the JAXR-based applications, you can connect to registries to publish, query, and manage data. This will help you use the registries in an effective manner, thereby engaging in meaningful and profitable B2B communication with other enterprises.
11 Working with JAX-RPC RPC stands for remote procedure calls. RPC is used for making procedure or function calls and receiving the responses, both over the network. During the days of procedural languages, this was the de facto method by which distributed applications communicated with each other. This often involved fairly complex socket programming to exchange data between the two remote applications. However, the growth of object-oriented programming saw a steady decline in the use of procedural languages for business applications. It became evident that using objectoriented paradigms could result in a better return on investment (in terms of scalability, development time, and so on). So, the world of business applications moved from procedural languages to object-oriented languages, such as Java. However, this led a new level of complexity in communication between distributed applications. Methods in object-oriented languages could not only return and take as parameters simple data types, but also complex objects such as vectors. With increasing complexity, it became increasingly difficult to use RPC to represent complex objects. Another complexity stemmed from the fact that more often than not, the distributed applications are on heterogeneous systems. This means that the data exchanged between two applications written in different languages must be coded so that it can be used by these applications. These complexities led to the gradual decline of RPC for low-level socket communications and the development of a plethora of alternative techniques. In the Java world, the primary new approach is Remote Method Invocation (RMI). Although useful in its own way, RMI has its own set of issues.
IN THIS CHAPTER • JAX-RPC Working Mechanism • Constituents of a JAX-RPC Server and Client • JAX-RPC Packages • The javax.xml.rpc Package • The xrpcc Tool • The Types Supported by JAX-RPC • The CarPartRequest Web Service • The CarPartRequestClient Application
280
CHAPTER 11
Working with JAX-RPC
RMI is very resource-intensive because it needs to use quite a few classes. Also, JRMP, the backbone of RMI, is poor on performance. Of course, you could go ahead and write your own remote protocol, but that is not necessarily the easiest of programming tasks. Additionally, as clients make RMI calls, sockets need to be opened and maintained—this also adds to the overhead. RMI also requires that the objects that can be called be bound to a server such as LDAP, an RMI registry, or a JNDI service. RMI is Java-only. This leads to the issue that the communicating parties have to be on Java to use RMIs, which is very difficult to ensure in a heterogeneous environment like the Internet. Finally, RMI-based applications require a lot of coding effort because there are quite a number of interfaces and classes that need to be implemented. So, while RMI solved the problem of how to exchange objects, it still had its complexities in terms of performance and simplicity of use. But how did RPC come back in fashion? The proliferation of the Internet and the emergence of XML gave rise to the possibility of using XML as an RPC mechanism. The fall of RPC was primarily for two reasons: the necessity of using socket programming to provide a transport mechanism for data, and the difficulty in representing complex objects. The ubiquity of the Internet meant that almost every imaginable system had support for HTTP, so it could be used as the transport mechanism of choice. The rise of XML ensured that it was possible to textually describe objects in a standard way that could be understood by all systems, regardless of the environments and languages. The XML-based SOAP specification provides the necessary standard mechanism by which to use RPC. In this chapter, you will learn about the JAX-RPC mechanism of using XML-RPC, as well as how to use APIs defined in the JAX-RPC specification to create a Web service and a client.
JAX-RPC Working Mechanism JAX-RPC uses SOAP and HTTP to do RPCs over the network. The SOAP specification defines the necessary structure, encoding rules, a convention for doing RPCs, and its corresponding responses. The RPCs and responses are transmitted over the network using HTTP as the primary transport mechanism. From an application developer’s point of view, an RPC-based system has two aspects: the server side (the Web service) and the client side. The Web service exposes the procedures that can be executed, and the client does the actual RPC over the network. As discussed in earlier chapters, a Web service environment is based on open standards such as SOAP, HTTP, and WSDL. It is therefore possible that a Web service or a client wasn’t developed using the Java platform. However, JAXR-RPC provides the mechanism that enables a non-Java client to connect to a Web service developed using Java platform, and vice versa. This chapter will focus on the development of a Web service and a client using JAX-RPC.
JAX-RPC Working Mechanism
Figure 11.1 represents the communication exchange between a JAX-RPC-based client and a service.
Client Program
Web Service
Stubs
Ties
JAX-RPC Runtime
FIGURE 11.1 service.
SOAP Message HTTP
JAX-RPC Runtime
Communication exchange between a JAX-RPC client program and a Web
Before we discuss the communication exchange process, you need to understand what stubs and ties are. Stubs are local objects that represent the remote procedures. Ties are classes that reside on the server and enable communication with the client. It is assumed that the client is aware of the Web service and the remote procedure that it can execute on the Web service. This is what happens: 1. The client calls the method on the stub that represents the remote procedure. 2. The stub executes the necessary routines on the JAX-RPC runtime system. 3. The runtime system converts this method call into a SOAP message and trans-
mits the message to the server as an HTTP request. 4. The server, upon receipt of the SOAP message, invokes the methods on the
JAX-RPC runtime. The JAX-RPC runtime converts the SOAP request into a method call. 5. The JAX-RPC runtime then calls the method on the tie object. 6. Finally, the tie object calls the method on the implementation of the Web
service. 7. The response to the RPC call is sent in a SOAP response message as an HTTP
response. Now let’s look at the physical implementation of a JAX-RPC-based server and client.
281
282
CHAPTER 11
Working with JAX-RPC
Constituents of a JAX-RPC Server and Client Figure 11.2 shows the physical implementation of a JAX-RPC-based system.
WSDL Document
Web Service
Container
JAX-RPC Runtime Client
SOAP HTTP
JAX-RPC Runtime
FIGURE 11.2
Physical implementation of a JAX-RPC-based system.
A JAX-RPC-based system has the following constituents: • The Web service • The container in which the Web service is located • The ties • The WSDL file • The client application • The stubs • The JAX-RPC runtime classes The Web service is represented by two files: the service definition interface, and the corresponding implementation class. The service definition interface and the implementation class are collectively known as the service endpoint. An application developer has to write the interface and the implementation class constituting the service endpoint. As you will see later, the service definition interface extends the Remote interface of the rmi package and declares the methods that can be executed remotely.
JAX-RPC Packages
The service endpoint is deployed in a container-based JAX-RPC runtime system. Typically, this is either a servlet or a stateless session bean deployed on an EJB container. In this chapter, we will use the Tomcat Web server and a servlet as the container for the service endpoint. The ties are lower-level classes that are used by the server to communicate with the client. These are created by a tool called xrpcc.bat (or xrpcc.sh, if you are a Unix user). The xrpcc tool also creates the WSDL file. A WSDL file is an XML document that describes the remote procedure call in a platform-independent way. This file enables the Web service to be accessible by clients, even if they are not on the Java platform. As an application developer, you need to run the xrpcc tool to generate the ties and the WSDL document. The WSDL document defines the parameters that a method can take, as well as the method’s return value, which is expressed as an XML schema definition (XSD) data type. The JAX-RPC mechanism provides a direct mapping of these XSD data types to Java language types. For example, if a procedure returns a String value, then the WSDL document will describe the return type as xsd:string. Similarly, if a WSDL document declares that a method can take an xsd:dateTime type as parameter, then the JAX-RPC mechanism maps that to the Calendar data type in the Web service. As a developer, you won’t need to worry about these mappings, because they are handled automatically by the xrpcc tool. The client application is the application that makes the remote procedure call on the Web service. As an application developer, you need to create the application program. The stubs are the local objects that represent the remote service. You can create the stubs by using the xrpcc tool. In some scenarios, it’s possible that the client is not aware of the signature of the remote procedure or the name of the service until runtime. To handle such cases, the client can use the dynamic invocation interface (DII). A client that uses the dynamic invocation interface does not use static stubs. A client that uses the DII is also more complex to code and implement than clients that use static stubs. The JAX-RPC runtime classes are provided with the reference implementation. Now let’s look at the packages that make up the JAX-RPC environment.
JAX-RPC Packages The JAX-RPC specification defines the following packages: • javax.xml.rpc • javax.xml.rpc.encoding
283
284
CHAPTER 11
Working with JAX-RPC
• javax.xml.rpc.handler • javax.xml.rpc.handler.soap • javax.xml.rpc.holders • javax.xml.rpc.server • javax.xml.rpc.soap Of all these packages, the one that you need to be concerned about as an application developer is the javax.xml.rpc package. It contains the interfaces that you will be using while developing the clients that use JAX-RPC mechanisms to perform remote procedure calls. The classes of the other packages are used by the JAX-RPC runtime, or by xrpcc to generate stubs, ties, and the WSDL document.
The javax.xml.rpc Package The javax.xml.rpc package contains the three interfaces, two classes, and two exceptions that you will use for developing JAX-RPC-based clients.
The javax.xml.rpc Interfaces The interfaces in the javax.xml.rpc package are as follows: • Call—The Call interface is used by a client that uses the DII to call a remote procedure. The Call interface provides a number of methods with which a client can access the remote procedures. • Service—The Service interface is essentially used as a factory to create instances of the Call interface. • Stub—The Stub interface is the base interface for the stub classes. Instances of the stub classes represent the procedures at the server. A client calls the method on a stub, and it is up to the stub to take up the remote procedure call from then on.
The javax.xml.rpc Classes The classes in the javax.xml.rpc package are as follows: • ServiceFactory—The ServiceFactory is an abstract factory class that enables you to create instances of the Service interface.
The xrpcc Tool
• NamespaceConstants—The NamespaceConstants class contains the constants that are used in JAX-RPC for namespace prefixes and URIs. For example, the NSPREFIX_SCHEMA_XSD represents the namespace prefix for the XML schema XSD. • ParameterMode—The ParameterMode class is an enumeration for parameter mode. It defines three constants that determine whether the parameter is of IN, OUT, or INOUT type. This class is used in the addParmeter(..) methods of the Call interface to determine the type of parameter that is being added.
The javax.xml.rpc Exceptions The exceptions in the javax.xml.rpc package are as follows: • JAXRPCException—The JAXRPCException is thrown when the JAX-RPC runtime fails to operate as expected. • ServiceException—The ServiceException is thrown when the methods of the Service interface or the ServiceFactory class fail to execute as expected. Now let’s take a detailed look at the xrpcc tool.
The xrpcc Tool The xrpcc tool creates the following for you: • The stubs and ties. • A server configuration file. This file is not part of the JAX-RPC specification as such, but it is used by the Tomcat Web server. • If the Web service is a JAX-RPC implementation, the xrpcc tool generates the WSDL document describing the Web service from the RMI interface. • If the Web service is not a JAX-RPC implementation, you can use the xrpcc tool to generate the RMI interfaces that your JAX-RPC client can use to connect to the Web service. The xrpcc tool will use the WSDL file to generate the RMI interfaces. To generate these files, the xrpcc tool reads a configuration XML file called config.xml. Depending on whether you start with the RMI interface or the WSDL document, the config.xml file will differ. Let’s look at both of the syntaxes. Later on in the chapter, you will see an actual implementation of the config.xml file for the sample CarPartRequest Web service that you will create.
285
286
CHAPTER 11
Working with JAX-RPC
The config.xml File Syntax When Starting with RMI Interfaces When starting with RMI interfaces, the config.xml file should have the following syntax:
This is the XML comment line. The comment starts with the tag. The XML processor ignores all text within the comment tag. However, it is important to remember that the comments’ start and end tags for XML comments should be entered exactly as shown here. If there is a deviation, such as a space between < and !-- , the XML parser might treat the comment as content markup, and you might have a rather unexpected outcome from the XML parsing. Another important point to remember is that you should not use the -string in the comment. Other than these two limitations, you are pretty much free to use anything inside the comments.
Processing Instructions
Comments can be placed anywhere outside of a markup. So, you can do the following: Wheel Set 1
However, doing this will land you in trouble:
367
368
APPENDIX B
LISTING B.2
XML: A Quick Tour
Continued
]> .......
The Document Type Declaration The document type declaration is the XML statement that declares the type of XML document and also identifies the DTD as being SYSTEM or PUBLIC. The document type declaration is as follows:
Element Content Model An element content model is a description of how the subelements might appear under the current element. The model describes the order of the elements and how many times they can or will occur. The general form for an element that has a content model is as follows:
Additionally, you can also specify element occurrence indicators. An element occurrence indicator specifies how many times an element or a group of elements can appear under an element. There are three element occurrence indicators: +, ?, and *. The ? occurrence indicator specifies that an element or group of elements can occur once at most under an element. For example, consider the following element declaration:
369
370
APPENDIX B
XML: A Quick Tour
This element declaration implies that only the following two pieces of XML will be valid: some data another data
and another data
The + occurrence indicator specifies that an element or group of elements must occur one or more times. The * occurrence indicator specifies that an element or group of elements must occur zero or any number of times in an XML document. Let’s see how these rules are applied for the DTD for the CarParts.xml file. The carparts element is the root element of the XML document and all other elements must come under it. So, the corresponding element declaration is as follows:
Next, the engines, carbodies, wheels, and carstereos elements can contain subelements, and each of these subelements must occur one or more times. Therefore, the element declarations are as follows: carbodies (carbody+)> wheels (wheel+)> carstereos (carstereo+)>
Character Data The last type of content that an element can have is text. To specify that an element can have only text, you use the #PCDATA keyword. The construct is as follows:
Coming back to our DTD, we know that the hubcaps element can have only text as its content. So, the element declaration for hubcaps is as follows:
We will conclude our discussion on DTD with a brief overview of how to declare the
Declaring Attributes
attributes for the elements.
Declaring Attributes Attributes are a mechanism with which you can provide further information about an element. You declare the attributes for an element in a DTD after declaring the element. The attribute declaration is of the following form:
where attribute_definition takes the following form: attribute_name attribute_type [default_declaration]
The attribute definition provides the following information: • The name of the attribute • The type of the attribute • Default value for the attribute, or whether the attribute is required
Attribute Name The name of the attribute is self-explanatory. Attribute names can be anything as long as they follow the naming rules that were described in the element declaration section of the chapter.
Attribute Type The type of an attribute can be one of the following three types: • A string • A tokenized attribute • An enumerated attribute
String Attribute Type An attribute of type string means that the attribute can take a string of characters as its value. To declare an attribute of type string, you need to do the following:
The CDATA keyword specifies that the attribute can take only string values. It is
371
372
APPENDIX B
XML: A Quick Tour
important to remember that the attribute can also take an internal entity reference. This is possible because the XML parser automatically replaces an entity reference with its replacement text while parsing the XML file. In our DTD for the CarParts.xml file, the supplier element has name and URL attributes that can take string values. It is declared as follows:
The entry in the CarParts.xml file for the supplier element is as follows:
Tokenized Attribute Types A tokenized attribute type can have one of the following values: ID, IDREF, IDREFS, ENTITY, ENTITIES, NMTOKEN, or NMTOKENS. ID
This attribute acts as the identifier for an element. The ID attribute value has to be unique for each element in a document. For example, consider the engine element that as an attribute called ID, which is declared as follows:
The corresponding entry in the XML file is as follows:
IDREF
The value of an attribute of type IDREF is a pointer to the value of an ID type attribute value existing in the XML document. For example, suppose the CarParts.xml file had another element called engineByOtherName, with an attribute called idref of type IDREF; the declaration would have been of the following form:
and implemented as
IDREFS
The value of an attribute of type IDREFS is a collection of IDREF type values.
Declaring Attributes
ENTITY
The attributes of type ENTITY are used to refer to a binary external entity defined in the DTD. This attribute type is often used to refer to graphic images in an XML document. The following is an example of how you can use an ENTITY type attribute. Suppose you have an XML document that describes furniture. Now you want to add an image called tableImage.gif to your XML file. The place where you want to add it is to the tableImage element. To do so, you need to declare the tableImage.gif as an external entity, say TableImage, by doing the following:
Next, specify the tableImage element as an empty element with an attribute called picture, of the ENTITY type, by adding the following:
Then in the actual XML file, you will enter the value of the picture attribute as &tableImage;. The code snippet is as follows:
ENTITIES
The value of an attribute of the ENTITIES type is a collection of ENTITY type values separated from each other by a space. NMTOKEN
The value of an attribute of the NMTOKEN type is a string. NMTOKENS
The value of an attribute of the NMTOKENS type is a collection of NMTOKEN-type values separated from each other by spaces. Enumerated Attribute Types An attribute that is of the enumerated type can take only one of the values that was declared in the DTD. For example, in the DTD for the CarParts.xml file, the capacity attribute of the engine element is an enumerated type attribute because the only values it can take are 1000, 2000, or 2500. The way to declare it is as follows:
The corresponding entry in the CarParts.xml file is as follows:
373
374
APPENDIX B
XML: A Quick Tour
Default Attribute Values Finally, let’s look at the default values that an attribute can take. Default values are specified through the attribute declaration to specify the action that an XML parser will take when it does not find an attribute in an element. Default values are specified through one of the three keywords: • #REQUIRED—Implies that the attribute value must be specified. If the XML processor does not find the attribute, it will raise an error. • #IMPLIED—Means that the XML parser will inform the application that no value was specified for the attribute, and it will be an application code that has to determine what to do about it. • #FIXED—Means that the value specified for the attribute must completely match the value specified in the attribute declaration. A mismatch will cause the XML parser to raise an error.
Index
Symbols & (ampersand) predefined entity, 364 XML (Extensible Markup Language) documents, 80 * (asterisk) context node, 177 element occurrence indicator, 369-370 XPath operator, 178 @* (context node), 177 . (dot), one (.) or two (..), 177 “ (double quotation mark), predefined entity, 364 / (forward slash), 177 . (full stop), 363 - (hyphen), 363 - (minus sign), XPath operator, 178 | (pipe), XPath operator, 178 + (plus sign) element occurrence indicator, 369-370 XPath operator, 178 ? (question mark), element occurrence indicator, 369 ; (semicolon), 363 ‘ (single quotation mark), predefined entity, 364 - - (double hyphen) string, 360 < (left angle bracket) XML (Extensible Markup Language), 37, 45, 52, 80, 363-364 XPath operator, 178 > (right angle bracket) character, 174 predefined entity, 364
>
376
XML (Extensible Markup Language), 52 80, 363 XPath operator, 178
JAXB (Java Architecture for XML Binding), 7-10
= (XPath operator), 178
JAXP (Java API for XML Processing), 7-9
!= (XPath operator), 178
JAXR (Java API for XML Registries), 7, 11-13
= (XPath operator), 178
parser-specific API set, 8 Publish, 28-29, 214 SAX (Simple API for XML), 8, 37 StAX (Streaming API for XML), 349
A
UDDI (Universal Description, Discovery and Integration), 28-29
accessing DOM (Document Object Model) parser, 127 DTDs (Document Type Definitions) information, 131-132 elements
XML (Extensible Markup Language), 7, 38, 348 XSLT (XSL Transformations), SAX-specific, 167 appendChild( ) method, 142 applications
attributes, 58, 137-140
BestDealsonAccessoriesRegistryPublisher.java, 303-309
nodes, 137-141
CarPartRequestClient, 296-298
registries with JAXR (Java API for XML Registries), 12
CarPartRequestClient.java (code), 333-342
XML (Extensible Markup Language) data, 131-141
client, JAX-RPC systems, 283
classes, supported by JAX-RPC, 288-289
acknowledgments, asynchronous updates (JAXM message exchanges), 197
CoolAccessoriesRegistryPublisher.java, 303, 309-314
active states (JAXM message providers), 203
creating
ampersand (&) predefined entity, 364 XML (Extensible Markup Language) documents, 80
for SAX (Simple API for XML), 110-115 for Web service case study, 303 DOM (Document Object Model) CarParts.dtd file (code), 124-125
and (XPath operator), 178
CarParts.xml file (code), 123-124
angle brackets for XML documents, left (), 80
creating, 123, 160-163
APIs (Application Programming Interfaces)
JAXP (Java API for XML Processing) classes, importing, 126
DOM (Document Object Model), 37 downloading, 46
error handling, 127-131
MyDOMHandler class declaration, creating, 126-127
ebXML (Electronic Business using Extensible Markup Language) CPP/A (Collaboration Protocol Profile/Agreement) for Java, 348
lexical events, handling, 80
Inquiry, 28-29, 214
Locator object, passing, 76
Java
MyDataDeleter, 272-273, 277
WSDL (Web Services Description Language), 349 XML (Extensible Markup Language) Pack, 7 JAX-RPC (Java API for XML-based RPC), 7, 13
parsers, 125-127
MyDataDeleter.java. creating, 271 MyDOMHandler, output (code), 136-137, 143-151 MyDOMTransformer, 160-166
attributes
MyJAXMClient, output (code), 215-216 MyOrganizationPublisher, 261-262 MyOrganizationPublisher.java, 250-251 MyRegistryQuery, 269-270 MyRegistryQuery.java, creating, 263 MySAXTransformer, output (code), 171-173 MyXMLHandler attributes (code), 59 characters( ) method (code), 64-66 DTDs (Document Type Definitions), code, 69-70
WeSupplyPartsRegistryPublisher.java, 303, 319-324 XML (Extensible Markup Language), APIs for developing, 7 architectures JAXR (Java API for XML Registries), 239-241 Web services, 17-19 arguments, PUBLIC or SYSTEM, 365 Association class (ebXML information model), 237 Association interface, 242 asterisk (*)
enhancing, 76
context node, 177
EntityResolver interface (code), 95-97
element occurrence indicator, 369-370
LexicalHandler interface (code), 82-83, 86-89
XPath operator, 178
Locator object (code), 77-80 namespaces (code), 99-102
asynchronous (JAXM message exchanges) inquiry, 196-197 updates with acknowledgments, 197
output, 53
AttachmentPart class (JAXM), 206
parser in validating mode (code), 71-73
attachments
processing instructions (code), 61-62 Xerces parser, 42 MyXSLTTransformer, 187-191 procurement for Great Car Parts Company, 34 SAX-parsing attributes, handling, 57-59 CarParts.xml file, creating, 48-49 characters, handling, 62-66 ContentHandler events, handling, 51-53 creating, 48 DefaultHandler classes, extending, 50 DTDs (Document Type Definitions), handling, 67-71
ebXML (Electronic Business using Extensible Markup Language) messages, 222-223 SOAP (Simple Object Access Protocol) messages, 200-201 Attachments Note (SOAP) Web site, 19 Attr interface, 120 node (DOM), 119 attributes creating, 145-146, 358 declaring, 371 default values, 374 definitions, 371
entities, handling, 67-71
and element nodes, accessing, 137-140
errors, handling, 53-57
elements, 57-58
JAXP (Java API for XML Processing) classes, importing, 50
ENTITIES, 373
parser, 49-51
enumerated attribute types, 373
processing instructions, handling, 59-62
handling, 57-59
validating parsers, 71-73
ID, 372
TheGreatPartsSupplierRegistryPublisher.java, 303, 314-319
377
ENTITY, 373
IDREF, 372 IDREFS, 372
How can we make this index more useful? Email us at
[email protected]
378
attributes
names, 371
blocks, try-catch, adding to parse( ) method (code), 55-56
NMTOKEN, 373
body element, SOAPBody, 212
NMTOKENS, 373
tag, 6
Node object, 133
books, Sams Teach Yourself XML in 24 Hours, 358
nodes (XPath), 175
Boolean functions (XPath), 181
string attribute type, 371-372
boolean(object) function, 181
tokenized attribute types, 372-373
brackets (angle) for XML documents, left (), 80
MyXMLHandler output (code), 59
types, 371-373 XML (Extensible Markup Language), 363 Attributes interface (org.sml.sax package), 39 object, 57 AttributesImpl class (org.xml.sax.helpers package), 40 AuditableEvent
buildclient.bat file, syntax, 270, 277, 297 building MyOrganizationPublisher application, 262 queries, 266 BulkResponse interface, 245 object, 267
class (ebXML information model), 238
bulletin boards, registries, 234
interface, 242
business-to-business (B2B) communication, 15-17, 233
awareness MyXMLHandler namespace, making aware (code), 99-100 parser namespaces, making aware, 99
businessEntity element (UDDI), 27, 236 businesses Best Deals on Accessories Inc., CarPartRequestImpl.java file (code), 326-327 Cool Accessories Inc. CarPartRequest Config.properties file (code), 329-333
B B2B (business-to-business) communication, 15-17, 233 Best Deals on Accessories Inc., CarPartRequestImpl.java file (code), 326-327
CarPartRequestImpl.java file (code), 328329 I Need Car Parts Inc., 301 The Great Parts Supplier Inc.
BestDealsonAccessories.war file, creating, 328
CarPartRequest Config.properties file (code), 331
BestDealsonAccessoriesRegistryPublisher.java application (code), 303-309
CarPartRequestImpl.java file (code), 330-331
binding compilers (JAXB), 345-346
We Supply Parts Inc., CarPartRequestImpl.java file (code), 331-333
element (WSDL), 32
BusinessLifecycleManager interface, 245
language (JAXB), 347
BusinessQueryManager interface, 245
runtime frameworks (JAXB), 346-347
businessService element (UDDI), 27, 236
XML (Extensible Markup Language)
businessTemplate element (UDDI), 27
Java architecture, 343-344
businesstModel element (UDDI), 28
schema, 9
buyers, registries, 234-235
bindingTemplate element (UDDI information model), 236
classes
C
379
case study for Web services applications, creating, 303
Call interface (java.xml.rpc package), 284 call( ) method, 214 callback methods, 37 characters( ), 63 implementing (code), 113-114 overriding for SAX (Simple API for XML) applications, 113-115 capability-specific interface, 240
BestDealsonAccessoriesRegistryPublisher.java application, 303-309 CoolAccessoriesRegistryPublisher.java application, 303, 309-314 description, 301-302 development order, 302 JWSDP (Java Web Services Developer Pack) Registry Server, 302
CapabilityProfile interface, 245
TheGreatPartsSupplierRegistryPublisher.java application, 303, 314-319
CarPartRequest Config.properties file (code), 329-333
WeSupplyPartsRegistryPublisher.java application, 303, 319-324
CarPartRequest Web service, 289-296
CataloguedObject interface, 245
CarPartRequestClient application, 296-298
CDATA
CarPartRequestClient.java application (code), 333-342 CarPartRequestImpl.java file (code), 326-333 CarPartRequest_Config.properties file, modifying serviceName entry, 325 /carparts path, 177
keyword, 371 section (XML), 80, 366 CDATASection interface, 120 node (DOM), 119
CarParts.dtd file (code), 124-125
Ceiling(number) function, 182
CarParts.xml file
Chapter 11 code, modifying, 325-326
code, 117-118, 123-124, 358-359
CharacterData interface, 120
creating, 48-49
characters
data, adding to tags (code), 62-63
> (right angle bracket), 174
DOCTYPE, code to add, 90-91
handling, 62-66
DOM (Document Object Model), 118
references (XML), 363
DTDs (Document Type Definitions), code, 67-69, 366-368
characters( ) callback method, 63
element attributes, adding (code), 57
charts, node information, 133
errors (code), 54
classes
modifying, 90-91
characters( ) method, 37, 64-66, 107
namespaces, introducing (code), 99
application, supported by JAX-RPC (Java API for XML-based RPC), 288-289
processing instructions (code), 60
Association (ebXML information model), 237
updating, 81-83
AttachmentPart (JAXM), 206
/carparts/carbody//supplier path, 177 /carparts/supplier[3]/suppliername[1] (element node), 178
AttributesImpl (org.xml.sax.helpers package), 40 AuditableEvent (ebXML information model), 238 Classification (ebXML information model), 238
How can we make this index more useful? Email us at
[email protected]
380
classes
ClassificationNode (ebXML information model), 238
MimeHeader (JAXM), 206
ClassificationScheme (ebXML information model), 238
MyDOMHandler, creating declarations, 126-127
DefaultHandler, 40, 44-45, 50, 111
MyErrorHandler, 129
DocumentBuilder, 122
NamespaceConstants (java.xml.rpc package), 285
DocumentBuilderFactory, 123 DOMResult, 157
MimeHeaders (JAXM), 206
EbXMLMessageImpl, 220
NamespaceSupport (org.xml.sax.helpers package), 40
EmailAddress (ebXML information model), 238
org.xml.sax.InputSource, 168
Endpoint (JAXM), 204
Organization (ebXML information model), 238
ExternalIdentifier (ebXML information model), 237
OutputKeys, 156
ExternalLink (ebXML information model), 238
ParserAdapter (org.xml.sax.helpers package), 40
helper, org.xml.sax.helpers package, 40
PostalAddress (ebXML information model), 238
importing
ParameterMode (java.xml.rpc package), 285
to MyJAXMClientWithProvider servlet, 218
ProviderConnectionFactory (JAXM), 205
for publishing data to registries, 251-252
RegistryObject (ebXML information model), 237
to standalone client implementations, 210-211 Java, not supported by JAX-RPC (Java API for XML-based RPC), 289
RegistryPackage (ebXML information model), 238 SAXParser, 41-44
java.xml.rpc package, 284
SAXParserFactory, 42-44
javax.net.* package, 251
SAXResult, 158
javax.security.* package, 251
SAXSource, 158
javax.util.* package, 251
SAXTranformerFactory, 158
javax.xml.messaging.URLEndpoint, 211
Service (ebXML information model), 238
javax.xml.parsers package, 41, 122
service definition interface implementation, creating, 291
javax.xml.registry package, 246 javax.xml.registry.* package, 251
ServiceBinding (ebXML information model), 238
javax.xml.registry.infomodel.* package, 251
ServiceFactory (java.xml.rpc package), 284
javax.xml.transform package (XSLT), 155-156
Slot (ebXML information model), 237
javax.xml.transform.*, 168
SOAPConnection (JAXM), 206
javax.xml.transform.dom package (XSLT), 157
SOAPConnectionFactory, 210-211
javax.xml.transform.dom.SAXSource, 168
SOAPElementFactory (JAXM), 206
javax.xml.transform.sax package (XSLT), 158
SOAPMessage (JAXM), 206
javax.xml.transform.stream package (XSLT), 158
SOAPPart (JAXM), 206
JAXMServlet (JAXM), 204
SpecificationLink (ebXML information model), 239
JAXP (Java API for XML Processing), importing, 50, 126, 159-160, 167-168
StreamResult, 158
LocatorImpl (org.xml.sax.helpers package), 40 MessageFactory, 206, 212
StreamSource, 158 StringReader, importing, 92 Transformer, 156
code
381
TransformerConfigurationException, 156
callback methods, implementing, 113-114
TransformerException, 156
CarPartRequest Config.properties file, 329-333
TransformerFactory, 156
CarPartRequestClient.java application, 333-342
TransformerFactoryConfigurationError, 156
CarPartRequestImpl.java file, 326-333
UrlEndpoint (JAXM), 205
CarParts.dtd file, 124-125
User (ebXML information model), 238
CarParts.xml file, 117-118, 123-124, 358-359
XMLFilterImpl (org.xml.sax.helpers package), 40
data, adding to tags, 62-63
XMLReaderAdapter (org.xml.sax.helpers package), 40
DTDs (Document Type Definitions), 67-69, 366-368
XMLReaderFactory (org.xml.sax.helpers package), 40
element attributes, adding, 57
Classification class (ebXML information model), 238 interface, 242 ClassificationNode class (ebXML information model), 238 ClassificationScheme
DOCTYPE, adding, 90-91
errors, 54 processing instructions, 60 Chapter 11, modifying, 325-326 characters( ) method, implementing, 63-64 connect method, 254-255, 264-265, 273-274 ContentHandler
class (ebXML information model), 238
events, MyXMLHandler output, 53
interface, 242
methods, overriding, 51-52
classifying organizations with NAICS classification scheme (code), 258-259
CoolAccessoriesRegistryPublisher.java application, 309-314
classpaths, JAR files availability, 47
credentials, setting in registries, 275
clients
data deletions, verifying, 276
applications, JAX-RPC (Java API for XML-based RPC) systems, 283
element attributes, accessing, 58
implementations
ErrorHandler interface, implementing, 54-55
EntityResolver interface, 93-97
creating, 209
exception-handling, 189-190
messaging providers, 217-230
index.html Web form, 225-226
standalone, 209-217
LexicalHandler interface, 81-89
JAX-RPC (Java API for XML-based RPC) systems, DII (dynamic invocation interface), 283 JAXM (Java API for XML Messaging), 11, 195-202, 228-230 JAXR (Java API for XML Registries), 240 MyJAXMClient, 209, 215-216 MyJAXMClientWithProvider output (code), 229-231 programs (JAX-RPC) and Web services, communicating, 281 code. See also syntax BestDealsonAccessoriesRegistryPublisher.java application, 303-309
Locator object elements, displaying, 76-77 MyXMLHandler application output, 77-80 MyDOMHandler application, output, 136-137, 143-151 MyDOMTransformer application, 160-166 MyJAXMClient application, output, 215-216 MyJAXMClientWithProvider output, 229-230 MyOrganizationPublisher application, compiling, 261 MyRegistryQuery application, 269-270 MySAXEventGeneratorReader output, 114-115
How can we make this index more useful? Email us at
[email protected]
382
code
MySAXTransformer application, output, 171-173
column numbers (XML documents), 75
MyXMLHandler output
com.sun.xml.registry.http.proxyPort property, 253
attributes, 59 characters( ) method, 64-66 DTDs (Document Type Definitions), 69-70
com.sun.xml.registry.http.proxyHost property, 253 com.sun.xml.registry.https.proxyHost property, 253
EntityResolver interface (code), 95-97
com.sun.xml.registry.https.proxyPort property, 253
LexicalHandler interface (code), 82-83
commands
LexicalHandler methods (code), 86-89
, 187
Locator object (code), 77
, 185
namespace processing (code), 101-102 parser in validating mode, 71-73 processing instructions, 61-62 MyXSLTTransformer application, output, 190-191
, 185 Comment interface, 120 node (DOM), 119 comments
NAICS classification scheme for organizations, 258-259
- - (double hyphen) string, 360
namespaces, 99-102
nodes (XPath), 176
Organization object, 257-261 organizations, getting details, 267-269 parse( ) method implementing, 105-107 invoking, 112-113 try-catch block, adding, 55-56 plumbing, writing
lines (XML), 360 XML (Extensible Markup Language), 360-361 communication B2B (business-to-business), 15-17, 233 client programs (JAX-RPC) and Web services, 281 companies
to delete data from registries, 272-273
Best Deals on Accessories Inc., CarPartRequestImpl.java file (code), 326-327
to publish data to registries, 252
Cool Accessories Inc.
to query data from registries, 263-264 processingInstruction( ) method, implementing, 60-61
CarPartRequest Config.properties file (code), 329-333 CarPartRequestImpl.java file (code), 328-329
SAX (Simple API for XML) parser, setting up, 50-51
I Need Car Parts Inc., 301
SOAP (Simple Object Access Protocol), 21-22
The Great Parts Supplier Inc.
TheGreatPartsSupplierRegistryPublisher.java application, 314-319
CarPartRequest Config.properties file (code), 331
variables, instantiating, 104-105
CarPartRequestImpl.java file (code), 330-331
web.xml file, 226-227 WeSupplyPartsRegistryPublisher.java application, 319-324 WSDL (Web Services Description Language) documents, 29-30 XMLReader methods, implementing, 108-110
We Supply Parts Inc., CarPartRequestImpl.java file (code), 331-333 comparing Java XML Pack and JSWDP (Java Web Services Developer Pack), 354
creating
SAX (Simple API for XML)
context node
1.0 and 2.0, 41
@*, 177
and DOM (Document Object Model), 173
*/engines, 178
URNs (uniform resource names) and URLs (uniform resource locators), 76 compilers, binding (JAXB), 345-346 compiling
383
engine[5] [@type=”Alpha37”], 178 engine[@type=”Alpha37”], 178 engine[@type=”Alpha37”][5], 178 converting
MyDataDeleter application, 277 MyOrganizationPublisher application (code), 261 MyRegistryQuery application (code), 269-270 concat(string, string,…) function, 180 Concept interface, 243 config.xml file
file objects to InputSource objects, 111-112 XML schema/DTDs to Java objects, 344-347 Cool Accessories Inc. CarPartRequest Config.properties file (code), 329-333 CarPartRequestImpl.java file (code), 328-329
creating, 291-293
CoolAccessoriesRegistryPublisher.java application, 303, 309-314
syntax, starting, 286-287
count(node-set function), 179
configuring XMLReader, 84-85
createConnection( ) method, 210, 219
connect method (code), 254-255, 264-265, 273-274
createElement( ) method, 142
connecting to registries, data
createTextNode( ) method, 147
deleting, 273-274 publishing, 252-255 querying, 264-265 Connection interface, 246 connections
createMessage( ) method, 212, 220 creating applications for SAX (Simple API for XML), 110-115 for Web service case study, 303 attributes, 145-146
MyJAXMClientWithProvider servlet, 218-219
BestDealsonAccessories.war, 328
SOAPConnection object, 211
CarPartRequest Web service, 289-290
standalone client implementations, 211
CarParts.xml file, 48-49
constituents, JAX-RPC (Java API for XML-based RPC) systems, 282 constructors, Party object, 222 containers, JAX-RPC (Java API for XML-based RPC) systems, 283
client implementations, 209 config.xml file, 291-293 DOM (Document Object Model) applications, 123-131, 160-163
contains(string, string) function, 180
ebXML (Electronic Business using Extensible Markup Language) messages, 219-223
content trees, validation, 347
element nodes, 142-144
ContentHandler
InputSource object, 168
events, handling, 51-53 interface, 39, 45, 111
instances of SAX (Simple API for XML) parser, 111
methods, overriding (code), 51-52
MyDataDeleter.java application, 271 MyDOMHandler class declaration, 126-127
How can we make this index more useful? Email us at
[email protected]
384
creating
MyJAXMClientWithProvider servlet, 217-224 MyOrganizationPublisher.java application, 251 MyRegistryQuery.java application, 263
D data
Organization object (code), 257
adding to tags in CarParts.xml file (code), 62-63
sampledoc.txt file, 227-228
character, 370
SampleMailMessage.txt file, 102-103
deleting
MyXSLTTransformer application, 187-191
SAX (Simple API for XML) parser, 103-110 SAX-parsing applications
from MyDataDeleter application, 272-273 from registries, 271-278
attributes, handling, 57-59
deletions, verifying (code), 276
CarParts.xml file, creating, 48-49
encoding rules (SOAP), 19
characters, handling, 62-66
managing with DOM (Document Object Model), 141-152
ContentHandler events, handling, 51-53 DefaultHandler classes, extending, 50 DTDs (Document Type Definitions), handling, 67-71 entities, handling, 67-71 errors, handling, 53-57 JAXP (Java API for XML Processing) classes, importing, 50 processing instructions, handling, 59-62 SAX (Simple API for XML) parser, 49-51 validating parsers, 71-73 service definition interface, 290-291 SOAP (Simple Object Access Protocol) messages for standalone client implementations, 212 standalone client implementations, 210 tag attributes, 358 text nodes, 147-149 URLEndpoint object for standalone client implementations, 214 WAR files, 328 Web forms, 224-226
normalized, 174 portability in XML (Extensible Markup Language), 6 publishing to registries, 250-262 querying from registries, 263-271 registries, 234 structures, UDDI (Universal Description, Discovery and Integration), 26-27 types, XML (Java mapping), 346 XML (Extensible Markup Language) DOM (Document Object Model), 131 DTDs (Document Type Definitions) information, accessing, 131-132 element node types, 133-137 element nodes and attributes, accessing, 137-140 element text nodes, accessing, 140-141 databases, registries, 234 declarations DTDs (Document Type Definitions), 360
web.xml file, 226-227, 293-294
CarParts.xml file (code), 67-69, 90-91, 366-368
XSLT (XSL Transformations) stylesheet, 184-187
definition, 67
credentials, setting in registries, 256-257, 275 customizing external entity resolution, 89-97
EntityResolver method, 95 handling, 67-71 information, accessing, 131-132 MyXMLHandler output (code), 69-73 resolveEntity( ) method, 94 XML (Extensible Markup Language), 9, 344-347, 366-368
Document Type Definitions
lines (XML), 360
interfaces, 29
MyDOMHandler class, creating, 126-127 DeclarativeQueryManager interface, 246
Java APIs (Application Programming Interfaces), 349
declaring
methods, 29
attributes, 371-374
operations, 29
elements, 369-370
ports, 29
DeclHandler interface (org.xml.sax.ext package), 40
request messages, 31-33
default attribute values, 374
SOAP (Simple Object Access Protocol) elements, 31-33
DefaultHandler class, 44-45 extending, 50, 111
385
response messages, 31-33
Web services, 29
interfaces, 44
Detail interface (JAXM), 205
org.xml.sax.helpers package, 40
DetailEntry interface (JAXM), 205
defining request or response messages, 31-33
details of organizations, getting (code), 267-269
definitions
dictionaries, samsdictionary Web site (turbo engine), 76
attributes, 371 definitions element (WSDL), 30
Digital XML APIs (Encryption or Signature), 348
DTDs (Document Type Definitions), 67
DII (dynamic invocation interface), JAX-RPC systems, 283
profiles, 11
directories, CarPartRequest Web service, 295
Web services, 15
displaying namespaces (code), 100-101
delete_binding( ) method, 28
div (XPath operator), 178
delete method, 271, 274-275 delete_xxxx functions, 28
DOCTYPE, adding to CarParts.xml file (code), 90-91
DeleteException exception, 247
doctype nodes, 118
deleteOrganization method, 275
Document interface, 120
deleting data from MyDataDeleter application, 272-273
node (DOM), 119
nodes, 151-152
object, 133
from registries, 271-278
Document Object Model. See DOM
verifying (code), 276
Document Type Definitions (DTDs), 360 CarParts.xml file (code), 67-69, 90-91, 366-368
deploying CarPartRequest Web service, 294-296
definition, 67
JAXM (Java API for XML Messaging) clients, 228-230
EntityResolver method, 95
Web services, 301
information, accessing, 131-132
handling, 67-71
descriptions, Web service case study, 301-302
MyXMLHandler output (code), 69-73
descriptive language, WSDL (Web Services Description Language)
resolveEntity( ) method, 94
documents, 29-32, 287 files, JAX-RPC (Java API for XML-based RPC) systems, 283
XML (Extensible Markup Language), 366-368 documents, 9 schema/DTDs, converting to Java objects, 344-347
How can we make this index more useful? Email us at
[email protected]
386
DocumentBuilder class
DocumentBuilder class, 122
Entity node, 119
DocumentBuilderFactory class, 123
EntityReference node, 119
DocumentFragment
error handling, 127-131
interface, 121
JAXP (Java API for XML Processing), 8, 117-126
node (DOM), 119
JDOM 1.0, Web site, 347
DocumentType node (DOM), 119
level 2 specifications, Web site, 120
documents
MyDOMHandler class declaration, creating, 126-127
element node, 118 locations, identifying, 75-80 order, 175 public identifiers, URNs (uniform resource names), 75
MyDOMTransformer application (code), 160-166 node types, 118-110 Notation node, 119
serial processing, 38
parsers, 8, 38, 125-127
standalone, 360
ProcessingInstruction node, 119
stylesheets, 154
and SAX (Simple API for XML), comparing, 173
system identifiers, URLs (uniform resource locators), 75 WSDL (Web Services Description Language), 29-32, 287 XML (Extensible Markup Language), 358-359
Text node, 119 XML (Extensible Markup Language) data, 131-141 XSLT (XSL Transformations), 159-167
CDATA section, 80
dom.jar file, 46
DTDs (Document Type Definitions), 9
DOMException, 122
marshaling, 346
DOMImplementation interface, 121
numbers (column and line), 75
DOMLocator interface, 157
SAX (Simple APIs for XML) parsers, 37-38
DOMResult class, 157
unmarshaling, 346
doPost( ) method, 218
XSLT (XSL Transformations), 38, 153-155
dots, one (.) or two (..), 177
DocumentType interface, 121
double quotation mark (“), predefined entity, 364
DOM (Document Object Model)
downloading
applications
APIs (Application Programming Interfaces), 46
CarParts.dtd file (code), 124-125
Java XML Pack, 354
CarParts.xml file (code), 123-124
JAXM (Java API for XML Messaging) Provider Administration Tool, 222
creating, 123, 160-163 Attr node, 119 CarParts.xml file, 118 CDATASection node, 119
JAXP (Java API for XML Processing), 46 JDK (Java Development Kit), 353 JWSDP (Java Web Services Developer Pack), 46, 354-355
Comment node, 119
DTDHandler interface, 39, 45-46
data management, 141-152
DTDs (Document Type Definitions), 360
Document node, 119
CarParts.xml file (code), 67-69, 90-91, 366-368
DocumentFragment node, 119
definition, 67
DocumentType node, 119
EntityResolver method, 95
Element node, 119
handling, 67-71
elements
information, accessing, 131-132
businessService (UDDI), 27, 236
MyXMLHandler output (code), 69-73
businessTemplate (UDDI), 27
resolveEntity( ) method, 94
businesstModel (UDDI), 28
XML (Extensible Markup Language), 366-368
character data, 370
documents, 9
declaring, 369
schema/DTDs, converting to Java objects, 344-347
definitions (WSDL), 30
dynamic invocation interface (DII), JAX-RPC systems, 283
387
document element node, 118 element content model, 369-370 empty, 362 engines, 362 envelope, SOAPEnvelope, 212
E
Envelope (SOAP), 23-24 Header (SOAP), 24-25, 212
ebXML (Electronic Business using Extensible Markup Language) CPP/A (Collaboration Protocol Profile/Agreement) APIs for Java, 348
hubcaps, 362 input (WSDL), 32 JAXM (Java API for XML Messaging), 201
information model, 237-238
message (WSDL), 32
messages, 219-224
nodes
providers, endpoint mappings, 222
attributes, accessing, 137-140
SOAP (Simple Object Access Protocol), 11
/carparts/supplier[3]/suppliername[1], 178
Web site, 12
engine[@id and @type], 178
EbXMLMessageImpl class, 220
//engines/engine[last( )], 178
eCo Framework, Web site, 12
engines[enginename = “Engine 1”], 178
EDI (Electronic Data Interchange), 5-6
engines[enginename], 178
Electronic Business using Extensible Markup Language. See ebXML
supplier[1], 177
electronic white, yellow, green pages (registries), 234
XPath, 175
Element
types, 133-137 occurrence indicator, 369 operation (WSDL), 32-33
interface, 121 node (DOM), 119 elements
output (WSDL), 32 part (WSDL), 32 port (WSDL), 32
* (asterisk), occurrence indicator, 369-370 + (plus sign), occurrence indicator, 369-370 ? (question mark), occurrence indicator, 369 attributes, 57-58 binding (WSDL), 32
portType (WSDL), 32 publisherAssertion (UDDI), 28, 237 root (XML), 361 service (WSDL), 31
bindingTemplate (UDDI), 236
SOAP (Simple Object Access Protocol) extensions, 31
body, SOAPBody (SOAPMessage object), 212
soap:binding, 33
businessEntity (UDDI), 27, 236
How can we make this index more useful? Email us at
[email protected]
388
elements
soap:body, 33 text nodes, accessing, 140-141
internal, 364-365 predefined, 364
tModel (UDDI information model), 237
ENTITIES attribute, 373
typeMappingRegistry, 287
Entity
WSDL (Web Services Description Language) SOAP (Simple Object Access Protocol), 31 XML (Extensible Markup Language), 362-363 email, SampleMailMessage.txt file, 102-103 EmailAddress
interface, 121 node, 119 ENTITY attribute, 373 entity references external entities, 365
class (ebXML information model), 238
internal entities, 364-365
interface, 243
predefined entities, 364
empty element, 362 encapsulation, org.xml.sax.InputSource class, 168
XML (Extensible Markup Language), 363-364 EntityReference
encoding data, rules (SOAP), 19
interface, 121
encryption, XML
node, 119
Digital Encryption APIs, 348 Transactioning API for Java (JAXTX), 348 end-points, JAXM (Java API for XML Messaging), 195 endElement( ) method, 37, 52, 100 ending and starting tags, matching, 362 Endpoint class (JAXM), 204 endpoints mappings for ebXML (Electronic Business using Extensible Markup Language) providers, 222 service, WebJAX-RPC systems, 282
EntityResolver interface, 39, 46, 91-97 method, 95 entries, serviceName (modifying), 325 enumerated attribute types, 373 Envelope element (SOAP), 23-24, 212 envelopes (XML), 19 error( ) method, 45, 54 ErrorHandler interface, 45 implementing (code), 54-55
engines, turbo (samsdictionary Web site), 76
methods, 54, 128
engines element, 362
org.sml.sax package, 39
*/engines (context node), 178
ErrorListener interface, 156
//engines/engine[last( )] (element node), 178
errors
engines[enginename = “Engine 1”] (element node), 178
CarParts.xml file (code), 54
engines[enginename] (element node), 178
handling, 53-57, 127-131, 164-165, 169
engine[5] [@type=”Alpha37”] (context node), 178
IOException, 169
engine[@id and @type] (element node), 178
in parsers, 53
engine[@type=”Alpha37”] (context node), 178
TransformerConfigurationException, 164, 169
engine[@type=”Alpha37”][5] (context node), 178 entities
fatal, 53
TransformerException, 164, 169 events
external, 89-97, 365
ContentHandler, handling, 51-53
handling, 67-71
lexical, 81-89 locations, identifying, 75-80 SAX (Simple API for XML), 102-115
files
exceptions DeleteException, 247 DOMException, 122
F factories
FindException, 247
SAXParserFactory class, 41-44
handling (code), 189-190
SOAPConnectionFactory class, 211
InvalidRequestException, 247
389
XMLReaderFactory class, 40
IOException, 169
false( ) function, 181
java.xml.rpc package, 285
fatal errors, 53
javax.xml.registry package, 246
fatal( ) method, 128
JAXRException, 205, 247
fatalerror( ) method, 45, 54, 128
JAXRPCException (java.xml.rpc package), 285
Federation interface, 246
org.w3c.dom package (JAXP), 122
files
ParserConfigurationException, 54
BestDealsonAccessories.war, creating, 328
in parsers, 53 SaveException, 247
BestDealsonAccessoriesRegistryPublisher.java application (code), 303-309
SAXException, 54, 126-128
buildclient.bat, syntax, 270, 277, 297
SAXParseException, 54, 126-128
CarPartRequest Config.properties (code), 329-333
ServiceException (java.xml.rpc package), 285 SOAPException (JAXM), 207
CarPartRequestImpl.java (code), 326-342
TransformerConfigurationException, 169
CarPartRequest_Config.properties, modifying serviceName entry, 325
TransformerException, 164, 169
CarParts.dtd (code), 124-125
UnexpectedObjectException, 247
CarParts.xml, 358-359
UnsupportedCapabilityException, 247 exceptionsTransformerConfigurationException, 164 exchanges, messages (JAXM), 196-199 expressions, XPath, 174-178 extending DefaultHandler classes, 50, 111
code, 117-118, 123-124 creating, 48-49 data, adding to tags (code), 62-63 DOCTYPE (code) to add, 90-91 DOM (Document Object Model), 118
Extensible Markup Language. See XML
DTDs (Document Type Definitions), code, 67-69, 366-368
ExtensibleObject interface, 243
element attributes (code) to add, 57
extensions, JAR files availability, 47
errors (code), 54
external entities, 365
modifying, 90-91
ExternalIdentifier class (ebXML information model), 237
namespaces, introducing (code), 99
ExternalIdentifier interface, 243 ExternalLink class (ebXML information model), 238 interface, 243 ExtrinsicObject interface, 243
processing instructions (code), 60 updating, 81-83 config.xml, 286-287, 291-293 CoolAccessoriesRegistryPublisher.java application, 303, 309-314 dom.jar, 46 index.html Web form, 224-226
How can we make this index more useful? Email us at
[email protected]
390
files
JAR, 46-48
Floor(number) function, 182
jaxp-api.jar, 46
forms, Web (creating), 224-226
MyDataDeleter.java application, creating, 271
forward slash (/), 177
MyJAXMClientWithProvider.java, 218
frameworks
MyOrganizationPublisher.java applications, 250-251 MyRegistryQuery.java application, creating, 263 MySAXTransformer.java, 167 objects, converting to InputSource objects, 111-112
binding runtime (JAXB), 346-347 eCo Framework Web site, 12 full stop (.), 363 functions boolean(object), 181 Ceiling(number), 182
runMyDataDeleter.bat, syntax, 278
concat(string, string,…), 180
sampledoc.txt, creating, 227-228
contains(string, string), 180
SampleMailMessage.txt, creating, 102-103
count(node-set), 179
sax.jar, 46
delete xxxx, 28
text
false( ), 181
SampleMailMessage.txt file, creating, 102-103
find xxxx, 28
TheGreatPartsSupplierRegistryPublisher.java application, 303, 314-319
id(object), 179
WAR, creating, 328 web.xml, creating, 226-227, 293-294 WeSupplyPartsRegistryPublisher.java application, 303, 319-324 WSDL (Web Services Description Language), JAX-RPC systems, 283
Floor(number), 182 lang(string), 181 last( ), 179 local-name(node-set), 179 name(node-set), 179 namespace-uri(node-set), 179 Normalize-space(string), 181
xalan.jar, 46
not(Boolean), 181
XercesImpl.jar, 46
Number(object), 182
xsltc.jar, 46
Position( ), 179
filtering XPath expression selections, 177-178
printDomNode( ), 133-135
filters, 39-40
Round(number), 182
find_binding( ) method, 28
save_xxxx, 28
find_business method, 214
set xxxx, 28
find_xxxx functions, 28
starts-with(string, string), 180
findClassificationSchemeByName method, 259
string(object), 180
FindException exception, 247
string-length(string), 180
finding information with Locator interface methods, 75
substring-after(string, string), 180
findOrganiations method, 267
substring(string, number, number), 180
FindQualifier interface, 246, 267
Sum(node-set), 182
fire-and-forget messaging (JAXM message exchanges), 198-199
Translate(string,string,string), 181
#FIXED keyword, 374
substring-before(string, string), 180
true( ), 181 XPath, 179-182
identifiers
G
DTDs (Document Type Definitions) (code), 69-70
getAttributes( ) method, 139
parser in validating mode (code), 71-73 processing instructions (code), 61-62
GetBookPrice method, 25, 32 getCarPartRequest method, 325
391
handling
getContentHandler( ) method (XMLReader), 43
attributes, 57-59
getDoctype( ) method, 132
characters, 62-66
getDocumentElement( ) method, 133-135
ContentHandler events, 51-53
getDTDHandler( ) method (XMLReader), 43
DTDs (Document Type Definitions), 67-71
getElementsByTagName( ) method, 137-138
entities, 67-71
getEntityResolver( ) method (XMLReader), 43
errors, 53-57
getEnvelope( ) method, 213
DOM (Document Object Model), 127-131
getErrorHandler( ) method (XMLReader), 43
XSLT (XSL Transformations) with DOM, 164-165
getFeature(java.lang.String name) method (XMLReader), 43
XSLT (XSL Transformations) with SAX (Simple API for XML), 169
getLastChild( ) method, 140
exceptions (code), 189-190
getMetaData( ) method, 220 getName( ) method, 132 getNextSibling( ) method, 152 getNodeType( ) method, 133 getParameter( ) method, 222 getProperty(java.lang.String name) method (XMLReader), 43 getSupportedProfiles( ) method, 219 getSystemId( ) method, 77, 132
processing instructions, 59-62 Header element (SOAP), 24-25, 212 help, Sams Teach Yourself XML in 24 Hours, 358 helper classes (org.xml.sax.helpers package), 40 Hewlett-Packard Web site (registry), 250 HTML (Hypertext Markup Language), tags, 80 HTTP (Hypertext Transfer Protocol) JAX-RPC (Java API for XML-based RPC), 280
getXMLReader( ) method, 51 Glue Web site (registry), 250 grammar, XML (Extensible Markup Language), 358
SOAP (Simple Object Access Protocol), 20-23 hubcaps element, 362 hyphen (-), 363
Great Car Parts Company, 33-34 Great Parts Supplier Inc. (The), 330-331 greater than sign (>), predefined entity, 364 green electronic pages (registries), 234
I I Need Car Parts Inc., 301 IBM registry URLs (uniform resource locators), 253
H
Web site, 250
handlers, MyXMLHandler output
ID attribute, 372
attributes (code), 59
id(object) function, 179
characters( ) method (code), 64-66
identifiers, public (URNs) or system (URLs), 75
How can we make this index more useful? Email us at
[email protected]
392
identifying document or event locations
identifying document or event locations, 75-80
InputSource objects
IDREF attribute, 372
creating, 168
IDREFS attribute, 372
file objects, converting to, 111-112
ignorableWhitespace( ) method, 71 implementations characters( ) method (code), 63-64 client
inquiries (JAXM message exchanges) asynchronous, 196-197 synchronous, 198 Inquiry API, 28-29, 214
creating, 209
InsertBefore( ) method, 142
messaging providers, 217-230
installing
standalone, 209-217
Java XML Pack, 353
ErrorHandler interface (code), 54-55
JAX (Java APIs for XML) packages, 353
JAXR (Java API for XML-based Registries), 249
JWSDP (Java Web Services Developer Pack), 354-355
physical, JAX-RPC (Java API for XML-based RPC) systems, 282 processingInstruction( ) method (code), 60-61 #IMPLIED keyword, 374 importing classes
instances DTDs (Document Type Definitions), 9 SAXParser class, 42 instantiating variables (code), 104-105 instructions
to MyJAXMClientWithProvider servlet, 218
PIs (processing instructions), 361-362
for publishing data to registries, 251-252
processing
to standalone client implementations, 210-211 JAXP (Java API for XML Processing) classes, 50, 126, 159-160, 167-168 LexicalHandler interface, 83-84 packages to MyJAXMClientWithProvider servlet packages, 218
handling, 59-62 nodes (XPath), 176 interfaces Association, 242 Attr, 120 Attributes (org.sml.sax package), 39 AuditableEvent, 242
for publishing data to registries, 251-252
BulkResponse, 245
for SAX (Simple API for XML), 103-104, 110
BusinessLifecycleManager, 245
to standalone client implementations, 210-211
BusinessQueryManager, 245
StringReader class, 92
Call (java.xml.rpc package), 284 capability-specific, 240
index.html Web form, 224-226
CapabilityProfile, 245
indicators, element occurrence, 369
CataloguedObject, 245
information
CDATASection, 120
DTDs (Document Type Definitions), accessing, 131-132 Finding with Locator interface methods, 75 models (registries), 235-236 node chart, 133 init( ) method, 219 input element (WSDL), 32
CharacterData, 120 Classification, 242 ClassificationScheme, 242 Comment, 120 Concept, 243 Connection, 246 ContentHandler, 39, 45, 111
interfaces
DeclarativeQueryManager, 246
Locator, 39, 75
DeclHandler (org.xml.sax.ext package), 40
Name (JAXM), 205
DefaultHandler class, 44
NamedNodeMap, 121
Detail (JAXM), 205
Node, 121, 205
DetailEntry (JAXM), 205
NodeList, 122
DII (dynamic invocation interface), 283
Notation, 122
Document, 120
OnewayListener (JAXM), 204
DocumentFragment, 121
org.w3c.dom package (JAXP), 120-122
DocumentType, 121
org.xml.sax package, 39
DOMImplementation, 121
org.xml.sax.ext package, 39-40
DOMLocator, 157
Organization, 244
DTDHandler, 39, 45-46
PersonName, 244
Element, 121
PostalAddress, 244
EmailAddress, 243
ProcessingInstruction, 122
Entity, 121
ProviderConnection (JAXM), 204
EntityReference, 121
ProviderMetaData (JAXM), 204
EntityResolver, 39, 46, 91-97
Query, 246
ErrorHandler, 45
QueryManager, 246
implementing (code), 54-55
RegistryEntry, 244
methods, 54, 128
RegistryObject, 242
org.sml.sax package, 39
RegistryPackage, 244
393
ErrorListener, 156
RegistryService, 240, 246
ExtensibleObject, 243
ReqRespListener (JAXM), 204
ExternalIdentifier, 243
Result, 156
ExternalLink, 243 ExtrinsicObject, 243
RMI (Remote Method Invocation), config.xml file syntax, 286-287
Federation, 246
Service, 244, 284
FindQualifier, 246
service definition
InternationalString, 243
creating, 290-291
java.xml.rpc package, 284
interface implementation class, creating, 291
javax.xml.registry package, 245 javax.xml.registry.infomodel package, 242 javax.xml.transform package (XSLT), 156-157 javax.xml.transform.sax package (XSLT), 158 JAXRResponse, 246 Key, 244 LexicalHandler, 40, 81-89 LifeCycleManager, 246 LocalizedString, 244
ServiceBinding, 244 Slot, 243 SOAPBody (JAXM), 205 SOAPBodyElement (JAXM), 205 SOAPConstants (JAXM), 206 SOAPElement (JAXM), 206 SOAPEnvelope (JAXM), 206 SOAPFault (JAXM), 206 SOAPFaultElement (JAXM), 206
How can we make this index more useful? Email us at
[email protected]
394
interfaces
SOAPHeader (JAXM), 206 SOAPHeaderElement (JAXM), 206 Source, 156
ebXML (Electronic Business using Extensible Markup Language) CPP/A (Collaboration Protocol Profile/Agreement) APIs, 348
SourceLocator, 157
JAXP (Java API for XML Processing), JAR files (reference implementation), 46-48
SpecificationLink, 244
mapping (XML schema data types), 346
Stub (java.xml.rpc package), 284
objects, converting to XML schema/DTDs, 344-345
TelephoneNumber, 244 Templates, 157 TemplatesHandler, 158 Text, 122, 206 TransformerHandler, 158 URIResolver, 157 User, 245 Versionable, 245 WSDL (Web Services Description Language), 29 XMLFilter (org.sml.sax package), 39 XMLReader implementing for SAX (Simple API for XML) parser, 104 methods, 42-44 org.sml.sax package, 39
types, supported by JAX-RPC (Java API for XML-based RPC), 288 Xalan libraries, 47 XML (Extensible Markup Language), 7 binding, 343-344 Transactioning API (JAXTX), 348 Java API for XML Messaging. See JAXM Java API for XML Processing. See JAXP Java API for XML Registries. See JAXR Java API for XML-based RPC. See JAX-RPC Java APIs (Application Programming Interfaces) JAXB (Java Architecture for XML Binding), 9-10 XML (Extensible Markup Language), 7-8 Java Architecture for XML Binding. See JAXB
intermediate destination support (JAXM message providers), 203-204
Java Community Process (JCP) Web site, 343
internal entities, 364-365
Java Specification Requests (JSRs), 343
InternationalString interface, 243
Java Web Services Developer Pack (JWSDP), 7, 46-48, 249-250, 302-303, 354-355
interoperability, JAXM (Java API for XML Messaging) and messaging applications, 199-200
Java Development Kit (JDK), downloading, 353
Java XML Pack, 7
InvalidRequestException exception, 247
downloading, 354
invoking parse( ) method, 112-113
installing, 353
IOException, 169
and JSWDP (Java Web Services Developer Pack), comparing, 354 java.xml.rpc package, 284-285 javax.net.* package, classes, 251
J
javax.security.* package, classes, 251
J2EE platform, 7
javax.util.* package, classes, 251
JAR files, 46-48
javax.xml.messaging package (JAXM), 204-205
Java
javax.xml.messaging.URLEndpoint class, 211
APIs (Application Programming Interfaces) for WSDL (Web Services Description Language), 349
javax.xml.parsers package, 41-42, 122-123
Classes not supported by JAX-RPC (Java API for XML-based RPC), 289
javax.xml.registry package, 245-247
javax.xml.parsers.SAXParserFactory system property, 42 javax.xml.registry.* package, classes, 251
JAXP
javax.xml.registry.infomodel package, 242-245
Specifications, Web site, 344
javax.xml.registry.infomodel.* package, classes, 251
StAX (Streaming API for XML), 349
javax.xml.registry.lifeCycleManagerURL property, 253 javax.xml.registry.queryManagerURL property, 253
395
XML (Extensible Markup Language) Digital Encryption APIs, 348 Digital Signature APIs, 348
javax.xml.soap package, 205-207, 211
schema/DTDs, converting to Java objects, 344-347
javax.xml.transform package (XSLT), 155-157
Transactioning API for Java (JAXTX), 348
javax.xml.transform.* classes, 168
Trust Service APIs (Application Programming Interfaces), 348
javax.xml.transform.dom package (XSLT), 157 javax.xml.transform.dom.SAXSource class, 168 javax.xml.transform.sax package (XSLT), 157-158
JAXM (Java API for XML Messaging), 7 clients, 11, 195, 201-202
javax.xml.transform.stream package (XSLT), 158
deploying, 228-230
JAX-RPC (Java API for XML-based RPC), 7
relationship with message providers, 195
application classes supported, 288-289
elements, 201
CarPartRequest Web service, 289-298
end-points, 195
client programs and Web services, communicating, 281
interoperability with messaging applications, 199-200
HTTP (Hypertext Transfer Protocol), 280
javax.xml.messaging package, 204-205
Java
javax.xml.soap package, 205-207
classes unsupported, 289 types supported, 288 java.xml.rpc package, 284-285
messages, 11 exchanges, 196-199 providers, 19, 195, 202-204
packages, 283-284
MyJAXMClient, 209
remote procedure calls, 279-280 RMI (Remote Method Invocation), 279
MyJAXMClientWithProvider output (code), 229-230
SOAP (Simple Object Access Protocol), 13, 280
packages, 204
stubs, 281
Provider Administration Tool, downloading, 222
systems, 282-283 ties, 281 types supported, 287 xrpcc tool, 285-287 JAXB (Java Architecture for XML Binding), 7-10
providers, 11 servers, 11 SOAP (Simple Object Access Protocol), 10, 200-201 JAXMException exception (JAXM), 205
binding, 345-347
JAXMServlet class (JAXM), 204
components, 344-345
JAXP (Java API for XML Processing), 7-9. See also XSLT
ebXML (Electronic Business using Extensible Markup Language) CPP/A (Collaboration Protocol Profile/Agreement) APIs for Java, 348
classes, importing, 50, 126, 159-160, 167-168
Java, 343-344, 349
DOM (Document Object Model), 8, 38, 117-125
JDOM 1.0, Web site, 347
downloading, 46
How can we make this index more useful? Email us at
[email protected]
396
JAXP
JAR files, reference implementation, 46-48
RegistryService interface, 240
javax.xml.parsers package, 122-123
specification (registries), 239
org.w3c.dom package, 120-122
JAXRException exception, 247
packages, 120 SAX (Simple API for XML), 8, 38-46
JAXRPCException exception (java.xml.rpc package), 285
SAX-parsing applications
JAXRResponse interface, 246
attributes, handling, 57-59
JAXTX (XML Transactioning API for Java), 348
CarParts.xml file, creating, 48-49
JCP (Java Community Process), 343
characters, handling, 62-66
JDK (Java Development Kit), downloading, 353
ContentHandler events, handling, 51-53
JDOM 1.0, Web site, 347
creating, 48
JSRs (Java Specification Requests), 343
DefaultHandler classes, extending, 50
JWSDP (Java Web Services Developer Pack), 7, 46-48, 249-250, 302-303, 354-355
DTDs (Document Type Definitions), handling, 67-71 entities, handling, 67-71 errors, handling, 53-57 JAXP (Java API for XML Processing) classes, importing, 50 processing instructions, handling, 59-62
K Key interface, 244 keywords
SAX (Simple API for XML) parser, 49-51
CDATA, 371
validating parsers, 71-73
#FIXED, 374
XML (Extensible Markup Language) documents (SAX parsers), 38
#IMPLIED, 374 NDATA, 45
XSLT (XSL Transformations) standards, 38 jaxp-api.jar file, 46 JAXR (Java API for XML Registries), 7, 11-13
#REQUIRED, 374 kits, JDK (Java Development Kit), downloading, 353
architecture, registries, 239 capability-specific interface, 240 clients, 240 data, registries deleting from, 271-278 publishing to, 250-262 querying from, 263-271 implementations, 249 javax.xml.registry package, 245-247 javax.xml.registry.infomodel package, 242-245 JWSDP (Java Web Services Developer Pack) Registry Server, 249-250
L lang(string) function, 181 languages. See also XML binding, 347 ebXML (Electronic Business using Extensible Markup Language) CPP/A (Collaboration Protocol Profile/Agreement) APIs for Java, 348 information model, 237-238
MyOrganizationPublisher.java applications, 250
messages, 219-224
packages, 241
providers, endpoint mappings, 222
providers, 240-241
SOAP (Simple Object Access Protocol), 11
registries, 12, 241
Web site, 12
markup languages
HTML (Hypertext Markup Language), tags, 80 WSDL (Web Services Description Language) documents, 29-32, 287 files, JAX-RPC (Java API for XML-based RPC) systems, 283 interfaces, 29
LocalizedString interface, 244 locations documents or events, identifying, 75-80 paths (XPath expressions), 176-177 Locator interface Methods for finding information, 75
Java APIs (Application Programming Interfaces), 349 methods, 29
org.sml.sax package, 39 object
operations, 29
displaying elements (code), 76-77
ports, 29
MyXMLHandler output (code), 77-80 passing to applications, 76
request messages, 31-33 response messages, 31-33 SOAP (Simple Object Access Protocol) elements, 31-33
397
LocatorImpl class (org.xml.sax.helpers package), 40
Web services, 29 last( ) function, 179 less than sign ( (XML documents), 363
and client programs (JAX-RPC), communicating, 281
Simple APIs for XML. See SAX Simple Mail Transfer Protocol (SMTP), 20
definition, 15
Simple Object Access Protocol. See SOAP
deploying, 301
single quotation mark (‘), predefined entity, 364
developing, 325-326
slashes, forward (/), 177
getCarPartRequest method, 325
Slot
Great Car Parts Company, 33-34
class (ebXML information model), 237
JAX-RPC (Java API for XML-based RPC) systems, 282
interface, 243 SMTP (Simple Mail Transfer Protocol), 20
SOAP (Simple Object Access Protocol), 19-25
SOAP (Simple Object Access Protocol)
UDDI (Universal Description, Discovery and Integration), 25-29
1.1 or 1.2 specifications, Web site, 19
WSDL (Web Services Description Language), 29-33
avax.xml.soap package, 211
XML (Extensible Markup Language), 357 XML (Extensible Markup Language) Trust Service APIs, 348
Attachments Note, Web site, 19 data encoding rules, 19 ebXML (Electronic Business using Extensible Markup Language), 11
servlets, MyJAXMClientWithProvider, 217-224
Envelope element, 23-24
set_xxxx function, 28
envelopes, 19
StreamSource class
extension elements (WSDL), 31
SOAPHeader
Header element, 24-25
interface (JAXM), 206
HTTP (Hypertext Transfer Protocol), 20-23
SOAPMessage object, 212
javax.xml.soap package (JAXM), 205-207
SOAPHeaderElement interface (JAXM), 206
JAX-RPC (Java API for XML-based RPC), 13, 280
SOAPMessage
JAXM (Java API for XML Messaging), 10, 200-201 major-number minor-number versioning method, 24 messages, 20-22, 212-217
class (JAXM), 206 object, 212 SOAPPart class (JAXM), 206 SOAPMessage object, 212
request messages, defining, 31-33
Source interface, 156
requests (code), 21
source trees, 153
response messages, defining, 31-33
SourceLocator interface, 157
responses (code), 21-22
SpecificationLink
RPCs (remote procedure calls) convention, 19 SMTP (Simple Mail Transfer Protocol), 20 Web services, 19-20 WSDL (Web Services Description Language), 31-33 soap:binding element, 33 soap:body element, 33 SOAPBody interface (JAXM), 205 SOAPMessage object, 212 SOAPBodyElement interface (JAXM), 205 SOAPConnection
class (ebXML information model), 239 interface, 244 specifications DOM (Document Object Model) level 2, Web site, 120 JAXB (Java Architecture for XML Binding), Web site, 344 JAXR (Java API for XML Registries), registries, 239 SOAP (Simple Object Access Protocol) 1.1 or 1.2, Web site, 19 UDDI (Universal Description, Discovery and Integration), 26
class (JAXM), 206
stacks, protocol (Web services), 18-19
object, 210-211
standalone
SOAPConnectionFactory class, 210-211 SOAPConstants interface (JAXM), 206
409
client implementations, 209-217 documents, 360
SOAPElement interface (JAXM), 206
standards, registries, 12
SOAPElementFactory class (JAXM), 206
startDocument( ) method, 52
SOAPEnvelope
startElement( ) method, 37, 45, 52, 57-58, 77, 100
interface (JAXM), 206
starting and ending tags, matching, 362
SOAPMessage object, 212
starts-with(string, string) function, 180
SOAPException exception (JAXM), 207
StAX (Streaming API for XML), 349
SOAPFault interface (JAXM), 206
stops, full (.), 363
SOAPFaultElement interface (JAXM), 206
StreamResult class, 158 StreamSource class, 158
How can we make this index more useful? Email us at
[email protected]
410
string-length(string) function
string-length(string) function, 180
systems
string(object) function, 180
identifiers, URLs (uniform resource locators), 75
StringReader class, importing, 92
JAX-RPC (Java API for XML-based RPC), 282-283
strings - - (double hyphen), 360
properties, javax.xml.parsers.SAXParserFactory, 42
attribute type, 371-372 functions (XPath), 180-181
Systinet Web site, registry, 250
structures, data (UDDI), 26-27 Stub interface (java.xml.rpc package), 284 stubs, JAX-RPC (Java API for XML-based RPC), 281-283
T
stylesheets, XSLT (XSL Transformations), 154, 173, 183-187
tags
substring-after(string, string) function, 180
. (full stop), 363
substring-before(string, string) function, 180
- (hyphen), 363
substring(string, number, number) function, 180
attributes, creating, 358
Sum(node-set) function, 182
, 6
supplier path, 177
data, adding CarParts.xml file (code), 62-63
//supplier path, 177
names, 362
supplier[1] (element node), 177
, CDATA section (XML documents), 80
support
starting and ending, matching, 362
intermediate destinations (JAXM message providers), 203-204 JAX-RPC (Java API for XML-based RPC), 287-289 profiles (JAXM message providers), 203 synchronous (JAXM message exchanges) inquiry, 198 updates, 197-198 syntax. See also code buildclient.bat file, 270, 277, 297 config.xml file, starting, 286-287 runMyDataDeleter.bat file, 278 XML (Extensible Markup Language) < (left angle bracket), 37, 45, 52 > (right angle bracket), 52 SYSTEM argument, 365
XML (Extensible Markup Languge), 5, 358 , 185 TelephoneNumber interface, 244 templates XSLT (XSL Transformations) stylesheet, 173 tag, 185 Templates interface, 157 TemplatesHandler interface, 158 text files, SAX (Simple API for XML) events, 102-115 nodes, 147-149, 176 Text interface, 122, 206 node (DOM), 119 The Great Parts Supplier Inc., 330-331 TheGreatPartsSupplierRegistryPublisher.java application, 303, 314-319 threads, SAXParserFactory class, 44 ties, JAX-RPC (Java API for XML-based RPC), 281-283
use models
tModel element (UDDI information model), 237
typeMappingRegistry element, 287
tokenized attribute types, 372-373
types
tools
411
attributes, 371-373
JAXM (Java API for XML Messaging) Provider Administration Tool, downloading, 222
element nodes, 133-137 supported by JAX-RPC (Java API for XML-based RPC), 287-288
xrpcc (JAX-RPC), 283-287 Transactioning API for Java (JAXTX)(XML) APIs, 348 transform( ) method, 165 transformations stylesheets, 154 tree, 153-154 Transformer (XSLT), setting up, 163, 168-169
U UDDI (Universal Description, Discovery and Integration)
Transformer class, 156
APIs (Application Programming Interfaces), 28-29
TransformerConfigurationException, 156, 164, 169
data structures, 26-27
TransformerException, 156, 164, 169
information model, 236-237
TransformerFactory class, 156
specifications, 26
TransformerFactoryConfigurationError class, 156
Web services, 25-26
TransformerHandler interface, 158
Web site, 12
transformers
XML (Extensible Markup Language) Schema, 26-28
MyDOMTransformer application (code), 160-166
UnexpectedObjectException exception, 247
MySAXTransformer application, output (code), 171-173
uniform resource locators (URLs), 75-76, 253
MyXSLTTransformer application, creating, 187-191
unmarshaling XML (Extensible Markup Language) documents, 346
uniform resource names (URNs), 75-76
transforming XML, 165-167, 170-173, 182-187
UnsupportedCapabilityException exception, 247
Translate(string,string,string) function, 181
Updates (JAXM message exchanges)
transparency (JAXM message providers), 203
asynchronous, 197
trees
synchronous, 197-198
content, validation, 347 output, 153
updating CarParts.xml file, 81-83
source, 153
Great Car Parts Company Web site, 34
transformations, 153-154
URIResolver interface, 157
XPath nodes, 174-176
URLEndpoint
true( ) function, 181 Trust Service (XML) APIs, 348 try-catch block, adding to parse( ) method (code), 55-56 turbo engine, samsdictionary Web site, 76 two dots (..), 177
Class, 205 object, 214 URLs (uniform resource locators), 75-76, 253 URNs (uniform resource names), 75-76 use models, registries, 234-235
How can we make this index more useful? Email us at
[email protected]
412
User
User
case study
class (ebXML information model), 238
applications, creating, 303
interface, 245
BestDealsonAccessoriesRegistryPublisher.jav a application (code), 303-309 CoolAccessoriesRegistryPublisher.java application, 303, 309-314
V
description, 301-302 development order, 302
validating content trees, 347 parsers, MyXMLHandler output (code), 71-73 values, default attribute, 374 variables, instantiating (code), 104-105 verifying data deletions (code), 276 Versionable interface, 245
JWSDP (Java Web Services Developer Pack) Registry Server, 302 TheGreatPartsSupplierRegistryPublisher.java application, 303, 314-319 WeSupplyPartsRegistryPublisher.java application, 319-324 and client programs (JAX-RPC), communicating, 281 definition, 15 deploying, 301
W
developing, 325-326
W3C (World Wide Web Consortium)
Great Car Parts Company, 33-34
getCarPartRequest method, 325
Web site, SOAP (Simple Object Access Protocol) specifications, 19
JAX-RPC (Java API for XML-based RPC) systems, 282
XSLT (XSL Transformations), 153
SOAP (Simple Object Access Protocol), 19-25
WAR files, creating, 328 warning( ) method, 45, 54, 128 warnings in parsers, 53 We Supply Parts Inc., CarPartRequestImpl.java file (code), 331-333 Web forms, creating, 224-226 Web services, 6
UDDI (Universal Description, Discovery and Integration), 25-29 WSDL (Web Services Description Language), 29-33 XML (Extensible Markup Language), 357 Web Services Description Language (WSDL) documents, 29-32, 287
architecture, 17-19
files, JAX-RPC (Java API for XML-based RPC) systems, 283
B2B (business-to-business) communication, 15-17
interfaces, 29
CarPartRequest, 289-296
Java APIs (Application Programming Interfaces), 349
CarPartRequest_Config.properties file, 325 CarPartRequest Config.properties file (code), 329-333 CarPartRequestClient.java application (code), 333-342 CarPartRequestImpl.java file (code), 326-333
methods, 29 operations, 29 ports, 29 request messages, 31-33 response messages, 31-33 SOAP (Simple Object Access Protocol) elements, 31-33 Web services, 29
XML
Web sites
413
writeTo( ) method, 214
DOM (Document Object Model) level 2 specifications, 120 ebXML (Electronic Business using Extensible Markup Language), 12
writing BestDealsonAccessoriesRegistryPublisher.java application, 303 plumbing code for registry data
eCo Framework, 12
deleting, 272-273
Glue, registry, 250
publishing, 252
Great Car Parts Company, updating, 34 Hewlett-Packard, registry, 250
querying, 263-264 WSDL (Web Services Description Language)
IBM, registry, 250
documents, 29-32, 287
Inquiry API, 29, 214
files, JAX-RPC (Java API for XML-based RPC) systems, 283
Java Community Process, 343
interfaces, 29
XML Pack, downloading, 354
Java APIs (Application Programming Interfaces), 349
JAXB (Java Architecture for XML Binding) specifications, 344
methods, 29
JAXM (Java API for XML Messaging) Provider Administration Tool, downloading, 222
operations, 29
JDK (Java Development Kit), downloading, 353
request messages, 31-33
JDOM 1.0, 347
response messages, 31-33
Microsoft, registry, 250
SOAP (Simple Object Access Protocol) elements, 31-33
OASIS (Organization for the Advancement of Structured Information Standards), 12
ports, 29
Web services, 29
Publish API, 29, 214 registries, 214 samsdictionary, turbo engine, 76 SAP (Systems, Applications, Products), registry, 250
X-Y-Z
SAX (Simple APIs for XML), 41
Xalan libraries, 47
SOAP (Simple Object Access Protocol), 1.1 or 1.2 specifications or Attachments Note, 19
xalan.jar file, 46
Systinet, registry, 250
XercesImpl.jar file, 46
UDDI (Universal Description, Discovery and Integration), 12
XML (Extensible Markup Language)
Xerces parser, 9, 42
& (ampersand), 80
web.xml file, creating, 226-227, 293-294
< (left angle bracket), 80
WeSupplyPartsRegistryPublisher.java application, 303, 319-324
> (right angle bracket), 80
white electronic pages (registries), 234
APIs (Application Programming Interfaces), applications, 7
World Wide Web Consortium (W3C)
attributes, 363, 371-374
Web site, SOAP (Simple Object Access Protocol) specifications, 19 XSLT (XSL Transformations), 153
binding Java architecture, 343-344 schemas, 9
How can we make this index more useful? Email us at
[email protected]
414
XML
tag, 6 CDATA section, 366
JWSDP (Java Web Services Developer Pack), downloading, 354-355
character references, 363
language and grammar, 358
comments, 360-361
org.xml.sax package, 39
ContentHandler interface, 45
org.xml.sax.ext package, 39-40
data
org.xml.sax.helpers package, 40
DOM (Document Object Model), 131-141
PIs (processing instructions), 361-362
portability, 6
root element, 361
declarations, 360
SAX (Simple APIs for XML), 37, 41
DefaultHandler class, 44-45
SAXParser class, 42-44
Digital Encryption APIs, 348
SAXParserFactory class, 42-44
Digital Signature APIs, 348
Schema, 26-28, 344-347
documents, 358-359
SOAP (Simple Object Access Protocol), 10, 19
> (right angle bracket) sign, 363
StAX (Streaming API for XML), 349
CDATA section, 80
syntax
column numbers, 75 DTDs (Document Type Definitions), 9
< (left angle bracket), 37, 45, 52 > (right angle bracket), 52
line numbers, 75
tags, 5, 358
marshaling, 346
Transactioning API for Java (JAXTX), 348
org.xml.sax.InputSource class, 168
transforming, 165-167, 170-173, 182-187
SAX (Simple APIs for XML) parsers, 37-38
Trust Service APIs (Application Programming Interfaces), 348
standalone, 360 unmarshaling, 346 XSLT (XSL Transformations), 38, 153-155 DOM (Document Object Model), APIs, 37 DTDs (Document Type Definitions), 360, 366-368 DTDHandler interface, 45-46 EDI (Electronic Data Interchange), 5-6 elements, 362-363, 369-370
Web services, 357 XML-DEV group, APIs, 38 XMLFilter interface (org.sml.sax package), 39 XMLFilterImpl class (org.xml.sax.helpers package), 40 XMLReader configuring, 84-85 interface
entity references, 363-365
implementing for SAX (Simple API for XML) parser, 104
EntityResolver interface, 46
methods, 42-44
ErrorHandler interface, 45
org.sml.sax package, 39
grammar, 358
methods, implementing (code), 108-110
Java APIs (Application Programming Interfaces), 7-13
XMLReaderAdapter class (org.xml.sax.helpers package), 40
Java XML Pack, 7, 353-354
XMLReaderFactory class (org.xml.sax.helpers package), 40
javax.xml.parsers package, 41-42 JAXM (Java API for XML Messaging), 11
yellow electronic pages
XPath data, normalized, 174 expressions, 174-178
415
XSLT (XSL Transformations) Transformer, setting up, 168-169 stylesheet, 173 creating, 184-187
functions Boolean, 181
expressions, 174
node-set, 179
XML (Extensible Markup Language), transforming, 183-184
numeric, 181-182 string, 180-181 nodes, 174-176
Transformer, setting up, 163, 168-169 XML (Extensible Markup Language) documents, 38, 153-155
operators, 178-179
command, 187
XSLT (XSL Transformations) stylesheet, 173
command, 185
xrpcc tool (JAX-RPC), 283-287
command, 185
XSLT (XSL Transformations)
command, 185
DOM (Document Object Model), 159 applications, creating, 160-163
tag, 185 xsltc.jar file, 46
error handling, 164-165 JAXP (Java API for XML Processing) classes, importing, 159-160
yellow electronic pages (registries), 234
steps in using, 159 transformed XML, generating, 165-167 XSLT (XSL Transformations) Transformer, setting up, 163 javax.xml.transform package classes, 155-156 interfaces, 156-157 javax.xml.transform.dom package, 157 javax.xml.transform.sax package, 157-158 javax.xml.transform.stream package, 158 MyXSLTTransformer application, creating, 187-191 packages, 155 parsers, 8, 38 SAX (Simple API for XML) error handling, 169 InputSource object, creating, 168 JAXP (Java API for XML Processing) classes, importing, 167-168 transformed XML, generating, 170-173 XSLT (XSL Transformations) APIs (Application Programming Interfaces), 167
How can we make this index more useful? Email us at
[email protected]
