package li.earth.urchin.twic.xml;

import java.util.List;
import java.util.Map;
import org.xml.sax.SAXException;

/**
An interface for objects which wish to consume events from an XML stream.
*/
public interface XMLListener {
	
	// TODO: probably pass through full tag info, namespace and all that - don't try to solve that problem here
	
	/**
	Called when a document starts.
	*/
	public void startDocument() throws SAXException;
	
	// TODO: probably pass through full tag info, namespace and all that - don't try to solve that problem here
	
	/**
	Called when a container element starts. A container is an element which contains other elements, but no text.
	
	@param	path	the sequence of tags enclosing, and including that of, the element
	@param	attrs	the Map<String, String> of the element
	*/
	public void startContainer(List<String> path, Map<String, String> attrs) throws SAXException;
	
	/**
	Called when ann item element starts. A item element is an element which contains only text, or is empty.
	
	@param	path	the sequence of tags enclosing, and including that of, the element
	@param	attrs	the Map<String, String> of the element
	@param	text	the text of the element; the empty string if it was empty
	*/
	public void item(List<String> path, Map<String, String> attrs, String text) throws SAXException;
	
	/**
	Called when a container element ends.
	
	@param	path	the sequence of tags enclosing, and including that of, the element
	*/
	public void endContainer(List<String> path) throws SAXException;
	
	/**
	Called when a document ends.
	*/
	public void endDocument() throws SAXException;
	
}