[KARAF-3679] Karaf-EIK manual migration

manual/pom.xml

@@ -128,6 +128,36 @@
                     </dependency>
                 </dependencies>
             </plugin>
+            <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>
+                                <docVersion>${project.version}</docVersion>
+                            </attributes>
+                        </configuration>
+                    </execution>
+                </executions>
+                <configuration>
+                    <sourceDirectory>src/main/asciidoc</sourceDirectory>
+                    <outputDirectory>target/docs</outputDirectory>
+                    <headerFooter>true</headerFooter>
+                    <imagesDir>images/</imagesDir>
+                </configuration>
+            </plugin>
             <plugin>
                 <artifactId>maven-war-plugin</artifactId>
                 <version>2.1</version>
@@ -230,7 +260,43 @@
                             </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>
+                                        <docVersion>${project.version}</docVersion>
+                                    </attributes>
+                                </configuration>
+                            </execution>
+                        </executions>
+                        <configuration>
+                            <sourceDirectory>src/main/asciidoc</sourceDirectory>
+                            <outputDirectory>target/docs</outputDirectory>
+                            <headerFooter>true</headerFooter>
+                            <imagesDir>images/</imagesDir>
+                        </configuration>
+                    </plugin>
                 </plugins>
             </build>
         </profile>

manual/src/main/asciidoc/developers-guide/example.adoc

