5
Compression for Java

Because XML files typically have repeated tags, compression of a streaming of XML structure and tokenizing of the XML tags can be very effective. Since it parses documents in real time, without waiting for the complete document to be read first, compression and decompression yield high performance benefits when exchanging a document over the internet between two sub-systems. XML compression retains the structural and hierarchical information of the XML data in the compressed format.

This chapter describes the oracle.xml.parser.v2 package classes responsible for compression:

• CXMLHandlerBase Class
• CXMLParser Class

  See Also: Oracle9i XML Developer's Kits Guide - XDK Oracle9i Supplied Java Packages Reference

---

CXMLHandlerBase Class

---

Description of CXMLHandlerBase

The SAX compression is implemented using SAX Handler, which compresses the data based on SAX events. To use the SAX compression, the application needs to implement this interface and register with the SAX parser through the Parser.setDocumentHandler().

---

Syntax of CXMLHandlerBase

public class CXMLHandlerBase implements oracle.xml.parser.v2.XMLDocumentHandler
 
oracle.xml.comp.CXMLHandlerBase

---

Implemented Interfaces of CXMLHandlerBase

oracle.xml.parser.v2.XMLDocumentHandler

---

Methods of CXMLHandlerBase

Table 5-1 Summary of Methods of CXMLHandlerBase  

Method	Description
CXMLHandlerBase()	Creates a new CXMLHandlerBase.
cDATASection()	Receives notification of a CDATA Section.
characters()	Receives notification of Character Data inside an element.
comment()	Receives notification of Comment.
endDoctype()	Receives notification of end of the DTD.
endDocument()	Receives notification of end of the Document.
endElement()	Receives notification of end of the Element.
endPrefixMapping()	Receives notification of end of scope of Prefix Mapping.
getCXMLContext()	Returns the CXML Context used for compression.
getProperty()	Looks up and returns the value of a property.
ignorableWhitespace()	Receives notification of ignorable whitespace in element content.
processingInstruction()	Receives notification of a processing instruction.
setDoctype()	Sets DTD to receive notification of that DTD.
setDocumentLocator()	Sets Locator to receive that Locator object for the document event.
setError()	Sets XMLError handler to receive notification of that XMLError handler.
setProperty()	Sets the value of a property.
setTextDecl()	Sets Text XML Declaration to receive notification of that Text XML Declaration.
setXMLDecl()	Sets XML Declaration to receive notification of that XML Declaration.
setXMLSchema()	Sets XMLSchema to receive notification of that XMLSchema object.
skippedEntity()	Receives notification of a skipped entity.
startDocument()	Receives notification of the beginning of the document.
startElement()	Receives notification of the beginning of an element.
startPrefixMapping()	Receives notification of the beginning of the scope of prefix URI mapping.

CXMLHandlerBase()

Description

Creates a new CXMLHandlerBase. The options are described in the following table.

Syntax	Description
public CXMLHandlerBase();	Default Constructor. Creates a new CXMLHandlerBase.
public CXMLHandlerBase( ObjectOutput out);	Constructs the CXMLHandlerBase using the ObjectOutput stream
public CXMLHandlerBase( oracle.xml.io.XMLObjectOutput out);	Constructs the CXMLHandlerBase using the XMLObjectOutputStream.

Parameter	Description
out	The output stream.

cDATASection()

Description

Receives notification of a CDATA Section. The Parser will invoke this method once for each CDATA Section found. Throws org.xml.sax.SAXException, which can be any SAX exception, possibly wrapping another exception.

Syntax

public void cDATASection( char[] cbuf,
                          int start,
                          int len);

Parameter	Description
cbuf	The CDATA section characters.
start	The start position in the character array.
len	The number of characters to use from the character array.

characters()

Description

Receives notification of character data inside an element.

Syntax

public void characters( char[] cbuf,
                        int start,
                        int len);

Parameter	Description
cbuf	Characters
start	The starting position in the character array.
len	The number of characters to use from the character array.

comment()

Description

Receives notification of a comment. The Parser will invoke this method once for each comment found: note that comment may occur before or after the main document element. Throws org.xml.sax.SAXException, which can be any SAX exception, possibly wrapping another exception.

Syntax

public void comment( String text);

Parameter	Description
text	The comment data; NULL if none is supplied.

endDoctype()

Description

Receives notification of end of the DTD. Throws org.xml.sax.SAXException, which can be any SAX exception, possibly wrapping another exception.

Syntax

public void endDoctype();

endDocument()

Description

Receives notification of the end of the document. Throws org.xml.sax.SAXException, which can be any SAX exception, possibly wrapping another exception.

Syntax

public void endDocument();

endElement()

Description

Receives notification of the end of the element.

Syntax

public void endElement( oracle.xml.parser.v2.NSName elem);

Parameter	Description
elem	The element.

endPrefixMapping()

Description

Receives notification of the end of scope of prefix URI mapping.

Syntax

public void endPrefixMapping( String prefix);

Parameter	Description
prefix	The prefix that was being mapped.

getCXMLContext()

Description

Returns the CXML Context used for compression.

Syntax

public oracle.xml.comp.CXMLContext getCXMLContext();

getProperty()

Description

Looks up and returns the value of a property. The property name is any fully-qualified URI.

Syntax

public java.lang.Object getProperty( String name);

Parameter	Description
name	The property name, which is a fully-qualified URI.

ignorableWhitespace()

Description

Receives notification of ignorable whitespace in element content.

Syntax

public void ignorableWhitespace( char[] cbuf,
                                 int start,
                                 int len);

Parameter	Description
cbuf	The Character from XML document.
start	The start position in the array.
len	The number of characters to read from the array.

processingInstruction()

Description

Receives notification of a processing instruction.

