I would like to see the TextUML Toolkit as an Eclipse MDT subproject. Not long ago, I talked to Kenn Hussey and Ed Merks about the idea of proposing the Toolkit to the EMO and they both liked it (Ed actually suggested the idea in the first place). However, I was concerned that just one guy (yours truly) working on the project on and off in his spare time with no user community didn’t look very promising, and Kenn promptly agreed, so it was decided that it was important to get other people on board first.

With the intent of starting to gather some sort of community and hopefully contributors, I decided to release version 1.1 as EPL. In the first couple of weeks after that, I noticed a significant spike in interest (page hits, issues opened, forum activity). But then everything went back to how it was before: today, there is no evidence anybody is using the tool, and I am still the only committer in the project.

So, this is a call (or a cry) for contributors: if you like the textual approach to UML modeling proposed by the TextUML Toolkit, would like to help putting together a proposal, and have some amount of time/resources to commit to the project in the long(ish) run, I am really eager to hear from you.

Things that are in scope for the project:

• broader notation coverage of UML features
• richer IDE support: content assist, search/hyperlinking, refactoring
• better integration with graphical UML tools

If you are interested, feel free to contact me via this blog, the Toolkit forum or e-mail (rafael at abstratt.com).

Just checked in a new feature in the TextUML Toolkit: required extensions for stereotypes (honestly, I didn’t know about that feature in UML until I read this post on the Eclipse UML2 newsgroup).

The following is a stereotype extending two metaclasses (uml::Class and uml::Operation):

profile my_profile;

import uml;

stereotype foo extends Class, Operation required
end;

end.

In the example above, the extension of Operation is required, the extension of Class is not.

Change set

