Developer Bootstrap

UI Development

1. Install Eclipse Helios (v3.6)
2. Install Google Web Toolkit, Google App Engine SDK, and Google plug-in for Eclipse using Eclipse new software from Google's update site - http://dl.google.com/eclipse/plugin/3.6.  Note if you were using an older version of this plugin you will need to uninstall it and then re-install it to ensure it has GWT 2.4.0 support.
3. Install the Maven2Eclipse plugin: http://www.eclipse.org/m2e/download/
4. Install the EGit eclipse plugin: http://www.eclipse.org/egit/download/
5. Create a GitHub user account
   
   1. Internal Sage developers will be added as a developer on the project and will be able to push directly
   2. External contributors should fork the repository and submit GitHub Pull Requests for code inclusion
6. Clone the SynapseWebClient project down to your computer: git clone https://<YOUR GITHUB USERNAME>@github.com/Sage-Bionetworks/Synapse-Repository-Services.git
   
   1. e.x. READ-ONLY: git clone https://git@github.com/Sage-Bionetworks/SynapseWebClient.git
7. Import the project as a maven project
   
   1. File -> Import -> Maven -> Existing Maven Projects
   2. Next, in Root Directory enter the local path to your repository clone
   3. Next, Finish 
8. Enable Git Team tracking
   
   1. Now right click on portal (project name) -> Team -> Share Project
   2. Next, Select repository type Git
   3. Next, Check the box "Use or create repository in parent folder of project
   4. Next, Finish 
