Migration Guide for WebSphere sMash applications
This page summarizes the changes that need to be applied to applications from the previous release of sMash (version 1.0.0.x) to the latest (as yet unreleased) version of sMash (version 1.1).
Contents
Introduction
Overview
WebSphere sMash allows developers to build rich internet applications quickly using conventions. The WebSphere sMash programming model and runtime allow scaling such applications by adopting RESTful principles. Since the last official release (1.0.0.x) of WebSphere sMash, we have strived to maintain the programming model and runtime so that applications that were built using the 1.0 version of the product will work with the new release of the product. However, as we incorporate newer technologies and evolve the platform to address additional requirements, we have had to make updates to the programming model and tooling which may require you to make minor updates to your application. The official
WebSphere sMash Documentation page and the
WebSphere sMash discussion forums are excellent resources for additional information.
Who are affected by this update ?
Anyone who has built applications using WebSphere sMash 1.0 and wish to move these applications up to WebSphere sMash 1.1 should review the contents of this article to understand what might need to be changed.
Specifics to consider while migrating
Repository update
The modules for WebSphere sMash 1.0 is located at
http://www.projectzero.org/sMash/1.0.x/repo, while the modules for WebSphere sMash 1.1 are located at
http://www.projectzero.org/sMash/1.1.x/repo. Since the WebSphere sMash 1.0 CLI uses the 1.0 repository by default, it is recommended that you download the WebSphere sMash 1.1 cli and use that for upgrading sMash 1.0 applications.
After setting up the CLI using the
download instructions, execute the following command at the root of your sMash 1.0 applications.
zero update
Version updates
The version of most of the WebSphere sMash modules have been updated. The default version of the modules matches the sMash release and is 1.1.0.xxxxx. For the most part, this should be transparent to your existing applications since we use a range from 1.0.0.0 to 2.0.0.0 in the default application templates. For instance a WebSphere sMash 1.0 application might have the following dependencies in config/ivy.xml
<dependencies>
<dependency name="derby" org="org.apache.derby" rev="10.3+"/>
<dependency name="derbyclient" org="org.apache.derby" rev="10.3+"/>
<dependency name="zero.dojo" org="zero" rev="[1.0.0.0, 2.0.0.0["/>
<dependency name="zero.php" org="zero" rev="[1.0.0.0, 2.0.0.0["/>
</dependencies>
Since the version of the sMash module dependencies have a range from 1.0.0.0 up to 2.0.0.0 (not inclusive), the application dependencies, on a zero update, will resolve to the sMash 1.1 modules (version 1.1.x.xxxxx) , if the sMash 1.1 CLI is used. If you have changed any of these dependencies to be fixed to a specific version of the sMash modules, you may have to update the dependencies in the ivy.xml of your application to include the correct versions of the modules.
Note that the sMash 1.1 repository does not contain sMash 1.0 modules with the exception of dojo and zero.dojo as mentioned in the next section. So, if your application needs to depend on a sMash 1.0 module, we would suggest that you do not upgrade to sMash 1.1 till you can update that dependency.
Additional information on changing CLI can be found at
http://www.projectzero.org/zero/silverstone/latest/docs/zero.devguide.doc/zero.cli.tasks/CliTasks.html#changing_cli.
Dojo Toolkit updates
WebSphere sMash 1.1 includes both Dojo 1.1 and Dojo 1.2. This will allow applications that currently work with Dojo 1.1 to continue to work with out having to rework the application to use Dojo 1.2. This also means that there are two versions of the dojo and zero.dojo modules in the WebSphere sMash 1.1 repository corresponding to dojo versions 1.1 and 1.2.
| Dojo Version | dojo module (ivy version) | zero.dojo module (ivy version) |
| 1.1 | dojo (1.1) | zero.dojo (1.0.x.xxxxx) |
| 1.2 | dojo (1.2) | zero.dojo (1.1.x.xxxxx) |
Use zero.dojo 1.0.x for Dojo 1.1 and the corresponding Zero widgets. For example:
<dependency org="zero" name="zero.dojo" rev="[1.0.0.0, 1.1.0.0["/>
Use zero.dojo 1.1.x for Dojo 1.2 and corresponding Zero widgets:
<dependency org="zero" name="zero.dojo" rev="[1.1.0.0, 1.2.0.0["/>
It is preferrable to use the
zero.dojo dependency rather than the
dojo dependency directly in your applications, since it help somewhat with compatibility problems and provides access to sMash specific widgets.
Global Context Updates
Several changes were made to the default zone handlers.
Pass by value rather than Pass by reference
Persistent zones are now pass by value. A thread excuting zget ("/zonePrefix/key") obtains a
copy of the object that resides at "key" with the following consequences.
- Modifications to the object are not persisted until a zput ("zonePrefix/key") is executed.
- . Multiple thread need to synchronize using locks if they wish to access the same key and esure that zput is executed before the lock is released. zpost ("zone#lock", "uri") should be used for synchronization.
Locking support no longer available in non persistent zones
Locking support has been removed from non-persistent zones.(From /tmp & /config zones) If concurrent access is desired to these zones, facilities provided by the language should be used.
For example, in java/groovy it is possible to synchronize on a well known object in the global context.
for example we can insert an object into the config zone thru zero.config.
/config/myLockObject1 = {
}
This places en empty hashmap in the config zone.
This can be used as follows by re-entrant code.
def l1 = zget ("/config/myLockObject1")
synchronized (l1) {
}
PHP accessors removed
The PHP Global Context accessors such as
get(),
put(),
post(),
delete(),
contains(),
list() etc., have been removed in favor of _zget(),
zput(),
zpost(),
zdelete(),
zcontains(),
zlist() etc.
| Global Context accessor removed | replaced by |
| get() | zget() |
| put() | zput() |
| post() | zpost() |
| delete() | zdelete() |
| cond_get() | Removed, use zget() instead |
|---|
| list_keys() | zlist() |
| dump() | zdump() |
| contains() | zcontains() |
Samples update
If you have created applications based on the 1.0.x samples, especially if they have been created using the zero create linkto command, these applications may have to be recreated. The updates to samples are summarized in the table below.
| Sample module name in sMash 1.0 | New Sample module name | Comments |
| books.demo | zero.books.demo | |
| employee.demo | zero.employee.demo | |
| employee.resource.demo | Removed | ZRM function is demostrated by zero.suggest.demo |
|---|
| employee.resource.openajax.demo | Removed | This sample was used by zero.openajax.demo to simulate a third-party application. We now use zero.employee.demo for this purpose |
|---|
| openajax.demo | zero.openajax.demo | |
| openid.demo | zero.openid.demo | |
| phpemployee.demo | zero.phpemployee.demo | |
| zero.assemble.flow.demo | zero.flow.demo | |
| officemonitor | zero.officemonitor.demo | This change was also effected in sMash 1.0.0.3 |
Assemble update
Metadata enhancement for extension activities in Assemble flow
In the flow definition, if the name of Activity input is missing, that input will be treated as same as the input defined in the first activity. E.g. The following two flow snippets are equal.
<sendMail name="sendMail_0"
address="${inputForm_0.client[0]}"
subject="The proposal of your request.">
<input value="Here's the final proposal." />
</sendMail>
<sendMail name="sendMail_0"
address="${inputForm_0.client[0]}"
subject="The proposal of your request.">
<input name="body" value="Here's the final proposal." />
</sendMail>
The following built-in activities will be updated
- <sendMail> : If you want to send the attachment in the email, you need specify the input with name "attachement"
- <XSLT> : If you want to specify the variables used in the XSLT transformation context, you need to specify the input with name "variables "
Changes in file and messaging receivers
This change will impact most applications using
zero.file.receiver or the
zero.messaging.receiver modules.
Previously, both
zero.file.receiver and
zero.messaging.receiver have included a predetermined POST handler to receive notifications from the corresponding kicker. This predetermined POST handlers have been removed to allow greater flexibility when deploying and protecting kicker/receiver combinations, allowing the application to configure the POST handler directly and so determine the endpoint address.
Applications using either the file or messaging receiver components in WebSphere sMash 1.0.0.0 or 1.0.0.1 will need an additional configuration clause when migrating to WebSphere sMash 1.1.
Applications using [b]zero.file.receiver[/b] can replace the previously predefined endpoint using:
/config/handlers += [{
"events" : "POST",
"handler" : "zero.file.receiver.FileReceiver.class",
"conditions" : "/request/path =~ /file/FileReceiver(/.*)?"
}]
Applications using
zero.messaging.receiver can replace the previously predefined endpoint using:
/config/handlers += [{
"events" : "POST",
"handler" : "zero.messaging.receiver.QueueReceiver.class",
"conditions" : "/request/path =~ /messaging/QueueReceiver(/.*)?"
}]
Note that both the file and messaging receivers can now be bound to different paths by simply changing the "conditions" clause in the POST hander and the "receiverURL" property of the associated kicker accordingly.
Security Updates
Deprecated Security Functions
There have been some features of WebSphere sMash's security model that have been superseded by new function. While migration from the deprecated methods is not required, it is strongly suggested to ensure your application is compatible with future versions of the sMash runtime. Complete information on the deprecated functions can be found at
http://www.projectzero.org/zero/silverstone/latest/docs/zero.devguide.doc/zero.core/SecurityDeprecations.html
Tooling updates
Eclipse updates
We have refactored the Eclipse plugin for WebSphere sMash so that it is consistent with the way the sMash CLI works. This means that any applications that were built on sMash 1.0.0.3 or higher and applications that are being ported to sMash 1.1 will be required to use the new plugin.
Uninstall the old plug-in and update sites
To avoid problems with the Eclipse update manager, you should completely remove all traces of the old plugin.
- Uninstall any existing "WebSphere sMash" plug-ins.
- In Eclipse 3.4, go to Help > Software Updates > Installed Software.
- In Eclipse 3.2, go to Help > Software Updates > Manage Configuration.
- After a restart, remove any Update Sites that point to the old Eclipse plug-in. If you don't perform this step, Eclipse 3.4 could force the new plug-in to use the legacy Update Manger, which is not actually needed.
Download and install a CLI
If you do not have a CLI on your system, you will need to install one before the new plug-in will work. You can download the WebSphere sMash 1.1 CLI from:
https://www.projectzero.org/download
After downloading and unzipping the CLI,
- Open a command prompt.
- CD into the directory where the CLI is installed.
- Type 'zero'
This will bootstrap the CLI, which allows the plug-in configuration to run without an initial delay.
Install and configure the new plug-in
It is recommended, although not required, that you start with an empty workspace.
- Install the new plug-in from one of the following update sites:
- After a restart, visit the "WebSphere sMash" preferences page and enter the location of your CLI. Then select a modulegroup from the combo. Press OK.
- You should now be able to create applications, manage your repository, etc.
Users with existing workspaces
Users with existing, non-empty workspaces should do a few things before jumping back into development.
- Delete the following directory if it exists: <workspace directory>\.metadata\.plugins\zero.cli.api\AppRoot\.zero\private\MG
- The new plug-in places different parameters in the "WebSphere sMash Application" launches, so it's in your best interest to delete and recreate the ones you use.
- You may need to update all of your projects. Do this by selecting them, Right Click > WebSphere sMash Tools > Update.
