Skip to content
Permalink
Browse files
Merge pull request #3 from ahus1/FELIX-5076-fix-broken-links
FELIX-5076 fix some broken links and anchors
  • Loading branch information
djencks committed Jan 3, 2022
2 parents ed37b0d + 97cedc0 commit b4ae68d3e79f363c89ade545ac61795b734565d0
Showing 13 changed files with 124 additions and 115 deletions.
@@ -186,11 +186,8 @@ Since Asciidoc has some notion of grammar, you'll need to fix the problems.

Title: ` :: replace with `= `

Error `level 0 sections can only be used when doctype is book` :: More deeply nest sections so body sections are at least `== `.
This may be facilitated in jetbrains products with an on-page regex search/replace from `
(=+ )` to `

=$1`.
Error `level 0 sections can only be used when doctype is book` :: More deeply nest sections so body sections are at least ``== ``.
This may be facilitated in jetbrains products with an on-page regex search/replace from ``(=+ )`` to `=$1`.

There are numerous classes of problems this does not cover.
The first step is probably to eliminate the command line errors/warnings.
@@ -236,7 +233,7 @@ echo '#!/bin/sh' >move-png.sh
find modules -name "*.png" -exec sh -c 'echo mkdir -p `dirname $0`\\ngit mv $0 $0' {} \; |sed 's/\([gp]\) modules\/ROOT\/pages/\1 modules\/ROOT\/images/g' >>move-png.sh
chmod u+x move-png.sh
./move-png.sh
---
----

You may need to move pngs with spaces in their filenames by hand.

@@ -44,7 +44,7 @@ The steps for granting software are a little more complicated since we need to e
For grants, you should:

. Verify that you have the authorization to donate the code.
. Review our xref:development.adoc[developer documentation] as well as the general https://www.apache.org/foundation/getinvolved.html[Apache documentation] to determine whether you would really like be involved with us and how we work.
. Review our xref:development/coding-standards.adoc[developer documentation] as well as the general https://www.apache.org/foundation/getinvolved.html[Apache documentation] to determine whether you would really like be involved with us and how we work.
. Assuming you're still interested, create a https://issues.apache.org/jira/browse/Felix[JIRA] issue describing the code you wish to donate.
. Attach an archive containing the code along with an MD5 signature of the archive to the above issue.
You should remove any existing headers from the source files and add the standard Apache header to each.
@@ -3,7 +3,7 @@


This page provides answers to frequently asked questions using the Maven SCR Plugin.
See xref:subprojects/apache-felix-maven-scr-plugin.adoc[] for documentation on that plugin.
See xref:subprojects/apache-felix-maven-scr-plugin/apache-felix-maven-scr-plugin-use.adoc[] for documentation on that plugin.

== Should I still use the Apache Felix SCR annotations over the official OSGi annotations?

@@ -335,7 +335,7 @@ The manager which is in charge of maintaining the state of components is implem
So, during activation, the component goes through a number of states, where each transition includes the invocation of the following lifecycle method callbacks on the service implementation:

* http://felix.apache.org/apidocs/dependencymanager.annotations/r13/org/apache/felix/dm/annotation/api/Init.html[@Init]: this callback is invoked after all required dependencies have been injected.
In this method, you can yet add more dynamic dependencies using the DM API, or you can possibly configure other dependencies filter and required flags (see <<# Dynamic dependency configuration,Dynamic dependency configuration>>).
In this method, you can yet add more dynamic dependencies using the DM API, or you can possibly configure other dependencies filter and required flags (see <<_dynamic_dependency_configuration,Dynamic dependency configuration>>).
* http://felix.apache.org/apidocs/dependencymanager.annotations/r13/org/apache/felix/dm/annotation/api/Start.html[@Start]: this callback is invoked after all required dependencies added in the @Init method have been injected.
* http://felix.apache.org/apidocs/dependencymanager.annotations/r13/org/apache/felix/dm/annotation/api/Registered.html[@Registered]: this callback is invoked after the service component is registered (if the component provides a service).
The callback can takes as argument a ServiceRegistration parameter.
@@ -354,7 +354,7 @@ When all required dependencies are available:
* inject all optional dependencies defined on class fields, possibly with a _NullObject_ if the dependency is not available.
* call the component init method (annotated with _@Init_, see (see http://felix.apache.org/apidocs/dependencymanager.annotations/r13/org/apache/felix/dm/annotation/api/Init.html[@Init javadoc]).).
In the init method, you are yet allowed to add some additional dependencies using the Dependency Manager API or DM Lambda).
Alternatively, you can also configure some dependencies dynamically (explained later, in <<#dynamic-dependency-configuration,Dynamic Dependency Configuration>>.
Alternatively, you can also configure some dependencies dynamically (explained later, in <<_dynamic_dependency_configuration,Dynamic Dependency Configuration>>.

2) Wait for extra required dependencies optionally configured from the init() method.
When all extra required dependencies are available:
@@ -117,6 +117,7 @@ To know when the framework has finished its shutdown sequence, use the `waitForS
A stopped framework will be in the `Bundle.RESOLVED` state.
It is possible to restart the framework, using the normal combination of `init()`/`start()` methods as previously described.

