Chapter 23 Provides an overview of performing XSLT transformations

XSLT(Extensible StyleSheet Language Transformations) is an XML-based Language used to describe how to transform a given XML document into another XML or other “human-readable” document. You can use the classes in the % xml. XSLT and % xml. XSLT2 packages to perform XSLT 1.0 and 2.0 transformations.

Note: The XML declaration of any XML document used should indicate the character encoding of the document, and the document should be encoded as declared. If character encodings are not declared, IRIS will use the default values described in “Input and Output Character encodings” earlier in this book. If these defaults are incorrect, modify the XML declaration so that it specifies the actual character set to use.

Perform an OVERVIEW of XSLT transformations in IRIS

IRIS provides two XSLT processors, each with its own API:

  • XalanProcessor supportXSLT 1.0.XML.XSLTPackages provide apis for the handler.
  • SaxonProcessor supportXSLT 2.0.%XML.XSLT2The package provides the API for the processor.

The XML.xslT2 API sends requests to Saxon through a connection to the XSLT 2.0 gateway. Gateways allow multiple connections. This means, for example, that two separate IRIS processes can be connected to the gateway, each with its own set of compiled stylesheets while sending transformation requests.

With the Saxon processor, the compiled stylesheet and ISC: Evaluate cache are connection-specific; You must manage your own connections to take advantage of these two features. If you open the connection and create a compiled stylesheet or Evaluate a transformation that populates the ISC: Evaluate cache, all other transformations evaluated on that connection will access the compiled stylesheet and ISC: Evaluate cache entries. If a new connection is opened, other connections (and their compiled stylesheets and caches) are ignored.

The apis of the two processors are similar, except that the method in % xml.xslt2 takes another parameter to specify the gateway connection to use.

To perform the XSLT transformation, do the following:

  1. Student: If you use thetaSaxonProcessor, as described in the next sectionXSLTGateway server. Or use the default configuration.

If you are using an Xalan processor, you do not need a gateway.

The system automatically starts the gateway when required. Or you can start it manually.

  1. Student: If you use thetaSaxonProcessor, you can choose to create%Net.Remote.GatewayRepresents an instance of theXSLTA single connection to a gateway.

Note that this step is required to leverage the compiled stylesheet and isC: Evaluate cache when using the Saxon processor.

  1. You have the option to create a compiled stylesheet and load it into memory. See “Creating compiled Stylesheets” later in this chapter. Student: If you use thetaSaxonProcessor, be sure to specify gateway parameters when creating the compiled stylesheet.

This step is useful if you plan to reuse the same style sheet. However, this step also consumes memory. When compiled stylesheets are no longer needed, be sure to remove them.

  1. Invoke one of the transformation methods of the applicable API. If you are using the Saxon processor, you can optionally specify gateway parameters when calling the Transform method.

  2. You can choose to call other transformation methods. If you are using the Saxon processor, you can select to specify gateway parameters when calling the Transform method. This enables another transformation to be computed using the same connection. This transformation will access all compiled stylesheets and ISC: Evaluate cache entries associated with this connection. If a new connection is opened, other connections (and their compiled stylesheets and caches) are ignored.

Studio also provides a wizard that you can use to test XSLT transformations; This is described later in this chapter.

Configure, start, and stop the XSLT 2.0 gateway

When using the Saxon processor to perform XSLT 2.0 transformations, IRIS uses the XSLT 2.0 gateway (which uses Java). To configure this gateway, do the following:

  1. In the administrative Portal, choose System Administration > Configuration > Connectivity > XSLT 2.0 Gateway Server.

  2. Choose to Go.

The XSLT Gateway server page displays.

Configuration details are displayed in the left pane, and recent activities are displayed in the right pane.

  1. In the left pane, you can optionally specify the following Settings:
  • Port Number –XSLT 2.0TCP port number exclusively used by the gateway. This port number must not conflict with any other local TCP port on the server.

The default value is IRIS SuperServer port number plus 3000. If the number is greater than 65535, the system uses 54773.

  • Java Version – Java Version to use.
  • Log File – Specifies the path name of the Log File. If this setting is ignored, logging is not performed. If the file name is specified but the directory is omitted, the log file is written to the system manager directory.
  • Java Home Directory – The Directory path containing the Java bin Directory. Specify this option if there is no default Java on the server, or if you want to use a different Java.

To see the default Java, execute the following command in the Shell on the server:

java -version
Copy the code
  • JVM Arguments – Any other Arguments to use by the Java virtual machine.

This area also displays the current value of the JAVA_HOME environment variable.

Note that you cannot edit any of these values at gateway runtime.

  1. If you have made changes, select Save to save the changes. Or select reset to.
  2. (Optional) Select tests to test changes.

On this page, you can also do the following:

  • Start the gateway. To do this, select Start in the area on the right.

Note that IRIS automatically starts the gateway when needed. You do not need to manually start the gateway.

  • Disable the gateway. To do this, select Stop in the area on the right.

