documentation/src/content/winegrower-knight.adoc

////
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.
////
= Arthur Winegrower Knights

Arthur Winegrower knight is responsible to support Winegrower.
It preconfigures the reflection and resource inclusion.

It generally assumes you have `winegrower-core` in your project dependencies.
Here is a sample dependencies block for a simple SCR application:

[source,xml]
----
<dependencies>
  <dependency>
    <groupId>org.osgi</groupId>
    <artifactId>osgi.core</artifactId>
    <version>${osgi.version}</version>
  </dependency>
  <dependency>
    <groupId>org.osgi</groupId>
    <artifactId>osgi.cmpn</artifactId>
    <version>${osgi.version}</version>
  </dependency>
  <dependency>
    <groupId>org.apache.felix</groupId>
    <artifactId>org.apache.felix.scr</artifactId>
    <version>${felix-scr.version}</version>
  </dependency>
  <dependency>
    <groupId>org.slf4j</groupId>
    <artifactId>slf4j-simple</artifactId>
    <version>${slf4j.version}</version>
  </dependency>
  <dependency>
    <groupId>org.apache.winegrower</groupId>
    <artifactId>winegrower-core</artifactId>
    <version>${winegrower.version}</version>
  </dependency>
</dependencies>
----

== Coordinates

[source,xml]
----
<dependency>
  <groupId>org.apache.geronimo.arthur.knights</groupId>
  <artifactId>winegrower-knight</artifactId>
  <version>${arthur.version}</version>
</dependency>
----

== Usage

To make a winegrower application compatible with `native-image` there are a few necessary steps to do:

. Ensure OSGi metadata (SCR, blueprint etc) descriptors are generated,
. Ensure Winegrower runs in metadata mode, i.e. it does not require to inspect files anymore to find `MANIFEST.MF` files and `OSGI-INF` descriptors,
. Ensure the SCR, blueprint, ... reflection model is registered.

The `winegrower-knight` handles all but the first point which is still done through `bnd-tool` or `maven-bundle-plugin`.
Here is a definition to generate the `META-INF/MANIFEST.MF` correctly:

[source,xml]
----
<plugin>
  <groupId>org.apache.felix</groupId>
  <artifactId>maven-bundle-plugin</artifactId>
  <version>${maven-bundle.version}</version>
  <extensions>true</extensions>
  <executions>
    <execution>
      <id>manifest</id>
      <phase>process-classes</phase>
      <goals>
        <goal>bundle</goal>
      </goals>
      <configuration>
        <exportScr>true</exportScr>
      </configuration>
    </execution>
  </executions>
</plugin>
----

Then, to generate `winegrower` metadata you can either use the related plugin or let the extension do (default).
If you decide to use the plugin you must define it like that:

[source,xml]
----
<plugin>
  <groupId>org.apache.winegrower</groupId>
  <artifactId>winegrower-maven-plugin</artifactId>
  <version>${winegrower.version}</version>
  <executions>
    <execution>
      <id>metadata</id>
      <phase>process-classes</phase>
      <goals>
        <goal>metadata</goal>
      </goals>
      <configuration>
        <autoFiltering>true</autoFiltering> <!-- enables to reduce the number of generated metadata, it is generally enough -->
        <excludeArtifacts> <!-- xbean will be in the classpath but not needed by most applications -->
          <excludeArtifact>xbean-finder-shaded</excludeArtifact>
        </excludeArtifacts>
      </configuration>
    </execution>
  </executions>
</plugin>
----

And to deactivate the extension metadata generation you must add an extension property:

[source,xml]
----
<plugin>
  <groupId>${project.groupId}</groupId>
  <artifactId>arthur-maven-plugin</artifactId>
  <version>${project.version}</version>
  <configuration>
    <!-- .... -->
    <extensionProperties>
      <extension.winegrower.metadata.generate>false</extension.winegrower.metadata.generate>
    </extensionProperties>
  </configuration>
</plugin>
----

Finally, whatever way you picked to generate metadata, you must register the winegrower knight in `arthur-maven-plugin`:


[source,xml]
----
<plugin>
  <groupId>org.apache.geronimo.arthur</groupId>
  <artifactId>arthur-maven-plugin</artifactId>
  <version>${arthur.version}</version>
  <configuration>
    <main>org.company.osgi.ScrMain</main>
    <graalExtensions>
      <graalExtension>winegrower</graalExtension>
    </graalExtensions>
  </configuration>
</plugin>
----

== Configuration

This knight has several configuration options:

[opts="header",role="table table-bordered",cols="2,1,3"]
|===
|Name|Type|Description
a|`extension.winegrower.[includes\|excludes]`|String|Comma separated values for scanning filter. It acts on the filename and matches prefixes.
a|`extension.winegrower.metadata.generate`|boolean|Should the winegrower metadata be automatically generated, default to true.
a|`extension.winegrower.metadata.autoFiltering`|boolean|Should winegrower metadata generation use autofiltering to reduce the number of metadata, default to true.
a|`extension.winegrower.metadata.defaultJarName`|String|What name to use for the exploded classpath folder of the module (`target/classes`), default to module folder name.
|===

---

Previous: link:knights.html[Knights]