gd.xml
Interface XMLResponder


public interface XMLResponder

Interface which must be implemented by any XML application which wishes to use the XMLParser class. It consists of a set of call back methods which are called by the XML parser when specific XML entities are encountered.

Very few of the methods return a value. Of those that do, only the DocumentStream method actually needs to return a non-null value. This makes the interface very easy to implement.

For developers unfamiliar with the concepts or terminology of XML, an introductory document on XML may help to explain some of the terms used in this documentation.

This paragraph describes the order in which the methods may be called. The getDocumentStream is always the first method called, followed by the recordDocStart method, after which comments and PI's may be received at any time until recordDocEnd method is called. All 'declaration' method calls are guaranteed to occur before any call to recordDocTypeDeclaration which is called after both the internal and external DTD's (if they existed) have been sucessfully parsed. no DTD related methods are called after the first call to recordElementStart. Each such method call is matched with a call to recordElementEnd. Character data will only be received within some element (ie. after the first element start and before the last element end). Contiguous character data may be reported in repeated calls to recordCharData.

All callbacks are made on the single thread used to start the parsing.

All character data supplied to the parser by this interface must be supplied in one of the following encodings:

See Also:
XMLParser

Method Summary
 java.io.InputStream getDocumentStream()
          This method is always called exactly once, before all other callbacks.
 void recordAttlistDeclaration(java.lang.String element, java.lang.String attr, boolean notation, java.lang.String type, java.lang.String defmod, java.lang.String def)
          This method is called when an attribute definition is parsed from an attlist tag in a DTD.
 void recordCharData(java.lang.String charData)
          This method is called to return character data to the application.
 void recordComment(java.lang.String comment)
          This method is called to return comments to the application.
 void recordDocEnd()
          This method is called to indicate that the document stream has been successfully closed.
 void recordDocStart()
          This method is called to indicate that the document stream has been opened successfully.
 void recordDoctypeDeclaration(java.lang.String name, java.lang.String pubID, java.lang.String sysID)
          This method is called after all the DTD related information is has been passed back.
 void recordElementDeclaration(java.lang.String name, java.lang.String content)
          This method is called when an element declaration is met in a DTD.
 void recordElementEnd(java.lang.String name)
          This method is called to indicate the closure of an element (tag).
 void recordElementStart(java.lang.String name, java.util.Hashtable attr)
          This method is called to indicate the start of an element (tag).
 void recordEntityDeclaration(java.lang.String name, java.lang.String value, java.lang.String pubID, java.lang.String sysID, java.lang.String notation)
          This method is called whenever an general entity declaration is parsed from a DTD.
 void recordNotationDeclaration(java.lang.String name, java.lang.String pubID, java.lang.String sysID)
          This method is called whenever a notation is parsed from a DTD.
 void recordPI(java.lang.String name, java.lang.String value)
          This method is called to passback program instructions to the application.
 java.io.InputStream resolveDTDEntity(java.lang.String name, java.lang.String pubID, java.lang.String sysID)
          This method is called to obtain an external DTD.
 java.io.InputStream resolveExternalEntity(java.lang.String name, java.lang.String pubID, java.lang.String sysID)
          This method is called when an external entity must be resolved for insertion into the document its DTD.
 

Method Detail

recordNotationDeclaration

public void recordNotationDeclaration(java.lang.String name,
                                      java.lang.String pubID,
                                      java.lang.String sysID)
                               throws ParseException
This method is called whenever a notation is parsed from a DTD.
Parameters:
name - the name of the notation
pubID - the public ID of the notation if it was specified or null otherwise
sysID - the system ID (typically filename) of the notation (or null if unspecified)

recordEntityDeclaration

public void recordEntityDeclaration(java.lang.String name,
                                    java.lang.String value,
                                    java.lang.String pubID,
                                    java.lang.String sysID,
                                    java.lang.String notation)
                             throws ParseException
This method is called whenever an general entity declaration is parsed from a DTD. Most applications will have no use for this information.
Parameters:
name - the name assigned to this entity
value - the replacement text of this entity
pubID - the public ID of the entities replacement text (or null if unspecified)
sysID - the system ID of the entities replacement text (or null if unspecified)
notation - specifies the notation associated with this entity (null if entity to be parsed as XML)

