1. ® IBM Software Group © 2006 IBM Corporation How to read/write XML using EGL This Learning Module shows how to utilize an EGL Library to read/write an XML file. ExternalTypes are provided which leverage the interface between EGL and the Java API's. These Java API's provide support for XPath (in order to search XML files) as well as DOM, in order to write XML.

2. 2 Calling XPath Queries from EGL ***Notes  In the next workshop we’ll be utilizing something called XPath. XPath is a query language (available through standard Java APIs) designed to search (“parse”) XML documents and return strings. ***Notes  We’ll create the following.JSP page, which utilizes XPath to query an XML document, and return various elements of it through EGL function calls

3. 3 – Overview Calling XPath Queries from EGL – Overview  In a short amount of time, XML has become the standard for exchanging information over the internet and/or between different pieces of software.  Querying XML files is not the easiest thing to do though, or the most fun code to write – as you have to learn the XML language, standards, and write custom routines to iterate over strings.  Error-prone  Time-consuming  Everything EGL is supposed to help you avoid  This course provides an EGL library to query XML files with minimal coding. We will use our own custom artifacts (all provided in the Notes sections of this document):  XML File – a listing of book authors  EGL ExternalType definitions – referencing the XPath Java API  A library of functions to call the External types – and query the XML file of books for specific information

4. 4  Create ExternalType Definitions to XPath and XML Write Start by adding the following ExternalType to your project. EGLSource\ ReadWrite  Create an EGL package in your \EGLSource\ folder called: xml ReadWrite XML_ExternalType.egl  Right click over the XPath package and create a new EGL Source File named XML_ExternalType.egl Ctrl/S  Copy/Paste the code in the notes and replace the default boiler plate code. Press Ctrl/S

5. 5  Create an EGL Library of XPath Function Calls – 1 of 2 Now let’s add a library to your project in order to make it easier to utilize the XPath API’s. XPath_Queries  Right-click over the libraries package and create a new EGL Source File named: XPath_Queries

6. 6  Calling XPath Queries from EGL – 2 of 2  Note the following about your new Library:  There are two functions  The first function sets the location of the XML file on the file system  The user passes this location to the function  The second function searches the XML file based on the XPath Query you specify  The results of the query are put into a dynamic string array which the user passes to the function***Notes

7. 7  Add an XML File – to be Queried Using XPath Now let’s add an XML file to your project that we can run XPath queries against: \EGLSource\  Right-click over the \EGLSource\ folder and select New  Other…  From the wizard that pops up, select XML and then click Next Next  Select:  Create XML from scratch, click Next books.xml  Specify to save the file under \EGLSource\, and name it: books.xml Source  Switch the editor to: Source mode books.xml  Copy/Paste the code in the notes section of the slide into books.xml

8. 8  Add an XML File – to be Queried Using XPath The XML file is essentially a catalog of books. Each book contains an author, title, genre, price, publish_date, and description. You can view the contents either in Source or Design mode.

9. 9  Create a.JSP Page to Show XML Contents XPath.jsp  Create a new.JSP page, named: XPath.jsp  From Page Designer  Change the default text Edit Page Code  Right click on the page and select Edit Page Code  Copy the code in the Notes section of the slide, and replace the boilerplate JSFHandler code  Browse through this file, and read the comments  Edit the first statement in the onConstruction() function:  “XPathQueries.setLocation(…)." books.xml  Point to the books.xml file in your project absolute path to your books.xml  You will want to specify the absolute path to your books.xml  Ctrl/S – save and generate

10. 10  XPath Query Syntax ***See Notes  Let’s examine the syntax for XPath queries, as it is very important that you examine and understand the structure of the XML file. ***See Notes for the XPath language keywords.  Query1: //book[author='Ralls, Kim']/title/text()  Returns the title of the book authored by Kim Ralls  Uses a recursive operator (//), the attribute operator ([]), and the text function  Could be written as: /catalog/book[author=‘Ralls, Kim’]/title/text();  Query2: //*/text()  Returns all values in the XML file  Uses the recursive operator and the wildcard operator  Query3: //author/text()  Returns all values of element type author in the XML file  Uses the recursive operator and the text function  Could alternatively be written as: /catalog/book/author/text()  Query4: //book[@id='bk105']/description/text()  Returns the description of the book with the id = ‘bk105’  Uses the recursive operator, the attribute operator, and the text function

