Package com.tccc.kos.core.primary.service.nodemgr.install

Class DeviceInstallBuilder

java.lang.Object
com.tccc.kos.core.primary.service.nodemgr.install.DeviceInstallBuilder
All Implemented Interfaces:
KabSource
public class DeviceInstallBuilder extends Object implements KabSource
Builder used to define a full kOS device installation. All installations within kOS are driven by a chain of manifest kabs which contains some form of DeviceManifest. Different implementations of DeviceManifest can exist and the installer need not understand the entire format to perform an installation.

Fundamentally, a manifest defines all the kabs required to get kOS into the state defined by the manifest, which in turn, defines the list of kabs that need to be installed. A DeviceManifest can define the state of multiple nodes in a multi-node device, and all kabs across all nodes must be installed on the primary node of the device. This means that all installations occur on the primary node of the device and kOS will handle installation of all other nodes in the device, even if they are added after the installation has occurred.

This builder is provided the manifest to install and a list of kabs (via KabSource) that correspond to the kabs listed in the manifest. It is ok for the kab sources to include more kabs than are required by the manifest as only those kabs listed in the manifest will be considered. The install process will also factor in kabs that are already installed on the device and only install kabs that are missing.

Since an installation is defined by the DeviceManifest, the builder must have a manifest to initiate the install. There are two options to satisfy this requirement:

  • Specify the actual manifest kab. Since the actual KabFile is specified, The kab does not need to be visible in any of the provided sources.
  • Specify the identifier of the manifest kab. This requires that the manifest kab be visible through the specified sources.
Version:
2023-10-12

  • Field Details

  • Method Details

    • setManifestId

      public DeviceInstallBuilder setManifestId(String manifestId)
      Set the identifier of the manifest. The kab will be fetched from the specified sources.
      Parameters:
      manifestId - identifier of the manifest kab

    • setManifestKab

      public DeviceInstallBuilder setManifestKab(KabFile manifestKab)
      Set the manifest kab. If set, setManifestId() will be ignored.
      Parameters:
      manifestKab - the manifest kab to use

    • addSource

      public DeviceInstallBuilder addSource(KabSource source)
      Add a kab source to the builder. Sources will be examined in the order in which they are added allowing for composite sources to be used.
      Parameters:
      source - the kab source to add

    • build

      public void build()
      Build a ResolvedDeviceManifest from the builder.

    • isChainComplete

      public boolean isChainComplete()
      Return true if the manifest chain is complete. At this point all required kabs are known and the required list can be used to garbage collect external kab sources.

    • getRequiredKabs

      public Collection<String> getRequiredKabs()
      Return the list of required kab id's based on the current manifest chain. This can be used to garbage collect kab sources. This list should only be used once isChainComplete() returns true as it's only possible to know all required kabs once the full manifest chain has been evaluated.

    • isComplete

      public boolean isComplete()
      Return true if the manifest chain is complete and all dependencies referenced in the chain are available and valid. If not complete, use the following methods to process the results:
      • getMissingKabs() : Returns a list of kab id's that are referenced but missing. This may be a manifest in the chain or artifacts that make up the release.
      • getCorruptKabs() : Returns a list of kab id's that are considered corrupt due to mini-hash or signature check failures. It is possible that these can be replaced with another copy that is not corrupt. These are also included in the invalid list.
      • getInvalidKabs() : Returns a list of kab that are not installable. This includes corrupt kabs as well as kabs that fail for other reasons such as expired certs and so on.

    • getMissingKabs

      public Set<String> getMissingKabs()
      Return the list of kab id's referenced by the manifest but are not available from any of the sources. Can only be called after calling build() .

    • getFirstMissingKab

      public String getFirstMissingKab()
      Get the first kabId from the missing list.

    • getCorruptKabs

      public Map<String,String> getCorruptKabs()
      Return the list of kab id's referenced by the manifest but are not valid due to potential file corruption. Can only be called after calling build() .

    • getInvalidKabs

      public Map<String,String> getInvalidKabs()
      Return the list of kab id's referenced by the manifest but are not valid due to some validation error. This list includes corrupted kabs as well as kabs that contain other validation failures such as out of date certs. The map key is the kab id and the value is the validation failure. Can only be called after calling build() .

    • getAvailableKabs

      public Set<String> getAvailableKabs()
      Return the list of kab id's that are currently available and valid. This is the list of required kabs minus missing and invalid.

    • getManifestArtifact

      public BaseManifestArtifact getManifestArtifact(String id)
      Return the BaseManfiestArtifact for the specified id. If the id identifies a manifest or a kab not included in the manifest chain then this will return null.
      Parameters:
      id - id of the kab
      Returns:
      BaseManifestArtifact or null

    • getKabByIdentifier

      public KabFile getKabByIdentifier(String identifier)
      Description copied from interface: KabSource
      Return the kab file with the specified identifier.
      Specified by:
      getKabByIdentifier in interface KabSource

    • getInitialManifestId

      public String getInitialManifestId()

    • getManifestKab

      public KabFile getManifestKab()

    • getMissingManifestId

      public String getMissingManifestId()

    • getManifestChain

      public List<KabFile> getManifestChain()