Support generation of eclipse-feature as resources

[laeubi]

Proposal

I'm currently in the process of transition Tycho/P2/PDE to using the the OSGi Resource/Repository API instead of the various legacy APIs.

While it is quite comfortable to transform a bundle into a Resource e.g. using

ResourceBuilder rb = new ResourceBuilder();
Domain manifest = Domain.domain(file);
if (manifest != null && rb.addManifest(manifest)) {
	rb.addContentCapability(uri, SHA256.digest(file).asHex(), file.length(), MIME_TYPE_BUNDLE);
	... perform other cool stufff ...
	return rb.build();
}

something similar is not possible for eclipse-features.
The general concept of Eclipse-Features is described here:

• Feature Overview
• Feature Information
• Included Plug-ins
• Included Features
• Feature Dependencies
• Feature Installation

As sooner or later this will become prominent i'd like to suggest to add support to the BND ResourceBuilder so such features can be handled with maximum interoperability instead of risk having multiple competing implementations that slightly differ.

As a feature is just an XML document I would like to suggest the following signature for such a method:

/**
 * Interpret the given document as containing an eclipse-feature as described 
 * <a href="https://help.eclipse.org/latest/topic/org.eclipse.pde.doc.user/guide/tools/editors/feature_editor/feature_editor.htm">here</a> 
 * and transform it into a resource
 * @param document the document to be used as an eclipse-feature
 * 
 * @return <code>true</code> if this was successful and parsed as a valid feature, <code>false</code> otherwise
 */
public boolean addEclipseFeature(org.w3c.dom.Document document) {
	...
}

This can now be used like this:

ResourceBuilder rb = new ResourceBuilder();
Document document = ...;
if (document != null && rb.addEclipseFeature(document)) {
	rb.addContentCapability(uri, SHA256.digest(file).asHex(), file.length(), MIME_TYPE_ECLIPSE_FEATURE);
	... perform other cool stufff ...
	return rb.build();
}

How to map eclipse-feature to resources

identity

Features essentially have a id a version like a bundle that acts as an identifier, what nicely maps to the osgi.identity Namespace and i suggest to use type="org.eclipse.feature" for this purpose. Some more general properties can be found here, where the following must not be supported:
Vendor, Branding Plug-in, Update Site URL, Update Site Name as these are only relevant at runtime, while the others can be included as simple properties for informational purpose if desired.
License information might be extracted as well but that optional I think as it is mostly important for display to the user at install time.

content

An eclipse-feature is the feature.xml packed as a jar file and probably additional files (e.g. properties, about.html, ...) so this jar serves as the osgi.content

capabilities

A feature only provides its identity as a capability and has no further capabilities attached to it

requirements

• A feature can require a given runtime (e.g. Operating Systems, Window Systems, Languages and/or System Architectures) what would map to the osgi.native namespace
• A feature can require another eclipse-feature as effective:=resolve what is a strict version range to that specific version and will point to the others feature osgi.identity Namespace
• A feature can require a bundle as effective:=resolve what is a strict version range to that specific version and would map to the osgi.wiring.bundle namespace
• A feature can have some (install time) dependencies , this can be either a feature or a bundle with different version range specifications these must be mapped to effective:=active and the equivalent osgi version range

[pkriens]

Thanks. Did a quick scan.

Overall questions:

• What is the relation to OSGi features?
• What is the use case? In OSGi, we generally had a description that showed the terminology and context.

Observations:

• The bsn + version must be globally unique, regardless of type. You might want to check if this will not give problems where a feature and bundle name are the same.
• I think I am a bit uncomfortable with the XML interface ... First, I would prefer, I think, to have a special class that takes a resource builder as parameter and does the conversion. The P2 XML is very complex and messy, I expect it will become quite large over time. I've no problem if this class is in bndlib, it is just to not explode the ResourceBuilder.
• For the P2 exporter, I developed a number of DTOs. Wouldn't these be an easier interface to build on than XML?
• The convention so far has been to declare a specific capability for the identity type. We have the Bundle Namespace for bundles and the Host Namespace for fragments. I think it would be wise to create an EclipseFeatureNamespace? This namespace can then contain all the rules. Requirements and capabilities should then be expressed in this namespace. Suggest we develop this in bnd and then get OSGi to standardize it?
• I do not understand the content capability as you describe it? The content cap is a URI to a remote resource and its SHA so it can be downloaded. You mean that the URI should be able to point to different formats?
• I am not sure the native code can handle a requirement to the platform? The general model in OSGi is that you carry all variants of your native code and the framework figure it out. I do not know any example where native code is used to limit the bundle to a specific platform during resolve? This puzzles me.
• Why does the version range to other features and bundles be strict?
• I do not understand the install time dependencies. We do not have maven scopes, the idea of the meta data is to not lie, just tell us what you need. If you have a runtime dependency, it is a requirement. The active would not make a difference in the resolve phase, it would still drag in the dependencies since we include active resources so we get the service providers.
• I recall features had lots of properties with special meaning, i.e. like

I think the details are not yet spelled out. This is not a big problem, the resource model should be powerful enough to handle these features, but I think it strengthens the case for a separate class and not do it in the ResourceBuilder itself.

