acme_t.jar:
     [echo] Creating acme_t.jar
...
    [javac] Compiling 44 source files to /Controller/launchpads/rpconlgen/tmp/rpconlgen_t-20100824.1/build
    [javac] Compiling 163 source files to /Controller/launchpads/cbapg/tmp/rp-bsg-20100831/build
    [javac] /Controller/launchpads/pad1/tmp/acme-20100831/src/com/acme/JsonRequest.java:3: package com.google.gson does not exist
    [javac] import com.google.gson.JsonArray;
    [javac]                       ^

The Java class compiled correctly in the ToolTwist workbench (Eclipse) but got this error when building in the Controller.

The most common cause for this type of error is a missing JAR file. To ensure that a JAR file is included when the payload is built by the Controller, it must be placed in the WebContent/WEB-INF/lib folder for the project.

In this case, the error above was corrected by installing WebContent/WEB-INF/lib/gson-1.5.jar in the acme_t project in Eclipse, and then submitting a new acme_t payload to the Controller. Using the new version of the acme_t payload, the build completed.

If the navpoints file is edited directly from within Eclipse, the navpoint hierarchy might disappear when the server is restarted.

If this occurs, the most common reason is that the encoding for the file is incorrect. To check this, right click on the file in the designer (e.g. webdesign/config/wbd/navpoints/acme/navpoints.conf) and select properties. On the Resource tab, you'll see a section titled "Text file encoding". The correct value for this is UTF-16.

If it's incorrect, change it then save the file again, then restart the server.

I always encounter this error in eclipse console when I update a widget and restart the tomcat server:

SEVERE: IOException while loading persisted sessions: java.io.WriteAbortedException: writing aborted; java.io.NotSerializableException: com.dinaa.ui.UimDataStoredInSession
java.io.WriteAbortedException: writing aborted; java.io.NotSerializableException: com.dinaa.ui.UimDataStoredInSession
    at java.io.ObjectInputStream.readObject0(ObjectInputStream.java:1333)
    at java.io.ObjectInputStream.readObject(ObjectInputStream.java:351)
    at java.util.Hashtable.readObject(Hashtable.java:859)
    at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
    at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)
    at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)
    at java.lang.reflect.Method.invoke(Method.java:597)
    ...

Afterwards the wbd IDE would not open. Its not that critical nor urgent because there's a workaround by restarting the tomcat server.

1. Create a file named context.xml under WebContent/META-INF.  This file should contain the connection settings to the database.  An example is given below:

<?xml version="1.0" encoding="UTF-8"?>

<Context path="/ttsvr" docBase="ttsvr" crossContext="true" reloadable="true" debug="1">

    <Resource name="jdbc/postgres"
            auth="Container"
            type="javax.sql.DataSource"
            driverClassName="org.postgresql.Driver"
            url="jdbc:postgresql://10.1.1.153:5432/qvas_coc"
            username="postgres"
            password="vsc"
            maxActive="10"
            maxIdle="5"
            maxWait="-1"
            removeAbandoned="true"
            removeAbandonedTimeout="60"
            logAbandoned="true"
            />

</Context>

2. Get a datasource from the connection pool.  The example below shows how to get a datasource for a jndi resource named: jdbc/postgres.

    InitialContext initialContext = new InitialContext();
    if (initialContext == null) {
        String message = "InitialContext was not setup properly.";
        logger.error(message);
        throw new SQLException(message);
    }
    // actual jndi name is "jdbc/postgres"
    DataSource datasource = (DataSource) initialContext.lookup( "java:/comp/env/jdbc/postgres" );
    if ( datasource == null ) {
        String message = "WebApp resource was not setup properly.";
        logger.error(message);
        throw new SQLException(message);
    }

3. Get a connection from the datasource

    Connection con = datasource.getConnection();

For the QVAS project a utility class named JdbcUtil was created.  This class is used in XPC's to get a connection from the pool.