recordElementDeclaration

public void recordElementDeclaration(java.lang.String name,
                                     java.lang.String content)
                              throws ParseException
This method is called when an element declaration is met in a DTD. Most applications will have no use for this information.
Parameters:
name - the tag name given to this element
content - a regexp-like expression which specifies which elements and character data may appear within this element

recordAttlistDeclaration

public void recordAttlistDeclaration(java.lang.String element,
                                     java.lang.String attr,
                                     boolean notation,
                                     java.lang.String type,
                                     java.lang.String defmod,
                                     java.lang.String def)
                              throws ParseException
This method is called when an attribute definition is parsed from an attlist tag in a DTD. Applications may wish to record these definitions to apply default values to element tags.
Parameters:
element - the element to which this attribute applies
attr - the name of the attribute being described by this declaration
notation - the notation (if any) which applies to this attribute
type - the type of value defined by this attribute
defmod - describes the nature of this attributes default value (one of 'FIXED', 'REQUIRED', 'IMPLIED' - as per XML spec - or 'DEFAULT' indicating a 'basic' default value)
def - the default value of this attribute (may be null, indicating no default specified)

recordDoctypeDeclaration

public void recordDoctypeDeclaration(java.lang.String name,
                                     java.lang.String pubID,
                                     java.lang.String sysID)
                              throws ParseException
This method is called after all the DTD related information is has been passed back. It supplies information about the document type applied to the document.
Parameters:
name - the name of the document type
pubID - the public ID of the document type (may be null)
sysID - the system ID of the document type (null if no external DTD is specified)

recordDocStart

public void recordDocStart()
This method is called to indicate that the document stream has been opened successfully.

recordDocEnd

public void recordDocEnd()
This method is called to indicate that the document stream has been successfully closed.

recordElementStart

public void recordElementStart(java.lang.String name,
                               java.util.Hashtable attr)
                        throws ParseException
This method is called to indicate the start of an element (tag).
Parameters:
name - the name of the element (tag name)
attr - a hashtable containing the explicitly supplied attributes (as strings)

recordElementEnd

public void recordElementEnd(java.lang.String name)
                      throws ParseException
This method is called to indicate the closure of an element (tag).
Parameters:
name - the name of the element (tag) being closed

recordPI

public void recordPI(java.lang.String name,
                     java.lang.String value)
              throws ParseException
This method is called to passback program instructions to the application.
Parameters:
name - the name of the program instruction
value - the data associated with this program instruction

recordCharData

public void recordCharData(java.lang.String charData)
This method is called to return character data to the application. As per the XML specification, newlines on all platforms are converted to single 0x0A's. Contiguous character data may be returned with successive calls to this method.
Parameters:
charData - character data from the document.

recordComment

public void recordComment(java.lang.String comment)
This method is called to return comments to the application. Most applications will have no use for this information. param comment the contents of the comment tag

getDocumentStream

public java.io.InputStream getDocumentStream()
                                      throws ParseException
This method is always called exactly once, before all other callbacks. It is used to retrieve an inputstream from which the XML document will be parsed. This method may not return null.
Returns:
an InputStream which supplies the document text.

resolveExternalEntity

public java.io.InputStream resolveExternalEntity(java.lang.String name,
                                                 java.lang.String pubID,
                                                 java.lang.String sysID)
                                          throws ParseException
This method is called when an external entity must be resolved for insertion into the document its DTD. This method may return null as an indication that the application declines to retrieve the entity.
Parameters:
name - the name of the entity to be retrieved.
pubID - the public ID of the entity (may be null)
sysID - the system ID of the entity
Returns:
an InputStream which supplies the entity's replacement text

resolveDTDEntity

public java.io.InputStream resolveDTDEntity(java.lang.String name,
                                            java.lang.String pubID,
                                            java.lang.String sysID)
                                     throws ParseException
This method is called to obtain an external DTD. Most applications will simply refer this call to the resolveExternalEntity method. This separate callback method is made available, should the application need to resolve the ID's differently.
Parameters:
name - the name of the DTD
pubID - its public ID (may be null)
sysID - its system ID
Returns:
an InputStream which supplies the DTD for this document