Previous Contents Index Next |
Sun Java System Application Server Standard and Enterprise Edition 7 2004Q2 Developer's Guide to NSAPI

> ## Chapter 5
> Examples of Custom SAFs

> This chapter discusses examples of custom Sever Application Functions (SAFs) for each directive in the request-response process. You may wish to use these examples as the basis for implementing your own custom SAFs. For more information about creating your own custom SAFs, see Chapter 4, “Creating Custom SAFs.”

> Before writing custom SAFs, you should be familiar with the request-response process, the role of the configuration file obj.conf, and the pre-defined SAFs that are available. For details on both these topics, see Chapter 1, "Syntax and Use of obj.conf," and Chapter 2, “Predefined SAFs and the Request Handling Process.”

> For a list of the NSAPI functions for creating new SAFs, see Chapter 6, “NSAPI Function Reference.”

> This chapter has the following sections:

> - Examples in the Build
> - AuthTrans Example
> - NameTrans Example
> - PathCheck Example
> - ObjectType Example
> - Service Example
> - AddLog Example
> - Quality of Service Examples

> ##

> Examples in the Build

> The install_dir/samples/nsapi directory contains examples of source code for SAFs.

> You can use the example.mak makefile in the same directory to compile the examples and create a library containing the functions in all the example files.

> To test an example, load the examples shared library into the Sun Java System Application Server by adding the following directive in the Init section of init.conf:

> Init fn=load-modules shlib=examples.so/dll funcs=function1,function2,function3

> The funcs parameter specifies the functions to load from the shared library.

> If the example uses an initialization function, be sure to specify the initialization function in the funcs argument to load-modules, and also add an Init directive to call the initialization function.

> For example, the PathCheck example implements the restrict-by-acf function, which is initialized by the acf-init function. The following directive loads both these functions:

> Init fn=load-modules yourlibrary funcs=acf-init,restrict-by-acf

> The following directive calls the acf-init function during server initialization:

> Init fn=acf-init file=extra-arg

> To invoke the new SAF at the appropriate step in the response handling process, add an appropriate directive in the object to which it applies, for example:

> PathCheck fn=restrict-by-acf

> After adding new Init directives to init.conf, you always need to restart the Sun Java System Application Server to load the changes, since Init directives are only applied during server initialization.

> ##

> AuthTrans Example

> This simple example of an AuthTrans function demonstrate how to use your own custom ways of verifying that the username and password that a remote client provided is accurate. This program uses a hard coded table of user names and passwords and checks a given user's password against the one in the static data array. The userdb parameter is not used in this function.

> AuthTrans directives work in conjunction with PathCheck directives. Generally, an AuthTrans function checks if the username and password associated with the request are acceptable, but it does not allow or deny access to the request -- it leaves that to a PathCheck function.

> AuthTrans functions get the username and password from the headers associated with the request. When a client initially makes a request, the username and password are unknown so the AuthTrans function and PathCheck function work together to reject the request, since they can’t validate the username and password. When the client receives the rejection, the usual response is for it to pop up a dialog box asking the user for their username and password, and then the client submits the request again, this time including the username and password in the headers.

> In this example, the hardcoded-auth function, which is invoked during the AuthTrans step, checks if the username and password correspond to an entry in the hard-coded table of users and passwords.

> ### Installing the Example

> To install the function on the Sun Java System Application Server, add the following Init directive to init.conf to load the compiled function:

> Init fn=load-modules shlib=yourlibrary funcs=hardcoded-auth

> Inside the default object in obj.conf add the following AuthTrans directive:

> AuthTrans fn=basic-auth auth-type="basic" userfn=hardcoded-auth userdb=unused

> Note that this function does not actually enforce authorization requirements, it only takes given information and tells the server if it's correct or not. The PathCheck function require-auth performs the enforcement, so add the following PathCheck directive also:

> PathCheck fn=require-auth realm="test realm" auth-type="basic"

> ### Source Code

> The source code for this example is in the auth.c file in the install_dir/samples/nsapi directory.

> ##

> NameTrans Example

> The ntrans.c file in the install_dir/samples/nsapi directory contains source code for two example NameTrans functions:

> - explicit_pathinfo

> This example allows the use of explicit extra path information in a URL.

> - https_redirect

> This example redirects the URL if the client is a particular version of Netscape Navigator.

> This section discusses the first example. Look at the source code in ntrans.c for the second example.

> Note | The main thing that a NameTrans function usually does is to convert the logical URL in ppath in rq->vars to a physical pathname. However, the example discussed here, explicit_pathinfo, does not translate the URL into a physical pathname, it changes the value of the requested URL. See the second example, https_redirect, in ntrans.c for an example of a NameTrans function that converts the value of ppath in rq->vars from a URL to a physical pathname.

