JOSIF Main Page | Getting Started

Introduction

This page should provide enough information for a developer wishing to get started with the TIP program. Before checking out any projects, you should install the prerequisite packages and set up your environment as described in Setting Up Environment.

PLEASE NOTE The process of setting up an environment has been greatly simplified by the new TIP Workbench installer. Details of this can be found in the TIP Workbench Installation page.

Very useful additional information can also be found in the getting started presentations at Team Action Week Training Baltimore July 2010

Checking out a TIP project

Overview

All of the TIP projects on this site have broadly the same structure. These instructions explain how to check out the trunk version of the SPM (Service Problem Management) project but can easily be adapted to any of the other interface projects once you understand the process.

Note that the trunk version of any project is subject to continuous development and may not successfully build at any particular point of time. Interim releases are provided in the

tags

branch of the repository for each project. These are older versions but should build successfully. For more information on the use of tags and branches see Version Numbering.

These instructions assume that you have already set up your environment with Java, maven and Tigerstripe as described in Setting Up Environment

The interface projects all consist of a set of sub modules. For example the SPM project consists of a number of sub projects each of which is a maven module controlled from the TIP_SPM_BaseProject.

      TIP_SPM_BaseProject
      TIP_SPM_CTKProject
      TIP_SPM_Dependencies
      TIP_SPM_Model
      TIP_SPM_Model_Package
      TIP_SPM_DocSpecPackage
      TIP_SPM_EjbImplGenSrcPackage
      TIP_SPM_EjbImplProject
      TIP_SPM_JvtSpecPackage
      TIP_SPM_SoapSpecPackage
      TIP_SPM_SoapImplGenSrcPackage
      TIP_SPM_Spec_Release_Package
      TIP_SPM_WSImplPackage (TODO)

All of these projects should be individually checked out into an Eclipse workspace. Note that particularly in windows environments, it is important that the workspace be located as close to the root of the drive as possible and that the classpath to the workspace does not contain any spaces (i.e. near C:\ NOT your home directory). In the following example, a workspace will be created called

C:\ws-ts14

.

Starting Eclipse and checking out the modules

1. Start Eclipse by double clicking on

Eclipse.exe

2. Enter the name of the workspace into the startup dialogue. (If the workspace doesn't exist it will be created)

3. We need to set some workspace variables for a new workspace

a) To set the M2_REPO variable for the workspace

      Select window>preferences>java>Class path variables

      Select New and enter Name:M2_REPO

      Select Path> File and navigate to your .m2/repository

b) In the Setting Up Environment steps you should have installed a Java 6 JDK. To this Eclipse workspace use the Java 6 JDK instead of the default JRE, we need to do the following steps

      select window>preferences>java>Installed JRE's    

      Select Search>C:\Program files\Java to find the JDK's installed

      Click the box beside the JDK

4. On the header bar select

Window>Open Perspective>Other...

and select

SVN Repository Exploring

5. Right click on the SVN Repositories panel and select new>Repository Location. Enter the following URL;

https://openoss.svn.sourceforge.net/svnroot/openoss/tip/

6. You should be able to navigate to the projects you want to checkout. (For a full description of the repository structure see Project Structure). In our case we want to checkout the trunk version of the SPM project. Open the

interfaces>ServiceProblemManagement>trunk

folder as illustrated below

7 It is quicker to check out multiple projects at the same time. This can be done by pressing the

cntrl

key and selecting all the projects you want to checkout at once. Then right click on one of the selected projects and select

checkout...

The illustrated dialogue will open. Leave the settings to the defaults and click finish.

Alternatively projects can be checked out one at a time. To check out a single project, right click on the project and select checkout... The illustrated dialogue will open. Select

checkout as project in the workspace

and click

finish

.

The projects should now be checked out. However the Eclipse properties still need to be set before eclipse can be used. We will cover this in the next steps.

Building the modules and adding the Eclipse settings

1. Close Eclipse and navigate in a explorer window to the checked out TIP_SPM_Model project

2. Copy the file called

tigerstripe-build.properties-TEMPLATE

to a file called

tigerstripe-build.properties

in the same folder.

3. Edit

tigerstripe-build.properties

so that it points to the location of your workspace and to the home of your Eclipse with Tigerstripe installed. The example below expects the workspace to be in

C:\ws-ts14

and the Eclipse installation to be in a folder called

C:\eclipsets

. (Note the use of
escape characters)

# tigerstripe-build.properties
#
# copy this file to tigerstripe-build.properties and modify settings to suit your environment
# make sure that tigerstripe-build.properties is tagged svn:ignore. Only this file should be 
# copied to subversion.
#
# The values in this file must be set before a Maven run of Tigerstripe
# NOTE: for Windows installations you must escape backslash characters  i.e. \\ 

# Set to the location of eclipse with tigerstripe installed 
# Note for windows this must include escape characters e.g. eclipse.home=C:\\eclipsets
eclipse.home=C:\\eclipsets

# Set to the absolute location of THIS tigerstripe workspace with plugins installed
# Note for windows this must include escape characters e.g. tigerstripe.workspace=C:\\ws-ts6  
tigerstripe.workspace=C:\\ws-ts14

3. You also need to copy the tigerstripe-build.properties file you have just created to the checked out TIP_SPM_Dependencies project where it performs the same function as in the TIP_SPM_Model project

4. Navigate in a explorer window to the checked out TIP_SPM_BaseProject and Open a command window in this folder.

5. In the command window type

mvn -U eclipse:eclipse

