de.infinityloop.util.xslt
Class ExtensionFunctions

java.lang.Object
  de.infinityloop.util.xslt.ExtensionFunctions

public class ExtensionFunctions
extends java.lang.Object

This class encapsulates XSLT extension function implementations for some often-needed handy utilities.

Except when noted otherwise for a function, the general usage pattern is as follows:

1. Create a namespace prefix mapping for the namespace in the <xsl:stylesheet> element, e.g.:

   xmlns:ilext="java:de.infinityloop.util.xslt.ExtensionFunctions" (for Saxon) or xmlns:ilext="xalan://de.infinityloop.util.xslt.ExtensionFunctions" (for Xalan)

2. In your XSLT, call the static member function:

   ilext:functionName( ...parameters if any... )

3. Add the prefix to the list of excluded prefixes in the result in the <xsl:stylesheet> element:

   exclude-result-prefixes="ilext ...other prefixes..."

Example:

<xsl:value-of select="ilext:URLToLocal(@href)" />

The above converts the value of the href attribute, which is supposed to be a URI reference, to local file naming convention.

Since:

upCast 5.4 / downCast 1.7

Author:

Christian Roth

Constructor Summary

ExtensionFunctions()

Method Summary

static double	absolutizeLength(java.lang.String length, java.lang.String fontsize, java.lang.String referenceValue, java.lang.String resultDimension) Converts and absolutizes the passed length specification to the given dimension.
static double	addLengths(java.lang.String length1, java.lang.String length2, java.lang.String resultDimension) Adds two absolute length values, even if using different dimensions.
static java.lang.String	calcCALSTablegrid(java.lang.String xml)
static java.lang.String	calcTableColgroup(java.lang.String tableXMLCode) Returns a serialized colspec element mirroring the column widths of the passed table code.
static double	convertLength(java.lang.String length, java.lang.String resultDimension) Converts the passed absolute length specification to the given dimension.
static java.lang.String	emptyString(boolean whatever) Returns an empty string
static java.lang.String	emptyString(java.lang.String whatever) Returns an empty string
static java.lang.String	FileCalcAbsolutePath(java.lang.String basePath, java.lang.String relativePath) Returns the absolute path for the relative one passed in, based on the absolute base path also specified.
static java.lang.String	FileCalcRelativePath(java.lang.String basePath, java.lang.String destPath) Returns the relative path from the base path to the destination path in URL format.
static boolean	FileExists(java.lang.String name) Tests if a local file or folder exists already in the file system.
static java.lang.String	FileGetBasename(java.lang.String name) Retrieves only the basename (i.e. the name without path, extension and trailing dot) of the specified file (if it is a file), the name otherwise.
static java.lang.String	FileGetName(java.lang.String name) Retrieves the name of the specified file (including extension).
static java.lang.String	FileGetPathOnly(java.lang.String name) Retrieves the folder path to the specified file (if it is a file), otherwise returns the argument unaltered.
static java.lang.String	filterCSSExcluding(java.lang.String src, java.util.List filter) Filter the passed string of CSS property definitions so that it contains all properties not matching one of the elements in the Sequence of filter string.
static java.lang.String	filterCSSIncluding(java.lang.String src, java.util.List filter) Filter the passed string of CSS property definitions so that it contains all properties matching one of the elements in the Sequence of filter string.
static java.lang.String	getRealmValue(java.lang.String pipelineInstanceId, java.lang.String realm, java.lang.String name, java.lang.String dflt) This method retrieves the value of a variable in a specified realm.
static int	getUnicodeFromFontchar(java.lang.String pipelineInstanceId, java.lang.String fontFamily, int index) This method tries to retrieve the Unicode codepoint equivalent of character index in font fontFamily.
static int	getUnicodeFromFontchar(java.lang.String pipelineUID, java.lang.String fontFamily, java.lang.String string)
static java.lang.String	getVersion() retrieves version information
static java.lang.String	localToURL(java.lang.String local) Returns the URL representation of the passed local filename.
static void	main(java.lang.String[] args) Extension function test method
static java.lang.String	makeValidXML_ID(java.lang.String src) Transform a passed string in such a way that the result conforms to the rules for an XML 1.0 'Name' (as used e.g. for element names or xml:id).
static java.lang.String	makeValidXMLName(java.lang.String src) Transform a passed string in such a way that the result conforms to the rules for an XML 1.0 'Name' (as used e.g. for element names or xml:id).
static double	multiplyLength(java.lang.String length, double factor, java.lang.String resultDimension) Multiply an absolute length by some factor.
static int	parseInteger(java.lang.String numberstring, int radix) This method parses a string into an integer using the specified numbering base.
static org.w3c.dom.DocumentFragment	parsePersonname(java.lang.String s) SAXON EXTENSION function: parse a string into a personname document fragment.
static void	setRealmValue(java.lang.String pipelineInstanceId, java.lang.String realm, java.lang.String name, java.lang.String value) This method sets a value in the specified realm.
static double	subtractLengths(java.lang.String length1, java.lang.String length2, java.lang.String resultDimension) Subtracts two absolute length values, even if using different dimensions.
static java.lang.String	toHexString(long value) This method converts the passed long value to its corresponding representation as a string of hexadecimal digits.
static java.lang.String	toHexString(long value, int length) This method converts the passed long value to its corresponding representation as a string of hexadecimal digits.
static java.lang.String	url2xml(java.lang.String url) This method parses a passed URL into its constituents and returns a string of XML source code that encapsulates the various parts into appropriate elements.
static java.lang.String	URLToLocal(java.lang.String url) Returns the local file name representation of the passed URL, if it's a file: URL; returns the normalized URL otherwise.
static boolean	writeLineToFile(java.lang.String url, java.lang.String line, boolean append) Writes the passed String followed by the platform-specific new line character to the specified file, optionally appending the data (instead of replacing any existing data).
static boolean	writeLineToFile(java.lang.String url, java.lang.String line, boolean append, java.lang.String encoding) Writes the passed String followed by the platform-specific new line character to the specified file, optionally appending the data (instead of replacing any existing data).
static boolean	writeStringToFile(java.lang.String url, java.lang.String data, boolean append) Writes the passed String to the specified file, optionally appending the data (instead of replacing any existing data).
static boolean	writeStringToFile(java.lang.String url, java.lang.String data, boolean append, java.lang.String encoding) Writes the passed String to the specified file, optionally appending the data (instead of replacing any existing data).

