| /* |
| * Licensed to the Apache Software Foundation (ASF) under one or more |
| * contributor license agreements. See the NOTICE file distributed with |
| * this work for additional information regarding copyright ownership. |
| * The ASF licenses this file to You under the Apache License, Version 2.0 |
| * (the "License"); you may not use this file except in compliance with |
| * the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| package org.apache.cocoon.components.elementprocessor; |
| |
| import org.apache.cocoon.components.elementprocessor.types.Attribute; |
| |
| import java.io.IOException; |
| |
| /** |
| * The ElementProcessor interface defines behavior for classes that |
| * can handle a particular XML element's content. |
| * <br> |
| * The life cycle of an ElementProcessor instance is: |
| * <ol> |
| * <li>Creation |
| * <li>Initialization via a call to initialize |
| * <li>Acquisition of element data via calls to acceptCharacters |
| * and acceptWhitespaceCharacters |
| * <li>Completion of processing via a call to endProcessing |
| * </ol> |
| * In response to a startElement event, the POIFSSerializer creates an |
| * ElementProcessor, delegating the act of creation to an |
| * ElementProcessorFactory, and then initializes the |
| * ElementProcessor. In response to subsequent characters and |
| * ignorableWhitespace events, the POIFSSerializer will pass data to |
| * the ElementProcessor via the acceptCharacters or |
| * acceptWhitespaceCharacters methods. Finally, in response to an |
| * endElement event, the POIFSSerializer calls the ElementProcessor's |
| * endProcessing method. |
| * |
| * @author Marc Johnson (marc_johnson27591@hotmail.com) |
| * @version CVS $Id$ |
| */ |
| public interface ElementProcessor |
| extends org.apache.avalon.framework.component.Component |
| { |
| |
| String ROLE = ElementProcessor.class.getName(); |
| |
| /** |
| * The implementation should walk the array of attributes and |
| * perform appropriate actions based on that data. The array of |
| * attributes is guaranteed never to be null, but it can be |
| * empty. An implementation can expect code like this to work |
| * without throwing runtime exceptions: |
| * <br> |
| * <code> |
| * for (int k = 0; k < attributes.length; k++)<br> |
| * {<br> |
| * Attribute attr = attributes[ k ];<br> |
| * // process attribute</br> |
| * }</br> |
| * </code> |
| * <br> |
| * <b>NOTE: if the XML DTD or schema includes <i>IMPLIED</i> |
| * attributes for an element, those attributes are not included in |
| * the Attribute array - they're not in the data provided in the |
| * startElement call. The constructor for the ElementProcessor |
| * should set those implied attributes itself, and allow them to |
| * be overridden if the XML source provided <i>explicit</i> values |
| * for them.</b> |
| * <br> |
| * The parent ElementProcessor is a reference to the |
| * ElementProcessor whose corresponding XML element contains this |
| * ElementProcessor's corresponding XML element. It will not be |
| * null unless this ElementProcessor's corresponding XML element |
| * is the top-level element in the XML document. Whether this |
| * ElementProcessor needs to establish a containment relationship |
| * with its parent or not, and whether it needs to do so at the |
| * beginning, middle, or end of its life cycle, are private |
| * matters left to the discretion of the individual |
| * ElementProcessor implementation. If the ElementProcessor needs |
| * to interact with its parent ElementProcessor, but is not ready |
| * to do so when the initialize method is called, it must cache |
| * the reference to its parent. |
| * <br> |
| * |
| * @param attributes the array of Attribute instances; may be |
| * empty, will never be null |
| * @param parent the parent ElementProcessor; may be null |
| * |
| * @exception IOException if anything goes wrong |
| */ |
| |
| public void initialize(Attribute [] attributes, ElementProcessor parent) |
| throws IOException; |
| |
| /** |
| * The data provided in this method call comes from the |
| * corresponding XML element's contents. The array is guaranteed |
| * not to be null and will never be empty. |
| * <br> |
| * The POIFSSerializer will make 0 to many calls to this method; |
| * all such calls will occur after the initialize method is called |
| * and before the endProcessing method is called. |
| * <br> |
| * Calls to this method may be interleaved with calls to |
| * acceptWhitespaceCharacters. All calls to acceptCharacters and |
| * acceptWhitespaceCharacters are guaranteed to be in the same |
| * order as their data is in the element. |
| * |
| * @param data the character data |
| */ |
| |
| public void acceptCharacters(char [] data); |
| |
| /** |
| * The data provided in this method call comes from the |
| * corresponding XML element's contents. The array is guaranteed |
| * not to be null and will never be empty. |
| * <br> |
| * The POIFSSerializer will make 0 to many calls to this method; |
| * all such calls will occur after the initialize method is called |
| * and before the endProcessing method is called. |
| * <br> |
| * Calls to this method may be interleaved with calls to |
| * acceptCharacters. All calls to acceptCharacters and |
| * acceptWhitespaceCharacters are guaranteed to be in the same |
| * order as their data is in the element. |
| * |
| * @param data the whitespace characters |
| */ |
| |
| public void acceptWhitespaceCharacters(char [] data); |
| |
| /** |
| * This is the last method call executed by the |
| * POIFSSerializer. When this method is called, the |
| * ElementProcessor should finish its work and perform its final |
| * interactions with its parent ElementProcessor. |
| * <br> |
| * If the implementation cached the parent ElementProcessor |
| * reference, when the initialize method was called, it should |
| * null out that reference. |
| * |
| * @exception IOException |
| */ |
| |
| public void endProcessing() |
| throws IOException; |
| } // end public interface ElementProcessor |