9. You need to make sure the GWT xml files are on the classpath. All of these resources can be found in src/main/resources directory.  You will probably need to remove the "Exclude **" filter on that folder in your build configuration dialog (Right-click->Build Path>Configure Build Path... and remove the exclude from the source tab on the resources directory.
10. We need to tell the GWT Eclipse-plugin that this is a GWT project. Do this by Right-Clicking on the project in the package explorer and select: Google->Web Toolkit Settings...
    
    1. From the resulting dialog make sure the "Use Google Web Tookit" check box is selected.
    2. Also make sure you are using GWT 2.4.0.
11. We need to tell the Google plugin where our web app directory can be found.  Right-click on the project in the package explorer and select Properties.
    
    1.  From the tree on the left of the dialog navigate to Google->Web Application
    2. Check the the check box: "This project has a WAR directory"
    3. With the "Browse" button, select "src/main/webapp"
    4. UN-CHECK the "Launch and deploy from this directory"  This is very important, if you keep this checked then Maven will not be able to generate a clean WAR file.  If you see "GWT needs to recompile" when you deploy your WAR then you probably have this box checked.
12. Now that the Portal.gwt.xml file is on the classpath, make sure GWT knows it is the entry point.
    
    1. Right-Click on the project from the package explorer.
    2. Select Google->Web Toolkit Settings...
    3. Under the "entry point modules" you should see "Portal - org.sagebionetworks.web",  if not, then add it with the add button.
13. Now make sure GWT can compile your code
    
    1. Right-Click on the project in the package explorer
    2. Google->GWT Compile
    3. The first time you run this you will be asked to select the output directory where GWT will compile the code. You want this to match the Maven WAR output directory, so use "target/portal-<VERSION>-SNAPSHOT"
14. Our web.xml is setup to redirect all traffic to HTTPS for security reasons. While GWT + Eclipse's development plugin is supposed to support this by ignoring the security-constraint, in my experience it does not ignore the constraint and instead gives a 403 error when you try running in development mode from Eclipse. For development only purposes, you should comment out the secutiy-constraint in the web.xml. Do not check this change in. 
    

    1. <!-- Comment the below security constraint out if you are working in GWT development mode -->
       <!-- 	<security-constraint>
       		<web-resource-collection>
       			<web-resource-name>Protected Context</web-resource-name>
       			<url-pattern>/*</url-pattern>
       		</web-resource-collection>
       		<user-data-constraint>
       			<transport-guarantee>CONFIDENTIAL</transport-guarantee>
       		</user-data-constraint>
       	</security-constraint>
        -->

15. You are finally ready to run the application in development mode.
    
    1. Right-Click on the project in the package explorer
    2. Select: Run As->Web Application
    3. Double-click on the link provided in the Development Mode window to view the portal in your browser.  If you get asked what page to start on choose Portal.html

Getting Eclipse's GWT Dev mode working again after version changes

When the root pom.xml's version changes (upon each sprint's release), your dev mode will be broken (giving either a 404 or a 503 error when you try to view the page at http://127.0.0.1:8888/Portal.html?gwt.codesvr=127.0.0.1:9997. To fix this you can do one of two things:

• Remove all of your PLFM projects, check out a fresh copy of the PLFM project and start from the beginning of this document.
• Alternatively, you can just rebuild your Eclipse's Portal project and keep your files in place:

1. Git pull update to the newest version
2. Delete your project from Eclipse (leave "Delete project contents on disk" UNCHECKED)
3. Go to client/web/ and delete .classpath, .project and the .settings/ folder
4. Go to Step 5 in "UI Development above"

If this still doesn't work, or your dev mode is broken for another reason (e.g. after an svn update), there are some further steps you can take.
(Check out this site for more information: http://www.eclipsezone.com/eclipse/forums/t61566.html)

1. Use the '-clean' argument.
   1. One way to do this is to add -clean on its own line as the first line on the eclipse.ini file, and restart Eclipse.
2. Use a new workspace.
   1. I followed the instructions in the site linked above. The gist of it is:
      1. Export your preferences to somewhere outside your Eclipse environment environment (Export -> General -> Preferences. Make sure that 'Export All' is checked.)
      2. Switch to a new workspace. (Switch Workspace -> Other, then name your new workspace.)
      3. Import your preferences into this new workspace (Import -> General -> Preferences, make sure 'Import All' is checked.)
      4. Import trunk as usual.

Technologies used

There are several technologies that we are currently utilizing in the portal. The following is a list of primers for each:

• For dependency injection (IoC) we are using a combination of GIN and Guice.
  • Guice - is the base IoC technology but it is only fully functional in Server-side. http://code.google.com/docreader/#p=google-guice&s=google-guice&t=Motivation
  • Gin - provides basic IoC for GWT client-side code. http://code.google.com/p/google-gin/wiki/GinTutorial
  • Guice Servlet - This is a sub-project of Guice that allows dependency inject into Servelets. http://code.google.com/p/google-guice/wiki/ServletModule
• Http REST calls are currently made using Spring's RestTemplate. http://blog.springsource.com/2009/03/27/rest-in-spring-3-resttemplate/
• To create API REST stub-services we are using a combination of two technologies:
  • Jersey - provides a quick and easy method for transforming simple POJO's into RESTful web services using annotations. http://jersey.java.net/nonav/documentation/latest/user-guide.html
  • Grizzly - The GrizzlyWebContainerFactory makes it simple to start a local web container. http://blog.msbbc.co.uk/2008/11/java-using-jersey-and-grizzly-to-create.html

How to override configuration (obsolete, needs updating)

If you want to point it to a locally running instance of the repository service:

1. Run As->Run Configurations
2. click on the "Arguments" Tab
3. add to the VM Arguments -Dorg.sagebionetworks.rest.api.endpoint=http://localhost:8080/
   

Creating a new Maven + GWTproject

This section outlines what is needed to create a new Java project that is configured correctly for both Maven and GWT. To setup a project correctly, we will be depending on the gwt-maven-plugin: http://mojo.codehaus.org/gwt-maven-plugin/.

1. From command line run the following command, and fill in all of the variables:

   mvn archetype:generate \
   -DarchetypeRepository=repo1.maven.org
   -DarchetypeGroupId=org.codehaus.mojo \
   -DarchetypeArtifactId=gwt-maven-plugin \
   -DarchetypeVersion=2.1.0-1
   

2. By default this seems to assume you want to use java 1.5, so we need to change the following files to use 1.6:
   1. ./settings/org.eclipse.jdt.core.prefs
   2. ./settings/org.eclipse.wst.common.component
   3. ./settings/org.eclipse.wst.common.project.facet.core.xml
   4. pom.xml
3. Once you have everything set you are ready to import the new project into eclipse.
4. Now set the correct library path in eclipse by doing the following:
   1. Right-click the project root in the package explorer and select properties.
      1. Under the Java Build Path tab, select Libraries.
      2. Remove the 1.5 JRE library.
      3. Select Add Library...
      4. Select JRE System Library then Next, and choose a 1.6 library.
5. Open the pom.xml in an editor and make the following changes:

   1. In the gwt-maven-plugin, comment-out the generateAsync goal as it conflicts with the GWT eclipse plugin:

      <plugin>
      <groupId>org.codehaus.mojo</groupId>
      <artifactId>gwt-maven-plugin</artifactId>
      <version>2.1.0-1</version>
      <executions>
      <execution>
      <goals>
      <goal>compile</goal>
      <goal>test</goal>
      <goal>i18n</goal>
      <\!-\- <goal>generateAsync</goal>-->
      </goals>