The change set to implement required extensions in the TextUML Toolkit (issue #2266268) was quite small (btw, kudos to the UML2 project for providing the best API for UML out there).

Here are the individual changes per plug-in (r153-r156):

• automated tests
• parser and model generation
• textual renderer
• editor

Any other UML feature you would like to see exposed in the TextUML notation? Suggestions are welcome.

The first milestone build of the next TextUML Toolkit release is now available from the milestone update site. This preview build is the first to include support for modeling behavior using action semantics. I hinted at this capability here before, and I plan to cover action semantics in the TextUML notation in following posts. But most people will get the gist of the notation from the examples below:

Here is an example of a UML model of an Account class represented in TextUML:

model bank;

import base;

class Account
    attribute accountNumber : String;
    attribute balance : Integer;

    operation withdraw(amount : Integer);
    begin
        self.balance := self.balance - amount;
    end;    

    operation deposit(amount : Integer);
    begin
        self.balance := self.balance + amount;
    end;

    static operation newAccount(number : String,owner : Client): Account;
    begin
        var newAccount : Account;
        newAccount := new Account;
        newAccount.accountNumber := number;
        newAccount.balance := 0;
        link ClientAccount(owner := owner, accounts := newAccount);
        return newAccount;
    end;
end;

class Client specializes Object
    attribute name : String;
    static operation newClient(name : String): Client;
    begin
        var newClient : Client;
        newClient := new Client;
        newClient.name := name;
        return newClient;
    end;
end;

association ClientAccount
    navigable role owner : Client[1];
    navigable role accounts : Account[0, *];
end;

end.

And here an example of a test driver ‘program’ (note the use of a closure for looping through a collection of objects):

package test;

apply base_profile;

import bank;
import base;

class TestDriver
  [entryPoint]
  static operation run();
  begin
      var john : Client, mary : Client,
             account1 : Account, account2 : Account, account3 : Account;
      john := Client#newClient(”John Doe”);
      mary := Client#newClient(”Mary Doe”);

      Console#writeln(”Created: “.concat(john.name));

      account1 := Account#newAccount(”1234-1″, john);
      account2 := Account#newAccount(”1238-2″, mary);
      account3 := Account#newAccount(”2231-7″, john);

      Console#writeln(”account owner: “.concat(account1->ClientAccount->owner.name));
      Console#writeln(”account number: “.concat(account1.accountNumber));
      Console#writeln(”initial balance is: “.concat(account1.balance.toString()));

      account1.deposit(2000);
      Console#writeln(”after deposit, balance is: “.concat(account1.balance.toString()));

      account1.withdraw(500);
      Console#writeln(”after withdrawal, balance is: “.concat(account1.balance.toString()));

       /* Now show information for all accounts. */
  	Account extent.forEach(
          (a : Account) {
              Console#writeln(”*******”);
              Console#writeln(”Owner: “.concat(a->ClientAccount->owner.name));
              Console#writeln(”Number: “.concat(a.accountNumber));
              Console#writeln(”Balance: “.concat(a.balance.toString()));
          }
      );
  end;
end;

end.

And here is the output of the test driver program, produced by running it on the Libra UML runtime (not part of the TextUML Toolkit):

Created: John Doe
account owner: John Doe
account number: 1234-1
initial balance is: 0
after deposit, balance is: 2000
after withdrawal, balance is: 1500
*******
Owner: Mary Doe
Number: 1238-2
Balance: 0
*******
Owner: John Doe
Number: 1234-1
Balance: 1500
*******
Owner: John Doe
Number: 2231-7
Balance: 0

Alternatively, one could have generated 100% of the code for a target platform of choice, given that all the information necessary for that is in the model. Note that code generation is not part of the TextUML Toolkit.

Do you want to give it a try? Install M1 from the milestone update site. You can also fetch the example projects from here.

It is certainly a rough stone. I am counting on the community feedback to figure out what areas need to be smoothed first. Please provide your feedback or ask questions on the TextUML Toolkit forums.

Do you know what UML can do for you? I mean, did you know that UML models can actually do things?

One of the least known features of UML is that you can model detailed imperative behavior. The UML “instruction set” can do things like:

• create and destroy objects
• create and destroy links (associations) between objects
• read and write attributes and local variables
• invoke operations and functions
• throw and catch exceptions
• conditional statements
• loops

That is quite amazing, isn’t? And all that while still preserving a high level of abstraction. Such capability is generally referred to as ‘action semantics’. Action semantics provides the basic framework for executability in UML and has been there for quite a while now. It was originally added to the spec, first as patch, in UML 1.5 (2003), and then more seamlessly integrated into UML 2.0 and following spec releases.

Action Semantics and TextUML

An even more well-kept secret is that the TextUML notation supports UML action semantics and thus the creation of fully executable UML models. This support is not yet shipped as part of the TextUML Toolkit, but will be in the next release. Meanwhile, if you want to give it a try or take a closer look, you will have to grab the source from the SVN repository.

I plan to go into more details in the near future, but just to wet your appetite, here is one example of an executable UML model described in the TextUML notation:

package hello;

apply base_profile;
import base;

class HelloWorld
    [entryPoint]
    static operation hello();
    begin
        Console#writeln(”Hello, World”);
    end;
end;

end.

Cool, isn’t? If you had a UML runtime, this model could be executed even before you made a decision about what platform to target. Also, if your code generator were action semantics aware, you could trigger code generation for the target platform(s) of choice, with the key difference that you could achieve (or get very close) to full code generation, as the model now also describes behavior. No more of that monkey business of having to edit the generated code and manually fill in all those /* IMPLEMENT ME! */ methods.

Do you think this has value? Would you want to work with a tool that supported that? I am really keen on knowing your opinion.

This is actually old news for many people, but recently I learned (by pure chance) that the OMG issued a RFP for a “Concrete Syntax for a UML Action Language”. Letters of intent are due on December 8th. Submissions, one year after. OMG members only need apply (Aww…). I wonder if anyone in the Eclipse Modeling project is involved in submitting a proposal. Anyone?

Soapbox: since version 1.5, UML has had support for algorithmic behavior specification, commonly called action semantics. It is still hardly used, and most people that consider they know a lot of UML have never noticed it. Some people believe that the lack of an official concrete syntax for action semantics is a barrier to adoption. You see, the OMG defined the semantics and an abstract syntax, but left concrete syntax as an exercise for tool vendors.

As I wrote here before, I don’t really see the value in the OMG godfathering one concrete syntax over all others. Of course, we are talking here about a syntax for human beings, not for tools. Tools certainly don’t need a human-readable concrete syntax, a standard binary or XML format will do. The problem is: we all have our own preferences for what makes a good syntax, and there is no single syntax that will make everybody happy, so we are bound to have multiple concrete syntaxes anyway. We all like interoperability between tools, but when it comes to sugar, we like choice.

But maybe I am wrong. Maybe an OMG-blessed C-like concrete syntax for UML is all that is missing for Executable UML to become mainstream in the software development community. Go figure, we are an amusing bunch. Personally, I don’t care that much. I have been a Java developer for around 12 years now, so I can certainly stand another C-like syntax. We are not talking about a language anyway, it is just a syntax for an existing language, and syntax, a bit like UI, is inherently disposable, if you take it away, the real stuff is still there.

One clear positive outcome of the RFP is that submitters must provide, along with the proposal for a concrete syntax, any changes to fUML* that would be required to support such action language. That will probably help closing some gaps in the UML specification that make it hard to execute if you are stuck with the standard.

There are many other interesting bits in the proposal, but I will leave a more detailed analysis to a future post.

* the Executable UML Foundation Submission says:“Foundational UML Subset (fUML) is that subset of UML required to write ‘programs’ in UML”

I posted this earlier this week on the UML2 newsgroup, thought I would share it here too…

I published a TextUML rendition of the UML 2.1 metamodel that is shipped by Eclipse UML2 here (warning: 5.9k lines, 370Kb of text). It starts like this:

(...)
model uml;

apply Ecore;
apply Standard;

import ecore;

(* A comment is a textual annotation that can be attached to a set of elements. *)
[Standard::Metaclass]
class Comment specializes Element
    (* Specifies a string that is the comment. *)
    [Ecore::EAttribute(isID=false,isTransient=false,isVolatile=false,isUnsettable=true,annotations=[])]
    public attribute body : String;
    (* References the Element(s) being commented. *)
    public attribute annotatedElement : Element[0, *];
end;
(…)

Thought it could be useful to anyone wanting to have a quick look at the UML metamodel. The TextUML renderer does not support all UML element types, so some elements might be missing/incomplete.

I think that is a nice demo of the textual browsing capabilities in the TextUML Toolkit. Of course, much more could be done in that area. If you feel like lending a hand, any help (bug reports included) will be much appreciated.

Shorthand notation for both composite and aggregate associations has just been checked in (r99-r100). It follows the same spirit as the existing shorthand for plain associations (a.k.a. references).

composition <end-name> : <referenced-type-name>;

or

aggregation <end-name> : <referenced-type-name>;

That will result in a new unnamed association with two member ends, one named, owned by the declaring classifier, with composite or shared aggregation type, and another unnamed, owned by the association itself.

Change set explained

When adding a new feature to the notation, the typical change set contains:

• updates to the affected grammar production rules
• implementation of the corresponding model generation handling code
• a few test cases.

In the case of the features presented in this post, the grammar change was quite simple (nicer view):

--- trunk/plugins/com.abstratt.mdd.frontend.textuml.core/textuml.scc	2008/09/16 05:47:13	99
+++ trunk/plugins/com.abstratt.mdd.frontend.textuml.core/textuml.scc	2008/09/16 05:47:20	100
@@ -341,7 +341,9 @@

   attribute_decl = attribute identifier colon type_identifier optional_subsetting semicolon ;

-  reference_decl = reference identifier colon type_identifier optional_subsetting  semicolon ;
+  reference_decl = reference_type identifier colon type_identifier optional_subsetting  semicolon ;
+
+  reference_type = {association} reference | {composition} composition | {aggregation} aggregation ; 

   optional_subsetting = subsets qualified_identifier | {empty} ;

In other words, where one could declare a reference, one can now declare also a composition or an aggregation (gotta love the readability of SableCC grammars…).

The corresponding model generator (a.k.a. compiler) changes were quite trivial as well, even more so if you consider I inadvertently checked in a fix to an unrelated bug around comments (just ignore the changes in lines not in the 300’s).

In terms of lines of code, the bulk of the changes were in the test class for associations, where I added three test cases. I had postponed writing tests for the reference shorthand notation, so I took this opportunity to write a test for it too.

As most test cases in the TextUML Toolkit test suite, the new test cases in AssociationTests have the following layout:

• one or more compilation units with TextUML source code are declared
• source code is compiled and the resulting errors verified (most test cases won’t expect errors)
• the resulting model is checked - were the expected elements created? Do they have the expected features?

Talking about tests

The TextUML Toolkit has a modestly sized test suite (~130 test cases) at this time. It could use dozens, probably hundreds more, but most features are covered to so some extent.

However, as important as coverage, is how much one can learn about the piece of software being tested by reading its test suite. And here is where I believe the TextUML Toolkit’s test suite shines. For example, by reading the test classes, one could (maybe more effectively than by reading the notation guide), learn how the following UML features are exposed by the TextUML notation:

• classes and structural features
  
• packages, imports, profiles
• associations
• multiplicity
• template classes

Trivia: can you find out from the test suite the difference between a private and a public package import? Give it a try and let me know if I am lying… by the way, the notation guide does not cover that yet, although the UML specification, of course, does.

I often see the TextUML Toolkit being compared to tools that produce UML diagrams from textual descriptions. Examples of tools like that are ModSL, MetaUML and UMLGraph. But that doesn’t really make sense, and here is why: these tools produce diagrams from text. The TextUML Toolkit produces models from text. But what is the difference between models and diagrams?

According to Wikipedia:

• A diagram is a 2D geometric symbolic representation of information according to some visualization technique.
• A model is a pattern, plan, representation (especially in miniature), or description designed to show the main object or workings of an object, system, or concept.

Note that even though both terms are defined around the word “representation”, the term “diagram” implies graphical visualization, whereas the term “model” admits any kind of media, basically because models have no concrete form per se.

Now, please, if you are not convinced yet, read aloud 5 times: MODELS ARE NOT DIAGRAMS!

If that didn’t work, well, maybe the facts below will help:

• models, not diagrams, are the subject matter of model-driven development.
• models, not diagrams, can be validated.
• models, not diagrams, can serve as input to code generation.
• models, not diagrams, can be automatically generated from reverse engineering source code.
• models, not diagrams, can be executed.

Even though diagrams are commonly used for representing models, they are not the only way, and non rare not the most appropriate one (yes, I am talking again about the virtues of textual notations, but I won’t repeat myself).

P.S. Maybe it helps adding to the confusion the fact that the TextUML Toolkit has an optional feature that will generate class diagrams automatically from the UML models created with it. However, that is just an optional, loosely integrated feature, and it is definitely not the Toolkit’s thing. Weirdly enough, from my observation, that feature is the main reason most people become interested in the TextUML Toolkit. Well, go figure.

TextUML Toolkit 1.1 is out! This is the first release after the TextUML Toolkit became an open source project. Besides the adoption of the Eclipse Public License, these are the new features that were added in 1.1:

• more UML features exposed by the textual notation: abstract operations and parameter direction modifiers
• more diagram layout controls (compartments, elements across packages)
• support for exporting the class diagram to a PNG or JPG image file (actually, an EclipseGraphviz feature, also available for other graphical content providers)

Also, the TextUML Toolkit is not available any longer as a standalone download. You need to install Eclipse 3.4 first  (3.3 support was dropped) and then install the TextUML Toolkit using the new smart Software Updates mechanism in Ganymede. See new install instructions here.

As usual, feedback is most welcome - blog, issue tracker or forum, whatever option works best.

Since I started working on the TextUML Toolkit more than a year ago, I have been asking myself whether it would make sense to make it available under an open source license.

Open sourcing a product is a tough decision. Once you take that road, there is no way back, at least not without risking a backlash from the community (of course, if you managed to build a community). And even though there are more and more examples of successful businesses built on top of open source offerings, they are still the exception. However, from day one, my plan for the Toolkit has always been to give it away for free. Going from “free-as-in-beer” to “free-as-in-speech” is not nearly as traumatic.

I resisted to the idea while I was working on releasing version 1.0, as I considered it as potentially distracting and of questionable value, as then I knew exactly what I wanted to ship and how to get it done. However, now that 1.0 is out of the way, it seems the right thing to do. The first release provided a good starting point, but the project certainly needs more hands on deck to get to the next level. It is also clear that an open source license means a lot when you are catering to a developer audience.

So, you heard it here first: the next release of the TextUML Toolkit will be licensed under the Eclipse Public License. The source code is already available on SourceForge, and user forums and issue tracking are now also hosted there.

Joining the Eclipse Modeling project (more specifically the MDT subproject) is an option for the future, depending on whether the project succeeds in attracting other contributors.

Using the tool, spreading the word, asking and answering questions on the forum, reporting problems and requesting features are all great ways of helping. Regarding new features, the project needs help on two main fronts: broader coverage of UML (state machines, activities), and better IDE features (such as content assist, templates, symbolic search and refactoring). If you like the textual notation approach, the tool, and feel like you could lend a hand, please do, the TextUML Toolkit needs you!

I just completed the code for supporting parameter direction modifiers. When this feature makes into the next build, modelers will be able to choose for named parameters any of the standard parameter direction kinds: out, inout, or (the default) in. By the way, the syntax for specifying return types remains the same. Here is an example:

  operation op1(in p1 : String, out p2 : String);

Java developers might consider this feature unnecessary as there is only one way of passing parameters in Java, but for distributed applications (such as those using CORBA or web services) these modifiers are quite relevant.

The corresponding support for rendering operation parameter direction kind modifiers has been added to the TextUML model viewer (decompiler) and EclipseGraphviz graphical rendering component.

This is the first new feature since version 1.0 was released.  The impact of implementing it was quite minimal to the code base, so I am looking forward to implementing the next notation feature. The question is: what feature? Any suggestions?

One potential downside people often point out about using TextUML as a notation for UML is that it is yet another language to learn. But that is not really a well founded argument. TextUML is not a full-blown language, it is just an alternative notation for UML, the de facto standard language for modeling. The language semantics of UML are defined in terms of an abstract syntax, and even though the specification includes sections about the graphical notation, it clearly supports the idea of alternate concrete syntaxes.

Moreover, we really shouldn’t care much about the actual notation being used, be it the standard graphical notation, TextUML or any other textual notation. I surely don’t. Regardless what notation you use for creating UML models, in the end there is only one language. All you know about the semantics of UML model elements is still true no matter what syntax you choose (for instance, if you know your UML, you should easily become productive with the TextUML Toolkit by just glancing over the notation guide now and then). In fact, I predict a time where people will want to move between different notations across tasks and time. Also, in the same team, different people will be collaboratively creating UML models using different notations.

This will only be possible because supporting a new concrete syntax is much simpler than supporting a whole new language (by the way, that is the same reason why I believe UML-based DSLs to be a better option than homegrown proprietary DSLs, but I digress). Any reasonably good programmer armed with a parser generator and knowledge of the metamodel should be able to write a compiler for a textual notation for UML, and Eclipse makes it really easy to provide basic IDE features such as those you see in the TextUML Toolkit. Also, there are tools in the horizon such as IMP and TMF that will make these tasks really a breeze.

Meanwhile, you can stick with what is here today.

I just uploaded the first interactive presentation showing how to install and configure the TextUML Toolkit on Eclipse 3.4. It starts with a plain Eclipse Platform Runtime install, and guides the reader through the following steps:

1. making sure you have the right version of Eclipse (3.4)
2. adding the TextUML Toolkit update site
3. installing the TextUML Toolkit and EclipseGraphviz
4. configuring EclipseGraphviz to point to your Graphviz install
5. opening the Image Viewer view to show models using the graphical notation
6. creating an empty TextUML Toolkit project
7. creating an empty TextUML source file
8. creating a minimal class diagram with a package and a featureless class
9. understanding the edit/compile/visualize cycle

Give it a try and let me know what you think. Blame me for any weird screen transitions. Wink is a great little tool but has a few small quirks that I have yet to master, but the next presentation should look better. Cheers,

Rafael

According to an announcement made on the acceleo-dev mailing list, Acceleo 2.3.0 has been released today. Congrats to the folks at Obeo! The latest bits are already available from Acceleo’s update site, but the download page still shows 2.2.1 as the latest release available.

That is one less excuse for using Eclipse 3.3, which was the latest release supported by Acceleo 2.2.1. An added bonus is that the TextUML Toolkit is much more stable on Eclipse 3.4 due to a nasty concurrency bug fixed in UML2 for the Ganymede release (kudos to Kenn and James!).

I just updated the install instructions for the Pet Store example application. With a new and improved Software Update mechanism (a.k.a. P2), it became much simpler to install the TextUML Toolkit and Acceleo on Eclipse 3.4. For instance, no need to worry about EMF or UML2, they are transparently installed. How cool is that?

I am proud to announce that the TextUML Toolkit reached version 1.0!

It is basically the same as the RC3 build, made available earlier this week, with version numbers updated to reflect the status of release. You can download the TextUML Toolkit 1.0 from here.

Even if it still preserves the same humble look & feel, the TextUML Toolkit has come a long way since the first public milestone was announced here more than a year ago:

• M1 - May 2007
  • website went live
  • first public milestone
• M2 - September 2007
  • graphical class diagram visualization for Windows only (spawned as a brand new open-source project, EclipseGraphviz)
  • support for enumerations
• M3 - March 2008
  • reverse engineering of UML2 models as TextUML source (aka textual browsing)
  • diagram rendering also on Linux and Mac OS/X
  • click-through license
  • better stability and performance
  • website improvements: added user forum (SMF)
• M4 - May 2008
  • duplicate symbols properly reported as compilation errors
  • TextUML source renderer showing nested packages
  • evaluated a few code generators (Acceleo, oAW xPand, EMF JET), chose Acceleo
  • first milestone available via update site
• M5 - June 2008
  • fixed a serious memory leak caused by UML2 caching
  • several bug fixes
  • decoupled the TextUML Toolkit from EclipseGraphviz (EG becoming just a possible integration)
  • website improvements: wiki-based (MediaWiki) documentation area
• 1.0 - July 2008
  • support for applying stereotypes to stereotypes
  • provided a Pet Store-like sample application
  • more, better documentation

On the outreach front: in December, I did a quick presentation of the TextUML Toolkit during the Eclipse DemoCamp in Vancouver, and had the opportunity of doing a longer, more detailed presentation at the VIJUG’s meeting in April. At both opportunities, receptivity to the project was quite good. People seemed very keen on the idea of UML models as text, and I got lots of interesting questions.

In early June, I joined many other fellow mISVers in the 30-day product challenge. Even though I didn’t achieve everything I had set out to do, I am quite happy for having been part of it, as it provided me with the strength and courage to finally ship the first release.

Overall, I am quite happy with the current state of the TextUML Toolkit (or else I would not have declared a release). On the other hand, I confess I am disappointed that interest has not picked up yet, considering it is a free tool that provides real value. Now that there is an example describing how to use the TextUML Toolkit and Acceleo for generating code from UML models (which is the main application of the tool), I hope the value of the tool will become more apparent. And I guess more attention to the marketing side of things won’t hurt.

For the next few months, I will be focusing on a more ambitious project I have hinted at here a couple of times before. During this time, I will be promoting the TextUML Toolkit, writing more documentation and examples, and fixing any bugs users might report, but I do not plan to develop any new features unless there is user demand.

Well, it has been a fun ride, and I appreciate the interest of those of you who have followed at least some part of the journey. Your comments on the blog have been very helpful and encouraging. Thanks a lot!

Cheers,

Rafael

The Pet Store-like model-driven sample application is now available. This initial version contains UML models for a few of the key entities, and generates the domain model classes and their corresponding Hibernate mapping files. I noticed the generated mapping files (or maybe the models) have a few issues and/or missing elements, but as a first stab I am quite happy. Please give it a try. It is a great way example of how the TextUML Toolkit can be used in the context of code generation, in this case, with the awesome Acceleo tool (open-source). Note this is just an example - you should be able to use any UML2-based Acceleo modules (like those available from Acceleo’s module repository) and generate code from any UML models you create using the TextUML Toolkit.

In addition to the sample application, the latest TextUML Toolkit release candidate (RC3) is also now available, both as a standalone download and as an update site, as usual. Work items delivered in this build:

• ticket #182 - associations end up with one single member end
• ticket #183 - cannot define stereotypes on stereotypes
• ticket #167 - provide sample application

To my fellow 30-dayers - yes, its 8 days past the 30 day deadline, but unless I get a serious bug reported during this week, this is it, I am about to achieve my modest goals (yay!) of shipping 1.0 and a sample application (remember, I started working on the TextUML Toolkit quite while ago). The only planned change for 1.0 is basically updating the splash screen to sport the elusive 1.0 version number.

Feedback on RC3 or the sample application is most welcome. As usual, feel free to comment here or on the forums.

Cheers,

Rafael

Even after cutting scope to close to half of what I was planning, I failed to accomplish what I set off to do in the 30-day challenge. I basically have the code and the example in a releasable state, but I have no means to publish a tutorial with images due to some unexpected web site issues. Even without this issue, I might not have made it, given how much work I left to the last day. Anyway… after spending quite some time trying to get MediaWiki to behave (with no success), now I don’t have time or energy for packaging and pushing the bits of the TextUML Toolkit RC3 (hopefully 1.0?) to the FTP server. Should do that at some point this week, and also hopefully get the wiki back online.

Well, enough ranting, need some sleep now. Thanks to the other 30-dayers for being part of this, and hope you guys had better luck. Cheers,

Rafael

P.S.: I considered not writing in my current mood, but I thought in the end it would be more honest doing so, so there you go

Well, things are not going so smoothly in TextUML Toolkit land. Hope the others are doing better.

• a user reported that the embedded Graphviz install was not working for him on Windows XP (I expected it to work on all Windows versions, but really tested only on Vista). After some investigation, I realized that a minimal Graphviz install will look very different depending on the Windows version. Result: I decided to quit bundling Graphviz for Windows. Now, the TextUML Toolkit users on Windows have to manually install Graphviz on their own, and configure the location of an external Graphviz manually, just as Linux and Mac OS X users had to do since day 0. The latest build RC2 (just published) already reflects that change.
• a simple Wordpress migration using GoDaddy’s Hosting Connection became a big hassle (their rollback feature did not work either). Result: had to delete my existing install, and install the latest version from scratch (thankfully, Wordpress export/import features worked like a charm). Lesson learned: avoid doing any infrastructure changes that are not critical in the weeks preceding a release (even if they seem harmless).

I finally woke up to the fact I am really late with most of the deliverables I planned for June 30th and we are already a week from the deadline. I decided thus to postpone all non-product related items. Other than any critical bug that might be found this week, I will be focusing on publishing the sample application on the wiki. Nothing else.

Well, maybe some blogging.

I finally figured out what was preventing me from exporting the product from Eclipse and worked around the problem. So the TextUML Toolkit RC1 is finally available for download, 4 days after planned.

It turned out the issue that was blocking me was not specific to Eclipse 3.4 RC3. Still, I decided that, until the end of the 30-day challenge, I will continue to use 3.3 to avoid any further surprises. I intend to go back to 3.4 shortly after that.

Another important task that was planned for the first phase (first two weeks) and I have yet to address is the sample application (models + templates). That means some of the less critical work items planned for the second phase will have to be postponed (probably the artwork item).

Even though I am behind schedule, I am really happy to be moving forward again…

(To my fellow 30-dayers: It has been a while since my last post in the 30-day challenge category - at least if you think of how brief it is. But worse, I am also behind the schedule. My goal was to have the first release candidate on the 15th. It is the 17th and I am not quite there yet. Read on for details)

Every now and then, the Eclipse Project goes through quite significant changes (OSGi and RCP in 3.0, P2 now in 3.4). And when the platform moves this fast, everybody living above feels it. New features are not well documented or are not very stable. Tooling for plug-in developers lags behind. Things that used to work before, are now broken.

That is really hard to avoid, even though backward compatibility with the previous release is a hard requirement for the Eclipse Project. I was part of the Eclipse Platform Core team in 3.0 (shipped in 2004) and even though we were having lots of fun with the move to OSGi and the birth of Equinox, it was a lot of work having to implement the new functionality and at the same time make sure all the existing use cases continued to work. And, as usual, some corner cases we missed were only discovered close to the release date, or even right after, when most people will finally migrate from the previous release. Many of the OSGi-aware features were only exposed by the plug-in development tooling in the subsequent releases. And even though we felt like all that backward compatibility effort was draining a lot of our time and energy, users would still get mad at us for introducing regressions, when they didn’t really give a damn about OSGi or RCP.

In hindsight, it is clear that all that work paid off when you look at the impact that OSGi and RCP had in the growth of Eclipse way beyond the realm of IDE frameworks. People are using Eclipse as a platform for embedded and server-side applications, or rich client applications you could swear were native. OSGi itself had a boom in adoption (and features) since when it was adopted in Eclipse and moved from niche technology into the mainstream.

I am sure the same is going to happen with P2, probably in smaller proportions (given its scope). We will be taking its features for granted two years from now, and the pain of change will have been long forgotten. And the good people developing P2 know that. But, this time around I am…

…on the other side of the fence

The plan of shipping TextUML Toolkit 1.0 (scheduled for June 30th) on top of Eclipse 3.4 (scheduled for late June - yes, that should have raised a flag) proved to be quite a challenge. I have had minor problems with the latest Eclipse SDK milestones, which I could work around, but more recently I have faced more serious, blocking issues. And even the non-blocking problems and difficulties, which are just time wasters, grow in importance when you are in a tight schedule.

So I stepped back and decided to and develop and ship the TextUML Toolkit 1.0 on Eclipse 3.3, which was last year’s release. It was not an easy decision, as I will be missing many improvements and fixes (some of them to pretty significant issues) made in the UML2 and EMF components, which are the main requirements. But at least I should be able to move forward in a more predictable pace, and be more confident I have a chance of meeting the June 30th deadline, even if quality might suffer. On the bright side, thanks to backward compatibility, the same update site should still work with 3.4, so users using the Update Manager/P2 in Eclipse 3.4 should be able to install the TextUML Toolkit features, and get better performance and stability.

What makes me feel good is that backward compatibility continues to be one of the Eclipse key values (e4 rumors aside), so regressions receive high priority and are fixed as quickly as possible. The least we (end-users and product providers) can do is to diligently report them.

Contrary to my original intention of working this week on code generation and the sample application, I have been doing some improvements in the graphical visualization of UML models in EclipseGraphviz. EclipseGraphviz (a spin-off of the TextUML Toolkit) is an open source component (EPL) that integrates Graphviz into Eclipse, and among other things, can generate UML class diagrams from Eclipse UML2 models on the fly.

After fixing a couple of bugs, I decided to add a preference page to give some level of control over the way the diagrams are laid out. Here is what it looks like:

You can now turn on or off several adornments such as association end names, multiplicities and membership. For example, this diagram was rendered using the options shown above:

Whereas the following one was rendered for the same model while having only the “Create constraints for association navigability” option checked:

As you can see, enabling constraints based on association navigability can significantly alter the diagram layout. One good reason for enabling that option is to avoid diagrams that grow too much horizontally (as Graphviz will put all nodes of the same rank on the same row), but I personally prefer the former layout.

Side note: I considered dropping the graphical visualization feature altogether for 1.0, as I see it as just a nice to have, and am not totally happy with the quality of the diagrams generated by Graphviz. But every bit of feedback I got for the TextUML Toolkit was that the graphical visualization was really nice, so I changed my mind. But unless serious bugs are found in this area, I have no plans of touching the EclipseGraphviz code again until after I complete the 30-day challenge.

Side note #2: I expanded the FAQ to cover the issue of notation choice and the role of EclipseGraphviz in the TextUML Toolkit.

Took a first stab at creating the model for the sample application for the TextUML Toolkit. As I wrote here before, the sample application is derived from Sun’s Java Pet Store application. Take a look at the models, and let me know how the textual notation feels.

It is late and I am tired, so it is very likely I have made at least a few mistakes (well, not syntactic ones, as the tool tells me about those). Of course, when I start working towards generating the code from the models, I am sure any mistakes I made will quickly emerge.

Cheers,

Rafael

M5 is now available. You can download a self-contained product install, or use the Eclipse update mechanism for adding the TextUML Toolkit to your Eclipse SDK (3.3 or 3.4), on Windows, Mac OS X or Linux. Please see instructions on the download page.

This milestone was mostly about bug fixing (including a performance bug), but it also included a minor architectural change: graphical visualization is now optional, and supports different implementations.

This is the list of bug fixes:

As I mentioned before, I joined the 30 day product challenge with the TextUML Toolkit. Of the benefits of being part of the challenge, the ones that most attract me are the sense of being part of something greater, and the motivational power of peer pressure (even if imaginary) and fear of public failure. With that in mind, these are my commitments for the challenge:

Phase 1 - June 1st to June 15th:

Focus on finishing development and examples.

• publish the milestone 5 of the TextUML Toolkit (M5) (done)
• making UML graphical visualization an optional component (done)
• publish an example application
  • model - probably a subset of the Java Pet Store app
  • code generation templates - probably using Acceleo
• should target Eclipse 3.4 (done - M5 can be installed on Eclipse 3.4 or 3.3, but download will continue to bundle 3.3 due to lack of tool support for product creation in the new software update mechanism available in Eclipse 3.4)
• bug fixing (continuously)
• improve documentation (continuously)
• publish Release Candidate 1 on June 15th
• development freeze

Phase 2 - June 16th to June 30th:

Focus on polishing and getting it out of the door.

• major/critical bugs
• minor bugs/polish items
• improve documentation (continuously)
• artwork
  • icons for TextUML source files, new project wizard (outsource)
  • website (images, skins)*
• legal stuff
  • make sure we comply with all licenses for any bundled open source software
  • legal notices using Eclipse branding
  • beef up license (no redistribution, no reverse engineering)
• PR (go easy, this is 1.0) - EPIC, announcement-friendly developer forums
• one active beta-tester
• one early adopter*
• screencasts (this is a biggie)
  • creating a UML model using the TextUML Toolkit
  • generating code using Acceleo
• RC3 on June 29th
• declare 1.0 on Monday June 30th

* marks nice-to-have items

There you go. You, my readers (yes, both of you), can now hold me accountable if I fail to accomplish any of the work items I committed to do above.

To my fellow 30-dayers: good luck to us all. It will be fun!

There was a recent thread about UML on Slashdot, as a reaction to this blog post . The headline: “Is UML Really Dead, Or Only Cataleptic?“. Many posters are clearly bitter towards UML. There seems to be a strong preference for using UML as a communication tool as opposed to as a basis for partial or full code generation (see post on UML modes). Many also complain that the graphical notation is cumbersome and that it hurts productivity (+1!). A few actually like UML; however, it is said that the UML specification is vast and complex and that you should pick the parts of UML that make sense for your case/goals (+1 here too).

Lots of interesting points, but the most negative posts are just misinformed. But that is Slashdot, what should I expect? Java and Eclipse have, in general, a poor receptivity on Slashdot, so I guess UML is in good company.

Of course, while I disagree with those that ditch UML because it was not properly employed in some project they worked, I strongly agree with the complaints about UML (graphical) diagrams being cumbersome and hard to deal with, as I have written here before. But that is not a problem with UML per se, but with the fact most still see it as a graphical language.

UML certainly has its share of problems (design by committee, no reference implementation), but I strongly believe it is very useful and that there isn’t anything out there (I am talking to you, home grown DSLs) that can replace it as the lingua franca for model-driven development.

I decided to join a group of fellow mISVers in the 30-day product challenge. Differently from most of the other entries, which will go from product idea to release in 30 days, the TextUML Toolkit has been in development for quite a while now, so my challenge will be to finally ship the first release of the product.

The challenge starts on June 1st. Watch this space for frequent updates as I make progress towards the elusive version 1.0.

Rafael

Up until now, the TextUML Toolkit tutorial had been the only piece of documentation available on the TextUML notation. Well, not anymore. I just finished writing some reference documentation on the notation on the wiki. Since I was already at it, I also created a few topics on UML 101 with TextUML (also on the wiki), taking the text from some posts I have written on the topic.

Any issues or suggestions for the documentation are most welcome.

Rafael

M4 has been declared. If you got the M4 test build that was announced a week ago, no need to download again, it is the same build. Please see that post for a summary of the changes.

The TextUML tutorial has been updated in order to reflect the changes that happened during M4, the most remarkable one being that starting with M4 there are no built-in packages (such as ‘base’ and ‘base_profile’) any longer, other than those defined in UML2 itself. So if you were using elements defined in those built-in packages, you have now to define the elements yourself. The rationale is that the TextUML Toolkit should not be in the business of providing built-in packages nor rely on anything other than standard UML to do its work.

If you didn’t get the test build, go ahead and download M4. If you want to see a feature in the TextUML Toolkit, now it is the time to ask, as the next milestone will be feature freeze. And if you have tried the Toolkit and decided it is not for you, we would die to know why. Your feedback is greatly appreciated.

TextUML is a textual notation for UML. The TextUML Toolkit is an Eclipse-based IDE-like tool for creating UML models using the TextUML notation.

Other tools follow the same approach. Emfatic (now an EMFT subproject) has been doing the same for EMF Ecore for a long time; the TMF project aims to be for textual modeling what GMF is for graphical modeling, and will be based on GMT’s TCS and xText components.

Still, people are often puzzled when I explain what the TextUML Toolkit is. A common question is: “if I am going to write code (sic), why do I need UML anyway?“.

Dean Wampler from Object Mentor wrote on his blog a while ago a post entitled “Why we write code and don’t just draw diagrams“. It is a short post, but he presents very good points on why a graphical notation is usually not suficient and is bound to be less productive than a textual one when it comes to modeling details. For instance, on the saying “a picture is worth a thousand words“, Dean wrote:

“What that phrase really means is that we get the ‘gist’ or the ‘gestalt’ of a situation when we look at a picture, but nothing expresses the intricate details like text, the 1000 words. Since computers are literal-minded and don’t ‘do gist’, they require those details spelled out explicitly.”

Couldn’t have said it better.

I strongly advise you to read the original post in its entirety, but I will leave you with another pearl from Dean’s post (emphasis is mine):

“I came to this realization a few years ago when I worked for a Well Known Company developing UML-based tools for Java developers. The tool’s UI could have been more efficient, but there was no way to beat the speed of typing text.”

Enough said.

The first (and hopefully only) test build for M4 is now available. This is the first milestone where you can get the TextUML Toolkit via Update Manager. Just point Update Manager to:

http://abstratt.com/textuml/update/

Actually, if you are planning to use Acceleo or UML2Tools, it is the best approach. From an Eclipse SDK 3.3 install, point the Update Manager to the site above and install the TextUML Toolkit along with its prerequisites (EMF and UML2). Once you are done, you can install any compatible tools, such as Acceleo and/or UML2Tools (sites will be automatically configured after you install the Toolkit and its prerequisites). If you are not planning to use Acceleo, you can start from an Eclipse Platform install, or you can just download the TextUML Toolkit from the download page as usual.

Follows a summary of the changes that went into M4, including features (in bold) and bug fixes.

I will be writing on some of those features in following posts.

Rafael

The next VIJUG meeting will follow the Lightning Talks format. Last December, I attended the Eclipse Democamp in Vancouver which had a similar format and it was quite dynamic and fast-paced. I am looking forward to VIJUG’s first meeting using this exciting format.

I plan to do a demo on using Acceleo for generating code from UML models, of course, using the TextUML Toolkit for modeling, which is what the next milestone (M4) is all about.

I will be presenting the TextUML Toolkit at this month’s Vancouver Island Java User Group meeting. If you are in the Victoria area, I hope to see you there. It is free, and there will be pizza and drinks. Oh, and there will be a cool demo of the toolkit, including code generation using Acceleo and a quick demo on model execution just to give a hint of what comes next after the toolkit goes GA.

Many thanks to Manfred, the JUG leader, for organizing the meeting, and to Genologics for sponsoring it!

UPDATE: the meeting was great (slides here), got lots of interesting questions and comments, and many in the audience liked the idea of using a textual notation for UML. A bit harder to get buy-in for the idea of UML as programming language. I guess I will need to show something running to get that across too… ;) 