> The explicit_pathinfo example allows URLs to explicitly include extra path information for use by a CGI program. The extra path information is delimited from the main URL by a specified separator, such as a comma.

> For example:

> http://host_name/cgi/marketing,/jan/releases/hardware

> In this case, the URL of the requested resource (which would be a CGI program) is http://hostname/cgi/marketing and the extra path information to give to the CGI program is /jan/releases/hardware.

> When choosing a separator, be sure to pick a character that will never be used as part of the real URL.

> The explicit_pathinfo function reads the URL, strips out everything following the comma and puts it in the path-info field of the vars field in the request object (rq->vars). CGI programs can access this information through the PATH_INFO environment variable.

> One side effect of explicit_pathinfo is that the SCRIPT_NAME CGI environment variable has the separator character tacked on the end.

> Normally NameTrans directives return REQ_PROCEED when they change the path so that the server does not process any more NameTrans directives. However, in this case we want name translation to continue after we have extracted the path info, since we have not yet translated the URL to a physical pathname.

> ### Installing the Example

> To install the function on the Sun Java System Application Server, add the following Init directive to init.conf to load the compiled function:

> Init fn=load-modules shlib=yourlibrary funcs=explicit-pathinfo

> Inside the default object in obj.conf add the following NameTrans directive:

> NameTrans fn=explicit-pathinfo separator=","

> This NameTrans directive should appear before other NameTrans directives in the default object.

> ### Source Code

> This example is in the ntrans.c file in the install_dir/samples/nsapi directory.

> ##

> PathCheck Example

> The example in this section demonstrates how to implement a custom SAF for performing path checks. This example simply checks if the requesting host is on a list of allowed hosts.

> The Init function acf-init loads a file containing a list of allowable IP addresses with one IP address per line. The PathCheck function restrict_by_acf gets the IP address of the host that is making the request and checks if it is on the list. If the host is on the list, it is allowed access otherwise access is denied.

> For simplicity, the stdio library is used to scan the IP addresses from the file.

> ### Installing the Example

> To load the shared object containing your functions add the following line in the Init section of the init.conf file:

> Init fn=load-modules yourlibrary funcs=acf-init,restrict-by-acf

> To call acf-init to read the list of allowable hosts, add the following line to the Init section in init.conf. (This line must come after the one that loads the library containing acf-init).

> Init fn=acf-init file=fileContainingHostsList

> To execute your custom SAF during the request-response process for some object, add the following line to that object in the obj.conf file:

> PathCheck fn=restrict-by-acf

> ### Source Code

> The source code for this example is in pcheck.c in the install_dir/samples/nsapi directory.

> ##

> ObjectType Example

> The example in this section demonstrates how to implement html2shtml, a custom SAF that instructs the server to treat a .html file as a .shtml file if a .shtml version of the requested file exists.

> A well-behaved ObjectType function checks if the content type is already set, and if so, does nothing except return REQ_NOACTION.

> if(pblock_findval("content-type", rq->srvhdrs)) return REQ_NOACTION;

> The main thing an ObjectType directive needs to do is to set the content type (if it is not already set). This example sets it to magnus-internal/parsed-html in the following lines:

> /* Set the content-type to magnus-internal/parsed-html */ pblock_nvinsert("content-type", "magnus-internal/parsed-html", rq->srvhdrs);

> The html2shtml function looks at the requested file name. If it ends with .html, the function looks for a file with the same base name, but with the extension .shtml instead. If it finds one, it uses that path and informs the server that the file is parsed HTML instead of regular HTML. Note that this requires an extra stat call for every HTML file accessed.

> ### Installing the Example

> To load the shared object containing your function, add the following line in the Init section of the init.conf file:

> Init fn=load-modules shlib=yourlibrary funcs=html2shtml

> To execute the custom SAF during the request-response process for some object, add the following line to that object in the obj.conf file:

> ObjectType fn=html2shtml

> ### Source Code

> The source code for this example is in otype.c in the install_dir/samples/nsapi directory.

> ##

> Service Example

> This section discusses a very simple Service function called simple_service. All this function does is send a message in response to a client request. The message is initialized by the init_simple_service function during server initialization.

> For a more complex example, see the file service.c in the examples directory, which is discussed in More Complex Service Example.

> ### Installing the Example

> To load the shared object containing your functions add the following line in the Init section of the init.conf file:

> Init fn=load-modules shlib=yourlibrary funcs=simple-service-init,simple-service

> To call the simple-service-init function to initialize the message representing the generated output, add the following line to the Init section in init.conf. (This line must come after the one that loads the library containing simple-service-init).

