Archive

Archive for October, 2010

(e)Wiki – A model based Wiki framework

October 20, 2010 3 comments

1. What’s Wiki with a (e)?

(e)Wiki is a Wiki markup generation framework based on Mylyn WikiText and EMF. The framework allows to read and write different Wiki markup formats – this time, the model driven way. If you have an existing model based tool chain, the framework could easily fit in there to generate some quick documentation, without worrying about markups. You could reuse all the WikiText markup parsers and document builders, combined with the power of EMF features like EMF persistence, EMF notification etc.

The framework was developed as part of a customer project to generate Wiki documentation out of EMF based domain models. The framework is currently not open sourced and made available to public. Talks are on with the customer on this however.

The article gives an overview about the framework and its features. The intention of the article is also to demonstrate the extensibility of two powerful Eclipse frameworks – Mylyn WikiText and EMF.

2. Architecture

(e)Wiki is an addon to Mylyn WikiText. WikiText is a framework which supports parsing/editing Wiki markup formats like MediaWiki, Textile, Confluence, TracWiki and TWiki and writing them as HTML, Eclipse Help, DocBookDITA and XSL-FO. WikiText however doesn’t have an internal data model for documents (like DOM for XML). (e)Wiki adds this missing layer to the WikiText framework. Instead of using a POJO data model, (e)Wiki uses a powerful EMF based metamodel. Using (e)Wiki you could read all the above markup formats and generate a (e)WikiModel based on EMF. The model could then be written out using any of the WikiText document builders.

3. (e)WikiModel

(e)WikiModel is an EMF based Wiki metamodel. It is a generic metamodel for any Wiki Language.

(Only partial model is shown above)

(e)WikiModel is not aimed to be used as a DSL for your domain. It is intended to capture the documentation aspects of your domain model. To better describe semantic information use a DSL of your own using a framework like Xtext.

4. Features

(e)Wiki currently delivers the following:

  • A metamodel for Wiki called (e)WikiModel
  • (e)WikiEditor to view/edit (e)Wiki files
  • Previewing of rendered (e)Wiki content
  • UI extensions to convert existing markups to (e)WikiModel
  • Generating Textile and Redmine markup (together with HTML and Docbook as already supported by WikiText)
  • Feature to split generated Textile and Redmine markup files into subpages
  • Add Table of Contents to generated output

5. Working with (e)Wiki

5.1. Creating a (e)WikiModel

A (e)Wiki instance could be created either from Eclipse UI or programatically.

5.1.1. Creating from UI

Create a markup file within the eclipse workspace.

Right click the markup file and invoke eWiki -> Generate eWiki.

An (e)Wiki file is created in the same folder as selected file with extension .ewiki.

5.1.2. Creating with code

WikiText is based on “Builder” design pattern. (e)Wiki uses the same pattern and adds a new DocmentBuilder, the EWikiDocumentBuilder. The snippet below shows how to convert existing markup (Textile in this case) to (e)Wiki.


final String markup = "h1. Quisque"

final ResourceSet resourceSet = new ResourceSetImpl();
final Resource eWikiResource = resourceSet.createResource (URI.createFileURI("..."));

MarkupParser parser = new MarkupParser();
parser.setMarkupLanguage(new TextileLanguage());
EWikiDocumentBuilder eWikiDocumentBuilder = new EWikiDocumentBuilder(eWikiResource);
parser.setBuilder(eWikiDocumentBuilder);
parser.parse(markup);

eWikiResource.save(Collections.EMPTY_MAP);

The snippet below shows how to create a (e)WikiModel using model APIs. If you have worked with EMF generated model API code, this is no different, except that (e)Wiki adds additional convenient factory methods.

final ResourceSet resourceSet = new ResourceSetImpl();
final Resource eWikiResource = resourceSet.createResource (URI.createFileURI("..."));
Document document = EwikiFactory.eINSTANCE.createDocument();
document.setTitle("Lorem ipsum");

EwikiFactory.eINSTANCE.createHeading(document, 1, "Quisque");

Paragraph paragraph = EwikiFactory.eINSTANCE.createParagraph();
document.getSegments().add(paragraph);
EwikiFactory.eINSTANCE.createText(paragraph, "Lorem ipsum dolor sit amet, consectetur adipiscing elit.");

BullettedList bullettedList = EwikiFactory.eINSTANCE.createBullettedList();
document.getSegments().add(bullettedList);
EwikiFactory.eINSTANCE.createListItem(bullettedList,"Mauris");
EwikiFactory.eINSTANCE.createListItem(bullettedList,"Etiam");

eWikiResource.getContents().add(document);
eWikiResource.save(Collections.EMPTY_MAP);

5.2. (e)WikiEditor

The (e)WikiEditor provides a tree based editor and a preview tab.

5.2.1. Tree editor tab

The tree editor provides a tree view of the (e)Wiki file. Although the editor could be used to change the file, it is rare that rich text would be edited in this way.

5.2.2. Preview tab

The preview tab provides a preview of the (e)Wiki file as rendered by your default browser.

 

5.3. Generating output

The (e)Wiki file could be converted to HTML, Docbook, Textile and Redmine markup formats.

5.3.1. Generating output from UI

Right clicking the (e)Wiki file brings up the context menu for conversions.

5.3.2. Generating output from Code

You could use any of the existing DocumentBuilders in WikiText to generate output from a (e)WikiModel. The snippet below shows how to convert an (e)Wiki instance to HTML programatically using the WikiText HTMLDocumentBuilder.

