jWic Migration Guide

Migration Guide
How to migrate existing applications from previous jWic versions to the latest version.

Last Update: 2006-09-28
Author: Florian Lippisch

From jWic v3.1.0 to v3.2.0

Follow the standard update procedure:

Update the jwic.jar file with the one from the latest distribution
Replace the content of the web_root/WEB-INF/jwic folder with the one from the distribution.
Replace the content of the web_root/jwic folder with the one from the distribution (default_webapp). If you have changed some of the files, you must migrate them manually.

jWic is now using the UTF-8 charset for all request types. Make sure that you updated the file jwic.ajax.page in the WEB-INF/jwic/pages folder and the jwic/jwic.js file.

Another noteworthy thing is that the .xwic application files are now named with an .xml suffix. This way the files are opened in an XML editor in common IDEs without the need to map the .xwic file extension to an XML editor. However, the request URL still ommits the .xml suffix (thought that you could map the extension in the web.xml file) and the old files are also found.

From jWic v3.0.4 to v3.1.0

Update the jwic.jar file with the one from the latest distribution
Replace the content of the web_root/jwic folder with the one from the distribution (default_webapp). If you have changed some of the files, you must migrate them manually.

From jWic v3.0.3 to v3.0.4

Follow those instructions to update your project:

Update the jwic.jar file with the one from the latest distribution
Replace the content of the web_root/jwic folder with the one from the distribution (default_webapp). If you have changed some of the files, you must migrate them manually.
If you have implemented containers that needs to get notified when a child-control is removed, must now override unregisterControl(..) instead of removeControl(..). This change was required to implement the adopt(..) functionality, which moves a control to a new container without destroying it.

Controls that listen to user actions with the actionPerformed(..) method may now make use of the auto-invocation of action methods: (Note that this step is optional.)
Old Code:

public void actionPerformed(String actionId, String parameter) {
  if(actionId.equals("add")) {
    add(parameter);
  } else if (actionId.equals("delete")) {
    delete(parameter);
  }
  
}
public void add(String parameter) {..}
public void delete(String parameter) {..}

New Variant:

 // do not override the actionPerformed method in that case!
public void actionAdd(String parameter) {
  ..
}
public void actionDelete(String parameter) {
  ..
}

From jWic v3.0.1/3.0.2 to v3.0.3

Follow those instructions to update your project:

Update the jwic.jar file with the one from the latest distribution
Add the dom4j.jar library to your project and add it to the classpath. This is important as jWic 3.0.3 won't run without it!
Replace the content of the web_root/jwic folder with the one from the distribution (default_webapp). If you have changed some of the files, you must migrate them manually.

Optional: It is recommended to migrate your custom jwic.page file to the new version that includes the required code from templates in the web_root/jwic folder for easier updates. Sample:

#parse("jwic/jwic.page.header")

## add your custom META, SCRIPT or LINK tags here
<link rel="stylesheet" type="text/css" href="sample.css">

#parse("jwic/jwic.page.body")

## Uncomment the following line to enable debug informations
## #parse("jwic/jwic.page.debug")

<!-- content -->
$content.render()
<!-- /content -->

#parse("jwic/jwic.page.footer")

The doctype is now specified as transitional in the included jwic.page.header. If you encounter layout problems in your existing application, it is recommended to remove this line:
```
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
```

From jWic v3.0.0 to v3.0.1

Follow those instructions to update your project:

Update the jwic.jar file with the one from the latest distribution
Add the commons-lang-2.1.jar library to your project and add it to the classpath. This is important as jWic 3.0.1 won't run without it!
Update the jwic directory in your webapp with the one from the distribution. This includes especialy the jwic.js JavaScript library and css files.

From jWic v2.1.x to v3.0.0

jWic 3.0 has changed the API at some central places, making it incompatible to older versions. Replacing the jwic.jar will result in a lot of errors in your existing classes, but they are easy to solve. This guide will not explain the pro's and con's of those changes as they are discussed in other places.

Updating the Environment

Update the API by replacing the jwic.jar file with the latest version.
Replace the jwic folder in your webapp-dir with the one from the distribution (default_webapp/jwic).
If you have modified those resource files (which is not recommend!), put those changes in an extra js file and include it in your jwic.page file.

Update the jwic.page file used by your application. Search the following part in the file:

<input type="hidden" name="_msid" value="$session.identifier">

And replace it with:

<input type="hidden" name="_msid" value="$context.sessionId">

Update the jwic-setup.xml configuration file in your WEB-INF directory. The easiest way to do this is to replace the file with the one from the distribution in default_webapp/WEB-INF.

Migrate your Application(s)

Control Instantiation

The probably most noticeable change from jWic 2 to 3 is the way how controls are instantiated. In jWic 3, the container for a control must be passed to the control in the constructor. This makes sure that the control is in a valid state before it can be used. The usage of controls change like this:

