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.
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.
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:
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 perspective
Choose SVN repository
Checkout 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.
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
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:
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 )
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.
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 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:
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.
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 in Vine consists of several components:
Example.java
)
ExampleModel.java
)
Example.mxml
)
Example.as
)
ExampleModel.as
)
locale
directory )
Example 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.
Here we present a couple of debugging methods in various IDEs.
In this case we connect to the local Tomcat instance and try to debug Vine using Intellij Idea.
Preparing environment and IDE configuration.
.bash_profile
) please add the following variables:
export JPDA_ADDRESS=1044
export JPDA_TRANSPORT=dt_socket
Run->Edit Configurations
menu.
Intellij Idea + Tomcat + Gridsphere application server location
JPDA_ADDRESS
) which in our case is 1044
:
Debug phase.