Getting Started
- Craig Gallen [Administrator] (Unlicensed)
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)
!EclipseSelectWorkspace.jpg!
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
!EclipseSettingM2_REPO.jpg!
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
!EclipseSelectJDK.jpg!
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
!EclipseViewRepository.jpg!
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.
!EclipseMultipleCheckOutAs.jpg!
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
.
!EclipseSingleCheckOutAs.jpg!
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 TIP 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.