<?xml version="1.0"?> 

<!--
	description:
	
		"Creating a Transformer"

	library: "Gobo Eiffel XSLT Library"
	copyright: "Copyright (c) 2004, Colin Adams and others"
	license: "Eiffel Forum License v2 (see forum.txt)"
	date: "$Date: 2005/07/07 18:37:45 $"
	revision: "$Revision: 1.5 $"
-->

<chapter xmlns="http://www.gobosoft.com/eiffel/gobo/documentation" id="xslt_transformer">
  <chapterinfo>
    <copyright>
      <year>2004</year>
      <holder>Colin Adams and others</holder>
    </copyright>
    <author>
      <firstname>Colin</firstname>
      <surname>Adams</surname>
    </author>
    <email>colin@colina.demon.co.uk</email>
    <date>Sunday, October 31st, 2004</date>
  </chapterinfo>
  <title>Creating a Transformer</title>
  <para>
    Once the XSLT processor is configured, you then need to create an executable version
    of your XSLT stylesheet or transform, and an <classname>XM_XSLT_TRANSFORMER</classname> to use it.
  </para>
  <para>
    The first step is to create an an <classname>XM_XSLT_TRANSFORMER_FACTORY</classname>. You simply call <featurename>make</featurename>,
    passing it the configuration you created in the previous step. By default, this caches compiled stylesheets for you. You can change this behaviour
    at any time by calling <featurename>set_caching (on_or_off: BOOLEAN)</featurename>.
  </para>
  <para>
    Then you call <featurename>create_new_transformer</featurename>. This takes a <classname>XM_XSLT_SOURCE</classname> as a parameter,
    so you first have to create one to represent your stylesheet. If you are starting with a <exmlsyntax>URI</exmlsyntax>, then you do this by creating a
    <link linkend="transformation_source"><classname>XM_XSLT_URI_SOURCE</classname></link>, 
    passing it the <exmlsyntax>URI</exmlsyntax> of your text file, as an absolute URI.
  </para>
  <para>
    If instead, you wish to transform a source document according to any xml-stylesheet processing instructions contained within it, then
    you should first call <featurename>associated_stylesheet</featurename> to create the <classname>XM_XSLT_SOURCE</classname>. This takes
    the <exmlsyntax>URI</exmlsyntax> of the source document as the first argument, the medium for the transformed document as the second
    argument, and an <classname>XM_XSLT_PI_CHOOSER</classname> as the third argument. This last argument is to allow choosing between
    alternate stylesheets. See <ulink url="http://www.w3.org/TR/xml-stylesheet/">Associating Style Sheets with XML documents</ulink> for an
    understanding of what is involved.
  </para>
  <para>
    The transformer factory either sets <featurename>was_error</featurename>, or else the new transformer is made available in
    <featurename>created_transformer</featurename>.
  </para>
  <para>
    The compiled stylesheets are re-usable (which is why they are cached). To re-use one, simply call  <featurename>create_new_transformer</featurename>
    again with an <classname>XM_XSLT_SOURCE</classname> that has the same <exmlsyntax>URI</exmlsyntax>.
  </para>
  <para>
    However, you should <emphasis>not</emphasis> attempt to run two transformations at once (not even if they involve different stylesheets).
  </para>
  <para>
    If you reuse a transformer, then before calling <featurecall><featurename>transform</featurename></featurecall> a second time,
    you may wish to call <featurecall><featurename>clear_document_pool</featurename></featurecall>. This clears all document nodes
    from memory, and destroys the mapping of URIs to document nodes. The reasons you might want to do this are:
  <itemizedlist>
    <listitem>
      <para>
	To save memory (and hence garbage collection cycles) by throwing away documents which will not be used again.
      </para>
    </listitem>
    <listitem>
      <para>
	If you reuse the same URIs to refer to different documents from one transformation to another. This is a doubtful practice,
	but if you insist on doing it then you <emphasis>must</emphasis> call <featurecall><featurename>clear_document_pool</featurename></featurecall>
	otherwise you will get incorrect results.
      </para>
    </listitem>
  </itemizedlist>
  </para>
  <para>
    In general, it is better to <emphasis>not </emphasis> call <featurecall><featurename>clear_document_pool</featurename></featurecall>, as you
    will then get better performance if you reuse a document (for example, by using the <xslt>document()</xslt> function), as the transformer will not have
    to parse the document afresh.
  </para>
</chapter>