Methods inherited from class java.lang.Object

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

Constructor Detail

ExtensionFunctions

public ExtensionFunctions()

Method Detail

emptyString

public static java.lang.String emptyString(java.lang.String whatever)

Returns an empty string

Parameters:

whatever -

Returns:

emptyString

public static java.lang.String emptyString(boolean whatever)

Returns an empty string

Parameters:

whatever -

Returns:

localToURL

public static java.lang.String localToURL(java.lang.String local)

Returns the URL representation of the passed local filename. If you pass in a string that is already in URL fromat, it is returned normalized.

Parameters:

local - the file name in local format

Returns:

the file name in URL format

URLToLocal

public static java.lang.String URLToLocal(java.lang.String url)

Returns the local file name representation of the passed URL, if it's a file: URL; returns the normalized URL otherwise.

Parameters:

url - the file name in URL format

Returns:

the file name in local naming convention for the platform it originates seemingly from

FileExists

public static boolean FileExists(java.lang.String name)

Tests if a local file or folder exists already in the file system.

Parameters:

name - the file to test for in URL format

Returns:

a boolean, true when the file or folder exists, false otherwise

FileGetBasename

public static java.lang.String FileGetBasename(java.lang.String name)

Retrieves only the basename (i.e. the name without path, extension and trailing dot) of the specified file (if it is a file), the name otherwise.

Parameters:

name - the absolute file name in either URL or local notation

Returns:

the empty string (""), if the name can not be determined, the basefile name if it is a file, or the name otherwise

Since:

upCast 6.0 / downCast 2.0

FileGetName

public static java.lang.String FileGetName(java.lang.String name)

Retrieves the name of the specified file (including extension).

Parameters:

name - the absolute file name in either URL or local notation

Returns:

the empty string (""), if the name can not be determined, the file or folder name otherwise

Since:

upCast 6.0 / downCast 2.0

FileGetPathOnly

public static java.lang.String FileGetPathOnly(java.lang.String name)

Retrieves the folder path to the specified file (if it is a file), otherwise returns the argument unaltered.

Parameters:

name - the absolute file name in either URL or local notation

Returns:

the empty string (""), if the path can not be determined, the folder path in local file path notation otherwise.

Since:

upCast 6.0 / downCast 2.0

FileCalcAbsolutePath

public static java.lang.String FileCalcAbsolutePath(java.lang.String basePath,
                                                    java.lang.String relativePath)

Returns the absolute path for the relative one passed in, based on the absolute base path also specified. For example, FileCalcAbsolutePath( "/usr/test/dir/", "../" ) returns "/usr/test/" (incl. trailing folder separator).

Parameters:

