Building a Tamino Server Extension Package

This document explains how you can build server extension packages based on Direct and Java-based infrastructures using the Tamino X-Tension Builder. Server extensions can be written in C++, Java or any language that supports dynamic loading of object libraries.


Programming Languages and Development Tools

The following combinations of programming languages and infrastructures are supported by Tamino Tools and/or described in this documentation:

Infrastructures / Programming Languages Direct Java
Direct/C++

X-Tension Builder

-
Java - X-Tension Builder

Building a Direct Infrastructure-Based Tamino Server Extension Package

Server extensions written in C++ or any programming language that supports the dynamic loading of object libraries can be executed using the Direct infrastructure of Tamino X-Tension. The X-Tension Builder supports the development of server extension packages based on this infrastructure.

Building a Java-Based Tamino Server Extension Package

The Tamino X-Tension Builder supports the development of Java-based server extension packages on Microsoft Windows and UNIX platforms. The infrastructure is established by means of a JVM attached to the Tamino Server process. The usage of Java is restricted to avoid harmful influences on the Tamino Server.

Using the X-Tension Builder

This section tells you how to build a server extension package. The X-Tension Builder supports developing server extensions using the Direct and Java-based infrastructures. For information about what Tamino server extensions are and how they can be developed, see the Introduction and the sections Tamino Server Extension Functions and Developing Tamino Server Extensions. The individual steps related to building a server extension package - which is what you need when you want to install a server extension into a database - are described in the following sections:

Creating a Server Extension Project

The Tamino X-Tension Builder is used to create a server extension project. The tool automatically generates files containing all of the code required by the infrastructure-specific parts of the program and for communication with the Tamino Server. You are responsible for implementing the functionality. This section explains how to use the tool to set up a new project.

Start of instruction setTo create a server extension project

  1. Create the directory or folder where the source files for your project are to be stored. Use different directories for different projects!

  2. Microsoft Windows:

    • Start the Tamino X-Tension Builder from the Tamino program group under the Windows Start menu.

    UNIX:

    • Call the script inosxbuilder.sh from the command line.

  3. The Tamino X-Tension Builder appears and displays an empty screen.

    Choose New from the File menu to open a new project.

  4. The first of two dialog boxes appears:

    graphics/builder1.png

  5. You can create either a Direct/C++ server extension or a Java-based server extension. Select the appropriate radio button. The following description shows the results of choosing the Java-based infrastructure for the server extension; the results of choosing the Direct infrastructure are similar.

    Enter a name for the server extension. This name is used to reference the object within Tamino.

    The text box for the short description is filled in automatically. You can edit this text, and also the text in the Author box.

    Choose Next.

  6. A second dialog box appears:

    graphics/builder2.png

    Enter a package name for the Java class. To ensure unique naming, Software AG recommends that you use your domain name in the package name.

    The class name is filled in automatically. You can edit this text.

    Enter the private classpath (if needed).

    Enter the directory where the source files are to be stored, or choose Browse... to select a drive and directory.

    If you keep the check mark in the Insert Javadoc comments box, you can generate Javadoc comments for your new server extension object and any server extension function that you include in the project after compiling the class file.

    When you have made all desired changes, choose Finish to create the new project.

    Note:

    • If the specified directory had already been used for a previous project, the following message is displayed:

      graphics/jstep3.gif

      If you select OK in the message box, the Install.xml file will be overwritten. If you choose the Cancel button, you are returned to the previous dialog, where you can choose a different directory.

  7. A list of files that will be created is displayed:

    graphics/jstep4.gif

    These two skeleton files are of special interest to the server extension developer:

    your-project.java

    The source file to which the signature of a server extension function is added using the Add Function menu item from the Project menu and into which the developer's function code has to be inserted;

    Install.xml

    The installation file which is required to install the finished server extension package. The XML server uses this file to put information about the server extension object into the repository.

    Choose OK to create the files.

  8. The source file your-project.java is opened in the editing window of the Tamino X-Tension Builder:

    graphics/install.gif

    At various points in the generated framework code, you will find comments of the form:

    // TODO: ...

    Add your code after these comment lines.

    Save the file.

  9. This file can be edited as described in the section Adding a Server Extension Function to an Existing Server Extension Project.

Opening an Existing Server Extension Project

