KARAF-3679 - Switch documentation to asciidoc, close #65
Project: http://git-wip-us.apache.org/repos/asf/karaf/repo Commit: http://git-wip-us.apache.org/repos/asf/karaf/commit/3de05ae9 Tree: http://git-wip-us.apache.org/repos/asf/karaf/tree/3de05ae9 Diff: http://git-wip-us.apache.org/repos/asf/karaf/diff/3de05ae9 Branch: refs/heads/master Commit: 3de05ae9a62e38535982977fe9987640321180db Parents: 68186c4 Author: Jean-Baptiste Onofré <[email protected]> Authored: Tue Dec 29 15:14:29 2015 +0100 Committer: Jean-Baptiste Onofré <[email protected]> Committed: Mon Jan 4 10:57:11 2016 +0100 ---------------------------------------------------------------------- manual/pom.xml | 374 +---- manual/src/fallback/manual.html | 20 - manual/src/fallback/manual.pdf | Bin 16576 -> 0 bytes .../asciidoc/developer-guide/archetypes.adoc | 378 +++++ .../asciidoc/developer-guide/blueprint.adoc | 15 + .../main/asciidoc/developer-guide/branding.adoc | 241 +++ .../main/asciidoc/developer-guide/connect.adoc | 96 ++ .../developer-guide/creating-bundles.adoc | 213 +++ .../developer-guide/custom-distribution.adoc | 650 +++++++ .../asciidoc/developer-guide/debugging.adoc | 199 +++ .../main/asciidoc/developer-guide/dev-cdi.adoc | 15 + .../developer-guide/developer-commands.adoc | 242 +++ .../src/main/asciidoc/developer-guide/ds.adoc | 15 + .../asciidoc/developer-guide/extending.adoc | 359 ++++ .../developer-guide/github-contributions.adoc | 81 + .../developer-guide/karaf-maven-plugin.adoc | 486 ++++++ .../asciidoc/developer-guide/scripting.adoc | 406 +++++ .../developer-guide/security-framework.adoc | 842 ++++++++++ .../main/asciidoc/developer-guide/services.adoc | 15 + .../asciidoc/developer-guide/writing-tests.adoc | 370 ++++ manual/src/main/asciidoc/images/asf-logo.png | Bin 0 -> 4735 bytes manual/src/main/asciidoc/images/bg.png | Bin 0 -> 244 bytes .../src/main/asciidoc/images/bg02-blue-left.png | Bin 0 -> 1068 bytes .../main/asciidoc/images/bg02-blue-right.png | Bin 0 -> 1114 bytes .../asciidoc/images/bg02-white-left-nogr.png | Bin 0 -> 951 bytes .../asciidoc/images/bg02-white-right-nogr.png | Bin 0 -> 958 bytes manual/src/main/asciidoc/images/big-bullet.png | Bin 0 -> 285 bytes manual/src/main/asciidoc/images/deployer.png | Bin 0 -> 51372 bytes .../src/main/asciidoc/images/jconsole_admin.jpg | Bin 0 -> 65713 bytes .../main/asciidoc/images/jconsole_connect.jpg | Bin 0 -> 38238 bytes .../main/asciidoc/images/jconsole_features.jpg | Bin 0 -> 63879 bytes .../main/asciidoc/images/jconsole_memory.jpg | Bin 0 -> 64714 bytes .../main/asciidoc/images/jconsole_overview.jpg | Bin 0 -> 72287 bytes .../main/asciidoc/images/jconsole_summary.jpg | Bin 0 -> 119430 bytes .../main/asciidoc/images/jconsole_threads.jpg | Bin 0 -> 62860 bytes manual/src/main/asciidoc/images/karaf-logo.png | Bin 0 -> 20682 bytes manual/src/main/asciidoc/images/karaf.png | Bin 0 -> 21494 bytes manual/src/main/asciidoc/images/karaf2.png | Bin 0 -> 21494 bytes .../main/asciidoc/images/left-box-bottom.png | Bin 0 -> 588 bytes .../src/main/asciidoc/images/left-box-right.png | Bin 0 -> 213 bytes .../src/main/asciidoc/images/left-box-top.png | Bin 0 -> 466 bytes manual/src/main/asciidoc/index.adoc | 137 ++ manual/src/main/asciidoc/overview.adoc | 51 + manual/src/main/asciidoc/quick-start.adoc | 181 ++ manual/src/main/asciidoc/update-notes.adoc | 171 ++ manual/src/main/asciidoc/user-guide/cdi.adoc | 75 + .../asciidoc/user-guide/configugration.adoc | 384 +++++ .../src/main/asciidoc/user-guide/console.adoc | 460 +++++ .../src/main/asciidoc/user-guide/deployers.adoc | 235 +++ .../user-guide/directory-structure.adoc | 41 + manual/src/main/asciidoc/user-guide/ejb.adoc | 91 + .../src/main/asciidoc/user-guide/failover.adoc | 255 +++ manual/src/main/asciidoc/user-guide/http.adoc | 74 + .../main/asciidoc/user-guide/installation.adoc | 167 ++ .../src/main/asciidoc/user-guide/instances.adoc | 390 +++++ manual/src/main/asciidoc/user-guide/jdbc.adoc | 224 +++ manual/src/main/asciidoc/user-guide/jms.adoc | 318 ++++ manual/src/main/asciidoc/user-guide/jndi.adoc | 224 +++ manual/src/main/asciidoc/user-guide/jpa.adoc | 44 + manual/src/main/asciidoc/user-guide/jta.adoc | 120 ++ manual/src/main/asciidoc/user-guide/kar.adoc | 298 ++++ manual/src/main/asciidoc/user-guide/log.adoc | 607 +++++++ .../main/asciidoc/user-guide/monitoring.adoc | 287 ++++ manual/src/main/asciidoc/user-guide/obr.adoc | 373 ++++ .../main/asciidoc/user-guide/provisioning.adoc | 685 ++++++++ manual/src/main/asciidoc/user-guide/remote.adoc | 424 +++++ .../src/main/asciidoc/user-guide/security.adoc | 584 +++++++ .../main/asciidoc/user-guide/start-stop.adoc | 439 +++++ manual/src/main/asciidoc/user-guide/tuning.adoc | 159 ++ manual/src/main/asciidoc/user-guide/urls.adoc | 60 + .../main/asciidoc/user-guide/webconsole.adoc | 61 + .../main/asciidoc/user-guide/webcontainer.adoc | 292 ++++ .../src/main/asciidoc/user-guide/wrapper.adoc | 409 +++++ .../asciidoc/users-guide/adociguration.adoc | 365 ---- manual/src/main/asciidoc/users-guide/cdi.adoc | 102 -- .../src/main/asciidoc/users-guide/console.adoc | 427 ----- .../main/asciidoc/users-guide/deployers.adoc | 286 ---- .../users-guide/directory-structure.adoc | 35 - manual/src/main/asciidoc/users-guide/ejb.adoc | 94 -- .../main/asciidoc/users-guide/enterprise.adoc | 35 - .../src/main/asciidoc/users-guide/failover.adoc | 243 --- .../src/main/asciidoc/users-guide/features.adoc | 64 - manual/src/main/asciidoc/users-guide/http.adoc | 74 - manual/src/main/asciidoc/users-guide/index.adoc | 77 - .../main/asciidoc/users-guide/installation.adoc | 145 -- .../main/asciidoc/users-guide/instances.adoc | 379 ----- manual/src/main/asciidoc/users-guide/jdbc.adoc | 226 --- manual/src/main/asciidoc/users-guide/jms.adoc | 304 ---- manual/src/main/asciidoc/users-guide/jndi.adoc | 219 --- manual/src/main/asciidoc/users-guide/jpa.adoc | 40 - manual/src/main/asciidoc/users-guide/jta.adoc | 119 -- manual/src/main/asciidoc/users-guide/kar.adoc | 304 ---- manual/src/main/asciidoc/users-guide/log.adoc | 565 ------- .../main/asciidoc/users-guide/migration.adoc | 66 - .../main/asciidoc/users-guide/monitoring.adoc | 273 --- manual/src/main/asciidoc/users-guide/obr.adoc | 373 ---- .../users-guide/provisioning-schema.adoc | 46 - .../src/main/asciidoc/users-guide/remote.adoc | 423 ----- .../src/main/asciidoc/users-guide/security.adoc | 583 ------- .../main/asciidoc/users-guide/start-stop.adoc | 433 ----- .../src/main/asciidoc/users-guide/tuning.adoc | 159 -- .../src/main/asciidoc/users-guide/update.adoc | 19 - manual/src/main/asciidoc/users-guide/urls.adoc | 58 - .../main/asciidoc/users-guide/webconsole.adoc | 62 - .../main/asciidoc/users-guide/webcontainer.adoc | 289 ---- .../src/main/asciidoc/users-guide/wrapper.adoc | 388 ----- manual/src/main/webapp/.livereload | 19 - .../WEB-INF/scalate/layouts/default.scaml | 116 -- .../webapp/WEB-INF/scalate/layouts/print.ssp | 817 --------- manual/src/main/webapp/WEB-INF/web.xml | 50 - manual/src/main/webapp/_banner.ssp | 14 - manual/src/main/webapp/_navigation.conf | 56 - manual/src/main/webapp/_quicklinks.ssp | 8 - manual/src/main/webapp/css/pygmentize.css | 134 -- manual/src/main/webapp/css/scalate/console.css | 71 - manual/src/main/webapp/css/style.css | 1588 ------------------ .../webapp/developers-guide/archetypes.conf | 360 ---- .../main/webapp/developers-guide/branding.conf | 222 --- .../main/webapp/developers-guide/connect.conf | 82 - .../developers-guide/creating-bundles.conf | 198 --- .../developers-guide/custom-distribution.conf | 625 ------- .../main/webapp/developers-guide/debugging.conf | 162 -- .../developers-guide/developer-commands.conf | 228 --- .../main/webapp/developers-guide/extending.conf | 340 ---- .../developers-guide/github-contributions.conf | 73 - .../src/main/webapp/developers-guide/index.conf | 18 - ...raf-maven-plugin-commands-generate-help.conf | 41 - ...maven-plugin-features-add-to-repository.conf | 52 - .../karaf-maven-plugin-features-create-kar.conf | 33 - ...ven-plugin-features-generate-descriptor.conf | 58 - ...ven-plugin-features-validate-descriptor.conf | 50 - ...af-maven-plugin-instance-create-archive.conf | 43 - .../developers-guide/karaf-maven-plugin.conf | 70 - .../main/webapp/developers-guide/scripting.conf | 305 ---- .../developers-guide/security-framework.conf | 695 -------- .../main/webapp/developers-guide/services.conf | 1 - .../webapp/developers-guide/writing-tests.conf | 328 ---- manual/src/main/webapp/images/asf-logo.png | Bin 4735 -> 0 bytes manual/src/main/webapp/images/bg.png | Bin 244 -> 0 bytes .../src/main/webapp/images/bg02-blue-left.png | Bin 1068 -> 0 bytes .../src/main/webapp/images/bg02-blue-right.png | Bin 1114 -> 0 bytes .../main/webapp/images/bg02-white-left-nogr.png | Bin 951 -> 0 bytes .../webapp/images/bg02-white-right-nogr.png | Bin 958 -> 0 bytes manual/src/main/webapp/images/big-bullet.png | Bin 285 -> 0 bytes manual/src/main/webapp/images/deployer.png | Bin 51372 -> 0 bytes .../src/main/webapp/images/jconsole_admin.jpg | Bin 65713 -> 0 bytes .../src/main/webapp/images/jconsole_connect.jpg | Bin 38238 -> 0 bytes .../main/webapp/images/jconsole_features.jpg | Bin 63879 -> 0 bytes .../src/main/webapp/images/jconsole_memory.jpg | Bin 64714 -> 0 bytes .../main/webapp/images/jconsole_overview.jpg | Bin 72287 -> 0 bytes .../src/main/webapp/images/jconsole_summary.jpg | Bin 119430 -> 0 bytes .../src/main/webapp/images/jconsole_threads.jpg | Bin 62860 -> 0 bytes manual/src/main/webapp/images/karaf-logo.png | Bin 20682 -> 0 bytes manual/src/main/webapp/images/karaf.png | Bin 21494 -> 0 bytes manual/src/main/webapp/images/karaf2.png | Bin 21494 -> 0 bytes .../src/main/webapp/images/left-box-bottom.png | Bin 588 -> 0 bytes .../src/main/webapp/images/left-box-right.png | Bin 213 -> 0 bytes manual/src/main/webapp/images/left-box-top.png | Bin 466 -> 0 bytes manual/src/main/webapp/index.conf | 11 - manual/src/main/webapp/manual.conf | 87 - manual/src/main/webapp/overview.conf | 37 - manual/src/main/webapp/quick-start.conf | 162 -- manual/src/main/webapp/update-notes.conf | 126 -- manual/src/main/webapp/users-guide/cdi.conf | 61 - .../main/webapp/users-guide/configuration.conf | 368 ---- manual/src/main/webapp/users-guide/console.conf | 443 ----- .../src/main/webapp/users-guide/deployers.conf | 223 --- .../webapp/users-guide/directory-structure.conf | 25 - manual/src/main/webapp/users-guide/ejb.conf | 80 - .../src/main/webapp/users-guide/enterprise.conf | 21 - .../src/main/webapp/users-guide/failover.conf | 230 --- .../src/main/webapp/users-guide/features.conf | 52 - manual/src/main/webapp/users-guide/http.conf | 60 - manual/src/main/webapp/users-guide/index.conf | 30 - .../main/webapp/users-guide/installation.conf | 128 -- .../src/main/webapp/users-guide/instances.conf | 365 ---- manual/src/main/webapp/users-guide/jdbc.conf | 210 --- manual/src/main/webapp/users-guide/jms.conf | 300 ---- manual/src/main/webapp/users-guide/jndi.conf | 205 --- manual/src/main/webapp/users-guide/jpa.conf | 26 - manual/src/main/webapp/users-guide/jta.conf | 105 -- manual/src/main/webapp/users-guide/kar.conf | 284 ---- manual/src/main/webapp/users-guide/log.conf | 551 ------ .../src/main/webapp/users-guide/monitoring.conf | 265 --- manual/src/main/webapp/users-guide/obr.conf | 359 ---- .../webapp/users-guide/provisioning-schema.conf | 46 - .../main/webapp/users-guide/provisioning.conf | 670 -------- manual/src/main/webapp/users-guide/remote.conf | 409 ----- .../src/main/webapp/users-guide/security.conf | 569 ------- .../src/main/webapp/users-guide/start-stop.conf | 419 ----- manual/src/main/webapp/users-guide/tuning.conf | 145 -- manual/src/main/webapp/users-guide/update.conf | 5 - manual/src/main/webapp/users-guide/urls.conf | 43 - .../src/main/webapp/users-guide/webconsole.conf | 48 - .../main/webapp/users-guide/webcontainer.conf | 275 --- manual/src/main/webapp/users-guide/wrapper.conf | 395 ----- pom.xml | 4 - 197 files changed, 12973 insertions(+), 22338 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/pom.xml ---------------------------------------------------------------------- diff --git a/manual/pom.xml b/manual/pom.xml index 9e9b119..90fccc8 100644 --- a/manual/pom.xml +++ b/manual/pom.xml @@ -23,117 +23,11 @@ <artifactId>manual</artifactId> <name>Apache Karaf :: Manual</name> - <packaging>war</packaging> - - <properties> - <must-succeed>false</must-succeed> - <manual.dir>${project.build.directory}/manual</manual.dir> - <manual>${manual.dir}/manual-${project.version}</manual> - <netbeans.hint.deploy.server>Tomcat60</netbeans.hint.deploy.server> - <jetty-port>8080</jetty-port> - <jetty-war-dir>${project.build.directory}/webapp/</jetty-war-dir> - <scalate.version>1.4.0</scalate.version> - <wikitext.version>1.3</wikitext.version> - <scalate.editor>${env.SCALATE_EDITOR}</scalate.editor> - <scalate.mode>production</scalate.mode> - <scalate.workdir>${project.build.directory}/scalateWorkDir</scalate.workdir> - <karaf.version>${project.version}</karaf.version> - <maven.wagon.version>1.0-beta-6</maven.wagon.version> - </properties> - - <dependencies> - <dependency> - <groupId>org.fusesource.scalate</groupId> - <artifactId>scalate-wikitext</artifactId> - <version>${scalate.version}</version> - </dependency> - <dependency> - <groupId>ch.qos.logback</groupId> - <artifactId>logback-classic</artifactId> - <version>1.0.0</version> - </dependency> - <dependency> - <groupId>org.slf4j</groupId> - <artifactId>slf4j-api</artifactId> - </dependency> - <dependency> - <groupId>org.scala-lang</groupId> - <artifactId>scala-library</artifactId> - <version>2.8.1</version> - </dependency> - <dependency> - <groupId>org.scala-lang</groupId> - <artifactId>scala-compiler</artifactId> - <version>2.8.1</version> - </dependency> - </dependencies> + <packaging>pom</packaging> <build> <plugins> <plugin> - <groupId>org.apache.maven.plugins</groupId> - <artifactId>maven-resources-plugin</artifactId> - <configuration> - <useDefaultDelimiters>false</useDefaultDelimiters> - <delimiters> - <delimiter>${*}</delimiter> - </delimiters> - </configuration> - <executions> - <execution> - <id>filter</id> - <phase>generate-resources</phase> - <goals> - <goal>copy-resources</goal> - </goals> - <configuration> - <outputDirectory>${project.build.directory}/webapp</outputDirectory> - <resources> - <resource> - <directory>src/main/webapp</directory> - <filtering>true</filtering> - </resource> - </resources> - </configuration> - </execution> - </executions> - </plugin> - <plugin> - <groupId>org.codehaus.mojo</groupId> - <artifactId>build-helper-maven-plugin</artifactId> - <executions> - <execution> - <id>add-source</id> - <phase>generate-resources</phase> - <goals> - <goal>add-source</goal> - </goals> - <configuration> - <sources> - <source>${project.build.directory}/webapp</source> - </sources> - </configuration> - </execution> - <!-- - <execution> - <id>attach-artifacts</id> - <phase>install</phase> - <goals> - <goal>attach-artifact</goal> - </goals> - <configuration> - <artifacts> - <artifact> - <file>${manual}.html</file> - <type>html</type> - </artifact> - </artifacts> - </configuration> - </execution> - --> - </executions> - </plugin> - <plugin> <groupId>org.apache.karaf.tooling</groupId> <artifactId>karaf-maven-plugin</artifactId> <version>${project.version}</version> @@ -145,8 +39,8 @@ <goal>commands-generate-help</goal> </goals> <configuration> - <format>conf</format> - <targetFolder>${project.build.directory}/webapp/commands/</targetFolder> + <format>asciidoc</format> + <targetFolder>${project.build.directory}/generated-docs/commands/</targetFolder> <classLoader>plugin</classLoader> </configuration> </execution> @@ -306,90 +200,32 @@ </dependency> </dependencies> </plugin> - <plugin> - <groupId>org.apache.maven.plugins</groupId> - <artifactId>maven-war-plugin</artifactId> - <configuration> - <webResources> - <resource> - <directory>${project.build.directory}/webapp/</directory> - </resource> - </webResources> - <archive> - <manifestFile>${project.build.outputDirectory}/META-INF/MANIFEST.MF</manifestFile> - </archive> - </configuration> - </plugin> <plugin> - <groupId>org.mortbay.jetty</groupId> - <artifactId>jetty-maven-plugin</artifactId> - <version>7.1.5.v20100705</version> - <configuration> - <!-- When editing the conf files, you can comment this line to run - mvn jetty:run - to have a live web site - --> - <webAppSourceDirectory>${jetty-war-dir}</webAppSourceDirectory> - - <systemProperties> - <systemProperty> - <name>scalate.editor</name> - <value>${scalate.editor}</value> - </systemProperty> - <systemProperty> - <name>scalate.workdir</name> - <value>${scalate.workdir}</value> - </systemProperty> - <systemProperty> - <name>scalate.mode</name> - <value>${scalate.mode}</value> - </systemProperty> - </systemProperties> - </configuration> - </plugin> - <plugin> - <groupId>org.apache.felix</groupId> - <artifactId>maven-bundle-plugin</artifactId> - <version>2.4.0</version> + <groupId>org.asciidoctor</groupId> + <artifactId>asciidoctor-maven-plugin</artifactId> + <version>1.5.2</version> <executions> <execution> - <id>bundle-manifest</id> - <phase>process-classes</phase> + <id>output-html</id> + <phase>generate-resources</phase> <goals> - <goal>manifest</goal> + <goal>process-asciidoc</goal> </goals> + <configuration> + <sourceHighlighter>coderay</sourceHighlighter> + <backend>html5</backend> + <attributes> + <toc /> + <linkcss>false</linkcss> + <doctype>book</doctype> + </attributes> + </configuration> </execution> </executions> <configuration> - <supportedProjectTypes> - <supportedProjectType>jar</supportedProjectType> - <supportedProjectType>bundle</supportedProjectType> - <supportedProjectType>war</supportedProjectType> - </supportedProjectTypes> - <instructions> - <Import-Package> - javax.servlet, - javax.servlet.http, - javax.servlet.jsp;resolution:=optional, - javax.servlet.jsp.el;resolution:=optional, - org.apache.commons.logging;resolution:=optional;provider=paxlogging, - org.apache.commons.logging.impl;resolution:=optional;provider=paxlogging, - org.apache.log4j;resolution:=optional;provider=paxlogging, - org.apache.log4j.spi;resolution:=optional;provider=paxlogging, - org.apache.log4j.xml;resolution:=optional;provider=paxlogging, - org.slf4j;resolution:=optional;provider=paxlogging, - org.slf4j.helpers;resolution:=optional;provider=paxlogging, - org.slf4j.spi;resolution:=optional;provider=paxlogging, - org.osgi.framework, - javax.swing.tree, - org.osgi.service.packageadmin - </Import-Package> - <Bundle-ClassPath>.,WEB-INF/classes</Bundle-ClassPath> - <Embed-Directory>WEB-INF/lib</Embed-Directory> - <Embed-Dependency>*;scope=compile|runtime</Embed-Dependency> - <Embed-Transitive>true</Embed-Transitive> - <Web-ContextPath>/karaf-doc</Web-ContextPath> - </instructions> + <sourceDirectory>src/main/asciidoc</sourceDirectory> + <headerFooter>true</headerFooter> + <imagesDir>../resources/images</imagesDir> </configuration> </plugin> <plugin> @@ -397,107 +233,17 @@ <artifactId>maven-scm-publish-plugin</artifactId> <version>1.0-beta-2</version> <configuration> - <checkinComment>[scm-publish] Updating main site with Karaf manual</checkinComment> + <checkinComment>[scm-publish] Updating main site with Karaf documentation</checkinComment> <pubScmUrl>scm:svn:https://svn.apache.org/repos/asf/karaf/site/production/manual/latest</pubScmUrl> - <content>${project.build.directory}/sitegen</content> + <content>${project.build.directory}/generated-docs</content> </configuration> </plugin> </plugins> </build> - <reporting> - <plugins> - <plugin> - <groupId>org.fusesource.scalate</groupId> - <artifactId>maven-scalate-plugin</artifactId> - <version>${scalate.version}</version> - </plugin> - </plugins> - </reporting> - <profiles> <profile> - <id>live</id> - <properties> - <jetty-war-dir>${basedir}/src/main/webapp/</jetty-war-dir> - <scalate.mode>development</scalate.mode> - </properties> - </profile> - <profile> - <id>scalate-manual</id> - <activation> - <activeByDefault>true</activeByDefault> - </activation> - - <build> - <plugins> - <plugin> - <groupId>org.fusesource.scalate</groupId> - <artifactId>maven-scalate-plugin</artifactId> - <version>${scalate.version}</version> - <executions> - <execution> - <id>generate-htmls</id> - <phase>prepare-package</phase> - <goals> - <goal>sitegen-no-fork</goal> - </goals> - <configuration> - <warSourceDirectory>${project.build.directory}/webapp</warSourceDirectory> - </configuration> - </execution> - </executions> - <configuration> - <remoteServerId>people.apache.org</remoteServerId> - <remoteServerUrl>scp://people.apache.org/www/karaf.apache.org/manual/${karaf.version} - </remoteServerUrl> - </configuration> - <dependencies> - <dependency> - <groupId>org.apache.maven.wagon</groupId> - <artifactId>wagon-ssh</artifactId> - <version>${maven.wagon.version}</version> - </dependency> - <dependency> - <groupId>org.fusesource.wikitext</groupId> - <artifactId>confluence-core</artifactId> - <version>${wikitext.version}</version> - </dependency> - </dependencies> - </plugin> - <plugin> - <groupId>org.apache.maven.plugins</groupId> - <artifactId>maven-antrun-plugin</artifactId> - <executions> - <execution> - <id>create-manual</id> - <phase>package</phase> - <goals> - <goal>run</goal> - </goals> - <configuration> - <tasks> - <mkdir dir="${manual.dir}" /> - <move file="${project.build.directory}/sitegen/manual.html" tofile="${manual}.html" /> - <echo message="Generating PDF using Prince XML (http://www.princexml.com/)" /> - <exec executable="prince"> - <arg value="${manual}.html" /> - <arg value="${manual}.pdf" /> - <arg value="--log" /> - <arg value="${project.build.directory}/prince.log" /> - </exec> - <attachartifact file="${manual}.html" type="html" /> - <attachartifact file="${manual}.pdf" type="pdf" /> - </tasks> - </configuration> - </execution> - </executions> - </plugin> - </plugins> - </build> - </profile> - <profile> - <id>pdf-manual</id> + <id>pdf</id> <build> <plugins> <plugin> @@ -512,85 +258,25 @@ </goals> <configuration> <tasks> - <mkdir dir="${manual.dir}" /> - <move file="${project.build.directory}/sitegen/manual.html" tofile="${manual}.html" /> + <mkdir dir="target" /> + <copy file="${project.build.directory}/generated-docs/index.html" tofile="target/documentation.html" /> <echo message="Generating PDF using Prince XML (http://www.princexml.com/)" /> <exec executable="prince"> - <arg value="${manual}.html" /> - <arg value="${manual}.pdf" /> + <arg value="target/documentation.html" /> + <arg value="target/documentation.pdf" /> <arg value="--log" /> <arg value="${project.build.directory}/prince.log" /> </exec> + <attachartifact file="target/documentation.html" type="html"/> + <attachartifact file="target/documentation.pdf" type="pdf"/> </tasks> </configuration> </execution> </executions> </plugin> - <plugin> - <groupId>org.codehaus.mojo</groupId> - <artifactId>build-helper-maven-plugin</artifactId> - <executions> - <execution> - <id>attach-artifacts</id> - <phase>install</phase> - <goals> - <goal>attach-artifact</goal> - </goals> - <configuration> - <artifacts> - <artifact> - <file>${manual}.pdf</file> - <type>pdf</type> - </artifact> - </artifacts> - </configuration> - </execution> - </executions> - </plugin> </plugins> </build> </profile> - <profile> - <id>asciidoc</id> - <build> - <plugins> - <plugin> - <groupId>org.asciidoctor</groupId> - <artifactId>asciidoctor-maven-plugin</artifactId> - <version>1.5.2</version> - <executions> - <execution> - <id>output-html</id> - <phase>generate-resources</phase> - <goals> - <goal>process-asciidoc</goal> - </goals> - <configuration> - <sourceHighlighter>coderay</sourceHighlighter> - <backend>html5</backend> - <attributes> - <toc /> - <linkcss>false</linkcss> - <doctype>book</doctype> - </attributes> - </configuration> - </execution> - </executions> - <configuration> - <sourceDirectory>src/main/asciidoc</sourceDirectory> - <headerFooter>true</headerFooter> - <imagesDir>../resources/images</imagesDir> - </configuration> - </plugin> - </plugins> - </build> - </profile> - <profile> - <id>release</id> - <properties> - <must-succeed>true</must-succeed> - </properties> - </profile> </profiles> </project> http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/fallback/manual.html ---------------------------------------------------------------------- diff --git a/manual/src/fallback/manual.html b/manual/src/fallback/manual.html deleted file mode 100644 index 4aa3dbd..0000000 --- a/manual/src/fallback/manual.html +++ /dev/null @@ -1,20 +0,0 @@ -<!-- - - Licensed to the Apache Software Foundation (ASF) under one or more - contributor license agreements. See the NOTICE file distributed with - this work for additional information regarding copyright ownership. - The ASF licenses this file to You under the Apache License, Version 2.0 - (the "License"); you may not use this file except in compliance with - the License. You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. ---> -<div class="wiki-content"> - Unable to generate manual. -</div> \ No newline at end of file http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/fallback/manual.pdf ---------------------------------------------------------------------- diff --git a/manual/src/fallback/manual.pdf b/manual/src/fallback/manual.pdf deleted file mode 100644 index 72f3d80..0000000 Binary files a/manual/src/fallback/manual.pdf and /dev/null differ http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/main/asciidoc/developer-guide/archetypes.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/developer-guide/archetypes.adoc b/manual/src/main/asciidoc/developer-guide/archetypes.adoc new file mode 100644 index 0000000..3584338 --- /dev/null +++ b/manual/src/main/asciidoc/developer-guide/archetypes.adoc @@ -0,0 +1,378 @@ +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +== Archetypes + +Karaf provides archetypes to easily create commands, manage features or repository and create a kar archive. +This section describes each of them and explain How to use it. + +=== Create a command (karaf-command-archetype) + +This archetype creates a Maven skeleton project that you will use to develop new Karaf commands. + +==== Command line + +Using the command line, we can create our project: + +---- +mvn archetype:generate \ + -DarchetypeGroupId=org.apache.karaf.archetypes \ + -DarchetypeArtifactId=karaf-command-archetype \ + -DarchetypeVersion=4.0.0 \ + -DgroupId=com.mycompany \ + -DartifactId=com.mycompany.command \ + -Dversion=1.0-SNAPSHOT \ + -Dpackage=com.mycompany.package +---- + +==== Additional parameters + +During the maven creation process, additional questions will be asked on the console : + +* Define value for property 'command': the name of the command (list, add-item, ...) +* Define value for property 'description': provide a description of the command that you want to create. +This description will be displayed in the Karaf console when the parameter --help is used +* Define value for property 'scope': this value represents the family name to which the command belongs +(features, osgi, admin, jaas, ...) + +==== Result of Maven command execution + +---- +[INFO] Scanning for projects... +[INFO] +[INFO] ------------------------------------------------------------------------ +[INFO] Building Maven Stub Project (No POM) 1 +[INFO] ------------------------------------------------------------------------ +[INFO] +[INFO] >>> maven-archetype-plugin:2.1:generate (default-cli) @ standalone-pom >>> +[INFO] +[INFO] <<< maven-archetype-plugin:2.1:generate (default-cli) @ standalone-pom <<< +[INFO] +[INFO] --- maven-archetype-plugin:2.1:generate (default-cli) @ standalone-pom --- +[INFO] Generating project in Interactive mode +[INFO] Archetype repository missing. Using the one from [org.apache.karaf.archetypes:karaf-command-archetype:4.0.0] found in catalog local +[INFO] Using property: groupId = com.mycompany +[INFO] Using property: artifactId = com.mycompany.command +[INFO] Using property: version = 1.0-SNAPSHOT +[INFO] Using property: package = com.mycompany.package +Define value for property 'command': : list +Define value for property 'description': : List sample command +Define value for property 'scope': : my +Confirm properties configuration: +groupId: com.mycompany +artifactId: com.mycompany.command +version: 1.0-SNAPSHOT +package: com.mycompany.package +command: list +description: List sample command +scope: my + Y: : +[INFO] ---------------------------------------------------------------------------- +[INFO] Using following parameters for creating project from Archetype: karaf-command-archetype:4.0.0 +[INFO] ---------------------------------------------------------------------------- +[INFO] Parameter: groupId, Value: com.mycompany +[INFO] Parameter: artifactId, Value: com.mycompany.command +[INFO] Parameter: version, Value: 1.0-SNAPSHOT +[INFO] Parameter: package, Value: com.mycompany.package +[INFO] Parameter: packageInPathFormat, Value: com/mycompany/package +[INFO] Parameter: package, Value: com.mycompany.package +[INFO] Parameter: version, Value: 1.0-SNAPSHOT +[INFO] Parameter: groupId, Value: com.mycompany +[INFO] Parameter: scope, Value: my +[INFO] Parameter: description, Value: List sample command +[INFO] Parameter: command, Value: list +[INFO] Parameter: artifactId, Value: com.mycompany.command +[WARNING] Don't override file /com.mycompany.command/pom.xml +[INFO] project created from Archetype in dir: /com.mycompany.command +[INFO] ------------------------------------------------------------------------ +[INFO] BUILD SUCCESS +[INFO] ------------------------------------------------------------------------ +[INFO] Total time: 27.204s +[INFO] Finished at: Mon Dec 19 09:38:49 CET 2011 +[INFO] Final Memory: 7M/111M +[INFO] ------------------------------------------------------------------------ +---- + +Next, you can import your project in Eclipse/IntelliJ and developp the Karaf command. + +=== Create an OSGi bundle (karaf-bundle-archetype) + +This archetype creates a Maven skeleton to create an OSGi bundle, including a bundle Activator (a special callback +class for bundle start/stop). + +==== Command line + +Using the command line, we can create our project: + +---- +mvn archetype:generate \ + -DarchetypeGroupId=org.apache.karaf.archetypes \ + -DarchetypeArtifactId=karaf-bundle-archetype \ + -DarchetypeVersion=4.0.0 \ + -DgroupId=com.mycompany \ + -DartifactId=com.mycompany.bundle \ + -Dversion=1.0-SNAPSHOT \ + -Dpackage=com.mycompany.package +---- + +==== Result of Maven command execution + +---- +[INFO] Scanning for projects... +[INFO] +[INFO] ------------------------------------------------------------------------ +[INFO] Building Maven Stub Project (No POM) 1 +[INFO] ------------------------------------------------------------------------ +[INFO] +[INFO] >>> maven-archetype-plugin:2.1:generate (default-cli) @ standalone-pom >>> +[INFO] +[INFO] <<< maven-archetype-plugin:2.1:generate (default-cli) @ standalone-pom <<< +[INFO] +[INFO] --- maven-archetype-plugin:2.1:generate (default-cli) @ standalone-pom --- +[INFO] Generating project in Interactive mode +[INFO] Archetype repository missing. Using the one from [org.apache.karaf.archetypes:karaf-bundle-archetype:4.0.0] found in catalog local +[INFO] Using property: groupId = com.mycompany +[INFO] Using property: artifactId = com.mycompany.bundle +[INFO] Using property: version = 1.0-SNAPSHOT +[INFO] Using property: package = com.mycompany.package +Confirm properties configuration: +groupId: com.mycompany +artifactId: com.mycompany.bundle +version: 1.0-SNAPSHOT +package: com.mycompany.package + Y: : +[INFO] ---------------------------------------------------------------------------- +[INFO] Using following parameters for creating project from Archetype: karaf-bundle-archetype:4.0.0 +[INFO] ---------------------------------------------------------------------------- +[INFO] Parameter: groupId, Value: com.mycompany +[INFO] Parameter: artifactId, Value: com.mycompany.bundle +[INFO] Parameter: version, Value: 1.0-SNAPSHOT +[INFO] Parameter: package, Value: com.mycompany.package +[INFO] Parameter: packageInPathFormat, Value: com/mycompany/package +[INFO] Parameter: package, Value: com.mycompany.package +[INFO] Parameter: version, Value: 1.0-SNAPSHOT +[INFO] Parameter: groupId, Value: com.mycompany +[INFO] Parameter: artifactId, Value: com.mycompany.bundle +[INFO] project created from Archetype in dir: /com.mycompany.bundle +[INFO] ------------------------------------------------------------------------ +[INFO] BUILD SUCCESS +[INFO] ------------------------------------------------------------------------ +[INFO] Total time: 7.895s +[INFO] Finished at: Mon Dec 19 11:41:44 CET 2011 +[INFO] Final Memory: 8M/111M +[INFO] ------------------------------------------------------------------------ +---- + +=== Create an OSGi blueprint bundle (karaf-blueprint-archetype) + +This archetype creates a Maven skeleton project to create an OSGi blueprint bundle, including a sample bean exposed as +an OSGi service in the blueprint XML descriptor. + +==== Command line + +Using the command line, we can create our project: + +---- +mvn archetype:generate \ + -DarchetypeGroupId=org.apache.karaf.archetypes \ + -DarchetypeArtifactId=karaf-blueprint-archetype \ + -DarchetypeVersion=4.0.0 \ + -DgroupId=com.mycompany \ + -DartifactId=com.mycompany.blueprint \ + -Dversion=1.0-SNAPSHOT \ + -Dpackage=com.mycompany.blueprint +---- + +==== Result of Maven command execution + +---- +[INFO] Scanning for projects... +[INFO] +[INFO] ------------------------------------------------------------------------ +[INFO] Building Maven Stub Project (No POM) 1 +[INFO] ------------------------------------------------------------------------ +[INFO] +[INFO] >>> maven-archetype-plugin:2.1:generate (default-cli) @ standalone-pom >>> +[INFO] +[INFO] <<< maven-archetype-plugin:2.1:generate (default-cli) @ standalone-pom <<< +[INFO] +[INFO] --- maven-archetype-plugin:2.1:generate (default-cli) @ standalone-pom --- +[INFO] Generating project in Interactive mode +[INFO] Archetype repository missing. Using the one from [org.apache.karaf.archetypes:karaf-blueprint-archetype:4.0.0] found in catalog local +[INFO] Using property: groupId = com.mycompany +[INFO] Using property: artifactId = com.mycompany.blueprint +[INFO] Using property: version = 1.0-SNAPSHOT +[INFO] Using property: package = com.mycompany.package +Confirm properties configuration: +groupId: com.mycompany +artifactId: com.mycompany.blueprint +version: 1.0-SNAPSHOT +package: com.mycompany.package + Y: : +[INFO] ---------------------------------------------------------------------------- +[INFO] Using following parameters for creating project from Archetype: karaf-blueprint-archetype:4.0.0 +[INFO] ---------------------------------------------------------------------------- +[INFO] Parameter: groupId, Value: com.mycompany +[INFO] Parameter: artifactId, Value: com.mycompany.blueprint +[INFO] Parameter: version, Value: 1.0-SNAPSHOT +[INFO] Parameter: package, Value: com.mycompany.package +[INFO] Parameter: packageInPathFormat, Value: com/mycompany/package +[INFO] Parameter: package, Value: com.mycompany.package +[INFO] Parameter: version, Value: 1.0-SNAPSHOT +[INFO] Parameter: groupId, Value: com.mycompany +[INFO] Parameter: artifactId, Value: com.mycompany.blueprint +[INFO] project created from Archetype in dir: /com.mycompany.blueprint +[INFO] ------------------------------------------------------------------------ +[INFO] BUILD SUCCESS +[INFO] ------------------------------------------------------------------------ +[INFO] Total time: 1:06:36.741s +[INFO] Finished at: Mon Dec 19 13:04:43 CET 2011 +[INFO] Final Memory: 7M/111M +[INFO] ------------------------------------------------------------------------ +---- + +=== Create a features XML (karaf-feature-archetype) + +This archetype creates a Maven skeleton project which create a features XML file, using the dependencies that you define +in the POM. + +==== Command line + +Using the command line, we can create our project: + +---- +mvn archetype:generate \ + -DarchetypeGroupId=org.apache.karaf.archetypes \ + -DarchetypeArtifactId=karaf-feature-archetype \ + -DarchetypeVersion=4.0.0 \ + -DgroupId=my.company \ + -DartifactId=my.company.feature \ + -Dversion=1.0-SNAPSHOT \ + -Dpackage=my.company.package +---- + +==== Result of maven command execution + +---- +[INFO] Scanning for projects... +[INFO] +[INFO] ------------------------------------------------------------------------ +[INFO] Building Maven Stub Project (No POM) 1 +[INFO] ------------------------------------------------------------------------ +[INFO] +[INFO] >>> maven-archetype-plugin:2.1:generate (default-cli) @ standalone-pom >>> +[INFO] +[INFO] <<< maven-archetype-plugin:2.1:generate (default-cli) @ standalone-pom <<< +[INFO] +[INFO] --- maven-archetype-plugin:2.1:generate (default-cli) @ standalone-pom --- +[INFO] Generating project in Interactive mode +[INFO] Archetype repository missing. Using the one from [org.apache.karaf.archetypes:karaf-feature-archetype:4.0.0] found in catalog local +[INFO] Using property: groupId = com.mycompany +[INFO] Using property: artifactId = com.mycompany.feature +[INFO] Using property: version = 1.0-SNAPSHOT +[INFO] Using property: package = com.mycompany.package +Confirm properties configuration: +groupId: com.mycompany +artifactId: com.mycompany.feature +version: 1.0-SNAPSHOT +package: com.mycompany.package + Y: : +[INFO] ---------------------------------------------------------------------------- +[INFO] Using following parameters for creating project from Archetype: karaf-feature-archetype:4.0.0 +[INFO] ---------------------------------------------------------------------------- +[INFO] Parameter: groupId, Value: com.mycompany +[INFO] Parameter: artifactId, Value: com.mycompany.feature +[INFO] Parameter: version, Value: 1.0-SNAPSHOT +[INFO] Parameter: package, Value: com.mycompany.package +[INFO] Parameter: packageInPathFormat, Value: com/mycompany/package +[INFO] Parameter: package, Value: com.mycompany.package +[INFO] Parameter: version, Value: 1.0-SNAPSHOT +[INFO] Parameter: groupId, Value: com.mycompany +[INFO] Parameter: artifactId, Value: com.mycompany.feature +[INFO] project created from Archetype in dir: /com.mycompany.feature +[INFO] ------------------------------------------------------------------------ +[INFO] BUILD SUCCESS +[INFO] ------------------------------------------------------------------------ +[INFO] Total time: 7.262s +[INFO] Finished at: Mon Dec 19 13:20:00 CET 2011 +[INFO] Final Memory: 7M/111M +[INFO] ------------------------------------------------------------------------ +---- + +=== Create a KAR file (karaf-kar-archetype) + +This archetype creates a Maven skeleton project including a features XML sample, used to generate a KAR file. + +==== Command line + +Using the command line, we can create our project: + +---- +mvn archetype:generate \ + -DarchetypeGroupId=org.apache.karaf.archetypes \ + -DarchetypeArtifactId=karaf-kar-archetype \ + -DarchetypeVersion=4.0.0 \ + -DgroupId=com.mycompany \ + -DartifactId=com.mycompany.kar \ + -Dversion=1.0-SNAPSHOT \ + -Dpackage=com.mycompany.package +---- + +==== Result of maven command execution + +---- +[INFO] Scanning for projects... +[INFO] +[INFO] ------------------------------------------------------------------------ +[INFO] Building Maven Stub Project (No POM) 1 +[INFO] ------------------------------------------------------------------------ +[INFO] +[INFO] >>> maven-archetype-plugin:2.1:generate (default-cli) @ standalone-pom >>> +[INFO] +[INFO] <<< maven-archetype-plugin:2.1:generate (default-cli) @ standalone-pom <<< +[INFO] +[INFO] --- maven-archetype-plugin:2.1:generate (default-cli) @ standalone-pom --- +[INFO] Generating project in Interactive mode +[INFO] Archetype repository missing. Using the one from [org.apache.karaf.archetypes:karaf-kar-archetype:4.0.0] found in catalog local +[INFO] Using property: groupId = com.mycompany +[INFO] Using property: artifactId = com.mycompany.kar +[INFO] Using property: version = 1.0-SNAPSHOT +[INFO] Using property: package = com.mycompany.package +Confirm properties configuration: +groupId: com.mycompany +artifactId: com.mycompany.kar +version: 1.0-SNAPSHOT +package: com.mycompany.package + Y: : +[INFO] ---------------------------------------------------------------------------- +[INFO] Using following parameters for creating project from Archetype: karaf-kar-archetype:4.0.0 +[INFO] ---------------------------------------------------------------------------- +[INFO] Parameter: groupId, Value: com.mycompany +[INFO] Parameter: artifactId, Value: com.mycompany.kar +[INFO] Parameter: version, Value: 1.0-SNAPSHOT +[INFO] Parameter: package, Value: com.mycompany.package +[INFO] Parameter: packageInPathFormat, Value: com/mycompany/package +[INFO] Parameter: package, Value: com.mycompany.package +[INFO] Parameter: version, Value: 1.0-SNAPSHOT +[INFO] Parameter: groupId, Value: com.mycompany +[INFO] Parameter: artifactId, Value: com.mycompany.kar +[INFO] project created from Archetype in dir: /com.mycompany.kar +[INFO] ------------------------------------------------------------------------ +[INFO] BUILD SUCCESS +[INFO] ------------------------------------------------------------------------ +[INFO] Total time: 7.465s +[INFO] Finished at: Mon Dec 19 13:30:15 CET 2011 +[INFO] Final Memory: 8M/157M +[INFO] ------------------------------------------------------------------------ +---- http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/main/asciidoc/developer-guide/blueprint.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/developer-guide/blueprint.adoc b/manual/src/main/asciidoc/developer-guide/blueprint.adoc new file mode 100644 index 0000000..88abccc --- /dev/null +++ b/manual/src/main/asciidoc/developer-guide/blueprint.adoc @@ -0,0 +1,15 @@ +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +== Blueprint \ No newline at end of file http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/main/asciidoc/developer-guide/branding.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/developer-guide/branding.adoc b/manual/src/main/asciidoc/developer-guide/branding.adoc new file mode 100644 index 0000000..da2cff8 --- /dev/null +++ b/manual/src/main/asciidoc/developer-guide/branding.adoc @@ -0,0 +1,241 @@ +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +== Branding + +=== 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: + +. adding a branding.properties file to etc +. creating a branding bundle. + +=== Adding a branding.properties file to etc + +Create a `etc/branding.properties` file similar to: + +---- +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> +---- + +Start Karaf and you will see your branded Karaf console. + +=== 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: + +---- +<?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> +---- + +You can put your `branding.properties` file in the project resources (`src/main/resources/org/apache/karaf/branding/branding.properties`): + +---- +welcome = This is my Karaf brand\r\n +prompt = Hey ${USER}> +---- + +For instance, the default Apache Karaf branding properties file contains: + +---- +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 +---- + +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: + +---- +# Define a user with fancy colors +prompt = \u001B[36mmy-karaf-user\u001B[0m\u001B[1m@\u001B[0m\u001B[34m${APPLICATION}\u001B[0m> +---- + +---- +# Static sober prompt +prompt = my-user@my-karaf> +---- + +=== Installing the branding bundle + +Thanks to the `pom.xml`, we can use `mvn` to build the branding bundle: + +---- +mvn install +---- + +You just have to drop the file in the `lib` directory: + +---- +cp branding.jar /opt/apache-karaf-4.0.0/lib/karaf-branding.jar +---- + +You can now start Apache Karaf to see your branded console. + +=== 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: + +---- +# +# 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 + +---- + +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: + +---- +<?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> +---- + +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/asciidoc/developer-guide/connect.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/developer-guide/connect.adoc b/manual/src/main/asciidoc/developer-guide/connect.adoc new file mode 100644 index 0000000..98881bf --- /dev/null +++ b/manual/src/main/asciidoc/developer-guide/connect.adoc @@ -0,0 +1,96 @@ +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +== 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. + +=== 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: + +---- +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); + } + +} +---- + +=== 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: + +---- +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(); + } + +} +---- \ No newline at end of file http://git-wip-us.apache.org/repos/asf/karaf/blob/3de05ae9/manual/src/main/asciidoc/developer-guide/creating-bundles.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/developer-guide/creating-bundles.adoc b/manual/src/main/asciidoc/developer-guide/creating-bundles.adoc new file mode 100644 index 0000000..2388968 --- /dev/null +++ b/manual/src/main/asciidoc/developer-guide/creating-bundles.adoc @@ -0,0 +1,213 @@ +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +== Basic bundle creation using the Felix maven-bundle-plugin + +Create a bundle instead of a normal jar by using a Maven POM file like this: + +---- +<?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> +---- + +=== 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: + +---- +== SYNOPSIS + ${project.description} + +== DESCRIPTION + Long description of your bundle, including usage, etc. + +==SEE ALSO + [http://yourside\] + [http://yourside/docs\] +---- + +You can display this extended information using: + +---- +root@karaf> bundles:info +---- + +=== Wiki Syntax + +Karaf supports some simple wiki syntax in bundle info files: + +---- +==, ===, ... : Headings +* : Enumerations +[http://....] : links +---- + +== Creating bundles for non OSGi third party dependencies + +=== Dynamically wrapping jars + +Karaf supports the wrap: protocol execution. + +It allows for directly deploying third party dependencies, like Apache Commons Lang: + +---- +root@karaf> bundles:install wrap:mvn:commons-lang/commons-lang/2.4 +---- + +The wrap protocol creates a bundle dynamically using the bnd. Confiugurations can be added in the wrap URL: + +* from the shell + +---- +root@karaf> bundles:install 'wrap:mvn:commons-lang/commons-lang/2.4$Bundle-SymbolicName=commons-lang&Bundle-Version=2.4' +---- + +* from features.xml + +---- +<bundle>wrap:mvn:commons-lang/commons-lang/2.4$Bundle-SymbolicName=commons-lang&Bundle-Version=2.4</bundle> +---- + +=== 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: + +---- +<?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> +---- + +The resulting OSGi bundle can now be deployed directly: + +---- +root@karaf> bundles:install -s mvn:osgi.commons-lang/osgi.commons-lang/2.4 +---- \ No newline at end of file
