This is an automated email from the ASF dual-hosted git repository.
stbischof pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/felix-dev.git
The following commit(s) were added to refs/heads/master by this push:
new 1c0619a05e Document satisfying condition as OSGi R8 spec-compliant
feature
1c0619a05e is described below
commit 1c0619a05ececfeb46ab02dcef9f1fbc400a4bb6
Author: copilot-swe-agent[bot] <[email protected]>
AuthorDate: Sun Nov 2 08:05:32 2025 +0000
Document satisfying condition as OSGi R8 spec-compliant feature
---
scr/README.md | 48 +++++++++++++++++++++-
scr/changelog.txt | 10 +++++
.../felix/scr/impl/metadata/ReferenceMetadata.java | 6 ++-
.../org/apache/felix/scr/impl/xml/XmlHandler.java | 12 ++++--
4 files changed, 71 insertions(+), 5 deletions(-)
diff --git a/scr/README.md b/scr/README.md
index a350e34d91..8bbf468b53 100644
--- a/scr/README.md
+++ b/scr/README.md
@@ -4,7 +4,7 @@ The Apache Felix Service Component Runtime described by the
[OSGi Declarative Se
The Java annotations defined by the specification make implementing components
easy and reduce the amount of code that needs be written. These annotations are
processed at build time and translated into XML descriptor files which in turn
are listed in the `Service-Component` header of the declaring bundle. But the
good news is, you usually don't have to worry about this XML, however in case
things don't work as expected , it's good to know how these things work.
-The Apache Felix Declarative Services implementation is the reference
implementation for the OSGi Declarative Services Specification Version 1.4 (R7)
and therefore passes the OSGi CT.
+The Apache Felix Declarative Services implementation is the reference
implementation for the OSGi Declarative Services Specification Version 1.4 (R7)
and therefore passes the OSGi CT. This implementation also includes support for
OSGi R8 features such as the Satisfying Condition specification.
## Example Usage
@@ -112,6 +112,52 @@ public Comparator(@Reference LogService logService)
}
```
+## Satisfying Condition (OSGi R8)
+
+Apache Felix SCR implements the Satisfying Condition feature as specified in
the OSGi R8 Declarative Services specification. This feature allows components
to be activated only when specific runtime conditions are met.
+
+### How It Works
+
+When the OSGi framework provides a `true` condition service (registered by the
system bundle with the property `osgi.condition.id=true`), Apache Felix SCR
automatically adds an implicit satisfying condition reference to all
components. This implicit reference:
+
+- Has the name `osgi.ds.satisfying.condition`
+- References the `org.osgi.service.condition.Condition` service
+- Uses a dynamic policy
+- Defaults to target `(osgi.condition.id=true)`
+
+### Customizing the Satisfying Condition
+
+Components can customize the satisfying condition target by setting the
`osgi.ds.satisfying.condition.target` property:
+
+```xml
+<scr:component name="my.component"
xmlns:scr="http://www.osgi.org/xmlns/scr/v1.5.0";>
+ <property name="osgi.ds.satisfying.condition.target"
value="(my.condition=ready)"/>
+ <implementation class="com.example.MyComponent"/>
+</scr:component>
+```
+
+Alternatively, components can explicitly declare the satisfying condition
reference to have full control over its configuration:
+
+```xml
+<scr:component name="my.component"
xmlns:scr="http://www.osgi.org/xmlns/scr/v1.5.0";>
+ <implementation class="com.example.MyComponent"/>
+ <reference name="osgi.ds.satisfying.condition"
+ interface="org.osgi.service.condition.Condition"
+ target="(my.custom.condition=true)"
+ policy="dynamic"/>
+</scr:component>
+```
+
+### Use Cases
+
+Satisfying conditions are useful for:
+- Delaying component activation until the system is fully initialized
+- Implementing conditional component activation based on runtime state
+- Managing component lifecycle based on external conditions
+
+For more details, see
+- [112.3.13 Satisfying
Condition](https://docs.osgi.org/specification/osgi.cmpn/8.0.0/service.component.html#service.component-satisfying.condition)
+
## Apache Maven Support
Both, the
[maven-bundle-plugin](http://felix.apache.org/documentation/subprojects/apache-felix-maven-bundle-plugin-bnd.html)
as well as the
[bnd-maven-plugin](https://github.com/bndtools/bnd/tree/master/maven) supports
processing the annotations and creating the XML component descriptors.
diff --git a/scr/changelog.txt b/scr/changelog.txt
index 73db2e4606..a9d0b19d64 100644
--- a/scr/changelog.txt
+++ b/scr/changelog.txt
@@ -1,3 +1,13 @@
+Changes in 2.2.15
+-----------------
+** Improvement
+ * Document Satisfying Condition feature as OSGi R8 specification-compliant
+ - The existing satisfying condition implementation is now documented as
compliant
+ with the preliminary OSGi R8 Declarative Services specification changes
+ - See
https://docs.osgi.org/specification/osgi.cmpn/8.0.0/service.component.html#service.component-satisfying.condition
+ - Added comprehensive documentation in README.md
+ - Updated code comments to reflect specification compliance
+
Changes in 2.2.14
-----------------
** PRs
diff --git
a/scr/src/main/java/org/apache/felix/scr/impl/metadata/ReferenceMetadata.java
b/scr/src/main/java/org/apache/felix/scr/impl/metadata/ReferenceMetadata.java
index dfaf73d042..985c8ec3d0 100644
---
a/scr/src/main/java/org/apache/felix/scr/impl/metadata/ReferenceMetadata.java
+++
b/scr/src/main/java/org/apache/felix/scr/impl/metadata/ReferenceMetadata.java
@@ -101,7 +101,11 @@ public class ReferenceMetadata
public static final String CONDITION_TRUE_FILTER =
"(osgi.condition.id=true)";
- // TODO this constant will be defined in the R8 Declarative Services spec
+ /**
+ * The reference name for the implicit satisfying condition as defined in
the
+ * OSGi R8 Declarative Services specification (see
https://github.com/osgi/osgi/pull/875).
+ * This reference is automatically added to components when a true
condition service is available.
+ */
public static final String REFERENCE_NAME_SATISFYING_CONDITION =
"osgi.ds.satisfying.condition";
// Name for the reference (required)
diff --git a/scr/src/main/java/org/apache/felix/scr/impl/xml/XmlHandler.java
b/scr/src/main/java/org/apache/felix/scr/impl/xml/XmlHandler.java
index 00a0546f37..a7588f6d68 100644
--- a/scr/src/main/java/org/apache/felix/scr/impl/xml/XmlHandler.java
+++ b/scr/src/main/java/org/apache/felix/scr/impl/xml/XmlHandler.java
@@ -483,6 +483,11 @@ public class XmlHandler extends DefaultHandler
m_pendingFactoryProperty = null;
}
}
+ // Add implicit satisfying condition reference as per OSGi R8
Declarative Services specification
+ // (see https://github.com/osgi/osgi/pull/875 and
https://github.com/osgi/osgi/issues/720).
+ // When a true condition service is available from the framework, an
implicit satisfying condition
+ // reference is automatically added to all components unless they
already explicitly declare one.
+ // This allows components to be activated only when certain runtime
conditions are met.
if (m_trueCondition != null &&
localName.equals(XmlConstants.EL_COMPONENT))
{
boolean missingSatisfyingConditionRef = true;
@@ -504,9 +509,10 @@ public class XmlHandler extends DefaultHandler
trueReference.setInterface(ReferenceMetadata.CONDITION_SERVICE_CLASS);
trueReference.setPolicy(ReferenceMetadata.POLICY_DYNAMIC);
m_currentComponent.addDependency(trueReference);
- // Here we add the target property for the implicit satisfying
condition
- // first such that any properties that are specified
explicitly can
- // be used to override this implicit property
+ // Add the target property for the implicit satisfying
condition.
+ // This is added first so that any explicitly specified
properties can
+ // override this implicit property, allowing components to
specify custom
+ // condition targets via the
osgi.ds.satisfying.condition.target property.
PropertyMetadata prop = new PropertyMetadata(true);
prop.setName(
ReferenceMetadata.REFERENCE_NAME_SATISFYING_CONDITION +
".target");
