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.treeprocessor;
018:
019: import org.apache.avalon.framework.component.Component;
020: import org.apache.avalon.framework.component.ComponentManager;
021: import org.apache.avalon.framework.configuration.Configuration;
022: import org.apache.avalon.framework.configuration.ConfigurationException;
023: import org.apache.excalibur.source.Source;
024:
025: import java.util.List;
026:
027: /**
028: *
029: * @author <a href="mailto:sylvain@apache.org">Sylvain Wallez</a>
030: * @version CVS $Id: TreeBuilder.java 433543 2006-08-22 06:22:54Z crossley $
031: */
032:
033: public interface TreeBuilder extends Component {
034:
035: void setProcessor(ConcreteTreeProcessor processor);
036:
037: ConcreteTreeProcessor getProcessor();
038:
039: /**
040: * Returns the language that is being built (e.g. "sitemap").
041: */
042: String getLanguage();
043:
044: /**
045: * Returns the name of the parameter element.
046: */
047: String getParameterName();
048:
049: /**
050: * Register a <code>ProcessingNode</code> under a given name.
051: * For example, <code>ResourceNodeBuilder</code> stores here the <code>ProcessingNode</code>s
052: * it produces for use by sitemap pipelines. This allows to turn the tree into a graph.
053: * If a node with the name is already registed, the process fails!
054: * @return If the node could be registered, <code>true</code> is returned; otherwise false.
055: */
056: boolean registerNode(String name, ProcessingNode node);
057:
058: /**
059: * @throws IllegalStateException
060: */
061: ProcessingNode getRegisteredNode(String name);
062:
063: ProcessingNodeBuilder createNodeBuilder(Configuration config)
064: throws Exception;
065:
066: /**
067: * Get the namespace URI that builders should use to find their nodes.
068: */
069: String getNamespace();
070:
071: /**
072: * Build a processing tree from a <code>Configuration</code>.
073: */
074: ProcessingNode build(Configuration tree) throws Exception;
075:
076: ProcessingNode build(Source source) throws Exception;
077:
078: String getFileName();
079:
080: /**
081: * Return the list of <code>ProcessingNodes</code> part of this tree that are
082: * <code>Disposable</code>. Care should be taken to properly dispose them before
083: * trashing the processing tree.
084: */
085: List getDisposableNodes();
086:
087: /**
088: * Setup a <code>ProcessingNode</code> by setting its location, calling all
089: * the lifecycle interfaces it implements and giving it the parameter map if
090: * it's a <code>ParameterizableNode</code>.
091: * <p>
092: * As a convenience, the node is returned by this method to allow constructs
093: * like <code>return treeBuilder.setupNode(new MyNode(), config)</code>.
094: */
095: ProcessingNode setupNode(ProcessingNode node, Configuration config)
096: throws Exception;
097:
098: /**
099: * Get the type for a statement : it returns the 'type' attribute if present,
100: * and otherwhise the default hint for the <code>ComponentSelector</code> identified by
101: * the role <code>role</code>.
102: *
103: * @throws ConfigurationException if the default type could not be found.
104: */
105: String getTypeForStatement(Configuration statement, String role)
106: throws ConfigurationException;
107:
108: /**
109: * Return the sitemap component manager
110: */
111: ComponentManager getSitemapComponentManager();
112:
113: /**
114: * Add an attribute. Useful to transmit information between distant (in the tree) node builders
115: */
116: void setAttribute(String name, Object value);
117:
118: /**
119: * Get the value of an attribute.
120: */
121: Object getAttribute(String name);
122: }
|