The latest milestone (M3) of the TextUML Toolkit has been declared today, as promised earlier here. As I said before, the focus for this milestone was stability and performance, so you can expect a much snappier and more solid tool. But it also includes some cool new features:

• you can drop UML2 models created elsewhere into a MDD project and you can use them from your TextUML code as you would with models created using the Toolkit
• you can even decompile a UML2 model and read it using the TextUML syntax with the TextUML Viewer (which takes over as the default editor for *.uml files)
• you can auto-format the current compilation unit with Ctrl-Shift-F
• and last but not least: Linux and Mac OS X (Power PC and Intel) are now supported

The main reason for this focus on performance and robustness is that the tool must be something that people can rely upon and become productive with. From now on, real user demand must drive the addition of any new features and bug fixing efforts. So now it is your turn. Download the TextUML Toolkit and start using it for creating your UML models. It is free! If you like the approach of modeling using a textual notation, I am sure you will enjoy it. And even if you haven’t bought the idea yet, give it a try. I would be more than glad of hearing your suggestions and opinions. And more importantly, will make sure that any problems reported will be promptly addressed.

Looking forward to your comments, either here or by e-mail on the Abstratt forum. Cheers.

Rafael

A TextUML Toolkit M3 test build is now available from the download page. If no serious issues are found in this build, it will be declared the final M3 build later this week.

