saker.nest Documentation TaskDoc JavaDoc Packages
public interface BundleLookup
Lookup interface to resolve bundles.

This interface provides access to various resolution methods that look up appropriate information based on bundle related inputs. In general it is used to query information about bundles, and the bundles themselves with a given bundle identifier or bundle name.

Each bundle lookup has a different scope that it resolves information in. Based on the storage configuration that was used to initialize the repository, each bundle lookup may resolve different bundles. It may be that if a bundle is visible from a given bundle lookup, it may not be visible from a different one.

Bundle lookups are often relative to a given resolved bundle. This is necessary, as accidental misresolution of bundles need to be avoided.
Given the following example:

Given the storage configuration [s1, s2, s3], and where the following bundles are contained in them:

  • s1: bundle.dep
  • s2: bundle.simple
  • s3: bundle.dep
We can see that the bundle with name bundle.dep is present multiple times in s1 and s2. In this scenario, assume that bundle.simple has a dependency on bundle.dep.

When we first resolve bundle.simple using the root lookup, we will find it in s2. After that, we need to resolve bundle.dep, as bundle.simple depends on it. If we used the root lookup again, we would find it in s1. However, that would be erroneous, as based on the storage configuration, we would have to use the bundle.dep in s3.

In this case, instead of using the root lookup, we use the relative lookup of bundle.simple that doesn't contain a back reference to s1, therefore correctly resolving bundle.dep in s3.

The resolution methods in this class also return an appropriate relative lookup object to use for further resolutions.

Bundle lookups also have a LookupKey associated with them, that uniquely identifies a given lookup object in the configuration. These keys may be serialized and used to query the lookup object for them. This can be used to properly support incremental builds and other operations.

This interface is not to be implemented by clients.

Methods
public Map<String, String>
Creates a repository user parameter configuration that provides access to the bundles accessible from this bundle lookup.
public LookupKey
Gets the unique lookup key for this bundle lookup.
public BundleLookupResult
Looks up a bundle with a given identifier.
public BundleIdentifierLookupResult
Look up bundle identifiers of bundles that have the same bundle name as the argument.
public BundleInformationLookupResult
Looks up a bundle information for the given identifier.
public BundleVersionLookupResult
Looks up the identifiers of bundles which only differ (or equal) in version number to the argument.
Creates a repository user parameter configuration that provides access to the bundles accessible from this bundle lookup.

This method can be used to create the user parameters that can be used to configure the repository the way that the same bundles are accessible as from this bundle lookup object.

This method is generally useful when external processes need to be spawned that use the classes the same way as the storage is currently configured from the view of this lookup.

One use-case for this is when Java compilation needs to be executed using a different JDK. In this case the compiler build task will spawn a new process that uses the saker.build runtime, loads the Nest repository, and the required compiler bundles to execute the compilation. However, in order for the new process to be able to locate the compiler bundles, the storage of the Nest repository needs to be configured appropriately. This method will create the configuration user parameters that can be directly passed to the spawned Nest repository to interpret.

Different bundle lookups may produce different results.

The returned parameters only contains NestBundleStorageConfiguration.PARAMETER_NEST_REPOSITORY_STORAGE_CONFIGURATION from the bundle storage configuration parameters. Constraints, task version pins, etc... are not included and need to be added manually. All appropriate storage view parameters will be included.

The created parameter map can only be used on the local file system.

repositoryidThe repository identifier to prefix the user parameters with. Specify null to use the default. ("nest")
The created configuration.
UnsupportedOperationExceptionIf the current configuration cannot be converted to parameters that can be used on the local file system.
public abstract LookupKey getLookupKey()
Gets the unique lookup key for this bundle lookup.
The lookup key.
Looks up a bundle with a given identifier.

The operation will attempt to load the NestRepositoryBundle for the given bundle identifier. If the bundle was not found, or cannot be loaded, BundleLoadingFailedException is thrown.

Some storages may require that the argument bundle identifier has a version qualifier.

bundleidThe bundle identifier to look up.
The bundle lookup result. Never null.
NullPointerExceptionIf the argument is null.
BundleLoadingFailedExceptionIf the bundle lookup failed.
Look up bundle identifiers of bundles that have the same bundle name as the argument.

The method will search for all bundles that have the same bundle name as the argument. The results are returned in the lookup result object.

bundlenameThe bundle name to get the bundles of.
The result of the lookup or null if no bundles found with the given name.
NullPointerExceptionIf the argument is null.
IllegalArgumentExceptionIf the argument is not a valid bundle name.
Looks up a bundle information for the given identifier.

The operation will attempt to get the BundleInformation for the given bundle identifier. If the bundle was not found, or the information cannot be loaded, BundleLoadingFailedException is thrown.

Some storages may require that the argument bundle identifier has a version qualifier.

bundleidThe bundle identifier to look up the information for.
The bundle information lookup result. Never null.
NullPointerExceptionIf the argument is null.
BundleLoadingFailedExceptionIf the bundle information lookup failed.
Looks up the identifiers of bundles which only differ (or equal) in version number to the argument.

This method will search for bundles which have the same bundle name and qualifiers (except the version qualifier) as the argument. The found bundle identifiers are returned in the lookup result.

Any version qualifier in the agument bundle identifier is ignored by this method.

bundleidThe bundle identifier to look up the versions for.
The result of the lookup or null if no bundle identifiers were found.
NullPointerExceptionIf the argument is null.