DSDP/MTJ/Preprocessing with Annocracy

Where can i download a Annocracy-Demo-Project

http://www.annocracy.four2b.de/GameOfLife.zip

Where can i download Annocracy

http://www.annocracy.four2b.de/update/

Additions-Plugins needed for the Demo-Project

In the GameOfLife Zip is a project and an additional Plugin (de.four2b.annocracy.mockDeviceDataSource_1.0.0.jar) that is not really useful for a real project, but is capable for the GameOfLife Example Project. Annocracy is extendable at several points, and this plugin is a simple DeviceInformation Datasource for Annocracy. The DeviceDataSources, BuildSystem etc. are not the Main-Parts of Annocracy. But we packed this example with a very simple Build-Cycle and DeviceData-Source, to show its functionality.

Installing Annocracy

We purpose to create a fresh Eclipse 3.2-Testing Installation and workspace for testing purpose and extract the GameOfLife-Zip and add the prepared project to this workspace. Please don't forgot to install the additional MockDeviceDataSource-Plugin into your plugin-directory.

Annocracy is an Eclipse Application so you can use it via RCP-Launch-Configuration. We prepared a small ANT-Task(not fully integrated all features yet). With this use can use Annocracy outside of Eclipse(just a RCP-Installation with the used plugins are needed). There is no UI-Plugins in Annocracy, but we want to integrate it into MTJ-Build-Process (posible there will be a need for using Wizards and Preference-Pages for Annocracy, but now let please discuss the preprocession terms in General).

In GameOfLife Project we tried to help setup your first Annocracy Build. Please read readme.txt and follow the instructions. Be carefull the temporary-workspace(WORK in build.xml and "Workspace Data" in RCP-Launch-Configuration) used by Annocracy will be deleted before processing.

Why Annotations

Using annotations for code fragmentation is quite different approach than some established solutions based on preprocessing with directives, e.g. J2ME Polish. This does not only mean that a developer has to change his way of programming. This also means that using annotations provides such capabilitys like syntax cheking or the ability to be processed by refactoring operations like any other Java element - "out of the box" and not only through extra tools.

Where can i place Annotations

The scope of annotations is not only a field or a method. They can be used along with much more elements:

• Type
• Field
• Method
• Constructor
• Parameter
• Local variable
• Pakage declaration
• Annotation

On the one hand it can be seen as not enough in a comparison to the omnipresence of Java comments wich are used to bring a preprocessing directive into the code. But on the other hand this omnipresence can be seen as reasonable limitations; why?

• Fragmenting the code should go along with taking the structure of this code into account. This strategy provides also a limitation of mistakes - like setting some //#endif on the wrong line or forgetting to set it at all.

Examples for using Annocracy

Removing a feature(e.g. playing a sound)

If you want to manage all occurencies of an element that should exist only in some case. According to a method this means to manage all its invocations by surrounding them with appropriate directives. In a complex structure this could easily be forgotten.If you use an Existence-Annotation in Annocracy, than the system takes care of all occurencies, invocations, etc. All you need is probably add a comment for yourself to see the dependency or use some visual decoration provided by a editor plugin(yet to come but not impemented at the moment)

Handle Complex Statements and Conditions

Who to handle Complex Statements like

   //#if polish.hasCommandKeyEvents || (polish.key.LeftSoftKey.defined &&  polish.key.RightSoftKey.defined)

in Annocracy

In the most annotations there is an element that is called "dependsOn". It's used to represent a case, e.g. that a device has some capability. In our small example application there are not many of such cases used, e.g. "midp1.0". This is not always, as it could seem to be, equivalent to some atomar case like polish.hasCommandKeyEvents. It is only a placeholder or a label for a rule which contains all the logic for a comparison of device properties with some values you expect. You could specify a rule that handles cases of any complexity - using the usual operators like AND, OR, NOT -, give it a name and reference it by this name in the annotations.

Where to Handles Complex Statements

Annocracy provides a way of this specification in an external file that easily can be modified or completed. I would say, it is even less verbose in an annotation, than in a comment based directive. Besides you have to specify such a rule - as it is called in the context of Annocracy - only once - in the mentioned file. If you prefer to use it other way, it's quite easy to provide an appropriate RuleValidator by yourself that can handle the same input like

   polish.hasCommandKeyEvents || (polish.key.LeftSoftKey.defined &&  polish.key.RightSoftKey.defined)

Handle Imports Switches

Concerning imports - you have no need to handle them in Annocracy in the way you would if you were using in e.g. J2ME Polish. Let us analyse what the cases are for handling imports.

Remove Import

The simple one can be that you are using some functionality in your application that should exist only in some special case. Importing the needed classes that comes along with it should also be handled in the same way. In J2ME Polish you can achieve this by surrounding such an import declaration with directives, as shown in the example provided by Richard:

   //#if polish.api.nokia-ui
      import com.nokia.mid.ui.*;
   //#endif

Annocracy handles such a case in a different way. The functionality is removed from code if the corresponding condition is not fulfiled - e.g. using @Existence. The import which of cource is not touched by any annotation and is not needed in the enclosing compilation unit will be removed by Annocracy at the end of the processing. It's just the same if you were using Eclipse as IDE and invoking "organize imports" action.

Change Import

The second case for handling imports could be that you have to "toggle" an import of a functionality that is provided by an advanced API but is not included in the old one, e.g. GameCanvas in MIDP-2.0. In such a case you would provide an own implementation - with the same name - and just want to "link" the import to yours one. In J2ME Polish this could by something like this:

   //#if polish.midp2
       import javax.microedition.lcdui.game.GameCanvas;
   //#else
       import my.own.GameCanvas;
   //#endif

In Annocracy you could use @Types instead to change the type of your element containing the declaration of your GameCanvas (because changing the type is what you want in such a case, isn't it?) :

   @Types(types = { @Type(dependsOn = "midp1.0" typeOwner = "canvasTypeOwner") })
   private javax.microedition.lcdui.game.GameCanvas canvas;
   
   @TypeOwner
   private my.own.GameCanvas canvasTypeOwner;

Other Annotations

Although this annotation was not used in our example application this does not mean that there is no such functionality provided by the annotations of Annocracy. Just look at the annotations in the package de.four2b.annocracy.annotations.core. By the way, you are not limited by using only this annotations. You can easily specify your own if there is a need. This comes along with providing of the appropriate processing component, but it's also nothing complex according to the simple API and using utilities included in Annocracy for such purposes.

Requirements

If you are working with annotations you need Java 5. You should have this installed on your computer if you want to use Annocracy. As mentioned in the readme file, that is shipped with our example application, you have to include the rt.jar from Java 5 JRE in the classpath of your project if you want to use all of the core annotations. It's also mentioned how you can limit the access to this JAR by adding some restrictions. This is e.g. one way if you do not want to have functionality from Java 5 in your project, besides the annotations.

GUI-Plugins

At the moment Annocracy dose not provide a GUI tool for assisting the developement process. It should be easier to implement than editorenhancements for comment-based preprocessor directives. This is because the editor plugin can use JDT-AST like Annocracy does.

---

Back to Device Fragmentation Solution