Best Practices / Tips & Tricks
You should actually be able to have a html rendered preview with every html editor in eclipse, which provides a html rendered preview. So far, however, we just discovered one. Amateras
Amateras is a multipage editor with two pages. The first page contains the html code, and the second page the rendered html page. You can actually configure the layout of the editor in the way, that it uses a splitted page. So, you can actually see the html code and the rendered page side by side. This is what you have to configure, if you want to use Amateras to provide a realtime preview of an html veloctiy template.
As common, you have to select the input xml-file for the velocity context, then open the apprioriate template file (make sure you named it xxxx.html.vm and you have configured Amateras as your default html-editor). Once the velocity editor is open, right click on it and select the entry "Preview type specific".
You do not have to crate a full blown generator which is neatly integrated in your IDE. Often, a set of simple scripts and templates will raise your productivity significantly. Imagine the follwing situation. You are assigned to a new project. It's mainly a common n-tier application, where the you mainly manage data.
You are assigned to implement a first prototype with a only a small subset of the domain classes that will be used in the finished product. You've already used QiQu before, and instead of simply starting with creating domain classes, you define an xml-file in which you define the domain classes, attributes and relations among them. With a simple template and an even more simple script, you generate the first version of your domain classes. The only thing inside there is to provide a member attribute and getter setters for every field and relation.
Next you notice, that you didn't provide a unique id and implementations of equal, hashcode and toString. You adapt the template, and generate the domain classes again. Next, you start to implement some simple GUIs. You write some templates, which provide basic implemtation for detail and query result dialogs for all of your domain classes. While you are doing that, you realize that you forgot to implement the PropertyChangeEvent-handling for your domain classes. You adapt the template again and regenerate. Next thing you need is a small persistence layer, so you extend the template with that functionality and write new templates, in order to generate the db scripts. It's 2:30 pm and your boss approaches you in order to tell, that you need to implement the logic for 20 more domain classes. "No problem! it'll be done by tomorrow morning", you say...
Of course, the story could go on with generating the necessary files for O/R-mapping layer like hibernate, generate the appropriate classes for EJBs, or the spring framework, and so on. The point is, that you can increase your productivity just by providing a couple of scripts and templates inside your project. You select the desired script in the package explorer, open the contextmenu and select run, and there you go. It is not necessary to implement a full blown generator plugin from the beginning. Keep it simple, start small.
You probably heard about this one already. Even if generator to provide the possibility
to mix generated and manually written code inside artefacts, you really shouldn't use it.
There are some problems related to that. Let me explain two of them.
For those of you, who have already seen an XMI-document, know that this is quite some heavy stuff. If you want to use the XMI as input for your generator, there are many things, you do not need, e.g. the positions of the elements in the diagramm. Also, information that belong together are sometimes in different sections and are only connected by an id. E.g. a stereotype of a class is not defined inside the class. Instead, all stereotype definitions are somewhere else and only linked logically by an id. The problem is, that you need to use a lot of Xpath expressions with an explizit attribute value ("//stereotype[@xmi.idref='X.25']). If you've already read the performance tutorial, you know, that such queries are quite costly. In addition it is also hard to read, and to work with. Therefor, we recommend creating a normalised modell. Remove everything you do not need from the original input, pack things together, which belong together. And then generate your code based on this normalised model. This also reduces the dependency to a certain version of XMI or vender implementation.
Of course, switching the generator framwork does produce some extra cots. But you do not have to do all the work. The process of introducing modell driven development inside a company, is likely much more expensive, than just switching the generator framework. Once you are following a modell driven development approach, you have already adapted your development process, your build process, you convinced the management and devlopers and so on. Moreover, you have already created a generator. You know exactly, what is supposed to do, and you know exactly, which input is provided. This makes the implementation of a generator based on a other framework almost risk-free. You simply compare the output of the old generator with the output of the new generator. If they match, the new generator does the same thing. With todays formatting possibilities inside the IDE and the compare and merge tools. It shouldn't be too hard, to provide the proof, that the new generator does the same thing.
Inside an UML model, you can add stereotypes and tagged values to almost every element inside the model. So, similar as you can defined tags inside comments of java sources and using Xdoclet, you can define anykind of tagged value and create a generator which uses this input. However, the UML-model should be a kind of business abstraction and adding technical aspects like foreign-key attributes for relation or special tags to create the jboss.xml could probably overload the model. In the case you prefer to separate the business model from techinical aspects instead of having all information in one model, create for everyl class an own definition xml. Inside this definition xml, you could define the relations to other classes in detail, or what kind of O/R-mapping strategy should be used. If you plan to generate your applicatin for different platforms, you could also create differnt definition xml files for every class. See also the next point.
If you define your complete model or just a part of it as pure xml files, define also an appropriate DTD file for them (actually, a couple of XML-editor like XMLBuddy are able to generate at least an inital version of the DTD out of on existing xml file). A lot of XML-editors (again e.g. XMLBuddy) give you the possibility to attach the DTD directly to a rootnode. So, even if you edit a file without having the DTD file defined in the xml file itself, the XML-editor will provide code-assist and validation for it. This comes almost free. If you need a more sophisticated editor, consider building your own editor like the "plugin.xml"-editor of eclipse. Xml Mpe FW could be a starting point for such an editor.
When you are following a modell driven development approach, you have to trade your models the same way, as you do with your source. This means, you need to be able not only to versioning the whole model, but also single parts of it. It's the same, as with source code. You do versioning a single source-file. Therefore, you should also be able to versionize a single UML-class element in an UML-model. So, if you have a modelling tool, which holds the whole model information in a single file, that's probably not want you want to have. Next, you need to be able to work concurrently on the model. If you have, for example, a domain model with 200 classes, the likelihood that more than one person needs to update the model at the same time is quite high. The first key success factor is having a tool, that does not store the model as one single file, as I mentioned before. If the tool saves to whole model in one file, this means that you need to merge the model every time, if more than one person has made changes at the same time. If the tool does store single parts of the model in single files, you should be able to easily recognize, which file belongs to which part. This means, if you have inside a domain class model a class X in the package Y, you should see that somehow in the file name and directory structure of the appropriate file. If there is just a cryptic name, you'll be stuck, if you use a versioning tool with pessimistic locking. Imagine yourself wanting to change the domain class X and trying to lock the right file. Next point, the content of the files need to be human readable, because you need to be able to merge and to compare different versions. So let me summarize that:
You need also to adress this points, when you define your own model editor. With tools and frameworks like the Graphical Modelling Framwork creating even graphical editor is getting easier and easier, but you may not forget to have an appropriate solution for your versioning needs.
One thing that was working pretty well in a project, was using Together 6.2 to define a domain model. The could be stored there as java source. So every domain class was defined in a java class file. Moreover, the same files were also referenced from an eclipse project. So we could actually edit the model and use the refactoring possibilities of eclipse to change the model.