final IFile eWikiFile = ...;
ResourceSet resourceSet = new ResourceSetImpl();
final Resource wikiResource = resourceSet.getResource(URI.createFileURI(eWikiFile.getRawLocation().toOSString()), true);
StringWriter writer = new StringWriter();

EWikiParser parser = new EWikiParser();
parser.setMarkupLanguage(new EWikiLanguage());
parser.setBuilder(new HTMLDocumentBuilder(writer));
parser.parse(wikiResource);

final String htmlContent = writer.toString();

Provisioning your Target Platform as local p2 site

October 9, 2010 12 comments

Provisioning your target platform from a p2/update site is a gem of a feature that was released with Eclipse 3.5. Chris called it “fantasy come true!” and so did many others. You could read the details on how this works from this article by Chris. (On the other hand, if you haven’t used target platforms at all, stop doing any further eclipse plugin development and read about it here first, right from the target platform expert Ekke).

Introduction

Provisioning your target platform from a p2 site allows you to basically download any eclipse flavor you like, and with the click of a button set up your target platform. PDE downloads all the plugins required for your target platform automatically from different software sites based on your target definition and builds your workspace. Although this is a great feature, using this in your workflow has some shortcomings.

  1. If your target platform is large (which is mostly the case), this would end up in a lot of bandwidth usage every time the bundles are downloaded from different software sites. Also, if you do not have high speed internet or you have restricted internet access, the time to initialize the target platform could be very long.
  2. Not all bundles are available from p2/update sites. Although p2 marketing has been quite successful recently, many plugin providers still doesn’t host their products as p2/update sites. Although, you could have such plugins as local folders or in a shared network folder, this takes away the power of provisioning.
  3. Many p2/update sites don’t believe in archiving older versions and continue providing them as p2/update sites. Hence you have no guarantee that your platforms based on some older bundles will work forever.
  4. Many development projects version their target platforms and maintains them in versioning systems like SVN. This is a prerequisite to reconstruct older target platforms. This, however, is not possible with the approach above.

If you have a closer look, you could see that many of the limitations above stems from the fact that the software sites referenced are not local, nor within your control. All of them could be avoided if you provision your target platform as a local p2/update site. This means, instead of you downloading bundles from a public software site, you (and your team) downloads them from a local p2/update site that you have set up with all your required target platform plugins/features. In this article, I describe a workflow in setting up such a local p2/update site for your target platform.

1. The aggregation task

The first step would be to aggregate all the plugins and features required by your target platform. You could easily do this by creating a target definition file which references the software site of your bundle providers using “New -> Target Definition“. If your bundle provider doesn’t have an p2/update site, reference them from a local download folder.

You will never share/distribute this “setup” target file

A sample target definition file could look like this.

If you want your target to support multiple platforms, make sure to check this checkbox while you add a software site.

2. Testing the target

Using the target definition editor, set the target by clicking “Set as Target Platform“.

Additionally, you could set the target platform in “Preferences -> Plug-in Development -> Target Platform” and selecting the newly created target. If all the projects in your workspace builds fine, then you have setup the target platform correctly. Else repeat Step 1 to add the missing plugins and the workspace errors vanish.

3. Creating a new target platform feature

Using the feature project wizard, create a new feature for the target platform.

Make sure to properly name and version the feature.

In the plugin selection page, the plugins listed are the ones in your target platform together with your workspace plugin projects. Select all plugins except the ones in your workspace.

4. Creating a p2 site for target platform

You could do this either using PDE or using Buckminster.

If you want your target platform to support multiple development platforms (OSX, Linux, Windows etc.) use Buckminster (unfortunately, PDE had some export issues doing this)

4.1. Creating p2 update site using PDE

Create a new update site project using the update site project wizard.

Create a proper category and add the target platform feature you created earlier as child, using “Add Feature…“.

Build the update site using “Build/Build All“.

If the build is successful, the update site project could look like this.

4.2 Creating p2 site using Buckminster

Install Buckminster from update site http://download.eclipse.org/tools/buckminster/updates-3.6 (for Helios).

Create a buckminster.properties file in your target platform feature project.

## buckminster.properties ##

#Where all the output should go

buckminster.output.root=${user.home}/project/site

# Where the temp files should go

buckminster.temp.root=${user.home}/project/tmp

# How .qualifier in versions should be replaced

qualifier.replacement.*=generator:lastRevision

target.os=*

target.ws=*

target.arch=*

Right click the target platform feature project and select “Buckminster -> Invoke Action…

Select buckminster.properties file created using “Workspace” button followed by “site.p2” from “Matching items” list

Select “OK” to close the dialog.

The p2 site would be created in feature folder pointed by buckminster.output.root in your buckminster.properties file.

You do not have to create a update site project (as you did in the PDE approach) while using Buckminster

5. Deploying the target platform

Identify a server space in your local network where the p2 site could be deployed (preferably a webserver). Copy the p2 site contents to this location.

6. Creating the final target definition

Create a new target file and point it to the newly hosted p2 site (similar to Step 1)

7. Testing the final target platform from local p2 site

Open the target file and set the target using “Set as Target Platform” as before. The bundles from the local p2 site will now be downloaded and your workspace built again. If you have zero errors, you have succeeded in setting up a p2 update site for your target platform. Distribute the final target file to your development team and they could now set their target platform in the same way.

8. Managing different versions of target platforms

You could provision multiple versions of target platforms at the same local p2 site. All you need to do is to create a new feature for the new target platform, add it to the update site site.xml, build and deploy the target platform as before and distribute the updated target file.

Follow

Get every new post delivered to your Inbox.