Vine Developer's Guide

Welcome to the Vine Toolkit Dev Guide! The Dev Guide is a practical introduction to developing applications with Vine. It explores the concepts behind Vine, the framework for constructing an application, and the best practices for integrating applications with underlying services.

Getting Started

Environment configuration

Packaging rules

Vine Toolkit is package sensitive framework, its package structure informs Vine how to deploy the variety of sources. Currently we provide two main branches of sources:

{project_name}/main
{project_name}/web

and one sub-branch for web ui:

{project_name}/web/ui

When deploying web application, we need to place jars in a specific locations which are ( Apache Tomcat example ):

{CATALINA_HOME}/shared/lib
{CATALINA_HOME}/vine/WEB-INF/lib

Additionally, to prevent jar conflicts Vine extends that functionality and adds the following locations:

{CATALINA_HOME}/vine/WEB-INF/vine/lib
{CATALINA_HOME}/vine/WEB-INF/vine/project/{PROJECT_NAME}/lib

By using custom class loaders enable us to have and use multiple set of jars ( i.e. Globus jars ) in a one webapp. The obvious drawback is that classes loaded by vine class loaders are not accessible from the external contexts.

Flex components jars with BlazeDs support need to be placed in {CATALINA_HOME}/vine/WEB-INF/lib directory, in order to do that you should use one of the following package patterns ( taken from our build script ):

