| // |
| // Licensed under the Apache License, Version 2.0 (the "License"); |
| // you may not use this file except in compliance with the License. |
| // You may obtain a copy of the License at |
| // |
| // http://www.apache.org/licenses/LICENSE-2.0 |
| // |
| // Unless required by applicable law or agreed to in writing, software |
| // distributed under the License is distributed on an "AS IS" BASIS, |
| // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| // See the License for the specific language governing permissions and |
| // limitations under the License. |
| // |
| |
| == Update Notes (from 2.x to 3.x) |
| |
| This section is dedicated to users of previous Apache Karaf version. |
| |
| === Distributions |
| |
| The Apache Karaf distributions content has changed. |
| |
| On Apache Karaf 2.x, we provide: |
| |
| * tar.gz archive dedicated for Unix platforms |
| * zip archive dedicated for Windows platforms |
| |
| Now, Apache Karaf 3.x still provide tar.gz and zip archives, but the content is the same. |
| Especially, the two archives contains a `bin` folder with both Unix scripts and Windows bat scripts. |
| |
| === Commands |
| |
| Most of the console commands have been renamed and dispatched in scopes between Apache Karaf 2.x and Apache Karaf 3.x. |
| |
| The purpose is to standardize the naming convention, and use more "logic" scope (especially for subshell). |
| |
| The following table shows the difference between the "old" commands and the "new" ones (if changed). |
| |
| |=== |
| |Apache Karaf 2.x |Apache Karaf 3.x |
| |
| |admin:change-opts |
| |instance:opts-change |
| |
| |admin:change-rmi-registry-port |
| |instance:rmi-registry-port-change |
| |
| |admin:change-rmi-server-port |
| |instance:rmi-server-port-change |
| |
| |admin:change-ssh-port |
| |instance:ssh-port-change |
| |
| |admin:clone |
| |instance:clone |
| |
| |admin:connect |
| |instance:connect |
| |
| |admin:create |
| |instance:create |
| |
| |admin:destroy |
| |instance:destroy |
| |
| |admin:list |
| |instance:list |
| |
| |admin:rename |
| |instance:rename |
| |
| |admin:start |
| |instance:start |
| |
| |admin:status |
| |instance:status |
| |
| |admin:stop |
| |instance:stop |
| |
| |dev:create-dump |
| |dev:dump-create |
| |
| |features:add-url |
| |feature:repo-add |
| |
| |features:chooseurl |
| |feature:repo-add |
| |
| |features:info |
| |feature:info |
| |
| |features:install |
| |feature:install |
| |
| |features:listVersions |
| |feature:version-list |
| |
| |features:list |
| |feature:list |
| |
| |features:listRepositories |
| |feature:repo-list |
| |
| |features:listUrl |
| |feature:repo-list |
| |
| |features:refreshUrl |
| |feature:repo-refresh |
| |
| |features:removeRepository |
| |feature:repo-remove |
| |
| |features:removeUrl |
| |feature:repo-remove |
| |
| |features:uninstall |
| |feature:uninstall |
| |
| |jaas:pending |
| |jaas:pending-list |
| |
| |jaas:realms |
| |jaas:realm-list |
| |
| |jaas:users |
| |jaas:user-list |
| |
| |jaas:manage |
| |jaas:realm-manage |
| |
| |jaas:roleadd |
| |jaas:role-add |
| |
| |jaas:roledel |
| |jaas:role-delete |
| |
| |jaas:useradd |
| |jaas:user-add |
| |
| |jaas:userdel |
| |jaas:user-delete |
| |
| |config:propappend |
| |config:property-append |
| |
| |config:propdel |
| |config:property-delete |
| |
| |config:proplist |
| |config:property-list |
| |
| |config:propset |
| |config:property-set |
| |
| |dev:dynamic-import |
| |bundle:dynamic-import |
| |
| |dev:framework |
| |system:framework |
| |
| |dev:print-stack-traces |
| |shell:stack-traces-print |
| |
| |dev:restart |
| |system:shutdown |
| |
| |dev:show-tree |
| |bundle:tree-show |
| |
| |dev:system-property |
| |system:property |
| |
| |dev:wait-for-service |
| |service:wait |
| |
| |dev:watch |
| |bundle:watch |
| |
| |log:display-exception |
| |log:exception-display |
| |
| |obr:addUrl |
| |obr:url-add |
| |
| |obr:listUrl |
| |obr:url-list |
| |
| |obr:refreshUrl |
| |obr:url-refresh |
| |
| |obr:removeUrl |
| |obr:url-remove |
| |
| |osgi:bundle-level |
| |bundle:start-level |
| |
| |osgi:classes |
| |bundle:classes |
| |
| |osgi:find-class |
| |bundle:find-class |
| |
| |osgi:headers |
| |bundle:headers |
| |
| |osgi:info |
| |bundle:info |
| |
| |osgi:install |
| |bundle:install |
| |
| |osgi:bundle-services |
| |bundle:services |
| |
| |osgi:list |
| |bundle:list |
| |
| |osgi:ls |
| |service:list |
| |
| |osgi:name |
| |system:name |
| |
| |osgi:refresh |
| |bundle:refresh |
| |
| |osgi:resolve |
| |bundle:resolve |
| |
| |osgi:restart |
| |bundle:restart |
| |
| |osgi:shutdown |
| |system:shutdown |
| |
| |osgi:start |
| |bundle:start |
| |
| |osgi:start-level |
| |bundle:start-level |
| |
| |osgi:stop |
| |bundle:stop |
| |
| |osgi:uninstall |
| |bundle:uninstall |
| |
| |osgi:update |
| |bundle:update |
| |
| |osgi:version |
| |system:version |
| |
| |packages:exports |
| |package:exports |
| |
| |packages:imports |
| |package:imports |
| |=== |
| |
| We encourage the users to use the `--help` option to check the name and type of arguments and options. |
| |
| In term of development, the previously shell anotations provided by the `org.apache.felix.gogo.commands*` package (`@Command`, `@Argument`, etc) |
| are now deprecated. Apache Karaf 3.0.0 still supports these annotations, but we encourage the users to upgrade to the new package `org.apache.karaf.shell.commands`. |
| |
| |=== |
| |Shell annotation |Apache Karaf 2.x |Apache Karaf 3.x |
| |
| |`@Argument` |
| |`org.apache.felix.gogo.commands.Argument` |
| |`org.apache.karaf.shell.commands.Argument` |
| |
| |`@Command` |
| |`org.apache.felix.gogo.commands.Command` |
| |`org.apache.karaf.shell.commands.Command` |
| |
| |`@CompleterValues` |
| |`org.apache.felix.gogo.commands.CompleterValues` |
| |`org.apache.karaf.shell.commands.CompleterValues` |
| |
| |`@Option` |
| |`org.apache.felix.gogo.commands.Option` |
| |`org.apache.karaf.shell.commands.Option` |
| |
| |`@SubShell` |
| |`org.apache.felix.gogo.commands.SubShell` |
| |`org.apache.karaf.shell.commands.SubShell` |
| |=== |
| |
| |=== |
| |Class name |Apache Karaf 2.x |Apache Karaf 3.x |
| |
| |Action |
| |`org.apache.felix.gogo.commands.Action` |
| |`org.apache.karaf.shell.commands.Action` |
| |
| |CommandException |
| |`org.apache.felix.gogo.commands.CommandException` |
| |`org.apache.karaf.shell.commands.CommandException` |
| |
| |AbstractCommand |
| |`org.apache.felix.gogo.commands.basic.AbstractCommand` |
| |`org.apache.karaf.shell.commands.basic.AbstractCommand` |
| |=== |
| |
| === JMX MBeans |
| |
| Like the console commands, the JMX MBeans object names have been renamed and the operations haven been dispatched in |
| new MBeans. |
| |
| The following table shows the correspondence between the "old" MBeans object names and the "new" ones. |
| |
| |=== |
| |Apache Karaf 2.x |Apache Karaf 3.x |
| |
| |`org.apache.karaf:type=bundles,name=*` |
| |`org.apache.karaf:type=bundle,name=*` |
| |
| |`org.apache.karaf:type=config,name=*` |
| |`org.apache.karaf:type=config,name=*` |
| |
| |`org.apache.karaf:type=dev,name=*` |
| |`org.apache.karaf:type=system,name=*` |
| |
| |`org;apache.karaf:type=log,name=*` |
| |`org.apache.karaf:type=log,name=*` |
| |
| |`org.apache.karaf:type=obr,name=*` |
| |`org.apache.karaf:type=obr,name=*` |
| |
| |`org.apache.karaf:type=packages,name=*` |
| |`org.apache.karaf:type=package,name=*` |
| |
| |`org.apache.karaf:type=services,name=*` |
| |`org.apache.karaf:type=service,name=*` |
| |
| |`org.apache.karaf:type=system,name=*` |
| |`org.apache.karaf:type=system,name=*` |
| |
| |`org.apache.karaf:type=web,name=*` |
| |`org.apache.karaf:type=web,name=*` |
| |=== |
| |
| === Features |
| |
| The Apache Karaf "core" features repository XML URL have changed: |
| |
| |=== |
| |Apache Karaf 2.x | Apache Karaf 3.x |
| |
| |`mvn:org.apache.karaf.assemblies.features/standard/2.3.x/xml/features` |
| |`mvn:org.apache.karaf.features/standard/3.0.x/xml/features` |
| |
| |`mvn:org.apache.karaf.assemblies.features/enterprise/2.3.x/xml/features` |
| |`mvn:org.apache.karaf.features/enterprise/3.0.x/xml/features` |
| |=== |
| |
| The Spring features have been isolated in a dedicated features repository (`mvn:org.apache.karaf.features/spring/3.0.x/xml/features`). |
| |
| === Namespaces |
| |
| Apache Karaf 3.x brings updated version of the namespaces: |
| |
| * Supported features namespaces: |
| ** `karaf-features-1.0.0.xsd` |
| ** `karaf-features-1.1.0.xsd` |
| ** `karaf-features-1.2.0.xsd` |
| * Supported jaas namespaces: |
| ** `karaf-jaas-1.0.0.xsd` |
| ** `karaf-jaas-1.1.0.xsd` |
| * Supported shell namespaces: |
| ** `karaf-shell-1.0.0.xsd` |
| ** `karaf-shell-1.1.0.xsd` |
| |
| === Maven plugin |
| |
| The previous `features-maven-plugin` and `cmdhelp-maven-plugin` Maven plugins have been gathered in one main Maven |
| plugin: `karaf-maven-plugin`. |
| |
| The goals have changed as follow: |
| |
| |=== |
| |Apache Karaf 2.x Maven plugins |Apache Karaf Maven plugin (3.x) |
| |
| |`features:add-features-to-repo` |
| |`karaf:features-add-to-repository` |
| |
| |`features:create-kar` |
| |`karaf:features-create-kar` |
| |
| |`features:generate-features-file` |
| |`karaf:features-generate-descriptor` |
| |
| |`features:generate-features-xml` |
| |`karaf:features-generate-descriptor` |
| |
| |`features:install-kars` |
| |`karaf:install-kars` |
| |
| |`features:validate-features` |
| |`karaf:features-validate-descriptor` |
| |
| |`cmdhelp:cmdhelp` |
| |`karaf:commands-generate-help` |
| |=== |
| |
| Using the `features:add-features-to-repo` goal, you have now to explicitily define the Apache Karaf features URL (previously, the Apache Karaf features were automatically added). |
| It means that you have to define: |
| |
| ---- |
| <descriptor>mvn:org.apache.karaf.features/standard/3.0.0/xml/features</descriptor> |
| <descriptor>mvn:org.apache.karaf.features/spring/3.0.0/xml/features</descriptor> |
| <descriptor>mvn:org.apache.karaf.features/enterprise/3.0.0/xml/features</descriptor> |
| ---- |
| |
| === Test tooling |
| |
| Apache Karaf 3.0.x is fully supported by OPS4J Pax Exam and "previous" karaf-pax-exam module is no more maintained. |
| |
| === WebContainer |
| |
| WebApplications using the `WebApp-Context` headers in the MANIFEST are no more supported. |
| |
| Apache Karaf now supports only the OSGi standard `Web-ContextPath` header in the MANIFEST. |
| |
| === Update guide |
| |
| We encourage users to stard a fresh Apache Karaf 3.x container more than trying to override the folders from an |
| Apache Karaf 2.x container. |
| |
| Most of the files in the different Apache Karaf folders have changed, and the merge/diff is very large. |
| |
| The future Apache Karaf version will introduce the concept of "Karaf Profiles" to simplify the update process. |
