Hi all,
due to a private need I implemented a tool that, as a Sling committer, I
would like to promote inside this community in order to have it as a public
domain.
The basic idea is to automate the production of documentation, providing to
both developers and customers a centralised documentation of all HTTP entry
points and Metatype configurations.
Advantages are:
* for an internal use, having such catalogue could reduce the development
efforts, maybe there are services already available for certain operations
that don’t need to be re-implemented; moreover, it can improve/simplify
heterogeneous teams integration work.
* from customers point of view, it would be good to know what solutions
are already offered, to develop their solution on top of our framework;
moreover, under a security PoV, admins have to be aware which are potential
entry-points that can be attacked.
How it works: it is a plain Java8 annotations processor, able to generate
documentations for:
* SlingServlet annotated components;
* (Deprecated) Felix SCR annotations (we still have lot of components in
the repo which use such annotations, i.e. Apache Sling Distribution Core)
* OSGi Component/Metatype annotations
All documentations are produced in Markdown format (intermediate metadata
formats are produced already by existing Maven plugins, so no
XML/JSON/YAML/...) and I tested initially in the
org-apache-sling-distribution-core[1], producing the output below:
sling-org-apache-sling-distribution-core stripodi$ tree target/docgen/
target/docgen/
├── metatype
│ └── org
│ └── apache
│ └── sling
│ └── distribution
│ ├── agent
│ │ └── impl
│ │ ├── ForwardDistributionAgentFactory.md
│ │ ├──
PrivilegeDistributionRequestAuthorizationStrategyFactory.md
│ │ ├── QueueDistributionAgentFactory.md
│ │ ├── ReverseDistributionAgentFactory.md
│ │ ├── SimpleDistributionAgentFactory.md
│ │ └── SyncDistributionAgentFactory.md
│ ├── component
│ │ └── impl
│ │ ├── DefaultDistributionComponentProvider.md
│ │ ├── DefaultDistributionConfigurationManager.md
│ │ └── DistributionComponentFactoryMap.md
│ ├── event
│ │ └── impl
│ │ └── DefaultDistributionEventFactory.md
│ ├── impl
│ │ └── DefaultDistributor.md
│ ├── monitor
│ │ └── DistributionQueueHealthCheck.md
│ ├── packaging
│ │ └── impl
│ │ ├── exporter
│ │ │ ├──
AgentDistributionPackageExporterFactory.md
│ │ │ ├──
LocalDistributionPackageExporterFactory.md
│ │ │ └──
RemoteDistributionPackageExporterFactory.md
│ │ └── importer
│ │ ├──
LocalDistributionPackageImporterFactory.md
│ │ ├──
RemoteDistributionPackageImporterFactory.md
│ │ └──
RepositoryDistributionPackageImporterFactory.md
│ ├── resources
│ │ └── impl
│ │ ├──
DistributionConfigurationResourceProviderFactory.md
│ │ └──
DistributionServiceResourceProviderFactory.md
│ ├── serialization
│ │ └── impl
│ │ ├── DefaultDistributionPackageBuilderProvider.md
│ │ ├── DistributionPackageBuilderFactory.md
│ │ └── vlt
│ │ └──
VaultDistributionPackageBuilderFactory.md
│ ├── servlet
│ │ └── DistributionAgentCreationFilter.md
│ ├── transport
│ │ └── impl
│ │ └──
UserCredentialsDistributionTransportSecretProvider.md
│ └── trigger
│ └── impl
│ ├──
DistributionEventDistributeDistributionTriggerFactory.md
│ ├── JcrEventDistributionTriggerFactory.md
│ ├──
PersistedJcrEventDistributionTriggerFactory.md
│ ├── RemoteEventDistributionTriggerFactory.md
│ ├── ResourceEventDistributionTriggerFactory.md
│ └── ScheduledDistributionTriggerFactory.md
└── servlets
└── org
└── apache
└── sling
└── distribution
└── servlet
├── DistributionAgentLogServlet.md
├── DistributionAgentQueueServlet.md
├── DistributionAgentServlet.md
├── DistributionPackageExporterServlet.md
├── DistributionPackageImporterServlet.md
└── DistributionTriggerServlet.md
33 directories, 37 files
Where a metatype output looks like:
sling-org-apache-sling-distribution-core stripodi$ cat
target/docgen/metatype/org/apache/sling/distribution/serialization/impl/vlt/VaultDistributionPackageBuilderFactory.md
#
org.apache.sling.distribution.serialization.impl.vlt.VaultDistributionPackageBuilderFactory
## Label
Apache Sling Distribution Packaging - Vault Package Builder Factory
## Description
OSGi configuration for vault package builders
## Configuration Policy
REQUIRE
## Declarative Services specification
1.1
## Implemented services
* org.apache.sling.distribution.packaging.DistributionPackageBuilder
## Properties
| ID | Name | Description | Cardinality | Unbound | Options | Default
value(s) |
| --- | ---- | ----------- | ----------: | ------- | ------- |
---------------: |
| `webconsole.configurationFactory.nameHint` | | | `0` | `DEFAULT` | `[]`
| `[Builder name: {name}]` |
| `name` | Name | The name of the package builder. | `0` | `DEFAULT` | `[]`
| `[]` |
| `type` | type | The type of this package builder | `0` | `DEFAULT` |
`[jcr packages, file packages, in memory packages]` | `[jcrvlt]` |
| `importMode` | Import Mode | The vlt import mode for created packages. |
`0` | `DEFAULT` | `[]` | `[]` |
| `aclHandling` | Acl Handling | The vlt acl handling mode for created
packages. | `0` | `DEFAULT` | `[]` | `[]` |
| `package.roots` | Package Roots | The package roots to be used for
created packages. (this is useful for assembling packages with an user that
cannot read above the package root) | `0` | `DEFAULT` | `[]` | `[]` |
| `package.filters` | Package Node Filters | The package node path filters.
Filter format: path|+include|-exclude | `100` | `DEFAULT` | `[]` | `[]` |
| `property.filters` | Package Property Filters | The package property path
filters. Filter format: path|+include|-exclude | `0` | `ARRAY` | `[]` |
`[]` |
| `tempFsFolder` | Temp Filesystem Folder | The filesystem folder where the
temporary files should be saved. | `0` | `DEFAULT` | `[]` | `[]` |
| `useBinaryReferences` | Use Binary References | If activated, it avoids
sending binaries in the distribution package. | `0` | `DEFAULT` | `[]` |
`[false]` |
| `autoSaveThreshold` | Autosave threshold | The value after which autosave
is triggered for intermediate changes. | `0` | `DEFAULT` | `[]` | `[-1]` |
| `cleanupDelay` | The delay in seconds between two runs of the cleanup
phase for resource persisted packages. | The resource persisted packages
are cleaned up periodically (asynchronously) since SLING-6503.The delay
between two runs of the cleanup phase can be configured with this setting.
60 seconds by default | `0` | `DEFAULT` | `[]` | `[60]` |
| `fileThreshold` | File threshold (in bytes) | Once the data reaches the
configurable size value, buffering to memory switches to file buffering. |
`0` | `DEFAULT` | `[]` | `[1]` |
| `MEGA_BYTES` | The memory unit for the file threshold | The memory unit
for the file threshold, Megabytes by default | `0` | `DEFAULT` | `[Bytes,
Kilobytes, Megabytes, Gigabytes]` | `[MEGA_BYTES]` |
| `useOffHeapMemory` | Flag to enable/disable the off-heap memory | Flag to
enable/disable the off-heap memory, false by default | `0` | `DEFAULT` |
`[]` | `[false]` |
| `digestAlgorithm` | The digest algorithm to calculate the package
checksum | The digest algorithm to calculate the package checksum,
Megabytes by default | `0` | `DEFAULT` | `[Do not send digest, md2, md5,
sha1, sha256, sha384, sha512]` | `[NONE]` |
| `monitoringQueueSize` | The number of items for monitoring distribution
packages creation/installation | The number of items for monitoring
distribution packages creation/installation, 100 by default | `0` |
`DEFAULT` | `[]` | `[0]` |
| `pathsMapping` | Paths mapping | List of paths that require be mapped.The
format is {sourcePattern}={destinationPattern}, e.g. /etc/(.*)=/var/$1/some
or simply /data=/bak | `100` | `DEFAULT` | `[]` | `[]` |
| `strictImport` | Install a content package in a strict mode | Flag to
mark an error response will be thrown, if a content package will
incorrectly installed | `0` | `DEFAULT` | `[]` | `[true]` |
and a servlet output looks like:
$ cat
target/docgen/servlets/org/apache/sling/distribution/servlet/DistributionPackageExporterServlet.md
# org.apache.sling.distribution.servlet.DistributionPackageExporterServlet
### Supported HTTP Methods
* POST
### Resource types
* sling/distribution/service/exporter
You can use an online Markdown editor[2] in order to have an idea how pages
could look alike.
Enabling it is very simple, just add in the pom.xml file the following
snippet:
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<configuration>
<generatedSourcesDirectory>
${project.build.directory}/docgen/</generatedSourcesDirectory>
<annotationProcessorPaths>
<annotationProcessorPath>
<groupId>org.apache.sling</groupId>
<artifactId>org.apache.sling.tools.docgen</
artifactId>
<version>0.0.1-SNAPSHOT</version>
</annotationProcessorPath>
</annotationProcessorPaths>
</configuration>
</plugin>
Where processor GAVs are merely for the PoC.
I packaged already all the sources in order to be donated to the ASF, I
just would like to start the discussion in order to understand if the
community is interested on that tool and which steps are required in order
to have it accepted.
Any feedback/suggestion/hint/... will be much more than appreciated, many
thanks in advance!
All the best,
~Simo
[1] https://github.com/apache/sling-org-apache-sling-distribution-core
[2] https://dillinger.io/
http://people.apache.org/~simonetripodi/
http://twitter.com/simonetripodi