The focus for this milestone was to improve the performance, memory footprint and stability of the tool, and very good progress was made in those areas. But there are also some brand new features, mostly in the area of integration with existing UML models. You can now safely add existing UML2 UML models (built elsewhere) to the project root and they will become available to the textual notation. Another cool feature in this area is that you can now double-click any existing UML2 UML model and read it using the textual notation (think “UML decompiler”). See below the sample model from Getting Started with UML2 in both textual and graphical notations:

Would you like to take a look? Grab the M3 test build, and give it a try. Please report here any problems and leave your comments. As usual, your feedback is really appreciated.

UPDATE: If the diagrams don’t show and everything else seems to work, you probably need the Visual C++ Redistributable package from Microsoft. This is a limitation that seemed to be recently introduced with the Graphviz support on Windows and the Graphviz team is looking into this issue. Sorry for the inconvenience.

Rafael

One common misconception is that UML is a graphical language and that any tools adopting alternative notations (such as a textual one) are inherently non-compliant. That can’t be farther from the truth. Read on to understand.

The fact is that the UML specification clearly separates abstract syntax (the kinds of elements and how they relate) and semantics (what they mean) from concrete syntax (what they look like), and states that there are two types of compliance:

• abstract syntax compliance
• concrete syntax compliance

Concrete syntax compliance means that users can continue to use a notation they are familiar with across different tools. This is important when UML is used as a communication tool in a team environment. Architects, designers, programmers and even many business analysts speak the same language.