// jWic 2.x:
ButtonControl button = new ButtonControl();
container.addControl("name", button); // add the control with the specified name

LabelControl label = new LabelControl();
container.addControl(label); // add the control with a default name

// jWic 3.x:
ButtonControl button = new ButtonControl(container, "name");
LabelControl label = new LabelControl(container);

All controls must implement this instantiation mechanism and implement an explicit constructor with the arguments IControlContainer, String. The initialisation that was previously done in the init() method must be done in the constructor as the init() method is no longer invoked by the framework.
The control must call the superconstructor super(IControlContainer container, String name) to register itself at the container. The name argument can be null to let the framework generate a name. Implementing a constructor without the String name argument is optional, but it makes it easier for others to use your control.

// jWic 2.x:
public class MyControl extends Control {
  ..
  public void init() {
    // initialize
    myColor = RED; 
    todaysTopic = TopicProvider.getTodaysTopic();
    ..
  }
}

// jWic 3.x:
public class MyControl extends Control {
  ..
  public MyControl(IControlContainer container, String name) {
    super(container, name);
    // initialize
    myColor = RED; 
    todaysTopic = TopicProvider.getTodaysTopic();
    ..
  }
}

// jWic 3.x, using two constructors:
public class MyControl extends Control {
  ..
  public MyControl(IControlContainer container) {
    super(container, null);
    init();
  }
  public MyControl(IControlContainer container, String name) {
    super(container, name);
    init();
  }
  private void init() {
    // initialize
    myColor = RED; 
    todaysTopic = TopicProvider.getTodaysTopic();
    ..
  }
}

Note: If you are using an init method that you call from within your constructors, make sure that you mark it private. Otherwise this method could be overriden by controls that extend your control. In such a case, the fields set by the overriden init method will be set back to the default values if they are specified.

New: The Application

Previous jWic versions did not made a difference between a simple container and the root object of the application. In jWic 3, a special object has been introduced that is used as the start class: IApplication interface and the Application which acts as an adapter for this interface.
The application object is responsible to create and setup the root control. You find more details about the Application object in the reference documentation.

// jWic 2.x:
public class MyApplication extends Page {
  public init() {
    setTitle("My-Application");
    MyControl control = new MyControl();
    addControl(control);
    ...
  }
}

// jWic 3.x:
public class MyApplication extends Application {
  public Control createRootControl(IControlContainer container) {
    Page page = new Page(container);
    page.setTitle("My-Application");
    //If you used a template for the page, you must explicitly specify it now:
    page.setTemplate(getClass().getName()); 
    MyControl control = new MyControl(page);
    
    return page; //You must return the control that is the root of the application!
  } 
}

The usage of an application object is not explicitly required. If you do not specify an application in your application-setup, a default application will be created that simply returns your specified root control. The configuration of the .xwic files do look like this now:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE application SYSTEM "http://www.jwic.de/dtd/xwic-3.0.dtd">
<application>
  <name>jWic Samples #1</name>
  <!-- Either use the class element to specify your application class -->
  <class>de.jwic.samples.sample1.HelloWorld</class>
  <!-- Or use the rootcontrol element to specify your root control.
     - If booth elements are specified, the rootcontrol is ignored. -->
  <rootcontrol 
    name="root"
    classname="de.jwic.samples.sample1.HelloWorld"/>
</application>

ListControls (ListBoxControl, CheckBoxControl, RadioGroupControl)

The argument order of the ListControl method addElement(String key, String title) has changed to addElement(String title, String key). We know that this is a possible trap for errors when it gets forgotten, but it makes it a lot easier for new users since we already got a addElement(String title) method.

Field processing

The way how field values are handled has been changed entirely in jWic3. Each field on the HTML form is now represented by a Field object. To make migration easier, the old way with setFieldValue(..)/getFieldValue(..) is still possible but deprecated. Look into the reference manual for details about the new field management.

ObjectSelectedListener renamed to SelectionListener

The listener used for button and anchor controls has been renamed to apply to the JavaBean listener convention. The old one is still available and works, but it has became deprecated.

// jWic 2.x:
button.addSelectionListener(new ObjectSelectedListener() {
  public void objectSelected(ObjectSelectedEvent event) {
    ...
  }
}

// jWic 3.x:
button.addSelectionListener(new SelectionListener() {
  public void objectSelected(SelectiondEvent event) {
    ...
  }
}

Logging in Subclasses of Control

The logger is now accessed using the protected field log instead of the method log().

Other Controls

A few controls have been moved from the base jWic library to a new library called 'ecolib'. The controls that got moved are:

ErrorWarningControl
InputDialogControl
MessageDialogControl
WizardControl
ProgressBarControl, including IBackendJob, BackendJob

Support & Feedback

You can post problems (or feedback) either on the board (http://www.jwic.de/board) or by mailing on our mailing-list.