Creating and Using Custom SAFs

Custom SAFs are functions in shared libraries that are loaded and called by the server.

To create a custom SAF

1. Write the Source Code using the NSAPI functions. Each SAF is written for a specific directive.

2. Compile and Link the source code to create a shared library ( .so , .sl , or .dll) file.

3. Load and Initialize the SAF by editing the magnus.conf file to:

   • Load the shared library file containing your custom SAF(s)

     • Initialize the SAF if necessary

4. Instruct the Server to Call the SAFs by editing obj.conf to call your custom SAF(s) at the appropriate time.

5. Restart the Server .

6. Test the SAF by accessing your server from a browser with a URL that triggers your function.

   The following sections describe these steps in greater detail.

Write the Source Code

Write your custom SAFs using NSAPI functions. For a summary of some of the most commonly used NSAPI functions, see Overview of NSAPI C Functions available routines, see Chapter 7, NSAPI Function Reference

For examples of custom SAFs, see nsapi/examples/ in the server root directory, and also seeChapter 5, Examples of Custom SAFs and Filters

The signature for all SAFs is:

int function(pblock *pb, Session *sn, Request *rq);

For more details on the parameters, seeSAF Parameters

The Sun Java System Web Server runs as a multi-threaded single process. On UNIX platforms there are actually two processes (a parent and a child), for historical reasons. The parent process performs some initialization and forks the child process. The child process performs further initialization and handles all of the HTTP requests.

Keep the following in mind when writing your SAF:

• Write thread-safe code

• Blocking may affect performance

• Write small functions with parameters and configure them in obj.conf

• Carefully check and handle all errors (and log them so you can determine the source of problems and fix them)

  If necessary, write an initialization function that performs initialization tasks required by your new SAFs. The initialization function has the same signature as other SAFs:

  int function(pblock *pb, Session *sn, Request *rq);

  SAFs expect to be able to obtain certain types of information from their parameters. In most cases, parameter block (pblock) data structures provide the fundamental storage mechanism for these parameters A pblock maintains its data as a collection of name-value pairs. For a summary of the most commonly used functions for working with pblock structures, see Parameter Block Manipulation Routines

  When defining a SAF, you do not specifically state which directive it is written for. However, each SAF must be written for a specific directive (such as AuthTrans, Service, and so on). Each directive expects its SAFs to behave in particular ways, and your SAF must conform to the expectations of the directive for which it was written. For details of what each directive expects of its SAFs, see Required Behavior of SAFs for Each Directive.

Compile and Link

Compile and link your code with the native compiler for the target platform. For UNIX, use the gmake command. For Windows, use the nmake command. For Windows, use Microsoft Visual C++ 6.0 or newer. You must have an import list that specifies all global variables and functions to access from the server binary. Use the correct compiler and linker flags for your platform. Refer to the example Makefile in the server_root/plugins/nsapi/examples directory.

Adhere to the following guidelines for compiling and linking.

Include Directory and nsapi.h File

Add the server_root/plugins/include (UNIX) or server_root\plugins\include (Windows) directory to your makefile to include the nsapi.h file.

Libraries

Add the server_root/bin/https/lib (UNIX) or server_root\bin\https\bin (Windows) library directory to your linker command.

The following table lists the library that you need to link to.

Linker Commands and Options for Generating a Shared Object

To generate a shared library, use the commands and options listed in the following table.

Additional Linker Flags

Use the linker flags in the following table to specify which directories should be searched for shared objects during runtime to resolve symbols.

On UNIX, you can also set the library search path using the LD_LIBRARY_PATH environment variable, which must be set when you start the server.

Compiler Flags

The following table lists the flags and defines you need to use for compilation of your source code.

The following table lists the optional flags and defines you can use.

Compiling 3.x Plugins on AIX

For AIX only, plug-ins built for 3.x versions of the server must be relinked to work with 4.x and 6.x versions. The files you need, which are in the server_root/plugins/nsapi/examples/ directory, are as follows:

• The Makefile file has the -G option instead of the old -bM:SRE -berok- brtl -bnoentry options.

• A script, relink_36plugin, modifies a plug-in built for 3.x versions of the server to work with 4.x and 6.x versions. The script’s comments explain its use.

  Sun Java System Web Server 4.x and 6.x versions are built on AIX 4.2, which natively supports runtime-linking. Because of this, NSAPI plug-ins, which reference symbols in the ns-httpd main executable, must be built with the -G option, which specifies that symbols must be resolved at runtime.

  Previous versions of Sun Java System Web Server, however, were built on AIX 4.1, which did not support native runtime-linking. Sun Java System Web Server had specific additional software to enable plug-ins. No special runtime-linking directives were required to build plug-ins. Because of this, plug-ins that have been built for previous server versions on AIX will not work with Sun Java System Web Server 4.x and 6.x versions as they are.

  However, they can easily be relinked to work with Sun Java System Web Server 4.x and 6.x versions. The relink_36plugin script relinks existing plug-ins. Only the existing plug-in itself is required for the script; original source and .o files are not needed. More specific comments are in the script itself. Since all AIX versions from 4.2 onward natively support runtime-linking, no plug-ins for Sun Java System Web Server versions 4.x and later will need to be relinked.

