ocm-lib introduction #367

fabianburth · 2023-05-15T09:37:47Z

What this PR does / why we need it:
It provides an introduction and overview of the ocm-lib to help other developers to get started.

Which issue(s) this PR fixes:
Fixes #

Special notes for your reviewer:

Release Notes:

docs/lib/introduction.md

In-Ko · 2023-05-22T10:10:14Z

docs/lib/introduction.md

+that has a corresponding _Type Registry_ is considered an extension point implementation (in the previous
+examples, the _simplemessage package_ and the _complexmessage package_ are extension points as they
+implement the _Message_ interface and there is a _Message Type Registry_).  
+**Settings:** On a conceptual level, settings are values that may be set for specific objects or passed to specific


Suggested change

**Settings:** On a conceptual level, settings are values that may be set for specific objects or passed to specific

**Settings:** Settings are values that may be set for specific objects or passed to specific

In-Ko · 2023-05-22T10:21:28Z

docs/lib/introduction.md

+Again, within the ocm-lib, there are multiple implementations of this interface. But most importantly, the package
+[`genericocireg`](../../pkg/contexts/ocm/repositories/genericocireg) provides an implementation of the _OCM Repository
+interface_ that is based on the _OCI Repository interface_. In other words, this package provides a mapping of the
+_OCM Repository_ functionility to the _OCI Repository_ functionality. The


Suggested change

_OCM Repository_ functionility to the _OCI Repository_ functionality. The

_OCM Repository_ functionality to the _OCI Repository_ functionality. The

In-Ko · 2023-05-22T10:24:09Z

docs/lib/introduction.md

+Thus, as there is an **oci** _repository type_ `OCIRegistry`, there is also an **ocm** _repository type_ `OCIRegistry`,
+as there is an **oci** _repository type_ `CommonTransportFormat`, there is also an **ocm** _repository type_
+`CommonTransportFormat`.
+Within the ocm-lib this is implemented through an **addition to the factory-based type registry** concept. In case the


I guess a word is missing here after "In case the ... "

In-Ko · 2023-05-22T10:26:23Z

docs/lib/introduction.md

+(called `defaultdecoder`). For the OCM Repository Type Registry, this _fallback factory_ is usually
+[initialized](../../pkg/contexts/ocm/builder.go) with a Type Registry itself, the
+[`DefaultDelegationRegistry`](../../pkg/contexts/ocm/repositories/genericocireg/type.go) which is based on the
+[`delegationRegistry`](../../pkg/contexts/ocm/internal/delegation.go). This Type Registry's iterates through all its


Suggested change

[`delegationRegistry`](../../pkg/contexts/ocm/internal/delegation.go). This Type Registry's iterates through all its

[`delegationRegistry`](../../pkg/contexts/ocm/internal/delegation.go). This Type Registry iterates through all its

In-Ko · 2023-05-22T10:26:58Z

docs/lib/introduction.md

+[initialized](../../pkg/contexts/ocm/builder.go) with a Type Registry itself, the
+[`DefaultDelegationRegistry`](../../pkg/contexts/ocm/repositories/genericocireg/type.go) which is based on the
+[`delegationRegistry`](../../pkg/contexts/ocm/internal/delegation.go). This Type Registry's iterates through all its
+factories and checks whether they knew that type. Currently, the only factory known by this _fallback Type Registry_ is


Suggested change

factories and checks whether they knew that type. Currently, the only factory known by this _fallback Type Registry_ is

factories and checks whether one of them know that type. Currently, the only factory known by this _fallback Type Registry_ is

In-Ko · 2023-05-22T14:44:38Z

docs/lib/introduction.md

+
+**Other Repository Types:**
+Besides _OCM_ and _OCI Repository Types_, there currently also exist a number of
+[_Credential Repository Types_](../../pkg/contexts/credentials/repositories) that have to implement the following


I don't quite get this: If these Credential Repo Types already exist, what is then meant with "that have to implement the following interface" ? If they do exist, wouldn't that mean they have already implemented the interface ?

In-Ko · 2023-05-22T14:57:04Z

docs/lib/introduction.md

+a specific configuration for dealing with this _access type (= model type)_.
+
+From the perspective of the ocm-lib, any _go type_ that implements the following
+[interface](../../pkg/contexts/ocm/internal/accesstypes.go) can be considered an _OCI Repository_:


Why can the existence of a go type implementing this AccessMethod interface be considered a OCI repository ? Below, an implementation for S3 or GitHub are mentioned as examples, which is not an OCI repositories, so maybe rather "OCM Repository" is meant here ?

That's a copy-paste mistake. It should be ...can be considered an Access Method.

