Support generation of Java class with symbols for resources supplied with bundle (like images)

[ruspl-afed]

may look similar to https://developer.android.com/reference/android/R and help to address the following issues:

• make it easier to reuse resources (like images) from upstream bundles to reduce duplication of similar/equal resources
• promote resources to an API level and utilize all the API rules and tooling we already have

[HannesWell]

That's a helpful idea.
One remark: There is already support to check resources referenced in Extensions exist if a special path type is used.

The right place to defines something like that is probably the build.properties file.
What should be defined there is a fully-qualified class name and a list of pattern that identify the resources to be referenced.
For the latter we can maybe re-use the bin.includes editor and its syntax to something like:
export.resources.foo.bar.Resources = icons/, other/icons/*.png

Would generate a class named foo.bar.Resources that provides symbols for all resources in icons/ and all png files in other/icons/

But I think there are a few questions we should answer:

• Should be permitted to defines multiple generated class, maybe with overlapping content maybe with disjunct content. It could be useful to give the classes more meaningful names.
• How should the constants representing the resource be named? Just the file name, e.g. in upper-case?
  In many the cases the resource would probably reside in a sub-folder, should the preceding path before the file-name be ignored? If yes, how should we resolve conflicting names of files in different folders?
• What if I want to move or rename the resource within the bundle. Then the symbol should stay the same and should just have its reference updated.

All these questions can certainly be answered, but there are many and it might be cumbersome to implement all these requirements/questions in a satisfying fashion.

Another solution that would probably be simpler from a tooling POV and would user also give more control is to just write the mentioned java class that represents the resources by hand add a special Annotation (and maybe use a special type) so that a suitable PDE builder can verify that the referenced resource really exists in the bundle.
Similar to what already exists for extensions as mentioned above, but in Java-code.
Then we just have to find a elegant way of definition and implement a verification that the resource exists and maybe also verify that the resources is included in the bin.includes.

Should Tycho also support it? At least should Tycho check if the generated class is in sync with the available files.?

[BeckerWdf]

• How should the constants representing the resource be named? Just the file name, e.g. in upper-case?

For me the file name is just an implementation detail that should be changeable without breaking consumers. So we should not use the file name as a key / constant.

[ruspl-afed]

There is already support to check resources referenced in Extensions exist if a special path type is used.

I know, but the idea is about promoting resource location to Java API

The right place to defines something like that is probably the build.properties file.

It may be there as well, but we need to have these generated Java symbols on runtime, to query ImageRegistry for example.

Should be permitted to defines multiple generated class, maybe with overlapping content maybe with disjunct content. It could be useful to give the classes more meaningful names.

We may need some flexibility, but also should have good defaults. May be an extra bundle header can serve us to query bundle resources.

How should the constants representing the resource be named?

What we use in our codebase is a record with the following fields: BundleSymboilcName, BundleResourcePath, ImageKey it looks enough to construct Platform URL and to access ImageRegistry. However we may want to add more data like size, etc.
Generated class may have several field of this record type, one per "public" image.
Yes, we should think about convention for non-public resources (images) as well.

What if I want to move or rename the resource within the bundle. Then the symbol should stay the same and should just have its reference updated.

This will be a breaking API change, since others may reference you by Platform URI. Only resource content may be changed

Another solution that would probably be simpler from a tooling POV and would user also give more control is to just write the mentioned java class that represents the resources by hand add a special Annotation (and maybe use a special type) so that a suitable PDE builder can verify that the referenced resource really exists in the bundle.

Yes, this also could be a way to go. Finally we should have an API Java class with symbols that corresponds to "public" images. Actually we use this approach for all the identifiers from plugin.xml, to reduce the influence of Eclipse Magic when strings from Java and plugin.xml should somehow match.

Should Tycho also support it?

Not yet clear what exactly to support.

[BeckerWdf]

What we use in our codebase is a record with the following fields: BundleSymboilcName, BundleResourcePath, ImageKey it looks enough to construct Platform URL and to access ImageRegistry

The solution should be depend on the usage of ImageRegistry.

[merks]

One can use platform:/plugin to refer to images:

Using this with a URLImageDescriptor and an ImageRegistry that provides for sharing...

[BeckerWdf]

But when doing this you have to "hope" that nothing (like the location or the file name) change. So this is not really "API".

[ruspl-afed]

@merks yes, sure, one can.
But these images and other resources inside, say, platform bundle are not a pat of API. One can only hope that image will not change its path. And one cannot reference a constant from Java code, but only hardcode image URL again. And one have no idea how image key in ImageRegistry corresponds to a bundle resource.

This discussion is how to promote such a resource (image) with its URL to a Java API and put it to a regular API control.

[laeubi]

But these images and other resources inside, say, platform bundle are not a pat of API.

I'm not sure if one really want them to make API... but e.g. Jfaces has JFaceResources / JFaceColors and there are always deprecation, so handling resources as API also seem to have some shortcomings.

A while back I mage the images a bundle, so theoretically one can install this and reuse icons there, the main pitfall is that on many places Eclipse does not allow to use a URI...

[ruspl-afed]

I'm not saying that everyone must turn every bundle image to an API, but such an opportunity would be nice to have to reduce the number of duplicated images for dependent components.
Imagine that one contributes an interface type AType with all the luxury of IAdaptable and so on. And also with image(s) to represent this type AType for different UI contributions. Let's say for E3 viewers all is good with WorkbenchAdapter, but we may need this image URL for other UI contributions.
The proposal it to promote an image URL to an API as well. So another person that wants to utilize AType type and provide more releated UI contributions may be sure that image(s) for AType will not change its location.

[laeubi]

e.g. E4 already allows to discover images from other bundles, if they are likely change is more a matter of the project, I just doubt that anyone is willing to maintain resources as API and for those that are willing they simply take care anyways.

If it is just that acquire the URL is a problem there is org.eclipse.jface.resource.ImageDescriptor.createFromFile(Class<?>, String) so all what is needed to make it API is:

1. Have an Interface (lets use your AType)
2. Define AType#MY_IMAGE_NAME (e.g. with value /icons/a.png)
3. The use it like ImageDescriptor.createFromFile(AType.class, AType.MY_IMAGE_NAME)

Then it is API and you can even rename/replace/move/... the /icons/a.png to another place.

[ruspl-afed]

Yes, I understand, there are several ways to reference an image.
But here I'm looking for a way to make image path stable for downstream components.

Then it is API and you can even rename/replace/move/... the /icons/a.png to another place.

This is exactly what I would like to restrict with "promotion to an API"
Because in other places (*.e4xmi, plugin.xml) one may have URL references that will be broken after "rename/replace/move/"

[ruspl-afed]

This is a skeleton of API we may want to have somewhere in Equinox to switch from blind string identifiers to typed records:

record BundleIdentity(String symbolic) {
//may be version or other things later
}

interface ResourceUrl {
	String url();
}

record ImageIdentity(BundleIdentity bundle, String path, String key) implements ResourceUrl {

	@Override
	public String url() {
		return "platform:/plugin/" + bundle.symbolic() + "/$nl$/" + path; //$NON-NLS-1$ //$NON-NLS-2$
	}

}

and here something we can write manually or generate with PDE to then use as controllable and predictable API

interface BundleResources {

	BundleIdentity qualifier = new BundleIdentity("org.example.bundle"); //$NON-NLS-1$

	interface Obj16 {

		ImageIdentity atype = new ImageIdentity(qualifier, "icons/full/obj16/atype.png", "atype"); //$NON-NLS-1$ //$NON-NLS-2$

	}
}

BTW, in our code base we added such an API types to generated EMF Edit bundles and it appeared to be very handy for many use cases, including usage of ImageRegistry. @merks

[laeubi]

Because in other places (*.e4xmi, plugin.xml) one may have URL references that will be broken after "rename/replace/move/"

But that's a general restriction of these techniques, e.g attribute names, or ids or whatever are not ...

This is a skeleton of API we may want to have somewhere in Equinox to switch from blind string identifiers to typed records

I don't really see how this is different from my suggestion to define a public final String, e.g. in your BundleResources you can happily change the name of BundleIdentity as well as ImageIdentity in any way without having API tools a way to complain.

What I can think about is something we have for NLS, where the name of a static field is directly mapped to a key in a properties file, then maybe the IDE can complain that a mapping is missing, but also here no API checks can be performed (but we have Wizards to 'externalize' String so it should work equally well for resources).

[ruspl-afed]

Thank you for your input @laeubi , it is very valuable to highlight the weak points of the discussed concept!

But that's a general restriction of these techniques, e.g attribute names, or ids or whatever are not ..

Yes, and this is exactly the problem that I would like to solve.

you can happily change the name of BundleIdentity as well as ImageIdentity in any way without having API tools a way to complain.

Yes, you are right. And for constants it is theoretically possible to implement value change control. However we don't have "contract change API control" yet in PDE, that is much harder to formalize than our current "signature change API control".

We can also have corresponding annotations to advice that one string should be equal to a Bundle-Symbolic-Name attribute of containing bundle and another should match a file inside bundle (and such a file should match a pattern in build.properties)

What I can think about is something we have for NLS

Yes, probably we can reuse some parts of it.

[laeubi]

Even if we can solve the string-change problem, there is one interesting question to solve:

Even if we assume the string is the same and everything is checked and we get errors, now assume I replace the icon file with something completely different... Should now we require a major version bump of the bundle? How many pixel changes are okay for a minor version bump? :-)

[ruspl-afed]

Should now we require a major version bump of the bundle?

I think we should not. To access an image we are using its Platform URI (or its reduced form if we are inside the same bundle).
So, the image URI is an interface (signature) for us while image content is an implementation, and we are going to start from interface (signature) control, as we do elsewhere.

I know it does not sound symmetric to a Java constant value change control we discussed above, but at the moment I don't have a better idea how to use the tools we already have (here I implicitly consider Java-based tooling as the most powerful in Eclipse ecosystem)

May be in the future we will have enough metadata and equipment to track pixel changes, who knows.
However, if we will start to annotate resources like images with metadata it will be easier to satisfy SBOM generators and other similar tools, but this is another topic.

[BeckerWdf]

Even if we can solve the string-change problem, there is one interesting question to solve:

Even if we assume the string is the same and everything is checked and we get errors, now assume I replace the icon file with something completely different... Should now we require a major version bump of the bundle? How many pixel changes are okay for a minor version bump? :-)

Some time ago we replaced the filter icon (some lines with arrow on it) with a completely new design (a funnel). Why should be increase version bumps (even major once) for that?

[BeckerWdf]

What's wrong with the approach that is taken e.g. in org.eclipse.ui.ISharedImages?

[HannesWell]

I think this approach is fine. In general one could think about using a more powerful/specific type for the constants, e.g. URL, URI or ImageDescriptor, then no other look-up method is necessary.
But defining constants for images or resources seems very java like to me and allows to reuse all existing API tooling.

The only deficit I see for that approach is that there is no tooling to ensure that the path actually exists (one could create a unit-test, but that's cumbersome).
Therefore I suggested to add tooling that verifies that a resource at a specified path actually exists in the last paragraph of my initial answer: #1315 (comment)
Christoph suggested an alternative approach, but I think the idea is the same:
#1315 (reply in thread)

With that I think that would be a very good and robust solution.

[ruspl-afed]

Created a PR for Equinox to demonstrate how API for image identification may look like