https://github.com/eclipse-ee4j/glassfish-spec-version-maven-plugin
API Specification Version Maven Plugin
https://github.com/eclipse-ee4j/glassfish-spec-version-maven-plugin
Last synced: 9 months ago
JSON representation
API Specification Version Maven Plugin
- Host: GitHub
- URL: https://github.com/eclipse-ee4j/glassfish-spec-version-maven-plugin
- Owner: eclipse-ee4j
- License: other
- Created: 2018-09-19T17:22:17.000Z (almost 8 years ago)
- Default Branch: master
- Last Pushed: 2025-09-26T20:55:56.000Z (9 months ago)
- Last Synced: 2025-09-26T22:27:32.558Z (9 months ago)
- Language: Java
- Homepage:
- Size: 353 KB
- Stars: 2
- Watchers: 23
- Forks: 6
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
- Notice: NOTICE.md
Awesome Lists containing this project
README
# API Specification Version Maven Plugin
The API Specification Version Plugin provides goals to set properties for manifest file OSGI headers and to verify and enforce specification properties to be compliant with [JakartaEE Maven Versioning Rules](https://wiki.eclipse.org/JakartaEE_Maven_Versioning_Rules).
**Goals:**
* `set-spec-properties` (validate phase)
* `check-module` (package phase) - enforce spec rules on a module and fail the build
* `check-distribution` (package phase) - Check a set of spec artifacts in a directory.
* `cli` (validate phase) - run spec verifications from the command line
## Spec object
Spec object is mandatory parameter of all plugin goals. But set of mandatory object properties depends on specific goal and values of `jarType` and `nonFinal` properties.
| Property | Type | Default
Value | Description |
| --- | --- | --- | --- |
| nonFinal | boolean | false | `true` for version numbers of non-final specifications`false` for version numbers of final specifications
| jarType | `api`|`impl`| `api` | `api`: specification with a separate API jar file
`impl`: specification with a standalone API jar file |
| apiPackage | java package | | primary Java package defining the API, with `javax` replaced by `jakarta` |
| implNamespace | java package | | primary Java package or namespace used by the implementation of the API, or with which the implementation of the API is associated |
| specVersion | version | | version number of the last final specification, always of the form `.` |
| newSpecVersion | version | | version number of the specification under development |
| specImplVersion | version | | version number of the API classes, derived from specVersion by adding an optional micro version number |
| implVersion | version | | version number of the implementation |
| newImplVersion | version | | version number of the implementation that will be used when the implementation is final |
| specBuild | version | | number of a particular build of the API jar file, e.g., "01", "02", etc |
| implBuild | version | | number of a particular build of the implementation jar file, e.g., "01", "02", etc. |
Version type is stored in String variables so leading zeroes won't be lost.
Properties must be encapsulated in `` section to be part of Spec object when defined in `pom.xml`, see [examples](#specification-version-plugin-configuration).
## Goal: `set-spec-properties`
Sets properties for manifest file OSGI headers.
### Properties
| Property | Type | Default
Value | Description |
| --- | --- | --- | --- |
| `spec` | object | | Required. API specification properties |
| `specMode` | `jakarta`|`javax` | `jakarta` | `jakarta`: Jakarta EE projects mode
`javaee`: legacy mode for java.net projects (deprecated) |
### Properties Mapping for `api` jarType
| Property | OSGI Header | Source |
| --- | --- | --- |
| `spec.bundle.symbolic-name` | Bundle-SymbolicName | `apiPackage` |
| `spec.bundle.spec.version`| BundleSpecVersion | `specVersion` |
| `spec.bundle.version`| Bundle-Version | `specImplVersion` |
| `spec.extension.name`| Extension-Name | `apiPackage` |
| `spec.specification.version`| Specification-Version | `specVersion` |
| `spec.implementation.version`| Implementation-Version | `specImplVersion` |
### Properties Mapping for `impl` jarType
| Property | OSGI Header | Source |
| --- | --- | --- |
| `spec.bundle.symbolic-name` | Bundle-SymbolicName | `implNamespace '.' apiPackage` |
| `spec.bundle.spec.version`| BundleSpecVersion | `specVersion` |
| `spec.bundle.version`| Bundle-Version | `implVersion` |
| `spec.extension.name`| Extension-Name | `apiPackage` |
| `spec.specification.version`| Specification-Version | `specVersion` |
| `spec.implementation.version`| Implementation-Version | `${project.version}` |
## Goal: `check-module`
Validates specification properties consistency with [Jakarta EE Maven Versioning Rules](https://wiki.eclipse.org/JakartaEE_Maven_Versioning_Rules) for a single module.
### Properties
| Property | Type | Default
Value | Description |
| --- | --- | --- | --- |
| `spec` | object | | Required. API specification properties |
| `specMode` | `jakarta`|`javax` | `jakarta` | `jakarta`: Jakarta EE projects mode
`javaee`: legacy mode for java.net projects (deprecated) |
| `module` | file | *artifact* | The module file to check |
| `ignoreErrors` | `boolean` | `false` | whether this goal should just print warnings or fail |
*artifact*: `${project.build.directory}/${project.build.finalName}.${project.packaging}` (this project's artifact file)
## Goal: `check-distribution`
Validates specification properties consistency with [Jakarta EE Maven Versioning Rules](https://wiki.eclipse.org/JakartaEE_Maven_Versioning_Rules) for a set of modules in a directory.
Only prints warnings, doesn't fail the build.
### Properties
| Property | Type | Default
Value | Description |
| --- | --- | --- | --- |
| `dir` | directory | | Required. The directory to search for module files to check |
| `specs` | list of spec objects | | Required. API specification properties |
| `includes` | `String` | `javax*.jar` | The files in the `dir` directory to include, specified using inclusion Ant patterns |
| `excludes` | `String` | | The files in the `dir` directory to exclude, specified using inclusion Ant patterns |
## Goal: `cli`
Run spec verifications from the command line. See [CommandLineMojo.java](src/main/java/org/glassfish/spec/maven/CommandLineMojo.java) for info about supported properties.
## Examples
### Specification Version Plugin Configuration
```xml
org.glassfish.build
spec-version-maven-plugin
false
api
1.1
1.1.3
jakarta.jpa
set-spec-properties
check-module
```
### OSGI Headers Generated Using `spec.` Properties
Properties with `spec.` prefix are generated by `set-spec-properties` goal.
```xml
org.apache.felix
maven-bundle-plugin
${spec.bundle.version}
${spec.bundle.symbolic-name}
${spec.extension.name}
${spec.implementation.version}
${spec.specification.version}
bundle-manifest
process-classes
manifest
```