UNICORE Life Wiki

Brought to you by: bjoernh, bschuller, golbi, piotrbala, rkluszczynski

U7PortalModuleTutorial

Tutorial: How to create an interface for UNICORE 7 Portal

This tutorial will help You to get started with UNICORE portal modules development. It is possible to create simple Maven module project which will create standalone archive (JAR file) with extensions of standard portal views.

You can find some projects which are being developed in PL-Grid infrastructure at:
http://sourceforge.net/p/unicore-life/code/HEAD/tree/plg-utils/plg-unicore-portal-modules/

Prerequisites (versions used in tutorial, older also may be valid):
- Java Development Kit >= 1.7.0_u45,
- Maven >= 3.1.1,
- Subversion,
- Internet access ;)

Quick start how to add additional UNICORE portal module

To make it really happen, You need to go through following steps:

Create implementation of Your own extension module,
Build Your module against portal libraries with the same version as a portal where You want to deploy Your extension UI,
Send plugin to UNICORE portal administrator who should add JAR archive to server's lib/ subdirectory and restart the server,
Log in and choose Your View through portal menu (at position where You have specified in implementation).

In this tutorial, there will be used portal template module prepared by PL-Grid developers.

Quick start with template portal module

Create a directory for Your first build of UNICORE portal plugin and enter to it:

klusi@ubuntu-VirtualBox:~$ mkdir u7portal

klusi@ubuntu-VirtualBox:~$ cd u7portal/

Check out template portal module from unicore-life repository:

klusi@ubuntu-VirtualBox:~/u7portal$ svn co https://svn.code.sf.net/p/unicore-life/code/plg-utils/plg-unicore-portal-modules/pl.unicore.portal.template/trunk pl.unicore.portal.template

(...)
Checked out revision 2675.

Enter to directory:

klusi@ubuntu-VirtualBox:~/u7portal$ cd pl.unicore.portal.template/

Run Maven to build and install the plugin:

klusi@ubuntu-VirtualBox:~/u7portal/pl.unicore.portal.template$ mvn install

(...)

[INFO] Installing /home/klusi/u7portal/pl.unicore.portal.template/target/pl.unicore.portal.template-1.0.0-SNAPSHOT.jar to /home/klusi/.m2/repository/pl/unicore/portal/pl.unicore.portal.template/1.0.0-SNAPSHOT/pl.unicore.portal.template-1.0.0-SNAPSHOT.jar
[INFO] Installing /home/klusi/u7portal/pl.unicore.portal.template/pom.xml to /home/klusi/.m2/repository/pl/unicore/portal/pl.unicore.portal.template/1.0.0-SNAPSHOT/pl.unicore.portal.template-1.0.0-SNAPSHOT.pom
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 7.087s
[INFO] Finished at: Sun Nov 17 13:57:52 CET 2013
[INFO] Final Memory: 22M/155M
[INFO] ------------------------------------------------------------------------

If you can see BUILD SUCCESS string it means, that all needed packages were in remote or Your local Maven repository. This is expected behavior. This means that You have build Your first portal module.

CONGRATULATIONS !!!

Unfortunately, in real life (even unicore-life) usually there are problems. One of the failures may be missing dependencies in Maven repositories. This can be noticed when error messages contains string "Could not resolve dependencies". Below, there is an example of failed build with such error message.

(...)

