001: /*
002: * Spoon - http://spoon.gforge.inria.fr/
003: * Copyright (C) 2006 INRIA Futurs <renaud.pawlak@inria.fr>
004: *
005: * This software is governed by the CeCILL-C License under French law and
006: * abiding by the rules of distribution of free software. You can use, modify
007: * and/or redistribute the software under the terms of the CeCILL-C license as
008: * circulated by CEA, CNRS and INRIA at http://www.cecill.info.
009: *
010: * This program is distributed in the hope that it will be useful, but WITHOUT
011: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
012: * FITNESS FOR A PARTICULAR PURPOSE. See the CeCILL-C License for more details.
013: *
014: * The fact that you are presently reading this means that you have had
015: * knowledge of the CeCILL-C license and that you accept its terms.
016: */
017:
018: package spoon.processing;
019:
020: import java.util.Set;
021:
022: import spoon.reflect.declaration.CtElement;
023:
024: /**
025: * This interface defines a generic code processor. To define a new processor,
026: * the user should subclass {@link spoon.processing.AbstractProcessor}, the
027: * abstract default implementation of this interface.
028: */
029:
030: public interface Processor<E extends CtElement> extends FactoryAccessor {
031:
032: /**
033: * Gets the model's traversal strategy for this processor (default is
034: * {@link TraversalStrategy#PRE_ORDER}). Programmers should override this
035: * method to return another strategy if needed.
036: */
037: TraversalStrategy getTraversalStrategy();
038:
039: /**
040: * Gets the environment of this processor.
041: */
042: Environment getEnvironment();
043:
044: /**
045: * Tells if this element is to be processed (returns <code>true</code> in
046: * the default implementation).
047: *
048: * @param candidate
049: * the candidate
050: * @return true if the candidate is to be processed by the
051: * {@link #process(CtElement)}
052: */
053: boolean isToBeProcessed(E candidate);
054:
055: /**
056: * A callback method upcalled by the meta-model scanner to perform a
057: * dedicated job on the currently scanned element. The way Spoon upcalls
058: * this method depends on the processed element types ({@link #getProcessedElementTypes()}),
059: * the traversal strategy ({@link #getTraversalStrategy()}), and the used
060: * processing manager ({@link Environment#getManager()}. Also, this method
061: * is upcalled only if the method {@link #isToBeProcessed(CtElement)}
062: * returns true for a given scanned element. In order to manually scan the
063: * meta-model, one can define the {@link #process()} method instead.
064: *
065: * @param element
066: * the element that is currenly being scanned
067: */
068: void process(E element);
069:
070: /**
071: * A callback method upcalled by the manager so that this processor can
072: * manually implement a processing job. On contrary to
073: * {@link #process(CtElement)}, this method does not rely on a built-in
074: * meta-model scanner and has to implement its own traversal strategy on the
075: * meta-model, which is stored in the factory ({@link FactoryAccessor#getFactory}).
076: * Note that if a processor implements both process methods, this one is
077: * upcalled first. This method does nothing in default implementations ({@link spoon.processing.AbstractProcessor}).
078: */
079: void process();
080:
081: /**
082: * Do the processing job for a given element. This method is upcalled on an
083: * element if the method {@link #isToBeProcessed(CtElement)} returns true.
084: *
085: * @param element
086: * the element that holds the processed annotations
087: */
088:
089: /**
090: * Gets all the element types than need to be processed.
091: */
092: Set<Class<? extends CtElement>> getProcessedElementTypes();
093:
094: /**
095: * This method is upcalled by the {@link ProcessingManager} when this
096: * processor has finished a full processing round on the program's model. It
097: * is convenient to override this method to tune the application's strategy
098: * of a set of processors, for instance by dynamically adding processors to
099: * the processing manager when a processing round ends (see
100: * {@link ProcessingManager#addProcessor(Class)}). Does nothing by default.
101: */
102: void processingDone();
103:
104: /**
105: * This method is upcalled to initialize the processor before each
106: * processing round. It is convenient to override this method rather than
107: * using a default constructor to initialize the processor, since the
108: * factory is not initialized at construction time. When overriding, do not
109: * forget to call super.init() first so that all the initializations
110: * performed by superclasses are also applied.
111: */
112: void init();
113:
114: /**
115: * Initializes the properties defined by this processor by using the environment.
116: *
117: *@see Environment#getProcessorProperties(String)
118: */
119: void initProperties(ProcessorProperties properties);
120:
121: }
|