basePath - the basepath where relativePath should be interpreted relative to

relativePath - the relative path to make absolute with respect to the base path. If it is already absolute, it is returned unaltered.

Returns:

the absolute path

Since:

upCast 6.0 / downCast 2.0

FileCalcRelativePath

public static java.lang.String FileCalcRelativePath(java.lang.String basePath,
                                                    java.lang.String destPath)

Returns the relative path from the base path to the destination path in URL format.

Parameters:

basePath - the path where we start navigation

destPath - the path where we want to be

Returns:

the relative path from basePath to destPath in file:-URL format. Might be "" if both are the same, or may be absolute if destPath is on a different volume.

Since:

upCast 6.0 / downCast 2.0

addLengths

public static double addLengths(java.lang.String length1,
                                java.lang.String length2,
                                java.lang.String resultDimension)

Adds two absolute length values, even if using different dimensions. The result dimension must also be specified.

Parameters:

length1 - the first length, e.g. "2mm"

length2 - the second length to add, e.g. "3.67in"

resultDimension - the dimension the result should be returned in, e.g. "cm"

Returns:

the resulting length as a double, assuming the specified destination dimension

convertLength

public static double convertLength(java.lang.String length,
                                   java.lang.String resultDimension)

Converts the passed absolute length specification to the given dimension.

Parameters:

length - the first length, e.g. "2mm"

resultDimension - the dimension the result should be returned in, e.g. "in"

Returns:

the resulting length as a double, assuming the specified destination dimension

absolutizeLength

public static double absolutizeLength(java.lang.String length,
                                      java.lang.String fontsize,
                                      java.lang.String referenceValue,
                                      java.lang.String resultDimension)

Converts and absolutizes the passed length specification to the given dimension.

Parameters:

length - the specified length, e.g. "2mm" or "100%" or "1.2em"

fontsize - the current fontsize

referenceValue - the reference value for percent specifications

resultDimension - the dimension the result should be returned in, e.g. "in"

Returns:

the resulting length as a double, assuming the specified destination dimension

subtractLengths

public static double subtractLengths(java.lang.String length1,
                                     java.lang.String length2,
                                     java.lang.String resultDimension)

Subtracts two absolute length values, even if using different dimensions. The result dimension must also be specified.

Parameters:

length1 - the first length, e.g. "2mm"

length2 - the length to subtract from length1, e.g. "3.67in"

resultDimension - the dimension the result should be returned in, e.g. "cm"

Returns:

the resulting length as a double, assuming the specified destination dimension

multiplyLength

public static double multiplyLength(java.lang.String length,
                                    double factor,
                                    java.lang.String resultDimension)

Multiply an absolute length by some factor. The result dimension must also be specified.

Parameters:

length - the first length, e.g. "2mm"

factor - the factor to multiply the length with, e.g. "2.54"

resultDimension - the dimension the result should be returned in, e.g. "cm"

Returns:

the resulting length as a double, assuming the specified destination dimension

makeValidXMLName

public static java.lang.String makeValidXMLName(java.lang.String src)

Transform a passed string in such a way that the result conforms to the rules for an XML 1.0 'Name' (as used e.g. for element names or xml:id). Invalid characters are replaced by '-' if within the name, and prepended by an additional '_' when at the beginning. Also note that a starting colon ':' will not be allowed by this function, as it has special meaning in XML Namespaces. Therefore, consider the passed string as only the local name of an element.

Important Note: This method does not guarantee that for different source strings the output will be different as well! For example, both 1elem and _1elem will be converted to _1elem: The first will be modified by prepending a '_', while the second is already a valid XML Name and therefore passed unchanged.

Parameters:

src - the source string

Returns:

a string that matches the XML 1.0 Name production.

makeValidXML_ID

public static java.lang.String makeValidXML_ID(java.lang.String src)

Transform a passed string in such a way that the result conforms to the rules for an XML 1.0 'Name' (as used e.g. for element names or xml:id). Invalid characters are replaced by '-' if within the name, and prepended by an additional '_' when at the beginning. This is essentially the same method as makeValidXMLName(), but additionally allows the colon character ':' .

Important Note: This method does not guarantee that for different source strings the output will be different as well! For example, both 1elem and _1elem will be converted to _1elem: The first will be modified by prepending a '_', while the second is already a valid XML Name and therefore passed unchanged.

Parameters:

src - the source string

Returns:

a string that matches the XML 1.0 Name production.

filterCSSExcluding

public static java.lang.String filterCSSExcluding(java.lang.String src,
                                                  java.util.List filter)

