1. Simple API for XML (SAX) Aug’10 – Dec ’10

2. Introduction to SAX Simple API for XML or SAX was developed as a standardized way to parse an XML document Simple API for XML or SAX was developed as a standardized way to parse an XML document To enable more efficient analysis of large XML documents To enable more efficient analysis of large XML documents This chapter covers the following ❑ What is SAX ❑ Where to download and how to set it up ❑ How and when to use the primary SAX Interfaces Aug’10 – Dec ’10

3. Problem with DOM Before traversing starts, it has to build up a massive in-memory map of the document Before traversing starts, it has to build up a massive in-memory map of the document This takes up space and time This takes up space and time If used to extract small amount of information from the document, this can be extremely difficult If used to extract small amount of information from the document, this can be extremely difficult Better suited for small XML documents Better suited for small XML documents Aug’10 – Dec ’10

4. How SAX works As the XML parser parses the documents, it returns a stream of events back to the application As the XML parser parses the documents, it returns a stream of events back to the application There are events for start of the document, end of the document, start and end of each element, contents of each element etc There are events for start of the document, end of the document, start and end of each element, contents of each element etc Once started, cannot interrupt the parser to go back and look at an earlier part of the document Once started, cannot interrupt the parser to go back and look at an earlier part of the document Unlike DOM, which gives access to the entire document at once, SAX stores little or nothing from event to event Unlike DOM, which gives access to the entire document at once, SAX stores little or nothing from event to event This makes SAX faster compared to DOM This makes SAX faster compared to DOM Aug’10 – Dec ’10

5. Where to get SAX SAX is specified as a set of JAVA interfaces SAX is specified as a set of JAVA interfaces Downloads available at http://saxproject.org Downloads available at http://saxproject.orghttp://saxproject.org Xerces-J – Parser developed to work with SAX Xerces-J – Parser developed to work with SAX Downloads available at http://xml.apache.org/xerces-j Needs Java Development Kit, release 1.1 or later Needs Java Development Kit, release 1.1 or later Aug’10 – Dec ’10

6. Receiving SAX Events Write Java class that implements one of the SAX Interfaces Write Java class that implements one of the SAX Interfaces public class Myclass implements ContentHandler ContentHandler is the name of the interface. Most important interface in SAX ContentHandler is the name of the interface. Most important interface in SAX ContentHandler interface defines the callback methods for content related events ContentHandler interface defines the callback methods for content related events Better to use DefaultHandler class– provides default implementations of functions in ContentHandler interface Better to use DefaultHandler class– provides default implementations of functions in ContentHandler interface public class Myclass extends DefaultHandler Aug’10 – Dec ’10

7. ContentHandler Interface Designed to control the reporting of events for the content of the document Designed to control the reporting of events for the content of the document Includes information about text, attributes, processing instructions, elements and the document itself Includes information about text, attributes, processing instructions, elements and the document itself ContentHandler Methods Event Description startDocument Event to notify the application that the parser has read the start of the document endDocument Event to notify the application that the parser has read the end of the document startElement Event to notify the application that the parser has read an element start-tag Aug’10 – Dec ’10

8. EventDescription endElement Event to notify the application that the parser has read an element end-tag. skippedEntityEvent to notify the application that the parser has skipped an external entity processingInstructionEvent to notify the application that the parser has read a processing instruction startPrefixMappingEvent to notify the application that the parser has read an XML namespace declaration, and that a new namespace prefix is in scope Aug’10 – Dec ’10 ContentHandler Interface

9. Example : TrainReader createXMLReader function createXMLReader function XMLReader reader = XMLReaderFactory.createXMLReader( “org.apache.xerces.parsers.SAXParser” ); Creates an XMLReader object using a factory helper object by sending a registered parser name to the factory function setContentHandler function setContentHandler functionreader.setContentHandler(this); To tell the XMLReader which class should receive events about the content of the XML document Aug’10 – Dec ’10