> Init fn=simple-service-init generated-output="<H1>Generated output msg</H1>"

> To execute the custom SAF during the request-response process for some object, add the following line to that object in the obj.conf file:

> Service type="text/html" fn=simple-service

> The type="text/html" argument indicates that this function is invoked during the Service stage only if the content-type has been set to text/html.

> ### Source Code

> #include <nsapi.h>

> static char *simple_msg = "default customized content";

> /* This is the initialization function.
> * It gets the value of the generated-output parameter
> * specified in the Init directive in init.conf
> */
> NSAPI_PUBLIC int init-simple-service(pblock *pb, Session *sn,
> Request *rq)
> {
> /* Get the message from the parameter in the directive in
> * init.conf
> */
> simple_msg = pblock_findval("generated-output", pb);
> return REQ_PROCEED;

> }

> /* This is the customized Service SAF.
> * It sends the "generated-output" message to the client.
> */
> NSAPI_PUBLIC int simple-service(pblock *pb, Session *sn, Request *rq)
> {
> int return_value;
> char msg_length[8];

> /* Use the protocol_status function to set the status of the
> * response before calling protocol_start_response.
> */
> protocol_status(sn, rq, PROTOCOL_OK, NULL);

> /* Although we would expect the ObjectType stage to
> * set the content-type, set it here just to be
> * completely sure that it gets set to text/html.
> */
> param_free(pblock_remove("content-type", rq->srvhdrs));
> pblock_nvinsert("content-type", "text/html", rq->srvhdrs);

> /* If you want to use keepalive, need to set content-length header.
> * The util_itoa function converts a specified integer to a
> * string, and returns the length of the string. Use this
> * function to create a textual representation of a number.
> */

> util_itoa(strlen(simple_msg), msg_length);
> pblock_nvinsert("content-length", msg_length, rq->srvhdrs);

> /* Send the headers to the client*/
> return_value = protocol_start_response(sn, rq);
> if (return_value == REQ_NOACTION) {
> /* HTTP HEAD instead of GET */
> return REQ_PROCEED;
> }

> /* Write the output using net_write*/
> return_value = net_write(sn->csd, simple_msg,
> strlen(simple_msg));
> if (return_value == IO_ERROR) {
> return REQ_EXIT;
> }

> return REQ_PROCEED;

> }

> ### More Complex Service Example

> The send-images function is a custom SAF. When a file is accessed as /dir1/dir2/something.picgroup, the send-images function checks if the file is being accessed by a Mozilla/1.1 browser. If not, it sends a short error message. The file something.picgroup contains a list of lines, each of which specifies a filename followed by a content-type (for example, one.gif image/gif).

> To load the shared object containing your function, add the following line at the beginning of the init.conf file:

> Init fn=load-modules shlib=yourlibrary funcs=send-images

> Also, add the following line to the mime.types file:

> type=magnus-internal/picgroup exts=picgroup

> To execute the custom SAF during the request-response process for some object, add the following line to that object in the obj.conf file (send-images takes an optional parameter, delay, which is not used for this example):

> Service method=(GET|HEAD) type=magnus-internal/picgroup fn=send-images

> ### Source Code

> The source code is in service.c in the install_dir/samples/nsapi directory.

> ##

> AddLog Example

> The example in this section demonstrates how to implement brief-log, a custom SAF for logging only three items of information about a request: the IP address, the method, and the URI (for example, 198.93.95.99 GET /jocelyn/dogs/homesneeded.html).

> ### Installing the Example

> To load the shared object containing your functions add the following line in the Init section of the init.conf file:

> Init fn=load-modules shlib=yourlibrary funcs=brief-init,brief-log

> To call brief-init to open the log file, add the following line to the Init section in init.conf. (This line must come after the one that loads the library containing brief-init).

> Init fn=brief-init file=/tmp/brief.log

> To execute your custom SAF during the AddLog stage for some object, add the following line to that object in the obj.conf file:

> AddLog fn=brief-log

> ### Source Code

> The source code is in addlog.c is in the install_dir/samples/nsapi directory.

> ##

> Quality of Service Examples

> The code for the qos-handler and qos-error SAFs is provided as an example in case you want to define your own SAFs for quality of service handling.

> For more information, see the Sun Java System Application Server Performance Tuning Guide.

> ### Installing the Example

> Inside the default object in obj.conf, add the following AuthTrans and Error directives:

> AuthTrans fn=qos-handler ... Error fn=qos-error code=503

> ### Source Code

> The source code for this example is in the qos.c file in the install_dir/samples/nsapi directory.

> Previous Contents Index Next

> Copyright 2004 Sun Microsystems, Inc. All rights reserved.