Configuring and Using the PeruserTransformer

PeruserTransformer is a pivotal component when using Peruser in a Cocoon environment.  It is a java class which implements the Coccon Transformer interface, and which can be made to do almost anything by using appropriate configuration patterns (and, where necessary, by creating extension code).

Defining Transformer Types

Each "type" of PeruserTransformer (hereafter, we may refer to it as a "PT-type") is defined in a sitemap and given a name.   This PT-type is then available for use in pipelines throughout the defining sitemap, and any mounted submaps.  In addition to a name, the PT-type is given certain configuration information at its point of definition, which looks like this:

<map:transformer name="example_transformer_type" logger="net.peruser" 
			src="net.peruser.binding.cocoon.PeruserTransformer">

	<pm:machine xmlns:ettm="http://www.peruser.net/2007/example#">
		<pm:cuteName>simple_machine</pm:cuteName>
		<pm:class>net.peruser.module.system.UtilityProcessorMachine</pm:class>
		<ettm:yowza color="mauve">parameter data which the machine code is free to use or to ignore
			<ettm:whoopee>...and which may include subtags, attribs, text, etc</ettm:whoopee>
		</ettm:yowza>
	</pm:machine>

</map:transformer>

As you can see, this PT-type is named "example_transformer_type", and is bound to the log4j logger "net.peruser".  The "src" attribute gives the full classname of the PT, which will usually be the same classname you see above, although you can also create your own extension classes if needed.  (Note: It is more common to create a custom Machine or Command class than a custom transformer class).

Next, we see a configuration of a machine which is bound to this PT-type.    This machine defines its own argument namespace with the URI
http://www.peruser.net/2007/example# and namesapace abbreviation "ettm".

The machine is itself configured with three parameters, two of which are required for all machines:  cuteName and class.      These parameters both come from the pm (peruser machine) namespace.    The class value gives the name of a java class which implements the peruser ProcessorMachine interface, and which contains code that will be executed whenever this PT-type is called upon to perform a transformation.

The third parameter comes from the machine's own namespace. is named "yowza", and is included to demonstrate how machine-specific configuration may be passed into a machine.  The machine java code can do whatever it wants with this information, which it accesses through the Peruser Config interface.

Using Transformer Types in Pipelines

Any transformer type may be be used  as part of any cocoon sitemap pipeline.   The type attribute of the transform directive indicates which type of transformer you are using.  A typical pipeline using the example PT-type from above looks like this:

<map:match pattern="exampleRelativeURL.xhtml">
	<map:generate type="request"/>
	<map:transform src="xslt/cook_params.xslt"/>
	<map:transform type="example_transformer_type" src="peruser:INSTRUCTION_NAME_GOES_HERE}">

		<!-- There are a lot of different ways to specify the value of a parameter -->
		
		<map:parameter name="somethin" value="HARCODED_ARGUMENT_VALE"/>

		<map:parameter name="whatUserSaid" 
				value="{request-param:nameOfSomeHttpRequestParameter}"/>

		<map:parameter name="valueFromPeruserInputModule" 
				value="{pim:argPassedToPeruserInputModule}"/>

		<map:parameter name="superFancyCombinedValue" 
				value="{request-param:userVal}-X-{pim:pq1}-Y-{pim:pq2}"/>

	</map:transform>
	<map:transform src="xslt/transform_query_output_into_user_readable_XHTML.xslt"/>
	<map:serialize type="xhtml"/>		
</map:match>

You will notice that the name "example_transformer_type" is now used as the value of the "type" attribute.  The transform tag also includes a src attribute, which must contain a URI, and a set of "parameter" tags, each of which has a name (string) and a value (string).   The src attribute given here is treated as the URI of an instruction to be executed by the machine bound to the transformer.  This src attribute should not be confused with the one specified on the PT-type in the previous section, which was for  the transformer java class.      The exact meaning of the src instruction and parameter values supplied to the PT depends upon details of how the bound machine works.  These interpretations are specified in the documentation of each machine class.   Also notice that the src and parameter values make use of sitemap substitution (the expressions denoted by curly braces '{' and '}')  in order to specify dynamic configuration information to the PT.

The Point of it all:  Transformation Semantics

At this point, it's clear that PeruserTransformer is a configurable component that you can bind into your cocoon pipelines with a lot of flexibility.  In this way, it forms the most visible part of the bridge from the world of Cocoon (which is primarily XML pipeline oriented) to the world of Peruser (which is primarily RDF model oriented).

It's also clear that the PeruserTransformer essentially delegates all the important decisions about how to perform a particular transformation to a Machine.  So, while we may speak of the PeruserTransformer implementing features X, Y, and Z, it is really the machines that are responsible for doing the work that implements these features.

Our next step is to introduce some of the Machines that you can use to perform queries, inference, database updates, and so on.  

Please use the links at left to navigate through the sections on Simple Behavior and Complex Behavior.