[[_launching]]
== Launching a Framework

Launching a framework is fairly simple and involves only four steps:
@@ -282,6 +283,7 @@ this is necessary because the framework never calls `System.exit()` and some lib
The framework is not active until the `start()` method is called.
If no shell bundles are installed and started or if there is difficulty locating the shell bundles specified in the auto-start property, then it will appear as if the framework is hung, but it is actually running without any way to interact with it since the shell bundles provide the only means of interaction.

[[_custom-launcher]]
=== Custom Framework Launcher

This section creates a bare-bones launcher to demonstrate the minimum requirements for creating an interactive launcher for the Felix framework.
@@ -1,16 +1,5 @@
= Apache Felix Framework Usage Documentation

* <<downloading-the-framework,Downloading the Framework>>
* <<starting-the-framework,Starting the Framework>>
* <<framework-shell,Framework Shell>>
** <<installing-bundles,Installing Bundles>>
** <<web-proxy-issues-when-installing-bundles,Web Proxy Issues when Installing Bundles>>
* <<bundle-auto-deploy,Bundle Auto-Deploy>>
* <<configuring-the-framework,Configuring the Framework>>
** <<system-property-substitution,System Property Substitution>>
* <<configuring-bundles,Configuring Bundles>>
* <<feedback,Feedback>>
== Downloading the Framework

Go to the link:{{ refs.downloads.path }}[downloads] page and download the latest Felix framework distribution.
@@ -115,7 +104,7 @@ These properties are:
this string should be the user name and password separated by a colon (e.g., `rickhall:mypassword`).

These system properties can be set directly on the command line when starting the JVM using the standard "[.code]``\-D<prop>=<value>``" syntax or you can put them in the `lib/system.properties` file of your Felix installation;
see the next section on <<configuring-the-framework,configuring Felix>> for more information.
see the next section on <<_configuring_the_framework,configuring Felix>> for more information.

== Bundle Auto-Deploy

@@ -174,7 +163,7 @@ To learn about the configuration options for specific bundles, refer to the docu
Bundle properties may also be defined in the `conf/config.properties` property file.
Any property placed in this file will be accessible via `BundleContext.getProperty()` at run time.
The property file uses the standard Java property file syntax (i.e., attribute-value pairs).
For information on changing the default location of this file, refer to the section on <<configuring-the-framework,configuring Felix>>.
For information on changing the default location of this file, refer to the section on <<_configuring_the_framework,configuring Felix>>.

== Feedback

@@ -53,28 +53,28 @@ The `CommandSession` interface provides methods for executing commands and getti

* basic commands

[source,sh]ell
[source,sh]
g! echo hello world
hello world

* session variables

[source,sh]ell
[source,sh]
g! msg = "hello world"
g! echo $msg
hello world

* execution quotes `()` - similar to bash backquotes

[source,sh]ell
[source,sh]
g! (bundle 1) location
file:/Users/derek/Downloads/felix-framework-3.0.0/bundle/org.apache.felix.bundlerepository-1.6.2.jar

=== Lists, maps, pipes and closures

* lists - `[]`

[source,sh]ell
[source,sh]
g! list = [1 2 a b]
1
2
@@ -83,23 +83,23 @@ The `CommandSession` interface provides methods for executing commands and getti

* maps - `[]`

[source,sh]ell
[source,sh]
g! map = [Jan=1 Feb=2 Mar=3]
Jan 1
Feb 2
Mar 3

* pipes - `|`

[source,sh]ell
[source,sh]
g! bundles | grep gogo
2|Active | 1|org.apache.felix.gogo.command (0.6.0)
3|Active | 1|org.apache.felix.gogo.runtime (0.6.0)
4|Active | 1|org.apache.felix.gogo.shell (0.6.0)

* closures - `{}`

[source,sh]ell
[source,sh]
g! echo2 = { echo xxx $args yyy }
g! echo2 hello world
xxx hello world yyy
@@ -108,7 +108,7 @@ The `CommandSession` interface provides methods for executing commands and getti