[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 4.752s
[INFO] Finished at: Sun Nov 17 11:51:45 CET 2013
[INFO] Final Memory: 7M/68M
[INFO] ------------------------------------------------------------------------
[ERROR] Failed to execute goal on project pl.unicore.portal.template: Could not resolve dependencies for project pl.unicore.portal:pl.unicore.portal.template:jar:1.0.0-SNAPSHOT: Could not find artifact eu.unicore.portal:eu.unicore.portal.ui:jar:1.0.0-SNAPSHOT in unicore.eu (http://unicore-dev.zam.kfa-juelich.de/maven) -> [Help 1]
[ERROR]
[ERROR] To see the full stack trace of the errors, re-run Maven with the -e switch.
[ERROR] Re-run Maven using the -X switch to enable full debug logging.
[ERROR]
[ERROR] For more information about the errors and possible solutions, please read the following articles:
[ERROR] [Help 1] http://cwiki.apache.org/confluence/display/MAVEN/DependencyResolutionException

If You have such a message, the quickest fix will be to use latest tagged version of UNICORE portal sources in order to build and install packages in Your local repository. So, let's get it on.

Fixing missing portal packages in Maven repositories

Get back to Your sandbox directory:

klusi@ubuntu-VirtualBox:~/u7portal$ cd ..

Checkout from repository latest tag of unicore-portal (You can find it here: https://sourceforge.net/p/unicore/svn/HEAD/tree/unicore-portal/tags/). In our case this is beta. We will save this to subdirectory with such name:

klusi@ubuntu-VirtualBox:~/u7portal$ svn co http://svn.code.sf.net/p/unicore/svn/unicore-portal/branches/release-1.0.0/ release-1.0.0

Now, enter the directory and build packages. I advice to skip tests. Although, they should work correctly in tagged sources, this is not always the case. So please enter commands:

klusi@ubuntu-VirtualBox:~/u7portal$ cd release-1.0.0/

klusi@ubuntu-VirtualBox:~/u7portal/release-1.0.0$ mvn -DskipTests install

This should go smoothly and can take couple minutes depends on Your bandwidth. If You have any problems here, please contact the author of this post. Next, I'm assuming that build was correct. So, get back to Your portal module template:

klusi@ubuntu-VirtualBox:~/u7portal/release-1.0.0$ cd ../pl.unicore.portal.template/

Build of portal modules run before has added needed JARs to Your local Maven repository. Unfortunately, this was probably made with different version id, so before starting the build You should update the pom.xml file by changing all -SNAPSHOT suffixes to -beta:

klusi@ubuntu-VirtualBox:~/u7portal/pl.unicore.portal.template$ sed -i -e 's/1.0.0-SNAPSHOT/1.0.0-beta/g' pom.xml

Next, You're ready to run Maven again. Please, add clean target:

klusi@ubuntu-VirtualBox:~/u7portal/pl.unicore.portal.template$ mvn clean install

The only difference is that this time template module will be packed to file named: pl.unicore.portal.template-1.0.0-beta.jar.

NOTE: please, do not commit any changes of pom.xml file.

What's inside of template portal module

Template portal module contains files:

pl.unicore.portal.template/src/main/java/pl/edu/icm/grid/unicore/template/TemplatePortalView.java
pl.unicore.portal.template/src/main/java/pl/edu/icm/grid/unicore/template/i18n/TemplateViewI18N.java
pl.unicore.portal.template/src/main/resources/META-INF/portalPlugin.xml
pl.unicore.portal.template/src/main/resources/pl/edu/icm/grid/unicore/template/i18n/TemplateMessages_pl.properties
pl.unicore.portal.template/src/main/resources/pl/edu/icm/grid/unicore/template/i18n/TemplateMessages.properties
pl.unicore.portal.template/pom.xml

The last one (pom.xml) contains dependencies and repositories needed to build JAR with template portal module. Now, let's explain a bit the rest one by one.

TemplatePortalView.java

All You have to know at the moment that this Java class contains main panel of a view in UNICORE portal. It should always extends eu.unicore.portal.ui.views.AbstractView class.

TemplateViewI18N.java

This class is needed for internalization. It contains ID used in UI classes.

portalPlugin.xml

This is the most important file if You want to integrate Your plugin with portal. Every JAR file is scanned by the portal server if it contains this XML. If yes, all additional extensions are taken into account during portal startup. Here, You can define few things like:
- where to find new entry for portal menu ("/plugin/extensions/menuExtension/category" tag),
- which class is a main panel ("/plugin/extensions/menuExtension/commandDescriptor/parameter/value" tag),
- full path to class containing ID of messages ("/plugin/extensions/MessageSourceExtension/location" tag).

TemplateMessages.properties

File containing pairs (key,value) with messages in English language.

TemplateMessages_pl.properties

File with messages in Polish language.