You can open a previously-generated server extension project with the Tamino X-Tension Builder at any time to edit and manipulate the source file (add the signature of a server extension function and the function code, compile and pack the server extension object) as long as the server extension has not yet been installed in one or more databases.

Start of instruction setTo open an existing server extension project

  1. Microsoft Windows:

    • Start the Tamino X-Tension Builder from the Windows Start menu.

    UNIX:

    • Call the script inosxbuilder.sh from the command line.

  2. Choose Open from the File menu of the Tamino X-Tension Builder.

  3. The Select Server Extension Project dialog box appears:

    graphics/jselect.png

    Browse to the drive and directory that contains the Install.xml file for the project.

    Select the file and choose Open.

  4. The your-project.java source file for this server extension project appears in the Tamino X-Tension Builder's editing window.

    You can view all source files for the project by selecting the filename in the tree displayed in the left-hand frame of the X-Tension Builder.

    Note:
    You should not change the Install.xml file. If you do change it, for example if you change parameter names, you must also make these changes in the your-project.java source file.

Note:
It is not possible to install different versions of a server extension at the same time. If you want to make changes to the function code of a server extension that is installed in a database without uninstalling it, create a new project specifying a different name for the server extension, add the modified function code, and compile and pack the project as usual with the Tamino X-Tension Builder.

Adding a Server Extension Function to an Existing Server Extension Project

You can add any number of map-in, map-out, map-delete, trigger, query and shadow functions, but only one init or event function to a server extension object.

We recommend including a complete set of mapping functions (one map-in, one map-out and one delete function) or trigger functions in a server extension object. Implement an init function to perform initializing actions prior to first function execution. Usually you will also need an event function to react to commit or rollback events.

Start of instruction setTo add a server extension function to an existing server extension project

  1. With the source file (your-project.java) open in the editing window, choose Add Function... from the Project menu.

  2. The Add X-Tension Function dialog box appears:

    graphics/jadd1.gif

    Enter the name of the server extension function in the Function Name text box.

    Either:

    • Select the Function Type drop-down list box for the server extension function.

      graphics/jadd1.png

      If you choose Map In Function, Map Out function or Delete Function, parameters with default names and types are generated automatically, and the Add button changes to Add Node Info, which can be used to add the nodeinfo parameter to the function.

      Choose OK to add the map-in function to your server extension.

    Or:

    • Choose Add.

      The Add parameter dialog box appears:

      graphics/admin56.png

      Enter a name for the parameter you want to define and select the XML type and attribute.

      Choose OK.

      The Add parameter dialog box appears again, allowing you to add all the parameters that are required for the type of server extension function you want to define.

      When you have specified all of your parameters, choose the Function Type (only function types with suitable parameter lists are enabled). Missing mandatory parameters are added.

      Optional parameters can be reordered. Select the parameter you want to move to another position, and the up and down arrows are enabled if reordering is allowed for that parameter.

      If you select one of the displayed parameters, the Remove and Edit buttons are enabled.

    Query function selected as Function Type

    • If you choose Query Function from the Function Type drop-down list box, the Edit return parameter dialog box appears, where you can define a return value:

      graphics/admin57.png

      Select the appropriate type (XML document or character string) of the value to be returned by your query function from the XML drop-down list box. (If you select "XML-OBJ", the XML document processor parses the result. If the result is not a well-formed XML document, the parser fails with the error message INOXPE8702 Invalid document prolog.)

      Choose OK.

      The Add Extension Function dialog box appears again with the Add button changed to Add Optional, allowing you to generate an arbitrary number of optional parameters for a query function. All of these parameters must be input parameters.

      Optional parameters can be reordered. Select the parameter you want to move to another position, and the up and down arrows are enabled if reordering is allowed for that parameter.

      If you select one of the displayed parameters, the Remove and Edit buttons are enabled.

      Choose OK to add the function's signature to the source file (your-project.java) and the Install.xml file.

  3. The following predefined code is displayed:

    graphics/jadd6.gif

    graphics/jadd7.gif

  4. At various points in the generated framework code, you will find comments of the form:

    // TODO: ...

    Add your code after these comment lines.

  5. Save the file.

Compiling the Server Extension Class File

When you have made all entries to the source file, the class file for the server extension must be compiled before the server extension can be packed. The class file is compiled using the packaging information that is specified in the second dialog box for creating a new project.

