xsltcbrazil/src/main/java/samples/CompiledBrazil/README.brazil

============================================================

CONTENTS OF THIS DOCUMENT:

  o) HOW TO PROVIDE XSL TRANSFORMATIONS AS A WEB SERVICE
  o) HOW TO INVOKE TRANSLETS FROM A BRAZIL HANDLER

------------------------------------------------------------

HOW TO PROVIDE XSL TRANSFORMATIONS AS A WEB SERVICE

This sample code illustrates how Xalan/XSLTC can be used to
offer XSL transformations as a web service without using a
full web server. We have chosen to use the Brazil prototype
for the web interface, originally available from Sunlabs:

  http://www.sun.com/research/brazil/

Both the website and the original downloads no longer exist.
An archived copy of the website (without downloads) is
available at:

  https://web.archive.org/web/20090402221714/http://research.sun.com/brazil/

The original code, slightly improved to be compilable on
JDK 17 ('yield' keyword), is available at:

  https://github.com/dev-aspectj/brazil

Maven Central coordinates:

  dev.aspectj:sunlabs.brazil:2.3.1

We could easily have used some other web interface such
as Tomcat. The supplied Java code implements a Brazil
"handler", which very much resembles a servlet.

The CompiledEJB and CompiledServlet sample code
demonstrate other approaches to providing XSL transformations
as a web service.

------------------------------------------------------------

HOW TO INVOKE TRANSLETS FROM A BRAZIL HANDLER

The CompiledBrazil directory contains the example source code:

  TransformHandler.java

This file contains a minimal implementation of an XSL
transformation handler, to be used with Brazil.

Compile any stylesheets you're interested in into translets.
Set your CLASSPATH to include xalan.jar, xercesImpl.jar,
xml-apis.jar, your translet classes and the Brazil server
jar file.

You can now set up the Brazil server to service requests by
using the following command:

java -cp <classpath> \
  -Djavax.xml.transform.TransformerFactory=org.apache.xalan.xsltc.trax.TransformerFactoryImpl \
  sunlabs.brazil.server.Main -port 8080 \
  -handler samples.CompiledBrazil.TransformHandler

In a browser, you can enter a URI similar to the following:

  http://localhost:8080/?translet=myTrans&document=myDoc

where "myTrans" is the URI of a stylesheet that you've
compiled into a translet and "myDoc" is URI of an XML document
you'd like to process using that stylesheet. The result of
the transformation will be displayed in your browser.

You can test this in the Xalan-Java source code repository
like this (Git Bash on Windows, please adjust shell syntax
Brazil classpath to your needs):

Console A:

mvn clean compile
mvn -pl xalan exec:java \
  -Dexec.mainClass=org.apache.xalan.xsltc.cmdline.Compile \
  -Dexec.arguments=samples/src/main/java/samples/SimpleTransform/birds.xsl
java \
  -cp "C:/Users/USER_ID/.m2/repository/dev/aspectj/sunlabs.brazil/2.3.1/sunlabs.brazil-2.3.1.jar;.;xalan/target/classes;serializer/target/classes;samples/target/classes" \
  -Djavax.xml.transform.TransformerFactory=org.apache.xalan.xsltc.trax.TransformerFactoryImpl \
  sunlabs.brazil.server.Main -port 8080 \
  -handler samples.CompiledBrazil.TransformHandler

Console B (with server running on console A):

curl "http://localhost:8080/?translet=birds&document=samples/src/main/java/samples/SimpleTransform/birds.xml"

Console output should be similar to:

<?xml version="1.0" encoding="UTF-8"?><BirdInfo>
Order is:  TINAMIFORMES
        Family is:  TINAMIDAE
            Great Tinamou. Tinamus major
            Highland Tinamou. Nothocercus
(...)
        Family is:  FREGATIDAE
            Magnificent Frigatebird. Fregata magnificens
            Great Frigatebird. Fregata minor
            Lesser Frigatebird. (A) Fregata ariel

</BirdInfo>