[RFC 152] [subsystems] Optional manifests, optional manifest headers, and default values.

[bjhargrave]

Original bug ID: BZ#1972 From: John Ross <jwross@us.ibm.com> Reported version: R4 V4.3

[bjhargrave]

Comment author: John Ross <jwross@us.ibm.com>

The RFC implies that subsystem archive files must end with ".eba", ".cba", and ".fba" for application, composite, and feature, respectively (see sections 6.4.3, 6.4.5, and 6.4.7). I don't see how this can be enforced by an implementation, particularly when an InputStream is passed as the content and the location can be anything.

One possibility might be to use a URL instead of an InputStream. Even this, however, could be problematic because the URL might point to a servlet that takes a parameter other than the file name in order to serve up the requested file.

If this is more of a SHOULD than a MUST, I'm not sure I see the point of mentioning it at all.

Stating that it must be a ZIP file is important, of course, in order to know how to interpret the InputStream bytes.

[bjhargrave]

Comment author: @tjwatson

I see no need to enforce this at runtime. Rather it seems like a recommended naming convention for the file containing the subsystem archive.

[bjhargrave]

Comment author: John Ross <jwross@us.ibm.com>

Rather it seems like a recommended naming convention for the file containing the subsystem archive.

I'm not sure that's true. The subsystem manifest is optional, according to the spec, and, if not present, must be calculated by the implementation according to the default rules for the subsystem type. In the absence of the manifest, how would an implementation determine the subsystem type other than by examining the file extension?

[bjhargrave]

Comment author: @tjwatson

Rather it seems like a recommended naming convention for the file containing the subsystem archive.

I'm not sure that's true. The subsystem manifest is optional, according to the spec, and, if not present, must be calculated by the implementation according to the default rules for the subsystem type. In the absence of the manifest, how would an implementation determine the subsystem type other than by examining the file extension?

How does one determine the version and symbolic name of a subsystem without a manifest? I thought symbolic name had to be specified at a minimum.

[bjhargrave]

Comment author: John Ross <jwross@us.ibm.com>

How does one determine the version and symbolic name of a subsystem without a manifest? I thought symbolic name had to be specified at a minimum.

The symbolic name is derived from the file name of the archive and the version defaults to 0.0.0.

[bjhargrave]

Comment author: @tjwatson

How does one determine the version and symbolic name of a subsystem without a manifest? I thought symbolic name had to be specified at a minimum.

The symbolic name is derived from the file name of the archive and the version defaults to 0.0.0.

But isn't that the same problem as this bug? How do we enforce the name of the file with an input stream? I think we need to make the manifest mandatory.

[bjhargrave]

Comment author: John Ross <jwross@us.ibm.com>

OSGi F2F Montpellier - It was proposed that, instead of the current three extensions (eba, fba, and cba), all subsystem archives would now have only one extension (eba).

Reiterating a point from comment 0, it's not clear to me there's any value in mentioning file extensions at all because knowing the extension is not guaranteed since a subsystem may be installed by providing either an InputStream or a String reperesenting a URL. Even with a URL, you can't assume the last three chars of the path will be the extension.

Because extension information will be either non-prescriptive or simply unreliable, the optional manifest issue remains, as already discussed in comment 2 and comment 5. If manifests remain optional, we need to understand how an implementation will determine the subsystem type and how it will default to a specified type as a last resort. See also bug BZ#2049.

[bjhargrave]

Comment author: @tjwatson

Someone needs to give a good usecase for having an eba that has no manifest. I know we allow R3 bundles with no manifest, but it seems quite pointless to me. All R4 bundles must have a manifest.

[bjhargrave]

Comment author: John Ross <jwross@us.ibm.com>

Someone needs to give a good usecase for having an eba that has no manifest. I know we allow R3 bundles with no manifest, but it seems quite pointless to me. All R4 bundles must have a manifest.

Anyone want to fight for manifestless subsystem archives?

[bjhargrave]

Comment author: @tjwatson

Someone needs to give a good usecase for having an eba that has no manifest. I know we allow R3 bundles with no manifest, but it seems quite pointless to me. All R4 bundles must have a manifest.

Anyone want to fight for manifestless subsystem archives?