* exception handling - console shows summary, but full context available

[source,sh]ell
[source,sh]
g! start xxx
E: Cannot coerce start[xxx] to any of [(Bundle)]
g! $exception printstacktrace
@@ -122,7 +122,7 @@ The `CommandSession` interface provides methods for executing commands and getti

* add all public methods on `java.lang.System` as commands:

[source,sh]ell
[source,sh]
g! addcommand system (loadClass java.lang.System)
g! system:getproperties
sun.io.unicode.encodingUnicodeLittle
@@ -158,7 +158,7 @@ The `ThreadIO` service transparently manages the singleton `System.out` etc, so

then

[source,sh]ell
[source,sh]
g! each [Jan Feb Mar] { echo $it | grep . }
Jan
Feb
@@ -25,7 +25,7 @@ In and of itself the Apache Felix Inventory Printer module is independent of oth

To actually get access to the output of Inventory Printer services, though, the Apache Felix Web Console must be installed.

In the future <<gogo-shell,Integration with the Apache Felix Gogo Shell>> will also be provided in which case the Apache Felix Gogo Shell must be installed.
In the future <<_integration_with_the_apache_felix_gogo_shell,Integration with the Apache Felix Gogo Shell>> will also be provided in which case the Apache Felix Gogo Shell must be installed.

== Inventory Printer Services

@@ -49,7 +49,7 @@ It should be descriptive but short.
| `felix.inventory.printer.format`
| --
| The property defining the supported rendering formats.
The value of this property is either a string or a string array containing valid names of xref:apidocs/inventory/1.0.0/org/apache/felix/inventory/Format.html[`Format`].
The value of this property is either a string or a string array containing valid names of link:{attachmentsdir}/apidocs/inventory/1.0.0/org/apache/felix/inventory/Format.html[`Format`].
If this property is missing or contains invalid values, the printer is ignored.

| `felix.inventory.printer.webconsole`
@@ -63,7 +63,7 @@ The first three properties are required for the Inventory Printer service to be
Otherwise the service is ignored by the framework printing a message to the log.

To prevent bundle resolution failure if the `InventoryPrinter` API is not available in the framework it is suggested to register the Inventory Printer services as service factories and dynamically import the API.
See the question xref:tutorials-examples-and-presentations/apache-felix-osgi-faq.adoc#how-to-provide-optional-services[{{ ref.apache-felix-osgi-faq.title }}] in the Apache Felix OSGi FAQ for more details.
See the question xref:tutorials-examples-and-presentations/apache-felix-osgi-faq.adoc#_how_to_provide_optional_services[How to provide optional services?] in the Apache Felix OSGi FAQ for more details.

=== Example Inventory Printer Service

@@ -95,7 +95,7 @@ See the question xref:tutorials-examples-and-presentations/apache-felix-osgi-faq
}
}

See also the link:/apidocs/inventory/1.0.0/[API JavaDoc].
See also the link:{attachmentsdir}/apidocs/inventory/1.0.0/[API JavaDoc].

== ZIP Attachment Provider

@@ -22,7 +22,7 @@ TIP: http://bnd.bndtools.org/chapters/790-format.html[A complete list of instruc
== Simple Example

Rather than going straight to a detailed list of plugin features, we will first look at a simple example of how to use the plugin to give an immediate flavor.
A detailed "<<detailed-how-to,how to>>" will follow.
A detailed "<<_detailed_how_to,how to>>" will follow.

Assume that we have a simple bundle project that has a pubic API package an several implementation packages, such as:

@@ -53,14 +53,14 @@ If we also assume that we have a bundle activator in one of the implementation p
The `<Export-Package>` and `<Private-Package>` instructions tell the plugin about the contents of the resulting bundle JAR file.
The `<Export-Package>` instruction tells the plugin which of the available packages to copy into the bundle _and_ export, while the `<Private-Package>` instruction indicates which of the available packages to copy into the bundle _but not_ export.
If the two sets overlap, as they do in the case, then the export takes precedence.
Since we did not specify any values for any other bundle manifest headers, they will assume default values which are described <<default-behavior,below>>.
Since we did not specify any values for any other bundle manifest headers, they will assume default values which are described <<_default_behavior,below>>.
One specific behavior to highlight is that the plugin generates the `Import-Package` bundle manifest header based on the contents of the bundle, which means that you generally do not ever need to explicitly specify it yourself.
That's it.

== Features

