X-Tension Developing Process (Java)

Hi everybody,

I will write down some experiences I gathered while developing an X-Tension function with Java and I didn’t read in the documentation.
Certainly I am wrong on some points, so don’t hesitate to amend or to comment my article.

A) Deleting / Uninstalling your X-Tension function
If you try to redefine the Schema Editor without the extension function you get:
"parameter map-type not updatable "
If you try to uninstall the Extension with the Manager you get:
"Line 1, Column 44: INOSXE7053: Error 8831 calling data map: SXS function name = mapin"
It is seemingly impossible to get rid of an X-Tension function. The only way is to undefine your schema (and hence to lose your data.)

B) Update your X-Tension function:
I found no proper way to update an X-Tension function.

The only way to update your X-Tension function is to recompile and replace the java file.
If you haven’t changed the structure you only have to replace the class file in a subfolder of C:\Program Files\Software AG\Tamino\Server Extensions\Java by the updated class file.
If you have changed the structure you should replace the install.xml as well.

After that you have to stop and restart the database.
If you use “Extension Trace” (see E) select “Server Extension” (in the Tamino Manager) and click on the button “Extension Trace On”.
There is no way to instruct Tamino to auto start the Extension Trace.

C) X-Tension function in a package:
If your X-Tension function depends on other classes of a package, you have to provide the whole package in D:\Program Files\Software AG\Tamino\Server Extensions\Java.
(It’s self-evident that you have to adapt this path to your local environment.)
I compile the whole package with my IDE and I copy/replace it to this path each time I want to retest a modification.
Then I continue as described in B.
For another possibility see at D.

D) Including jar files in your X-Tension function
On my computer there is a registry folder like this: “HKEY_LOCAL_MACHINE\SOFTWARE\Software AG\Tamino\\SXS”.
There you have a variable called “java classpath”.
By default there are already the “[…]\Software AG\Tamino\Server Extensions\Java” folder and the jar file “[…]\Software AG\Tamino\Tamino\Bin\sxsrte.jar” is already included.
You can add here your jar files.
(Is this the only way to include jar files?)
You can also include another folder in order to find class files, so you don’t have to copy your class files as in C.
But you still have to restart your database after each update (see B).

E) Output of Extension Trace
To see the java exception details you might output it with the SxsTrace(String st).
I added this try catch to my X-Tension function(s) during development:
try {
//… everything else
} catch (Exception ex) {
ByteArrayOutputStream baos = new ByteArrayOutputStream();
PrintStream ps = new PrintStream(baos);
If you don’t do this you won’t get any idea why your function failed.
An alternative would be to write the exception’s stack trace to a file.
With SxsTrace(String st) you can output any String, if you output xml data embrace it with a CDATA section: <![CDATA[ ]]>