No, but I will fight AGAINST the idea of supporting manifestless subsystem archives. ;-)

[bjhargrave]

Comment author: Glyn Normington <gnormington@vmware.com>

Someone needs to give a good usecase for having an eba that has no manifest. I know we allow R3 bundles with no manifest, but it seems quite pointless to me. All R4 bundles must have a manifest.

Anyone want to fight for manifestless subsystem archives?

No, but I will fight AGAINST the idea of supporting manifestless subsystem archives. ;-)

Me too. Daft idea. ;-)

[bjhargrave]

Comment author: Graham Charters <charters@uk.ibm.com>

Someone needs to give a good usecase for having an eba that has no manifest. I know we allow R3 bundles with no manifest, but it seems quite pointless to me. All R4 bundles must have a manifest.

Anyone want to fight for manifestless subsystem archives?

No, but I will fight AGAINST the idea of supporting manifestless subsystem archives. ;-)

Me too. Daft idea. ;-)

I'm not quite ready to let go of the daft idea just yet :)

I'd like us to consider the adoption path for Subsystems and what we require the developer to specify to get started. I haven't filled out the 152 manifest defaulting sections yet, but the thought was we can derive enough information from an archive which doesn't have a manifest. If the developer adds a manifest then that takes precedence. The manifest does not have to be complete, so the defaulting rules apply on a per header basis. I think this approach has the lowest cost to entry for someone starting with a set of bundles and wanting to package them up as an application and give them a whirl.

[bjhargrave]

Comment author: Glyn Normington <gnormington@vmware.com>

Someone needs to give a good usecase for having an eba that has no manifest. I know we allow R3 bundles with no manifest, but it seems quite pointless to me. All R4 bundles must have a manifest.

Anyone want to fight for manifestless subsystem archives?

No, but I will fight AGAINST the idea of supporting manifestless subsystem archives. ;-)

Me too. Daft idea. ;-)

I'm not quite ready to let go of the daft idea just yet :)

I'd like us to consider the adoption path for Subsystems and what we require the developer to specify to get started. I haven't filled out the 152 manifest defaulting sections yet, but the thought was we can derive enough information from an archive which doesn't have a manifest. If the developer adds a manifest then that takes precedence. The manifest does not have to be complete, so the defaulting rules apply on a per header basis. I think this approach has the lowest cost to entry for someone starting with a set of bundles and wanting to package them up as an application and give them a whirl.

That's a reasonable requirement, but wouldn't a virtually empty manifest be sufficient with the content defaulted, ideally one which the newcomer (and I don't mean Eric) could copy mindlessly?

[bjhargrave]

Comment author: Graham Charters <charters@uk.ibm.com>

Someone needs to give a good usecase for having an eba that has no manifest. I know we allow R3 bundles with no manifest, but it seems quite pointless to me. All R4 bundles must have a manifest.

Anyone want to fight for manifestless subsystem archives?

No, but I will fight AGAINST the idea of supporting manifestless subsystem archives. ;-)

Me too. Daft idea. ;-)

I'm not quite ready to let go of the daft idea just yet :)

I'd like us to consider the adoption path for Subsystems and what we require the developer to specify to get started. I haven't filled out the 152 manifest defaulting sections yet, but the thought was we can derive enough information from an archive which doesn't have a manifest. If the developer adds a manifest then that takes precedence. The manifest does not have to be complete, so the defaulting rules apply on a per header basis. I think this approach has the lowest cost to entry for someone starting with a set of bundles and wanting to package them up as an application and give them a whirl.

Someone needs to give a good usecase for having an eba that has no manifest. I know we allow R3 bundles with no manifest, but it seems quite pointless to me. All R4 bundles must have a manifest.

Anyone want to fight for manifestless subsystem archives?

No, but I will fight AGAINST the idea of supporting manifestless subsystem archives. ;-)

Me too. Daft idea. ;-)

I'm not quite ready to let go of the daft idea just yet :)

I'd like us to consider the adoption path for Subsystems and what we require the developer to specify to get started. I haven't filled out the 152 manifest defaulting sections yet, but the thought was we can derive enough information from an archive which doesn't have a manifest. If the developer adds a manifest then that takes precedence. The manifest does not have to be complete, so the defaulting rules apply on a per header basis. I think this approach has the lowest cost to entry for someone starting with a set of bundles and wanting to package them up as an application and give them a whirl.

