http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/main/webapp/developers-guide/branding.conf ---------------------------------------------------------------------- diff --git a/manual/src/main/webapp/developers-guide/branding.conf b/manual/src/main/webapp/developers-guide/branding.conf deleted file mode 100644 index c0f16aa..0000000 --- a/manual/src/main/webapp/developers-guide/branding.conf +++ /dev/null @@ -1,222 +0,0 @@ -h1. Branding - -h2. Console - -You can "brand" the Apache Karaf console. - -By branding, it means that you can define your own: - -* the welcome message (motd or Message Of The Day) displayed when you start the console -* the prompt displayed to the users - -There are 2 ways of branding the Karaf console: (1) adding a branding.properties file to etc, and (2) creating a branding bundle. - -h2. Adding a branding.properties file to etc - -Create a {{etc/branding.properties}} file similar to: - -{{code}} -welcome = \ -\u001B[36m __ __ ____ \u001B[0m\r\n\ -\u001B[36m / //_/____ __________ _/ __/ \u001B[0m\r\n\ -\u001B[36m / ,< / __ `/ ___/ __ `/ /_ \u001B[0m\r\n\ -\u001B[36m / /| |/ /_/ / / / /_/ / __/ \u001B[0m\r\n\ -\u001B[36m /_/ |_|\\__,_/_/ \\__,_/_/ \u001B[0m\r\n\ -\r\n\ -\u001B[1m Apache Karaf\u001B[0m (4.0.0)\r\n\ -\r\n\ -Hit '\u001B[1m<tab>\u001B[0m' for a list of available commands\r\n\ - and '\u001B[1m[cmd] --help\u001B[0m' for help on a specific command.\r\n\ -Hit '\u001B[1m<ctrl-d>\u001B[0m' or '\u001B[1mosgi:shutdown\u001B[0m' to shutdown Karaf.\r\n - -prompt = \u001B[1m${USER}@${APPLICATION}\u001B[0m> -{{code}} - -Start Karaf and you will see your branded Karaf console. - -h2. Branding bundle - -At startup, Apache Karaf is looking for a bundle which exports the {{org.apache.karaf.branding}} package, containing -a {{branding.properties}} file. - -Basically, a branding bundle is a very simple bundle, just containing a {{org/apache/karaf/branding/branding.properties}} -file. - -It's easy to create such branding bundle using Apache Maven. - -The following {{pom.xml}} creates a branding bundle: - -{code:lang=xml} -<?xml version="1.0" encoding="UTF-8"?> -<project xmlns="http://maven.apache.org/POM/4.0.0"; xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd";> - - <modelVersion>4.0.0</modelVersion> - - <groupId>your.group.id</groupId> - <artifactId>your.branding.artifact.id</artifactId> - <version>1.0-SNAPSHOT</version> - <packaging>bundle</packaging> - <name>Your Branding Bundle Name</name> - - <build> - <plugins> - <plugin> - <groupId>org.apache.felix</groupId> - <artifactId>maven-bundle-plugin</artifactId> - <version>2.4.0</version> - <extensions>true</extensions> - <configuration> - <instructions> - <Bundle-SymbolicName>${project.artifactId}</bundle-SymbolicName> - <Import-Package>*</Import-Package> - <Private-Package>!*</Private-Package> - <Export-Package> - org.apache.karaf.branding - </Export-Package> - <Spring-Context>*;public-context:=false</Spring-Context> - </instructions> - </configuration> - </plugin> - </plugins> - </build> - -</project> -{code} - -You can put your {{branding.properties}} file in the project resources ({{src/main/resources/org/apache/karaf/branding/branding.properties}}): - -{code} -welcome = This is my Karaf brand\r\n -prompt = Hey ${USER}> -{code} - -For instance, the default Apache Karaf branding properties file contains: - -{code} -welcome = \ -\u001B[36m __ __ ____ \u001B[0m\r\n\ -\u001B[36m / //_/____ __________ _/ __/ \u001B[0m\r\n\ -\u001B[36m / ,< / __ `/ ___/ __ `/ /_ \u001B[0m\r\n\ -\u001B[36m / /| |/ /_/ / / / /_/ / __/ \u001B[0m\r\n\ -\u001B[36m /_/ |_|\\__,_/_/ \\__,_/_/ \u001B[0m\r\n\ -\r\n\ -\u001B[1m Apache Karaf\u001B[0m (${project.version})\r\n\ -\r\n\ -Hit '\u001B[1m<tab>\u001B[0m' for a list of available commands\r\n\ - and '\u001B[1m[cmd] --help\u001B[0m' for help on a specific command.\r\n\ -Hit '\u001B[1m<ctrl-d>\u001B[0m' or type '\u001B[1msystem:shutdown\u001B[0m' or '\u001B[1mlogout\u001B[0m' to shutdown Karaf.\r\n -{code} - -As you can see, the {{branding.properties}} contains two properties: -* welcome is the welcome message displayed when you start Apache Karaf console. -* prompt is the string used to display the console prompt. This string supports variables: -** ${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 switches the foreground in bold -and \u001B[0m switch back to normal. - -Some examples of customized prompt examples follow: - -{code} -# Define a user with fancy colors -prompt = \u001B[36mmy-karaf-user\u001B[0m\u001B[1m@\u001B[0m\u001B[34m${APPLICATION}\u001B[0m> -{code} - -{code} -# Static sober prompt -prompt = my-user@my-karaf> -{code} - -h2. Installing the branding bundle - -Thanks to the {{pom.xml}}, we can use {{mvn}} to build the branding bundle: -{code} -mvn install -{code} - -You just have to drop the file in the {{lib}} directory: - -{code} -cp branding.jar /opt/apache-karaf-4.0.0/lib/karaf-branding.jar -{code} - -You can now start Apache Karaf to see your branded console. - -h2. WebConsole - -It's also possible to brand the Apache Karaf WebConsole. - -You have to create a bundle, fragment of the Apache Karaf WebConsole. - -This WebConsole branding bundle contains a {{META-INF/webconsole.properties}} containing branding properties: - -{code} -# -# This file contains branding properties to overwrite the default -# branding of the Apache Felix Web Console when deployed in an -# Apache Karaf application. - - -webconsole.brand.name = My Web Console - -webconsole.product.name = My Karaf -webconsole.product.url = http://karaf.apache.org/ -webconsole.product.image = /res/karaf/imgs/logo.png - -webconsole.vendor.name = The Apache Software Foundation -webconsole.vendor.url = http://www.apache.org -webconsole.vendor.image = /res/karaf/imgs/logo.png - -webconsole.favicon = /res/karaf/imgs/favicon.ico -webconsole.stylesheet = /res/karaf/ui/webconsole.css - -{code} - -The bundle also provides the css stylesheet and images defined in this properties file. - -As for console, you can use the following {{pom.xml}} to create the WebConsole branding bundle: - -{code} -<?xml version="1.0" encoding="UTF-8"?> -<project xmlns="http://maven.apache.org/POM/4.0.0"; xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd";> - - <modelVersion>4.0.0</modelVersion> - - <groupId>my.group.id</groupId> - <artifactId>branding</artifactId> - <packaging>bundle</packaging> - - <build> - <plugins> - <plugin> - <groupId>org.apache.felix</groupId> - <artifactId>maven-bundle-plugin</artifactId> - <version>2.4.0</version> - <extensions>true</extensions> - <configuration> - <instructions> - <Bundle-DocURL>http://felix.apache.org/site/apache-karaf.html</Bundle-DocURL> - <Fragment-Host>org.apache.karaf.webconsole.console;bundle-version="[3,4)"</Fragment-Host> - <Export-Package>!*</Export-Package> - <Import-Package> - javax.servlet;version=2.4, - javax.servlet.http;version=2.4, - !org.apache.felix.webconsole*, - org.apache.aries.blueprint, - org.osgi.service.blueprint.container, - org.osgi.service.blueprint.reflect, - * - </Import-Package> - </instructions> - </configuration> - </plugin> - </plugins> - </build> - -</project> -{code} - -With the {{webconsole}} feature installed, you can install this bundle (using {{bundle:install}} or by editing the -{{etc/startup.properties}}), you will see the WebConsole with your branding.
http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/main/webapp/developers-guide/connect.conf ---------------------------------------------------------------------- diff --git a/manual/src/main/webapp/developers-guide/connect.conf b/manual/src/main/webapp/developers-guide/connect.conf deleted file mode 100644 index 5afdf7c..0000000 --- a/manual/src/main/webapp/developers-guide/connect.conf +++ /dev/null @@ -1,82 +0,0 @@ -h1. Programmatically connect - -As described in the users guide, Apache Karaf supports remote access to both the console (by embedding a SSHd server) and -the management layer. - -h2. To the console - -You can write a Apache Karaf remote console client in Java (or other language). - -Accessing to a remote Apache Karaf console means writing a SSH client. This SSH client can be in pure Java or in -another language. - -For instance, the {{bin/client}} script starts a SSH client written in Java. - -The following code is a simple code to create a SSH client: - -{code:lang=java} -import org.apache.sshd.ClientChannel; -import org.apache.sshd.ClientSession; -import org.apache.sshd.SshClient; -import org.apache.sshd.client.future.ConnectFuture; - -public class Main { - - public static void main(String[] args) throws Exception { - String host = "localhost"; - int port = 8101; - String user = "karaf"; - String password = "karaf"; - - SshClient client = null; - try { - client = SshClient.setUpDefaultClient(); - client.start(); - ConnectFuture future = client.connect(host, port); - future.await(); - ClientSession session = future.getSession(); - session.authPassword(user, password); - ClientChannel channel = session.createChannel("shell"); - channel.setIn(System.in); - channel.setOut(System.out); - channel.setErr(System.err); - channel.open(); - channel.waitFor(ClientChannel.CLOSED, 0); - } catch (Throwable t) { - t.printStackTrace(); - System.exit(1); - } finally { - try { - client.stop(); - } catch (Throwable t) { } - } - System.exit(0); - } - -} -{code} - -h2. To the management layer - -The Apache Karaf management layer uses JMX. Apache Karaf embeds a JMX MBeanServer that you can use remotely. - -In order to use the MBeanServer remotely, you have to write a JMX client. - -The following example shows a simple JMX client stopping Apache Karaf remotely via the JMX layer: - -{code:lang=java} -javax.management.*; - -public class Main { - - public static void main(String[] args) throws Exception { - JMXServiceURL url = new JMXServiceURL("service:jmx:rmi:///jndi/rmi://localhost:1099/karaf-root"); - JMXConnector connector = JMXConnectorFactory.connect(url, null); - MBeanServerConnection mbeanServer = connector.getMBeanServerConnection(); - ObjectName systemMBean = new ObjectName("org.apache.karaf:type=system,name=karaf-root"); - mbeanServer.invoke(systemMBean, "halt", null, null); - connector.close(); - } - -} -{code} \ No newline at end of file http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/main/webapp/developers-guide/creating-bundles.conf ---------------------------------------------------------------------- diff --git a/manual/src/main/webapp/developers-guide/creating-bundles.conf b/manual/src/main/webapp/developers-guide/creating-bundles.conf deleted file mode 100644 index da0546c..0000000 --- a/manual/src/main/webapp/developers-guide/creating-bundles.conf +++ /dev/null @@ -1,198 +0,0 @@ -h1. Basic bundle creation using the 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"?> -<project xmlns="http://maven.apache.org/POM/4.0.0"; - xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; - xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd";> - - <modelVersion>4.0.0</modelVersion> - - <groupId>my.groupId</groupId> - <artifactId>my.bundle</artifactId> - <version>1.0-SNAPSHOT</version> - <name>My Bundle</name> - <description>My bundle short description</description> - - <build> - <resources> - <resource> - <directory>${project.basedir}/src/main/resources</directory> - <filtering>true</filtering> - <includes> - <include>**/*</include> - </includes> - </resource> - </resources> - <plugins> - <plugin> - <groupId>org.apache.felix</groupId> - <artifactId>maven-bundle-plugin</artifactId> - <version>2.4.0</version> - <extensions>true</extensions> - <configuration> - <instructions> - <Bundle-SymbolicName>${project.artifactId}</Bundle-SymbolicName> - ... - </instructions> - </configuration> - </plugin> - </plugins> - </build> - -</project> -{code} - -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} -h1. SYNOPSIS - ${project.description} - -h1. DESCRIPTION - Long description of your bundle, including usage, etc. - -h1.SEE ALSO - [http://yourside\] - [http://yourside/docs\] -{code} - -You can display this extended information using: - -{code} -root@karaf> bundles:info -{code} - -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. - -It allows for directly deploying third party dependencies, like Apache Commons Lang: - -{code} -root@karaf> bundles:install wrap:mvn:commons-lang/commons-lang/2.4 -{code} - -The wrap protocol creates a bundle dynamically using the bnd. Confiugurations can be added in the wrap URL: - -from the shell -{code} -root@karaf> bundles:install 'wrap:mvn:commons-lang/commons-lang/2.4$Bundle-SymbolicName=commons-lang&Bundle-Version=2.4' -{code} - -from features.xml -{code} -<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, simply define the following Maven POM: - -{code:lang=xml} -<?xml version="1.0" encoding="UTF-8"?> -<project xmlns="http://maven.apache.org/POM/4.0.0"; - xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; - xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd";> - - <modelVersion>4.0.0</modelVersion> - - <groupId>osgi.commons-lang</groupId> - <artifactId>osgi.commons-lang</artifactId> - <version>2.4</version> - <packaging>bundle</packaging> - <name>commons-lang OSGi Bundle</name> - <description>This OSGi bundle simply wraps commons-lang-2.4.jar artifact.</description> - - <dependencies> - <dependency> - <groupId>commons-lang</groupId> - <artifactId>commons-lang</artifactId> - <version>2.4</version> - <optional>true</optional> - </dependency> - </dependencies> - - <build> - <defaultGoal>install</defaultGoal> - - <plugin> - <groupId>org.apache.maven.plugins</groupId> - <artifactId>maven-shade-plugin</artifactId> - <version>1.1</version> - <executions> - <execution> - <phase>package</phase> - <goals> - <goal>shade</goal> - </goals> - <configuration> - <artifactSet> - <includes> - <include>commons-lang:commons-lang</include> - </includes> - </artifactSet> - <filters> - <filter> - <artifact>commons-lang:commons-lang</artifact> - <excludes> - <exclude>**</exclude> - </excludes> - </filter> - </filters> - <promoteTransitiveDependencies>true</promoteTransitiveDependencies> - <createDependencyReducedPom>true</createDependencyReducedPom> - </configuration> - </execution> - </executions> - </plugin> - <plugin> - <groupId>org.apache.felix</groupId> - <artifactId>maven-bundle-plugin</artifactId> - <version>2.1.0</version> - <extensions>true</extensions> - <configuration> - <instructions> - <Bundle-SymbolicName>${project.artifactId}</Bundle-SymbolicName> - <Export-Package></Export-Package> - <Import-Package></Import-Package> - <_versionpolicy>[$(version;==;$(@)),$(version;+;$(@)))</_versionpolicy> - <_removeheaders>Ignore-Package,Include-Resource,Private-Package,Embed-Dependency</_removeheaders> - </instructions> - <unpackBundle>true</unpackBundle> - </configuration> - </plugin> - </build> - -</project> -{code} - -The resulting OSGi bundle can now be deployed directly: - -{code} -root@karaf> bundles:install -s mvn:osgi.commons-lang/osgi.commons-lang/2.4 -{code} - -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]. - http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/main/webapp/developers-guide/custom-distribution.conf ---------------------------------------------------------------------- diff --git a/manual/src/main/webapp/developers-guide/custom-distribution.conf b/manual/src/main/webapp/developers-guide/custom-distribution.conf deleted file mode 100644 index 7a27b5f..0000000 --- a/manual/src/main/webapp/developers-guide/custom-distribution.conf +++ /dev/null @@ -1,625 +0,0 @@ - - -h1. Custom distributions - -As Karaf is an OSGi container, it's heavily used as as application and middleware kernel. - -You may wish to construct your own Karaf distribution preconfigured to your requirements. -This custom distribution could contain: -- 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 -- a pre-populated system repository (containing your own bundle and features descriptor) -- renamed or specific scripts in the bin folder -- system documentation files - -h2. Maven assembly - -The recommended way to create a Karaf server assembly is to use the karaf-assembly packaging with the karaf-maven-plugin. This assembles a server from the maven dependencies in the project pom. After explanation of the configuration options we present an example. The Karaf project effectively uses this packaging to assemble the official Karaf distributions, but due to maven limitations we have to simulate rather than use the karaf-assembly packaging. - -This packaging creates tar.gz and zip archives containing the assembled server. They are identical except that zip archives don't unpack with appropriate unix file permissions for the scripts. - -h3. Maven dependencies -Maven dependencies in a karaf-assembly project can be feature repositories (classifier "features") or kar archives. Feature repositories are installed in the internal "system" Maven structured repository. Kar archives have their content unpacked on top of the server as well as contained feature repositories installed. - -The Maven scope of a dependency determines whether its feature repository is listed in the features service configuration file etc/org.apache.karaf.features.cfg featuresRepositories property: - -compile (default): All the features in the repository (or for a kar repositories) will be installed into the startup.properties. The feature repo is not listed in the features service configuration file. - -runtime: feature installation is controlled by <startupFeature>, <bootFeature>, and <installedFeature> elements in the karaf-maven-plugin configuration. The feature repo uri is listed in the features service configuration file. - -h3. Plugin configuration - -Control how features are installed using these elements referring to features from installed feature repositories: - -* <startupFeature>foo</startupFeature> This will result in the feature bundles being listed in startup.properties at the appropriate start level and the bundles being copied into the "system" internal repository. You can use feature_name or feature_name/feature_version formats. - -* <bootFeature>bar</bootFeature> This will result in the feature name added to boot-features in the features service configuration file and all the bundles in the feature copied into the "system" internal repository. You can use feature_name or feature_name/feature_version formats. - -* <installedFeature>baz</installedFeature> This will result in all the bundles in the feature being installed in the "system" internal repository. Therefore at runtime the feature may be installed without access to external repositories. You can use feature_name or feature_name/feature_version formats. - -h3. Minimal Distribution Example - -This is the minimal assembly pom changed to use the packaging and annotated - -{code} -<?xml version="1.0" encoding="UTF-8"?> -<project xmlns="http://maven.apache.org/POM/4.0.0"; xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd";> - <modelVersion>4.0.0</modelVersion> - - <parent> -... - </parent> - - <groupId>org.apache.karaf</groupId> - <artifactId>apache-karaf-minimal</artifactId> - <version>${project.version}</version> - <packaging>karaf-assembly</packaging> - <name>Apache Karaf :: Assemblies :: Minimal Distribution</name> - - <dependencies> - <dependency> - <!-- scope is compile so all features (there is only one) are installed into startup.properties and the feature repo itself is not added in etc/org.apache.karaf.features.cfg file --> - <groupId>org.apache.karaf.features</groupId> - <artifactId>framework</artifactId> - <version>${project.version}</version> - <type>kar</type> - </dependency> - <dependency> - <!-- scope is runtime so the feature repo is listed in etc/org.apache.karaf.features.cfg file, and features will installed into the system directory --> - <groupId>org.apache.karaf.features</groupId> - <artifactId>standard</artifactId> - <classifier>features</classifier> - <type>xml</type> - <scope>runtime</scope> - </dependency> - </dependencies> - - <build> - <!-- if you want to include resources in the distribution --> - <resources> - <resource> - <directory>src/main/resources</directory> - <filtering>false</filtering> - <includes> - <include>**/*</include> - </includes> - </resource> - <resource> - <directory>src/main/filtered-resources</directory> - <filtering>true</filtering> - <includes> - <include>**/*</include> - </includes> - </resource> - </resources> - - <plugins> - <!-- if you want to include resources in the distribution --> - <plugin> - <groupId>org.apache.maven.plugins</groupId> - <artifactId>maven-resources-plugin</artifactId> - <version>2.6</version> - <executions> - <execution> - <id>process-resources</id> - <goals> - <goal>resources</goal> - </goals> - </execution> - </executions> - </plugin> - <!-- karaf-maven-plugin will call both assembly and archive goals --> - <plugin> - <groupId>org.apache.karaf.tooling</groupId> - <artifactId>karaf-maven-plugin</artifactId> - <extensions>true</extensions> - <configuration> - <!-- no startupFeatures --> - <bootFeatures> - <feature>standard</feature> - </bootFeatures> - <!-- no installedFeatures --> - </configuration> - </plugin> - </plugins> - </build> -</project> -{code} - -h3. Custom Distribution Example - -It's possible to specify feature versions using the name/version format. - -For instance, to pre-install Spring 4.0.7.RELEASE_1 feature in your custom distribution, you can use the following pom.xml: - -{code} -<?xml version="1.0" encoding="UTF-8"?> -<project xmlns="http://maven.apache.org/POM/4.0.0"; xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd";> - - <modelVersion>4.0.0</modelVersion> - - <groupId>my.custom</groupId> - <artifactId>my.distribution</artifactId> - <version>1.0</version> - <packaging>karaf-assembly</packaging> - - <dependencies> - <dependency> - <!-- scope is compile so all features (there is only one) are installed into startup.properties and the feature repo itself is not added in etc/org.apache.karaf.features.cfg file --> - <groupId>org.apache.karaf.features</groupId> - <artifactId>framework</artifactId> - <version>4.0.0</version> - <type>kar</type> - </dependency> - <dependency> - <!-- scope is runtime so the feature repo is listed in etc/org.apache.karaf.features.cfg file, and features will installed into the system directory if specify in the plugin configuration --> - <groupId>org.apache.karaf.features</groupId> - <artifactId>standard</artifactId> - <classifier>features</classifier> - <type>xml</type> - <scope>runtime</scope> - </dependency> - <dependency> - <!-- scope is runtime so the feature repo is listed in etc/org.apache.karaf.features.cfg file, and features will installed into the system directory if specify in the plugin configuration --> - <groupId>org.apache.karaf.features</groupId> - <artifactId>spring</artifactId> - <classifier>features</classifier> - <type>xml</type> - <scope>runtime</scope> - </dependency> - </dependencies> - - <build> - <!-- if you want to include resources in the distribution --> - <resources> - <resource> - <directory>src/main/resources</directory> - <filtering>false</filtering> - <includes> - <include>**/*</include> - </includes> - </resource> - <resource> - <directory>src/main/filtered-resources</directory> - <filtering>true</filtering> - <includes> - <include>**/*</include> - </includes> - </resource> - </resources> - - <plugins> - <!-- if you want to include resources in the distribution --> - <plugin> - <groupId>org.apache.maven.plugins</groupId> - <artifactId>maven-resources-plugin</artifactId> - <version>2.6</version> - <executions> - <execution> - <id>process-resources</id> - <goals> - <goal>resources</goal> - </goals> - </execution> - </executions> - </plugin> - <plugin> - <groupId>org.apache.karaf.tooling</groupId> - <artifactId>karaf-maven-plugin</artifactId> - <version>4.0.0</version> - <extensions>true</extensions> - <configuration> - <!-- no startupFeatures --> - <bootFeatures> - <feature>minimal</feature> - </bootFeatures> - <installedFeatures> - <feature>wrapper</feature> - <feature>spring/4.0.7.RELEASE_1</feature> - </installedFeatures> - </configuration> - </plugin> - </plugins> - </build> -</project> -{code} - -h2. (deprecated old style) Maven assembly - -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. -4. Overriding the configuration files in the etc folder. - -These tasks could be performed using scripting, or more easily and portable, using Apache Maven and a set of Maven plugins. - -For instance, the Maven POM could look like: - -{code} -<?xml version="1.0" encoding="UTF-8"?> -<project xmlns="http://maven.apache.org/POM/4.0.0"; xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; xsi:schemaLocation="http://maven.apache.org/POM http://maven.apache.org/xsd/maven-4.0.0.xsd";> - - <groupId>my.company</groupId> - <artifactId>mycustom-karaf</artifactId> - <version>1.0</version> - <packaging>pom</packaging> - <name>My Unix Custom Karaf Distribution</name> - - <properties> - <karaf.version>${project.version}</karaf.version> - </properties> - - <dependencies> - <dependency> - <groupId>org.apache.karaf</groupId> - <artifactId>apache-karaf</artifactId> - <version>${karaf.version}</version> - <type>tar.gz</type> - </dependency> - <dependency> - <groupId>org.apache.karaf</groupId> - <artifactId>apache-karaf</artifactId> - <version>${karaf.version}</version> - <type>xml</type> - <classifier>features</classifier> - </dependency> - </dependencies> - - <build> - <resources> - <resource> - <directory>${project.basedir}/src/main/filtered-resources</directory> - <filtering>true</filtering> - <includes> - <include>**/*</include> - </includes> - </resource> - </resources> - <plugins> - <plugin> - <groupId>org.apache.maven.plugins</groupId> - <artifactId>maven-resources-plugin</artifactId> - <executions> - <execution> - <id>filter</id> - <phase>generate-resources</phase> - <goals> - <goal>resources</goal> - </goals> - </execution> - </executions> - </plugin> - <plugin> - <groupId>org.apache.karaf.tooling</groupId> - <artifactId>features-maven-plugin</artifactId> - <version>${karaf.version}</version> - <executions> - <execution> - <id>add-features-to-repo</id> - <phase>generate-resources</phase> - <goals> - <goal>add-features-to-repo</goal> - </goals> - <configuration> - <descriptors> - <descriptor>mvn:org.apache.karaf/apache-karaf/${karaf.version}/xml/features</descriptor> - <descriptor>file:${project.basedir}/target/classes/my-features.xml</descriptor> - </descriptors> - <features> - <feature>my-feature</feature> - </features> - </configuration> - </execution> - </executions> - </plugin> - <plugin> - <groupId>org.apache.maven.plugins</groupId> - <artifactId>maven-dependency-plugin</artifactId> - <executions> - <execution> - <id>copy</id> - <phase>generate-resources</phase> - <goals> - <goal>copy</goal> - </goals> - <configuration> - <!-- Define here the artifacts which should be considered in the assembly --> - <!-- For instance, the branding jar --> - <artifactItems> - <artifactItem> - <groupId>my.groupId</groupId> - <artifactId>my.branding.id</artifactId> - <version>1.0</version> - <outputDirectory>target/dependencies</outputDirectory> - <destFileName>mybranding.jar</destFileName> - </artifactItem> - </artifactItems> - </configuration> - </execution> - <execution> - <!-- Uncompress the standard Karaf distribution --> - <id>unpack</id> - <phase>generate-resources</phase> - <goals> - <goal>unpack</goal> - </goals> - <configuration> - <artifactItems> - <artifactItem> - <groupId>org.apache.karaf</groupId> - <artifactId>apache-karaf</artifactId> - <type>tar.gz</type> - <outputDirectory>target/dependencies</outputDirectory> - </artifactItem> - </artifactItems> - </configuration> - </execution> - </executions> - </plugin> - <plugin> - <groupId>org.apache.maven.plugins</groupId> - <artifactId>maven-assembly-plugin</artifactId> - <executions> - <execution> - <id>bin</id> - <phase>package</phase> - <goals> - <goal>single</goal> - </goals> - <configuration> - <descriptors> - <descriptor>src/main/descriptors/bin.xml</descriptor> - </descriptors> - <appendAssemblyId>false</appendAssemblyId> - <tarLongFileMode>gnu</tarLongFileMode> - </configuration> - </execution> - </executions> - </plugin> - </plugins> - </build> - -</project> -{code} - -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 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 contain: -* {{my-features.xml}} where Maven properties will be replaced -* {{etc/org.apache.karaf.features.cfg}} file containing your my-features descriptor: -{code} -# -# Comma separated list of features repositories to register by default -# -featuresRepositories=mvn:org.apache.karaf/apache-karaf/${karaf.version}/xml/features,mvn:my.groupId/my-features/${project.version}/xml/features - -# -# Comma separated list of features to install at startup -# -featuresBoot=config,ssh,management,my-feature -{code} - -The {{src/main/distribution}} contains all your custom Karaf configuration files and script, as, for examples: - -* etc/org.ops4j.pax.logging.cfg -{code} -# Root logger -log4j.rootLogger=INFO, out, osgi:VmLogAppender -log4j.throwableRenderer=org.apache.log4j.OsgiThrowableRenderer - -# CONSOLE appender not used by default -log4j.appender.stdout=org.apache.log4j.ConsoleAppender -log4j.appender.stdout.layout=org.apache.log4j.PatternLayout -log4j.appender.stdout.layout.ConversionPattern=%d{ABSOLUTE} | %-5.5p | %-16.16t | %-32.32C %4L | %X{bundle.id} - %X{bundle.name} - %X{bundle.version} | %m%n - -# File appender -log4j.appender.out=org.apache.log4j.RollingFileAppender -log4j.appender.out.layout=org.apache.log4j.PatternLayout -log4j.appender.out.layout.ConversionPattern=%d{ABSOLUTE} | %-5.5p | %-16.16t | %-32.32C %4L | %X{bundle.id} - %X{bundle.name} - %X{bundle.version} | %m%n -log4j.appender.out.file=${karaf.home}/log/my-customer-distribution.log -log4j.appender.out.append=true -log4j.appender.out.maxFileSize=1MB -log4j.appender.out.maxBackupIndex=10 - -# Sift appender -log4j.appender.sift=org.apache.log4j.sift.MDCSiftingAppender -log4j.appender.sift.key=bundle.name -log4j.appender.sift.default=my-custom -log4j.appender.sift.appender=org.apache.log4j.FileAppender -log4j.appender.sift.appender.layout=org.apache.log4j.PatternLayout -log4j.appender.sift.appender.layout.ConversionPattern=%d{ABSOLUTE} | %-5.5p | %-16.16t | %-32.32c{1} | %-32.32C %4L | %m%n -log4j.appender.sift.appender.file=${karaf.data}/log/$\\{bundle.name\\}.log -log4j.appender.sift.appender.append=true -{code} -* etc/system.properties -{code} -# -# The properties defined in this file will be made available through system -# properties at the very beginning of the FAS boot process. -# - -# Log level when the pax-logging service is not available -# This level will only be used while the pax-logging service bundle -# is not fully available. -# To change log levels, please refer to the org.ops4j.pax.logging.cfg file -# instead. -org.ops4j.pax.logging.DefaultServiceLog.level=ERROR - -# -# Name of this custom instance. -# -karaf.name=my-custom - -# -# Default repository where bundles will be loaded from before using -# other Maven repositories. For the full Maven configuration, see the -# org.ops4j.pax.url.mvn.cfg file. -# -karaf.default.repository=system - -# -# Location of a shell script that will be run when starting a shell -# session. This script can be used to create aliases and define -# additional commands. -# -karaf.shell.init.script=${karaf.home}/etc/shell.init.script - -# -# Set this empty property to avoid errors when validating xml documents. -# -xml.catalog.files= - -# -# Suppress the bell in the console when hitting backspace to many times -# for example -# -jline.nobell=true - -# -# Default port for the OSGi HTTP Service -# -org.osgi.service.http.port=8181 - -# -# Allow usage of ${custom.home} as an alias for ${karaf.home} -# -custom.home=${karaf.home} -{code} -* etc/users.properties -{code} -admin=admin,admin -{code} -* You can add a {{etc/custom.properties}}, it's a placeholder for any override you may need. For instance: -{code} -karaf.systemBundlesStartLevel=50 -obr.repository.url=http://svn.apache.org/repos/asf/servicemix/smx4/obr-repo/repository.xml -org.osgi.framework.system.packages.extra = \ - org.apache.karaf.branding; \ - com.sun.org.apache.xalan.internal.xsltc.trax; \ - com.sun.org.apache.xerces.internal.dom; \ - com.sun.org.apache.xerces.internal.jaxp; \ - com.sun.org.apache.xerces.internal.xni; \ - 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, configured in POM above to be {{src/main/descriptors/bin.xml}}: - -{code} -<assembly> - - <id>bin</id> - - <formats> - <format>tar.gz</format> - </formats> - - <fileSets> - - <!-- Expanded Karaf Standard Distribution --> - <fileSet> - <directory>target/dependencies/apache-karaf-${karaf.version}</directory> - <outputDirectory>/</outputDirectory> - <excludes> - <exclude>**/demos/**</exclude> - <exclude>bin/**</exclude> - <exclude>etc/system.properties</exclude> - <exclude>etc/users.properties</exclude> - <exclude>etc/org.apache.karaf.features.cfg</exclude> - <exclude>etc/org.ops4j.pax.logging.cfg</exclude> - <exclude>LICENSE</exclude> - <exclude>NOTICE</exclude> - <exclude>README</exclude> - <exclude>RELEASE-NOTES</exclude> - <exclude>karaf-manual*.html</exclude> - <exclude>karaf-manual*.pdf</exclude> - </excludes> - </fileSet> - - <!-- Copy over bin/* separately to get the correct file mode --> - <fileSet> - <directory>target/dependencies/apache-karaf-${karaf.version}</directory> - <outputDirectory>/</outputDirectory> - <includes> - <include>bin/admin</include> - <include>bin/karaf</include> - <include>bin/start</include> - <include>bin/stop</include> - </includes> - <fileMode>0755</fileMode> - </fileSet> - - <!-- Copy over jar files --> - <fileSet> - <directory>target/dependencies</directory> - <includes> - <include>my-custom.jar</include> - </includes> - <outputDirectory>/lib/</outputDirectory> - </fileSet> - - <fileSet> - <directory>src/main/distribution</directory> - <outputDirectory>/</outputDirectory> - <fileMode>0644</fileMode> - </fileSet> - <fileSet> - <directory>target/classes/etc</directory> - <outputDirectory>/etc/</outputDirectory> - <lineEnding>unix</lineEnding> - <fileMode>0644</fileMode> - </fileSet> - - <fileSet> - <directory>target/features-repo</directory> - <outputDirectory>/system</outputDirectory> - </fileSet> - - </fileSets> - - <files> - <file> - <source>${basedir}/target/dependencies/apache-karaf-${karaf.version}/bin/karaf</source> - <outputDirectory>/bin/</outputDirectory> - <destName>my-custom</destName> - <fileMode>0755</fileMode> - <lineEnding>unix</lineEnding> - </file> - <file> - <source>${basedir}/target/classes/features.xml</source> - <outputDirectory>/system/my.groupid/my-features/${project.version}</outputDirectory> - <destName>my-features-${project.version}-features.xml</destName> - <fileMode>0644</fileMode> - <lineEnding>unix</lineEnding> - </file> - </files> - -</assembly> -{code} - -To build your custom Karaf distribution, just run: - -{code} -mvn install -{code} - -You will find your Karaf custom distribution tar.gz in the target directory. - -h2. Roadmap - -A distribution goal is in preparation in the next Karaf - -h2. Custom distribution examples - -* [Apache ServiceMix 4|http://svn.apache.org/repos/asf/servicemix/smx4/features/trunk/assemblies/] -* [Apache ServiceMix NMR|http://svn.apache.org/repos/asf/servicemix/smx4/nmr/trunk/bundle/] -* [BuildProcess BuildEraser|http://buildprocess.svn.sourceforge.net/viewvc/buildprocess/builderaser/trunk/assembly/] http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/main/webapp/developers-guide/debugging.conf ---------------------------------------------------------------------- diff --git a/manual/src/main/webapp/developers-guide/debugging.conf b/manual/src/main/webapp/developers-guide/debugging.conf deleted file mode 100644 index 3661590..0000000 --- a/manual/src/main/webapp/developers-guide/debugging.conf +++ /dev/null @@ -1,162 +0,0 @@ -h1. Troubleshooting, Debugging, Profiling, and Monitoring - -h2. Troubleshooting - -h3. Logging - -Logging is easy to control through the console, with commands grouped under _log_ shell. To learn about the available -logging commands type: - -{code} -karaf@root> log<tab> - -log:display log:display-exception log:get log:set -karaf@root> -{code} - -Typical usage is: - - # Use {{log:set}} to dynamically change the global log level - # Execute the problematic operation - # Use {{log:display}} (or {{log:display-exception}} to display the log - -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 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 - -Usually, the easiest way to debug Karaf or any application deployed onto it is to use remote debugging. -Remote debugging can be easily activated by using the {{debug}} parameter on the command line. - -{noformat} -> bin/karaf debug -{noformat} -or on Windows -{noformat} -> bin\karaf.bat debug -{noformat} - -Another option is to set the {{KARAF_DEBUG}} environment variable to {{TRUE}}. - -This can be done using the following command on Unix systems: -{noformat} -export KARAF_DEBUG=true -{noformat} - -On Windows, use the following command -{noformat} -set KARAF_DEBUG=true -{noformat} - -Then, you can launch Karaf using the usual way: -{noformat} -bin/karaf -{noformat} -or -{noformat} -bin\karaf.bat -{noformat} - -Last, inside your IDE, connect to the remote application (the default port to connect to is 5005). - -This option works fine when it is needed 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. - -{code} -export DEFAULT_JAVA_DEBUG_OPTS='-Xdebug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5005' -{code} - -and on Windows, - -{code} -set DEFAULT_JAVA_DEBUG_OPTS='-Xdebug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5005' -{code} - -h3. Debugging Environment Variables - -||Variable||Description||Default|| -|KARAF_DEBUG|Set to TRUE to enable debugging.| | -|EXTRA_JAVA_OPTS|Java options append to JAVA_OPTS | | -|JAVA_DEBUG_OPTS|Java options to enable debuging.|Calculated based on the OS| -|JAVA_DEBUG_PORT|Port used by the debugger.|5005| - -h2. Profiling - -h3. jVisualVM - -You have to edit the {{etc/config.properties}} configuration file to add the jVisualVM package: - -{code} -org.osgi.framework.bootdelegation=...,org.netbeans.lib.profiler.server -{code} - -Run Karaf from the console, and you should now be able to connect using jVisualVM. - -h3. YourKit - -You need a few steps to be able to profile Karaf using YourKit. - -The first one is to edit the {{etc/config.properties}} configuration file and add the following property: - -{code} -org.osgi.framework.bootdelegation=...,com.yourkit.* -{code} - -Then, set the {{JAVA_OPTS}} environment variable: - -{code} -export JAVA_OPTS='-Xmx512M -agentlib:yjpagent' -{code} - -or, on Windows - -{code} -set JAVA_OPTS='-Xmx512M -agentlib:yjpagent' -{code} - -Run Karaf from the console, and you should now be able to connect using YourKit standalone or from your favorite IDE. - -h2. Monitoring - -Karaf uses JMX for monitoring and management of all Karaf components. - -The JMX connection could be: -* local using the process id - -!/images/jconsole_connect.jpg|border=1! - -* remote using the {{rmiRegistryPort}} property defined in {{etc/org.apache.karaf.management.cfg}} file. - -Using JMX, you can have a clean overview of the running Karaf instance: - -* A overview with graphics displaying the load in terms of thread, heap/GC, etc: - -!/images/jconsole_overview.jpg|border=1! - -* A thread overview: - -!/images/jconsole_threads.jpg|border=1! - -* A memory heap consumption, including "Perform GC" button: - -!/images/jconsole_memory.jpg|border=1! - -* A complete JVM summary, with all number of threads, etc: - -!/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: - -!/images/jconsole_admin.jpg|border=1! - -You can also manage Karaf features MBean to list, install, and uninstall Karaf features: - -!/images/jconsole_features.jpg|border=1! http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/main/webapp/developers-guide/developer-commands.conf ---------------------------------------------------------------------- diff --git a/manual/src/main/webapp/developers-guide/developer-commands.conf b/manual/src/main/webapp/developers-guide/developer-commands.conf deleted file mode 100644 index e442530..0000000 --- a/manual/src/main/webapp/developers-guide/developer-commands.conf +++ /dev/null @@ -1,228 +0,0 @@ -h1. Developer commands - -As you can see in the users guide, Apache Karaf is an enterprise ready OSGi container. - -It's also a container designed to simplify the life for developers and administrators to get details about the -running container. - -h2. Dump - -If you encounter issues like performance degradations, weird behaviour, it could be helpful to have a kind of snapshot -about the current activity of the container. - -The {{dev:dump-create}} command creates a dump file containing: - -* the {{bundles.txt}} file contains the list of all OSGi bundles, with id, symbolic name, version, current status -* the {{features.txt}} file contains the list of all features, including current status -* the {{environment.txt}} file contains details about Apache Karaf, OSGi framework, Operating System, JVM, system - properties, threads count, classes loaded -* the {{memory.txt}} file contains the status of the JVM memory at the dump time -* the {{heapdump.txt}} file contains a memory heap dump, with all objects instances, space usage, etc. -* the {{threads.txt}} file contains a thread dump, with all threads, waiting status, etc. -* the {{log}} folder contains the {{data/log}} folder, with all log files. - -By default, the {{dev:dump-create}} command creates a zip file in the {{KARAF_BASE}} folder, with the timestamp of the -dump creation: - -{code} -karaf@root()> dev:dump-create -Created dump zip: 2015-07-01_171434.zip -{code} - -We can see the file generated in the {{KARAF_BASE}} folder: - -{code} -$ cd /opt/apache-karaf-4.0.0 -$ ls -lh *.zip --rw-rw-r-- 1 user group 17M Jul 1 17:14 2015-07-01_171434.zip -{code} - -You can specify the file name of the zip archive: - -{code} -karaf@root()> dev:dump-create mydump.zip -Diagnostic dump created. -{code} - -Instead of a zip archive, you can create the dump (exploded) in a directory using the {{-d}} ({{--directory}}) option: - -{code} -karaf@root()> dev:dump-create -d /tmp/mydump -Diagnostic dump created. -{code} - -h2. Diagnostic - -It's not always easy for the developers to understand why a bundle is not active. - -It could be because the Activator failed, the Blueprint container start failed, etc. - -The {{bundle:diag}} command gives you details about a bundle is not active: - -{code} -karaf@root()> bundle:diag -Apache ServiceMix :: Bundles :: avro-ipc (81) ---------------------------------------------- -Status: Installed -Unsatisfied Requirements: -[81.0] osgi.wiring.package; (&(osgi.wiring.package=javax.servlet)(version>=2.5.0)(!(version>=3.0.0))) -[81.0] osgi.wiring.package; (&(osgi.wiring.package=javax.servlet.http)(version>=2.5.0)(!(version>=3.0.0))) -[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.apache.avro)(version>=1.7.0)(!(version>=2.0.0))) -[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.apache.avro.data)(version>=1.7.0)(!(version>=2.0.0))) -[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.apache.avro.file)(version>=1.7.0)(!(version>=2.0.0))) -[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.apache.avro.generic)(version>=1.7.0)(!(version>=2.0.0))) -[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.apache.avro.io)(version>=1.7.0)(!(version>=2.0.0))) -[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.apache.avro.reflect)(version>=1.7.0)(!(version>=2.0.0))) -[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.apache.avro.specific)(version>=1.7.0)(!(version>=2.0.0))) -[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.apache.avro.util)(version>=1.7.0)(!(version>=2.0.0))) -[81.0] osgi.wiring.package; (osgi.wiring.package=org.apache.velocity) -[81.0] osgi.wiring.package; (osgi.wiring.package=org.apache.velocity.app) -[81.0] osgi.wiring.package; (osgi.wiring.package=org.apache.velocity.context) -[81.0] osgi.wiring.package; (osgi.wiring.package=org.apache.velocity.exception) -[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.jboss.netty.bootstrap)(version>=3.4.0)(!(version>=4.0.0))) -[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.jboss.netty.buffer)(version>=3.4.0)(!(version>=4.0.0))) -[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.jboss.netty.channel)(version>=3.4.0)(!(version>=4.0.0))) -[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.jboss.netty.channel.group)(version>=3.4.0)(!(version>=4.0.0))) -[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.jboss.netty.channel.socket.nio)(version>=3.4.0)(!(version>=4.0.0))) -[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.jboss.netty.handler.codec.frame)(version>=3.4.0)(!(version>=4.0.0))) -[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.jboss.netty.handler.codec.oneone)(version>=3.4.0)(!(version>=4.0.0))) -[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.jboss.netty.handler.execution)(version>=3.4.0)(!(version>=4.0.0))) -[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.mortbay.jetty)(version>=6.1.0)(!(version>=7.0.0))) -[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.mortbay.jetty.bio)(version>=6.1.0)(!(version>=7.0.0))) -[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.mortbay.jetty.nio)(version>=6.1.0)(!(version>=7.0.0))) -[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.mortbay.jetty.servlet)(version>=6.1.0)(!(version>=7.0.0))) -[81.0] osgi.wiring.package; (&(osgi.wiring.package=org.mortbay.resource)(version>=6.1.0)(!(version>=7.0.0))) -{code} - -h2. Dynamic import - -The {{bundle:dynamic-import}} command allows you to enable or disable the dynamic import of a given bundle: - -{code} -karaf@root()> bundle:dynamic-import 50 -Enabling dynamic imports on bundle org.ops4j.pax.url.wrap [50] -{code} - -The purpose of dynamic import is to allow a bundle to be wired up to packages that may not be knwon about in advance. -When a class is requested, if it cannot be solved via the bundle's existing imports, the dynamic import allows other -bundles to be considered for a wiring import to be added. - -The {{bundle:dynamic-import}} command allows or doesn't allow this behaviour. - -h2. 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()> system:framework -Current OSGi framework is felix -karaf@root()> system:framework -debug -Enabling debug for OSGi framework (felix) -karaf@root()> system:framework -nodebug -Disabling debug for OSGi framework (felix) -{code} - -h2. Stack traces printout - -The {{shell:stack-traces-print}} command prints the full stack trace when the execution of a command -throws an exception. - -You can enable or disable this behaviour by passing true (to enable) or false (to disable) on the command on the fly: - -{code} -karaf@root()> stack-traces-print -Printing of stacktraces set to true -karaf@root()> bundle:start -java.lang.RuntimeException: Access to system bundle 0 denied. You can override with -f - at org.apache.karaf.bundle.command.BundlesCommand.assertNoSystemBundles(BundlesCommand.java:57) - at org.apache.karaf.bundle.command.BundlesCommand.doExecute(BundlesCommand.java:48) - at org.apache.karaf.bundle.command.BundlesCommandWithConfirmation.doExecute(BundlesCommandWithConfirmation.java:41) - at org.apache.karaf.shell.console.AbstractAction.execute(AbstractAction.java:33) - at org.apache.karaf.shell.console.OsgiCommandSupport.execute(OsgiCommandSupport.java:39) - at org.apache.karaf.shell.commands.basic.AbstractCommand.execute(AbstractCommand.java:33) - at sun.reflect.GeneratedMethodAccessor30.invoke(Unknown Source) - at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43) - at java.lang.reflect.Method.invoke(Method.java:601) - at org.apache.aries.proxy.impl.ProxyHandler$1.invoke(ProxyHandler.java:54) - at org.apache.aries.proxy.impl.ProxyHandler.invoke(ProxyHandler.java:119) - at org.apache.karaf.shell.console.commands.$BlueprintCommand14083304.execute(Unknown Source) - at sun.reflect.GeneratedMethodAccessor30.invoke(Unknown Source) - at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43) - at java.lang.reflect.Method.invoke(Method.java:601) - at org.apache.aries.proxy.impl.ProxyHandler$1.invoke(ProxyHandler.java:54) - at org.apache.aries.proxy.impl.ProxyHandler.invoke(ProxyHandler.java:119) - at org.apache.karaf.shell.console.commands.$BlueprintCommand14083304.execute(Unknown Source) - at org.apache.felix.gogo.runtime.CommandProxy.execute(CommandProxy.java:78) - at org.apache.felix.gogo.runtime.Closure.executeCmd(Closure.java:477) - at org.apache.felix.gogo.runtime.Closure.executeStatement(Closure.java:403) - at org.apache.felix.gogo.runtime.Pipe.run(Pipe.java:108) - at org.apache.felix.gogo.runtime.Closure.execute(Closure.java:183) - at org.apache.felix.gogo.runtime.Closure.execute(Closure.java:120) - at org.apache.felix.gogo.runtime.CommandSessionImpl.execute(CommandSessionImpl.java:89) - at org.apache.karaf.shell.console.impl.jline.ConsoleImpl$DelegateSession.execute(ConsoleImpl.java:497) - at org.apache.karaf.shell.console.impl.jline.ConsoleImpl.run(ConsoleImpl.java:198) - at java.lang.Thread.run(Thread.java:722) - at org.apache.karaf.shell.console.impl.jline.ConsoleFactoryService$3.doRun(ConsoleFactoryService.java:118) - at org.apache.karaf.shell.console.impl.jline.ConsoleFactoryService$3$1.run(ConsoleFactoryService.java:109) - at java.security.AccessController.doPrivileged(Native Method) - at org.apache.karaf.jaas.modules.JaasHelper.doAs(JaasHelper.java:47) - at org.apache.karaf.shell.console.impl.jline.ConsoleFactoryService$3.run(ConsoleFactoryService.java:107) -karaf@root()> stack-traces-print false -Printing of stacktraces set to false -karaf@root()> bundle:start -Error executing command: Access to system bundle 0 denied. You can override with -f -{code} - -h2. Bundle tree - -The {{bundle:tree-show}} command shows the bundle dependency tree based on the wiring information of a given single bundle -ID. - -{code} -karaf@root()> bundle:tree-show 40 -Bundle org.ops4j.pax.url.wrap [40] is currently ACTIVE - -org.ops4j.pax.url.wrap [40] -+- org.ops4j.base.util.property [14] -+- org.ops4j.pax.url.commons [49] -| +- org.ops4j.base.util.property [14] -| +- org.ops4j.pax.logging.pax-logging-api [23] -| +- org.ops4j.pax.swissbox.property [31] -| | +- org.ops4j.base.util.property [14] -| | +- org.ops4j.base.lang [41] -| +- org.apache.felix.configadmin [43] -| | +- org.ops4j.pax.logging.pax-logging-api [23] -| +- org.ops4j.base.lang [41] -+- org.ops4j.pax.logging.pax-logging-api [23] -+- org.ops4j.pax.swissbox.bnd [25] -| +- biz.aQute.bndlib [30] -| | +- org.apache.servicemix.bundles.junit [36] -| +- org.ops4j.pax.logging.pax-logging-api [23] -| +- org.ops4j.base.lang [41] -+- org.apache.felix.configadmin [43] -+- org.ops4j.base.net [29] -| +- org.ops4j.base.monitors [37] -| +- org.ops4j.base.lang [41] -+- org.ops4j.base.lang [41] -{code} - -h2. Watch - -The {{bundle:watch}} command enables watching the local Maven repository for updates on bundles. -If the bundle file changes on the Maven repository, Apache Karaf will automatically update the bundle. - -The {{bundle:watch}} allows you to configure a set of URLs to monitore. All bundles 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. - -{warning} -Only Maven based URLs and Maven SNAPSHOTs will actually be updated automatically. -{warning} - -The following command: - -{code} -karaf@root()> bundle:watch * -{code} - -will monitor all bundles that have a location matching mvn:* and '-SNAPSHOT' in their URL. http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/main/webapp/developers-guide/extending.conf ---------------------------------------------------------------------- diff --git a/manual/src/main/webapp/developers-guide/extending.conf b/manual/src/main/webapp/developers-guide/extending.conf deleted file mode 100644 index eb04003..0000000 --- a/manual/src/main/webapp/developers-guide/extending.conf +++ /dev/null @@ -1,340 +0,0 @@ -h1. Extending - -Apache Karaf is a very flexible container that you can extend very easily. - -h2. Console - -In this section, you will see how to extend the console by adding your own command. - -We will leverage Apache Maven to create and build the OSGi bundle. -This OSGi bundle will use Blueprint. We don't cover the details of OSGi bundle and Blueprint, see the specific -sections for details. - -h3. Create the Maven project - -To create the Maven project, we can: - -* use a Maven archetype -* create by hand - -h4. Using archetype - -The Maven Quickstart archetype can create an empty Maven project where you can put your project definition. - -You can directly use: - -{code} -mvn archetype:create \ - -DarchetypeArtifactId=maven-archetype-quickstart \ - -DgroupId=org.apache.karaf.shell.samples \ - -DartifactId=shell-sample-commands \ - -Dversion=1.0-SNAPSHOT -{code} - -It results to a ready to use project, including a {{pom.xml}}. - -You can also use Maven archetype in interactive mode. You will have to answer to some questions used to generate -the project with the {{pom.xml}}: - -{code} -mvn archetype:generate -Choose a number: (1/2/3/4/5/6/7/.../32/33/34/35/36) 15: : 15 -Define value for groupId: : org.apache.karaf.shell.samples -Define value for artifactId: : shell-sample-commands -Define value for version: 1.0-SNAPSHOT: : -Define value for package: : org.apache.karaf.shell.samples -{code} - -h3. By hand - -Alternatively, you can simply create the directory {{shell-sample-commands}} and create the {{pom.xml}} file inside it: - -{code:lang=xml} -<project xmlns="http://maven.apache.org/POM/4.0.0"; xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd";> - - <modelVersion>4.0.0</modelVersion> - - <groupId>org.apache.karaf.shell.samples</groupId> - <artifactId>shell-sample-commands<artifactId> - <packaging>bundle</packaging> - <version>1.0-SNAPSHOT</version> - <name>shell-sample-commmands</name> - - - <dependencies> - <dependency> - <groupId>org.apache.karaf.shell</groupId> - <artifactId>org.apache.karaf.shell.console</artifactId> - <version>${project.version}</version> - </dependency> - <dependency> - <groupId>junit</groupId> - <artifactId>junit</artifactId> - <version>3.8.1</version> - <scope>test</scope> - </dependency> - </dependencies> - - <build> - <plugins> - <plugin> - <groupId>org.apache.felix</groupId> - <artifactId>maven-bundle-plugin</artifactId> - <version>${felix.plugin.version}</version> - <configuration> - <instructions> - <Import-Package> - org.apache.felix.service.command, - org.apache.karaf.shell.commands, - org.apache.karaf.shell.console, - * - </Import-Package> - </instructions> - </configuration> - </plugin> - </plugins> - </build> - -</project> -{code} - -h3. Configuring for Java 6/7 - -We are using annotations to define commands, so we need to ensure Maven will actually use JDK 1.6 or 1.7 to compile the jar. -Just add the following snippet after the {{dependencies}} section. - -{code:lang=xml} -<build> - <plugins> - <plugin> - <groupId>org.apache.maven.plugins</groupId> - <artifactId>maven-compiler-plugin</artifactId> - <configuration> - <target>1.6</target> - <source>1.6</source> - </configuration> - </plugin> - </plugins> -</build> -{code} - -h3. Loading the project in your IDE - -We can use Maven to generate the needed files for your IDE: - -Inside the project, run the following command -{code} -mvn eclipse:eclipse -{code} -or -{code} -mvn idea:idea -{code} - -The project files for your IDE should now be created. Just open the IDE and load the project. - -h3. Creating a basic command class - -We can now create the command class {{HelloShellCommand.java}} - -{code:lang=java} -package org.apache.karaf.shell.samples; - -import org.apache.karaf.shell.api.action.Action; -import org.apache.karaf.shell.api.action.Command; -import org.apache.karaf.shell.api.action.lifecycle.Service; - -@Command(scope = "test", name = "hello", description="Says hello") -@Service -public class HelloShellCommand implements Action { - - @Override - public Object execute() throws Exception { - System.out.println("Executing Hello command"); - return null; - } -} -{code} - -h3. Manifest - -In order for Karaf to find your command, you need to add the {{Karaf-Commands=*}} manifest header. - -This is usually done by modifying the maven bundle plugin configuration -{code:lang=xml} -<plugin> - <groupId>org.apache.felix</groupId> - <artifactId>maven-bundle-plugin</artifactId> - <configuration> - <instructions> - <Karaf-Commands>*</Karaf-Commands> - </instructions> - </configuration> -</plugin> -{code} - -h3. Compile - -Let's try to build the jar. Remove the test classes and sample classes if you used the artifact, then from the command line, run: - -{code} -mvn install -{code} - -The end of the maven output should look like: -{code} -[INFO] ------------------------------------------------------------------------ -[INFO] BUILD SUCCESSFUL -[INFO] ------------------------------------------------------------------------ -{code} - -h3. Test - -Launch Apache Karaf and install your bundle: - -{code} -karaf@root()> bundle:install -s mvn:org.apache.karaf.shell.samples/shell-sample-commands/1.0-SNAPSHOT -{code} - -Let's try running the command: - -{code} -karaf@root()> test:hello -Executing Hello command -{code} - -h3. Command completer - -A completer allows you to automatically complete a command argument using <tab>. 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. - -h3. Command argument - -We add an argument to the HelloCommand: - -{code:lang=java} -package org.apache.karaf.shell.samples; - -import org.apache.karaf.shell.api.action.Action; -import org.apache.karaf.shell.api.action.Argument; -import org.apache.karaf.shell.api.action.Command; -import org.apache.karaf.shell.api.action.Completion; -import org.apache.karaf.shell.api.action.lifecycle.Service; - -@Command(scope = "test", name = "hello", description="Says hello") -@Service -public class HelloShellCommand implements Action { - - @Argument(index = 0, name = "name", description = "The name that sends the greet.", required = true, multiValued = false) - @Completion(SimpleNameCompleter.class) - String name = null; - - @Override - public Object execute() throws Exception { - System.out.println("Hello " + name); - return null; - } -} -{code} - -h3. Completer bean - -A completer is a bean which implements the Completer interface: - -{code:lang=java} -package org.apache.karaf.shell.samples; - -import org.apache.karaf.shell.api.action.lifecycle.Service; -import org.apache.karaf.shell.api.console.CommandLine; -import org.apache.karaf.shell.api.console.Completer; -import org.apache.karaf.shell.api.console.Session; -import org.apache.karaf.shell.support.completers.StringsCompleter; - -/** - * <p> - * A very simple completer. - * </p> - */ -@Service -public class SimpleNameCompleter implements Completer { - - public int complete(Session session, CommandLine commandLine, List<String> candidates) { - StringsCompleter delegate = new StringsCompleter(); - delegate.getStrings().add("Mike"); - delegate.getStrings().add("Eric"); - delegate.getStrings().add("Jenny"); - return delegate.complete(buffer, cursor, candidates); - } - -} -{code} - -h3. Completers for option values - -Quite often your commands will not have just arguments, but also options. You can provide completers for option values. -The snippet below shows the HelloShellCommand with an option to specify what the greet message will be. - -{code:lang=java} -package org.apache.karaf.shell.samples; - -import org.apache.karaf.shell.api.action.Action; -import org.apache.karaf.shell.api.action.Argument; -import org.apache.karaf.shell.api.action.Command; -import org.apache.karaf.shell.api.action.Completion; -import org.apache.karaf.shell.api.action.Option; -import org.apache.karaf.shell.api.action.lifecycle.Service; - -@Command(scope = "test", name = "hello", description="Says hello") -@Service -public class HelloShellCommand implements Action { - - @Argument(index = 0, name = "name", description = "The name that sends the greet.", required = true, multiValued = false) - @Completion(SimpleNameCompleter.class) - String name = null; - - @Option(name = "-g", aliases = "--greet", description = "The configuration pid", required = false, multiValued = false) - @Completion(GreetCompleter.class) - String greet = "Hello; - - @Override - public Object execute() throws Exception { - System.out.println(greet + " " + name); - return null; - } -} -{code} - -h3. Completers with state - -Some times we want to tune the behavior of the completer depending on the commands already executed, in the current shell -or even the rest of the arguments that have been already passed to the command. Such example is the config:set-property -command which will provide auto completion for only for the properties of the pid specified by a previously issued config:edit -command or by the option --pid. - -The Session object provides map like methods for storing key/value pairs and can be used to put/get the state. -The pre-parsed CommandLine objects allows you to check the previous arguments and options on the command line and to fine tune -the behavior of the Completer. -Those two objects are given to the Completer when calling the {{complete}} method. - -h3. Test - -Launch a Karaf instance and run the following command to install the newly created bundle: - -{code} -karaf@root()> bundle:install -s mvn:org.apache.karaf.shell.samples/shell-sample-commands/1.0-SNAPSHOT -{code} - -Let's try running the command: - -{code} -karaf@root> test:hello <tab> - one two three -{code} - -h2. WebConsole - -You can also extend the Apache Karaf WebConsole by providing and installing a webconsole plugin. - -A plugin is an OSGi bundle that register a Servlet as an OSGi service with some webconsole properties. http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/main/webapp/developers-guide/github-contributions.conf ---------------------------------------------------------------------- diff --git a/manual/src/main/webapp/developers-guide/github-contributions.conf b/manual/src/main/webapp/developers-guide/github-contributions.conf deleted file mode 100644 index d278f0d..0000000 --- a/manual/src/main/webapp/developers-guide/github-contributions.conf +++ /dev/null @@ -1,73 +0,0 @@ -h1. Github Contributions - -Some people prefer to make contributions to karaf source via github. If you are one of them, this is for you! - - -h2. Introduction - -Apache Karaf is available as a periodically replicated mirror on: [https://github.com/apache/karaf] - - -h2. Suggested Workflow - -# make a fork of karaf repo github mirror -# do all your new work on your own karaf fork -# when ready, file a jira issue [https://issues.apache.org/jira/browse/KARAF], attach the link to your github pull request, and ask for a review -# one of karaf committers will discuss your pull request on github; and at some point your pull request will be accepted -# when your pull request is accepted, squash it into a single commit and attach single patch file to the original jira, with ASF grant check box selected -# now pray to your favorite ASF committer to really accept the patch :-) -# when your patch is committed to the svn, and you can verify it in the latest karaf snapshot, close your pull request on github - - -h2. License Reminder - -in order for your contributions to be accepted: - -* all files must contain ASL license grant header - -* you must select ASF grant check box when attaching patch to the jira - - -h2. How to Generate a One-File-Patch Via Throw-Away Branch - -here is one way to generate squash of your commits: - -[http://stackoverflow.com/questions/616556/how-do-you-squash-commits-into-one-patch-with-git-format-patch] - -{code} - -# -# 'archon' referers to karaf mirror -# 'origin' referers to your own fork -# - -# attach karaf mirror as remote, if not done yet -git remote add archon https://github.com/apache/karaf - -# fetch latest karaf mirror -git fetch archon - -# ensure you are on your fork trunk -git checkout origin/trunk - -# kill previous patch delivery, if you had one -git branch -D delivery - -# make new delivery throw-away branch, based on latest karaf mirror -git branch delivery archon/trunk - -# use it -git checkout delivery - -# squash all your local development into a single commit -git merge --squash trunk - -# commit it to the delivery branch -git commit -m "delivery" - -# generate a patch file against the mirror -git format-patch archon/trunk - -{code} - -root of your karaf source now contains a file named "0001-delivery.patch.txt" (please attach the .txt ending;this will allow commiters to open your patch directly in the browser and give it a short look there) which you should attach to your karaf jira, and ask to commit to the svn trunk http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/main/webapp/developers-guide/index.conf ---------------------------------------------------------------------- diff --git a/manual/src/main/webapp/developers-guide/index.conf b/manual/src/main/webapp/developers-guide/index.conf deleted file mode 100644 index 1aaaa52..0000000 --- a/manual/src/main/webapp/developers-guide/index.conf +++ /dev/null @@ -1,18 +0,0 @@ -h1. Developers Guide - -* [Developer commands|developer-commands] -* [Scripting|scripting] -* [Programmatically connect|connect] -* [Branding|branding] -* [Extending|extending] -* [Karaf Maven plugin|karaf-maven-plugin] -* [Custom distribution|custom-distribution] -* [OSGi services|services] -* [Create OSGi bundle|creating-bundles] -* [Blueprint|blueprint] -* [CDI|cdi] -* [Maven Archetypes|archetypes] -* [Security Framework|security-framework] -* [Troubleshooting, Debugging, Profiling|debugging] -* [Integration testing|writing-tests] -* [Github Contributions|github-contributions] http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/main/webapp/developers-guide/karaf-maven-plugin-commands-generate-help.conf ---------------------------------------------------------------------- diff --git a/manual/src/main/webapp/developers-guide/karaf-maven-plugin-commands-generate-help.conf b/manual/src/main/webapp/developers-guide/karaf-maven-plugin-commands-generate-help.conf deleted file mode 100644 index d81b1bf..0000000 --- a/manual/src/main/webapp/developers-guide/karaf-maven-plugin-commands-generate-help.conf +++ /dev/null @@ -1,41 +0,0 @@ -h2. Goal {{karaf:commands-generate-help}} - -The {{karaf:commands-generate-help}} goal generates documentation containing Karaf commands help. - -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 help for the commands in the current project: -{pygmentize:xml} -<project> - <build> - <plugins> - <plugin> - <groupId>org.apache.karaf.tooling</groupId> - <artifactId>karaf-maven-plugin</artifactId> - <version>${project.version}</version> - - <executions> - <execution> - <id>document-commands</id> - <phase>generate-resources</phase> - <goals> - <goal>commands-generate-help</goal> - </goals> - <configuration> - <targetFolder>${project.build.directory}/docbook/sources</targetFolder> - </configuration> - </execution> - </executions> - </plugin> - </plugins> - </build> -</project> -{pygmentize} - -h3. Parameters -|| Name || Type || Description || -| {{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 in loading the commands. \\ Default value: ${project} | http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/main/webapp/developers-guide/karaf-maven-plugin-features-add-to-repository.conf ---------------------------------------------------------------------- diff --git a/manual/src/main/webapp/developers-guide/karaf-maven-plugin-features-add-to-repository.conf b/manual/src/main/webapp/developers-guide/karaf-maven-plugin-features-add-to-repository.conf deleted file mode 100644 index b2720cd..0000000 --- a/manual/src/main/webapp/developers-guide/karaf-maven-plugin-features-add-to-repository.conf +++ /dev/null @@ -1,52 +0,0 @@ -h2. Goal {{karaf:features-add-to-repository}} - -Consider using the karaf-assembly packaging which makes it easy to assemble a custom distribution in one step instead of this individual goal. - -The {{karaf:features-add-to-repository}} goal adds all the required bundles for a given set of features into directory. You can use this goal to create a {{/system}} directory for building your own Karaf-based distribution. - -By default, the Karaf core features descriptors (standard and enterprise) are automatically included in the descriptors set. - -h3. Example -The example below copies the bundles for the {{spring}} and {{war}} features defined in the Karaf features XML descriptor into the {{target/features-repo}} directory. -{pygmentize:xml} -<project> - <build> - <plugins> - <plugin> - <groupId>org.apache.karaf.tooling</groupId> - <artifactId>karaf-maven-plugin</artifactId> - <version>${project.version}</version> - - <executions> - <execution> - <id>features-add-to-repo</id> - <phase>generate-resources</phase> - <goals> - <goal>features-add-to-repository</goal> - </goals> - <configuration> - <descriptors> - <descriptor>mvn:org.apache.karaf.features/standard/4.0.0/xml/features</descriptor> - <descriptor>mvn:my.groupid/my.artifactid/1.0.0/xml/features</descriptor> - </descriptors> - <features> - <feature>spring</feature> - <feature>war</feature> - <feature>my</feature> - </features> - <repository>target/features-repo</repository> - </configuration> - </execution> - </executions> - </plugin> - </plugins> - </build> -</project> -{pygmentize} - -h3. Parameters -|| Name || Type || Description || -| {{descriptors}} | {{String[]}} | List of features XML descriptors where the features are defined | -| {{features}} | {{String[]}} | List of features that bundles should be copied to the repository directory | -| {{repository}} | {{File}} | The directory where the bundles will be copied by the plugin goal | - http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/main/webapp/developers-guide/karaf-maven-plugin-features-create-kar.conf ---------------------------------------------------------------------- diff --git a/manual/src/main/webapp/developers-guide/karaf-maven-plugin-features-create-kar.conf b/manual/src/main/webapp/developers-guide/karaf-maven-plugin-features-create-kar.conf deleted file mode 100644 index 1e8fe45..0000000 --- a/manual/src/main/webapp/developers-guide/karaf-maven-plugin-features-create-kar.conf +++ /dev/null @@ -1,33 +0,0 @@ -h2. Goal {{karaf:kar}} - -Except in unusual circumstances, use the <packaging>kar</packaging> to run this goal. - -The {{karaf:kar}} goal assembles a KAR archive from a features XML descriptor file, normally generated in the same project with the {{karaf:features-generate-descriptor}} mojo. - -h2. kar layout - -There are two important directories in a kar: -repository/ contains a Maven structured repository of artifacts to be copied into the Karaf repository. The features descriptor and all the bundles mentioned in it are installed in this directory. -resources/ contains other resources to be copied over the Karaf installation. - -Everything in target/classes is copied into the kar. Therefore resources you want installed into Karaf need to be in e.g. src/main/resources/resources. This choice is so other resources such as legal files from the maven-remote-resources-plugin can be included under META-INF in the kar, without getting installed into Karaf. - -h3. Example -{pygmentize:xml} -<project> -... - <packaging>kar</packaging> - <build> - <plugins> - <plugin> - <groupId>org.apache.karaf.tooling</groupId> - <artifactId>karaf-maven-plugin</artifactId> - <version>${project.version}</version> - <extensions>true</extensions> - <!-- There is no useful configuration for the kar mojo. The features-generate-descriptor mojo configuration may be useful --> - </plugin> - </plugins> - </build> -</project> -{pygmentize} - http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/main/webapp/developers-guide/karaf-maven-plugin-features-generate-descriptor.conf ---------------------------------------------------------------------- diff --git a/manual/src/main/webapp/developers-guide/karaf-maven-plugin-features-generate-descriptor.conf b/manual/src/main/webapp/developers-guide/karaf-maven-plugin-features-generate-descriptor.conf deleted file mode 100644 index 6a71d60..0000000 --- a/manual/src/main/webapp/developers-guide/karaf-maven-plugin-features-generate-descriptor.conf +++ /dev/null @@ -1,58 +0,0 @@ -h2. Goal {{karaf:features-generate-descriptor}} - -Except in unusual circumstances, use the <packaging>feature</packaging> to run this goal. - -The {{karaf:features-generate-descriptor}} goal generates a features XML file based on the Maven dependencies. By default, it will follow Maven transitive dependencies, stopping when it encounters bundles already present in features that are Maven dependencies. - -A record of the dependency tree search can be found in target/history/treeListing.txt. - -You can track dependency changes and warn or fail on change. - -h2. Configuration - -Specify the packaging as a top level element - -{code} -<packaging>feature</packaging> -{code} - -You can supply a feature descriptor to extend in src/main/feature/feature.xml. - -|| Parameter Name || Type || Description || -| aggregateFeatures | boolean (false) | Specifies processing of feature repositories that are (transitive) Maven dependencies. If false, all features in these repositories become dependencies of the generated feature. If true, all features in these repositories are copied into the generated feature repository. | -| startLevel | int | The start level for the bundles determined from Maven dependencies. This can be overridden by specifying the bundle in the source feature.xml with the desired startlevel. | -| includeTransitiveDependency | boolean (true) | Whether to follow Maven transitive dependencies. | -| checkDependencyChange | boolean (false) | Whether to record dependencies in src/main/history.dependencies.xml for change tracking. | -| warnOnDependencyChange | boolean (false) | whether to fail on changed dependencies (false, default) or warn in the build output (true). | -| logDependencyChanges | boolean (false) | If true, added and removed dependencies are shown in target/history. | -| overwriteChangedDependencies | boolean (false) | If true, the src/main/history/dependencies.xml file will be overwritten if it has changed. | - -h3. Example -{pygmentize:xml} -<project> -... - <packaging>feature</packaging> - <dependencies> - <dependency> - <groupId>org.apache</groupId> - <artifactId>bundle1</artifactId> - <version>1.0</version> - </dependency> - </dependencies> - <build> - <plugins> - <plugin> - <groupId>org.apache.karaf.tooling</groupId> - <artifactId>karaf-maven-plugin</artifactId> - <version>${project.version}</version> - <extensions>true</extensions> - <configuration> - <startLevel>80</startLevel> - <aggregateFeatures>true</aggregateFeatures> - </configuration> - </plugin> - </plugins> - </build> -</project> -{pygmentize} -
