New Wizards needed more details - The model

Last week I talked a little bit about generating wizards with actifsource. I further talked about the model and what things the actifsource code generator will do for you. This week I want to go in some more details and tell you how I started using a Code Generator for implementing the wizards.

The idea of generating the wizards came up, when Micha had to create new wizards and looked into the other implementations to see how the wizard pages where built there. Since all the wizards where completely handwritten, there was nothing but the coding conventions that restricted us in implementing them. As a result, each wizard does its job a little bit different.

How is this possible? If you think about your own code you will find out quickly, that if you have to implement the same stuff a half year later or give it to a colleague, it will result in slightly different code. A reason for that is, that writing code always depends on the experience of the developer, which grows over the years. It comes the time where code style and coding conventions will be changed, but no one will go through the old code to update.

What can we do against this? One thing is discipline in following company guidelines. But who really remembers all the rules? Some rules are not even written down in a document. Here is where actifsource templates can help. A template defines the structure and limits needed to ensure that things look the same way and ensure that changes will be made in all implementation at the same time.

Okay, let's start. We have the code mess, we want to get rid of. First, you have to find a meta-model, that is common for all wizards, but still different when writing the wizard classes. All wizards have a title, a description and pages. The title and description is always set in the constructor. Each page must be accessible by the finish-method, thus we need to declare a field of the concrete type for each wizard page. These are things normally done by hand. The information will be stored in the model and the translation of the code structure in the templates.

After collecting the information, I started creating a new actifsource resource folder in the existing wizard project and creates an actifsource class named "Wizard":



The second class I needed was the "WizardPage":



The wizard page, again has a title, a description and an inputfield. The inputfield are the different control to be filled out by the user. There are some more classes but I think you can see where this goes. I don't define the field and methods to be generated in the model, I created a simple description of a wizard.

The data for each wizard is also stored in the model, for this I created a model instance of the wizard class:



As you can see this is a really minimalistic model. That is one of the benefits of using actifsource, the model can change over the time as needed. Actifsource supports iterative and incremential development.

By the way setting of the dependency between the resourcefolder and packagename is forced by a decorating property. If you are interested how they work, checkout our State Machine Tutorial.

The next time I will tell you about how the GUI code is generated by using actifsource templates.

Mapping from Ecore to the Actifsource Core - Part 2

Last week, I wrote about the similarities of ecore and the actifsource core. This time, I want to tell you about the differences and why they exist.

Elements Missing in Actifsource

Some things that are present in ecore do not have a correspondence in the actifsource core:

• Operations
• Information which is used only for the serialization of data: volatile, transient, id, resolveProxies, instanceClassName
• Factories
• Annotations
• Derived References and Attributes

Why were these things left out in the actifsource core? You will understand this when we look at the purposes of the two meta-models. Quoting from the EMF homepage:

"EMF provides tools and runtime support to produce a set of Java classes for the model, a set of adapter classes that enable viewing and command-based editing of the model, and a basic editor."

So, an ecore model must hold all information to generate a set of java classes which allow reading and writing the model including notifications and serialization. In actifsource however, you model your domain using domain classes. These domain classes do not directly map to Java classes for editing and serializing the model! Instead, instantiation and editing of your model is done in actifsource itself using the Resource Editor. Therefore, we do not want any information for mapping to a Java representation in the core itself!

If you want to map your domain classes to Java (or C, C++, Ruby, Scala..) you make use of Generic Code Templates. Like that, you have full control about every single character of the generated code! This explains why there is no need to have Operations, Factories and mapping information in the actifsource core model.

Annotations

Annotations are a way to attach additional information to any ecore element. There is currently no such thing in actifsource. However, it is possible to create an extension of the actifsource core model and define so-called Decorators which add additional information to the elements (actually, any model, not just the core can be extended in this way!). This has the advantage that the for additional information a meta-model can be defined such that they are fully typed as well. Ecore annotations on the other hand are just maps with key-value pairs of strings.

Derived Attibutes and References

Derived features do not add more information to the model but calculate something based on the ordinary attributes and references. For example, the eAllAtributes Reference collects all attributes on a class inculding those defined on its super-classes. Such funtionallity does not really describe the structure of the model but are just helpers. Actifsource has a similar concept: Functions. However, these functions are only used when writing code templates. They allow you to define and use what would be a derived feature in ecore for the purpose of code generation. Each function is associated to a function space which is usually the template. Like that, these functions do not clutter the domain model.

Additional Elements in Actifsource

Some elment of actifsource cannot be mapped to anything in ecore:

Aspects

Some elements of actifsource can implement a so-called Aspect. Each aspect has an interface which defines its purpose. Aspects allow to associate elements with functionality (usually implemented as Java class) which is needed for displaying, validating or editing models. For example, there are aspects which further restrict the range of a Relation, validate additinal contraints or add entries to the content-assist in the resource editor.

Sub-Relations

Sub-relations restrict a relation which is defined in a base class. Instances of the sub-class can then only realise the restricted association. Surprisingly, you can find such a constellation in the ecore model:

• ETypedElement has the relation eType with target EClassifier
• EAttribute inherits the eType relation
• EAttribute has the (derived) relation eAttributeType with target EDataType
  