That's a reasonable requirement, but wouldn't a virtually empty manifest be sufficient with the content defaulted, ideally one which the newcomer (and I don't mean Eric) could copy mindlessly?

If the empty manifest serves no other purpose than to make the runtime happy (and satisfy the spec), then I think people will ask why they are required to include it. It's not communicating anything to the runtime. Or am I misunderstanding your suggestion?

[bjhargrave]

Comment author: Alasdair Nottingham <not@uk.ibm.com>

Someone needs to give a good usecase for having an eba that has no manifest. I know we allow R3 bundles with no manifest, but it seems quite pointless to me. All R4 bundles must have a manifest.

Anyone want to fight for manifestless subsystem archives?

No, but I will fight AGAINST the idea of supporting manifestless subsystem archives. ;-)

Me too. Daft idea. ;-)

If it is a daft idea why did Java EE remove the need for an application.xml for an EAR file? They did this because for an application you should be able to infer the information contained in it from other sources, like the file name content etc. As far as I can tell the reason this is a problem is because the API allows a variant where an InputStream is passed in. In that case I think the appropriate solution would be to find a different way to work out what the type should be, rather than to ban it in all cases.

If we want to make the argument that OSGi is easy to use and the "hard" part is doing modularity I think we need to focus on what the user of the technologies has to do and ensure it is the minimum they need to do, rather than ruling things out because it makes the implementation harder.

[bjhargrave]

Comment author: John Ross <jwross@us.ibm.com>

content etc. As far as I can tell the reason this is a problem is because the API allows a variant where an InputStream is passed in. In that case I think the appropriate solution would be to find a different way to work out what the type should be, rather than to ban it in all cases.

In terms of determining the type, the proposal on the table is to default to "application".

In terms of determining the symbolic name, I suppose that, in the case where an InputStream was provided, the location could be used in the same way that url.getPath() would be used. That is, take everything after the last '/' as the name.

[bjhargrave]

Comment author: @tjwatson

If we want to make the argument that OSGi is easy to use and the "hard" part is doing modularity I think we need to focus on what the user of the technologies has to do and ensure it is the minimum they need to do, rather than ruling things out because it makes the implementation harder.

For me this is not an implementation discussion. I would prefer to have a single way for declaring the one piece of information which (so far) we have defined as mandatory metadata for a subsystem; that is the symbolic name. Perhaps the symbolic name is not really that important for an application? Applications cannot export anything and cannot be required by anyone so maybe we just say the implementation is free to generate one if it is not present? The generation of that symbolic name is implementation specific.

[bjhargrave]

Comment author: Alasdair Nottingham <not@uk.ibm.com>

If we want to make the argument that OSGi is easy to use and the "hard" part is doing modularity I think we need to focus on what the user of the technologies has to do and ensure it is the minimum they need to do, rather than ruling things out because it makes the implementation harder.

For me this is not an implementation discussion. I would prefer to have a single way for declaring the one piece of information which (so far) we have defined as mandatory metadata for a subsystem; that is the symbolic name. Perhaps the symbolic name is not really that important for an application? Applications cannot export anything and cannot be required by anyone so maybe we just say the implementation is free to generate one if it is not present? The generation of that symbolic name is implementation specific.

I would prefer John's suggestion to this one. I think for a archive we should make an effort to generate the same symbolic name. Doing location processing seems more reasonable than allowing the implementation to make one up.

[bjhargrave]

Comment author: Glyn Normington <gnormington@vmware.com>

My "daft idea" comment was motivated by the edge cases Virgo has hit in the past dealing with streams, directories, peculiar filenames, etc. when trying to determine a default symbolic name for some of its artifacts.

But I accept Graham's and Alastair's points about the user experience. Perhaps making the behaviour implementation specific would get us out of the problem of constantly having to update the spec as we discover more edge cases.

[bjhargrave]

Comment author: Glyn Normington <gnormington@vmware.com>