public class JdbcUtil {
    private static DataSource datasource = null;
    private static Logger logger = Logger.getLogger(JdbcUtil.class);

    private synchronized static DataSource getDataSource() throws NamingException, SQLException {
        if (datasource == null) {
            InitialContext initialContext = new InitialContext();
            if (initialContext == null) {
                String message = "InitialContext was not setup properly.";
                logger.error(message);
                throw new SQLException(message);
            }
            // actual jndi name is "jdbc/postgres"
            datasource = (DataSource) initialContext.lookup( "java:/comp/env/jdbc/postgres" );
            if ( datasource == null ) {
                String message = "WebApp resource was not setup properly.";
                logger.error(message);
                throw new SQLException(message);
            }
        }
        return datasource;
    }
    
    public synchronized static Connection getConnection() throws SQLException, NamingException {
        return getDataSource().getConnection();
    }

    public static synchronized void freeConnection(Connection connection) throws SQLException {
        connection.close();
    }
}

Usage:

    Connection con = JdbcUtil.getConnection();
    Statement stm = con.createStatement();
    ResultSet rst = stm.executeQuery(sql);

I have found that when you put document.observe('dom:loaded', function() {}) such as autocompleter from the widget, on tooltwist designer you can't move that widget out of the page into the basket.

To install FindBugs:

1. Click on Help > Install New Software...
2. Click on Add...
3. Fill in the following:
    - Name: FindBugs
    - Location: http://findbugs.cs.umd.edu/eclipse/
4. Check FindBugs and the packages underneath it
5. Continue the installation process by clicking on Next, I Agree, etc..

To use FindBugs

1. Right-Click on the project
2. Select Find Bugs > Find Bugs
3. The Find Bugs perspective gives a list of possible bugs with suggestions

Here's a list of common bugs found by Find Bugs on the Tutuki project and suggested actions:

1. When concatinating strings, especially within a loop, use StringBuffer instead of String
    wrong way:

        String s = "----\n";
        for (int i = 0; i < 10; i++) {
            s += "hello\n";
        }
        System.out.println(s);

    correct way:

        StringBuffer s = new StringBuffer("----\n");
        for (int i = 0; i < 10; i++) {
            s.append("hello\n");
        }
        System.out.println(s.toString());

    note: StringBuffer does not override the equals(Object) method.  Use the equals method of String by:

        StringBuffer sb = new StringBuffer("hello");
        if ("hello".equals(sb.toString())) ...

    or:

        if (sb.toString().equals("hello")) ...

2. Avoid empty catch blocks
    wrong way:

        catch (Exception ex) {}

    note: at the very least, do an ex.printStackTrace();  This is still not recommended though.  Best is to re-raise an exception.  Let tooltwist/tomcat/java handle that for you.
    best way:

        catch (Exception ex) {
            // few handling/logging statements
            throw new CustomException(ex);
        }

3. Handle specific exceptions explicitly.
    wrong way:

        catch (Exception ex)

    right way:

        catch (ExType1 ex) {
            ...
        }
        catch (ExType2 ex) {
            ...
        }

    According to FindBugs: "this construct also accidentally catches RuntimeException as well, masking potential bugs."

4. When a variable is not in use, delete it.  If you think the code will use this later, just comment it out.  The bulk of the errors/warnings was because of advance code.  One particular sample is the log4j logger.

5. Misc:
    - Always remove autogenerated comments.  These are comments marked with the text 'TODO Auto-generated'.
    - Always remove unused imports.  An eclipse shortcut is to press Command-Shift-'O' to organize imports.

Background
Quite commonly, multiple navpoints will refer to a single page layout. That doesn't make much sense if every page was rendered the same, so there are several mechanisms widgets can use to change their appearance, based upon the navpoint being rendered.

The first, is that the widget looks at one or more of the properties of the navpoint currently being rendered. For example, the navpoint ID, it's categories, it's title, or it's SEO related fields.