Now, the eType of an EAttribute should never map to something that is not an EDataType! This means that the eAttributeType relation is actually a sub-relation of eType! Sadly, this information is missing in ecore!

Decocrating Relations

Deocrating relations can be used to define Homomorphisms in your model. I might write about this another time. If you do not want to wait, check out the Statemachine Tutorial where you can find an example of a decorating relation.

On Symbolic Integration

Writing Code in a GPL (General Purpose Language), elements are referenced by name. Say we do have a Class UserService. If I'd like to instantiate an Object of type UserService, I have to write something like:

UserService userService = new UserService();

Renaming the Class UserService enforces me to rename:

• All references in the code
• All comment where UserService occurs
• UML Diagrams
• User Documentation
• SW Architecture
• ...

As Martin Fowler states in his groundbreaking Article Language Workbenches: The Killer-App for Domain Specific Languages?:

"The second big plus of a language workbench is that you get symbolic integration. The ability to take an excel-like formula language, and just plug it into your own specialized language is pretty nifty. As is the ability to change symbols in one language and have those changes ripple through the whole system, which is a plausible thing to consider with a language workbench (I'm not sure if any of them can do that yet.)"

-- Martin Fowler

Starting actifsource 5 years ago, we agreed that names can be changed anytime. This tasks becomes even more complex if you want to change names on a conceptual level. Imagine to build up a Service Infrastructure. It seems obvious that our Software Architecture describes how to implement Services.

As it almost ever happens, requirements may change due to market demands. Let's say that the Service Concept shall be broaden to a general Component Concept and therefore Services shall be renamed to Component.

If you have done this before in a Larger Scale Software Project, you will agree that renaming conceptual elements is a very hard task. This is because a conceptual name is used widely by its very nature.

For this reason, we decided that we will never reference any element by its name but by a GUID:

"A globally unique identifier or GUID (pronounced /ˈɡuːɪd/ or /ˈɡwɪd/) is a special type of identifier used in software applications to provide a unique reference number. The value is represented as a 32 character hexadecimal character string, such as {21EC2020-3AEA-1069-A2DD-08002B30309D} and usually stored as a 128 bit integer."

-- wikipedia

Using GUIDs instead of names will do the trick: Using actifsource, you are able to rename any element easily. No matter if it has a conceptual or a specific nature.

Technically, a name is just an attribute, which is identified by its GUID. Renaming an actifsource Resource just means to notify all listeners.

To change names easily, make sure that you always reference you Domain Model using the actifsource Content Assist to insert a Model Reference (blue underlined). Even when writing comments.

Designing Large Scale Software Systems for Change

Today's software systems are of a complexity we can hardly manage. Even harder than just maintaining a system is adopting the system to new market needs. Changing an existing system is nearly impossible. Let's explore why.

One of the most important thing for designing a large scale software system is an up-to-date overview of all Business Objects an their relations. For an even deeper understanding, Business Objects need to be categorized by Business Classes. Designing a Service Oriented Architecture, Business Classes and their relationship might be as follows:


Using conventional programming technique, we have to implement the Business Object using classes. Say we do have 10 different services, we do need at least 10 different classes representing these services.

Anytime a new service is implemented as a class, the Service Concept gets cemented a little more. Having implemented dozens of services, nobody can even think of touching the underlying concept.

The problem seems to be easy to understand:

• Every concept is a directive how to build some things
  
• Changing the concept enforces the change of every built thing

Having built lots of things already, changing the concept will get more and more expensive.
The basic idea of actifsource is very simple:

• Implement every concept only once

At a first glance, this sounds impossible. But we can achieve this by providing one generic implementation. The tedious work of implementing the concept over and over again can be let to your computer. That's what machine can do best!

• Every implementation of a concept has to be done only once as a generic implementation
• Specific implementations can now be generated
• Changing the concepts only leads to the change of one single implementation
• Therefore changing concepts becomes cheap

New wizards needed

This week I created two new wizards for importing and exporting the ecore model. If you ever created an eclipse jface wizard you know there are a lot of things to do.

- Create the wizard class
- Create the wizard page and add them to the wizard
- Initialize the values of the wizard and it’s pages depending on selection
- Implement the code to update status message
- Defining when a page is complete
- Place the wizard page control
- Connect the page controls that depends on each other
- Remembering and Storing the settings from last wizard usages
- Setting the initial focus control
- Defining the perform finish code

Since these tasks are always the same for all wizards we decided to use our actifsource templates to generate the wizard classes. You may notice that some of the tasks above may be done by super classes. For example we can setup the layout manager, define the page complete state and collect the status messages from the page control interfaces. We also may set the focus to the control containing first undefined value. But all these tasks don’t require the concrete types of the values. When we come to the initialization, finish and settings management code, we have to start writing a concrete subclass for this wizard and these are the classes we generate. The templates automatically create the fields for accessing the concrete wizard pages, allowing access to the specific getters and setters not on the page interfaces. I also defined the dependencies of page controls in the model. This way the code for connecting the controls with each other is created by the generator. Code that has to be handwritten is placed in protected regions. It’s the code for initializing, storing the settings, updating the status message and performing the finish action, but this time I don’t have to create the things like field for accessing the wizard page and the initialization method for each page. I’m more or less forced to put the code in the right places. The structure of each wizard implementation is kept clean.

