You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@karaf.apache.org by cs...@apache.org on 2013/10/24 11:36:07 UTC
svn commit: r1535327 - in
/karaf/trunk/manual/src/main/webapp/developers-guide: creating-bundles.conf
developer-commands.conf
Author: cschneider
Date: Thu Oct 24 09:36:06 2013
New Revision: 1535327
URL: http://svn.apache.org/r1535327
Log:
KARAF-1186 Some more fixes to the manual
Modified:
karaf/trunk/manual/src/main/webapp/developers-guide/creating-bundles.conf
karaf/trunk/manual/src/main/webapp/developers-guide/developer-commands.conf
Modified: karaf/trunk/manual/src/main/webapp/developers-guide/creating-bundles.conf
URL: http://svn.apache.org/viewvc/karaf/trunk/manual/src/main/webapp/developers-guide/creating-bundles.conf?rev=1535327&r1=1535326&r2=1535327&view=diff
==============================================================================
--- karaf/trunk/manual/src/main/webapp/developers-guide/creating-bundles.conf (original)
+++ karaf/trunk/manual/src/main/webapp/developers-guide/creating-bundles.conf Thu Oct 24 09:36:06 2013
@@ -1,10 +1,6 @@
-h1. Add extended information to bundles
+h1. Basic bundle creation using the Felix maven-bundle-plugin
-Karaf supports a OSGI-INF/bundle.info file in a bundle.
-
-This file is extended description of the bundle. It supports ASCII character declarations (for adding color, formatting, etc).
-
-For instance, you can define a bundle like this (using Apache Felix maven-bundle-plugin):
+Create a bundle instead of a normal jar by using a pom file like this:
{code:lang=xml}
<?xml version="1.0" encoding="UTF-8"?>
@@ -34,7 +30,7 @@ For instance, you can define a bundle li
<plugin>
<groupId>org.apache.felix</groupId>
<artifactId>maven-bundle-plugin</artifactId>
- <version>2.2.0</version>
+ <version>2.4.0</version>
<extensions>true</extensions>
<configuration>
<instructions>
@@ -49,19 +45,22 @@ For instance, you can define a bundle li
</project>
{code}
-And simply add a src/main/resources/OSGI-INF/bundle.info file containing, for instance:
+h2. Add extended information to bundles
+
+Karaf supports a OSGI-INF/bundle.info file in a bundle. This file is extended description of the bundle. It supports ASCII character declarations (for adding color, formatting, etc) and some simple Wiki syntax.
+
+Simply add a src/main/resources/OSGI-INF/bundle.info file containing, for instance:
{code}
-\u001B[1mSYNOPSIS\u001B[0m
+h1. SYNOPSIS
${project.description}
-\u001B[1mDESCRIPTION\u001B[0m
+h1. DESCRIPTION
Long description of your bundle, including usage, etc.
-\u001B[1mSEE ALSO\u001B[0m
- \u001B[36mhttp://yourside\u001B[0m
- \u001B[36mhttp://yourside/docs\u001B[0m
-
+h1.SEE ALSO
+ [http://yourside\]
+ [http://yourside/docs\]
{code}
You can display this extended information using:
@@ -70,7 +69,19 @@ You can display this extended informatio
root@karaf> bundles:info
{code}
-h1. Creating bundles for third party dependencies
+h2. Wiki Syntax
+
+Karaf supports some simple wiki syntax in bunde info files:
+{code}
+h1., h2., ... : Headings
+* : Enumerations
+[http://....] : links
+{code}
+
+h1. Creating bundles for non OSGi third party dependencies
+
+
+h2. Dynamically wrapping jars
Karaf supports the wrap: protocol execution.
@@ -80,7 +91,7 @@ It allows for directly deploying third p
root@karaf> bundles:install wrap:mvn:commons-lang/commons-lang/2.4
{code}
-You can specify OSGi statements in the wrap URL:
+The wrap protocol creates a bundle dynamically using the bnd. Confiugurations can be added in the wrap URL:
from the shell
{code}
@@ -92,10 +103,12 @@ from features.xml
<bundle>wrap:mvn:commons-lang/commons-lang/2.4$Bundle-SymbolicName=commons-lang&Bundle-Version=2.4</bundle>
{code}
+h2. Statically bundling jars
+
You can also create a wrap bundle for a third party dependency.
This bundle is simply a Maven POM that shades an existing jar and package into a jar bundle.
-For instance, to create an OSGi bundle that wraps Apache Commons Lang, you can simply define the following Maven POM:
+For instance, to create an OSGi bundle that wraps Apache Commons Lang, simply define the following Maven POM:
{code:lang=xml}
<?xml version="1.0" encoding="UTF-8"?>
@@ -175,7 +188,7 @@ For instance, to create an OSGi bundle t
</project>
{code}
-You have now a OSGi bundle for commons-lang that you can deploy directly:
+The resulting OSGi bundle can now be deployed directly:
{code}
root@karaf> bundles:install -s mvn:osgi.commons-lang/osgi.commons-lang/2.4
Modified: karaf/trunk/manual/src/main/webapp/developers-guide/developer-commands.conf
URL: http://svn.apache.org/viewvc/karaf/trunk/manual/src/main/webapp/developers-guide/developer-commands.conf?rev=1535327&r1=1535326&r2=1535327&view=diff
==============================================================================
--- karaf/trunk/manual/src/main/webapp/developers-guide/developer-commands.conf (original)
+++ karaf/trunk/manual/src/main/webapp/developers-guide/developer-commands.conf Thu Oct 24 09:36:06 2013
@@ -1,5 +1,3 @@
-
-
h1. Developer commands
Karaf provides a set of commands specific for developer use.
@@ -19,28 +17,26 @@ Diagnostic dump created.
The previous command generates a zip archive in the KARAF_HOME (by default the name is the generation timestamp).
The following dumps are available in the zip archive:
-* {{features.txt}} provides an overview of the features. It means:
-** the repository list
-** the feature list including bundles URL
+* {{features.txt}} provides an overview of the feature repositoroes, the installed features and bundles
* {{bundles.txt}} provides an overview of the installed bundles, with the ID and the state of each bundle.
-* {{threads.txt}} provides a complete threads dump. It describe all threads running in Karaf and their current state (blocked,
-waiting, etc) with the associated class hierarchy.
+* {{threads.txt}} provides a complete threads dump. It describe all threads running in Karaf and their current state (blocked, waiting, etc) with the associated class hierarchy.
+
These dumps are very helpful when you would like to take a snapshot of a current Karaf running instance.
+
h2. Dynamic import
-The {{dev:dynamic-import}} command allows you to enable or disable the dynamic import of a given bundle:
+The {{bundle:dynamic-import}} command allows you to enable or disable the dynamic import of a given bundle:
{code}
-karaf@root> dev:dynamic-import 41
+karaf@root> bundle:dynamic-import 41
Enabling dynamic imports on bundle org.apache.karaf.shell.config [41]
{code}
h2. OSGi framework
-The {{dev:framework}} command shows you the current OSGi framework in use, and enables debugging of the underlying
-OSGi framework.
+The {{system:framework}} command allows to display the current OSGi framework in use, and enable / disable debugging inside the OSGi framework.
{code}
karaf@root> dev:framework
@@ -59,13 +55,13 @@ Restart Karaf now to disable Felix debug
h2. Print stack trace
-The {{dev:print-stack-traces}} command prints the full stack trace in the console when the execution of a command
+The {{shell:stack-traces-print}} command prints the full stack trace in the console when the execution of a command
throws an exception.
You can enable or disable this behavior by passing true (to enable) or false (to disable) on the command on the fly:
{code}
-karaf@root> dev:print-stack-traces
+karaf@root> shell:stack-traces-print
karaf@root> bundles:start
Error executing command bundles:start: argument ids is required
CommandException: Argument ids is required
@@ -80,17 +76,17 @@ CommandException: Argument ids is requir
at org.apache.felix.gogo.runtime.CommandSessionImpl.execute(CommandSessionImpl.java:79)
at org.apache.karaf.shell.console.jline.Console.run(Console.java:180)
at java.lang.Thread.run(Thread.java:619)
-karaf@root> dev:print-stack-traces false
+karaf@root> shell:stack-traces-print false
karaf@root> bundles:start
Error executing command bundles:start: argument ids is required
{code}
h2. Karaf restart
-The {{dev:restart}} command allows you to restart the running Karaf instance:
+The {{system:shutdown}} -r command allows you to restart the running Karaf instance:
{code}
-karaf@root> dev:restart
+karaf@root> system:shutdown -r
karaf@root>
__ __ ____
/ //_/____ __________ _/ __/
@@ -140,7 +136,7 @@ org.apache.karaf.diagnostic.command [40]
h2. Watching and updating bundle
-The {{dev:watch}} watches and updates bundles. It's especially helpful in development mode.
+The {{bundle:watch}} watches the local maven repository and updates changed bundles. It's especially helpful in development mode.
It allows you to configure a set of URLs that will be monitored. All bundles whose location matches the given URL
will be automatically updated. It avoids needing to manually update the bundles or even copy the bundle to the system folder.
@@ -151,4 +147,4 @@ Note that only Maven based URLs and Mave
karaf@root> dev:watch *
{code}
-it will actually monitor all bundles that have a location matching mvn:* that have '-SNAPSHOT' in their URL.
\ No newline at end of file
+it will actually monitor all bundles that have a location matching mvn:* that have '-SNAPSHOT' in their URL.