Developing for ToolTwist in Eclipse - tooltwist/documentation GitHub Wiki

Pre-requisites

Before starting, you'll need these technologies installed on your machine:

  • gradle
  • ImageMagick
  • MySQL (if you wish to use traditional ToolTwist security)
  • Tomcat

Set up Gradle

  1. Create a location for you application specific repository. When you publish extension projects they will be added here.

    $ sudo su

    $ mkdir -p /Development/gradle-repo

    $ chown -R kelvin.santos:kelvin.santos /Development/

  2. Create a file named ~/.gradle/gradle.properties, replacing the paths to your home directory:

    localRepo=/Development/gradle-repo

    PROPERTY_LOCAL_REPOSITORY=file://Development/gradle-repo

    PROPERTY_TOOLTWIST_REPOSITORY=file://Development/tooltwist-repo

Unzip ToolTwist

  1. Unzip the tooltwist repository files into a directory on your own machine, or on a shared drive for use by all developers.

    $ cd /Development

    $ unzip tooltwist-8.5.0.zip

Install Eclipse

  1. Create a location for you application specific repository.

    $ mkdir /Tools

    $ chown -R kelvin.santos:kelvin.santos /Tools/

  2. Install a standard J2EE version of Eclipse. While preparing this wiki page we used eclipse-jee-mars-1-macosx-cocoa-x86_64.tar.gz on OSX and installed it at /Tools/.

  3. Start Eclipse, and create a new workspace, for example at /Development/tooltwist-8.5.0.

  4. If you wish to use Github, instructions can be found here. You might need to use Help->Eclipse Marketplace->Installed update EGIT first.

Install the ToolTwist wizard

(At the time of writing the wizard has not been updated to v8.5.0)

  1. Help->Install New software

  2. Use this http://kelvinsantos.github.io/eclipsePluginUpdateSite/ to install ToolTwist Wizard.

  3. You may need to restart Eclipse to make the wizard take effect.

Tomcat Web Server

  1. Use Help->Cheat Sheets->ToolTwist->Tomcat Server Setup to define and configure the Tomcat Server.

  2. On the Tomcat configuration tab, use Use Custom location (does not modify Tomcat installation).

  3. For Server Path, click Browse... and select the deployed-server directory.

  4. You might need to install a keystore file for Tomcat to provide https (get one from a previous install?). It needs to be placed in Servers/Tomcat\ v7.0\ Server\ at\ localhost-config/keystore.

Create configuration files

$ export TOOLTWIST_HOME=/Development/Tooltwist-8.5.0/site-conf
$ mkdir -p $TOOLTWIST_HOME/conf

You then need to create these config files:

Download the demo project