The second, more common way for a widget to change it's appearance - based upon the navpoint of the page - is to use page data.

Page data is XML data related to a specific widget, for a specific navpoint. If a widget defines that it wants to use page data, then any navpoint that refers to a page containing that widget will have the "Edit Page Data" button enabled. By clicking on that button, a user can then enter XML that will be used by the widget when it is rendering on that navpoint.

Note: In a future version, specific page data editors will be available. For now however, page data is all edited as XML.

Using Page Data in a Widget
To use page data, a widget controller must first implement the UsesPageData interface.

public class BillboardWidget extends WbdWidgetController implements UsesPageData
{

    @Override
    protected void init(WbdWidget instance) throws WbdException
    {
        instance.defineProperty(new WbdStringProperty("pageDataSection", null, "PageDataSection", "billboard"));
        ...
    }

    ...
    
    public XData getInitialPageData(WbdWidget instance)
    {
        StringBuffer xml = new StringBuffer();
        xml.append("<pageData>\n");
        xml.append("    <billboard>\n");
        xml.append("        <cropImage>cropImageName</cropImage>\n");
        xml.append("        <imageSrc>imageUrl</imageSrc>\n");
        xml.append("        <alt>Alternate text</alt>\n");
        xml.append("        <navPointId>[navPointId]</navPointId>\n");
        xml.append("        <url>[url]</url>\n");
        xml.append("    </billboard>\n");
        xml.append("</pageData>");     
        return new XData(xml);
    }

}

This will enable the "Edit Page Data" button for navpoints where this widget is used, and will provide default XML page data. The "PageDataSection" property is used by the page data editor to allow a unique block of XML to be edited for this widget.

The final step is to have the widget use the page data as it is rendering production pages.

    @Override
    public void renderForJSP(WbdGenerator generator, WbdWidget instance, UimHelper ud, WbdRenderHelper buf) throws Exception
    {
        String navpointId = WbdSession.getNavpointId(ud.getCredentials());
        String pageDataSection = instance.getProperty(generator, "pageDataSection");

        // Get the page data
        Xpc xpc = ud.getXpc();
        xpc.start("tooltwist.wbd.getPagedata", "select");
        xpc.attrib("pageDataNavPoint", navpointId);
        xpc.attrib("pageDataSection", pageDataSection);
        XData pagedata = xpc.run();

        // Render the widget, using the page data
        String imageSrc = pagedata.getText("/*/*/imageSrc");
        ...
    }

-oOo-

1. Output from a snippet.
2. Zero or more basic parameters, that may be substituted into the output from the snippet.
3. No logic.

Many user controls just require specific HTML or JSP output without any intelligence, except perhaps basic parameter replacement.

The following steps can be used to crete a new widget without any Java coding. In this example, we'll just create a page heading surrounded by h1 tags.

Step 1: Create a new widget directory
Create a new folder for a scratch version of the widget, for the your usual user id.

e.g.
mkdir ...../webdesign/config/wbd/libraries/myProject_widgets/headingWidget/scratch_myUserId

Step 2: Create the configuration file

In the folder just created, create a new configuration file for the widget (conf.xml).

<widget>
  <widgetClass>tooltwist.wbd.widgets.GenericWidgetController</widgetClass>
  <idWithinRootWidget>0</idWithinRootWidget>
  <label>Heading Widget</label>
  <icon>/tooltwist/wbd/toolbox_icons/youtube_icon.png</icon>
  <isStatic>Y</isStatic>
  <description>A heading surrounded by h1 tags</description>
  <property>
    <name>heading</name>
    <label>Heading</label>
    <type>string</type>
  </property>
</widget>

The property tag defines a property that can be edited in the normal manner within the ToolTwist designer.

Step 3: Create the snippet files
Create files named snippet_design.html, snippet_preview.html and snippet_production.jsp. These may be edited with a regular HTML or JSP editor. The parameters defined in the conf.xml will all be available as normal snippet variables.

