This is an automated email from the ASF dual-hosted git repository.
cziegeler pushed a commit to branch master
in repository
https://gitbox.apache.org/repos/asf/sling-org-apache-sling-feature-extension-apiregions.git
The following commit(s) were added to refs/heads/master by this push:
new 347f4bf Update docs for using api behind toggles
347f4bf is described below
commit 347f4bf559d0247fafeda95cdb8d42b1dbfc6760
Author: Carsten Ziegeler <[email protected]>
AuthorDate: Fri Dec 4 16:51:47 2020 +0100
Update docs for using api behind toggles
---
docs/api-regions.md | 39 +++++++++++++++++++++++++++++++++++++++
1 file changed, 39 insertions(+)
diff --git a/docs/api-regions.md b/docs/api-regions.md
index 066e195..f6df2f0 100644
--- a/docs/api-regions.md
+++ b/docs/api-regions.md
@@ -66,6 +66,45 @@ If a feature exports no packages and only wants to have
visibility of packages f
]
```
+## Java API Behind a Toggle
+
+API Regions support the usage of toggles, where API can be hidden behind a
toggle and that API is only available in the region, if the toggle is enabled.
For this, a package in a region can be configured with a toggle. In this case
an object is used per package:
+
+``` json
+ "api-regions:JSON|optional" : [
+ {
+ "name": "global",
+ "exports": [
+ {
+ "name" : "org.apache.sling.api",
+ "toggle" : "SLING_API"
+ }
+ ]
+ }
+ ]
+```
+
+In the above example, the package *org.apache.sling.api* is only available if
the toggle *SLING_API* is enabled.
+
+While the above example enables a complete package based on a toggle, it is
also possible to enable a new version of an existing API with a toggle:
+
+``` json
+ "api-regions:JSON|optional" : [
+ {
+ "name": "global",
+ "exports": [
+ {
+ "name" : "org.apache.sling.api",
+ "toggle" : "NEW_SLING_API",
+ "previous" : "org.apache.sling:org.apache.sling.api:1.1"
+ }
+ ]
+ }
+ ]
+```
+
+In the above example, if the toggle *NEW_SLING_API* is enabled, the package
*org.apache.sling.api* is available based on the artifact in the feature model
providing this package. If the toggle *NEW_SLING_API* is not enabled, the
package *org.apache.sling.api* is available based on the artifact mentioned in
the `previous` property. Usually that points to an older version of the API.
+
## Deprecation of Java API
The usual process for deprecating Java API is to mark it with a corresponding
annotation and javadoc tag. However, in cases where changing the source code of
an API is not possible to add such a marker, the deprecation can be specified
through an API region. This information can be used by tooling to mark and
report usage of such API.