I would prefer John's suggestion to this one. I think for a archive we should make an effort to generate the same symbolic name. Doing location processing seems more reasonable than allowing the implementation to make one up.

Fair enough If we can find a way of persuading ourselves we've covered all the edge cases. Or was this comment restricted to the non-stream archive case?

[bjhargrave]

Comment author: John Ross <jwross@us.ibm.com>

I would prefer John's suggestion to this one. I think for a archive we should make an effort to generate the same symbolic name. Doing location processing seems more reasonable than allowing the implementation to make one up. Fair enough If we can find a way of persuading ourselves we've covered all the edge cases. Or was this comment restricted to the non-stream archive case?

I don't think we're persuaded all of the edge cases have been covered.

My understanding was we're discussing the possibility of standardizing the behavior when there is either no manifest information available or the manifest information is missing the symbolic name header, the goal being the user will end up with the same symbolic name regardless of which implementation is being used. In the case of install(String, InputStream), my suggestion was to use either the complete location string or everything after the last '/' if that character is present. In the case of install(String), the same rule applies accept with the value of url.getPath().

It was also my understanding that the particular use case being addressed was the idea of someone simply zipping up a bunch of jars in order to create an application. Something would then need to pick up that file and submit it to subsystems. So I admit my proposal pretty much assumes what you ultimately end up with is the file name of the archive as the symbolic name.

[bjhargrave]

Comment author: Glyn Normington <gnormington@vmware.com>

I would prefer John's suggestion to this one. I think for a archive we should make an effort to generate the same symbolic name. Doing location processing seems more reasonable than allowing the implementation to make one up. Fair enough If we can find a way of persuading ourselves we've covered all the edge cases. Or was this comment restricted to the non-stream archive case?

I don't think we're persuaded all of the edge cases have been covered.

My understanding was we're discussing the possibility of standardizing the behavior when there is either no manifest information available or the manifest information is missing the symbolic name header, the goal being the user will end up with the same symbolic name regardless of which implementation is being used. In the case of install(String, InputStream), my suggestion was to use either the complete location string or everything after the last '/' if that character is present. In the case of install(String), the same rule applies accept with the value of url.getPath().

It was also my understanding that the particular use case being addressed was the idea of someone simply zipping up a bunch of jars in order to create an application. Something would then need to pick up that file and submit it to subsystems. So I admit my proposal pretty much assumes what you ultimately end up with is the file name of the archive as the symbolic name.

Unless I've missed some restriction on location strings, we have to consider edge cases like:

install("C:\x\y.eba", InputStream)

and

install("[ClusterA|App1]", InputStream)

both of which contain characters outside the allowed set for a symbolic name. I can think of some heuristics that work in these cases, but I'm not sure I'd particularly want to spec them.

[bjhargrave]

Comment author: John Ross <jwross@us.ibm.com>

I'm moving the discussion of archive file extensions to bug BZ#2049, which already has the similar topic of condensing subsystem specific type header names and manifest names.

I'm leaving the discussion of optional manifests, optional header names, and default values here. I've updated the summary accordingly.

The current proposal is as follows.

(1) Subsystem manifests are optional. (2) All subsystem manifest headers are optional. (3) Default values will be defined by the spec. (4) As long as the same "installer" is being used (i.e. the thing responsible for generating the location string), the resulting symbolic name and version (if not specified in the manifest) must be consistent across subsystems implementations.

The last will require specifying the parsing rules for a location string.

[bjhargrave]

Comment author: John Ross <jwross@us.ibm.com>

I'm moving the discussion of archive file extensions to bug BZ#2049, which already has the similar topic of condensing subsystem specific type header names and manifest names. I'm leaving the discussion of optional manifests, optional header names, and default values here. I've updated the summary accordingly. The current proposal is as follows. (1) Subsystem manifests are optional. (2) All subsystem manifest headers are optional. (3) Default values will be defined by the spec. (4) As long as the same "installer" is being used (i.e. the thing responsible for generating the location string), the resulting symbolic name and version (if not specified in the manifest) must be consistent across subsystems implementations. The last will require specifying the parsing rules for a location string.

Currently, the proposed parsing rules are as follows.

