Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Equinox p2 Metadata Authoring
This page describes the design of the proposed p2 meta data authoring project.
Contents
Metadata authoring proposal
The problems this project should solve:
- Many types are automatically "adapted" to installable units (e.g. features and plugins), but there is no direct authoring available.
- Existing "adapted" installable units may have meta data that needs to be modified/augmented in order for the unit to be useful - there is a mechanism available to provide advice to the resolution mechanism, but authoring of such advice is not.
I think the work consists of:
- An XML definition for "authored installable unit" (most likely the <unit> format in the local meta data repository). It should be possible to create such an "iu" file with any name without requirements that it is in some special project or folder.
- An XML definition for "advice to adapted installable unit" (as I am not sure what is needed here, a separate definition is perhaps needed).
- An editor for Installable Unit
- Ad editor for Installable Unit advice (is perhaps the same editor).
- A way to test the installable unit (resolution, install-ability)
- A way to export/publish installable units
Files and Formats
A new Installable Unit file can be created with the New IU Wizard.
It is possible to browse for the container, and then create the file:
The format of the "IU" file
It seems obvious to reuse the xml format from the local meta data repository as it already describes an installable unit.
<?xml version='1.0' encoding='UTF-8'?> <?InstallableUnit class='org.eclipse.equinox.internal.p2.metadata.InstallableUnit' version='1.0.0'?> <installable version="1.0.0"> <unit> <!-- like local metadata repository for 'unit' element --> </unit> </installable>
In order to make it easier to reuse the parser/writer for the local metadata repository, a new root element "<installable>" is used to wrap a single "<unit>" element. This also opens up the possibility to include other elements (than unit) if required.
Naming convention
To make it easy to detect the "IU" files an ".iu" extension should be required.
Writer/Parser design
It was possible to crete a prototype that read and writes this format by reusing the metadata repository XMLReader and XMLWriter. It is however a bit unclear if the intention is to allow the InstallableUnit to be used by an editor, or if these classes should be considered internal/private.
The IU Editor
The IU editor is written with PDE Forms. The editor has support for:
- Validation of (most) fields with interactive error reporting
- Undo/Redo support that also moves focus to the modified page/field
Overview Page
Namespace
The namespace is the naming scope of the installable unit's name. From what has been understood by looking at some installable, these are examples of namespaces:
- org.eclipse.equinox.p2.iu
- org.eclipse.equinox.p2.eclipse.type
- osgi.bundle
- java.package
- org.eclipse.equinox.p2.localization
Namespace Questions?
- Should the user be allowed to type anything in the namespace field?
- If not allowed to type anything - where are the valid namespaces found?
- Can the set of namespaces be extended?
- Does namespace have a valid format (looks like it follows package name format)?
- Can namespace be left empty?
Namespace Implementation
The namespace field is validated as a structured name (i.e. like a java package name)
Name
Questions
- What is the valid format of a name?
- Is format determined by p2 for all namespaces, or can name format vary between different namespaces?
- If it can vary, how is the namespace/name validation extended to new namespaces?
Prototype Implementation
In the prototype, the assumption is that the name should follow structured java naming - i.e. a pattern that:
- name can consist of multiple parts where parts are separated by a "."
- each part must be at least one char long
- each part must begin with a-zA-Z_$
- subsequent chars in a part can be a-zA-Z0-9_$
Version
Version is an OSGi version and is validated as one. Version is required.
Provider
Optional string value. No validation.
Filter
This is assumed to be an LDAP filter expression.
Questions
- Is the assumption correct (LDAP filter expression)
- Is it meaningful to provide structured input of the filter (i.e. like feature editor with separate sections for platform, arch, window system, arch and language)?
- is p2 open and can filter on an expandable set of variables, or is it a fixed set (platform, arch, window system, arch and language)?
Prototype Implementation
The prototype implementation has a field for entering an LDAP filter. It has a LDAP filter validator that conform (in part) to the RFC 2254 for textual representation of LDAP filter with the following exceptions:
- OCTAL STRING input is not handled
- attribute options (e.g.";binary") is not handled
- use of extensions or reference to LDAP matching rules is not handled
- (currently) the attribute names are restricted to US ASCII letters, digits and the hyphen '-' character and '.' to separate parts in a structured name. (RFC 2254 specifies that ISO 10646 should be used, and that "letters", "digits" and "hyphens" are allowed.)
Required Capabilities
This is implemented in the prototype by showing a list of required capabilities. Entries can be added/removed, and moved up/down and edited. There is currently no repository lookup.
Provided Capabilities
This is implemented in the prototype by showing a list of provided capabilities. Entries can be added/removed, and moved up/down and edited.
Artifact Keys
This is implemented in the prototype by showing a list of artifact keys. Entries can be added/removed, and moved up/down and edited. There is currently no repository lookup.
Information
The prototype has editing of the information copyright notice, license agreement, and description.
Update
TBD
Touchpoint Data
An installable Unit can be installed into one touchpoint. The IU meta data consists of a reference to the touchpoint (Touchpoint Type), and describes a set of actions/instructions to execute on the referenced touchpoint. Currently, two touchpoints (native, and eclipse) have been implemented. The native touchpoint has aprox 5 different actions, and the eclipse touchpoint has aprox 20. Some of these actions take parameters. The actions and parameters are encoded in a Map where they keys are the references to actions, and the value is a single parameter, or a map of multiple parameters.
A parameter may use other parameters by using ${paramName}. Here is a list of the actions per touchpoint
Questions
- Is the description of how actions/parameters are encoded correct?