$ cd /Development/ToolTwist-8.5.0
$ mkdir webdesign
$ (cd webdesign; git clone https://github.com/twistresources/ttdemo.git)

Extension Projects

  1. Install your projects

Existing Project:
In the clean Eclipse workspace, select File->Import->Git->Projects from Git->Next->Clone URI->Next, then enter the URL for you git repository (for example [email protected]:philcal/trackmotion.git).

When it asks for the location to clone the repository, make sure you use ~/Development/ToolTwist-8.5.0, not ~/git.

New Extension Project:
Use Help->Cheat Sheets...->ToolTwist->Creating a ToolTwist project.

  1. Create a build.gradle.

In your extension project directory, create a file named build.gradle. You can use this example build.gradle and simply update the project dependencies.

Note: If you are using Tooltwist Source Code, make sure to update settings.gradle (Refer to Using ToolTwist Source Code - Step 2)

  1. Compile your project using gradle (run in project directory) and check for errors.

    $ gradle compileJava

  2. Update the Eclipse classpath to match the dependencies

    $ gradle eclipse

  3. Update classpath in Eclipse

In Eclipse, right click on the project and select Refresh, then right click again and select Properties.

In Java Build Path->Libraries you should see a library for each project dependency. If you see junit or javaee-api, delete it from the list.

Also under the Libraries tab, check there is an entry for Apache Tomcat Runtime. If it is missing, use Add Library... to add it.

  1. Under Deployment Assembly you should have the following mappings, with a list of jar files for your dependencies. These may need to add them using Add...->Java Build Path Entries (don't forget this step!).

Deployment Assembly for ttsvr

Using ToolTwist Source Code

If you wish to work with the ToolTwist source code follow these steps to allow development or debugging.

  1. Import the source into Eclipse. Make sure you load these repos into ~/Development/ToolTwist-8.5.0, not ~/.git.

     - ssh://[email protected]/twistresources/tooltwist.git  
 - [email protected]:twistresources/ttWbd.git  
 - ssh://[email protected]/twistresources/ttStd.git  
 - https://github.com/twistresources/ttsec-standaloneDesigner.git

  2. Create ~/Development/ToolTwist-8.5.0/settings.gradle. These settings tell gradle that these projects are all related.

     //set parent as our root project  
 rootProject.name = 'ttsvr'  
 rootProject.projectDir = new File(settingsDir, 'ttsvr')  
  
 //include sub projects  
 includeFlat 'tooltwist'  
 includeFlat 'ttWbd'  
 includeFlat 'ttStd'  
 includeFlat 'myproject'

  3. In your project's build.gradle change your dependancy definitions to use projects:

     compile project(':tooltwist')
 compile project(':ttStd')
 compile project(':ttWbd')
 compile project(':ttsec-standaloneDesigner')

  4. Run gradle eclipse in each of the eclipse source directories, and adjust the Java Build and Deployment Assembly as discussed above.

Deployment Assembly for tooltwist project

  1. In Eclipse, refresh each of these projects, and add them to ttsvr.

Common Problems

Problem: Cannot log in to Designer

    com.dinaa.xpc.XpcConfigException: Unknown user type: ...

This exception is displayed in the browser when attempting to use the Designer. It is caused because the file standaloneDesigner.userType.xpc is not being found. Check that all the required projects are defined in site-conf/config/tooltwist.xml, including ttsec-standaloneDesigner.

Problem: Cannot start ttsvr when Tomcat starts

If the Tomcat log contains an error like this, it may be caused because web.xml is corrupt or cannot be found.

    [29/01/14 10:06:53 AM] carlo.adona: SEVERE: A child container failed during start
    java.util.concurrent.ExecutionException: org.apache.catalina.LifecycleException: Failed to start component [StandardEngine[Catalina].StandardHost[localhost].StandardContext[/ttsvr]]
            ...
    	at java.lang.Thread.run(Thread.java:722)
    Caused by: org.apache.catalina.LifecycleException: Failed to start component [StandardEngine[Catalina].StandardHost[localhost].StandardContext[/ttsvr]]
    	at org.apache.catalina.util.LifecycleBase.start(LifecycleBase.java:154)
    	... 7 more
    [29/01/14 10:06:58 AM] carlo.adona: could not start tomcat

Check that you have web.xml at ttsvr/src/main/wepapp/WEB-INF/web.xml, and check that your Deployment Assembly for ttsvr contains these entries:

    /src/main/webapp -> /
    /WebContent -> META-INF/resources
    + projects (e.g. filemap, tooltwist, ttStd, ttWbd, ttsec-standaloneDesigner, xdata, myproject)

Problem: Missing classes at runtime

These errors may occur at runtime, and may even prevent Tomcat from starting the ttsvr webapp.

    java.lang.ClassNotFoundException: ch.qos.logback.core.joran.spi.JoranException
    	at org.apache.catalina.loader.WebappClassLoader.loadClass(WebappClassLoader.java:1702)
    	at org.apache.catalina.loader.WebappClassLoader.loadClass(WebappClassLoader.java:1547)
            ...

This error is caused by an incorrect classpath, where the dependencies defined in the build.gradle files are not passing all the way through to the Tomcat deployment. Usually this is caused by an incorrect Deployment Assembly definition for one of the projects.

  1. Look through your projects and check they all have the jars defined in their deployment assembly. Running the gradle eclipse command sometimes resets the Deployment Assembly definition.

  2. If all the Deployment Assemblies appear correct, then check that the Deployment Assembly for ttsvr is correct. Review this section again.

  3. If ttsvr is correctly configured, one must of the projects may be missing the jar file containing the class. To determine the jar file the class belongs in. In Eclipse type Command-Shift-T (or Ctrl-Shift-T on windows) and enter the name of the missing class. The bottom status message should show the name of the jar containing the class.

Finding the JAR containing a Class

  1. Look at each of your build.gradle files and see which uses this jar file. For that project, check that the Java Build path for the project includes the jar file. If not, run gradle eclipse again for the project.

  2. Check that the Deployment Assembly for the project also contains the jar file.

  3. If you cannot determine which project uses the jar file, the gradle dependencies command may be useful.

Problem: Cannot change Tomcat configuration

If you can't change the Tomcat configuration because that section of the config screen is disabled...

Finding the JAR containing a Class

... you'll need to

  1. shut down the server
  2. Go to the Modules page, unmap ttsvr and any other modules from the server, then save with Command-S.
  3. Go to the Servers tab, select the Publish icon.

Problem: Error converting images

If generating images in the Designer creates error messages in the Tomcat log (for example, when using Misc->Generate Images), then you may have to adjust the ImageMagic configuration.

2014-01-29 12:49:12,003 DEBUG t.i.ImageManipulation - /usr/local/bin/convert ...
2014-01-29 12:49:12,017 DEBUG t.i.StreamGobbler - convert:ERROR >dyld: Symbol not found: __cg_jpeg_resync_to_restart
2014-01-29 12:49:12,018 DEBUG t.i.StreamGobbler - convert:ERROR >  Referenced from: /System/Library/Frameworks/ApplicationServices.framework/Versions/A/Frameworks/ImageIO.framework/Versions/A/ImageIO
2014-01-29 12:49:12,018 DEBUG t.i.StreamGobbler - convert:ERROR >  Expected in: /usr/local/lib/libjpeg.8.dylib
2014-01-29 12:49:12,018 DEBUG t.i.StreamGobbler - convert:ERROR > in /System/Library/Frameworks/ApplicationServices.framework/Versions/A/Frameworks/ImageIO.framework/Versions/A/ImageIO
...

Try these steps:

  1. Type convert on the command line and check that ImageMagick is installed.

  2. Use which convert to determine where it is installed.

     $ which convert
 /usr/local/bin/convert

  3. Update the entry in webdesign/config/wbd/wbd.conf to point to this directory, excluding the /bin.

     # ImageMagick-related properties
 # imageMagickHome not required for Windows
 isWindows=N
 imageMagickHome=/usr/local

Problem: Generated Images don't appear until server is restarted

On the Tomcat server configuration page, check you have Serve Modules without publishing selected.

Server modules without publishing

Problem: Eclipse hangs when changing validation preferences

On Mac, Eclipse kepler will hang with a spinning beach ball if you click on a settings button on the validation preferences page. The solution is to click on the row before clicking the button, or to use the right mouse button.

--