Syntax

public void processingInstruction( String target,
                                   String data);

Parameter	Description
target	The processing instruction target.
data	The processing instruction data.

setDoctype()

Description

Registers DTD so can subsequently receive notification on that DTD. The Parser will invoke this method after calling startDocument() to register the DTD used. Throws org.xml.sax.SAXException, which can be any SAX exception, possibly wrapping another exception.

Syntax

public void setDoctype( oracle.xml.parser.v2.DTD dtd);

Parameter	Description
dtd	The DTD node.

setDocumentLocator()

Description

Registers Locator object so can subsequently receive notification for that Locator object for the document event. By default, do nothing. This method could be overridden by the subclasses events.

Syntax

public void setDocumentLocator( org.xml.sax.Locator locator);

Parameter	Description
locator	The locator for the SAX document events.

setError()

Description

Registers XMLError handler so can subsequently receive notification of that XMLError handler. Throws org.xml.sax.SAXException, which can be any SAX exception, possibly wrapping another exception.

Syntax

public void setError( oracle.xml.parser.v2.XMLError he);

Parameter	Description
he	The XMLError object.

setProperty()

Description

Sets the value of a property. The property name is any fully-qualified URI.

Syntax

public void setProperty( String name,
                         Object value);

Parameter	Description
name	The property name, which is a fully-qualified URI.
value	The requested value for the property.

setTextDecl()

Description

Registers Text XML Declaration so can subsequently receive notification of that Text XML Declaration. The Parser will invoke this method once for each text XMLDecl. Throws org.xml.sax.SAXException, which can be any SAX exception, possibly wrapping another exception.

Syntax

public void setTextDecl( String version,  
                         String encoding);

Parameter	Description
version	The version number; NULL if not specified.
encoding	The encoding name.

setXMLDecl()

Description

Registers XML Declaration so can subsequently receive notification of that XML Declaration. The Parser will invoke this method once for XMLDecl. Throws org.xml.sax.SAXException, which can be any SAX exception, possibly wrapping another exception.

Syntax

public void setXMLDecl( String version,
                        String standalone,
                        String encoding);

Parameter	Description
version	The version number.
standalone	The standalone value; NULL if not specified.
encoding	The encoding name; NULL if not specified.

setXMLSchema()

Description

Registers XMLSchema so can subsequently receive notification of that XMLSchema object. Throws org.xml.sax.SAXException, which can be any SAX exception, possibly wrapping another exception.

Syntax

public void setXMLSchema( Object s);

Parameter	Description
s	The XMLSchema object.

skippedEntity()

Description

public void skippedEntity( String name);

Syntax

Receives notification of a skipped entity. The Parser will invoke this method once for each entity skipped. Non-validating processors may skip entities if they have not seen the declarations (because, for example, the entity was declared in an external DTD subset). All processors may skip external entities, depending on the values of the external-general-entities and the external-parameter-entities properties. Throws org.xml.sax.SAXException, which can be any SAX exception, possibly wrapping another exception.

Parameter	Description
name	The name of the skipped entity. If it is a parameter entity, the name will begin with '%', and if it is the external DTD subset, it will be the string "[dtd]".

startDocument()

Description

Receives notification of the beginning of the document. By default, do nothing. This method could be overridden by the subclasses to take specific actions at the beginning of a document.

Syntax

public void startDocument();

startElement()

Description

Receives notification of the beginning of an element.

Syntax

public void startElement( oracle.xml.parser.v2.NSName elem,
                          oracle.xml.parser.v2.SAXAttrList attributes);

Parameter	Description
elem	The element.
attributes	Attributes of the element.

startPrefixMapping()

Description

Receives notification of the beginning of the scope of prefix URI mapping.

Syntax

public void startPrefixMapping( String prefix,
                                String uri);

Parameter	Description
prefix	The Namespace prefix being declared.
uri	The Namespace URI to which the prefix is mapped.

---

CXMLParser Class

---

Description of CXMLParser

This class implements the re-generation of XML document from the compressed stream by generating the SAX events from them.

---

Syntax of CXMLParser

public class CXMLParser

oracle.xml.comp.CXMLParser

---

Methods of CXMLParser

Table 5-2 Summary of Methods of CXMLHandlerBase  

Method	Description
startPrefixMapping()	Creates a new XML Parser object for reading the compressed stream.
CXMLParser()	Retrieves content handler.
getContentHandler()	Retrieves the current error handler.
getErrorHandler()	Parses the compressed stream and generates the SAX events.
parse()	Parses the compressed stream and generates the SAX events.
setContentHandler()	Registers a content event handler.
setErrorHandler()	Registers an error event handler.

CXMLParser()

Description

Creates a new XML Parser object for reading the compressed stream.

Syntax

public  CXMLParser();

getContentHandler()

Description

Retrieves content handler; returns NULL if the handler has not been registered.

Syntax

public org.xml.sax.ContentHandler getContentHandler();

getErrorHandler()

Description

Retrieves the current error handler; returns NULL if the handler has not been registered.

Syntax

public org.xml.sax.ErrorHandler getErrorHandler();

parse()

Description

Parses the compressed stream and generates the SAX events. Throws the following exceptions:

• SAXException - any SAX exception
• IOException - an error due to I/O operations

Syntax

public void parse( String inFile);

Parameter	Description
inFile	The input source which needs to be parsed to regenerate the SAX events.

setContentHandler()

Description

Registers a content event handler.

Syntax

public void setContentHandler( org.xml.sax.ContentHandler handler);

Parameter	Description
handler	The content handler

setErrorHandler()

Description

Registers an error event handler.

Syntax

public void setErrorHandler( org.xml.sax.ErrorHandler handler);

Parameter	Description
handler	The error handler