Abstract syntax compliance means that users can move models across different tools, even if they use different notations. This is essential when UML is used as a basis for model-driven development. You might want to use tool A for creating the model, tool B for validating the model, tool C for somehow transforming/enhancing the model and tool D for generating code from it (a common form of MDD tool chain).

The TextUML Toolkit uses a textual notation that strictly exposes the UML semantics, but it is not compliant with the language concrete syntax by any means. On the other hand, the toolkit uses Eclipse UML2’s XMI flavor for persisting models and thus is fully compliant regarding the abstract syntax. That is consistent with the vision for the product: a tool from developers for developers that want to build software in a more sane way: the model-driven way. Developers can create models using a notation they are more productive with. Models can then be used as input for code generation using many of the tools available in the market. If non-developers might frown upon a textual modeling notation, they will always have the option of using their favorite graphical-notation based tools for reading the models. I mean, if their tool of choice is abstract syntax compliant as well.

I just added a brand new FAQ section to the web site. It was long overdue.

Here is the first batch of questions:

1. Can a tool that uses a textual notation be considered UML compliant?
2. What are the differences between TextUML and the real UML?
3. I thought UML was all about raising the level of abstraction. Why should I go back to coding?
4. How much does the TextUML Toolkit cost?
5. Is the TextUML Toolkit open source?
6. What diagrams can I create with the TextUML Toolkit?

