public class BundleUpgradeParser
extends java.lang.Object
Modifier and Type | Class and Description |
---|---|
static class |
BundleUpgradeParser.CatalogUpgrades
The result from parsing bundle(s) to find their upgrade info.
|
static class |
BundleUpgradeParser.VersionRangedName
Records a name (string) and version range (string),
with conveniences for pretty-printing and converting to OSGi format.
|
Modifier and Type | Field and Description |
---|---|
static java.lang.String |
MANIFEST_HEADER_FORCE_REMOVE_BUNDLES
A header in a bundle's manifest, indicating that this bundle will force the removal of matching
bundle(s) previously added and the types they contain.
|
static java.lang.String |
MANIFEST_HEADER_FORCE_REMOVE_LEGACY_ITEMS
A header in a bundle's manifest, indicating that this bundle will force the removal of the
given legacy catalog items.
|
static java.lang.String |
MANIFEST_HEADER_UPGRADE_FOR_BUNDLES
A header in a bundle's manifest, indicating that this bundle recommends a set of upgrades.
|
static java.lang.String |
MANIFEST_HEADER_UPGRADE_FOR_TYPES
A header in a bundle's manifest, indicating that this bundle recommends a set of upgrades.
|
Constructor and Description |
---|
BundleUpgradeParser() |
Modifier and Type | Method and Description |
---|---|
static BundleUpgradeParser.CatalogUpgrades |
parseBundleManifestForCatalogUpgrades(org.osgi.framework.Bundle bundle,
<any> typeSupplier) |
public static final java.lang.String MANIFEST_HEADER_FORCE_REMOVE_LEGACY_ITEMS
name:versionRange
, eg "my-tomcat:[0,1)"
;
see MANIFEST_HEADER_FORCE_REMOVE_BUNDLES
for more information
*
means all legacy items for things defined in this bundle, with version
numbers lower than the version of the bundle,
and quoted *:versionRange
means the indicated version(s) of types in this bundle.
For example, if the bundle is version 1.0.0 and its catalog.bom contains items "foo" and "bar", then
*
is equivalent to writing "foo:[0,1.0.0)","bar:[0,1.0.0)"
.
As per the comments on MANIFEST_HEADER_FORCE_REMOVE_BUNDLES
,
the version of the bundle and items being added by a bundle to replace legacy catalog items
should typically be larger in major/minor/point value,
as a qualifier bump can be quite complex due to ordering differences.
"my-tomcat:[0,1)","my-nginx:[0,1)"
;
see MANIFEST_HEADER_FORCE_REMOVE_BUNDLES
for more information
public static final java.lang.String MANIFEST_HEADER_FORCE_REMOVE_BUNDLES
name:versionRange
, where version range follows the OSGi conventions
(except that a single version number means exactly that version rather than greater
than or equal to that version). For example, "org.example.mybundle:[0,1)"
.
Note in particular this uses OSGi ordering semantics not Brooklyn ordering semantics,
so qualifiers come after unqualified versions here, snapshot is not special-cased,
and qualifiers (last/fourth segment) are compared alphabetically
(thus "1.0" < "1.0.0.GA" < "1.0.0.SNAPSHOT" < "1.0.0.v10" < "1.0.0.v2" --
but they are the same with respect to major/minor/point numbers so if in doubt stick with those!).
Thus if using a range it is generally recommended to use a "[" square bracket start and ")" round bracket end
so that the start is inclusive and end exclusive, and any edge cases explicitly referenced.
If you want to replace a SNAPSHOT or RC version with a GA version you will need to call this out specially,
as described in the "comma-separated list" format below.
This is good anyway because there are different conventions for release names
(e.g. "1.0.0" or "1.0.0.GA" or "1.0.0.2017-12") and any automation here is likely to cause surprises.
*
as an entry, meaning all lower versions of this bundle,
or quote *:versionRange
, meaning the given version range on this bundle.
For example, if the bundle is org.example.mybundle:1.0.0
,
then *
is equivalent to writing "org.example.mybundle:[0,1.0.0)"
and "*:1-SNAPSHOT"
is equivalent to writing "org.example.mybundle:1-SNAPSHOT"
(which when converted to OSGi is equivalent to "org.example.mybundle:1.0.0.SNAPSHOT"
)
"org.example.mybundle:[0,1)","org.example.myotherbundle:[0,1)"
(useful for
when this bundle merges the contents of two previous bundles), or
"*","*:1.0.0.SNAPSHOT","*:1.0.0.rc1"
when releasing org.example.mybundle:1.0.0.GA
(to replace versions pre 1.0.0 as well as a snapshot and an rc1)
public static final java.lang.String MANIFEST_HEADER_UPGRADE_FOR_BUNDLES
key=value
pairs, where each key is a name with a version range
(as per MANIFEST_HEADER_FORCE_REMOVE_BUNDLES
) specifying what should be upgraded, and value
is a name and
version specifying what it should be upgraded to. The =value
can be omitted, and usually is,
to mean this bundle at this version. (The =value
is available if one bundle is defining upgrades for other bundles.)
A wildcard can be given as the key, without a version (*
) or with (*:[0,1)
) to refer to
all previous versions (OSGi ordering, see below) or the indicated versions, respectively, of the bundle this manifest is defining.
If this header is supplied and MANIFEST_HEADER_UPGRADE_FOR_TYPES
is omitted, the types to upgrade are inferred as
being all types defined in the bundle this manifest is defining, and all versions of this bundle upgraded by this bundle
according to this header. If this header is included but does not declare any versions of this bundle upgraded by this bundle,
then MANIFEST_HEADER_UPGRADE_FOR_TYPES
must be explicitly set.
Version ordering may be surprising particularly in regard to qualifiers.
See MANIFEST_HEADER_FORCE_REMOVE_BUNDLES
for discussion of this.
In most use cases, one can provide a single line, e.g. if releasing a v2.0.0:
Brooklyn-Catalog-Upgrade-For-Bundles: *:[0,2)
to indicate that this bundle is able to upgrade all instances of this bundle lower than 2.0.0,
and all types in this bundle will upgrade earlier types.
This can be used in conjunction with:
Brooklyn-Catalog-Force-Remove-Bundles: *:[0,2)
to forcibly remove older bundles at an appropriate point (eg a restart) and cause all earlier instances of the bundle
and the type instances they contain to be upgraded with the same-named types in the 2.0.0 bundle.
It is not necessary to supply MANIFEST_HEADER_UPGRADE_FOR_TYPES
unless types are being renamed
or versions are not in line with previous versions of this bundle.
public static final java.lang.String MANIFEST_HEADER_UPGRADE_FOR_TYPES
MANIFEST_HEADER_UPGRADE_FOR_BUNDLES
, with two differences in interpretation.
If =value
is omitted, the upgrade target is assumed to be the same type as the corresponding key but at the
version of the bundle.
A wildcard can be given as the key, without a version (*
) or with (*:[0,1)
) to refer to
all types in the present bundle.
If the version/range for a type is omitted in any key, it is inferred as the versions of this bundle
that this bundle declares it can upgrade in the MANIFEST_HEADER_UPGRADE_FOR_BUNDLES
header.
It is an error to omit a version/range if that header is not present or does not declare versions
of the same bundle being upgraded.
If this key is omitted but a MANIFEST_HEADER_UPGRADE_FOR_BUNDLES
header is present defining
versions of the containing bundle that are upgraded, then the default is *
to give the common semantics
when a bundle is upgrading previous versions that types similarly upgrade. If that header is absent or
this bundle is an upgrade for other bundles but not this bundle, then this key must be specified if
any types are intended to be upgraded.
What this is saying in most cases is that if a bundle foo:1
contains foo-node:1
, and
bundle foo:2
contains foo-node:2
, then:
if foo:2
declares Brooklyn-Catalog-Upgrade-For-Bundles: foo:1
it will also declare that
foo-node:2
upgrades foo-node:1
;
if foo:2
declares Brooklyn-Catalog-Upgrade-For-Bundles: *
the same thing will occur
(and it would also upgrade a foo:0
contains foo-node:0
);
if foo:2
declares no Brooklyn-Catalog-Upgrade-*
manifest headers, then no advisory
upgrades will be noted.
As noted in MANIFEST_HEADER_UPGRADE_FOR_BUNDLES
the primary use case for this header is type renames.public static BundleUpgradeParser.CatalogUpgrades parseBundleManifestForCatalogUpgrades(org.osgi.framework.Bundle bundle, <any> typeSupplier)