KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > sapia > util > xml > parser > HandlerContextIF


1 package org.sapia.util.xml.parser;
2
3
4 // Imports of David Meggison's SAX classes
5
// ---------------------------------------
6
import org.xml.sax.Attributes JavaDoc;
7 import org.xml.sax.SAXException JavaDoc;
8
9
10 /**
11  * The <CODE>HandlerContextIF</CODE> interface represents the context in which the
12  * handlers of SAX events are stacked. It provides methods set the current and remove
13  * a <CODE>HandlerStateIF</CODE> object. This context behaves like a stack where each
14  * new handler added to this context becomes the "current" one. When you remove that
15  * current state, the previous state now becomes the "current" one.<p>
16  *
17  * This context also provides a way to gather results generated by the different
18  * handler that it contains. For more detail see the methods <CODE>setResultFor()</CODE>
19  * and <CODE>getResultFor()</CODE>.
20  *
21  * @see HandlerStateIF
22  * @see StatefullSAXHandler
23  * @author Jean-Cedric Desrochers
24  *
25  * <dl>
26  * <dt><b>Copyright:</b><dd>Copyright &#169; 2002-2003 <a HREF="http://www.sapia-oss.org">Sapia Open Source Software</a>. All Rights Reserved.</dd></dt>
27  * <dt><b>License:</b><dd>Read the license.txt file of the jar or visit the
28  * <a HREF="http://www.sapia-oss.org/license.html">license page</a> at the Sapia OSS web site</dd></dt>
29  * </dl>
30  */

31 public interface HandlerContextIF {
32   /**
33    * Returns the current handler state of this context.
34    *
35    * @return The current handler state of this context.
36    */

37   public HandlerStateIF getCurrentState();
38
39   /**
40    * Changes the current handler state to the handler state passed in. The collection
41    * of state objects needs to behave like a stack (LIFO - Last in, first out) in
42    * order to go back to the previous state of a handler.<P>
43    *
44    * The handler context will notify the child handler state of the start of the element
45    * by calling it's <CODE>startElement()</CODE> method passing the arguments received.
46    *
47    * @param aHandlerState The new current handler state.
48    * @param anUri The namespace URI of the element that starts.
49    * @param aLocalName The local name of the element that starts.
50    * @param aQualifiedName The qualified name of the element that starts.
51    * @param someAttributes The attributes of the element that starts.
52    * @exception SAXException If an error occurs while setting the new handler state.
53    */

54   public void setCurrentState(HandlerStateIF aHandlerState, String JavaDoc anUri,
55     String JavaDoc aLocalName, String JavaDoc aQualifiedName, Attributes JavaDoc someAttributes)
56     throws SAXException JavaDoc;
57
58   /**
59    * Removes the current handler state from this handler context. The previous handler
60    * state becomes the current state.<P>
61    *
62    * The handler context will notify the parent handler state of the end of the
63    * element by calling it's <CODE>endElement()</CODE> method passing the arguments
64    * received.
65    *
66    * @param anURI The namespace URI of the element that closes.
67    * @param aLocalName The local name of the element that closes.
68    * @param aQualifiedName The qualified name of the element that closes.
69    * @exception SAXException If an error occurs while removing the new handler state.
70    */

71   public void removeCurrentState(String JavaDoc anUri, String JavaDoc aLocalName,
72     String JavaDoc aQualifiedName) throws SAXException JavaDoc;
73
74   /**
75    * Sets the namespace URI passed in as the current mapping for the given prefix.
76    *
77    * @param aPrefix The Namespace prefix being declared.
78    * @param anUri The Namespace URI mapped to the prefix.
79    */

80   public void startPrefixMapping(String JavaDoc aPrefix, String JavaDoc anUri);
81
82   /**
83    * Removes the current mapping of the prefix passed in.
84    *
85    * @param aPrefix The Namespace prefix being declared.
86    */

87   public void endPrefixMapping(String JavaDoc aPrefix);
88
89   /**
90    * Returns the current namespace URI for the passed in prefix.
91    *
92    * @return The current namespace URI or <CODE>null</CODE> if not mapping exists.
93    */

94   public String JavaDoc getNamespaceURIFor(String JavaDoc aPrefix);
95
96   /**
97    * associates the result object to the handler state passed in.
98    *
99    * @param aHandlerState The handler state for which a result is provided.
100    * @param aResult The result object of the handler state.
101    */

102   public void setResultFor(HandlerStateIF aHandlerState, Object JavaDoc aResult);
103
104   /**
105    * Returns the result for the handler state passed in.
106    *
107    * @param aHandlerState The handler state for which to search for a result.
108    * @return The result object found, or <CODE>null</CODE> if no handler state was foud
109    * or if no result was associated for the handler state passed in.
110    */

111   public Object JavaDoc getResultFor(HandlerStateIF aHandlerState);
112 }
113
Popular Tags