Load and Initialize the SAF

For each shared library (plug-in) containing custom SAFs to be loaded into the Sun Java System Web Server, add an Init directive that invokes the load-modules SAF to magnus.conf.

The syntax for a directive that calls load-modules is:

Init fn=load-modules shlib=[path]sharedlibname funcs="SAF1,...,SAFn"

• shlib is the local file system path to the shared library (plug-in).

• funcs is a comma-separated list of function names to be loaded from the shared library. Function names are case-sensitive. You may use dash a (-) in place of an underscore (_) in function names. There should be no spaces in the function name list.

  If the new SAFs require initialization, be sure that the initialization function is included in the funcs list.

  For example, if you created a shared library animations.so that defines two SAFs do_small_anim() and do_big_anim() and also defines the initialization function init_my_animations, you would add the following directive to load the plug-in:

Init fn=load-modules shlib=animations.so 
funcs="do_small_anim,do_big_anim,init_my_animations"

If necessary, also add an Init directive that calls the initialization function for the newly loaded plug-in. For example, if you defined the function init_my_new_SAF() to perform an operation on the maxAnimLoop parameter, you would add a directive such as the following to magnus.conf:

Init fn=init_my_animations maxAnimLoop=5

Instruct the Server to Call the SAFs

Next, add directives to obj.conf to instruct the server to call each custom SAF at the appropriate time. The syntax for directives is:

Directive fn=function-name [name1="value1"]...[nameN="valueN"]

• Directive is one of the server directives, such as AuthTrans, Service, and so on.

• function-name is the name of the SAF to execute.

• nameN="valueN" are the names and values of parameters which are passed to the SAF.

  Depending on what your new SAF does, you might need to add just one directive to obj.conf, or you might need to add more than one directive to provide complete instructions for invoking the new SAF.

  For example, if you define a new AuthTrans or PathCheck SAF, you could just add an appropriate directive in the default object. However, if you define a new Service SAF to be invoked only when the requested resource is in a particular directory or has a new kind of file extension, you would need to take extra steps.

  If your new Service SAF is to be invoked only when the requested resource has a new kind of file extension, you might need to add an entry to the MIME types file so that the type value gets set properly during the ObjectType stage. Then you could add a Service directive to the default object that specifies the desired type value.

  If your new Service SAF is to be invoked only when the requested resource is in a particular directory, you might need to define a NameTrans directive that generates a name or ppath value that matches another object, and then in the new object you could invoke the new Service function.

  For example, suppose your plug-in defines two new SAFs, do_small_anim() and do_big_anim(), which both take speed parameters. These functions run animations. All files to be treated as small animations reside in the directory D:/Sun/WebServer61/server1/docs/animations/small, while all files to be treated as full-screen animations reside in the directory D:/Sun/WebServer61/server1/docs/animations/fullscreen.

  To ensure that the new animation functions are invoked whenever a client sends a request for either a small or full-screen animation, you would add NameTrans directives to the default object to translate the appropriate URLs to the corresponding path names and also assign a name to the request.

NameTrans fn=pfx2dir from="/animations/small"
dir="D:/Sun/WebServer61/server1/docs/animations/small" name="small_anim"
NameTrans fn=pfx2dir from="/animations/fullscreen"
dir="D:/Sun/WebServer61/server1docs/animations/fullscreen"
name="fullscreen_anim"

         

You also need to define objects that contain the Service directives that run the animations and specify the speed parameter.

<Object name="small_anim">
Service fn=do_small_anim speed=40
</Object>
<Object name="fullscreen_anim">
Service fn=do_big_anim speed=20
</Object>

         

Restart the Server

After modifying obj.conf, you need to restart the server. A restart is required for all plug-ins that implement SAFs and/or filters.

Test the SAF

Test your SAF by accessing your server from a browser with a URL that triggers your function. For example, if your new SAF is triggered by requests to resources in http://server-name/animations/small, try requesting a valid resource that starts with that URI.

You should disable caching in your browser so that the server is sure to be accessed. In Netscape Navigator you may hold the shift key while clicking the Reload button to ensure that the cache is not used. (Note that the shift-reload trick does not always force the client to fetch images from source if the images are already in the cache.)

You may also wish to disable the server cache using the cache-init SAF.

Examine the access log and error log to help with debugging.