Do you have any questions that are not answered in the FAQ or do not agree with or understand an answer? Fire your comments, I am always happy to hear from you.

Andreas Awenius, from Empowertec, was kind enough to devote not only one, but two blog postings on the TextUML Toolkit. While his first post was just a paragraph or two acknowledging the use of a textual notation for UML modeling in the TextUML Toolkit, his second post was a very detailed and balanced analysis on the whether using textual notations is a good idea. Even though the conclusion of his posting is that a graphical notation is superior to a textual one, I still agree with many points Andreas has made in his analysis:

1. the presentation notation and the persistence format are completely unrelated concerns (exactly, see my previous comment on this).
2. diagrams are views for models, focused on a specific aspect, and as such must show only what is needed and omit anything that is not essential. (perfect)
3. there are “multiple ways to manipulate the repository, e.g. the conventional - graphical - way or a textual notation”. (yes!)

These are the very same facts that justify the existence of a tool such as the TextUML Toolkit.

1. since user-oriented notation and persistence format are completely different things, you can please users with the most appropriate syntax for their needs (and that is text for many developers), without affecting interoperability with other tools, as tools interoperate at the level of the persistence format. The TextUML Toolkit achieves that by producing UML2 models as the native object file format.
2. the graphical notation is great for creating views, but it is not that suitable for exposing all the details in a model. A textual notation has no problem doing that. The graphical notation is still useful, and this is why TextUML Toolkit will include a read-only graphical view for browsing the repository. And here is the first point I disagree with Andreas. He says: “a diagram must carefully be crafted manually, leaving out all irrelevant detail”. I say: automatically generated diagrams can still obey a set of preferences defined by the user (level of detail, color, font, etc). UMLGraph has been doing this for a long time (albeit by breaking some basic rules of separation of concerns, but I digress). The TextUML Toolkit will embed an upcoming version of UMLGraph in its next milestone.
3. this is basically a conundrum of points #1 and #2. The model created will be the same (from the point of view of tools) regardless the user-facing notation. If users say they would rather use a textual notation, why forcing them to use a graphical one when there are no technical reasons to do so? Here is where Andreas makes several points to back his opinion based on technical and strategical reasons, most of which I (strongly to moderately) disagree. Instead of trying to refute each of those arguments (that is not how you encourage people to provide elaborate feedback), I will use them as an opportunity for driving awareness efforts around the Toolkit, the notation and our future offerings in upcoming posts to this blog.