<html>
<body>
<!--START-->
<h1>%%label%%</h1>
<!--END-->
</body>
</html>

Step 4: Restart the server
After restarting, the widget should be available to be dropped on a page.

In most cases, it is called during (a), when all the widgets are loaded, the first time someone goes into the Designer. If an error occurs here, it's not always easy to see. The exception is written to the log file, but ToolTwist silently traps the error to prevent a rogue widget from stopping the Designer from running. In most cases, nobody notices the exception till some time later, which can waste a lot of debugging time.

Another common problem, is if an exception in init() prevents the widget from ever working, until such time as it's reloaded from file. The widget fails every time it is asked to render itself, but the real error may have occurred a long time previously.

A better solution is to ensure that errors repeatedly occur, or are at least reported, whenever the widget is displayed in the Designer and also when the JSP pages are being generated.

A common problem occurs when the widget's init() cannot find a configuration file.

private XYZ config = null;

public void init()
{
    //  Load the configuration (i.e. stuff that might cause an exception)
    this.config = new XYZ(...);
}

public void renderForJSP(...)
{
    config.getValue();
}

If the config is not sucessfully loaded when init() is called, then renderForJSP() will always have a problem, either:
    - with a NullPointerException because config is null, or
    - because config has not been completely initialised, and contains invalid data.

A better design framework allows the widget to repeatedly trying to load the configuration until it succeeds.

private XYZ config = null;

private XYZ getConfig() throws WbdException
{
    if (config == null)
    {
        syncronized (this)
        {
            //  Load the configuration
            XYZ tmpConfig = new XYZ(...);

            // Do other stuff that might cause an exception
            ...

            // Final step
            this.config = tmpConfig;
        }
    }
}

public void init()
{
    // Don't load the config
}

public void renderForJSP(...)
{
    String value = config.getSomeConfigurationValue();
}

A few notes:
1. The config is not loaded until it is needed.
2. An exception in getConfig gets passed back to renderForJSP, and out through to the ToolTwist infrastructure,
so it can be included in ToolTwist's error reports.
3. The config variable is only set as the final step - after any chance of an exception occurring. this ensures that
the widget will try to load the config again if it fails.
4. The "synchronised" prevents the unlikely chance of a concurrency problem with multiple people using the Designer.

Cookie cookie = new Cookie("is_login", "true");
cookie.setPath(WbdCache.getWebappPrefix());
response.addCookie(cookie);

2. Aside from the cookie, you need to add a flag in the request object, so that if you have a Production Helper that will be checking for the login status before the current process has returned to the user's browser, your Production Helper will get the correct value.

LoginRequestHandler:

WbdSession.setTemporaryValue(uh.getCredentials(), "loginStatus", "true");

LoginProductionHelper:

String isLoginTempStr = WbdSession.getTemporaryValue(ud.getCredentials(), "loginStatus");

If you placed the login cookie in the HttpServletResponse object and the page goes through the Login Production Helper, the production helper won't be able to find the cookie from the HttpServletRequest object since it is independent from the HttpServletResponse object.  It needs to make a full cycle to the user's browser before the cookie is placed in the request object.

3. When logging out remove the cookie by expiring it and again set the login flag in the request object to false for the production helper.

Cookie[] cookies = request.getCookies();
for (Cookie c : cookies) {
    if (c.getName().equals("is_login")) {
    c.setMaxAge(0);
    response.addCookie(c);
    break;
    }
}
WbdSession.setTemporaryValue(uh.getCredentials(), "loginStatus", "false");

For a server that will be deployed from the Controller, the config files are copied as follows:

        /Controller/custom-config-files/p_tooltwist.conf-phil_tmp
            --> ~servername/server/tooltwist.conf

        /Controller/custom-config-files/p_wdb.conf
            --> ~servername/server/files/webdesign/config/wbd/wbd.conf

        /Controller/custom-config-files/p_web.xml
            --> ~servername/server/tomcat/webapps/ttsvr/WEB-INF/web.xml