This should begin to set the Eclipse properties for the project. It will download the dependencies and begin building the project. This might take some time. NOTE that the -U option ensures that the latest snapshot versions are checked (without the -U option, the SNAPSHOT repository is only checked once a day).

Note that if you do not have a tigerstripe profile and the appropriate tigertripe generators already installed in Eclipse, this step is expected to fail at some point, most likely with the message

[INFO] ------------------------------------------------------------------------
[ERROR] BUILD ERROR
[INFO] ------------------------------------------------------------------------
[INFO] Unable to find artifact.

It may also fail if you have an earlier version of profile or generators installed. The TIP Worlbench Installer has put the right generators the the correct profile already in the Tigerstripe environment, so ntohting should be needed at this step.
In case of problem, this step will have downloaded the correct profile and generators into the

TIP_SPM_Model/TigerstripeGenerators

folder for manual installation. The folder should now contain the following files (or later versions);

TIP_Doc_Generator-0.1.0_temp.zip
TIP_EjbImpl_Generator-0.3_temp.zip
TIP_JvtSpec_Generator-0.3_temp.zip
TIP_Soap_Generator-0.1.3_temp.zip
tip_profile.wbp

The zip files will be tigerstripe Generators - otherwise know as plugins
The tip_profile.wbp file is a tigertripe profile

6. Restart Eclipse and refresh all the projects in the workspace (i.e select all the projects, right click on one of them and choose

refresh

)

7. This step is no longer needed with JOSIF rel 1.1 as the correct generators are now installed by the installer.This rest of this step can be skipped.
In the Eclipse Header Bar select

Tigerstripe>Plugins

to open the

Deployed Tigerstripe Plugins

dialogue. Right Click in this dialogue and select

Deploy

. Navigate to the

TIP_SPM_Model/TigerstripeGenerators

folder and select one of the Generators to deploy. Repeat this step for all of the generators.

8. This step is no longer needed with JOSIF rel 1.1 as the correct generators are now installed by the installer.This rest of this step can be skipped.
double click on the tip_profile.wbp file to open it and select the link

Save as active profile and reload

. This will load the profile into tigerstripe.

With the correct profile loaded and the generators installed, any errors present in src folder of the TIP_SPM_Model project should disappear.

IMPORTANT - the system will have downloaded the latest profile and generators based upon the settings in the BaseProject pom.xml. If the project is calling for SNAPSHOT versions, the version numbers of these files do not normally change from SNAPSHOT version to version as this upsets the tigerstripe configuration in all the projects. So, even if you think tigerstripe has the correct plugins and profile installed, it is usually safer to un-deploy the previous plugins and profiles and re-deploy the latest downloaded ones.

9. Close Eclipse and navigate in an explorer window to the checked out TIP_SPM_BaseProject and Open a command window in this folder. In the command window type

mvn clean install

The project should now build correctly with a final message similar to the following;

[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO] ------------------------------------------------------------------------
[INFO] TIP_SPM_BaseProject ................................... SUCCESS [3.588s]
[INFO] TIP_SPM_Model ......................................... SUCCESS [21.965s]
[INFO] TIP_SPM_SoapSpecPackage ............................... SUCCESS [18.392s]
[INFO] TIP_SPM_DocSpecPackage ................................ SUCCESS [1.124s]
[INFO] TIP_SPM_JvtSpecPackage ................................ SUCCESS [17.706s]
[INFO] TIP_SPM_EjbImplGenSrcPackage .......................... SUCCESS [59.295s]
[INFO] ------------------------------------------------------------------------
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 2 minutes 3 seconds
[INFO] Finished at: Fri Aug 14 14:28:03 BST 2009
[INFO] Final Memory: 58M/104M
[INFO] ------------------------------------------------------------------------

10. To ensure that Eclipse is now referencing the modules in the project properly. Do the following commands in the TIP_SPM_BaseProject;

mvn eclipse:clean   - to clear out previous configurations
mvn eclipse:eclipse - to correctly set the eclipse .project .settings and .classpath for each project

11. Restart eclipse and refresh all the projects in the workspace
You should now have a working project which eclipse can edit and see all the dependencies on it's classpath. If you change the model, you should rebuild the project by running

mvn clean install

to re-check that the model is compiled correctly

12. (Optional)To ensure model is valid and respects best practices, you are encouraged to validate the model with TIP_Model_Validator

Check svn:ignore settings

The project should have been checked into subversion with the correct svn:ignore settings which will be respected by your workspace. However you should check that the following files are NEVER checked into the subversion repository as they are specific to your local environment and are generated by the maven build.

.properties
.classpath
.project
.log*
tigerstripe-build.properties
bin folders
classes folders
target folders

Creating a new TIP Project

The above steps have described how to check out and build an existing project using Eclipse and Tigerstripe. The TIP_Project_Creator creates a new project from scratch. Having created a project, the above steps should be performed to make it work with Eclipse. For more information on the TIP_Project_Creator see  JOSIF Project Creator

Importing model to TIP Project

The result of the previous step includes 2 empty Tigerstripe model projects: interface model and its dependency model. You need to import ABEs and their dependencies from a SID branch into the 2 projects. The TIP SID Import Plug-ins help here. For more information on the plug-ins please see TIP SID Import.

Enriching the model

Now you are ready to edit and enrich the model. Please refer to JOSIF_Guidebook.

Generating the interfaces

To generate interfaces from the model , you use JOSIF generators. The supported interface styles include Web Services, EJB, and Java. JOSIF provide a documentation generator which produce Information Agreeemnt (IA) from the model.

Please refer to JOSIF_Guidebook, in particularly, the section Interface_Tooling.