Heads up: Package restructuring

at 2006-11-17 in Announcements, Homepage by friebe (0 comments)

When RFC #0084: "Package cleanup" is implemented, lots of packages will change. After you update to the newest version some of your sourcecode will no longer work.

This article shows you how to fix the issues raised by this change.

Brief overview

The webservices API
If you use any of the webservice-related packages (org.json, xml.xmlrpc, xml.soap, xml.wddx, xml.uddi) you will get errors that the classes can no longer be found. This is because all the webservice APIs were united into one new top-level package called "webservices" (org.json becomes webservices.json, xml.soap becomes webservices.soap, ... and so on).
The unittest API
The util.profiling.unittest package was made top-level, thus the new name is simply unittest.
GUI API
The package gui.gtk was moved to the ports/classes directory and renamed to org.gnome.
More...
The "Functionality" section of RFC #0084 lists everything all details.

Note: The classnames inside the packages have not changed!.

Solutions

For those packages moved to port/classes/ without changes, it is as simple as adding that directory to your include path.
In those cases where packages where renamed inside skeleton, replacing any occurrences of these packages' names by their corresponding new names will make the class loading errors disappear.
For the deprecated packages (xml.xp, io.cca, util.adt, util.registry, text.apidoc, net.planet-xp) you can either decide to migrate to new APIs or to download the BC XARs from http://xp-framework.net/downloads/rfc0084/ and add them to your include path.

Upgrade advisor
This RFC contains a command line script which will generate a report of your files and what needs to be changed in them. You can find this script in your XP checkout's directory trunk/rfc/contrib/rfc0084/migrate or download it from here. This script can be run at any time - though we suggest you do it before you update to the restructured XP skeleton

.

Change to the migrate directory and type $ php report.php to see the script's usage.

This is an abbreviated example of a report it will generate:

The command used here was php report.php ~/devel/xp/trunk/xp/projects/ -O ~/rfc-0084.schlund-projects-report.html -r html.

Colorcodes used in reports:

Blue lines
These can be migrated automatically.
Orange lines
These can be migrated automatically but require you to put ports/classes in your include path
Red lines
Indicate problems where automatic migration will fail. You will have to check each one of these and perform manual steps to resolve the problems encountered.

In case nothing migrateable can be found the report script will print "Nothing to be migrated here". In this case, you're lucky, RFC #0084 will not break your application(s)

Migration script
The migration script (same directory as the report script) is intended to be run after RFC #0084 has been implemented.

Change to the migrate directory and type $ php migrate.php to see the script's usage. It's basically the same as the report-script except that this script will actually change your files.

Note: If you're using a version control sytem like CVS or SVN we suggest you let this script run on a clean checkout (vs. your working copy). It will be much easier to undo any changes!.

Start the migration by typing php migrate.php /path/to/migrate > migrate.log (by redirecting output to a file you will be able to keep a complete record of actions). The script will go through the directory recursively and apply changes directly into the files it finds a migration rule for.

Sample output:

===> Migrating /usr/home/thekid/devel/webtools/irc/soap/
/usr/home/thekid/devel/webtools/irc/soap/bin/soap.php: [
  xml.soap => [
    0 => Rule applied(success w/ 1 changes, "")
  ]
]
/usr/home/thekid/devel/webtools/irc/soap/rpcrouter/index.php: [
  xml.soap => [
    0 => Rule applied(success w/ 1 changes, "")
  ]
]

===> Done

After the migration is done, your sourcecode should work as expected again (unless, of course, you're using deprecated APIs).

In my case, devel/webtools/ is a CVS checkout, so I can see the changes by typing cvs diff.

You can subscribe to the XP framework's news by using RSS syndication.

Heads up: Package restructuring

Subscribe

Categories

Related