001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017: package org.apache.cocoon.components.elementprocessor;
018:
019: import org.apache.cocoon.components.elementprocessor.types.Attribute;
020:
021: import java.io.IOException;
022:
023: /**
024: * The ElementProcessor interface defines behavior for classes that
025: * can handle a particular XML element's content.
026: * <br>
027: * The life cycle of an ElementProcessor instance is:
028: * <ol>
029: * <li>Creation
030: * <li>Initialization via a call to initialize
031: * <li>Acquisition of element data via calls to acceptCharacters
032: * and acceptWhitespaceCharacters
033: * <li>Completion of processing via a call to endProcessing
034: * </ol>
035: * In response to a startElement event, the POIFSSerializer creates an
036: * ElementProcessor, delegating the act of creation to an
037: * ElementProcessorFactory, and then initializes the
038: * ElementProcessor. In response to subsequent characters and
039: * ignorableWhitespace events, the POIFSSerializer will pass data to
040: * the ElementProcessor via the acceptCharacters or
041: * acceptWhitespaceCharacters methods. Finally, in response to an
042: * endElement event, the POIFSSerializer calls the ElementProcessor's
043: * endProcessing method.
044: *
045: * @author Marc Johnson (marc_johnson27591@hotmail.com)
046: * @version CVS $Id: ElementProcessor.java 433543 2006-08-22 06:22:54Z crossley $
047: */
048: public interface ElementProcessor extends
049: org.apache.avalon.framework.component.Component {
050:
051: String ROLE = ElementProcessor.class.getName();
052:
053: /**
054: * The implementation should walk the array of attributes and
055: * perform appropriate actions based on that data. The array of
056: * attributes is guaranteed never to be null, but it can be
057: * empty. An implementation can expect code like this to work
058: * without throwing runtime exceptions:
059: * <br>
060: * <code>
061: * for (int k = 0; k < attributes.length; k++)<br>
062: * {<br>
063: * Attribute attr = attributes[ k ];<br>
064: * // process attribute</br>
065: * }</br>
066: * </code>
067: * <br>
068: * <b>NOTE: if the XML DTD or schema includes <i>IMPLIED</i>
069: * attributes for an element, those attributes are not included in
070: * the Attribute array - they're not in the data provided in the
071: * startElement call. The constructor for the ElementProcessor
072: * should set those implied attributes itself, and allow them to
073: * be overridden if the XML source provided <i>explicit</i> values
074: * for them.</b>
075: * <br>
076: * The parent ElementProcessor is a reference to the
077: * ElementProcessor whose corresponding XML element contains this
078: * ElementProcessor's corresponding XML element. It will not be
079: * null unless this ElementProcessor's corresponding XML element
080: * is the top-level element in the XML document. Whether this
081: * ElementProcessor needs to establish a containment relationship
082: * with its parent or not, and whether it needs to do so at the
083: * beginning, middle, or end of its life cycle, are private
084: * matters left to the discretion of the individual
085: * ElementProcessor implementation. If the ElementProcessor needs
086: * to interact with its parent ElementProcessor, but is not ready
087: * to do so when the initialize method is called, it must cache
088: * the reference to its parent.
089: * <br>
090: *
091: * @param attributes the array of Attribute instances; may be
092: * empty, will never be null
093: * @param parent the parent ElementProcessor; may be null
094: *
095: * @exception IOException if anything goes wrong
096: */
097:
098: public void initialize(Attribute[] attributes,
099: ElementProcessor parent) throws IOException;
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() throws IOException;
153: } // end public interface ElementProcessor
|