The BND library underlying the plugin defines instructions to direct its behavior.
For this Maven plugin, these instructions are issued in the plugin configuration section of the POM file, as was illustrated <<simple-example,above>>.
For this Maven plugin, these instructions are issued in the plugin configuration section of the POM file, as was illustrated <<_simple_example,above>>.
BND recognizes three types of instructions:

. _Manifest headers_ - Any instruction that starts with a capital letter will appear in the resulting bundle's manifest file;
@@ -2,7 +2,7 @@

== Using the Apache Felix Maven SCR Plugin to generate Declarative Services and Metatype Service descriptors during a Maven Build

Support for automatic generation of the compenent and metadata descriptors is embeded in the `org.apache.felix:maven-scr-plugin` plugin.
Support for automatic generation of the component and metadata descriptors is embedded in the `org.apache.felix:maven-scr-plugin` plugin.
To use this plugin, it has to be declared in the project descriptor as a `<plugin>` element:
[source,xml]
<project>
@@ -69,32 +69,33 @@ If you want to process the standard annotations with the `maven-scr-plugin` add
...
</project>

These dependencies needs to be specified in order to have an easy way to opt-out the processing of one set or use other tools to process them.
These dependencies need to be specified in order to have an easy way to opt-out the processing of one set or use other tools to process them.
It's possible to specify both dependencies and use both annotations within a single project (however it's better to stay with one set).
The plugin may be configured with the following properties (Check the version column to make sure you use at least this version for the mentioned feature):

'''

*`specVersion`* + _Default_: Automatically detected + _Since_: 1.4.0 + The plugin will generate a descriptor for the Declarative Service version (e.g.
[%header,cols="2a,2a,1a,3a"]
|===
| Property | Default | Since | Description
| *`specVersion`* | Automatically detected | 1.4.0 | The plugin will generate a descriptor for the Declarative Service version (e.g.
1.0, 1.1, or 1.2).
If no value is specified, the plugin will detect the version and only use 1.1 if features from this version are used.
--- *`generateAccessors`* + _Default_: `true` + _Since_: + If this switch is turned on, the bind and unbind methods for unary references are automatically generated by the plugin.
--- *`scanClasses`* + _Default_: `false` + _Since_: 1.9.0 + By default the plugin scans the java source tree, if this is set to `true`, the generated classes directory is scanned instead.
--- *`sourceIncludes`* + _Default_: `true` + _Since_: 1.7.4 + Comma separated list of classes to include when processing the source.
--- *`sourceExcludes`* + _Default_: `true` + _Since_: + Comma separated list of classes to exclude when processing the source.
--- *`strictMode`* + _Default_: `false` + _Since_: + The plugin distinguishes between errors and warnings.
| *`generateAccessors`* | `true` | | If this switch is turned on, the bind and unbind methods for unary references are automatically generated by the plugin.
| *`scanClasses`* | `false` | 1.9.0 | By default the plugin scans the java source tree, if this is set to `true`, the generated classes directory is scanned instead.
| *`sourceIncludes`* | `true` | 1.7.4 | Comma separated list of classes to include when processing the source.
| *`sourceExcludes`* | `true` | | Comma separated list of classes to exclude when processing the source.
| *`strictMode`* | `false` | | The plugin distinguishes between errors and warnings.
In strict mode warnings are treated as errors and cause the plugin to fail.
--- *`properties`* + _Default_: None + _Since_: 1.2.0 + A map of predefined properties.
| *`properties`* | None | 1.2.0 | A map of predefined properties.
These properties are set to each component (if the component does not define the property already).
This is a map where the property name is made up by the included element name and the value is the value of the element.
--- *`outputDirectory`* + _Default_: `${project.build.outputDirectory}` + _Since_: 1.0.0 + The directory where all files are generated in.
--- *`supportedProjectTypes`* + _Default_: `jar, bundle` + _Since_: 1.8.0 + Project types which this plugin supports.
---
| *`outputDirectory`* | `${project.build.outputDirectory}` | 1.0.0 | The directory where all files are generated in.
| *`supportedProjectTypes`* | `jar, bundle` | 1.8.0 | Project types which this plugin supports.
|===

The metatype files are generated in the `OSGI-INF/metatype/` directory and the Declarative Services descriptor files in the `OSGI-INF` directory.

The plugin will look for component annotations in all Java files found in the source directories of the project unless the `scanClasses` property indicates the class files are to be scanned instead.
This is usefull if the annotations are actually defined in JVM-based languages such as Groovy or Scala.
This is useful if the annotations are actually defined in JVM-based languages such as Groovy or Scala.

== Using the descriptor

0 comments on commit b4ae68d

Please sign in to comment.