Package aQute.bnd.annotation.headers

This package contains a number of annotations that create or append headers in the manifest.

See: Description

Enum Summary

Enum	Description
Category	Standard categories as specified on OSGi References Page
Resolution	Deprecated see org.osgi.annotation.bundle.Requirement.Resolution

Annotation Types Summary

Annotation Type	Description
BundleCategory	The Bundle-Category header holds a comma-separated list of category names.
BundleContributors	Maven defines contributors and developers in the POM.
BundleCopyright	The Bundle-Copyright header contains the copyright specification for this bundle.
BundleDevelopers	Maven defines developers in the POM.
BundleDocURL	The Bundle-DocURL headers must contain a URL pointing to documentation about this bundle.
BundleLicense	The Bundle-License header provides an optional machine readable form of license information.
ProvideCapability	Deprecated see org.osgi.annotation.bundle.Capability
RequireCapability	Deprecated see org.osgi.annotation.bundle.Requirement

Package aQute.bnd.annotation.headers Description

This package contains a number of annotations that create or append headers in the manifest. These annotations simplify maintaining these headers:

• The annotations can be applied on the types that are generating their need instead of maintaining them in the manifest
• Less errors because of the use of annotations
• Use of IDE features to track them or navigate

The annotations provide the following features:

• Macros - use the bnd macro preprocessor for DNRY
• Coloring - define custom annotations that encapsulate some headers
• No runtime dependencies since all annotations are build time.
• No duplicates

Macros

Any strings in the annotations are run through the bnd preprocessor and can therefore use any of the myriad of bnd macros (except system commands, for obvious reason they are excluded). As a convenience, a number of local macros are set from the context:

• ${@package} – The package name
• ${@class} – The class name to which this macro is applied to
• ${@class-short} – The short class name to which this macro is applied to
• ${@version} – The package version if set
• ${@frange;version[;isProvider]} – A macro to create a filter expression on a version based on the semantic versioning rules. Default is consumer, specify true for the isProvider to get provider semantics.

Coloring

Annotations can only be applied once, making it impossible to add for example two Provide-Capability headers on the same type. It also would become unreadable quickly. The advised way to use most of these annotation headers is therefore through 'annotation coloring'. These header annotations should be applied to custom annotations that represents the 'thing'. This is clearly represented in the BundleLicense custom annotations like for example the ASL_2_0 annotation. This annotation can be applied to any type and will automatically then create the appropriate clauses.

For example:

 public class Webserver {
   @RequireCapability(ns="osgi.extender", name="webserver", version="${@version}")
   @interface Require {}
   @ProvideCapability(ns="osgi.extender", filter="(&(osgi.extender=webserver)${@frange;${@version}}))")
   @interface Provide {}
   ...
 }
 

This resource can now be stored in a library to be used by others. If a component now wants to depend this resource, it can declare its component as follows:

 @Webserver.Require
 public class MyResource {
   ...
 }