(1) Convert all '\' into '/'. (2) Extract everything after the last '/' or simply everything if no '/'. (3) Replace all invalid BSN chars with an agreed upon char.

The result of this then needs to be parsed into BSN/version, if possible. The proposed syntax is:

symbolic-name ('@ ' version) ('.' 'eba' | 'fba' | 'cba')

The file extension, if present, is stripped out. The version, if present, is used unless specified in the manifest. If version is not present, the default is '0.0.0'. What remains is used for the symbolic name if not specified in the manifest.

This syntax is not enforced (i.e. the location string is not required to conform to this syntax). Implementations simply attempt to parse it according to this syntax. If not recognizable, the whole thing simply becomes the symbolic name.

Note this is a new proposal not previously discussed. Others may need to correct my understanding if not accurately conveyed.

[bjhargrave]

Comment author: @bjhargrave

Currently, the proposed parsing rules are as follows.

(1) Convert all '\' into '/'. (2) Extract everything after the last '/' or simply everything if no '/'. (3) Replace all invalid BSN chars with an agreed upon char.

The result of this then needs to be parsed into BSN/version, if possible. The proposed syntax is:

symbolic-name ('@ ' version) ('.' 'eba' | 'fba' | 'cba')

So this means that the version qualifier can't end in any of those strings.

The file extension, if present, is stripped out. The version, if present, is used unless specified in the manifest. If version is not present, the default is '0.0.0'. What remains is used for the symbolic name if not specified in the manifest.

This syntax is not enforced (i.e. the location string is not required to conform to this syntax). Implementations simply attempt to parse it according to this syntax. If not recognizable, the whole thing simply becomes the symbolic name.

Note this is a new proposal not previously discussed. Others may need to correct my understanding if not accurately conveyed.

If you are going to define a convention for location strings, why not go all the way and define a URI scheme?

osgi.eba://bundle.symbolic.name#version osgi.fba://bundle.symbolic.name#version osgi.cba://bundle.symbolic.name#version

[bjhargrave]

Comment author: John Ross <jwross@us.ibm.com>

If you are going to define a convention for location strings, why not go all the way and define a URI scheme? osgi.eba://bundle.symbolic.name#version osgi.fba://bundle.symbolic.name#version osgi.cba://bundle.symbolic.name#version

So if one wanted to use the symbolic name defaulting functionality (the version here is optional and can always be defaulted to 0.0.0), they must use one of these URI schemes. Is that what you were thinking?

I see how this would work with install(String, InputStream), but what about install(String)? Would we extend the syntax to allow an embedded URL for locating the content?

[bjhargrave]

Comment author: @bjhargrave

If you are going to define a convention for location strings, why not go all the way and define a URI scheme? osgi.eba://bundle.symbolic.name#version osgi.fba://bundle.symbolic.name#version osgi.cba://bundle.symbolic.name#version

So if one wanted to use the symbolic name defaulting functionality (the version here is optional and can always be defaulted to 0.0.0), they must use one of these URI schemes. Is that what you were thinking?

Yes. Then the type of the entity is unambiguous.

I see how this would work with install(String, InputStream), but what about install(String)? Would we extend the syntax to allow an embedded URL for locating the content?

I guess. Like the jar: scheme, you could define how an embedded URL could be used.

[bjhargrave]

Comment author: John Ross <jwross@us.ibm.com>

Reitering the requirements:

(1) Manifests must be optional. (2) All manifest headers must be optional with defaults defined by the spec. (3) Default symbolic names must be consistent across implementations assuming the same installer is used. (4) There must be a way to specify a default version.

The proposal is to define a custom URI scheme for subsystems. The proposed syntax is as follows.

'subsystem' (. 'eba'|'fba'|'cba') ':' (url) '!/' symbolic-name ('#' version)

If omitted, the default type is 'eba'.

This URI must be used in order to specify default values for symbolic name and version.

If the symbolic name header is omitted and this URI is not used, what is the result?

(1) A SubsystemException is thrown. (2) A symbolic name is generated by the implementation. (3) Behavior is unspecified.

[bjhargrave]

Comment author: @bjhargrave

Reitering the requirements:

(1) Manifests must be optional. (2) All manifest headers must be optional with defaults defined by the spec. (3) Default symbolic names must be consistent across implementations assuming the same installer is used. (4) There must be a way to specify a default version.

