Index: debugging.conf =================================================================== --- debugging.conf (revision 1141702) +++ debugging.conf (working copy) @@ -1,6 +1,6 @@ -h1. Troubleshooting, Debugging,Profiling, and Monitoring +h1. Troubleshooting, Debugging, Profiling, and Monitoring h2. Troubleshooting @@ -25,7 +25,7 @@ h3. Worst Case Scenario -If you end up with a Karaf in a really bad state (i.e. you can not boot it anymore) or you just want to revert to a clean state quickly, you can safely remove the {{data}} directory just in the installation directory. This folder contains transient data and will be recreated if you remove it and relaunch Karaf. +If you end up with a Karaf in a really bad state (i.e. you can not boot it anymore) or you just want to revert to a clean state quickly, you can safely remove the {{data}} directory in the installation directory. This folder contains transient data and will be recreated if removed when you relaunch Karaf. You may also want to remove the files in the {{deploy}} folder to avoid them being automatically installed when Karaf is started the first time. h2. Debugging @@ -64,8 +64,11 @@ Last, inside your IDE, connect to the remote application (the default port to connect to is 5005). -This option works fine when we have to debug a project deployed top of Apache Karaf. Nervertheless, you will be blocked if you would like to debug the server Karaf. In this case, you can change the following parameter suspend=y in the karaf.bat script file. That will cause the JVM to pause just before running main() until you attach a debugger then it will resume the execution. This way you can set -your breakpoints anywhere in the code and you should hit them no matter how early in the startup they are +This option works fine when it is needed to debug a project deployed top of Apache Karaf. Nevertheless, you will be blocked +if you would like to debug the server Karaf. In this case, you can change the following parameter suspend=y in the +karaf.bat script file. That will cause the JVM to pause just before running main() until you attach a debugger then it +will resume the execution. This way you can set your breakpoints anywhere in the code and you should be able to hit them +no matter how early in the startup they are. {code} export DEFAULT_JAVA_DEBUG_OPTS='-Xdebug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5005' @@ -127,10 +130,10 @@ !/images/jconsole_summary.jpg|border=1! -You can manage Karaf features like you are in the shell. For example, you have access to the Admin service MBean, allowing you to create, rename, destroy, change SSH port, etc Karaf instances: +You can manage Karaf features like you are in the shell. For example, you have access to the Admin service MBean, allowing you to create, rename, destroy, change SSH port, etc. Karaf instances: !/images/jconsole_admin.jpg|border=1! -You can also manage Karaf features MBean to list, install, uninstall Karaf features: +You can also manage Karaf features MBean to list, install, and uninstall Karaf features: !/images/jconsole_features.jpg|border=1! \ No newline at end of file Index: karaf-maven-plugin-commands-generate-help.conf =================================================================== --- karaf-maven-plugin-commands-generate-help.conf (revision 1141702) +++ karaf-maven-plugin-commands-generate-help.conf (working copy) @@ -2,10 +2,10 @@ The {{karaf:commands-generate-help}} goal generates documentation containing Karaf commands help. -It looks for command in the current project class loader to find Karaf commands, and generate the help as displayed with the --help option in the Karaf shell console. +It looks for Karaf commands in the current project class loader and generates the help as displayed with the --help option in the Karaf shell console. h3. Example -The example below generates the help for the commands in the current project: +The example below generates help for the commands found in the current project: {pygmentize:xml} @@ -35,6 +35,6 @@ h3. Parameters || Name || Type || Description || -| {{targetFolder}} | {{File}} | The directory where the documentation output files are generated \\ Default value: ${project.build.directory}/docbkx/sources | +| {{targetFolder}} | {{File}} | The directory where the documentation output files are to be generated \\ Default value: ${project.build.directory}/docbkx/sources | | {{format}} | {{String}} | The output format (docbx or conf) of the commands documentation. \\ Default value: docbx | -| {{classLoader}} | {{String}} | The class loader to use to load the commands. \\ Default value: ${project} | +| {{classLoader}} | {{String}} | The class loader to use in loading the commands. \\ Default value: ${project} | Index: security-framework.conf =================================================================== --- security-framework.conf (revision 1141702) +++ security-framework.conf (working copy) @@ -4,7 +4,7 @@ h2. Overview -This feature allow the deployment at runtime of JAAS based configuration for use in various parts of the application. This includes the remote console login, which uses the {{karaf}} realm, but which is configured with a dummy login module by default. These realms can also be used by the NMR, JBI components or the JMX server to authenticate users logging in or sending messages into the bus. +This feature allows runtime deployment of JAAS based configuration for use in various parts of the application. This includes the remote console login, which uses the {{karaf}} realm, but which is configured with a dummy login module by default. These realms can also be used by the NMR, JBI components or the JMX server to authenticate users logging in or sending messages into the bus. In addition to JAAS realms, you can also deploy keystores and truststores to secure the remote shell console, setting up HTTPS connectors or using certificates for WS-Security. @@ -12,7 +12,7 @@ h2. Schema -To override or deploy a new realm, you can use the following XSD which is supported by a Spring namespace handler and can thus be defined in a spring xml configuration file. +To override or deploy a new realm, you can use the following XSD which is supported by a Spring namespace handler and can thus be defined in a Spring xml configuration file. Following is the XML Schema to use when defining Karaf realms: {snippet:url=../jaas/config/src/main/resources/org/apache/karaf/jaas/config/karaf-jaas-1.1.0.xsd|lang=xml|pygmentize=true} @@ -20,7 +20,7 @@ You can find the schema at the following [location|http://karaf.apache.org/xmlns/jaas/v1.1.0]. -Here are two example using this schema: +Here are two examples using this schema: {pygmentize:xml} {pygmentize} -The {{id}} attribute is the blueprint id of the bean, but it will be used by default as the name of the realm if no {{name}} attribute is specified. Additional attributes on the {{config}} elements are a {{rank}}, which is an integer. When the LoginContext looks for a realm for authenticating a given user, the realms registered in the OSGi registry are matched against the required name. If more than one realm is found, the one with the highest rank will be used, thus allowing the override of some realms with new values. The last attribute is {{publish}} which can be set to false to not publish the realm in the OSGi registry, hereby disabling the use of this realm. +The {{id}} attribute is the blueprint id of the bean, but it will be used by default as the name of the realm if no {{name}} attribute is specified. Additional attributes on the {{config}} elements are a {{rank}}, which is an integer. When the LoginContext looks for a realm for authenticating a given user, the realms registered in the OSGi registry are matched against the required name. If more than one realm is found, the one with the highest rank will be used, thus allowing the override of some realms with new values. The last attribute is {{publish}} which can be set to false to not publish the realm in the OSGi registry, thereby disabling the use of this realm. -Each realm can contain one or more module definition. Each module identify a LoginModule and the {{className}} attribute must be set to the class name of the login module to use. Note that this login module must be available from the bundle classloader, so either it has to be defined in the bundle itself, or the needed package needs to be correctly imported. The {{flags}} attribute can take one of four values that are explained on the [JAAS documentation|http://svn.apache.org/repos/asf/karaf/tags/karaf-2.0.0/jaas/boot/src/main/java/org/apache/karaf/jaas/boot/ProxyLoginModule.java]. +Each realm can contain one or more module definitions. Each module identifies a LoginModule and the {{className}} attribute must be set to the class name of the login module to use. Note that this login module must be available from the bundle classloader, so either it has to be defined in the bundle itself, or the needed package needs to be correctly imported. The {{flags}} attribute can take one of four values that are explained on the [JAAS documentation|http://svn.apache.org/repos/asf/karaf/tags/karaf-2.0.0/jaas/boot/src/main/java/org/apache/karaf/jaas/boot/ProxyLoginModule.java]. The content of the {{module}} element is parsed as a properties file and will be used to further configure the login module. Deploying such a code will lead to a [JaasRealm|http://svn.apache.org/repos/asf/karaf/tags/karaf-2.0.0/jaas/config/src/main/java/org/apache/karaf/jaas/config/JaasRealm.java] object in the OSGi registry, which will then be used when using the JAAS login module. h3. Configuration override and use of the {{rank}} attribute -The {{rank}} attribute on the {{config}} element is tied to the ranking of the underlying OSGi service. When the JAAS framework will perform an authentication, it will use the realm name to find a matching JAAS configuration. If multiple configurations are used, the one with the highest {{rank}} attribute will be used. +The {{rank}} attribute on the {{config}} element is tied to the ranking of the underlying OSGi service. When the JAAS framework performs an authentication, it will use the realm name to find a matching JAAS configuration. If multiple configurations are used, the one with the highest {{rank}} attribute will be used. So if you want to override the default security configuration in Karaf (which is used by the ssh shell, web console and JMX layer), you need to deploy a JAAS configuration with the name {{name="karaf"}} and {{rank="1"}}. {pygmentize:xml} @@ -84,21 +84,21 @@ Due to constraints in the JAAS specification, one class has to be available for all bundles. This class is called [ProxyLoginModule|http://svn.apache.org/repos/asf/karaf/tags/karaf-2.0.0/jaas/boot/src/main/java/org/apache/karaf/jaas/boot/ProxyLoginModule.java] and is a LoginModule that acts as a proxy for an OSGi defines LoginModule. If you plan to integrate this feature into another OSGi runtime, this class must be made available from the system classloader and the related package be part of the boot delegation classpath (or be deployed as a fragment attached to the system bundle). -The xml schema defined above allow the use of a simple xml (leveraging spring xml extensibility) to configure and register a JAAS configuration for a given realm. This configuration will be made available into the OSGi registry as a [JaasRealm|http://svn.apache.org/repos/asf/karaf/tags/karaf-2.0.0/jaas/config/src/main/java/org/apache/karaf/jaas/config/JaasRealm.java] and the OSGi specific Configuration will look for such services. Then the proxy login module will be able to use the information provided by the realm to actually load the class from the bundle containing the real login module. +The xml schema defined above allows the use of a simple xml (leveraging spring xml extensibility) to configure and register a JAAS configuration for a given realm. This configuration will be made available into the OSGi registry as a [JaasRealm|http://svn.apache.org/repos/asf/karaf/tags/karaf-2.0.0/jaas/config/src/main/java/org/apache/karaf/jaas/config/JaasRealm.java] and the OSGi specific Configuration will look for such services. Then the proxy login module will be able to use the information provided by the realm to actually load the class from the bundle containing the real login module. h2. Available realms -Karaf comes with several login modules that can be used to integrate into your environment. +Karaf comes with several login modules to handle authentication needs for your environment. h3. PropertiesLoginModule -This login module is the one configured by default. It uses a properties text file to load the users, passwords and roles from. +This login module is the one configured by default. It uses a properties text file to load the users, passwords and roles. || Name || Description | | {{users}} | location of the properties file | This file uses the [properties file format|http://download.oracle.com/javase/6/docs/api/java/util/Properties.html#load(java.io.Reader)]. -The format of the properties are as follows, each line defining a user, its password and the associated roles: +The format of the properties is as follows, with each line defining a user, its password and associated roles: {code} user=password[,role][,role]... {code} @@ -123,7 +123,7 @@ h3. JDBCLoginModule -The JDBCLoginModule uses a database to load the users, passwords and roles from, provided a data source _(normal or XA)_. The data source and the queries for password and role retrieval are configurable, with the use of the following parameters. +The JDBCLoginModule uses a database to load the users, passwords and roles from a provided data source _(normal or XA)_. The data source and the queries for password and role retrieval are configurable using the following parameters. || Name || Description || | {{datasource}} | The datasource as on OSGi ldap filter or as JDNI name| @@ -133,7 +133,7 @@ +Passing a data source as an OSGi ldap filter+ -To use an OSGi ldap filter, the prefix osgi: needs to be provided. See the example below: +To use an OSGi ldap filter, the prefix osgi: needs to be provided, as shown below: {pygmentize:xml} @@ -148,7 +148,7 @@ +Passing a data source as a JNDI name+ -To use an JNDI name, the prefix jndi: needs to be provided. The example below assumes the use of aries jndi to expose services via JNDI. +To use an JNDI name, the prefix jndi: needs to be provided. The example below assumes the use of Aries JNDI to expose services via JNDI. {pygmentize:xml} @@ -163,7 +163,7 @@ h3. LDAPLoginModule -The LDAPLoginModule uses a LDAP to load the users and roles, bind the users on the LDAP to check passwords. +The LDAPLoginModule uses LDAP to load the users and roles and bind the users on the LDAP to check passwords. The LDAPLoginModule supports the following parameters: @@ -206,7 +206,7 @@ {pygmentize} -If you want to use an SSL connection, the following configuration can be used as an example: +If you wish to use an SSL connection, the following configuration can be used as an example: {pygmentize:xml} @@ -273,7 +273,7 @@ h3. Jasypt -Karaf default installation comes with a simple encryption service which usually fullfill simple needs. However, in some cases, you may want to install the [Jasypt|http://www.jasypt.org/] library which gives you stronger encryption algorithm and more control over it. +Karaf default installation comes with a simple encryption service which usually fulfills simple needs. However, in some cases, you may need to install the [Jasypt|http://www.jasypt.org/] library which provides stronger encryption algorithms and more control over them. To install the Jasypt library, the easiest way is to install the available feature: {code} @@ -312,7 +312,7 @@ h2. Role discovery policies -The JAAS specification does not provide means to distinguish between User and Role Principals, without referring to the specification classes. In order to provide means to the application developer to decouple the application from Karaf JAAS implementation role policies have been created. +The JAAS specification does not provide means to distinguish between User and Role Principals without referring to the specification classes. In order to provide means to the application developer to decouple the application from Karaf JAAS implementation role policies have been created. A role policy is a convention that can be adopted by the application in order to identify Roles, without depending from the implementation. Each role policy can be cofigured by setting a "role.policy" and "role.discriminator" property to the login module configuration. Currently, Karaf provides two policies that can be applied to all Karaf Login Modules. @@ -320,7 +320,7 @@ # Grouped Roles +Prefixed Roles+ -When the prefixed role policy is used the login module applies a configurable prefix _(property role.discriminator)_ to the role, so that the application can identify the roles principals by its prefix. Example: +When the prefixed role policy is used the login module applies a configurable prefix _(property role.discriminator)_ to the role, so that the application can identify the role's principals by its prefix. Example: {pygmentize:xml} Index: karaf-maven-plugin-features-generate-descriptor.conf =================================================================== --- karaf-maven-plugin-features-generate-descriptor.conf (revision 1141702) +++ karaf-maven-plugin-features-generate-descriptor.conf (working copy) @@ -2,10 +2,10 @@ The {{karaf:features-generate-descriptor}} goal generates a features XML file for every bundle listed in the project's dependencies. In order to satisfy the required imports in these bundles, the plugin will add bundles: - bundles provided by Apache Karaf -- a list of bundles +- a explicit list of bundles - bundles discovered in the POM's transitive dependencies -Afterwards, the generated file is attached to the build as an additional build artifact (by default as {{group:artifact:version:xml:features}}) +Afterwards, the generated file will be attached to the build as an additional build artifact (by default as {{group:artifact:version:xml:features}}) h3. Example The example below generates one feature that installs bundle {{mvn:org.apache:bundle1:1.0}} in a features XML file called {{target/features.xml}}. It will find bundle in Apache Karaf ${project.version}, the transitive dependencies for this POM and the bundles listed in {{src/main/resources/bundles.properties}}. Index: writing-tests.conf =================================================================== --- writing-tests.conf (revision 1141702) +++ writing-tests.conf (working copy) @@ -2,7 +2,7 @@ h1. Writing integration tests -We recommend using [PAX Exam|http://wiki.ops4j.org/display/paxexam/Pax+Exam] to write integration tests when developping applications using Karaf. +We recommend using [PAX Exam|http://wiki.ops4j.org/display/paxexam/Pax+Exam] to write integration tests when developing applications using Karaf. Karaf provides an helper library to help writing such integration tests. {pygmentize:java} @@ -17,7 +17,7 @@ } {pygmentize} -If you need to provision a few features in addition to the default karaf environment, you can do so by adding the following code: +If you need to provision a few features in addition to the default Karaf environment, you can do so by adding the following code: {pygmentize:java} scanFeatures( Index: karaf-maven-plugin.conf =================================================================== --- karaf-maven-plugin.conf (revision 1141702) +++ karaf-maven-plugin.conf (working copy) @@ -2,9 +2,9 @@ The Karaf maven plugin allows you: - * to manipulate Karaf features: validate a features descriptor, add features bundle into a repository, create a KAR archive from a features descriptor, etc. - * to manipulate Karaf commands help: it generates help from Karaf commands - * to manipulate Karaf instance and create distribution + * to work with Karaf features: validate a features descriptor, add features bundle into a repository, create a KAR archive from a features descriptor, etc. + * to create Karaf commands help: it generates help from Karaf commands + * to modify Karaf instances and create distributions h2. Features goals @@ -19,7 +19,7 @@ h2. Commands goals -The {{karaf-maven-plugin}} is able to generate a documentation for Karaf commands: +The {{karaf-maven-plugin}} is able to generate documentation for Karaf commands: || Goal || Description || | {{[karaf:commands-generate-help|karaf-maven-plugin-commands-generate-help]}} | Generates help for Karaf commands. | Index: developer-commands.conf =================================================================== --- developer-commands.conf (revision 1141702) +++ developer-commands.conf (working copy) @@ -2,14 +2,14 @@ h1. Developer commands -Karaf provides a set of commands dedicated to the developer. +Karaf provides a set of commands specific for developer use. -It allows you to get detailed information about the Karaf instance and the applications running into. +They allow for getting detailed detailed information about the Karaf instance and the applications running in them. h2. Diagnostic dump command -Karaf provides a {{dev:create-dump}} command which creates dump containing diagnostic information. The dumps could be -packaged in a zip archive or directly into a given directory. +Karaf provides a {{dev:create-dump}} command which creates a dump files containing diagnostic information. The dumps can be +packaged in a zip archive (default) or directly into a given directory. {code} karaf@root> dev:create-dump @@ -39,7 +39,7 @@ h2. OSGi framework -The {{dev:framework}} command shows you the current OSGi framework in use, and enable debug on the OSGi framework. +The {{dev:framework}} command shows you the current OSGi framework in use, and enables debugging of the underlying OSGi framework. {code} karaf@root> dev:framework @@ -108,8 +108,7 @@ h2. Bundle tree -The {{dev:show-tree}} command show the tree of bundles based on the wiring information. You give the bundle ID and the -command will display a tree of bundles used with the bundle ID: +The {{dev:show-tree}} command shows the bundle dependency tree based on the wiring information of a given single bundle ID. {code} karaf@root> dev:show-tree 40 @@ -137,14 +136,14 @@ +- org.apache.karaf.diagnostic.core [23] {code} -h2. Watch and update bundle +h2. Watching and updating bundle -The {{dev:watch}} watches and updates bundle. It's especially helpful in development mode. +The {{dev:watch}} watches and updates bundles. It's especially helpful in development mode. -It allows you to configure a set of URLs that will be monitored. All bundles location matching the given URL will be -automatically updated. It avoids to manually update the bundles or even copy the bundle to the system folder. +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. This avoids needing to manually update the bundles or even copy the bundles to the system folder. -Note that only maven based URLs and maven SNAPSHOTs will actually be updated automtically, so if you do: +Note that only Maven based URLs and Maven SNAPSHOTs will actually be updated automatically, so if you do: {code} karaf@root> dev:watch * Index: branding-console.conf =================================================================== --- branding-console.conf (revision 1141702) +++ branding-console.conf (working copy) @@ -2,18 +2,17 @@ h1. Branding the Console -This chapter will guide you how to brand the Karaf console. +This chapter will show you how to customize the user interface of the Karaf console, making +changes such as a new welcome message and console prompt. This is what we refer to as "branding" Karaf. -By branding, it means that you can define your own welcome message and console prompt. - h2. Create your branding bundle -At startup, Karaf is looking for a bundle which export {{org.apache.karaf.branding}} package containing a {{branding.properties}} +At startup, Karaf is looking for a bundle which exports the {{org.apache.karaf.branding}} package containing a {{branding.properties}} file. -So you need to create a very simply bundle just containing a {{org/apache/karaf/branding/branding.properties}} file. +So you need to create a very simple bundle containing just a {{org/apache/karaf/branding/branding.properties}} file. -The Maven POM of your branding bundle should looks like: +The Maven POM of your branding bundle should look like this: {code:lang=xml} @@ -52,7 +51,7 @@ {code} -Now, add a {{src/main/resources/org/apache/karaf/branding/branding.properties}} looking like: +Now, add a {{src/main/resources/org/apache/karaf/branding/branding.properties}} similar to: {{code}} welcome = \ @@ -74,17 +73,17 @@ As you can see, the {{branding.properties}} contains two properties: * welcome is the welcome message displayed when you start Karaf. * prompt is the string used to display the console prompt. This string supports variables: -** ${USER}} defines the user name of the prompt. NB: up to know, it's hard coded to "karaf". However you can define -your own static user name. +** ${USER}} defines the user name of the prompt. Caveat -- the user name is presently static and hardcoded to "karaf", +however you can override here with your own static user name. ** ${{APPLICATION}} defines the Karaf instance name. -As you can see, both strings support ASCII escaped format. For instance \u001B[1m switch the foreground in bold and \u001B[0m -switch back to normal. +As you can see, both strings support ASCII escaped format. For instance \u001B[1m switches the foreground to bold and \u001B[0m +switches it back to normal. -Some prompt examples follow: +Some examples of customized prompts: {code} -# Define a user with fanzy colors +# Define a user with fancy colors prompt = \u001B[36mmy-karaf-user\u001B[0m\u001B[1m@\u001B[0m\u001B[34m${APPLICATION}\u001B[0m> {code} Index: extending-console.conf =================================================================== --- extending-console.conf (revision 1141702) +++ extending-console.conf (working copy) @@ -2,13 +2,14 @@ h1. Extending the console -This chapter will guide you through the steps needed to extend the console and create a new shell. We will leverage Maven, Blueprint and OSGi, so you will need some knowledge of those products. +This chapter will guide you through the steps needed to extend the console and create a new shell. +We will leverage Maven, Blueprint and OSGi, so you will need some knowledge of those products. You may also find some information about the console at [http://felix.apache.org/site/rfc-147-overview.html]. h2. Create the project using maven -We first need to create the project using maven. Let's leverage maven archetypes for that. +We first need to create a project using Maven. Let's leverage Maven archetypes for that. h3. Command line @@ -91,9 +92,9 @@ {pygmentize} -h2. Configuring for Java 5 +h2. Configuring for Java 6 -We are using annotations to define commands, so we need to ensure maven will actually use JDK 1.5 to compile the jar. +We are using annotations to define commands, so we need to ensure Maven will actually use JDK 1.6 to compile the jar. Just add the following snippet after the {{dependencies}} section. {pygmentize:xml} @@ -103,8 +104,8 @@ org.apache.maven.plugins maven-compiler-plugin - 1.5 - 1.5 + 1.6 + 1.6 @@ -113,7 +114,7 @@ h2. Loading the project in your IDE -We can use maven to generate the needed files for your IDE: +We can use Maven to generate the needed files for your IDE: Inside the project, run the following command {code} @@ -204,7 +205,7 @@ h1. Command completer -A completer allow you to automatically complete a command argument using . A completer is simply a bean which is injected to a command. +A completer allows you to automatically complete a command argument using . A completer is simply a bean which is injected to a command. Of course to be able to complete it, the command should require an argument. @@ -253,16 +254,16 @@ public class SimpleCompleter implements Completer { /** - * @param buffer it's the beginning string typed by the user - * @param cursor it's the position of the cursor + * @param buffer the beginning string typed by the user + * @param cursor the position of the cursor * @param candidates the list of completions proposed to the user */ public int complete(String buffer, int cursor, List candidates) { - StringsCompleter delegate = new StringsCompleter(); - delegate.getStrings().add("one"); - delegate.getStrings().add("two"); - delegate.getStrings().add("three"); - return delegate.complete(buffer, cursor, candidates); + StringsCompleter delegate = new StringsCompleter(); + delegate.getStrings().add("one"); + delegate.getStrings().add("two"); + delegate.getStrings().add("three"); + return delegate.complete(buffer, cursor, candidates); } } Index: creating-bundles.conf =================================================================== --- creating-bundles.conf (revision 1141702) +++ creating-bundles.conf (working copy) @@ -2,7 +2,7 @@ Karaf supports a OSGI-INF/bundle.info file in a bundle. -This file is extended description of the bundle. It supports ASCII character (to color, formatting, etc). +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): @@ -49,7 +49,7 @@ {code} -And simply add src/main/resources/OSGI-INF/bundle.info file containing, for instance: +And simply add a src/main/resources/OSGI-INF/bundle.info file containing, for instance: {code} \u001B[1mSYNOPSIS\u001B[0m @@ -72,24 +72,24 @@ h1. Creating bundles for third party dependencies -Karaf support the wrap: protocol execution. +Karaf supports the wrap: protocol execution. -It allows you to directly deploy third party dependency, like Apache Commons Lang: +It allows for directly deploying third party dependencies, like Apache Commons Lang: {code} root@karaf> osgi:install wrap:mvn:commons-lang/commons-lang/2.4 {code} -You can specify OSGi statements on the wrap URL: +You can specify OSGi statements in the wrap URL: {code} root@karaf> osgi:install wrap:mvn:commons-lang/commons-lang/2.4,Bundle-SymbolicName=commons-lang&Bundle-Version=2.4 {code} -Anyway, you can create a wrap bundle for a third party dependencies. -This bundle is simply a Maven POM that shade an existing jar and package into a jar bundle. +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 to wrap Apache Commons Lang, you can simply define the following Maven POM: +For instance, to create an OSGi bundle that wraps Apache Commons Lang, you can simply define the following Maven POM: {code:lang=xml} @@ -169,11 +169,11 @@ {code} -You have now a OSGi bundle for commons-lang that you can deploy directory: +You have now a OSGi bundle for commons-lang that you can deploy directly: {code} root@karaf> osgi:install -s mvn:osgi.commons-lang/osgi.commons-lang/2.4 {code} -Some more infos available at [http://gnodet.blogspot.com/2008/09/id-like-to-talk-bit-about-third-party.html], [http://blog.springsource.com/2008/02/18/creating-osgi-bundles/] and [http://felix.apache.org/site/apache-felix-maven-bundle-plugin-bnd.html]. +Some more information is available at [http://gnodet.blogspot.com/2008/09/id-like-to-talk-bit-about-third-party.html], [http://blog.springsource.com/2008/02/18/creating-osgi-bundles/] and [http://felix.apache.org/site/apache-felix-maven-bundle-plugin-bnd.html]. Index: custom-distribution.conf =================================================================== --- custom-distribution.conf (revision 1141702) +++ custom-distribution.conf (working copy) @@ -2,20 +2,20 @@ h1. Custom distributions -As Karaf is an OSGi container, it's heavily used as the kernel of applications and middlewares. +As Karaf is an OSGi container, it's heavily used as an application and middleware kernel. -You could require to construct your own Karaf distribution matching your requirements. +You may wish to construct your own Karaf distribution preconfigured to your requirements. This custom distribution could contain: -- configuration files that you want to change by default (in the etc folder) +- branding to change the Karaf console look-and-feel +- configuration files (in the etc folder) altered to your requirements - pre-packaged artifacts in the deploy folder -- pre-populated system repository (containing your own bundle and features descriptor) +- a pre-populated system repository (containing your own bundle and features descriptor) - renamed or specific scripts in the bin folder -- branding -- your documentation files +- system documentation files h2. Maven assembly -Basically a Karaf custom distribution is: +Basically a Karaf custom distribution involves: 1. Uncompressing a standard Karaf distribution in a given directory. 2. Populating the system repo with your features. 3. Populating the lib directory with your branding or other system bundle jar files. @@ -36,7 +36,7 @@ My Unix Custom Karaf Distribution - 2.1.3 + 2.2.1 @@ -172,16 +172,16 @@ {code} -The Maven POM will download the Karaf standard distribution and prepares resources to be processed by the Maven assembly plugin. +The Maven POM will download the Karaf standard distribution and prepare resources to be processed by the Maven assembly plugin. Your Maven project structure should look like: * pom.xml: the previous POM file * src/main/descriptors/bin.xml: the assembly maven plugin descriptor (see below) -* src/main/filtered-resources: contains all files where some maven properties should be replaced/filtered. Typically, it contains the features descriptor and configuration files. -* src/main/distribution: contains all raw files which will be copied into your custom distribution. +* src/main/filtered-resources: contains all resource files that have Maven property values to be filtered/replaced. Typically, this will include features descriptor and configuration files. +* src/main/distribution: contains all raw files which will be copied as-is into your custom distribution. -For instance, {{src/main/filtered-resources}} could contains: +For instance, {{src/main/filtered-resources}} could contain: * {{my-features.xml}} where maven properties will be replaced * {{etc/org.apache.karaf.features.cfg}} file containing your my-features descriptor: {code} @@ -196,7 +196,7 @@ featuresBoot=config,ssh,management,my-feature {code} -The {{src/main/distribution}} contain all your custom Karaf configuration files and script, as, for examples: +The {{src/main/distribution}} contains all your custom Karaf configuration files and scripts, as, for examples: * etc/org.ops4j.pax.logging.cfg {code} @@ -249,7 +249,7 @@ # # Default repository where bundles will be loaded from before using -# other maven repositories. For the full maven configuration, see the +# other maven repositories. For the full Maven configuration, see the # org.ops4j.pax.url.mvn.cfg file. # karaf.default.repository=system @@ -299,7 +299,7 @@ com.sun.jndi.ldap {code} -Now, we can "assemble" our custom distribution using the Maven assembly plugin. The Maven assembly plugin uses an assembly descriptor in the {{src/main/descriptors/bin.xml}}: +Now, we can "assemble" our custom distribution using the Maven assembly plugin. The Maven assembly plugin uses an assembly descriptor, configured in POM above to be {{src/main/descriptors/bin.xml}}: {code} @@ -393,7 +393,7 @@ {code} -To build you custom Karaf distribution, just do: +To build your custom Karaf distribution, just run: {code} mvn install Index: connect-console.conf =================================================================== --- connect-console.conf (revision 1141702) +++ connect-console.conf (working copy) @@ -2,7 +2,7 @@ h1. Programmatically connect to the console -A connection to Karaf console can also be done programmatically. +A connection to the Karaf console can also be done programmatically. The following code is a simplified version of the code from the client library. {pygmentize:java}