Package net.sf.saxon.trans.packages

## Class PackageLibrary

- java.lang.Object
- - net.sf.saxon.trans.packages.PackageLibrary

-     public class PackageLibrary
      extends java.lang.Object

  A PackageLibrary represents a collection of packages that can be searched, typically to satisfy an xsl:use-package declaration. Packages are indexed by their package name and version. It is possible to index a package under a different name and/or version than appears in the source code; this allows the same source package to be compiled into two different variants with different settings for static parameters, so that the xsl:use-package declaration can pick up one or the other by a suitable choice of package name or version. A package can also have a short-form alias, which is ignored by xsl:use-package, but can be used to identify the package in the -xsl option of the Transform command line (this is only useful when the package is set up from a configuration file).

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `PackageLibrary​(CompilerInfo compilerInfo)` | Create an empty package library
    `PackageLibrary​(CompilerInfo info, java.util.Set<java.io.File> files)` | Create a package library from a set of source files (being either the source XSLT of the top-level modules of the packages in question, or the exported SEF file representing the compiled package)
    `PackageLibrary​(PackageLibrary library)` | Create a package library as a copy of an existing package library

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `addPackage​(java.io.File file)` | Add a package supplied in the form of a file: either a source XSLT package, or an exported package
    `void` | `addPackage​(StylesheetPackage packageIn)` | Add a compiled and loaded package to this package library.
    `void` | `addPackage​(PackageDetails details)` | Add an entry for a package to the library
    `PackageDetails` | `findDetailsForAlias​(java.lang.String shortName)` | Find the entry with a given shortName.
    `PackageDetails` | `findPackage​(java.lang.String name, PackageVersionRanges ranges)` | Find a package from the library that has the given name and whose version lies in the given ranges.
    `CompilerInfo` | `getCompilerInfo()` |
    `java.util.List<StylesheetPackage>` | `getPackages()` | Supply all the packages that currently exist in this library
    `StylesheetPackage` | `obtainLoadedPackage​(PackageDetails details, java.util.List<VersionedPackageName> disallowed)` | Obtain a loaded package, given details of the package.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### PackageLibrary

          public PackageLibrary​(CompilerInfo compilerInfo)

      Create an empty package library
      Parameters:
        `compilerInfo` - the compiler options to be used if any package from the library needs to be compiled. The package library retains a reference to the CompilerInfo, so any subsequent changes to the options in the CompilerInfo will take effect.

    - #### PackageLibrary

          public PackageLibrary​(PackageLibrary library)

      Create a package library as a copy of an existing package library
      Parameters:
        `library` - the existing package library to be copied. The new package library will contain a reference to the same CompilerInfo as the supplied package library, and any subsequent changes to this CompilerInfo will take effect.

    - #### PackageLibrary

          public PackageLibrary​(CompilerInfo info,
                                java.util.Set<java.io.File> files)
                         throws XPathException

      Create a package library from a set of source files (being either the source XSLT of the top-level modules of the packages in question, or the exported SEF file representing the compiled package)
      Parameters:
        `info` - the compiler to which this library belongs
        `files` - the files making up the package library
      Throws:
        `XPathException` - if any of the files doesn't have a top-level xsl:package element containing the package name and package-version attributes. Note that validation of the content of the file is minimal; if the name and version can be successfully extracted, then full validation will be carried out if and when the package is actually used.

  - ### Method Detail

    - #### getCompilerInfo

          public CompilerInfo getCompilerInfo()

    - #### addPackage

          public void addPackage​(StylesheetPackage packageIn)

      Add a compiled and loaded package to this package library. This will replace any existing package with the same name and version.
      Parameters:
        `packageIn` - The stylesheet package to be added

    - #### addPackage

          public void addPackage​(PackageDetails details)

      Add an entry for a package to the library
      Parameters:
        `details` - details of the package to be added. The package referenced in these details may exist in either source or compiled form. No static processing or validation takes place at this stage.

    - #### addPackage

          public void addPackage​(java.io.File file)
                          throws XPathException

      Add a package supplied in the form of a file: either a source XSLT package, or an exported package
      Parameters:
        `file` - a file to be added to the package library
      Throws:
        `XPathException`

    - #### findPackage

          public PackageDetails findPackage​(java.lang.String name,
                                            PackageVersionRanges ranges)

      Find a package from the library that has the given name and whose version lies in the given ranges. If multiple versions exist, select the one with highest priority or version number.
      Parameters:
        `name` - The name of the package. This must match the name under which the package is registered in the library, which is not necessarily the same as the package name appearing in the source code.
        `ranges` - The ranges of versions of that package that are acceptable
      Returns:
        Details of the package that best meets the criteria, or null if none can be found. The name of the package must match; if there are multiple versions, then the version chosen is based first on the priority attached to this package/version in the library, and if the priorities are equal (or there are no explicit priorities) then the one with highest version number is taken.

    - #### findDetailsForAlias

          public PackageDetails findDetailsForAlias​(java.lang.String shortName)

      Find the entry with a given shortName.
      Parameters:
        `shortName` - the shortName of the entry
      Returns:
        the PackageDetails for this shortName if present, or null otherwise.
      Throws:
        `java.lang.IllegalStateException` - if there is more than one entry with the requested shortName

    - #### obtainLoadedPackage

          public StylesheetPackage obtainLoadedPackage​(PackageDetails details,
                                                       java.util.List<VersionedPackageName> disallowed)
                                                throws XPathException

      Obtain a loaded package, given details of the package. This will return the package if it is already loaded; otherwise it will attempt to compile and/or load the package from XSLT source or from an export file. It will also load all the packages on which it depends, recursively, and will report an error if any cycles are found.
      Parameters:
        `details` - the package details for the required package, as previously returned (perhaps) using `findPackage(String, PackageVersionRanges)`
        `disallowed` - the names/versions of packages that reference this package, and that therefore cannot be referenced by this package without creating a cycle of dependencies.
      Returns:
        the loaded package
      Throws:
        `XPathException` - if loading the package fails, typically either because (a) a package contains static XSLT errors, or (b) because there is a cycle of package dependencies
      Since:
        9.8

    - #### getPackages

          public java.util.List<StylesheetPackage> getPackages()

      Supply all the packages that currently exist in this library
      Returns:
        every package indexed