The ‘raison d’être‘ for this blog is to establish connections with the modeling community at large, users and tool providers. I really appreciate the time and energy that Andreas committed to sharing his views on the TextUML Toolkit and the textual notation approach and am both grateful and honored for that. Thanks a lot, Andreas. Stay in touch. I hope at some point I can convince you that you are wrong!

Last Thursday happened the 1st Eclipse DemoCamp in Vancouver. It was a very dynamic event, with nine short talks packed into little more than one and a half hours. Attendance was high, I was really amazed to see such a great turnaround. The audience saw a diverse range of interesting Eclipse-based projects being developed in Vancouver/Victoria.

I demoed the TextUML Toolkit and got good feedback and some very interesting questions. The idea of a using a textual notation for creating UML models is still not a very easy sell, and that continues to surprise me. Being a developer, I find working with a textual notation so much more natural than a graphical one that it makes it hard for me to see things from other people’s shoes. I plan to go over the issue of textual versus graphical notations on a future post.

All in all, it was a great event. Many thanks to Tasktop’s Robert Elves and Mik Kersten for organizing it, to the Eclipse Foundation for sponsoring the event, and congrats to all presenters.

In a recent thread on the EMF newsgroup, I came to realize that there are (at least) two EMFs, each belonging to a different class of product, and attending completely distinct requirements.

