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.