[KARAF-3781] Add update notes
Project: http://git-wip-us.apache.org/repos/asf/karaf/repo Commit: http://git-wip-us.apache.org/repos/asf/karaf/commit/3969972f Tree: http://git-wip-us.apache.org/repos/asf/karaf/tree/3969972f Diff: http://git-wip-us.apache.org/repos/asf/karaf/diff/3969972f Branch: refs/heads/master Commit: 3969972fc7cb2fe3ccfc1d608885a46c26f9d061 Parents: 59d69b2 Author: Jean-Baptiste Onofré <[email protected]> Authored: Thu Jun 25 10:31:54 2015 +0200 Committer: Jean-Baptiste Onofré <[email protected]> Committed: Thu Jun 25 10:31:54 2015 +0200 ---------------------------------------------------------------------- README | 2 +- manual/src/main/webapp/overview.conf | 7 +- manual/src/main/webapp/update-notes.conf | 283 ++++++++------------------ 3 files changed, 86 insertions(+), 206 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/karaf/blob/3969972f/README ---------------------------------------------------------------------- diff --git a/README b/README index 57668ed..459e143 100644 --- a/README +++ b/README @@ -18,7 +18,7 @@ Welcome to Apache Karaf ======================= Apache Karaf is a modern and polymorphic container. -It's a lightweight, performent, and enterprise ready container powered by OSGi. +It's a lightweight, powerful, and enterprise ready container powered by OSGi. The container is able to host different kind of applications, OSGi or non OSGi. The following features are included: http://git-wip-us.apache.org/repos/asf/karaf/blob/3969972f/manual/src/main/webapp/overview.conf ---------------------------------------------------------------------- diff --git a/manual/src/main/webapp/overview.conf b/manual/src/main/webapp/overview.conf index 8a5281f..18e80dd 100644 --- a/manual/src/main/webapp/overview.conf +++ b/manual/src/main/webapp/overview.conf @@ -1,8 +1,11 @@ h1. Apache Karaf Overview -Apache Karaf is a OSGi-based runtime which provides a lightweight container onto which various components and applications can be deployed. +Apache Karaf is a modern and polymorphic container. -Apache Karaf uses either Apache Felix Framework or Eclipse Equinox OSGi frameworks, and provide additional features on top of the framework. +It's a lightweight, powerful, and enterprise ready container powered by OSGi. +You can deploy different kind of applications in Karaf, OSGi or non-OSGi. + +Apache Karaf uses either Apache Felix Framework or Eclipse Equinox OSGi frameworks, providing additional features on top of the framework. Apache Karaf can be scaled from a very lightweight container to a fully features enterprise service: it's a very flexible and extensible container, covering all the major needs. http://git-wip-us.apache.org/repos/asf/karaf/blob/3969972f/manual/src/main/webapp/update-notes.conf ---------------------------------------------------------------------- diff --git a/manual/src/main/webapp/update-notes.conf b/manual/src/main/webapp/update-notes.conf index f63cf07..3526079 100644 --- a/manual/src/main/webapp/update-notes.conf +++ b/manual/src/main/webapp/update-notes.conf @@ -1,202 +1,100 @@ -h1. Update Notes (from 2.x to 3.x) +h1. Update Notes (from 3.x to 4.x) This section is dedicated to users of previous Apache Karaf version. -h2. Distributions - -The Apache Karaf distributions content has changed. +NB: for the users upgrading from Karaf 2.x, please see the "Update Notes (from 2.x to 3.x)" in the Karaf 3.x +documentation first. -On Apache Karaf 2.x, we provide: +NB: Karaf 4.x supports Java8. -* tar.gz archive dedicated for Unix platforms -* zip archive dedicated for Windows platforms +h2. Distributions -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. +Apache Karaf 4.x is available as tar.gz and zip archives. The content is the same and works on either Unix or Windows +platforms. +The {{bin}} folder contains both sh and bat scripts. h2. Commands -All 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 correspondence between the "old" commands and the "new" ones. - -|| 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:cancel | jaas:cancel | -| 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:update | jaas:update | -| jaas:useradd | jaas:user-add | -| jaas:userdel | jaas:user-delete | -| shell:alias | shell:alias | -| shell:cat | shell:cat | -| shell:clear | shell:clear | -| shell:date | shell:date | -| shell:each | shell:each | -| shell:echo | shell:echo | -| shell:exec | shell:exec | -| shell:grep | shell:grep | -| shell:head | shell:head | -| shell:history | shell:history | -| shell:if | shell:if | -| shell:info | shell:info | -| shell:java | shell:java | -| shell:logout | shell:logout | -| shell:more | shell:more | -| shell:new | shell:new | -| shell:printf | shell:printf | -| shell:sleep | shell:sleep | -| shell:sort | shell:sort | -| shell:source | shell:source | -| shell:tac | shell:tac | -| shell:tail | shell:tail | -| shell:watch | shell:watch | -| shell:wc | shell:wc | -| config:cancel | config:cancel | -| config:delete | config:delete | -| config:edit | config:edit | -| config:list | config:list | -| config:propappend | config:property-append | -| config:propdel | config:property-delete | -| config:proplist | config:property-list | -| config:propset | config:property-set | -| config:update | config:update | -| 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:clear | log:clear | -| log:display-exception | log:exception-display | -| log:display | log:display | -| log:get | log:get | -| log:tail | log:tail | -| log:set | log:set | -| obr:addUrl | obr:url-add | -| obr:deploy | obr:deploy | -| obr:find | obr:find | -| obr:info | obr:info | -| obr:list | obr:list | -| obr:listUrl | obr:url-list | -| obr:refreshUrl | obr:url-refresh | -| obr:removeUrl | obr:url-remove | -| obr:resolve | obr:resolve | -| obr:source | obr:source | -| obr:start | obr:start | -| 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 | -| ssh:ssh | ssh:ssh | -| ssh:sshd | ssh:sshd | -| web:list | web:list | -| wrapper:install | wrapper:install | +Karaf 4 commands are close to the ones provided in Karaf 3. + +The sub-shell modes are the same (in {{etc/org.apache.karaf.shell.cfg}} or using {{shell:completion}} command). + +However, some minor changes have been introduced and new commands available: + +|| Apache Karaf 3.x || Apache Karaf 3.x || +| | feature:requirement-list | +| | feature:requirement-add | +| | feature:requirement-remove | +| | feature:regions | +| | feature:start | +| | feature:stop | +| | jaas:group-create | +| | jaas:group-add | +| | jaas:group-delete | +| | jaas:group-list | +| | jaas:group-role-add | +| | jaas:group-role-delete | +| | jaas:su | +| | jaas:sudo | +| | shell:edit | +| | shell:env | +| | shell:less | +| | shell:stack-traces-print | +| | shell:threads | +| | shell:while | +| | log:list | +| | bundle:capabilities | +| | bundle:diag | +| | bundle:id | +| | bundle:load-test | +| | bundle:requirements | +| | bundle:resolve | +| | system:name | 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}}. +In term of development, you can still use the blueprint definition as you do in Karaf 2.x & 3.x (with the corresponding annotations). -|| 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 | +However, in Karaf 4.x, you can use DS and new annotations and avoid the usage of a blueprint XML. -|| 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}} | +The new annotations are available: @Service, @Completion, @Parsing, @Reference. It allows you to complete define the command +in the command class directly. -h2. JMX MBeans +To simplify the generation of the code and OSGi headers, Karaf 4.x provides the karaf-services-maven-plugin (in org.apache.karaf.tooling Maven groupId). -Like the console commands, the JMX MBeans object names have been renamed and the operations haven been dispatched in -new MBeans. +Take a look in the developer guide for the command development "new style" details. -The following table shows the correspondence between the "old" MBeans object names and the "new" ones. +h2. Features repositories -|| 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=*}} | +Karaf 4.x provides: -h2. Features +* {{mvn:org.apache.karaf.features/enterprise/4.0.x/xml/features}} +* {{mvn:org.apache.karaf.features/framework/4.0.x/xml/features}} +* {{mvn:org.apache.karaf.features/spring/4.0.x/xml/features}} +* {{mvn:org.apache.karaf.features/standard/4.0.x/xml/features}} +* {{mvn:org.apache.karaf.features/static/4.0.x/xml/features}} -The Apache Karaf "core" features repository XML URL have changed: +h2. Features resolver -|| 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}} | +Apache Karaf 4.x brings a complete new feature resolver. The purpose is to simplify the features installation and +lifecycle. +The new resolver now checks the feature requirements (defined directly in the features XML), and check which bundles +provides the capabilities to satisfy these requirements. +It allows Karaf to automatically install bundles required by features. -The Spring features have been isolated in a dedicated features repository ({{mvn:org.apache.karaf.features/spring/3.0.x/xml/features}}). +For "old style" feature (features XML using namespace from Karaf 2.x or 3.x), this feature is not enabled. +As soon as you use a "new style" feature (with namespace 1.3.0 used by Karaf 4.x), this feature is enabled. h2. Namespaces -Apache Karaf 3.x brings updated version of the namespaces: +Apache Karaf 4.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}} +** {{karaf-features-1.2.1.xsd}} +** {{karaf-features-1.3.0.xsd}} * Supported jaas namespaces: ** {{karaf-jaas-1.0.0.xsd}} ** {{karaf-jaas-1.1.0.xsd}} @@ -206,44 +104,23 @@ Apache Karaf 3.x brings updated version of the namespaces: h2. 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: - -{code} -<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> -{code} - -h2. Test tooling - -Apache Karaf 3.0.x is fully supported by OPS4J Pax Exam and "previous" karaf-pax-exam module is no more maintained. - -h2. WebContainer +A cleanup of the goals provided by {{karaf-maven-plugin}} has been done. -WebApplications using the {{WebApp-Context}} headers in the MANIFEST are no more supported. +Now the provided goals are: -Apache Karaf now supports only the OSGi standard {{Web-ContextPath}} header in the MANIFEST. +* {{karaf:archive}} to create a tar.gz or zip of a Karaf distribution +* {{karaf:assembly}} to create a custom Karaf distribution assembly +* {{karaf:kar}} to create a kar file +* {{karaf:verify}} to verify and validate Karaf features +* {{karaf:features-add-to-repository}} to recursively copy features XML and content into a folder (repository) +* {{karaf:features-export-meta-data}} to extract the metadata from a features XML +* {{karaf:features-generate-descriptor}} to generate a features XML +* {{karaf:commands-generate-help}} to generate help/documentation on the commands h2. 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. +We encourage users to start a fresh Apache Karaf 4.x container. -Most of the files in the different Apache Karaf folders have changed, and the merge/diff is very large. +If you upgrade an existing container, {{lib}} and {{system}} folder have to be updated (just an override copy). -The future Apache Karaf version will introduce the concept of "Karaf Profiles" to simplify the update process. +For the {{etc}} folder, a diff is required as some properties changed and new configurations are available.