EMF’s native metamodel, Ecore, is a generic, lean object-oriented metamodel based on a subset of UML.

EMF’s runtime framework provides Java applications with runtime support for object models “including change notification, persistence support with default XMI serialization, and a very efficient reflective API for manipulating EMF objects generically” (source).

I am a happy user of EMF’s Ecore metamodel as a poor man’s UML (EMF team, please take that as a compliment). From Ecore-based models, using a compatible template engine, I can generate all code/artifacts that are prone to automation, be they Java code or not.

The runtime aspect of EMF is certainly useful to many applications, but certainly not to all or maybe even most. That is not to say that the EMF runtime does not provide a lot of value, as it clearly does given its popularity. Nor does it imply that the EMF runtime API has design flaws that prevent its use to be more widespread. The fact is that frameworks, while designed for extension, always impose a certain set of architectural decisions in order to provide value out-of-the-box. Those decisions are bound to make its use more suitable to some scenarios and applications than others. The goal is to make as many people happy as possible. It is clear that the EMF team has pulled off that trick. But that does not mean that using EMF-generated model code is appropriate for every Java application out there.

Model driven development maximizes reuse via a complete separation between problem domain and technological concerns. This separation is critical to allow us to build software in an obsolescence-proof way. EMF’s Ecore provides a good foundation for MDD in this sense, regardless the technology choices for the software being developed. The EMF runtime framework, albeit a valuable tool for a significant range of applications, brings with it a specific set of choices in terms of design and implementation decisions, and as such has a less universal applicability.

However, time and again I read comments in the EMF newsgroup that lead me to believe that this duality might have been accidental, and that the sole reason Ecore was created was to support the generation of Java applications based on the EMF runtime. If that is really the case, this is something that both amuses and worries me. My concern is that if the EMF team does not acknowledge the importance of Ecore as an independently useful product, technical decisions in the evolution of EMF might break the use of Ecore in contexts other than EMF-based Java applications.

One weird thing about UML is that there aren’t collection types or array types. Basically, multiplicity and typing are totally independent concerns, represented by the metaclasses TypedElement and MultiplicityElement.

A typed element is a named element that has a type, and that is all about it. Examples of typed elements are value specifications, properties, parameters,