IBM VisualAge Smalltalk Goodie:  XalanWrapper
================================================

OVERVIEW

What is Xalan?
Xalan is an XSLT processor for transforming XML documents into HTML, text, or other XML document 
types.  

Xalan-C++ version 1.4 includes a C API; therefore, it is possible to invoke the Xalan-C++ support
from VisualAge Smalltalk applications.  

A free download of the Xalan-C++ support can be obtained from 
http://xml.apache.org/xalan-c/index.html.  You must install the Xalan C++ support prior to
using the Xalan wrapper goodie.  Follow the Xalan C++ support installation instructions, for additional
requirements (such as: Setting up the system path).


Xalan wrapper goodie
The Xalan wrapper goodie provides a simple interface to the Xalan-C++ library functions.  Currently, the 
Xalan wrapper goodie has been tested on Windows only.  However, the code should work properly on 
all platforms where both VisualAge Smalltalk and Xalan are supported.



Installation Instructions

1. Unzip the distribution package file, "Goodie-XalanWrapper.zip" into your
   VisualAge Smalltalk Client root directory (for example, c:\vast600 or /opt/IBMvast/6.0).  
   Note that Your unzip program must honor (not flatten) the directory structure when it unzips the
   package. 
2. Import the 'Goodies - XalanWrapper' configuration map from 
    <vast-root>\goodies\XalanWrapper\manager\xalanwrapper.dat (Windows or OS/2) or 
    <vast-root>/goodies/XalanWrapper/manager/xalanwrapper.dat (Unix). 
3. Load the 'Goodies - XalanWrapper' configuration map.


When the application 'AbxXalanWrapperApp' is loaded the Xalan library name is set to 'XalanTransformer_1_4_0'.
This name is correct for the Windows platform.  For other platforms, the library name can be changed using
code like that shown below:
	AbxXalanWrapper libraryName: <myLibrary>.


Package Contents
This package consists of a single zip containing:

XalanWrapper
	license
		license.txt
	manager
		xalanwrapper.dat
	readme
		readme.txt
	setup
		xalanwrapper.wks


Supported API

Below is a list of the API functions that can be invoked using the provided AbxXalanWrapper class.

compileStyleSheet: anXslStringOrByteArray
Compile the style sheet represented by @anXslStringOrByteArray.  Answer the handle of the compiled style sheet.
The caller is responsible for destroying the compiled style sheet handle #destroyStyleSheet:  

compileStyleSheetFile: 
Compile the style sheet in file named @aFileName.  Answer the handle of the compiled style sheet.
The caller is responsible for destroying the compiled style sheet handle #destroyStyleSheet:  

destroyCompiledStyleSheet: aCSSHandle
Release a compiles style sheet handle

destroyParsedSource: aPSHandle
Release a parsed source handle

parseSource: anXmlStringOrByteArray
Parse the XML stored in @anXmlStringOrByteArray.  Answer the handle of the parsed source.
The caller is responsible for destroying the compiled style sheet handle #destroyParsedSource:  

parseSourceFile:  aFileName
Parse the XML in file @aFileName.  Answer the handle of the parsed source.
The caller is responsible for destroying the compiled style sheet handle #destroyParsedSource: 

release
Release the encapsulated XalanTransformer handle.  This operation can be invoked by user code, but it is invoked
automatically when the object is garbage collected.

transformBuffer: anXmlStringOrByteArray xslBuffer: anXslStringOrByteArray
Converts the contents of the argument @anXmlStringOrByteArray using the XSLT rules defined in the buffer
@anXslStringOrByteArray.  Answers the converted String.

transformBuffer: aStringOrByteArray xslFileName: anXslFileName
Converts the contents of the argument  @anXmlStringOrByteArray using the XSLT rules defined in the file
named @anXslFileName.  Answers the converted String.

transformFileNamed:anXmlFileName xslFileName: anXslFileName
Converts the contents of the file named @anXmlFileName using the XSLT rules defined in the file
named @anXslFileName.  Answers the converted String.

transformFileNamed:anXmlFileName xslFileName: anXslFileName outputFileName: anOutputFileName
Converts the contents of the file named @anXmlFileName using the XSLT rules defined in the file
named @anXslFileName.  Converted result is written to the file named @anOutputFileName.
Answers 'true' for success or an AbtError on failure.

transformParsedSourceHandle: aParsedSourceHandle cssHandle: aCSSHandle
Perform a transformation using the supplied resource handles.  Answer the String result of the
transformation, or an AbtError if a failure occurs.

transformParsedSourceHandle: aParsedSourceHandle cssHandle: aCSSHandle outputFileName: aFileName
Perform a transformation using the supplied resource handles.  Write the output to @aFileName.
Answer 'true' for successful transformation, or an AbtError.
	
Usage
See the file '..\goodies\setup\xalanwrapper.wks' for code examples that utilize the Xalan wrapper.


Version History 
	Version 1.0.0 -- First public release of Xalan wrapper goodie


Reporting Errors and Suggesting Enhancements

Your thoughts, comments, suggestions, and criticisms are much appreciated. Please use the VisualAge Smalltalk newsgroup (news://news.software.ibm.com/ibm.software.vasmalltalk) to provide this feedback.


Disclaimer

THIS DOCUMENT IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND.  IBM DISCLAIMS ALL WARRANTIES, WHETHER EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF FITNESS FOR A PARTICULAR PURPOSE AND MERCHANTABILITY WITH RESPECT TO THE INFORMATION IN THIS DOCUMENT.  BY FURNISHING THIS DOCUMENT, IBM GRANTS NO LICENSES TO ANY PATENTS OR COPYRIGHTS. 

(C) Copyright IBM Corporation 2002. All rights reserved. 