The proposal is to define a custom URI scheme for subsystems. The proposed syntax is as follows.

'subsystem' (. 'eba'|'fba'|'cba') ':' (url) '!/' symbolic-name ('#' version)

If omitted, the default type is 'eba'.

This URI must be used in order to specify default values for symbolic name and version.

If the symbolic name header is omitted and this URI is not used, what is the result?

(1) A SubsystemException is thrown. (2) A symbolic name is generated by the implementation. (3) Behavior is unspecified.

Perhaps the BSN and version might be in the thing at the embedded URL?

[bjhargrave]

Comment author: John Ross <jwross@us.ibm.com>

Reitering the requirements:

(1) Manifests must be optional. (2) All manifest headers must be optional with defaults defined by the spec. (3) Default symbolic names must be consistent across implementations assuming the same installer is used. (4) There must be a way to specify a default version.

The proposal is to define a custom URI scheme for subsystems. The proposed syntax is as follows.

'subsystem' (. 'eba'|'fba'|'cba') ':' (url) '!/' symbolic-name ('#' version)

If omitted, the default type is 'eba'.

This URI must be used in order to specify default values for symbolic name and version.

If the symbolic name header is omitted and this URI is not used, what is the result?

(1) A SubsystemException is thrown. (2) A symbolic name is generated by the implementation. (3) Behavior is unspecified.

Perhaps the BSN and version might be in the thing at the embedded URL?

Right. You'd have to check the content to see if there was a manifest with a symbolic name header before failing, if that will be the result. I meant if the symbolic name header was omitted in all respects, both the URI and manifest.

By the way, the intent here is that a symbolic name or version included within the manifest would override the values specified in the URI.

[bjhargrave]

Comment author: John Ross <jwross@us.ibm.com>

To shore up the proposal:

Requirements: (1) Manifests must be optional. (2) All manifest headers must be optional with defined defaults. (3) There must be a standard way to specify a default symbolic name. (4) There must be a standard way to specify a default version.

The spec will define a custom URI scheme with the following syntax.

'subsystem' ('.' 'eba'|'fba'|'cba') ':' (url) '!/' symbolic-name ('#' version)

If omitted, the default type is 'eba'. If omitted, the default version is '0.0.0'.

Implementations must support this URI and use the provided symbolic name and version as the default values for the associated Subsystem-SymbolicName and Subsystem-Version headers, respectively, if omitted. If the associated header is present, the header value has precedence.

If this URI is not used, and the Subsystem-SymbolicName header is omitted, and the implementation does not provide some other means for computing a default symbolic name, a SubsystemException must be thrown.

[bjhargrave]

Comment author: @bjhargrave

'subsystem' ('.' 'eba'|'fba'|'cba') ':' (url) '!/' symbolic-name ('#' version)

If url is optional, how can this URL be mapped to an InputStream? Seems like url is mandatory.

'subsystem' ('.eba'|'.fba'|'.cba') ':' url '#' symbolic-name ('@ ' version)

seems more correct. We don't need / after ! since symbolic-name is not a path in the url. We also need to consider how we want the URI parser to parse this. I changed it to use # as the separator between url and symbolic-name/version so that they would be parsed as the uri fragment instead of being part of the scheme specific part. But I think some experimentation with parsing is necessary to settle on the best form.

The shortest form is then:

subsystem:url#name

which is an eba at the specified url with the default symbolic name of name and version of 0.

[bjhargrave]

Comment author: @bjhargrave

'subsystem' ('.eba'|'.fba'|'.cba') ':' url '#' symbolic-name ('@ ' version)

It may also be better to make the eba, fba and cba marking appear elsewhere in the URI. With a default of .eba, you end up needing to have 4 scheme handlers (subsystem, subsystem.eba, subsystem.fba, and subsystem.cba). If more types are added later, then we need more scheme handlers.

[bjhargrave]

Comment author: John Ross <jwross@us.ibm.com>

If url is optional, how can this URL be mapped to an InputStream? Seems like url is mandatory.

The url is optional because the uri can be used with both install(String) and install(String, InputStream). The latter does not require a url pointing to the content.