Similar files can be used to override the config files for the launchpad. These might be needed to rectify errors while generating the CI web pages:

        /Controller/custom-config-files/p_tooltwist.conf-phil_tmp
            --> /Controller/launchpads/phil_tmp/image/tooltwist.conf

        /Controller/custom-config-files/p_wdb.conf
            --> /Controller/launchpads/phil_tmp/image/files/webdesign/config/wbd/wbd.conf

        /Controller/custom-config-files/p_web.xml
            --> /Controller/launchpads/phil_tmp/image/tomcat/webapps/ttsvr/WEB-INF/web.xml)

These files all provide some variable substitution, and are best copied initially from the directory named /Controller/custom-config-files/examples.

Commonly, these files are modifed for these purposes:

        web.xml - to define servlets
        tooltwist.conf - to define database connection URLs, and to define technology layers
        wbd.conf - to define application specific parameters, and parameters for the ToolTwist Designer.

The first step is to log on to the controller and go to the launchpad directory. e.g.

    ssh controller2@10.1.1.154        (harrier)
    cd /Controller/launchpads/phil_tmp

A normal build can be run with the following command:

    ant -f bootstrap.xml

This is the command that is normally run by the Hudson build task for the launchpad. Note that this only runs steps it decided are necessary, after comparing the launchpad's configuration files against timestamp files found in the launchpad directory.

To force the build to start at a specific step, you can remove one or more timestamp files:

    construct.timestamp
    validate.timestamp
    generate.timestamp
    install.timestamp

The stage for the file you remove will be performed, and subsequent stages as well. Prior stages will also occur if bootstrap.xml determines that they are required. For example, removing generate.timestamp will ensure that a generate and then an install are performed. However, if one of the payloads used by the launchpad have changed, then construct, validate, generate and installed will be performed.

Steps can be run independantly using the follwoing commands:

    ant - f construct.xml full    (stop the server, build everything, start the server)
    ant - f construct.xml start    (start the launchpad server)
    ant - f construct.xml stop
    ant - f construct.xml build
    ant - f generate.xml        (generate JSP files for navpoints, crop images, install stylesheets, etc)
    ant - f install.xml        (e.g. install files to phil_tmp@kingfisher)

Note however, that the status of the launchpad, as shown in the Control Panel, is not updated by these commands.

The following information assumes that the website worked properly when generated on the Designer (which may have been run from within Eclipse). In this case, the best approach is to work forwards from the start:

1. Look at the Tomcat log on the deployed server.

      ~/server/tomcat/logs/catalina.out

2. Check the deployment occured properly? The Hudson build log can be accessed from the Launchpad's status page.

3. Try a complete re-deploy (construct, validate, generate, install), and see if it solves the problem.

4. Test to see if the same problem occurs on the launchpad.
      a) go into the designer on the launchpad.
      b) generate on the launchpad, from the designer, then check that the site works properly.

5. Assuming it works on the Launchpad server.... check if the configuration files are different. Customised versions of web.xml, wbd.conf, and tooltwist.conf are defined in /Controller/custom-config-files.

6. Check the version of Java in use on the Controller and the deployed server.

7. Check the database can be accessed on the deployed server.

Their are several reasons this can occur:

1.  The design for a new web page has been deployed to the server, but a matching technology payload has not also been deployed. A typical scenario is this:

      - a new widget is been developed and is checked in with technology payload A.
      - a page uses that widget, and is submitted.
      - the new page is mapped to the production server (possibly via an "auto" payload), but the new technology
        payload is not.

Solution: ensure that a new technology payload is deployed, before any pages that use it's new widgets/classes.

2. MOST COMMON. A new technology payload is mapped onto the server. The Controller then installs new JSPs and new JAR files to the server, but the server has not been rebooted. As a result, the new JAR is not recognised by Tomcat.

Solution: Restart Tomcat.