Add create/load/refereshRepository() methods to IRepositoryManager

[HannesWell]

Add the following methods to the super interface IRepositoryManager, which both existing sub-interfaces IArtifactRepositoryManager and IMetadataRepositoryManager covariantly override:

• createRepository()
• loadRepository()
• refreshRepository()

This allows more general usage of the IRepositoryManager interface, for example in Tycho.

Furthermore (in the first of the two commits), apply a few minor doc unifications and clean-ups in all RepositoryManager interfaces.

[github-actions]

Test Results

       9 files  ±0         9 suites  ±0   38m 18s ⏱️ + 2m 45s
2 175 tests ±0  2 171 ✔️ ±0    4 💤 ±0  0 ❌ ±0 
6 615 runs  ±0  6 604 ✔️ ±0  11 💤 ±0  0 ❌ ±0 

Results for commit e3bce54. ± Comparison against base commit 344ac78.

♻️ This comment has been updated with latest results.

[laeubi]

The only think I can think of is that a repository manager not necessarily must support creation/loading/ of repositories and these must not necessarily even be URI based...

Also I wonder if this can be used in P2 anywhere directly?

[merks]

This seems fine.

[HannesWell]

The only think I can think of is that a repository manager not necessarily must support creation/loading/ of repositories and these must not necessarily even be URI based...

At least at the moment there are only two sub-interfaces, which both do support it and override these methods.
I cannot assess if it is realist to assume that in the future there might be another sub-type that does not support that?
But in case we now say no falsely, such implementation can still throw an UnsupportedOperationException like it is for example done in the Collections framework.

Also I wonder if this can be used in P2 anywhere directly?

I checked it and indeed there are many places and I added another commit to use the new methods.

It also unifies the behavior if a repository manager of specific type cannot be found in ProvisioningHelper to throw an exception in all cases. But I assume those services should actually never be absent.

The little difficulty is that the generic IRepositoryManager can only return an IRepository<IInstallableUnit> instead of IMetadataRepository and IRepository<IArtifactKey> instead of IArtifactRepository but often the specializations are assumed which requires casting. In order to cover that with generics, the list of parameters of IRepositoryManager<T> would have to be extended to IRepositoryManager<T, R extends IRepository<T>>.
But this would at least be a source-incompatible change (which is annoying but solvable, because if one compiles code one can usually adapt it).

A review of the changes in the third commit would be more than welcome.

[HannesWell]

validRepositoryLocation() either returned true or threw an exception.
Therefore initDestinationRepository() was never called for a metadata repository.

[laeubi]

@HannesWell can we merge this one?