Preparing an extension project for v8.3 - tooltwist/documentation GitHub Wiki

Back

Extension projects should be converted one at a time, in order of their dependencies. If A depends upon B, then B should be converted first.

If possible, make sure that the extension project compiles properly in Eclipse before starting.

Make sure you have all changes committed to git, and create a new branch for the conversion.

$ git checkout -b v8.3-convert

For Gradle, java source must be placed beneath src/main/java, rather than just under the traditional src directory. To keep your commit history, make sure you use git to do the move. For example:

$ cd src
$ mkdir -p main/java
$ git mv com main/java
$ git mv META-INF main/java
...

Continue till you have moved all the source code into the new location.

Create build.gradle in the root directory of you extension project.

Example build.gradle

This file is almost identical for all extension projects. In mist cases only the dependencies need to be changed.

If the project does not already have gradlew and gradlew.bat scripts in it's root directory, create them with these commands and save them to git.

$ gradle wrapper
$ git add gradle gradlew gradlew.bat
$ git commit -m "[CONFIG] Add Gradle wrapper"

In Eclipse take note of the 3rd party jars used by the project. We won't be using a 3rdPartyJars project or WEB-INF/lib from this point on. Rather these dependencies should be defined in build.gradle, and will be loaded back up into Eclipse.

It's a good idea to take a screen shot of the Build Path libraries in Eclipse, for later reference.

Update the dependencies section of build.gradle. If you aren't sure where to find the jar for a class, this video might help:

Once you are finished, load the dependencies into Eclipse:

$ gw eC eclipse              (gradlew eclipseClean eclipse)

In Eclipse:

1. refresh the project
2. In the project properties dialog, check the Source tab for dependencies, or overlap between src and src/main/java.
3. Remove any projects from the Projects tab.
4. Check the Libraries tab contains a valid libraries for JRE System and Apache Tomcat.
5. Clean the project (Project->Clean).
6. If you have too many JSP errors, disable JSP Syntax Validation for the project. This can be done from the project Properties dialog, on the Validations pane. There was a bug here that caused Eclipse to hang. To prevent it, click on the JSP Syntax Validator line first, before un-selecting the checkboxes.

If there are any compile errors try to fix them in Eclipse.

If you have dependency errors, you might need to proceed to the next section to find the cause, then repeat some of this section to re-load the dependencies into Eclispe.

Before trying to publish the project to Artifactory, we'll first just build the jar file.

$ g jar