[bjhargrave]

Comment author: John Ross <jwross@us.ibm.com>

I changed it to use # as the separator between url and symbolic-name/version so that they would be parsed as the uri fragment instead of being part of the scheme specific part.

I was making no assumptions about what the url, if included, would look like. It might already have a fragment. I saw the symbolic-name/version portion as something separate and distinct from the url. In other words, they're part of the uri but not the embedded url.

[bjhargrave]

Comment author: John Ross <jwross@us.ibm.com>

'subsystem' ('.eba'|'.fba'|'.cba') ':' url '#' symbolic-name ('@ ' version) It may also be better to make the eba, fba and cba marking appear elsewhere in the URI. With a default of .eba, you end up needing to have 4 scheme handlers (subsystem, subsystem.eba, subsystem.fba, and subsystem.cba). If more types are added later, then we need more scheme handlers.

Yes, I would like to avoid that.

[bjhargrave]

Comment author: John Ross <jwross@us.ibm.com>

If url is optional, how can this URL be mapped to an InputStream? Seems like url is mandatory.

I still think it makes more sense to leave the url as optional because of the install(String, InputStream) case but am not married to it.

'subsystem' ('.eba'|'.fba'|'.cba') ':' url '#' symbolic-name ('@ ' version) seems more correct. We don't need / after ! since symbolic-name is not a path in the url. We also need to consider how we want the URI parser to parse this. I changed it to use # as the separator between url and symbolic-name/version so that they would be parsed as the uri fragment instead of being part of the scheme specific part. But I think some experimentation with parsing is necessary to settle on the best form. The shortest form is then: subsystem:url#name which is an eba at the specified url with the default symbolic name of name and version of 0.

It seems that maximum reuse of the URI class' built-in parsing is attained with the following syntax.