[laeubi]

What is the relation to OSGi features?

OSGi features might be inspired a bit by p2 features but ther is no releation at all

What is the use case?

Storing eclipse-features in OSGi repository format

The bsn + version must be globally unique, regardless of type. You might want to check if this will not give problems where a feature and bundle name are the same.

Thats not the problem of the generator I think (beside that bsn is bundle terminology I think you men OSGi identity)

The P2 XML is very complex and messy

This has nothing to do with P2 at all, P2 is a director and a repository format and here we talk about the feature.xml. If you like you can use parser classes I think Document is much more flexible as one can always transfor classes > document and vice versa,

For the P2 exporter

Again, this has nothing to do with P2 so please forget everything you know about P2 here ;-)

I think it would be wise to create an EclipseFeatureNamespace

I'm open to suggestions, so if it helps here why not? I'm only not completely sure where such a namespace definition should be hosted (e.g. pde or bnd or osgi ...)

I do not understand the content capability as you describe it? The content cap is a URI to a remote resource and its SHA so it can be downloaded. You mean that the URI should be able to point to different formats?

It should point to a jar file the same as for a bundle (but will contain a feature.xml in the jar instead of a bundle-manifest)

I am not sure the native code can handle a requirement to the platform?

At a first look it seems to match, but we can add these properties to the EclipseFeatureNamespace as well

Why does the version range to other features and bundles be strict?

Because that's how eclipse features work

I do not understand the install time dependencies.

These are dependencies that an installer would need to make sure is present before installing the feature

I recall features had lots of properties with special meaning

Feature have the properties I linked above if you like to se how a feature usually looks like you can take a look for example here: https://www.eclipse.org/downloads/download.php?file=/technology/m2e/releases/latest/features/org.eclipse.m2e.sdk.feature_2.4.0.20230827-1557.jar

[pkriens]

I was mixed P2/features, thanks for clearing up.

The bsn + version must be globally unique, regardless of type. You might want to check if this will not give problems where a feature and bundle name are the same.

Thats not the problem of the generator I think (beside that bsn is bundle terminology I think you men OSGi identity)

The responsibility is to keep the IdentityNamespace osgi.identity + version in the Identity namespace globally unique. You will have to do something here to get a name that does not map with bundles. Doesn't Eclipse have separate namespaces for these names?

I think it would be wise to create an EclipseFeatureNamespace

I'm open to suggestions, so if it helps here why not? I'm only not completely sure where such a namespace definition should be hosted (e.g. pde or bnd or osgi ...)

It would be nice to host it at OSGi but for a starter we could do it in bnd since the ResourceBuilder is there now.

I am not sure the native code can handle a requirement to the platform?

At a first look it seems to match, but we can add these properties to the EclipseFeatureNamespace as well

I guess you can add a requirement with the same properties as the Native Code but I do not think the platforms currently export that capability? This might be an extension for the OSGi to add these properties to the EE?

I do not understand the install time dependencies.

These are dependencies that an installer would need to make sure is present before installing the feature

How do they differ from the bundle requirements? Will the management agent need to recognize these types of requirements? Don't you have to create namespaces for these requirements?

There seems to be an implicit management agent that must provide some capabilities to handle the features. Just like the native properties, you might want to make that explicit in this mapping and not assume the proper management agent is going to be on the receiving end. I.e. if you require the management agent to handle FOO resources, you might want to add a requirement for handling FOO resources that is provided by the platform. We have the bundles and fragments implicit, but if we extend like this we might want to do it right.

[laeubi]

Doesn't Eclipse have separate namespaces for these names?

Eclipse has Plugins (bundles), Features and Products all of them can have an id that is equal as the type itself is enough to distinguish them. So for a repository having ID+VERSION+TYPE being unique would be sufficient for me and that's also what the spec says

The osgi.identity namespace has a capability that can uniquely identify a resource. Its purpose is to identify a type for the resource and then provide a name that is unique for that type.
[...]
It is required that the value of the osgi.identity attribute, plus the value of the type attribute, plus the version attribute are a unique combination.

It would be nice to host it at OSGi but for a starter we could do it in bnd since the ResourceBuilder is there now.

As long as we get this working it would be fine with BND hosting it.

I guess you can add a requirement with the same properties as the Native Code but I do not think the platforms currently export that capability? This might be an extension for the OSGi to add these properties to the EE?

At least Equinox exports framework properties osgi.os, osgi.ws, osgi.... that are currently used for that purpose of decide if a feature "matches"

How do they differ from the bundle requirements? Will the management agent need to recognize these types of requirements? Don't you have to create namespaces for these requirements?

They only differ in effective directive, similar to what BND do when processing DS and creating a service requirement, so it is not required for resolve but for install time, e.g. you can think of the following situation:

• I write a plugin that provides a cool new editor in the context of java but do not depend on anything from JDT
• Still it only is useful if JDT is there, I therefore can declare that my feature my.cool.editor.feature includes the bundle my.cool.editor but depends on feature org.eclipse.jdt.feature.

[pkriens]

@laeubi are you going to do anything with this issue? I'd like to close it and maybe move it to a (draft) PR