In-Ko · 2023-05-22T15:03:11Z

docs/lib/introduction.md

+a triple of _RepositoryType_ (e.g. `OCIRegistry`, `CommonTransportFormat`, ...), _ArtifactType_ (e.g. `OCIArtifact`,
+`ociImage`, ...) and _MimeType_ (e.g. `text/plain`, `application/gzip`, ...). The upload logic passes the current
+contextual information about the underlying _storage repository type_ and the _artifact_ and _mime type_ at hand to the
+_Lookup Handler_ method a _Constraint Registry_, which eventually returns a number of _Handlers_ fulfilling the


Suggested change

_Lookup Handler_ method a _Constraint Registry_, which eventually returns a number of _Handlers_ fulfilling the

_Lookup Handler_ method of a _Constraint Registry_, which eventually returns a number of _Handlers_ fulfilling the

In-Ko · 2023-05-22T15:06:36Z

docs/lib/introduction.md

+
+### Section 3.3 - Constraint Registries aka. Handler Registries (and Handler-Registration Handler Registries)
+
+**Constraint Registries aka. Handler Registries**  


Why are these called CONSTRAINT Registries ? That term seems a bit unintuitive, no ?

In-Ko · 2023-05-22T15:11:36Z

docs/lib/introduction.md

+}
+```
+
+Thus, a `HandlerRegistrationHandlerRegistry` also is itself also a  `HandlerRegistrationHandler`.


Suggested change

Thus, a `HandlerRegistrationHandlerRegistry` also is itself also a `HandlerRegistrationHandler`.

Thus, a `HandlerRegistrationHandlerRegistry` is itself also a `HandlerRegistrationHandler`.

In-Ko · 2023-05-22T15:14:20Z

docs/lib/introduction.md

+`BlobHandlerRegistry` by calling the BlobHandlerRegistry's _Register_ method (e.g. in an
+[init](../../pkg/contexts/ocm/blobhandler/oci/ocirepo/blobhandler.go) function to register that implementation in a
+DefaultRegistry). Thereby, you have to pass an object of that handler implementation to the _Register_ method.  
+But imagine you are working with the _ocm-cli_ and you want to register either a predefined `BlobHandler` (in other


Suggested change

But imagine you are working with the _ocm-cli_ and you want to register either a predefined `BlobHandler` (in other

But imagine you are working with the _ocm-cli_ and you want to register a predefined `BlobHandler` (in other

In-Ko · 2023-05-22T15:18:18Z

docs/lib/introduction.md

+`BlobHandlerRegistry` by calling the BlobHandlerRegistry's _Register_ method (e.g. in an
+[init](../../pkg/contexts/ocm/blobhandler/oci/ocirepo/blobhandler.go) function to register that implementation in a
+DefaultRegistry). Thereby, you have to pass an object of that handler implementation to the _Register_ method.  
+But imagine you are working with the _ocm-cli_ and you want to register either a predefined `BlobHandler` (in other


What would be a usecase for registering such a predefined Handler ? Why is this a necessary feature to have , making things rather complex ? I would like to see some real-world example here, which could really help to motivate the reader to understand this complex stuff ...

In-Ko · 2023-05-22T15:26:28Z

docs/lib/introduction.md

+}
+```
+
+A `RepositorySpecHandlers` Registry **is not** also a `HandlerRegistrationHandlerRegistry`.


Why is it necessary to state this so explicitly here ? And if it is necessary, some reasoning why this is not the case should be provided.

In-Ko · 2023-05-22T15:29:20Z

docs/lib/introduction.md

+These decisions can be made within BlobHandlers. The `StoreBlob` method has to return an `AccessSpec` that can then be
+inserted into the corresponding new _Component Descriptor_.
+
+A `BlobHanderRegistry` **is** also a `HandlerRegistrationHandlerRegistry`.


Same as above: If it is necessary to state this here so explicitly, then some reasoning would be nice.

In-Ko · 2023-05-22T15:32:51Z

docs/lib/introduction.md

+Here, the different _Contexts_ shown in the overview are explained.
+
+A context object is the _entry point_ for using dedicated functional areas. It bundles all _settings_ and
+_extensions point implementations_ for this area.


Suggested change

_extensions point implementations_ for this area.

_extension point implementations_ for this area.

morri-son · 2024-03-25T15:50:23Z

@fabianburth @mandelsoft What should happen with this issue?

fabianburth added 4 commits May 15, 2023 11:33

ocm-lib introduction (work in progress)

4aa2a52

update section 3.2.1 - repository types scheme

a53af7a

update section 3.2.2 - access type scheme

c370236

update section 3.2.3 - repository spec handlers

ea28fc2