svn commit: r1383358 - /karaf/trunk/manual/src/main/webapp/users-guide/migration.conf

[cs...@apache.org]

Author: cschneider
Date: Tue Sep 11 11:28:36 2012
New Revision: 1383358

URL: http://svn.apache.org/viewvc?rev=1383358&view=rev
Log:
KARAF-1186 First stab at migration notes

Added:
    karaf/trunk/manual/src/main/webapp/users-guide/migration.conf

Added: karaf/trunk/manual/src/main/webapp/users-guide/migration.conf
URL: http://svn.apache.org/viewvc/karaf/trunk/manual/src/main/webapp/users-guide/migration.conf?rev=1383358&view=auto
==============================================================================
--- karaf/trunk/manual/src/main/webapp/users-guide/migration.conf (added)
+++ karaf/trunk/manual/src/main/webapp/users-guide/migration.conf Tue Sep 11 11:28:36 2012
@@ -0,0 +1,62 @@
+h1. Migration from Karaf 2.x to 3.x
+
+This section shows the necessary changes you have to consider when upgrading karaf.
+
+h2. Updating an existing instance
+
+
+
+h2. Changes in command names
+
+In general the command names now have the scheme <object in singular>:<command on object>.
+For cases when one scope cares for more than one object type like feature:* that cares for features and feature repositories the sheme is partly: <scope>:<object-command>.
+The following table shows side by side the old and new command names.
+
+|| Name 2.x || Name 3.x ||
+| features:add-url | feature:repo-add |
+| features:chooseurl | feature:repo-add |
+| features:chooseurl | feature:repo-add |
+| features:listrepositories | feature:repo-list |
+| features:listurl | feature:repo-list |
+| features:listversions | feature:version-list |
+| features:refreshurl | feature:repo-add |
+| features:removerepository | feature:repo-remove |
+| features:removeurl | feature:repo-remove |
+| features:* | feature:* |
+| osgi:* | bundle:* |
+| dev:dynamic-import | bundle:dynamic-import |
+| dev:framework | system:framework |
+| dev:print-stack-traces | shell:print-stack-traces |
+| dev:restart | system:shutdown -r |
+| dev:show-tree | bundle:tree-show |
+| dev:watch | bundle:watch |
+| admin:* | instance:* |
+| config: | config: |
+| jaas: | jaas: |
+
+h2. Changes in servlet API version
+
+Karaf 3 includes an implementation of the servlet API version 3. This results in the package javax.servlet.api to be exported in version 3 instead of version 2.5. So default imports of this package with version range [2.5,3) will fail now.
+As the servlet API 3 is compatible with servlet API 2.5 you should change your imports to [2.5,4). When using the maven bundle plugin you can do this by using:
+
+{code}
+<Import-Package>*,javax.servlet*;version="[2.5,4)"</Import-Package>
+{code}
+
+h2. Changes in MBeans
+
+For Karaf 3 we did a major refactoring of the module and package structure of Karaf. So almost all mbean interfaces moved to a new package. So if you use the Java interface to access an mbean you will most likely have to change that.
+
+Like the commands the bean types have bean renamed to the singular form:
+
+|| Type Karaf 2.x || Type Karaf 3.x ||
+| admin | instance |
+| bundles | bundle |
+| features | feature |
+| packages | package |
+| services | service |
+
+Besides the type in the objectname a lot of the operations / attributes changed. 
+
+h2. Considerations when migrating a custom karaf distribution
+