jsedding commented on code in PR #2952:
URL: https://github.com/apache/jackrabbit-oak/pull/2952#discussion_r3402973539
##########
oak-doc/src/site/markdown/osgi_config.md:
##########
@@ -500,6 +500,31 @@ in both config file and framework properties then
framework property takes prece
For example by default Sling sets **repository.home** to
_${sling.home}/repository_. So this value
need not be specified in config files
+#### Feature Toggles
+
+The **Feature Toggle** mechanism enables the safe rollout, testing, and
management of internal repository features.
+It allows new functionality, experimental logic, or performance optimizations
to be shielded behind conditional
+switches that can be controlled at runtime without requiring a repository
restart.
+
+##### Core Architecture
+
+Built upon the **Whiteboard** (the internal service registry), the system
relies on the `FeatureToggle` interface
+from the `org.apache.jackrabbit.oak.spi.toggle` package.
+
+
+* **Registration:** Components register a `FeatureToggle` instance into the
Whiteboard with a unique name.
+* **Consumption:** Dependent repository logic queries the Whiteboard to check
`isEnabled()` before executing the toggled code paths.
+
+**Note:** The Whiteboard is primarily needed as a lookup service. Code that
already has direct access to the
+`FeatureToggle` instance - such as in test cases - does not need to look it up.
Review Comment:
```suggestion
##### Core Architecture
The `org.apache.jackrabbit.oak.spi.toggle.FeatureToggle` class encapsulates
the concept
of a named boolean flag. The code behind the toggle normally only needs
access to the
boolean; the name is used to identify the correct `FeatureToggle` and to
change the value
of the boolean flag. The boolean is represented by java's `AtomicBoolean`
class.
`FeatureToggle` instances are meant to be registered with a **Whiteboard**,
Oak's internal
service registry abstraction. This allows `FeatureToggle` instances to be
discovered by
third party code. E.g. in order to enable/disable the toggle using its
`#setEnabled(boolean)`
method.
* **Registration:** Components register a `FeatureToggle` instance into the
Whiteboard with
* a unique name.
* **Consumption:** Dependent repository logic usually only needs access to
the
* `AtomicBoolean` instance, which allows to keep implementations agnostic of
the
* `FeatureToggle` API.
**Note:** Code that already has direct access to the `AtomicBoolean` or to
the `FeatureToggle`
instance - such as test cases - does not require a lookup via the
`Whiteboard`.
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