Filter the passed string of CSS property definitions so that it contains all properties not matching one of the elements in the Sequence of filter string. For the string sequence of filter, you either pass the (unquoted) full property name, or you can use the '*' qualifier to be used after some prefix. E.g. to filter out all Mozilla-proprietary CSS properties, use a filter sequence of ('-moz-*').

Example:

ilext:filterCSSExcluding( @style, (, 'width', '-moz-*') ) removes the width property and all properties starting with -moz- from the property list string in the style attribute of the context element.

Parameters:

src - the source string, consisting of property definitions

filter - a sequence of filter strings

Returns:

the filtered CSS property string

filterCSSIncluding

public static java.lang.String filterCSSIncluding(java.lang.String src,
                                                  java.util.List filter)

Filter the passed string of CSS property definitions so that it contains all properties matching one of the elements in the Sequence of filter string. For the string sequence of filter, you either pass the (unquoted) full property name, or you can use the '*' qualifier to be used after some prefix. E.g. to only retain all Mozilla-proprietary CSS properties, use a filter sequence of ('-moz-*').

Example:

ilext:filterCSSIncluding( @style, (, 'width', '-moz-*') ) removes all properties except for the width property and all properties starting with -moz- from the property list string in the style attribute of the context element.

Parameters:

src - the source string, consisting of property definitions

filter - a sequence of filter strings

Returns:

the filtered CSS property string

toHexString

public static java.lang.String toHexString(long value)

This method converts the passed long value to its corresponding representation as a string of hexadecimal digits.

Parameters:

value - the value to encode

Returns:

the value encoded as hex digits

toHexString

public static java.lang.String toHexString(long value,
                                           int length)

This method converts the passed long value to its corresponding representation as a string of hexadecimal digits. The second parameter specifies the exact length of the returned value, padded by leading zeros if necessary.

Parameters:

value - the value to encode

length - the expected length in characters of the resulting string

Returns:

the value encoded as hex digits, with the specified length

parseInteger

public static int parseInteger(java.lang.String numberstring,
                               int radix)

This method parses a string into an integer using the specified numbering base. Returns Integer.

Parameters:

numberstring - the integer number to convert as string. Leading zeroes are allowed.

radix - the numbering system base to use. This is 10 for decimal system, 16 for hex numbers, 8 for octal numbers, and 2 for binary numbers (consisting of 0 and 1 digits).

Returns:

the integer number the string has been translated to.

Throws:

java.lang.NumberFormatException - when the string does not represent a parseable number in the specified numbering system

parsePersonname

public static org.w3c.dom.DocumentFragment parsePersonname(java.lang.String s)

SAXON EXTENSION function: parse a string into a personname document fragment. This tries to parse out firstname, surname, honorific, lineage out of the string we get. TODO Needs revision for better algorithm, e.g.: what if field contains two persons' names?!

getVersion

public static java.lang.String getVersion()

retrieves version information

writeStringToFile

public static boolean writeStringToFile(java.lang.String url,
                                        java.lang.String data,
                                        boolean append)

Writes the passed String to the specified file, optionally appending the data (instead of replacing any existing data). The encoding is UTF-8.

Parameters:

url - the file to write to

data - the data to write

append - when true, data is appended to existing file

writeStringToFile

public static boolean writeStringToFile(java.lang.String url,
                                        java.lang.String data,
                                        boolean append,
                                        java.lang.String encoding)

Writes the passed String to the specified file, optionally appending the data (instead of replacing any existing data). The encoding can also be specified.

Parameters:

url - the file to write to

data - the data to write

append - when true, data is appended to existing file

encoding - the Java encoding name to use for writing; UTF-8 when the empty string

writeLineToFile

public static boolean writeLineToFile(java.lang.String url,
                                      java.lang.String line,
                                      boolean append)

Writes the passed String followed by the platform-specific new line character to the specified file, optionally appending the data (instead of replacing any existing data). The encoding is UTF-8.

Parameters:

url - the file to write to

line - the line of text to write

append - when true, data is appended to existing file

writeLineToFile

public static boolean writeLineToFile(java.lang.String url,
                                      java.lang.String line,
                                      boolean append,
                                      java.lang.String encoding)

Writes the passed String followed by the platform-specific new line character to the specified file, optionally appending the data (instead of replacing any existing data). The encoding can also be specified.

Parameters:

url - the file to write to

line - the line of text to write

append - when true, data is appended to existing file

encoding - the Java encoding name to use for writing; UTF-8 when the empty string

url2xml

public static java.lang.String url2xml(java.lang.String url)

