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 and 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

Modifier and Type	Method and 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(PackageDetails details) Add an entry for a package to the library
void	addPackage(StylesheetPackage packageIn) Add a compiled and loaded package to this package 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.
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 a 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

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

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.

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 a 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