'subsystem'('.'eba'|'.fba'|'.cba')'://'(url)'?'symbolic-name('#'version)

This results in uri.getScheme() == subsystem. uri.getAuthority() == url, uri.getQuery() == symbolic-name, and uri.getFragment() == version.

It also solves the issue of the "subsystem:#com.acme.foo" short form being an invalid URI. "subsystem://#com.acme.foo" is valid.

It may also be better to make the eba, fba and cba marking appear elsewhere in the URI. With a default of .eba, you end up needing to have 4 scheme handlers (subsystem, subsystem.eba, subsystem.fba, and subsystem.cba). If more types are added later, then we need more scheme handlers.

I don't think this is a concern since we're defining a URI and not a URL?

[bjhargrave]

Comment author: @bjhargrave

It also solves the issue of the "subsystem:#com.acme.foo" short form being an invalid URI. "subsystem://#com.acme.foo" is valid.

I think you mean "subsystem://?com.acme.foo", since the symbolic-name is the query and the version is the fragment.

[bjhargrave]

Comment author: @tjwatson

'subsystem' ('.eba'|'.fba'|'.cba') ':' url '#' symbolic-name ('@ ' version) It may also be better to make the eba, fba and cba marking appear elsewhere in the URI. With a default of .eba, you end up needing to have 4 scheme handlers (subsystem, subsystem.eba, subsystem.fba, and subsystem.cba). If more types are added later, then we need more scheme handlers.

Yes, I would like to avoid that.

My understanding is that we are spec'ing a String format for a URI with the latest being:

'subsystem'('.'eba'|'.fba'|'.cba')'://'(url)'?'symbolic-name('#'version)

The intention is that the subsystem could use this string to construct a URI. This will not require any protocol handlers to parse into a URI with schemes of subsystem.*

The only place where a URL protocol handler would be needed is to process the (url) portion of the subsystem location in order for the subsystem impl to get the content in cases where an input stream was not provided.

[bjhargrave]

Comment author: John Ross <jwross@us.ibm.com>

It also solves the issue of the "subsystem:#com.acme.foo" short form being an invalid URI. "subsystem://#com.acme.foo" is valid. I think you mean "subsystem://?com.acme.foo", since the symbolic-name is the query and the version is the fragment.

Yes, thanks. That's valid too.

Note that ':/' instead of '://' works too but results in a little more work since you have to strip off the leading '/' from uri.getPath().

[bjhargrave]

Comment author: @tjwatson

It seems that maximum reuse of the URI class' built-in parsing is attained with the following syntax.

'subsystem'('.'eba'|'.fba'|'.cba')'://'(url)'?'symbolic-name('#'version)

This results in uri.getScheme() == subsystem. uri.getAuthority() == url, uri.getQuery() == symbolic-name, and uri.getFragment() == version.

It also solves the issue of the "subsystem:#com.acme.foo" short form being an invalid URI. "subsystem://#com.acme.foo" is valid.

Note that in order for uri.getAuthority() to return the full (url) the url portion must be encoded. For example:

subsystem.eba://http://ibm.com/test/app.eba?a=v#f1?com.ibm.app#1.0.0

The (uri) portion "http://ibm.com/test/app.eba?a=v#f1" must be encoded for this to work:

subsystem.eba://http%3a%2f%2fibm.com%2ftest%2fapp.eba%3fa%3dv%23f1?com.ibm.app#1.0.0

[bjhargrave]

Comment author: John Ross <jwross@us.ibm.com>

'subsystem' ('.eba'|'.fba'|'.cba') ':' url '#' symbolic-name ('@ ' version) It may also be better to make the eba, fba and cba marking appear elsewhere in the URI. With a default of .eba, you end up needing to have 4 scheme handlers (subsystem, subsystem.eba, subsystem.fba, and subsystem.cba). If more types are added later, then we need more scheme handlers.

Yes, I would like to avoid that.

My understanding is that we are spec'ing a String format for a URI with the latest being: 'subsystem'('.'eba'|'.fba'|'.cba')'://'(url)'?'symbolic-name('#'version) The intention is that the subsystem could use this string to construct a URI. This will not require any protocol handlers to parse into a URI with schemes of subsystem.* The only place where a URL protocol handler would be needed is to process the (url) portion of the subsystem location in order for the subsystem impl to get the content in cases where an input stream was not provided.

That's correct.

I should also point out that the embedded URL should be encoded; otherwise, all bets are off. URI.getAuthority() returns the decoded version.

[bjhargrave]

Comment author: @tjwatson

Created attachment 189 URI usage

I think you must use :// to have the URI make the most sense. Here is a test program that shows some results of using URI with the proposed scheme.

Attached file: TestURL.java (text/plain, 1901 bytes) Description: URI usage

[bjhargrave]

Comment author: John Ross <jwross@us.ibm.com>

EEG Call:

No objections were presented to moving forward with the URI concept as the means for external clients to unambiguously communicate a default symbolic name and version.

A file naming convention would still need to be defined for the case where manifestless subsystem A includes manifestless subsystem B in its archive. The only thing to use would be the subsystem B file name.

[bjhargrave]

Comment author: John Ross <jwross@us.ibm.com>

Added the following to section 5.3.2.3.

If not specified in the manifest, or the manifest is omitted, the following rules are defined for computing the default values of Subsystem-SymbolicName and Subsystem-Version. Manifest values override the defaults. If not otherwise specified, the default value of Subsystem-Version is always 0.0.0. If the symbolic name is not provided in the manifest and cannot be computed by any of the following means, implementations may fail the installation.

1. When installing a subsystem via the subsystem interface (i.e. using one of the install methods), the following URI syntax must be used as the location in order to specify default values. Note that the optional URL component, if included, must be encoded.

subsystem-uri ::= 'subsystem://' ( url )? '?' symbolic-name ( '#' version )?

url ::= <see RFC 1738> // Retrieved via URI.getAuthority().

symbolic-name ::= <see OSGi Core Specification 1.3.2> // Retrieved via URI.getQuery().

version ::= <see OSGi Core Specification 3.2.5> // Retrieved via URI.getFragment().

2. When installing a subsystem with no content headers and containing other subsystem archives with no symbolic name or version, default values will be derived from the archive file names. The syntax is as follows. subsystem-archive ::= symbolic-name ( '@ ' version ) '.ssa'

3. When installing a subsystem with content headers having clauses pointing to other subsystems with no symbolic name or version, the path and version attribute of the corresponding clause will be used as the default symbolic name and version.