VE Source Editor / Code Generation (CodeGen) component
Illustration 3 shows in more detail the architecture of the Visual Editor CodeGen component.
The key elements of the VE Source Editor/CodeGen component are;
- JavaSourceTranslator – an implementation of an IDiagramModelBuilder and an IDiagramSourceDecoder
- the 'BDM', that is an instance of IBeanDeclModel and its related classes.
- Decoders and DecoderAdapters
These are described in more detail below.
JavaVisualEditorPart (JVEP) subclasses org.eclipse.jdt.internal.ui.javaeditor.CompilationUnitEditor which is the default Java Editor within Eclipse. This class serves not only as the embedded source editor for the Java code but is also the entry point for Eclipse VE. Hence it does a lot more than just provide editing support.
Illustration 4 summarizes the different roles that JVEP plays. Not only does it create the visual components that users interact with such as the Graphical Viewer and source editor, it also creates the IModelBuilder used to parse the Java code and build the VE Model, creates factory classes used to provide decoder classes as well as provide the source code editing function.
Hence the JVEP is a key class to customize in order to be able to use Visual Editor for a Groovy file.
JavaVisualEditorPart as Source Editor
As stated above JavaVisualEditorPart subclasses CompilationUnitEditor which uses a CompilationUnitDocumentProvider as its IDocumentProvider. This means that it gets the Java source code through a JDT CompilationUnit. This CompilationUnit is created when the IEditorInput is set on the Editor. The path to it is stored in JDT's WorkingCopyManager and accessed later by classes in the CodeGen component.
The source code is potentially being updated by more than one source within the Visual Editor, such as the Graphical Viewer, the Source Editor, etc., with some of the updates taking place in the display thread, others in slower background threads. Hence updates to the source file are coordinated through the use of JDT's CompilationUnit and the concept of working copies. The CompilationUnit is also part of the Java Abstract Syntax Tree (AST) and is used to provide information about the source codes classes, methods etc.
JavaSourceTranslator implements IDiagramModelBuilder and IDiagramSourceDecoder. It uses JavaBeanModelBuilder and CodeSnippetModelBuilder, depending on whether it is parsing the code for the first time or reacting to editor input, to build an IBeanDeclModel instance, otherwise known as the 'BDM'. The BDM is an intermediate model of the source code enabling updates to the source to occur in two different ways. User actions in the Graphical Viewer, Java Beans Tree and Property Sheet leads to the 'VE' Model being updated. These changes are then propagated to the BDM Model and from there to the source code. Users can also edit the source code directly in the source editor. These edit changes are then processed by the CodeSnippetModelBuilder which updates the BDM Model. Decoders propagate the changes to the 'VE' model.
Once the BDM has been built the JavaSourceTranslator uses it to build an instance of IVEModelInstance, the 'VE' Model.
JavaBeanModelBuilder and CodeSnippetModelBuilder parse the Java code and use the Java AST(Abstract Syntax Tree) to build elements of the BDM. Factory classes are used to get rules, instances of IVisitorFactoryRule and visitors, instances of ISourceVisitor. Override files can be used to provide different rules and visitors. In practice this allows only the customization of rules and visitors that will be used on a Java AST.
The parsing takes place in two stages. Firstly the AST is visited and the relevant elements of the BDM Model such as BeanPart, CodeExpressionRef, CodeMethodRef, CodeEventRef instances created and added to the BDM model. Then the expressions are decoded and the relationships between BeanParts created. For example, if a JButton is added to a JPanel then the two BeanParts representing the JButton and JPanel will be updated to reflect the Container / Contained relationship that exists.
IBeanDeclModel – the 'BDM'
The BDM models directly the beans, properties and source code expressions that are in the source code. Elements of the BDM model the beans, source expressions, methods and events. The Java AST Expressions and Statements are used as Constructor parameters to these instances. Hence the Java source code is an integral part of the BDM.
Decoders and DecoderAdapters
Decoders are responsible for decoding the Java AST expression contained in a CodeExpressionRef and for making the appropriate updates to the VE Model. For each type of object an ExpressionDecoderFactory will provide a decoder, an instance of IExpressionDecoder. The class of the decoder that is returned is defined by the override files.
The Decoder will decode all the expressions that belong to a particular BeanPart. For each expression the Decoder will analyse the AST Expression that is parsed in and then delegate the decoding to two further classes, an instance of IFeatureMapper and an instance of IDecoderHelper. These classes will analyse the AST expression and make updates to the VE Model as well updating the BeanParts to reflect the relationships between beans.
DecoderAdapters are used to react to VE Model updates and then delegate any necessary source code updates to the appropriate decoders.