10. Handling Element Events startElement function startElement function public void startElement(String uri, String localName, String qName, Attributes atts) The first three parameters help to identify the element the parser encountered The fourth parameter Attributes – to lookup attributes and values endElement function endElement function public void endElement(String uri, String localName, String qName) Aug’10 – Dec ’10

11. Handling Element Events startElement startElement The first three paramters help identify the element based on its namespace name and local name or by its prefix This behavior allows to identify similar elements in different vocabularies If the parser encounters the following element : If the parser encounters the following element : http://example.com uri http://example.com http://example.com localNamemyElement qNamemyPrefix:myElement If there is no prefix for element name, then the localName and qName should be the same Aug’10 – Dec ’10

12. Handling Element Events Attributes Attributes The Attributes interface gives the ability to easily lookup the attributes and their values at the start of each element The default Attrributes interface provides the following functions : getLengthDetermine the number of attributes available in the Attributes interface getLengthDetermine the number of attributes available in the Attributes interface getIndexRetrieves the index of a specific attribute in the list. Uses attribute’s qualified name or both local name and namespace URI getIndexRetrieves the index of a specific attribute in the list. Uses attribute’s qualified name or both local name and namespace URI getLocalNameRetrieves a specific attribute’s local name by sending the index in the list. getLocalNameRetrieves a specific attribute’s local name by sending the index in the list. getQnameRetrieves a specific attribute’s qualified name by sending the index in the list. getQnameRetrieves a specific attribute’s qualified name by sending the index in the list. getURIRetrieve a specif attribute’s namespace URI by sending the index in the list. getURIRetrieve a specif attribute’s namespace URI by sending the index in the list. Aug’10 – Dec ’10

13. Handling Element Events getTypeRetrieve a specific attribute’s type by sending the index in the list, by using the attribute’s qualified name, or by using both the local name and the namespace URI. getTypeRetrieve a specific attribute’s type by sending the index in the list, by using the attribute’s qualified name, or by using both the local name and the namespace URI. If there is no DTD, this function will always return CDATA getValueRetrieve a specific attribute’s value by sending the index in the list, by using the attribute’s qualified name, or by using both the local name and the namespace URI. getValueRetrieve a specific attribute’s value by sending the index in the list, by using the attribute’s qualified name, or by using both the local name and the namespace URI. Some parsers expose extended behavior through an interface called Attributes2, which allows to check Some parsers expose extended behavior through an interface called Attributes2, which allows to check whether an attribute was declared in a DTD whether an attribute was declared in a DTD whether or not the attribute value appeared in the XML document whether or not the attribute value appeared in the XML document if it appeared because of a DTD attribute default declaration if it appeared because of a DTD attribute default declaration Aug’10 – Dec ’10

14. Element and Attribute Events public void startElement(String uri, String localName, String qName, Attributes atts) throws SAXException {if(localName.equals(“car”)){ if(atts != null) { System.out.println(“Car: “ + atts.getValue(“type”)); }}} Output : Running train reader Start of the train Car : Engine Car : Baggage Car : Dining End of the train Aug’10 – Dec ’10

15. Handling Character Content public void characters(char[] ch, int start, int len) throws SAXException To retrieve character content between two tags To retrieve character content between two tags Characters are delivered as a buffer Characters are delivered as a buffer start and len indicates the starting position and length of data to be read if it is going to be copied from the buffer start and len indicates the starting position and length of data to be read if it is going to be copied from the buffer Parser reports the characters for an element in multiple chunks Parser reports the characters for an element in multiple chunks Aug’10 – Dec ’10

16. Handling Character Content To retrieve character content in color tag in train.xml private boolean isColor; private String trainCarType = “”; private StringBuffer trainCarColor = new StringBuffer(); public void startElement(String uri, String localName, String qName, Attributes atts) throws SAXException {if(localName.equals(“car”)){ if(atts ! = null) trainCarType = atts.getValue(“type”); }if(localName.equals(“color”)){trainCarColor.setLength(0); isColor = true; }else isColor = false; } Aug’10 – Dec ’10