11. 11  Create a.JSP Page to Show XML Contents – JSF Components  Return to the Page Designer  Drag the outPutText variable onto the page as display only  Drag all four functions onto the page – where they will become Submit Buttons ans  Drag the ans string array onto the page as a display only field

12. 12  Calling XPath Queries from EGL  Run the page on the Server  Query 3 has been run  All values of the Author element are being displayed in the Ans dataTable  Now take the knowledge you’ve learned from this workshop and utilize our EGL library on your own XML files!

13. 13 Writing XML Files  Now that we can properly query XML files using XPath, how about writing to XML?!?!  We will create the following page which writes the specified input to an XML file  You are then able to query this XML file using XPath

14. 14  Create an EGL Library of XML Write Function Calls – 1 of 2  Let’s first add a library to our project, which will give us simple XML writing capabilities. XMLWriteLib  Right-click over the libraries package and create a new EGL Source File named: XMLWriteLib. Copy/paste the code in the notes

15. 15  Create an EGL Library of XML Write Function Calls – 2 of 2  Note the following about your new Library:  There are eight functions accessible outside of the library  Several of these functions are used only once  startWriter() –Initiates the XML Engine  writBaseLevel(value string in, parm string in) –Used to insert the first element into the XML file (and only the first element)  endWriter() returns(string) –Used to Shutdown the XML Engine and return the final XML output as a string  The remaining functions are used throughout the creation of your XML file  writeElement(value string in, parm string in) –Used to insert an Element into the XML File. –Ex. writeElement(“Customer”, “Scott”);  Scott  writeComment(value string in); –Used to write comments in the XML File, comments are appended to the last Element inserted. –Ex. writeComment(“This is a Comment!”);  <!– This is a Comment   writeAttribute(a string in, b string in) –Used to give the last Element inserted an Attribute –Ex. writeAttribute(“id”, “1”);  Scott  createSiblingStructure() –Used to tell the XML engine to append the following elements to the previously inserted Element. i.e. Create a new level of depth in your XML file.  endSiblingStructure() –Used to tell the XML engine to append the following elements to the parent of the current parent Element. i.e. Return up one level of depth in your XML file.

16. 16  Create a.JSP Page to Test the New Library 1 of 3 writeXML.jsp  Create a new.JSP page, named: writeXML.jsp  From Page Designer  Change the default text Edit Page Code  Right click on the page and select Edit Page Code  Copy the code in the Notes section of the slide, and replace the boilerplate JSFHandler code  Notice we first call startWriter() to initiate the XML writing engine  writeBaseLevel() is then used to write the first element to the file  We then create a siblingStructure, which allows us to insert nodes at a deeper level (as a child to the ALLCUSTOMERS element)  Next we insert several Elements, Attributes, Comments, and even create a new sibling structure  We then end the sibling structure and loop back up (for 5 iterations)  Finally the XML file is opened via a startCMD!  Ctrl/S – save and generate

17. 17  Create a.JSP Page to Test the New Library 2 of 3  Since we will be writing to a file from our JSF Handler, we will need to add an entry to the linkage option of our buildfile!  Open your buildfile, and from the outline view, open the resource association (resAssociation)  Add a new file to the resource association  Finally, give the new file the following attributes (in the resource association)

18. 18  Create a.JSP Page to Utilize the new XML Library 3 of 3  Return to the Page Designer  Drag the xmlin array onto the page  Make sure to display the elements as input fields, except for the customer_id field  Drag the writeToXML function onto the screen as well as the query input field  adjust the size of the query field  Finally drag the query1 button onto the page with the ans array below it as output text  You are able to create an XML file, then run an XPath query on it!!

19. 19  Run On Server!