If you have compile errors, fix them in Eclipse (it's easier).

If you have dependency errors, we can request progressively deeper levels of debug information. We can quickly get overwhelmed with information, so these steps prevent us from getting swamped unless we need to.

1. Standard error message The command above will give an error message like this.

    FAILURE: Build failed with an exception.
   
    * What went wrong:
    Could not resolve all dependencies for configuration ':compile'.
    \> Could not find com.tooltwist:ttStdZ:8.3.2.
      Required by:
          com.tooltwist:bootstrap-tooltwist:1.0.0-SNAPSHOT
   

If the dependency is one of your own projects, check that the dependency definition looks correct in build.gradle, and check the resource exists in Artifactory and is the correct version.

1. Information Log Messages Information level logging will give us the URL being used to access Artifactory.

    $ g -i jar
    ...
    Resource missing. [HTTP GET: http://repo.tooltwist.com/artifactory/tooltwist-all-in-one/com/tooltwist/ttStdZ/8.3.2/ttStdZ-8.3.2.pom]
    ...
   

In your browser, log in to http://repo.tooltwist.com/artifactory as the user defined in ~/.gradle/gradle.properties. We can then take the URL from the error message and add ?trace onto the end, and enter it into a browser.

Since tooltwist-all-in-one is a virtual repository it maps onto - and will search - multiple local and remote repositories. With the trace command Artifactory will display each in turn along with it's result.

1. Debug level logging If info level didn't provide enough information, you can try debug level:

    $ gradle -d jar | More
    ...
    02:37:53.513 [DEBUG] [org.apache.http.impl.conn.DefaultClientConnection] Sending request: GET /artifactory/tooltwist-all-in-one/com/tooltwist/ttStdZ/8.3.2/ttStdZ-8.3.2.
    ...
   

pom HTTP/1.1 02:37:53.609 [DEBUG] [org.apache.http.impl.conn.DefaultClientConnection] Receiving response: ... ...

Search for Receiving response (use '/' in more to search), and you should find the reason the resource cannot be found. A 404 error means the repository doesn't believe the resource is in any of the repositories the virtual repository maps to.

Tip: The curl command can also be used to run a trace. For example:

    curl -ufred.smith:{DESede}NHQXUshwJ28hShajks96nZ==  http://repo.tooltwist.com/artifactory/tooltwist-all-in-one/com/tooltwist/ttStdZ/8.3.2/ttStdZ-8.3.2.pom?trace

Once your project compiles without errors in Eclipse and also from the command line, you can publish it to Artifactory. Initially, it is highly recommended that you only publish a SNAPSHOT, usually starting from 1.0.0-SNAPSHOT.

    $ gw aP                    (gradlew artifactoryPublish)

An extension project MUST NOT define a web.xml, but usually should define a web-fragment.xml.

This file can contain the servlet definitions specific to this extension project, but not the standard ToolTwist servlets, etc which will be defined elsewhere. The definitions of all the extension projects are merged at the time the server is started.

Below is an example web-fragment.xml:

src/META-INF/web-fragment.xml:

    <?xml version="1.0" encoding="UTF-8"?>
    <web-fragment id="WebFragment_ID" version="3.0" xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-fragment_3_0.xsd">
    <display-name>skyportal</display-name>
            <name>skyportal</name>
    
            <servlet>
                    <servlet-name>tooltwist.skypepi.servlet.CourseNavigatorServlet</servlet-name>
                    <servlet-class>tooltwist.skypepi.servlet.CourseNavigatorServlet</servlet-class>
            </servlet>
            <servlet-mapping>
                    <servlet-name>tooltwist.skypepi.servlet.CourseNavigatorServlet</servlet-name>
                    <url-pattern>/servlet/tooltwist.skypepi.servlet.CourseNavigatorServlet</url-pattern>
            </servlet-mapping>
            ...
    
    </web-fragment>

Your build.xml should contain this code to tell the JAR plugin to include the META-INF directory in the jar.

    sourceSets {
        main.compileClasspath += configurations.provided
        test.compileClasspath += configurations.provided
        test.runtimeClasspath += configurations.provided
        main {
            resources {
                srcDir 'src'
            }
        }
    }

Check for interceptors that may stop the Designer from working (config/interceptors/interceptor.*.xml). If you find any, you can temporarily disable them with the enabled tag:

    <interceptor>
            <class>tooltwist.skypepi.interceptor.LoginInterceptor</class>
            <enabled>false</enabled>
    </interceptor>

Don't forget to change them back once you work out what the problem is.

Not sure if this is required (Phil August 2014)

Create either ./init.gradle or ~/.gradle/init.gradle:

    gradle.projectsLoaded {
        rootProject.allprojects {
            buildscript {
                repositories {
    			maven{
    			//url "http://repo.jfrog.org/artifactory/gradle"
    			url "http://repo.tooltwist.com/artifactory/tooltwist-all-in-one"
    			}
    		    dependencies {
    			classpath(group: 'org.jfrog.buildinfo', name: 'build-info-extractor-gradle', version: '2.0.12')
    		    }
    		}
             }       
        }
    }

Part of the migration to ToolTwist v8.3 involves switching from log4j to slf4j.

If this hasn't been done already, the best way to do this is to change the build.gradle, import into Eclipse, and then rectify the compile errors from the Logger class is no longer being defined.

    [remove to build.gradle]
    compile group: 'log4j', name: 'log4j', version: '1.2.15'
    compile group: 'wsdl4j', name: 'wsdl4j', version: '1.6.3'

    [add to build.gradle]
    compile group: 'ch.qos.logback', name: 'logback-core', version: '0.9.30'
    compile group: 'ch.qos.logback', name: 'logback-classic', version: '0.9.30'
    compile group: 'org.slf4j', name: 'slf4j-api', version: '1.6.2'

After reloading the dependencies in to Eclipse (`g eclipse), update your source files in Eclipse to remove the compile errors shown in the Problems tab. If you know your Eclipse short cuts this doesn't take long.

    [in your source files]
    import org.slf4j.Logger;
    import org.slf4j.LoggerFactory;
    ...
    private static final Logger logger = LoggerFactory.getLogger(MyThing.class);

One change in the migration to v8.3... the following is no longer defined:

    Navpoint np = WbdCache.findNavPoint(linkNavpoint, false);

This should now be replaced with:

    Navpoint np = generator.getProject().findNavPoint(linkNavpoint, false);

or

    Navpoint np = WbdCache.findNavPointInAnyLoadedProject(linkNavpoint, false);

The second of these should normally be avoided, as it can find navpoints external to the current webdesign project.

    g clean
    g jar
    g cleanEclipse (g cE)
    g eclipse
    g artifactoryPublish (g aP)

--