17. Handling Character Content public void characters(char[] ch, int start, int len) throws SAXException {if(isColor)trainCarColor.append(ch,start,len);} public void endElement(String uri, String localName, String qName) throws SAXException {if(isColor){ System.out.println(“The color of the” + trainCarType + “ car is “ + trainCarColor.toString()); }} Aug’10 – Dec ’10

18. Handling Character Content Output: Running train reader Start of the train The color of the Engine car is Black The color of the Baggage car is Green The color of the Dining car is Green and Yellow End of the train Aug’10 – Dec ’10

19. When to ignore IgnorableWhitespace public void ignorableWhitespace(char[] ch, int start, int len) throws SAXException Similar to characters event Similar to characters event Parser may call this function multiple times within a single element Parser may call this function multiple times within a single element Whitespaces such as spaces, tabs and line feeds which are used to make the xml document more readable are often not important to the application Whitespaces such as spaces, tabs and line feeds which are used to make the xml document more readable are often not important to the application <color>Black</color> 512 tons 512 tons </car> Aug’10 – Dec ’10

20. When to ignore IgnorableWhitespace The only way for the SAX parser to know that the whitespace is ignorable is when an element is declared in DTD to not contain PCDATA The only way for the SAX parser to know that the whitespace is ignorable is when an element is declared in DTD to not contain PCDATA Only validating parsers can report this event Only validating parsers can report this event If parser has no knowledge of the DTD, then it assumes that all character data including whitespace is important If parser has no knowledge of the DTD, then it assumes that all character data including whitespace is important Aug’10 – Dec ’10

21. Skipped Entities Alerts the application that the SAX parser has encountered information that the application can or must skip Alerts the application that the SAX parser has encountered information that the application can or must skip An entity can be skipped for several reasons : - An entity can be skipped for several reasons : -  The entity is a reference to an external resource that cannot be parsed or cannot be found  The entity is an external general entity and the http://xml.org/sax/features/external-general-entities feature is set to false http://xml.org/sax/features/external-general-entities  The entity is an external parameter entity and the http://xml.org/sax/features/external-parameter-entities feature is set to false http://xml.org/sax/features/external-parameter-entities public void skippedEntity (String name) throws SAXException public void skippedEntity (String name) throws SAXException Aug’10 – Dec ’10

22. Skipped Entities The skippedEntity event is declared as follows:- The skippedEntity event is declared as follows:- public void skippedEntity (String name) throws SAXException The name parameter is the name of the entity that was skipped The name parameter is the name of the entity that was skipped The name parameter will begin with “%” in case of a parameter entity The name parameter will begin with “%” in case of a parameter entity SAX considers the external DTD subset an entity SAX considers the external DTD subset an entity If the name parameter is “[dtd]” it means the external DTD subset was not processed. If the name parameter is “[dtd]” it means the external DTD subset was not processed. Aug’10 – Dec ’10

23. Processing Instructions To pass specific instructions to applications To pass specific instructions to applications SAX allows to receive these special instructions in application through the processingInstruction event SAX allows to receive these special instructions in application through the processingInstruction event public void processingInstruction (String target, String data) throws SAXException If the processing instruction in the XML document is as follows : target -TrainApplication data- instructionForTrainPrograms XML declaration is not a processing instruction XML declaration is not a processing instruction Aug’10 – Dec ’10

24. Namespace Prefixes SAX processors fire a startPrefixMapping and endPrefixMapping event for any namespace declaration SAX processors fire a startPrefixMapping and endPrefixMapping event for any namespace declaration public void startPrefixMapping (String prefix, String uri) throws SAXException public void endPrefixMapping (String prefix) throws SAXException The prefix parameter is the namespace prefix that is being declared In case of a default namespace declaration, the prefix should be an empty string The uri parameter is the namespace URI that is being declared xmlns:example = http://example.com prefix -example uri-http://example.com Aug’10 – Dec ’10