@@ -0,0 +1,55 @@
+
+= How to modify code
+
+With this example we want to show how to modify EIK.
+To do this we start by an example, we try to solve together a issue https://issues.apache.org/jira/browse/KARAF-1855.
+
+== Prerequisites
+
+For import eik project in eclipse without error we need follow the following point
+
+*Environment:*
+
+* Java SE Development Kit 1.6.x or greater (http://www.oracle.com/technetwork/java/javase/).
+* Apache Maven 3.0.3 (http://maven.apache.org/download.html).
+* Eclipse IDE Eclipse for RCP and RAP Developers (http://www.eclipse.org/downloads/packages/release/indigo/sr2).
+* Apache KARAF 2.2.x or 2.3.x (http://karaf.apache.org/index/community/download.html);
+* m2e(clipse) plugins (http://eclipse.org/m2e/)
+* Tycho Project Configurators it is downloaded automatically when inport EIK in eclipse with m2e version 0.6.0 or higher
+* WST server tools download from *Install Manager* version 3.2.100.v20110303-51EoAkF77g8HBSc or higher
+* JST Enterprise Core from *Install Manager*    3.3.0.v201102200555 or higher
+* JST Enterprise User Documentation from *Install Manager*  version  3.3.100.v201105122000-62FUGBgJ9EA9aEeHRHc or higher
+* JST Server Adapters   from *Install Manager* version 3.3.0.v201102200555 or higher
+* JST Server UI from *Install Manager* version 3.3.0.v201102200555 or higher
+* JST Server User Documentation from *Install Manager* version  3.3.100.v20110303-2-Eo7w3121162A3329 or higher
+* JST Web Core from *Install Manager*   version 3.3.0.v201103310009 or higher
+* JST Web User Documentation from *Install Manager* version 3.3.0.v201102200555-2107w31211938 or higher
+
+
+== Import EIK in eclipse
+
+From File > Import > Maven > Existing Maven Projects
+
+image::devexample_1.png[]
+
+After the development environment is ready, the class to change for resolve the issue is *NewKarafProjectWizard*.
+Goal is to advise user that the project has been created successfully and close the wizard.
+
+For do that I added a messageDialog as outlined in the code:
+
+image::devexample_4.png[]
+
+To see if the change has its effect select
+*Right click on org.apache.karaf.eik.ui  > Debug As > EclipseApplication*
+
+Create a new project as see in link:../user-guide/installation.html.adoc[installation]
+
+image::devexample_5.png[]
+
+Click Finish and message and wizard will be closed.
+
+image::devexample_6.png[]
+
+This minor change doesn't resolve the issue, but it illustrates how to test our changes on the code.
+
+

manual/src/main/asciidoc/developers-guide/index.adoc

@@ -0,0 +1,4 @@
+image::../images/karaf-logo.png[]
+= Eclipse Integration Karaf Developer Guide
+* link:/developers-guide/prerequisites.adoc[Prerequisites]
+* link:/developers-guide/example.adoc[How to modify code]

manual/src/main/asciidoc/developers-guide/prerequisites.adoc

@@ -0,0 +1,20 @@
+= Prerequisites
+
+For import eik project in eclipse without error we need follow the following point
+
+*Environment:*
+
+* Java SE Development Kit 1.6.x or greater (http://www.oracle.com/technetwork/java/javase/).
+* Apache Maven 3.0.3 (http://maven.apache.org/download.html).
+* Eclipse IDE Eclipse for RCP and RAP Developers (http://www.eclipse.org/downloads/packages/release/indigo/sr2).
+* Apache KARAF 2.2.x or 2.3.x (http://karaf.apache.org/index/community/download.html);
+* m2e(clipse) plugins (http://eclipse.org/m2e/)
+* Tycho Project Configurators it is downloaded automatically when inport EIK in eclipse with m2e version 0.6.0 or higher
+* WST server tools download from *Install Manager* version 3.2.100.v20110303-51EoAkF77g8HBSc or higher
+* JST Enterprise Core from *Install Manager*    3.3.0.v201102200555 or higher
+* JST Enterprise User Documentation from *Install Manager*  version  3.3.100.v201105122000-62FUGBgJ9EA9aEeHRHc or higher
+* JST Server Adapters   from *Install Manager* version 3.3.0.v201102200555 or higher
+* JST Server UI from *Install Manager* version 3.3.0.v201102200555 or higher
+* JST Server User Documentation from *Install Manager* version  3.3.100.v20110303-2-Eo7w3121162A3329 or higher
+* JST Web Core from *Install Manager*   version 3.3.0.v201103310009 or higher
+* JST Web User Documentation from *Install Manager* version 3.3.0.v201102200555-2107w31211938 or higher

manual/src/main/asciidoc/index.adoc

@@ -0,0 +1,7 @@
+image::images/karaf-logo.png[]
+= Apache Karaf EIK
+
+Welcome to Apache Eclipse Intergration Karaf (EIK) Subproject.
+* link:overview.adoc[Overview]
+* link:user-guide/index.adoc[User Guide]
+* link:developers-guide/index.adoc[Developers guide]

manual/src/main/asciidoc/manual.adoc

@@ -0,0 +1,44 @@
+// 
+// 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.
+// 
+= Apache Karaf-Cellar {docVersion} Guide 
+Apache Software Foundation
+:doctype: book
+:toc: left
+:toclevels: 3
+:toc-position: left
+:toc-title: Apache Karaf
+:numbered:
+:projectdir: ../../../
+:sourcedir: {projectdir}/target/test-sources
+:icons: font
+:leveloffset: 1
+
+image::karaf-logo.png[]
+
+Copyright 2008-2015 The Apache Software Foundation
+
+The PDF format of the Karaf Manual has been generated by Prince XML (http://www.princexml.com).
+
+include::overview.adoc[]
+
+include::user-guide/prerequisites.adoc[]
+include::user-guide/supportedversions.html.adoc[]
+include::user-guide/installation.adoc[]
+include::user-guide/createproject.adoc[]
+include::user-guide/launchconf.adoc[]
+include::user-guide/loadbundle.adoc[]
+include::user-guide/uninstall.adoc[]
+include::user-guide/devcomponent.adoc[]
+include::user-guide/devcomponentwithm2e.adoc[]
+include::developers-guide/example.adoc[]

manual/src/main/asciidoc/overview.adoc

@@ -0,0 +1,25 @@
+image::images/karaf-logo.png[]
+= Karaf EIK Overview
+EIK supports nearly all Apache Karaf compatible runtimes including:
+
+* Apache Karaf
+* Apache ServiceMix
+* Talend ESB
+* FUSE ESB
+
+
+Notable features include:
+
+* Custom Eclipse perspective for Apache Karaf development:
+** places valuable Karaf runtime information in one location
+* Apache Karaf installation management in your workspace:
+** Karaf installations are managed as workspace projects giving the developer visibility in to the runtime
+** each Karaf installation is automatically synchronized with your workspace, including additional bundles, configuration files
+* Run and debug Karaf installations with a single Eclipse Launcher:
+** the launch configuration allows developers to fine tune how Karaf will launch
+* Automatic deployment of workspace plugin projects:
+* create plugin-projects and have them deployed automatically
+* Advanced instrumentation of the running Karaf instance:
+** watch bundles deploy in real time and examine the OSGi service registry from within the Eclipse IDE
+* Access Eclipse platform IDE plugins from within a running Karaf instance:
+** all Eclipse plugins are presented as an OBR

manual/src/main/asciidoc/user-guide/createproject.adoc

@@ -0,0 +1,38 @@
+
+= Create a new Apache Karaf Project
+
+Create new karaf runtime with *Select File > New > Apache Karaf Installation* and add *project_name*
+
+image::createproject_1.png[]
+
+Select runtime *karaf_installation_dir* of your karaf or Servicemix  runtime
+
+image::createproject_2.png[]
+
+Doubleclick on <project_name>.target and select target platform.
+Target platform corresponds to the set of OSGi components used for development and any OSGi components defined as projects within the workspace for Example (Karaf , Servicemix, Camel , CXF ). 
+For example Eclipse PDE uses these components for compilation and checks if imports can be resolved.
+Basically is based on a directory containing these components. 
+By default, this is the plugins directory under the Eclipse installation directory, which contains all plug-ins associated with Eclipse.
+
+image::createproject_3.png[]
+
+To configure target platform there can be two approch:
+* Using the facilities provided by Eclipse PDE to specify all the components you need selecting directory ecc.ecc.
+* EIK provides preconfigured target platforms for Karaf based runtime
+
+choose the most convenient for you
+
+
+
+
+
+
+
+
+
+
+
+
+
+

manual/src/main/asciidoc/user-guide/devcomponent.adoc

@@ -0,0 +1,112 @@
+
+= Developing OSGi components with EIK
+
+This chapter describes how to develop a osgi component with EIK.
+Now we have a functional karaf environment in Eclipse, and we will illustrate howto develop a debug simple Camel route
+
+For this example we use apache servicemix 4.4.2.
+
+Using command line, we can create our project:
+----
+mvn archetype:generate \
+  -DarchetypeGroupId=org.apache.karaf.eik.archetypes \
+  -DarchetypeArtifactId=eik-camel-archetype \
+  -DarchetypeVersion=0.9.0-SNAPSHOT \
+  -DgroupId=org.apache \
+  -DartifactId=eik-camel-osgi-project \
+  -Dversion=1.0.0-SNAPSHOT 
+----
+as soon as possible this archetype will be available for m2e 
+
+
+*Additional parameters*
+
+During the maven creation process, additional questions will be asked on the console :
+
+* Define value for property 'camel-version':
+  The version of camel we want to use
+
+* Define value for property 'slf4j-version':
+  The version of slf4j we want to use
+
+*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.2:generate (default-cli) @ standalone-pom >>>
+[INFO] 
+[INFO] <<< maven-archetype-plugin:2.2:generate (default-cli) @ standalone-pom <<<
+[INFO] 
+[INFO] --- maven-archetype-plugin:2.2:generate (default-cli) @ standalone-pom ---
+[INFO] Generating project in Interactive mode
+[INFO] Archetype repository missing. Using the one from [org.apache.karaf.eik.archetypes:camel-osgi-pde-plugin:3.0.0-SNAPSHOT] found in catalog local
+[INFO] Using property: groupId = org.apache
+[INFO] Using property: artifactId = eik-camel-osgi-project
+[INFO] Using property: version = 1.0.0-SNAPSHOT
+[INFO] Using property: package = org.apache
+Define value for property 'camel-version':  ${camel-version}: : 2.8.5
+Define value for property 'slf4j-version':  ${slf4j-version}: : 1.6.1
+Confirm properties configuration:
+groupId: org.apache
+artifactId: eik-camel-osgi-project
+version: 1.0.0-SNAPSHOT
+package: org.apache
+camel-version: 2.8.5
+slf4j-version: 1.6.1
+ Y: : 
+[INFO] ----------------------------------------------------------------------------
+[INFO] Using following parameters for creating project from Archetype: camel-osgi-pde-plugin:3.0.0-SNAPSHOT
+[INFO] ----------------------------------------------------------------------------
+[INFO] Parameter: groupId, Value: org.apache
+[INFO] Parameter: artifactId, Value: eik-camel-osgi-project
+[INFO] Parameter: version, Value: 1.0.0-SNAPSHOT
+[INFO] Parameter: package, Value: org.apache
+[INFO] Parameter: packageInPathFormat, Value: org/apache
+[INFO] Parameter: camel-version, Value: 2.8.5
+[INFO] Parameter: package, Value: org.apache
+[INFO] Parameter: version, Value: 1.0.0-SNAPSHOT
+[INFO] Parameter: groupId, Value: org.apache
+[INFO] Parameter: slf4j-version, Value: 1.6.1
+[INFO] Parameter: artifactId, Value: eik-camel-osgi-project
+[INFO] project created from Archetype in dir: /projects/formazione/manual/test/eik-camel-osgi-project
+[INFO] ------------------------------------------------------------------------
+[INFO] BUILD SUCCESS
+[INFO] ------------------------------------------------------------------------
+[INFO] Total time: 13.551s
+[INFO] Finished at: Wed Oct 10 13:54:28 CEST 2012
+[INFO] Final Memory: 7M/118M
+[INFO] ------------------------------------------------------------------------
+----
+
+*Import project in eclipse*
+
+To compile and import project in Eclipse, type:
+
+mvn clean install -DskipTests=true eclipse:eclipse
+
+then import the project in Eclipse and add to MANIFEST
+
+then inport project in eclipse and add in MANIFEST
+
+* Bundle ID
+* Name
+
+image::devcomponent_1.png[]
+
+
+Using Eclipse IDE we can import package for our needs in the project, the package available are those present in target platform.
+To do that we need do double click on the MANIFEST.MF >  Dependencies you can use UI to import package
+
+EIK feature allows Automatic deployment of workspace plugin projects.
+If you check Run configurations or in Debug configurations. You will see your project
+
+image::devcomponent_2.png[]
+
+To run your application, select Debug button, wait few seconds for container startup and you will see
+
+image::devcomponent_9.png[]