The server extension class file can only be compiled if you have installed a Java compiler (by default this is installed as part of the standard Tamino installation procedure) and set the system environment variable path to point to it.

Start of instruction setTo compile the server extension class file

  1. With the source file (your-project.java) open in the editing window:

    Either:

    • Choose Compile from the Project menu.

    Or:

    • Choose Copy Compile Command from the Project menu.

      This copies the compile command to the clipboard. You can now paste it at a command prompt (so-called "DOS box"), where it can be executed.

  2. The source file appears, showing messages about the compilation process in the Result Frame.

    • If errors occurred, correct your function code and recompile the file.

Generating Javadoc Comments for a Server Extension Class File

If the Insert Javadoc comments check box was selected in the second dialog box for creating a new project, you can generate Javadoc comments for the server extension class file and include them in the server extension package.

Start of instruction setTo generate Javadoc comments

  1. With the source file (your-project.java) open in the editing window, choose Call Javadoc from the Project menu.

  2. A list of the created files appears:

    graphics/javadoc.gif

    The HTML file that is named after your project and stored in the directory where the class file is located is of special interest to the server extension developer. The other files are stored in the project's main directory.

    Close the box.

Packaging a Server Extension

When the server extension class file has been successfully compiled and, if desired, the Javadoc comments have been generated, the server extension package can be created.

Start of instruction setTo create a server extension package

  1. With the source file (your-project.java) open in the editing window, choose Pack Server Extension from the Project menu.

  2. The first Pack Server Extension dialog box appears:

    graphics/jpack1.gif

    Choose Change Directory... if you want to create the package in a directory other than the default.

    Choose Next to continue, or Finish to complete the wizard using default values.

  3. The second Pack Server Extension dialog box appears, displaying the Java executables available for the specified server extension object:

    graphics/jpack2.gif

    Select one of the displayed executables and choose Add... to include it into the package. If you want to exclude an executable you have specified from the package to be created, select it and choose Remove. Full path and Relative destination directory are displayed automatically. You cannot edit them.

    Choose Next to continue, or Finish to complete the wizard using default values.

  4. The third Pack Server Extension dialog box appears, displaying a help file (HTM, HTML, XML and TXT) for the server extension object.

    graphics/jpack3.gif

    The relative destination directory of the selected help file is displayed.

    If you want to exclude a help file you have specified from the package to be created, choose Clear.

    The Reference text field can be used to specify a bookmark in the help file. In this case, the help file will start at the position indicated by the bookmark.

    Choose the Choose... button.

    The References available list box appears showing the bookmarks available in the current help file.

    graphics/jref1.gif

    Select a bookmark.

    Choose OK.

  5. The fourth Pack Server Extension dialog box appears:

    graphics/jpack4.gif

    A help file for the individual server extension function is displayed, together with the relative destination directory.

    Choose Browse... to select a different help file than the one suggested in the dialog box, or choose Clear to remove a help file.

    The Reference text field can be used to specify a bookmark in the help file. In this case, the help file will start at the position indicated by the bookmark.

    Choose the Choose... button.

    The References available list box appears, showing the bookmarks available in the current help file:

    graphics/jref2.gif

    Select a bookmark.

    Choose OK.

    Choose Finish to complete the wizard actions.

    Note:
    The complete help information may be contained in one file. This file can be specified repeatedly; for example, for the server extension object (as described in step 3) and for any server extension function that you select in the current page.

    If you want to include all files generated using the Call Javadoc item in the Project menu, select all the files, one after the other, for all functions or one of the functions contained in the selected executable.

  6. A list of the files to be included in the package is displayed:

    graphics/jpack5.gif

    Choose OK to create the server extension package.

The package file (your-project.sxp) can now be installed as described in the section Installing a Tamino Server Extension.

Using Direct Infrastructure

Server extensions written in C++ or any other programming language that supports dynamic loading of object libraries can be executed using Tamino X-Tension's Direct infrastructure. The X-Tension Builder supports the development of Direct/C++ server extension packages.

Start of instruction setTo create a server extension project

  1. Open a project in the X-Tension Builder. On the first page there is a button Direct. Select this button and you will be guided through the whole building procedure using the Direct infrastructure. The procedure is very similar to that described for the X-Tension Builder.