The Toolset

The toolset covers four functional areas, comparators, attribute modifiers, character data modifiers and notifiers, represented by the base classes and base interfaces – ElementComparator, AttributesModifier, CDataModifier and for notification, specialized subclasses of these base classes which forward the data passed to them to registered target objects. Another notifier – BeanPropertySetter implements the ContentHandler interface and can be added to the ProgrammableSAXFilter as a “listener.

• ProgrammableSAXFilter - main filter object - delegate SAX events to registered tools.
  
• ElementComparator - Abstract base class which defines how elements are detected in the SAX event stream.
  
• ElementReplacer - Interface for objects which can replace a tag "on the fly".
  
• ElementModifier - Abstract base class which defines methods by which the ProgrammableSAXFilter sends messages to filter tools
  

The function of sax filter comparators is to identify elements within an XML document for processing. The first group compares element tags for match, the second are a set of boolean comparators that can be used to create compound comparison operations.

• TagComparator – matches on the entire name (uri and localName) of an element.
  
• TagAttributeComparator – matches on element name and on the presence and value of an element attribute.
  
• TagAttributesComparator – matches on the element name and a set of required attributes (name/value pairs ).
  
• TagListComparator – Can be used in one of two modes: one matches if any of a list of tag names matches the name of an element, the other matches if none of a list of tag names matches the name of an element.
  
• XPathComparator -- matches on an XML path which contains the element order to an element starting with the document root element (see XPath specification).
   
• NamespaceComparator – matches on tags with a given namespace or URI.
   

Boolean comparators – These comparators combine the effects of primary comparators or other boolean comparators, enabling the creation of compound comparison operations.

• ElementOrComparator -- matches if either one of its contained ElementComparators matches.
  
• ElementAndComparator – matches if both of its contained ElementComparators match.
  
• ElementNotComparator – matches if its contained ElementComparator does not match.
  
• ElementListComparator – can be set to AND or OR mode. If AND, matches is all of the contained ElementComparators in its list match. If OR matches if any one of its contained ElementComparators match.
  

The set of AttributesModifiers provides for attribute addition, deletion and modification as well as an implementation that can be used to provide a sequential numbering of elements.

• AttributeIncrementer – allows consecutive numbering of elements. Constructor takes a name and an initial number. _modifyAttributes method adds an attribute to each element with name=”<nextNumber>”.
  
• AttributeDeleter – deletes the attribute with the given uri and name.
  
• AttributeEditor – replaces the value of the attribute with the given uri and name, with the value supplied to its constructor.
  
• AttributesAdder – adds a new attribute with the uri, name, and value supplied to its constructor.
  
• ObjectPropertyAttributeSetter - Uses Java Reflection to get a property of an object to be used to set a tag Attribute
  

The set of CDataModifiers allows several operations to be performed on a character data segment.

• CDataDeleter – deletes the character data by setting the length of the character data segment to 0.
  
• CDataExtender -- can do either prepending or appending. Inserts an additional call to characters( ) on the target ContentHandler either at the start of an element (prepend mode) or just before the endElement method is forwarded (append mode).
  
• CDataInserter – inserts a character string either before or after a character string pattern. Can be set to insert on the first occurrence of the pattern, last occurrence or all occurrences of the pattern.
  
• CDataEditor – replaces individual words in a character string. Uses a java.util.Map to relate words to be replaced with their replacements.
  
• CDataTrimmer -- trims the character string to the substring between a start pattern and and end pattern.
  

Enable sections of an XML document to be replaced with strings, or by another SAX or DOM source.

• CDataCharReplacer – replaces one character in the character data with another.
  
• CDataReplacer – replaces the character string with new string. If a pattern string is supplied, can be set to replace the first occurrence of the pattern, last occurrence or all occurrences of the pattern.
  
• ElementTagRemover - Removes the Tag from an element, leaving just the character data.
  
• SAXElementReplacer - replaces xml element with data from a SAX parsing source. Enables merging of two XML sources.
  
• DOMElementReplacer - replaces xml element with data from a DOM source. Enables merging of two XML sources.
  
• StringElementReplacer - replaces xml element with contents of a String object.
  
• ReaderElementReplacer - replaces xml element with content of a java.io.Reader IO stream
  

The notifiers are subclasses of ElementModifier, AttributesModifier and CDataModifier. They implement the interface methods not by changing the data that is passed to them but rather use the data to send object messages to registered target objects using Java reflection techniques.

• ElementNotifier – subclass of ElementModifier. Its constructor takes a target object, a method to call on a startElement event, parameters to pass back to the target object on start, and another pair of method name/parameters to use for the endElement event.
  
• AttributeObjectPropertySetter – calls a method on a target object, passing the value of a given attribute in the method’s single String parameter.
  
• CDataObjectPropertySetter – calls a method on a target object, passing the value of the XML character data in the method’s single String parameter.
  
• BeanPropertySetter – this object implements the ContentHandler interface. Its constructor takes an element name and a java.lang.Object or a list of objects which must implement the methods conforming to the JavaBean specification, that is setX( ) methods that take a String argument. For every attribute in the parent element or character data of a child element, the BeanPropertySetter looks for a method named set or set and if found, invokes the method with the appropriate data. This provides a means of XML-to-object construction in which the target object can a) be constructed on any child element of an XML stream and b) can select the attributes and/or child element data that it requires as its properties.
  
• TagContentObjectPropertySetter - Sets the target objects property equal to an XML fragment
  
• TagContentWriter - Writes a XML tag content to a java.io.Writer stream.
  
• TagTextExtractor - enables the character data of a tag to be extracted and used to notify an object via Java reflection.
  
• TagTextWriter - writes an XML tag's character data to a java.io.Writer stream.
  

• SAXOutputter - Converts SAX event stream to an character stream
  
• SAXSplitter - converts child elements of an XML element to a list of XML String objects
  
• SAXWriter - converts SAX event stream to a java.io.Writer character stream
  

• XMLFilterInputStream - enables a SAX filter to be inserted into a java.io.InputStream pipeline.
  
• XMLFilterOutputStream - enables a SAX filter to be inserted into a java.io.OutputStream pipeline
  

• XSLTFilter - glue object which enables two XSLT filters to be joined, needed to maintain a filter stream using the javax.xml.transform interfaces.
  
• VerboseSAXFilter - diagnostic object - reports all SAX events passing though the filter stream.