25. Stopping the process in exceptional circumstances To stop processing, create and throw new SAXException To stop processing, create and throw new SAXException For example, to check and throw exception if the Engine color is not Black For example, to check and throw exception if the Engine color is not Black public void endElement(String uri, String localName, String qName) throws SAXException {if(isColor){ System.out.println(“The color of the “ + trainCarType + “ car is “+trainCarColor.toString()); System.out.println(“The color of the “ + trainCarType + “ car is “+trainCarColor.toString()); if ((trainCarType.equals(“Engine”)) && (!trainCarColor.toString().equals(“Black”)) if ((trainCarType.equals(“Engine”)) && (!trainCarColor.toString().equals(“Black”)) { throw new SAXException(“The engine is not black ! “); }} isColor = false; } If the Engine color is not Black, parsing process will be stopped. If the Engine color is not Black, parsing process will be stopped. Aug’10 – Dec ’10

26. Stopping the process in exceptional circumstances Output: Running train reader.. Start of the train The color of the Engine car is Red Exception in thread “main” org.xml.sax.SAXException : The engine is not black ! at TrainReader.endElement (TrainReader.java:80) at org.apache.xerces….... at TrainReader.read at TrainReader.main When the exception is raised it stops the whole application When the exception is raised it stops the whole application This is because the exception is not handled anywhere This is because the exception is not handled anywhere Aug’10 – Dec ’10

27. Stopping the process in exceptional circumstances Add a try..catch block to handle exception Add a try..catch block to handle exception public void read (String filename) throws Exception { XMLReader reader = XMLReaderFactory.createXMLReader( “org.apache.xerces.parsers.SAXParser”); reader.setContentHandler(this);try{reader.parse(fileName);} catch (SAXException e) { System.out.println(“Parsing stopped ! “ + e.getmessage()); }} Output: Output: Running train reader.. Start of the train The color of the Engine car is Red Parsing stopped ! The engine is not black ! Aug’10 – Dec ’10

28. Providing the location of the Error SAX can provide line number and column position information of the error using setDocumentLocator event SAX can provide line number and column position information of the error using setDocumentLocator event setDocumentLocator event allows the parser to pass the application a Locator interface setDocumentLocator event allows the parser to pass the application a Locator interface The methods of the Locator object include : The methods of the Locator object include : getLineNumberRetrieves the line number for the current event getColumnNumberRetrieves the column number for the current event getSystemIdRetrieves the system identifier of the document for the current event getPublicIdRetrieves the public identifier of the document for the current event Aug’10 – Dec ’10

29. Providing the location of the Error private Locator trainLocator = null; public void setDocumentLocator (Locator loc) { trainLocator = loc; } public void endElement(String uri, String localName, String qName) throws SAXException {if(isColor){ System.out.println(“The color of the “ + trainCarType + “ car is “+trainCarColor.toString()); System.out.println(“The color of the “ + trainCarType + “ car is “+trainCarColor.toString()); if ((trainCarType.equals(“Engine”)) && (!trainCarColor.toString().equals(“Black”)) if ((trainCarType.equals(“Engine”)) && (!trainCarColor.toString().equals(“Black”)) { if (trainLocator != null) throw new SAXException(“The engine is not black ! at line “ + trainLocator.getLineNumber() + “, column” + trainLocator.getColumnNumber() ); }} isColor = false; } Aug’10 – Dec ’10

30. Providing the location of the Error Output : Running train reader.. Start of the train The color of the Engine car is Red Parsing stopped ! The engine is not black ! at line 4, column 20 Locator object : - easily notify the user where the error occurred in the XML document The information provided by the Locator object is not always absolute Aug’10 – Dec ’10

31. ErrorHandler Interface To receive error events To receive error events Add call to setErrorHandler and set validation feature Add call to setErrorHandler and set validation feature warning Allows the parser to notify the application of a warning it has encountered in the parsing process errorAllows the parser to notify the application that it has encountered an error. Even though the parser has encountered an error, parsing can continue. fatalErrorAllows the parser to notify the application that it has encountered a fatal error and cannot continue parsing. Well-formedness errors are reported through this event Aug’10 – Dec ’10

32. ErrorHandler Interface Add internal DTD to validate the document <!DOCTYPE train [ ]> Aug’10 – Dec ’10

33. ErrorHandler Interface Modifying read function public void read(String fileName) throws Exception { XMLReader reader = XMLReaderFactory.createXMLReader("org.apache.xerces.parsers.SAXParser "); reader.setContentHandler(this);reader.setErrorHandler(this);try{ reader.setFeature( “http://xml.org/sax/features/validation”, true); http://xml.org/sax/features/validation } catch(SAXException e) { System.err.println(“Cannot activate validation”); }try{reader.parse(fileName);} catch(SAXException e) { System.out.println(“Parsing stopped ! “ + e.getMessage()); }} Aug’10 – Dec ’10

34. ErrorHandler Interface Add Error Handling Functions public void warning (SAXParseException exception) throws SAXException { System.err.println(“[Warning]“ + exception.getMessage() + “ at line “ + exception.getLineNumber() + “, column “ + exception.getColumnNumber()); } public void error (SAXParseException exception) throws SAXException { System.err.println(“[Error]“ + exception.getMessage() + “ at line “ + exception.getLineNumber() + “, column “ + exception.getColumnNumber()); } public void fatalError (SAXParseException exception) throws SAXException { System.err.println(“[Fatal Error]“ + exception.getMessage() + “ at line “ + exception.getLineNumber() + “, column “ + exception.getColumnNumber()); throw exception; } Introduce Errors into the XML document and check : Change Element to new Element name Remove closing > bracket for tag – Violating Well formedness Aug’10 – Dec ’10

35. DTDHandler Interface To receive events about declarations To receive events about declarations It supports generating events for only notations and unparsed entities It supports generating events for only notations and unparsed entities NotationDecl Allows the parser to notify the application that it has read a notation declaration UnparsedEntityDeclAllows the parser to notify the application that it has read an unparsed entity declaration. Events for declarations of elements, attributes and internal entities are made available in one of the extension interfaces, DeclHandler Events for declarations of elements, attributes and internal entities are made available in one of the extension interfaces, DeclHandler To use the DTDHandler interface, To use the DTDHandler interface,reader.setDTDHandler(this); Aug’10 – Dec ’10

36. EntityResolver Interface Allows to control how a SAX parser behaves when it attempts to resolve external entity references within the DTD. Allows to control how a SAX parser behaves when it attempts to resolve external entity references within the DTD. The EntityResolver interface defines one function: The EntityResolver interface defines one function: resolveEntityAllows the application to handle the resolution of entity lookups for the parser To use EntityResolver interface : To use EntityResolver interface :reader.setEntityResolver(this); Allows application to control how the processor opens and connects to external resources. Allows application to control how the processor opens and connects to external resources. Aug’10 – Dec ’10

37. Features and Properties Some behavior of SAX parsers is controlled through setting features and properties Working with Features To change the value of a feature in SAX, call the setFeature function of the XMLReader To change the value of a feature in SAX, call the setFeature function of the XMLReader public void setFeature(String name, boolean value) throws SAXNotRecognizedException, SAXNotSupportedException Parsers may not support or recognize every feature Parsers may not support or recognize every feature The getFeature function allows to check the value of any feature The getFeature function allows to check the value of any feature public boolean getFeature (String name) throws SAXNotRecognizedException, SAXNotSupportedException Aug’10 – Dec ’10

38. Features and Properties Working with Features http://xml.org/sax/features/validation Controls whether or not the parser will validate the document as it parses http://xml.org/sax/features/external-general-entities Controls whether or not external general entities should be processed http://xml.org/sax/features/external-parameter-entities Controls whether or not external parameter entities should be processed http://xml.org/sax/features/xml-1.1 Read-only property that returns true if the parser supports XML 1.1 and XML 1.0 Aug’10 – Dec ’10

39. Features and Properties Working with Properties Used to connect helper objects to an XMLReader Used to connect helper objects to an XMLReader SAX comes with an extension set of interfaces called DeclHandler and LexicalHandler that’s allows to receive additional events about the XML document SAX comes with an extension set of interfaces called DeclHandler and LexicalHandler that’s allows to receive additional events about the XML document The only way to register these events with the XMLReader is through the setProperty function The only way to register these events with the XMLReader is through the setProperty function public void setProperty(String name, Object value) throws SAXNotRecognizedException, SAXNotSupportedException public object getProperty(String name) throws SAXNotRecognizedException, SAXNotSupportedException Aug’10 – Dec ’10

40. Features and Properties Working with Properties http://xml.org/sax/properties/declaration-handler Specifies the DeclHandler object registered to receive events for declarations within the DTD http://xml.org/sax/properties/lexical-handler xml.org/sax/properties/lexical-handler Specifies the LexicalHandler object registered to receive lexical events such as comments, CDATA sections and entity references http://xml.org/sax/properties/document-xml-version Read-only property that describes the actual version of the XML document such as “1.0” or “1.1” Aug’10 – Dec ’10

41. Extension Interfaces DeclHandler Interface – for declarations within the DTD The DeclHandler interface declares the following events: The DeclHandler interface declares the following events: AttributeDeclAllows the parser to notify the application that it has read an attribute declaration ElementDeclAllows the parser to notify the application that it has read an element declaration ExternalEntityDeclAllows the parser to notify the application that it has read an external entity declaration InternalEntityDeclAllows the parser to notify the application that it has read an internal entity declaration Aug’10 – Dec ’10

42. Extension Interfaces LexicalHandler Interface – for lexical events The LexicalHandler interface declares the following events: The LexicalHandler interface declares the following events: commentAllows the parser to notify the application that it has read a comment startCDATAAllows the parser to notify the application that it has encountered a CDATA section start marker endCDATAAllows the parser to notify the application that it has encountered a CDATA section end marker Other events supported are startDTD, endDTD, startEntity, endEntity To register, reader.setProperty(“http://xml.org/sax/properties/lexical-handler”, this); http://xml.org/sax/properties/lexical-handler Aug’10 – Dec ’10

43. Good SAX and Bad SAX Advantages Simple Simple Doesn’t load the whole document into memory Doesn’t load the whole document into memory The parser has a smaller footprint than DOM The parser has a smaller footprint than DOM It is faster It is faster Focuses on real content rather than the way it is laid out Focuses on real content rather than the way it is laid out Good for filtering data and lets concentrate on the subset of interest Good for filtering data and lets concentrate on the subset of interest Aug’10 – Dec ’10

44. Good SAX and Bad SAX Disadvantages Receive the data in the order SAX gives. Absolutely no control over the order in which the parser searches Receive the data in the order SAX gives. Absolutely no control over the order in which the parser searches SAX programming requires fairly intricate state keeping SAX programming requires fairly intricate state keeping If the focus is on analyzing an entire document, DOM is much better If the focus is on analyzing an entire document, DOM is much better Aug’10 – Dec ’10

45. Consumers, Producers and Filters In addition to consuming events from an XMLReader, it is possible to write a class that produce SAX events In addition to consuming events from an XMLReader, it is possible to write a class that produce SAX events eg: class that reads a comma-delimited file and fires SAX events Can filter events as they pass from XMLReader to event handler Can filter events as they pass from XMLReader to event handler A SAX filter acts as a middleman between the parser and the application A SAX filter acts as a middleman between the parser and the application Filters can insert, remove or modify events before passing them on to the application Filters can insert, remove or modify events before passing them on to the application Aug’10 – Dec ’10 Other Languages C++, Perl, Python, Pascal, Visual Basic,.NET, Curl