001// Copyright 2004, 2005 The Apache Software Foundation
002//
003// Licensed under the Apache License, Version 2.0 (the "License");
004// you may not use this file except in compliance with the License.
005// You may obtain a copy of the License at
006//
007//     http://www.apache.org/licenses/LICENSE-2.0
008//
009// Unless required by applicable law or agreed to in writing, software
010// distributed under the License is distributed on an "AS IS" BASIS,
011// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
012// See the License for the specific language governing permissions and
013// limitations under the License.
014
015package org.apache.hivemind.schema;
016
017import org.apache.hivemind.internal.Module;
018
019/**
020 * Object used when processing the elements contributed in an
021 * {@link org.apache.hivemind.internal.Contribution}.
022 * 
023 * @author Howard Lewis Ship
024 */
025public interface SchemaProcessor
026{
027    /**
028     * The SchemaProcessor is always the bottom (deepest) object on the stack. Top level objects
029     * (contained by a schema, not another element) can use an
030     * {@link org.apache.hivemind.schema.rules.InvokeParentRule} to add themselves to the list
031     * of elements for the {@link org.apache.hivemind.internal.ConfigurationPoint} being
032     * constructed.
033     */
034    public void addElement(Object element);
035
036    /**
037     * Pushes an object onto the processor's stack.
038     */
039    public void push(Object object);
040
041    /**
042     * Pops the top object off the stack and returns it.
043     */
044
045    public Object pop();
046
047    /**
048     * Peeks at the top object on the stack.
049     */
050
051    public Object peek();
052
053    /**
054     * Peeks at an object within the stack at the indicated depth.
055     */
056
057    public Object peek(int depth);
058
059    /**
060     * Returns the module which contributed the current elements being processed.
061     */
062
063    public Module getContributingModule();
064
065    /**
066     * Return the module which defined the schema.
067     * 
068     * @since 1.1
069     */
070
071    public Module getDefiningModule();
072
073    /**
074     * Returns the path to the current element in the form a sequence of element names separated
075     * with slashes. This is most often used in error messages, to help identify the position of an
076     * error.
077     */
078
079    public String getElementPath();
080
081    /**
082     * Returns a {@link org.apache.hivemind.schema.Translator} used to convert the content of the
083     * current element. Will not return null.
084     */
085
086    public Translator getContentTranslator();
087
088    /**
089     * Returns the {@link org.apache.hivemind.schema.Translator} for a particular attribute of the
090     * current element. Will not return null.
091     */
092
093    public Translator getAttributeTranslator(String attributeName);
094
095    /**
096     * Returns the named {@link org.apache.hivemind.schema.Translator}.
097     */
098
099    public Translator getTranslator(String translator);
100}