mbeckerle commented on a change in pull request #394: URL: https://github.com/apache/incubator-daffodil/pull/394#discussion_r453006731
########## File path: daffodil-core/src/main/scala/org/apache/daffodil/dsom/walker/AbstractDSOMWalker.scala ########## @@ -0,0 +1,217 @@ +/* + * 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.daffodil.dsom.walker + +import java.io.File + +import org.apache.daffodil.compiler.Compiler +import org.apache.daffodil.dsom.{Choice, ComplexTypeBase, ElementBase, GroupRef, ModelGroup, Root, Sequence, SimpleTypeBase, Term} + +/** + * A class designed to walk the internal representation of a DFDL Schema File. + * + * There are numerous internal event handlers to be defined by the implementing class; each + * corresponds to "encountering" a particular element type in the DFDL Schema file. + * + * Though recursion is used here to define the walk, it is not advised to use recursion between + * these event handlers. Instead, consider a stack-like structure, as the DFDL Schema structure + * as well as the recursive method call structure can be represented by trees. + * @param schemaFile an input DFDL Schema file to parse + * @tparam T the return type of walkDSOMSchema and onWalkEnd. This should be a class used to + * represent the structure of the Schema. You could always make it Unit if you don't + * want these methods to return anything. + */ +abstract class AbstractDSOMWalker[T](schemaFile: File) { + /** + * The root element of the DFDL Schema. This will be the starting point for the traversal + */ + private final val schemaSetRoot: Root = Compiler().compileFile(schemaFile).sset.root + + /** + * Auxiliary constructor to initialize this class with a path to a schema File rather than + * a File object directly + * @param pathToSchemaFile path to the DFDL Schema file desired to be parsed + */ + def this(pathToSchemaFile: String) = this(new File(pathToSchemaFile)) + + /** + * Method to be called on the beginning of the traversal. It is recommended to add some + * sort of wrapper element to a stack if you're doing a typical stack-based traversal. + * @param root the root element of the DFDL Schema + */ + protected def onWalkBegin(root: Root): Unit + + /** + * Method to be called when the traversal concludes. It is recommended to put any post-processing + * and anything to tidy up the stack or the result here. + * @param root the root element of the DFDL Schema + * @return the result of the traversal + */ + protected def onWalkEnd(root: Root): T + + /** + * Method to be called when a *sequence* element is encountered. + * This is not really your array type; the typical "array" you'll see in an infoset + * is a special kind of Element, so it will be encountered + * in onElementBegin + * @param sequenceElement the sequence element + */ + protected def onSequenceBegin(sequenceElement: Sequence): Unit + + /** + * Method to be called when all the children of a sequence element are done being processed + * @param sequenceElement the original containing sequence element + */ + protected def onSequenceEnd(sequenceElement: Sequence): Unit + + /** + * Method to be called when a *GroupRef* element is encountered. In RecordWalker we will treat + * this exactly like it's a Sequence, but you have the option to treat it differently. + * in onElementBegin + * @param groupRef the GroupRef element + */ + protected def onGroupRefBegin(groupRef: GroupRef): Unit + + /** + * Method to be called when all the children of a GroupRef element are done being processed + * @param groupRef the original containing GroupRef element + */ + protected def onGroupRefEnd(groupRef: GroupRef): Unit + + /** + * Method to be called when a *choice* element is encountered. + * A choice element is an important type and has significant + * implications for the resulting infoset. + * @param choiceElement the choice element that was encountered + */ + protected def onChoiceBegin(choiceElement: Choice): Unit + + /** + * Method to be called when all the elements within a choice element have been processed. + * @param choiceElement the original containing choice element + */ + protected def onChoiceEnd(choiceElement: Choice): Unit + + /** + * Method to be called when a "simple" element is encountered. This isn't really used + * in the RecordWalker implementation since it's usually just a wrapper for an element + * with the simple you really care about, but it is here just in case. + * @param simpleElement the simple element that was encountered + */ + protected def onSimpleBegin(simpleElement: SimpleTypeBase): Unit + /** + * Method to be called after a "simple" element has been processed. + * @param simpleElement the simple element that was encountered + */ + protected def onSimpleEnd(simpleElement: SimpleTypeBase): Unit + + /** + * Method to be called when a "complex" element is encountered. This isn't really used + * in the RecordWalker implementation since it's usually just a wrapper for some inner element. + * @param complexElement the complex element that was encountered + */ + protected def onComplexBegin(complexElement: ComplexTypeBase): Unit + /** + * Method to be called after a "complex" element has been processed. + * @param complexElement the complex element that was encountered + */ + protected def onComplexEnd(complexElement: ComplexTypeBase): Unit + + /** + * Method to be called when a regular element is encountered. This is one of the most + * important methods; most DFDL elements with useful data become some subclass of + * ElementBase. + * @param element the element that was encountered + */ + protected def onElementBegin(element: ElementBase): Unit + /** + * Method to be called when a regular element has been processed. + * @param element the element that was encountered + */ + protected def onElementEnd(element: ElementBase): Unit + + final def walkDSOMSchema(): T = { + onWalkBegin(schemaSetRoot) + // this is allowed because Root is a subclass of ElementBase + walkerHelper(schemaSetRoot) + // onWalkEnd will return the value returned by this method! + onWalkEnd(schemaSetRoot) + } + + /** + * Overloaded walkerHelper method used for when some "group" element is encountered in + * the DSOM; the group elements are Sequences, Choices, and GroupRefs + * @param modelGroup the ModelGroup element that was encountered in the Schema + */ + private final def walkerHelper(modelGroup: ModelGroup): Unit = { + modelGroup match { + case sequence: Sequence => + onSequenceBegin(sequence) + for (child <- sequence.groupMembers) walkerHelper(child) + onSequenceEnd(sequence) + case choice: Choice => + onChoiceBegin(choice) + for (child <- choice.groupMembers) walkerHelper(child) + onChoiceEnd(choice) + case groupRef: GroupRef => + if (!groupRef.isHidden) { + onGroupRefBegin(groupRef) + for (child <- groupRef.groupMembers) walkerHelper(child) + onGroupRefEnd(groupRef) + } + } + } + + /** + * Overloaded walkerHelper method that will handle the input either as an ElementBase or ModelGroup + * @param term the Term element that was encountered in the Schema + */ + private final def walkerHelper(term: Term): Unit = { + term match { + case element: ElementBase => walkerHelper(element) + case modelGroup: ModelGroup => walkerHelper(modelGroup) + } + } + + /** + * Overloaded walkerHelper method that will handle some element either as a complex or simple type + * @param element the element that was encountered in the Schema + */ + private final def walkerHelper(element: ElementBase): Unit = { + onElementBegin(element) + if (element.isComplexType) { + onComplexBegin(element.complexType) + walkerHelper(element.complexType.group) + onComplexEnd(element.complexType) + } else { + onSimpleBegin(element.simpleType) + onSimpleEnd(element.simpleType) + } + onElementEnd(element) + } +} Review comment: Sometimes nothing but a recursive walk algorithm will do. A visitor struggles with state management when it has to refer to more than one tree node at a time. Suggest we stick for now with what makes this particular NiFI Record-Schema synthesizer work out well. If that's a visit pattern then great, but if an actual walk proves more natural we should have that. ---------------------------------------------------------------- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: [email protected]