**/flex/app/**, **/web/portlet/app/**, **/web/servlet/app/**, **/web/app/**, **/flex/blazeds/webapp/**')

Notice that creating new project with Vine Configurator gives you a proper package structure.

Vine Toolkit + Eclipse

In this section we describe how to set up dev environment based on the Eclipse IDE.

Getting sources

As the first step we encourage creating the following directory structure:

vine-1.3/
|-- liferay-portal-5.2.3
|-- portal -> /Users/gosiaw/vine-1.3/liferay-portal-5.2.3/tomcat-5.5.27/
`-- vine

The contents of that directory include:

  • liferay-portal-5.2.3 directory with Liferay
  • liferay-portal-5.2.3/Tomcat 5.5.27 directory with a symbolic link ( portal )
  • vine directory with the latest sources of Vine Toolkit from the SVN

To check out the Vine Toolkit from the SVN please use the following command:

svn co https://gforge.man.poznan.pl/svn/vine/vine/trunk vine

Or use Eclipse with Subclipse plugin installed.

SVN Repository perspectiveSVN Repository perspective
Choose SVN repositoryChoose SVN repository
Checkout from SVNCheckout from SVN

After checkout operation, Vine directory contains basic codes of Vine Toolkit. It is not necessary to download all components of Vine Toolkit. It is much better to choose appropriate installer and download components used by this installer only.
In the picture below we can see the list of Vine Toolkit installers.

List of installersList of installers

It is much easier to download components using terminal window.

magnolia-small:Vine gosiaw$ ant fetch

After running this command it is necessary to choose appropriate installer and decide if it should become the default one.

magnolia-small:vine gosiaw$ ant fetch
Buildfile: build.xml

fetch:

-------------------------------------------------------------
-- Available Installers
-------------------------------------------------------------
[1] BEinGRID Demonstration for Tomcat 5.X and GridSphere 3.1
[2] BlazeDs example installer for Gridsphere 3.1
[3] BlazeDs example installer for Liferay 5.x
[4] Flowify Portal
[5] Flowify Portal - installation without Gria
[6] Flowify services
[7] HPCEuropa2
[8] Job Manager Test
[9] OMII-Europe Demonstration for Tomcat 5.X and GridSphere 3.1
[10] PLGRIDSRV (servlet mode)
[11] PLGrid with GridSphere
[12] PLGrid with Liferay
[13] Vine for Tomcat 5.X, GridSphere 3.1 and Globus Toolkit 4
[14] Vine for Tomcat 5.X, GridSphere 3.1 and UNICORE 6
[15] Vine for Tomcat 5.X, GridSphere 3.1 and gLite 3
[16] WOW2GREENSRV
[17] Wow2Green portal installer
[18] nano abinit project deployed to Liferay
[input] Enter the number of the installer you want to use, i.e. "1"
12

[input] Would you like this installer to be the default installer? ([y], n)
y

And then execute install command.

magnolia-small:Vine gosiaw$ ant install

Vine Toolkit + IntelliJ IDEA

In this section we describe how to set up dev environment based on the IntelliJ Idea IDE.

Getting sources

As the first step we encourage creating the following directory structure:

vine-1.3/
|-- apache-tomcat-5.5.26
|-- gridsphere-3.1
|-- portal -> /Volumes/Extended/work/projects/vine-1.3/apache-tomcat-5.5.26
`-- vine

The contents of that directory include:

  • Tomcat 5.5.26 directory with a symbolic link ( portal )
  • Gridsphere 3.1 directory with a stable release of Gridsphere
  • vine directory with a latest sources of Vine Toolkit from the SVN

To check out the Vine from the SVN please use the following command:

svn co https://gforge.man.poznan.pl/svn/vine/vine/trunk vine

The next step involves fetching all projects required by you. If you need just the projects from the installer you are using, please do:

ant fetch

If you want to have all projects to work with, do:

ant fetch-all

You will be prompted to choose the installer you want to use and make it a default one ( say yes ).

As a result of the previous step the content of your projects directory shall look similar to that listing:

projects/
|-- activedirectory
|-- bes
|-- besgt4
|-- glite3
|-- gria
|-- grid
|-- grms
|-- gt2
|-- gt4
|-- kepler
|-- opendsp
|-- srb
|-- srm
|-- uitutorials
|-- unicore6
|-- voms
|-- webdav
`-- workflow

Creating project in the IntelliJ IDEA ( based on the v. 9.0.2 )

  • Choose 'New Project' from the menu.
  • Proceed as follows:

    IntelliJ Idea: New Project typeIntelliJ Idea: New Project type
     

  • Set up project properties as on the following picture:

    IntelliJ Idea: New Project propertiesIntelliJ Idea: New Project properties
     

  • Mark all java sources found by the Idea:

    IntelliJ Idea: New Project java sourcesIntelliJ Idea: New Project java sources
     

  • Mark all libraries found by the Idea:

    IntelliJ Idea: New Project java libsIntelliJ Idea: New Project java libs
     

  • Merge all to one 'libs' library - it will be easier to manage it:

    IntelliJ Idea: New Project java libs mergeIntelliJ Idea: New Project java libs merge
     

  • Mark all modules found by the Idea:

    IntelliJ Idea: New Project modulesIntelliJ Idea: New Project modules
     

  • Merge all to one 'vine' module:

    IntelliJ Idea: New Project modules mergeIntelliJ Idea: New Project modules merge
     

  • On the next screen deselect any facelets found by Idea and click 'Finish'.
     
  • You should end up with the view similar to the picture below. As you can see, Idea created several context roots for the sources.

    IntelliJ Idea: Vine project with many context roots.IntelliJ Idea: Vine project with many context roots.
     

  • To change that into more user friendly form ( one context root ), go to the 'Module settings':

    IntelliJ Idea: Vine module settingsIntelliJ Idea: Vine module settings
     

  • Delete the vine module and add new module as follows:

    IntelliJ Idea: New moduleIntelliJ Idea: New module
     

  • Again, mark all java sources found by Idea:

    IntelliJ Idea: New Module java sourcesIntelliJ Idea: New Module java sources
     

  • New module has been added, it should look like the following picture:

    IntelliJ Idea: New module - one context rootIntelliJ Idea: New module - one context root
     

  • Add library dependency to the new module:

    IntelliJ Idea: New module library dependencyIntelliJ Idea: New module library dependency
     

  • Accept all changes and your project should look similar to the following picture:

    IntelliJ Idea: Vine project with one context rootIntelliJ Idea: Vine project with one context root
     

Managing projects

Vine bases on its modular structure. It consists of core project - a set of main interfaces and their implementation stored in sub projects. Typically, when developer wants to extends Vine's functionality he does that by adding a new project. This can be achieved in a old fashion way by creating relevant directory structure, but in order to avoid possible errors we can use Vine configure utility.

Creating new project

There are two ways to create new projects in vine. The simple command line one and the second by using our gui tool which let you to customize your new project more.

Command line ant task:

In the Vine directory type:

1. ant new-project -Dname=projects_name

2. Depending on your project's name you should see it in {vine_home}/projects/{projects_name} directory. Notice that configuration for your project is saved in {project_name}/ant/project.properties file.

GUI tool:

1. In Vine directory type:

ant gui

2. Change tab to 'Projects'
Configurator - projects tabConfigurator - projects tab
3. Fill all relevant fields on the left side according your needs. If you want to create only new UI components it's enough to select only Flex support.

4. If you want to use some of Vine subprojects:

  • in the compile time ( i.e. to import custom Vine flex components paths during flex component compilation ) use 'Projects uses' list,
  • in the run time ( to use subprojects libraries ) use 'Project extends' list.

5. Click 'Save changes' to create new project or 'New project' to reset all options to their default values.

6. Depending on your project's name you should see it in {vine_home}/projects/{projects_name} directory. Notice that configuration for your project is saved in {project_name}/ant/project.properties file.

Developing Flex components

All components in Vine are based on Adobe Flex technology. In the past we evaluated other solutions starting from pure jsp pages, tapestry and jsf frameworks, looking at some new and nifty looking ones ( Echo 2 ) and ending up with our own UI framework - Sportlets. What we learned is that with the old fashion HTML and Java Script approach it's very hard to manage crossbrowser compatibility issues and it's almost impossible to create and maintain a product which could be deployed into other heavily featured (ui-wise) environments ( eg. Liferay ).

Currently Flex 4 is used as primary UI platform for the Vine Toolkit. It has been adopted along with the open source data services - BlazeDs. In this section we will describe several scenarios of creating Flex components with the custom add ons provided by the Vine Toolkit.

Flex application model in a nutshell

Flex application in Vine consists of several components:

  • server side
    • backend service ( Example.java )
    • backend model ( ExampleModel.java )
  • client side
    • gui component ( Example.mxml )
    • action script source for component ( Example.as )
    • model action script class ( ExampleModel.as )
  • locale ( located in the locale directory )

Example project - structure diagram: MVC layers in the context of client-server architectureExample project - structure diagram: MVC layers in the context of client-server architecture
These elements maps into the MVC structure which lets you to create multiple presentation instances or reuse business logic in other applications.

In the packaging rules section we described how the initial sources are deployed as a portlet application, here we present communication flow between particular components.

Model is the glue between client and server side. It contains the state of component. Thereby it's vital to get now its lifecycle. Default scope for Flex/BlazeDs component is the application scope. That means that data will get persisted over user sessions. In order to put some more control over that process we designed a ModelInitialization interface which is responsible for managing the initialization phase of component.

View is our Flex application in a form of several mxml/as files.

Controller is our business logic located in java classes, it's also possible to shift some actions strictly to the client side.

Locale in a form of resource bundles are used both by the client and server side code.

Developing services

Debugging Vine

Here we present a couple of debugging methods in various IDEs.

Intellij Idea + Tomcat + Gridsphere

In this case we connect to the local Tomcat instance and try to debug Vine using Intellij Idea.

Preparing environment and IDE configuration.

  1. In your environment (i.e. .bash_profile) please add the following variables:

    export JPDA_ADDRESS=1044
    export JPDA_TRANSPORT=dt_socket
     
  2. In the IDE go to the Run->Edit Configurations menu.
  3. Go to the 'Add New Configuration' and choose Tomcat Server->Local

    Intellij Idea + Tomcat + Gridsphere debugIntellij Idea + Tomcat + Gridsphere debug

  4. Configure new Application Server for our debug task:

    Intellij Idea + Tomcat + Gridsphere application serverIntellij Idea + Tomcat + Gridsphere application server

  5. Click Add and select your $CATALINA_HOME location:

    Intellij Idea + Tomcat + Gridsphere application server locationIntellij Idea + Tomcat + Gridsphere application server location

  6. Idea will add all jars from Tomcat like:

    Intellij Idea + Tomcat + Gridsphere application server jarsIntellij Idea + Tomcat + Gridsphere application server jars

  7. Then you need to setup your port number to the value set in the env variable ( JPDA_ADDRESS ) which in our case is 1044:

    Intellij Idea + Tomcat + Gridsphere startup connectionIntellij Idea + Tomcat + Gridsphere startup connection

 
 
Debug phase.

  1. Search for the VineLoginCom clas and set a break point as in the following picture:

    Intellij Idea + Tomcat + Gridsphere breakpoint setIntellij Idea + Tomcat + Gridsphere breakpoint set

  2. Go to the Run->Debug menu option, Tomcat should start and the new window at the bottom should appear:

    Intellij Idea + Tomcat + Gridsphere logs viewIntellij Idea + Tomcat + Gridsphere logs view

  3. Go to your browser type: "http://localhost:8080/gridsphere", setup new user and try to log in to the portal. Portal should freeze. Go to the Intellij Idea to see that debug mode is on and working:

    Intellij Idea + Tomcat + Gridsphere debug snapshotIntellij Idea + Tomcat + Gridsphere debug snapshot