KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > cocoon > components > elementprocessor > ElementProcessor


1 /*
2  * Copyright 1999-2004 The Apache Software Foundation.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 package org.apache.cocoon.components.elementprocessor;
17
18 import org.apache.cocoon.components.elementprocessor.types.Attribute;
19
20 import java.io.IOException JavaDoc;
21
22 /**
23  * The ElementProcessor interface defines behavior for classes that
24  * can handle a particular XML element's content.
25  * <br>
26  * The life cycle of an ElementProcessor instance is:
27  * <ol>
28  * <li>Creation
29  * <li>Initialization via a call to initialize
30  * <li>Acquisition of element data via calls to acceptCharacters
31  * and acceptWhitespaceCharacters
32  * <li>Completion of processing via a call to endProcessing
33  * </ol>
34  * In response to a startElement event, the POIFSSerializer creates an
35  * ElementProcessor, delegating the act of creation to an
36  * ElementProcessorFactory, and then initializes the
37  * ElementProcessor. In response to subsequent characters and
38  * ignorableWhitespace events, the POIFSSerializer will pass data to
39  * the ElementProcessor via the acceptCharacters or
40  * acceptWhitespaceCharacters methods. Finally, in response to an
41  * endElement event, the POIFSSerializer calls the ElementProcessor's
42  * endProcessing method.
43  *
44  * @author Marc Johnson (marc_johnson27591@hotmail.com)
45  * @version CVS $Id: ElementProcessor.java 30932 2004-07-29 17:35:38Z vgritsenko $
46  */
47 public interface ElementProcessor
48                     extends org.apache.avalon.framework.component.Component
49 {
50
51     String JavaDoc ROLE = ElementProcessor.class.getName();
52     
53     /**
54      * The implementation should walk the array of attributes and
55      * perform appropriate actions based on that data. The array of
56      * attributes is guaranteed never to be null, but it can be
57      * empty. An implementation can expect code like this to work
58      * without throwing runtime exceptions:
59      * <br>
60      * <code>
61      * for (int k = 0; k < attributes.length; k++)<br>
62      * {<br>
63      * &nbsp;&nbsp;&nbsp;&nbsp;Attribute attr = attributes[ k ];<br>
64      * &nbsp;&nbsp;&nbsp;&nbsp;// process attribute</br>
65      * }</br>
66      * </code>
67      * <br>
68      * <b>NOTE: if the XML DTD or schema includes <i>IMPLIED</i>
69      * attributes for an element, those attributes are not included in
70      * the Attribute array - they're not in the data provided in the
71      * startElement call. The constructor for the ElementProcessor
72      * should set those implied attributes itself, and allow them to
73      * be overridden if the XML source provided <i>explicit</i> values
74      * for them.</b>
75      * <br>
76      * The parent ElementProcessor is a reference to the
77      * ElementProcessor whose corresponding XML element contains this
78      * ElementProcessor's corresponding XML element. It will not be
79      * null unless this ElementProcessor's corresponding XML element
80      * is the top-level element in the XML document. Whether this
81      * ElementProcessor needs to establish a containment relationship
82      * with its parent or not, and whether it needs to do so at the
83      * beginning, middle, or end of its life cycle, are private
84      * matters left to the discretion of the individual
85      * ElementProcessor implementation. If the ElementProcessor needs
86      * to interact with its parent ElementProcessor, but is not ready
87      * to do so when the initialize method is called, it must cache
88      * the reference to its parent.
89      * <br>
90      *
91      * @param attributes the array of Attribute instances; may be
92      * empty, will never be null
93      * @param parent the parent ElementProcessor; may be null
94      *
95      * @exception IOException if anything goes wrong
96      */
97
98     public void initialize(Attribute [] attributes, ElementProcessor parent)
99         throws IOException JavaDoc;
100
101     /**
102      * The data provided in this method call comes from the
103      * corresponding XML element's contents. The array is guaranteed
104      * not to be null and will never be empty.
105      * <br>
106      * The POIFSSerializer will make 0 to many calls to this method;
107      * all such calls will occur after the initialize method is called
108      * and before the endProcessing method is called.
109      * <br>
110      * Calls to this method may be interleaved with calls to
111      * acceptWhitespaceCharacters. All calls to acceptCharacters and
112      * acceptWhitespaceCharacters are guaranteed to be in the same
113      * order as their data is in the element.
114      *
115      * @param data the character data
116      */
117
118     public void acceptCharacters(char [] data);
119
120     /**
121      * The data provided in this method call comes from the
122      * corresponding XML element's contents. The array is guaranteed
123      * not to be null and will never be empty.
124      * <br>
125      * The POIFSSerializer will make 0 to many calls to this method;
126      * all such calls will occur after the initialize method is called
127      * and before the endProcessing method is called.
128      * <br>
129      * Calls to this method may be interleaved with calls to
130      * acceptCharacters. All calls to acceptCharacters and
131      * acceptWhitespaceCharacters are guaranteed to be in the same
132      * order as their data is in the element.
133      *
134      * @param data the whitespace characters
135      */
136
137     public void acceptWhitespaceCharacters(char [] data);
138
139     /**
140      * This is the last method call executed by the
141      * POIFSSerializer. When this method is called, the
142      * ElementProcessor should finish its work and perform its final
143      * interactions with its parent ElementProcessor.
144      * <br>
145      * If the implementation cached the parent ElementProcessor
146      * reference, when the initialize method was called, it should
147      * null out that reference.
148      *
149      * @exception IOException
150      */
151
152     public void endProcessing()
153         throws IOException JavaDoc;
154 } // end public interface ElementProcessor
155
Popular Tags