Reusing XSLT Gateway server connections (XSLT 2.0)

If you are using a Saxon processor, InterSystems IRIS will use the XSLT 2.0 gateway you configured previously. To communicate with this Gateway, InterSystems IRIS creates an XSLT Gateway connection internally (an instance of % net.remote. Gateway). By default, the system creates a connection, uses it for transformation, and then discards the connection. There is an overhead associated with opening new connections, so maintaining a single connection for multiple transformations provides the best performance. In addition, you must maintain your own connections to take advantage of the compiled stylesheets and isC: Evaluate cache.

To reuse XSLT gateway connections, do the following:

  1. call%XML.XSLT2.TransformertheStartGateway()Methods:
 set status=##class(%XML.XSLT2.Transformer).StartGateway(.gateway)
Copy the code

This method starts the XSLT 2.0 Gateway (if it is not already running) and returns an instance of % net.remote. Gateway as output. Note that this method also returns status.

The % net.remote.Gateway instance represents a connection to a Gateway.

StartGateway() has an optional second argument, useSharedMemory. If this parameter is true (the default), connections to localhost or 127.0.0.1 will use shared memory (if possible). To force connections to use ONLY TCP/IP, set this parameter to False.

  1. Check the status returned from the previous step:
    if $$$ISERR(status) {
     quit
    }
Copy the code
  1. Create any compiled stylesheets. When performing this operation, specify the gateway parameter as%Net.Remote.GatewayInstanceIs created in Step 1.
  2. Call as needed%XML.XSLT2.TransformertheTransformMethods (TransformFile(),TransformFileWithCompiledXSL(),TransformStream()andTransformStreamWithCompiledXSL()). When performing this operation, specify the gateway parameters as those created in Step 1%Net.Remote.GatewayThe instance.
  3. If the given compiled stylesheet is no longer required, call%XML.XSLT2.CompiledStyleSheettheReleaseFromServer()Methods:
 Set status=##class(%XML.XSLT2.CompiledStyleSheet).ReleaseFromServer(compiledStyleSheet.gateway) 
Copy the code

Important: Be sure to use this method when compiled stylesheets are no longer needed.

  1. Called when the XSLT gateway connection is no longer needed%XML.XSLT2.TransformertheStopGateway()Method and pass the gateway connection as a parameter:
 set status=##class(%XML.XSLT2.Transformer).StopGateway(gateway)
Copy the code

This method discards the connection and resets the current device. It does not stop the XSLT 2.0 gateway.

Important: Be sure to use this method when you no longer need to connect.

For an example, see the Example10() method in XSLT2. Examples in the Samples namespace.

Troubleshoot the XSLT 2.0 gateway server connection failure

When the XSLT 2.0 gateway is turned on, the connection between InterSystems IRIS and the gateway server may become invalid. For example, if a network error occurs or the gateway server is restarted after InterSystems IRIS connects to the gateway server, the connection may not close properly. Therefore, errors may be encountered.

You can try to reconnect InterSystems IRIS to the gateway server by calling the %LostConnectionCleanup() method and the % Reconnect method of the XSLT gateway connection object in succession.

If you want to automatically reconnect to the gateway server when you disconnect, set the AttemptReconnect property of the gateway connection object to True.

Create compiled stylesheets

If you plan to use the same style sheet repeatedly, you may need to compile the style sheet to speed things up. Note that this step consumes memory. When compiled stylesheets are no longer needed, be sure to remove them.

To create a compiled stylesheet, do the following:

  • Student: If you use thetaXalanProcessor (forXSLT 1.0), please use%XML.XSLT.CompiledStyleSheetOne of the following class methods:
    • CreateFromFile()
    • CreateFromStream()
  • Student: If you use thetaSaxonProcessor (forXSLT 2.0), please use it again%XML.XSLT2.CompiledStyleSheetOne of the following class methods:
    • CreateFromFile()
    • CreateFromStream()

Also note that you will need to create an XSLT gateway connection; See “Reusing XSLT Gateway server connections (XSLT 2.0).”

For all of these methods, the complete argument list is as follows:

  1. Source – Style sheet.

For CreateFromFile(), this argument is the file name. For CreateFromStream(), this argument is a stream.

  1. CompiledStyleSheet – a compiledStyleSheet returned as an output parameter.

This is the style sheet class (% % piledStyleSheet XML.XSLT.Com or XL.XSLT2.Com piledStyleSheet, as the case may be).

  1. ErrorHandler – Optional custom error handlers to use when compiling stylesheets.

For the methods in both classes, this is the instance of % xml.XSLT.ErrorHandler.

  1. (Applicable only%XML.XSLT2.CompiledStyleSheet) the gateway –%Net.Remote.GatewayAn instance of the
/ / sets the tXSL to OREF Set equal to the appropriate flow of tSC = # # class (% piledStyleSheet XML.XSLT.Com. CreateFromStream (tXSL,. TCompiledStyleSheet) the If $$$ISERR(tSC) QuitCopy the code