This method parses a passed URL into its constituents and returns a string of XML source code that encapsulates the various parts into appropriate elements. You can use e.g. saxon:parse() to make an XML document from the returned string and extract parts of the tree using standard XSLT code.

Example:

http://login:passwd@infinity-loop.de:1234/dir1/dir2/file.html?par1&par2=v2&par3=v3#fragment-id

will be translated into a string like

<url source="http://login:passwd@infinity-loop.de:1234/dir1/dir2/file.html?par1&amp;par2=v2&amp;par3=v3#fragment-id">
  <protocol>http</protocol>
  <default-port>80</default-port>
  <authority>
    <literal>login:passwd@infinity-loop.de:1234</literal>
    <user-info>
      <literal>login:passwd</literal>
      <login>login</login>
      <password>passwd</password>
    </user-info>
    <host>infinity-loop.de</host>
    <port>1234</port>
  </authority>
  <path>
    <literal>/dir1/dir2/file.html</literal>
    <elem index="1">dir1</elem>
    <elem index="2">dir2</elem>
    <elem index="3">file.html</elem>
  </path>
  <query>
    <literal>par1&amp;par2=v2&amp;par3=v3</literal>
    <param index="1" name="par1" value="" />
    <param index="2" name="par2" value="v2" />
    <param index="3" name="par3" value="v3" />
  </query>
  <fragment>fragment-id</fragment>
</url>

Parameters:

url - the URL to parse

Returns:

a string of XML source code describing the URL parts

calcCALSTablegrid

public static java.lang.String calcCALSTablegrid(java.lang.String xml)

calcTableColgroup

public static java.lang.String calcTableColgroup(java.lang.String tableXMLCode)

Returns a serialized colspec element mirroring the column widths of the passed table code.

Parameters:

tableXMLCode - the XML code for the table to calculate the column widths for. We recognize table, tr, th and td.

Returns:

the XML code for the colgroup specification for that table

getRealmValue

public static java.lang.String getRealmValue(java.lang.String pipelineInstanceId,
                                             java.lang.String realm,
                                             java.lang.String name,
                                             java.lang.String dflt)

This method retrieves the value of a variable in a specified realm. You must supply the pipeline's instance id to this function, which you should pass as a parameter to your stylesheet. The pipeline's instance id can be retrieved using ${pipeline:PipelineInstanceId}.

Parameters:

pipelineInstanceId - the pipeline's instance id

realm - the variable realm to retrieve a value from, e.g. application, pipeline or javaproperty

name - the name of the variable

dflt - the default value to be returned when either the pipeline object can not be retrieved or the specified variable does not exist

Returns:

the variable's value cast to a String

setRealmValue

public static void setRealmValue(java.lang.String pipelineInstanceId,
                                 java.lang.String realm,
                                 java.lang.String name,
                                 java.lang.String value)

This method sets a value in the specified realm. You must supply the pipeline's instance id to this function, which you should pass as a parameter to your stylesheet. The pipeline's instance id can be retrieved using ${pipeline:PipelineInstanceId}.

Parameters:

pipelineInstanceId - the pipeline's instance id

realm - the variable realm to set the value in. Currently, this can only be the single realm value pipeline

name - the name of the variable

value - the value to be set

Throws:

java.lang.Exception - when the value could not be set

getUnicodeFromFontchar

public static int getUnicodeFromFontchar(java.lang.String pipelineInstanceId,
                                         java.lang.String fontFamily,
                                         int index)

This method tries to retrieve the Unicode codepoint equivalent of character index in font fontFamily. You must supply the pipeline's instance id to this function, which you should pass as a parameter to your stylesheet. The pipeline's instance id can be retrieved using ${pipeline:PipelineInstanceId}. The method consults the pipeline's font configuration setting and uses the resolution fallbacks described in the upCast manual. When there is no Unicode codepoint equivalent for the font+character index passed in, the codepoint for the Unicode replacement character U+FFFD (65533) is returned.

Parameters:

pipelineInstanceId - the pipeline's instance id

fontFamily - the font family name the character index is in

index - the character index in the specified font in the range from 0..255 for single-byte characters. Values greater than 255 are interpreted as meaning a double-byte character sequence where bits 15..8 are the first byte and bits 7..0 are the second byte of the DBCS.

Since:

7.1.2

getUnicodeFromFontchar

public static int getUnicodeFromFontchar(java.lang.String pipelineUID,
                                         java.lang.String fontFamily,
                                         java.lang.String string)

main

public static void main(java.lang.String[] args)

Extension function test method

Parameters:

args -