Now all we have to do is to create a wizard instance in the model and define the pages with their control and connect them. Afterwards the generator creates the whole skeleton and we simply have to fill out the gaps. If we decide to rename a wizard all class-, field- and method names coming from the model are changed by the generator.

Look at the model:


I defined a Wizard-Class which contains WizardPages containing inputfields (package-selection, filename-selection, etc.). Each inputfield has a name and uses a fieldeditor (page controls) that may define other fieldeditor as dependency. When the fieldeditor has a dependency you must define a dependency from that to an inputfield to another inputfield using the required fieldeditor. For example I can create a package-field which is restricted based on the selected a resource folder. After defining some name, titles and page descriptions I’m ready to go. Further work that may be done is writing templates for the fieldeditors.

Finally this is one of the generated wizards, each row label, textField and button is a fieldeditor (page control).

Mapping from Ecore to the Actifsource Core (and back)

As I am currently implementing the import of models created with the Eclipse Modeling Framework (EMF) into actifsource I had to think about the mapping from ecore to the actifsource core (the mapping needs to be bidirectional such that actifsource models can be exported to ecore as well) . If you are already acquainted with modeling using EMF this blog posting should help you getting started modeling with actifsource very quickly.

As both ecore and actifsource core are self-describing meta-meta models it is not surprising that in their heart they are very similar. But the naming is a bit different:

ecore name	actifsource name
EPackage	Package
EObject	Resource
ENamedElement	NamedResource
EClass	Class
EStructuralFeature	Property
EAttribute	Attribute
EReference	Relation
EDataType	Literal
EEnum	Enum
EEnumLiteral	EnumValue

Visually compared:

As a first difference you can see that the actifsource diagram contains dotted relations between elements which correspond to an instance relation. Have you ever tried to change the type of an elment in the ecore model editor after you created it? It is not possible because the fact that one elment is a type of another comes implicitly into the ecore model.

In actifsource however, the fact that one Resource is an instance of some other is modeled by the typeOf Relation. Therefore, types of Resources can be changed as easily as any other property of the model. (The typeOf Relation is part of the Class Resource and therefore every Resource has it. That's where the self-describing plays an important role -- which can be rather confusing at first but you do not have to fully understand this to successfully model with actifsource!)

You might wonder why we did not just use ecore instead of the actifsource core when they look so similar. In the next blog posting I will analyze the differences of ecore and the actifsource core which will show you that the origin of the cores are fundamentally different.

Common Classes vs. Domain Specific Classes

Right now, I have had an interesting phone call with a potential customer. Quite important to mention - my conversational partner has lots of experience using code generators.

After a 10 minute talk, it came to my mind, that we are talking about different things. My conversational partner has the idea, that generators are transforming Common Classes from a graphical representation to a textual code representation.

Common Classes mean classes as we now them from object-oriented languages or UML. In a nutshell, such classes do have a class name, a base class, members variables and member functions.

If we have to represent a Domain-Object, let's say a Service-Object, all the properties of this Service have to be expressed by member variables and member functions. When working with Common Classes, it makes no difference whether we implement some service calls or functions to set up the service environment.

class MyUserService implements IService
{
// Service Calls
public boolean registerUser(int id, String name) {...}
public boolean deregisterUser(int id) {...}
public User getUser(int id) {...}

// Service Environment
public boolean setUserRegistry(UserRegistry userRegistry);
public boolean resetUserRegistry();
}

Using Domain Specific Classes on the other hand side, we can distinguish between functions concerning Service Call and Service Environment.

Since we are not working with Common Classes, we first have to design our Domain Specific Classes. Means, we have to specify the Attributes (i.e. class name) and the relation between these classes. In actifsource, we do this task in a diagram editor using an UML-like syntax.



Since we do have an exact Specification of our Domain Specific Classes, the Domain Objects are no longer of type Class, but type of the domain-specific class Service.

As shown above, we can now create dozens of specific services of type Service. As you know from your experience, every specific service has a similar implementation.

By example, we write a class for every service. Furthermore, we write a function for every service call. Subsequent, we do have do write a typed parameter for every service call argument.

Today, this tedious and error prone work is done for every service over and over again. But how would it be, if we could state our intension just by writing template code? Template code which doesn't depend on Common Classes - but which refers to Domain Specific Classes!



The idea behind actifsource is writing templates, bases on Domain Specific Classes, rather than Common Classes! Doing so gives you the possibility to write templates as easy as you write code.

Working with Domain Specific Classes allows you to access all the attributes of your domain in the templates which is rather easier than coping with Common Classes!

New actifsource Blog

actifsource is a state-of-the-art code-generator-workbench that tightly integrates into the popular Eclipse IDE.

In this blog we write about our everyday life as developers. Follow us to see actifsource grow daily and let us know about new features you need. Get involved: share your thoughts and discuss the merits of model driven software development.

Check http://www.actifsource.com