You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@felix.apache.org by tj...@apache.org on 2021/03/05 18:33:54 UTC
[felix-atomos] branch gh-pages updated: Add initial example readmes
This is an automated email from the ASF dual-hosted git repository.
tjwatson pushed a commit to branch gh-pages
in repository https://gitbox.apache.org/repos/asf/felix-atomos.git
The following commit(s) were added to refs/heads/gh-pages by this push:
new 9558873 Add initial example readmes
9558873 is described below
commit 9558873514285bf5438e8012c8b42fd997f0cfb8
Author: Thomas Watson <tj...@us.ibm.com>
AuthorDate: Fri Mar 5 12:32:49 2021 -0600
Add initial example readmes
---
atomos.examples/README.md | 10 +++
atomos.examples/SUBSTRATE.md | 27 ++++++++
atomos.examples/atomos.examples.android/README.md | 10 +++
atomos.examples/atomos.examples.index/README.md | 15 ++++
.../atomos.examples.jaxrs.bundle/pom.xml | 79 ++++++++++++++++++++++
atomos.examples/atomos.examples.jaxrs/README.md | 11 +++
atomos.examples/atomos.examples.jlink/README.md | 37 ++++++++++
.../atomos.examples.springloader/README.md | 15 ++++
.../atomos.examples.substrate.lib/README.md | 8 +++
9 files changed, 212 insertions(+)
diff --git a/atomos.examples/README.md b/atomos.examples/README.md
new file mode 100644
index 0000000..195b368
--- /dev/null
+++ b/atomos.examples/README.md
@@ -0,0 +1,10 @@
+# Atomos Examples
+
+The following examples are available:
+1. [Atomos Index example](atomos.examples.index/README.md) - Assembles an executable JAR which uses an Atomos index for bundle entry content.
+1. [Atomos jlink example](atomos.examples.jlink/README.md) - Assembles a jlink image that loads the framework and a set of bundles as modules included in a fit for purpose JVM image
+1. [Atomos Spring Loader example](atomos.examples.springloader/README.md) - Assembles an executable JAR that uses the Spring Jar loader to load bundle content from embedded JAR files.
+1. [Atomos native-image lib folder example](atomos.examples.substrate.lib/README.md) - Assembles a native image using Graal Substrate to load the framework and a set of bundles
+1. [Atomos native-image maven plugin example](atomos.examples.substrate.maven/README.md) - Assembles a native image using Graal Substrate with the atomos-maven-plugin
+1. [Atomos Android example](atomos.examples.android/README.md) - Uses the result of the [Atomos index example](atomos.examples.index/README.md) to build an Android application
+1. [Atomos JAX-RS example](atomos.examples.jaxrs/README.md) - Uses Aries JAX-RS [whiteboard](https://github.com/apache/aries-jax-rs-whiteboard) implementation for a simple JAX-RS resource example.
diff --git a/atomos.examples/SUBSTRATE.md b/atomos.examples/SUBSTRATE.md
new file mode 100644
index 0000000..edf8d91
--- /dev/null
+++ b/atomos.examples/SUBSTRATE.md
@@ -0,0 +1,27 @@
+# Building Substrate Examples
+
+The example projects that build Graal Substrate native-images are not built as part of the main Atomos build because they require an installation of GraalVM CE 21.0.0.2 (Java 8 or Java 11 can be used) and the native-image tools for Substrate. The Java 11 version of Graal Substrate does not currently support full introspection at image runtime of the Java Platform Module System. Atomos Module support expects to have full introspection of the Java Platform Module System when running on Jav [...]
+
+To build the native image examples you must install the native image support for Graal (see https://www.graalvm.org/docs/reference-manual/native-image/). You need to run the `gu` command that comes with Graal VM:
+
+`gu install native-image`
+
+If you are using GraalVM CE 21.0.0.2 Java 11 then you can build all of Atomos, including the substrate examples, with the following single maven build using the `substrate` profile:
+
+`./mvnw clean install -Pjava8 -Psubstrate -Pequinox`
+
+There is currently an issue using GraalVM to build the jlink example image (see https://github.com/oracle/graal/issues/3090)
+that prevents running the complete build because the jlink example will fail.
+If using GraalVM CE 21.0.0.2 Java 8 then you must first use Java 11 for the main Atomos build using the Java 8 profile:
+
+`./mvnw clean install -Pjava8 -Pequinox`
+
+To use the Felix Framework use `-Pfelix` instead of `-Pequinox`
+
+Note that `install` target must be used so that Atomos is installed into your local m2 repository. This still requires Java 11 to be used to build but the result allows the `atomos.framework` JAR to be used on Java 8. Next you must switch to a Java installation of Graal with the Substrate native-image tools installed and then run the maven builds for the substrate example projects:
+
+For the [Atomos native-image lib folder example](atomos.examples.substrate.lib/README.md) a directory `target/atomos_lib/` is created. This contains all the original bundle JARs that got compiled into the native image `atomos`. In order to launch the native `atomos` you must be in the directory containing both `atomos` and the `atomos_lib/` folder. This is a simple way for Atomos to discover the available bundles and load additional bundle entries at runtime.
+
+Alternatively a substrate image can be created that does not rely on the directory `target/atomos_lib/` to discover the bundles. Instead the bundle entry resources can be placed in an `atomos/` folder which is placed on the classpath during native image compilation. The resources from the `atomos/` folder can then be included in the native image. The `atomos/` folder has a file `bundles.index` that contains information for Atomos to discover the bundles and their entries that are inclu [...]
+
+If substrate adds full introspection to the Java Platform Module System in the future it could allow Atomos to discover the modules within the image and load them as bundles. If a proper module reader could be obtained and it contains the necessary resources from the original bundle JARs then it would eliminate the need for the `atomos_lib/` or `atomos/` resource folder for running a native image.
diff --git a/atomos.examples/atomos.examples.android/README.md b/atomos.examples/atomos.examples.android/README.md
new file mode 100644
index 0000000..56b4dcd
--- /dev/null
+++ b/atomos.examples/atomos.examples.android/README.md
@@ -0,0 +1,10 @@
+# Atomos Android Example
+
+This is a very simple Android example project that can be loaded by Android Studio and/or built with `gradlew` from command line:
+
+`gradlew build`
+
+Before building the example a JAR file containing an Atomos index and set of bundles must be copied to the `app/libs` folder. For this example it is assumed you copy the executable JAR produced by the [Atomos Index example](../atomos.examples.index/README.md) into the `app/libs` folder.
+
+The build will produce an APK andoid application at `app/build/outputs/apk/debug/app-debug.apk`. This application can then be installed on an emulator or an android device. The resulting application is very simple. It has a single `Launch Atomos` button. When clicked it will launch Atomos which will automatically install and start all the bundles included in the Atomos index JAR that got copied to the `app/libs` folder. The display should indicate when Atomos has launched and give a sta [...]
+
diff --git a/atomos.examples/atomos.examples.index/README.md b/atomos.examples/atomos.examples.index/README.md
new file mode 100644
index 0000000..e8c1278
--- /dev/null
+++ b/atomos.examples/atomos.examples.index/README.md
@@ -0,0 +1,15 @@
+# Atomos Index Example
+
+This example uses the `atomos-maven-plugin` to create an Atomos index. An Atomos index contains all the bundle entry resources of the bundles that are required by the example. For this example the necessary bundles are included to have a functional Felix Gogo console and a Felix WebConsole. The Atomos index can then be included into the final JAR along with all the required packages from all the bundles included in the JAR.
+
+This example uses `maven-assembly-plugin` to package all the dependent bundles into a single executable JAR which also includes the Atomos index. The Atomos class `org.apache.felix.atomos.Atomos` is used as the `main-class` for the executable JAR. If you introspect the JAR produced by this example you will notice it includes an `atomos/` folder which includes all the bundle entry resources for all the dependent bundles. This allows for duplicate bundle entry paths to be included in the J [...]
+
+The following command should produce a gogo shell prompt:
+
+`java -jar target/org.apache.felix.atomos.examples.index-<version>.jar`
+
+Where `<version>` is the current version of this example. When executed all the bundles are loaded using the single application class loader provided by the JVM. Additional bundles can be installed, but these additional bundles will be loaded by the typical bundle class loader provided by the OSGi Framework.
+
+Once the example is launched you can access the web console with the URL [http://localhost:8080/system/console/bundles](http://localhost:8080/system/console/bundles) with the id/password of admin/admin.
+
+On its own the Atomos Index example is not that interesting. But it does open the possibility to include it in other examples that need to compose the bundles into a single artifact. For example, to produce an Android application or a native-image which includes all the bundles of your application.
\ No newline at end of file
diff --git a/atomos.examples/atomos.examples.jaxrs.bundle/pom.xml b/atomos.examples/atomos.examples.jaxrs.bundle/pom.xml
new file mode 100644
index 0000000..dba8058
--- /dev/null
+++ b/atomos.examples/atomos.examples.jaxrs.bundle/pom.xml
@@ -0,0 +1,79 @@
+<!--
+ 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.
+ -->
+<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>
+ <groupId>org.apache.felix.atomos.examples</groupId>
+ <artifactId>org.apache.felix.atomos.examples</artifactId>
+ <version>1.0.1-SNAPSHOT</version>
+ </parent>
+ <artifactId>org.apache.felix.atomos.examples.jaxrs.bundle</artifactId>
+ <name>atomos.examples.jaxrs.bundle</name>
+ <dependencies>
+ <dependency>
+ <groupId>org.osgi</groupId>
+ <artifactId>osgi.annotation</artifactId>
+ <scope>provided</scope>
+ </dependency>
+ <dependency>
+ <groupId>org.osgi</groupId>
+ <artifactId>org.osgi.service.component.annotations</artifactId>
+ <scope>provided</scope>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.geronimo.specs</groupId>
+ <artifactId>geronimo-jaxrs_2.1_spec</artifactId>
+ <version>1.1</version>
+ </dependency>
+ <dependency>
+ <groupId>org.osgi</groupId>
+ <artifactId>org.osgi.service.jaxrs</artifactId>
+ <version>1.0.0</version>
+ </dependency>
+ </dependencies>
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-compiler-plugin</artifactId>
+ <executions>
+ <execution>
+ <id>default-compile</id>
+ <configuration>
+ <release>8</release>
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
+ <plugin>
+ <groupId>biz.aQute.bnd</groupId>
+ <artifactId>bnd-maven-plugin</artifactId>
+ </plugin>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-jar-plugin</artifactId>
+ <configuration>
+ <archive>
+ <manifestFile>${project.build.outputDirectory}/META-INF/MANIFEST.MF</manifestFile>
+ </archive>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build>
+</project>
diff --git a/atomos.examples/atomos.examples.jaxrs/README.md b/atomos.examples/atomos.examples.jaxrs/README.md
new file mode 100644
index 0000000..635f639
--- /dev/null
+++ b/atomos.examples/atomos.examples.jaxrs/README.md
@@ -0,0 +1,11 @@
+# Atomos Substrate Example (atomos-maven-plugin)
+
+This example builds a native image that includes the Equinox Framework implementation with a set of bundles using Graal Substrate. See the substrate [README](../SUBSTRATE.md) for instructions on building the Substrate examples. This example uses the `atomos-maven-plugin` plugin to generate an Atomos index which is then included in the native-image. This allows for a native-image that does not require the presence of the original bundle JARs at runtime in an `atomos_lib/` folder.
+
+Buiding this example will create a folder `target/native_image_build/bin` folder that contains the executable `org.apache.felix.atomos.examples.jaxrs`. If you launch `org.apache.felix.atomos.examples.jaxrs` it will give you a gogo `g!` prompt to run gogo commands. The example itself contains a bundle that provides a JAX-RS hello resource. The resource can be accessed using `http://localhost:8080/hello/{name}`. Also included in this example is a version of the Felix web console. The web [...]
+
+This example also builds an uber JAR using the Atomos Index. This example can be run with the following command:
+
+`java -jar target/org.apache.felix.atomos.examples.jaxrs-<version>.jar`
+
+Where `<version>` is the current version of this example. The index JAR contains the same bundles as the native image and the Atomos index used for both the native and the Atomos index JAR should be the same. This can be useful when debugging the behavior difference for the native image vs. a normal Java application running on the classpath. Such an approach also makes it easy to use the Atomos index JAR to run with the Graal tracing [agent](https://medium.com/graalvm/introducing-the-t [...]
\ No newline at end of file
diff --git a/atomos.examples/atomos.examples.jlink/README.md b/atomos.examples/atomos.examples.jlink/README.md
new file mode 100644
index 0000000..f41bc55
--- /dev/null
+++ b/atomos.examples/atomos.examples.jlink/README.md
@@ -0,0 +1,37 @@
+# Atomos jlink Example
+
+This example uses `jlink` in order to build a Java image that includes a set of bundle and the modules they require from the base JVM installation. This allows for a set of bundle modules to be used to build a fit for purpose Java image that only includes the required modules from the JVM.
+
+In order to successfully build a jlink image all bundles included in the image must contain a `module-info.class`, they cannot be automatic modules. This example uses the `1.0.0.Beta2` version of the `moditect-maven-plugin` to add `module-info.class` as necessary to the bundles used in the image.
+
+When this example is built a jlink image will be created under `target/atomos`. Executing the following command against the jlink image should produce a gogo shell prompt:
+
+`./bin/atomos`
+
+You should see the following output:
+
+```
+Registered Echo service from activator.
+____________________________
+Welcome to Apache Felix Gogo
+
+g!
+```
+
+You can also load additional modules into atomos at:
+
+ - System start
+by using the `atomos.modules` option when launching `atomos`. For example:
+
+```
+atomos/bin/atomos atomos.modules=/path/to/more/modules
+```
+
+ - Runtime
+by using the gogo command `atomos:install`. For example:
+
+```
+atomos:install MyLayerName OSGI /path/to/more/modules
+```
+
+When doing that the additional modules will be loaded into a child layer where the Atomos OSGi Framework will control the class loaders. This will produce a class loader per module bundle installed. This has advantages because it allows the module class loader for the bundle to implement the `org.osgi.framework.BundleReference` interface.
\ No newline at end of file
diff --git a/atomos.examples/atomos.examples.springloader/README.md b/atomos.examples/atomos.examples.springloader/README.md
new file mode 100644
index 0000000..c0a3060
--- /dev/null
+++ b/atomos.examples/atomos.examples.springloader/README.md
@@ -0,0 +1,15 @@
+# Atomos Spring Loader Example
+
+This example uses the `spring-boot-maven-plugin` to create an executable JAR that includes each required bundle as embedded JAR files inside the single executable JAR. This executable JAR includes the `org.springframework.boot.loader` which is then used to load all the bundles included in the JAR. For this example the necessary bundles are included to have a functional Felix Gogo console and a Felix WebConsole. The Atomos index can then be included into the final JAR along with all the [...]
+
+This is not a Spring Boot example itself. It only Spring Boot loader which understands how to discover and load all the included JAR files with a single class loader. This class loader is able to load content from the embedded JAR files without requiring them to be extracted to disk first.
+
+The Atomos class `org.apache.felix.atomos.Atomos` is used as the `Start-Class` for the executable JAR. If you introspect the JAR produced by this example you will notice it includes a `BOOT-INF/lib/` folder which includes all the embedded JARs for all the dependent bundles. Atomos is able to discover all the included JARs and load the bundle entry resources from them.
+
+The following command should produce a gogo shell prompt:
+
+`java -jar target/org.apache.felix.atomos.examples.springloader-<version>.jar`
+
+Where `<version>` is the current version of this example. When executed all the bundles are loaded using the single class loader provided by the Spring loader. Additional bundles can be installed, but these additional bundles will be loaded by the typical bundle class loader provided by the OSGi Framework.
+
+Once the example is launched you can access the web console with the URL [http://localhost:8080/system/console/bundles](http://localhost:8080/system/console/bundles) with the id/password of admin/admin.
diff --git a/atomos.examples/atomos.examples.substrate.lib/README.md b/atomos.examples/atomos.examples.substrate.lib/README.md
new file mode 100644
index 0000000..8d76a5a
--- /dev/null
+++ b/atomos.examples/atomos.examples.substrate.lib/README.md
@@ -0,0 +1,8 @@
+# Atomos Substrate Example
+
+This example builds a native image that includes the framework implementation with a set of bundles using Graal Substrate. See the substrate [README](../SUBSTRATE.md) for instructions on building the Substrate examples.
+
+Buiding this example will create a `target/atomos` executable. If you launch `atomos` it will give you a gogo `g!` prompt to run gogo commands. Also included in this example is a version of the Felix web console. The web console can be access with http://localhost:8080/system/console/bundles and the id/password is admin/admin.
+
+For this example a directory `target/atomos_lib/` is created. This contains all the original bundle JARs that got compiled into the native image `atomos`. In order to launch the native `atomos` you must be in the directory containing both `atomos` and the `atomos_lib/` folder. This is a simple way for Atomos to discover the available bundles and load additional bundle entries at runtime.
+