01: package net.sf.saxon.trace;
02:
03: import net.sf.saxon.expr.XPathContext;
04: import net.sf.saxon.om.Item;
05:
06: import java.util.EventListener;
07:
08: /**
09: * This interface defines methods that are called by Saxon during the execution of
10: * a stylesheet, if tracing is switched on. Tracing can be switched on by nominating
11: * an implementation of this class using the TRACE_LISTENER feature of the TransformerFactory,
12: * or using the addTraceListener() method of the Controller, which is Saxon's implementation
13: * of tyhe JAXP javax.xml.transform.Transformer interface.
14: */
15:
16: public interface TraceListener extends EventListener {
17:
18: /**
19: * Method called at the start of execution, that is, when the run-time transformation starts
20: */
21:
22: public void open();
23:
24: /**
25: * Method called at the end of execution, that is, when the run-time execution ends
26: */
27:
28: public void close();
29:
30: /**
31: * Method that is called when an instruction in the stylesheet gets processed.
32: * @param instruction gives information about the instruction being
33: * executed, and about the context in which it is executed. This object is mutable,
34: * so if information from the InstructionInfo is to be retained, it must be copied.
35: */
36:
37: public void enter(InstructionInfo instruction, XPathContext context);
38:
39: /**
40: * Method that is called after processing an instruction of the stylesheet,
41: * that is, after any child instructions have been processed.
42: * @param instruction gives the same information that was supplied to the
43: * enter method, though it is not necessarily the same object. Note that the
44: * line number of the instruction is that of the start tag in the source stylesheet,
45: * not the line number of the end tag.
46: */
47:
48: public void leave(InstructionInfo instruction);
49:
50: /**
51: * Method that is called by an instruction that changes the current item
52: * in the source document: that is, xsl:for-each, xsl:apply-templates, xsl:for-each-group.
53: * The method is called after the enter method for the relevant instruction, and is called
54: * once for each item processed.
55: * @param currentItem the new current item. Item objects are not mutable; it is safe to retain
56: * a reference to the Item for later use.
57: */
58:
59: public void startCurrentItem(Item currentItem);
60:
61: /**
62: * Method that is called when an instruction has finished processing a new current item
63: * and is ready to select a new current item or revert to the previous current item.
64: * The method will be called before the leave() method for the instruction that made this
65: * item current.
66: * @param currentItem the item that was current, whose processing is now complete. This will represent
67: * the same underlying item as the corresponding startCurrentItem() call, though it will
68: * not necessarily be the same actual object.
69: */
70:
71: public void endCurrentItem(Item currentItem);
72:
73: }
74:
75: // Contributor(s):
76: // This module is originally from Edwin Glaser (edwin@pannenleiter.de)
77: // It has since been heavily modified by Michael Kay
78: //
|