NOTE: This project has been retired, and there will be no more updates. Other future projects may reuse some concepts presented here.Projects having here incubation status are to promote some new ideas, develop innovative software solutions and convince skeptics that proposed solutions can be useful in supporting the software development process. Therefore, incubation projects can be closed if they do not deliver sound results.
Annotating Gen Objects project is the first incubation project started by the JGen Notes. Technology and solution proposed in this one mostly support extending the CA Gen Toolset, but there are plans to move beyond this arena in the future.
Table of Contents
Introduction
This post presents a new idea how to store extra custom metadata in the CA Gen Model without changing existing structure of the model. The proposed solution is going to use well-known in programming languages a concept of annotations. In the computer programming languages, an annotation is a form of syntactic metadata that can be added to the source code. We need to understand the construction of the CA Gen Model before we can propose a similar solution for the CA Gen. Simply, it is not obvious how to do it if we do not have such things like sources in the Gen models.
We need to understand the construction of the CA Gen Model and find the place to add and store annotations in the CA Gen Model. It is not obvious how to do it if we do not have such things like sources in the CA Gen’s models.
The CA Gen Model is a collection of elements like objects, associations, and properties. The toolset adds those elements to the model during a development process. We call such data a metadata. The CA Gen’s functions checking consistency allow only those specific types of elements in the model and identifying the incorrect use of model elements. The CA Gen uses a concept of the schema which defines the lists of allowed object types, association types, and property types. The schema is metadata about metadata and sometimes referred as meta-meta-data. The CA Gen developer cannot modify meta-meta-data by adding additional element types. There are few exceptions where you can reuse some objects for your ends. For example, you can create your model preferences in a CA Gen Model, but this feature will not be discussed here.
There is one type of property associated with the selection of object types that allows storing any text value. The mnemonic name for this property is DESC. Usually, the DESC value has some descriptive information about objects that the developers are free to add during development. Those are like comments in the traditional programming languages. The important point here is that value of the DESC, toolset stores in the model. Many dialogs in the Gen Toolset allow to enter text value using dedicated dialog multi-line text fields and preserving its value in the model. Whenever you find area Description field in dialog box used by the CA Gen Toolset, you may assume that there is a property DESC associated with the main object type defined by the dialog box.
We are going to use DESC property to store annotations. The JGen Notes Annotation project utilizes this property DESC and using proved annotation solution borrowed from the Java world.
Annotations
No doubt that introduction of annotations into the Java language world produced a significant change in the way we are building applications now. It allows many new tools that are processing annotations to enhance and simplify the development process. Hopefully, the JGen Notes Annotation project will help in developing such tools around the CA Gen.
Property DESC is a block of text having the maximum length of 4KB. It is more than enough to accommodate even most complex Java-style annotations. It could happen that DESC property has already some text documenting some aspects of the application. Existing text is not a problem because we can accommodate both annotation and existing text by using Java-style comments. The potential problem can occur only when a combined size of the text exceeds 4KB. The solution will be to truncate existing contents.
As mentioned earlier, DESC property is behind Description field placed on many dialog boxes provided by the CA Gen Toolset. Here are couple examples how you can use the Description field to accommodate annotations and preserve existing contents in such Description field.
Example A
Suppose we want to follow who developed what in your big application. It is beneficial if every developer responsible for a particular part will add some information inserting dedicated annotation into the description for the object created or updated by this individual. Here is an example of such entry using annotation@Author for the object action block.
Example B
Suppose we have utility allowing convert action block to implement a user-added function. We probably need to have the annotation @Function marking those action blocks in the model to be transformed into the implementation of the user-added function. Here is an example of an entry using annotation@Funtion. Please notice that you can insert as many annotations as you like.
Example C
Suppose we have a generator utility capable of generating source code in the Swift language and deployed on one of many Linux server platforms. Here is an example of entry using annotation @Generate that allows specifying selected generation language.
Declaring Annotations
So now we are going to define what is a correctly inserted annotation. It would be nice to have some mechanism determining what is correct annotation and what is not. Firstly, we are going to use well established Java method defining annotations. Here are how it can be done in Java for all annotations used in the above examples.
package sample.annot;
public @interface Author {
String name() default "John Doe";
String version() default "1.0";
String date() default "2017-01-01";
}
package sample.annot;
public @interface Function {
String name();
}
package sample.annot;
public @interface Generate {
Languages lang();
}
package sample.annot;
public enum Languages {
swift, java, cobol, c
}
One important point is demonstrating how we can accommodate annotations coming from the different vendors. We can use proven concept of namespaces coming from the Java world and based on package names. You need to use the import statement to indicate from where a particular annotation is coming. You can add an import statement in each description field or insert them in one of the objects that have global scope. A good candidate is the object Root Subject Area, which represents the whole model and is always there. Fortunately, the Root Subject Area object has DESC property. We can assume that all descriptions in the model will inherit import statements placed in this object. Here is an example of how to do it.
Editing Annotations
The simplest way to add annotation is to open a dialog box in the CA Gen Toolset and use the Description field to add an annotation. It is a simple method, but not very reliable. What about correct syntax and validation. The CA Gen Toolset on its own allowing enter any text and do not bother to do any checks on its contents. The JGen Notes Annotation project envisages a full-function editor that allows errorless insertion of the annotations that are valid within the scope of the model.
Here it is the first glims of how such an editor can look like.
Annotation editor is part of the CA Gen Plug-in implemented as Eclipse RCP application that can be invoked from inside of the CA Gen Toolset. Primally, it will focus on the object selected from inside the CA Gen Toolset, but it will have a navigation view allowing browse all objects and select any object in the model having DESC property. The navigation view is on the left side pane. On the right side pane, you see opened editor allowing edit selected Description. The solution will validate and prevent entering wrongly created annotations.
Processing Annotations
Once we have annotations stored in the model, we need to find a way to process them. Processing annotations start with finding objects of interest in the model. You can use the full power of the CA Gen JMMI API to scan the model, getting the required objects and extracting DESC properties, and checking if they have valid annotations qualifying for further processing. Part of the project will be delivering a dedicated parser to process the contents of the DESC properties. The parser will return a Java object which is equivalent to the syntax tree representing the contents of the entire description. The project envisages classes and methods that are helping filter contents and extracting accurate information from the syntax tree. Developers will have full instrumentation contributing to developing tools like generators which are utilizing that additional metadata stored in the model now.
Summary
The project is using the following software:
- Windows 10
- CA Gen 8.6 (Free)
- Java Version 8 (Update 20)
- Eclipse Oxygen
- Xtext 2.12.0
- Xtend 2.11
The software will be delivered as an Eclipse Plugin. More information about the project and proposed solutions will be provided later. The source will be posted on GitHub once will be more mature and stable.
Links
The initial version of the Annotation Editor sources has been published here.
Here is a new post discussing here how to process existing annotations already in the model.