Web Application Server Programming

This section contains the following topics:

•

Overview

•	Developing Native Oracle Tuxedo Web Applications

•	Developing Python Web Applications

•	Developing Ruby Web Applications

•	Developing PHP Web Applications

Overview

Oracle SALT adds features that enable Web Applications to run in Oracle Tuxedo and be accessed easily through HTTP server plug-ins. Using HTTP servers such as Apache 2, Oracle HTTP Server and iPlanet, you can directly expose applications to the World Wide Web. HTTP servers must use Oracle Tuxedo-specific plug-ins (referred to as mod_tuxedo) that translates HTTP requests into Oracle Tuxedo requests, and translates Oracle Tuxedo responses into HTTP responses.

Note:

On HP platforms, plug-in libraries must be built with multi-threading enabled via the compiler -mt flag because the GWWS system server is a multi-threaded program.

Applications can be written in C or C++ using a Gateway Interface similar to CGI but specific to Oracle Tuxedo servers and their mode of communication, or in dynamic languages such as PHP, Python and Ruby. Using dynamic languages, programs are not aware that they are running in Oracle Tuxedo, which allows re-using application frameworks such as Symfony (PHP), Django (Python) or Rails (Ruby) directly into an Oracle Tuxedo-based environment.

Developing Native Oracle Tuxedo Web Applications

While mod_tuxedo provides the Oracle Tuxedo client part of Web requests serving, on the Oracle Tuxedo side one of the methods of processing the requests is to access them directly. This is permitted by documenting the format of the received buffer, which is an Oracle Tuxedo FML32 typed buffer.

This method allows you to generate dynamic HTTP content by developing Oracle Tuxedo services and leverage Oracle Tuxedo RASP and integration capabilities in doing so.

The relevant elements of an HTTP request are exposed (Method name, Query string URL, File name, POST data, etc.). As well as the return data to mod_tuxedo (HTTP Response Headers (if necessary), HTML document).

For more information, see Oracle SALT reference Guide.

The development process is similar to developing a regular Oracle Tuxedo service that generates HTML code, the difference being that developing RESTful services adheres to a set of conventions or rules governing the behavior of the service (a service processing GET should behave differently than when processing PUT). RESTful services are generally not designed to be accessed using an HTML browser (that is, similar to SOAP services).

The data flow is as follows:

•	An Apache2 or OHS process is configured to handle certain URLs using the mod_tuxedo module.

•	mod_tuxedo intercepts the request.

•	mod_tuxedo formats the request and sends it to an Oracle Tuxedo service, which name is derived from the SCRIPT_NAME value. In the examples that follow, the service in question is named TUXSVC.

•	The Oracle Tuxedo service receives the data and processes it accordingly:

•	REQUEST_METHOD contains the REST operation: GET, PUT, POST or DELETE.

•	PATH_INFO may contain the resource accessed. In this example, it contains "/1234". The program can parse this value according to a documented convention between client and server to obtain the account number.

•

QUERY_STRING or POST_DATA (for GET or POST) may contain additional parameters. Pre-determined conventions govern what the parameters look like and what they contain. This is determined by service developers and published as application documentation so client programs can be developed to communicate with these services.

•	The Oracle Tuxedo service composes a response which is implicitly sent back to mod_tuxedo.

•	The format of the response is up to you:

•

"XML

•	"CSV (comma-separated values)

•

JSON

•

…

•	mod_tuxedo sends the response back to the client program.

The different components are shown in Listing 3‑1 through Listing 3‑4

Listing 3‑1 Configure OHS or Apache2 (httpd.conf excerpt)

<Location "/ACCOUNT">

 

<IfModule mod_tuxedo.c>

SetHandler tuxedo-script

Tuxconfig "/home/maurice/src/tests/secsapp/work/tuxconfig"

</IfModule>

 

</Location>

 

Write the Oracle Tuxedo service as shown in Listing 3‑2

Listing 3‑2 Oracle Tuxedo Service

void

ACCOUNT(TPSVCINFO *rqst)

{

char val[1024]; /* TODO: query size first */

long len;

int rc;

 

/* Fetch PATH_INFO value, which contains the resource */

len = sizeof(val);

rc = Fget32((FBFR32 *)inbuf, PATH_INFO, 0, (char *)val, &len);

if (rc < 0) {

/* Handle error */

}

 

/* Variable 'val' contains resource name, process it */

...

 

/* Fetch QUERY_STRING, which optionally contains

additional parameters */

len = sizeof(val);

rc = Fget32((FBFR32 *)inbuf, QUERY_STRING, 0, (char *)val, &len);

if (rc < 0) {

/* Handle error */

}

 

/* Depending on method, do processing */

len = sizeof(val);

rc = Fget32((FBFR32 *)inbuf, REQUEST_METHOD, 0, (char *)val, &len);

if (rc < 0) {

/* Handle error */

}

 

if (strcmp(val, "GET") == 0) {

...

} else if (strcmp(val, "PUT") == 0) {

...

} else if (strcmp(val, "POST") == 0) {

/* Get POST_DATA, parse it */

...

} else if (strcmp(val, "DELETE") == 0) {

...

}

 

/* Compose return document, using xml or JSON */

...

 

/* Return result document */

tpreturn(TPSUCCESS, 0, result, 0L, 0);

}

 

Example URL/response:

Method: GET

Request URL: http://myhost/ACCOUNT/1234

Response (XML) as shown in Listing 3‑3.

Note:

XML generation can be done using existing libtxml.

Listing 3‑3 XML Response

<account id="1234">

<balance value="10000"/>

<customer name="John Smith"/>

</account>

 

Response (JSON) as shown in Listing 3‑4.

Note:

JSON generation can be done using JSON-C, a free and redistributable JSON implementation in C (MIT license), provided as source code. Many libraries exist in a number of languages including PHP, Perl, Python, Ruby, Java, etc.

Listing 3‑4 JSON Response

[

"account": {

"id": "1234",

"balance": {

"value": "10000"

},

"customer": {

"name": "John Smith"

}

}

]

 

Developing Python Web Applications

Similar to how PHP applications can run inside the WEBHNDLR Oracle Tuxedo System Server, Oracle SALT allows writing applications for the Web in Python.Unlike PHP (where all scripts are designed to run in a CGI-like model), Python require running using a specific Web layer.

This layer is designated as WSGI (Web Server Gateway Interface) and is built into the language. It actually is a Python specification (PEP 333). In Python, although applications may be written for WSGI, complete application frameworks are available (conforming to WSGI. Django seems to be the most popular).

The following sections describe how to configure WEBHNDLR to run Python WSGI applications (including using the Django framework).

•	Prerequisites

•

Usage

•	Example(s)

Prerequisites

•	A Python 2.5.5 or higher installation.

•	Python must be built with shared-libraries enabled. This is usually the case for out-of-the-box installations. If you are building from source, the --enable-shared options must be used in the configure step.

•	There are no known database or third-party library support restrictions.

Usage

A simple WSGI application example is shown in Listing 3‑5

Listing 3‑5 WSGI Application Example

import cgi

 

def application(environ, start_response):

form = cgi.FieldStorage(fp=environ['wsgi.input'],

environ=environ,

keep_blank_values=1)

write = start_response('200 OK', [('Content-type', 'text/html')])

if form.getvalue('name'):

write('<html><head><title>Hello!</title></head>\n')

write('<body>\n')

write('<h1>Hello %s!</h1>\n' % form['name'].value)

else:

write('<html><head><title>Who is there?</title></head>\n')

write('<body>\n')

write('<h1>Who is there?</h1>\n')

write('<form action="%s" method="POST">\n' % environ['SCRIPT_NAME'])

write('What is your name?<br>\n')

write('<input type="text" name="name" value="%s"><br>\n'

% cgi.escape(form.getvalue('name', ''), 1))

write('<input type="submit" value="That is my name"></form>\n')

write('</body></html>\n')

return None

 

With frameworks such as Django, this is performed in a handler script that is not seen by the application developer.

Any Python WSGI application may run inside the WEBHNDLR System Server by performing the following steps:

1.	Configure Apache (or OHS) to forward requests to WEBHNDLR. This may require additional configuration to indicate the path to necessary static files (for example, images, CSS stylesheets or javascript files).

2.	Add the application path to the PYTHONPATH environment variable.

3.	Set APP_CONFIG for WEBHNDLR to load the application or middleware handler (for frameworks like Django).

For more information, see Oracle SALT Reference Guide.

Example(s)

Stand-Alone Script/Application

Listing 3‑6 shows an Apache configuration for a WSGI application example.

Listing 3‑6 Stand-Alone Script/Application Example

<VirtualHost 10.143.7.223:2280>

DocumentRoot "/media/src/tests"

<Directory "/media/src/tests">

<IfModule mod_tuxedo.c>

SetHandler tuxedo-script

Tuxconfig "/media/src/TUX11g/web/tests/tuxconfig"

TuxService PYWEB

</IfModule>

</Directory>

</VirtualHost>

 

The ubbconfig file and setting for a standalone WSGI application are located in a script named test_app.py (==module), in the /media/src/tests directory (PYTHONPATH must contain /media/src/tests):

WEBHNDLR SRVGRP=PHPGRP SRVID=1 MIN=5 MAX=8
   CLOPT="-A -- -l Python -S PYWEB "

Before booting WEBHNDLR, you must either

•	set APP_CONFIG to test_app ('export APP_CONFIG=test_app' on Unix), or

•	use an ENVFILE with the value APP_CONFIG=test_app.

Django-Based Application

For an Apache Django-based application you must note the RewriteEngine rules and Alias. These are there to indicate the location of static files (for example, CSS, images or javascript), and also map the root URL to the application (see last RewriteRule) as shown in Listing 3‑7.

Listing 3‑7 Django-Based Application

<VirtualHost 10.143.7.223:2280>

DocumentRoot "/media/src/test_django/mysite"

Alias /media /usr/lib/python2.5/site-packages/django/contrib/admin/media

<Directory "/media/src/test_django/mysite">

<IfModule mod_tuxedo.c>

SetHandler tuxedo-script

Tuxconfig "/media/src/TUX11g/web/tests/tuxconfig"

TuxService PYWEB

</IfModule>

</Directory>

 

RewriteEngine On

RewriteRule ^/(media.*)$ /$1 [QSA,L,PT]

RewriteCond %{REQUEST_FILENAME} !-f

RewriteRule ^/(.*)$ /mysite/$1 [QSA,L]

</VirtualHost>

 

The environment variable DJANGO_SETTINGS_MODULE must be set before booting WEBHNDLR. For example, for an application named mysite:

DJANGO_SETTINGS_MODULE=mysite.settings

The PYTHONPATH setting for a Django example, called mysite and located in the /media/src/test_django directory:

PYTHONPATH=/media/src/test_django

The ubbconfig setting for the Django example mentioned here:

WEBHNDLR SRVGRP=PHPGRP SRVID=1 MIN=5 MAX=8

CLOPT="-A -- -l Python -S PYWEB"

Before booting WEBHNDLR, you must either:

•	set APP_CONFIG to django.core.handlers.wsgi (WSGIHandler) ('export APP_CONFIG="django.core.handlers.wsgi (WSGIHandler)"' on Unix), or

•	use an ENVFILE with the value APP_CONFIG=" django.core.handlers.wsgi (WSGIHandler)".

Developing Ruby Web Applications

Similar to how PHP applications can run inside the WEBHNDLR Oracle Tuxedo System Server, Oracle SALT allows writing applications for the Web in Ruby.Unlike PHP (where all scripts are designed to run in a CGI-like model), Ruby requires running using a specific Web layer.

There is an equivalent to WSGI (called Rack), which is done in the form of a library that installs separately. In Ruby, although applications may be written on top of Rack directly, complete application frameworks are available such as Rails. A rack application is an interface between application and servers for Ruby (similar to WSGI). It is usually installed as an add-on to the language, and is a pre-requisite to application server environments such as Rails. The sections below describe how to configure WEBHNDLR to run Ruby Rack-conformant applications, including using the Rails framework.

•	Prerequisites

•

Usage

•	Example(s)

Prerequisites

•	A Ruby 1.9.x installation.

•	Ruby must be built with shared-libraries enabled. This is usually the case for out-of-the-box installations. If building from source the '--enable-shared' options must be used in the configuration.

•	Rails 2.x or 3.0.x libraries.

•	There are no known database or third-party library support restrictions.

Usage

Listing 3‑8 shows a simple Rack application example.

Listing 3‑8 Simple Rack Application Example

class HelloWorld

def call(env)

[200, {"Content-Type" => "text/plain"}, ["Hello world!"]]

end

end

 

With frameworks like Ruby, this is performed in a handler script that is not seen by the application developer.

The script in Listing 3‑8 is passed to the handler using a RackUp script that allows adding more functionality (such as pretty exceptions, LINT wrappers, etc.) to the application.

A RackUp script example loading the application is shown in Listing 3‑9.

Listing 3‑9 RackUp Script Example

require 'hello'

 

use Rack::ShowExceptions

run HelloWorld.new

 

Any Ruby Rack-compliant application may run inside the WEBHNDLR system server by performing the following steps:

1.	Configure Apache (or OHS) to forward requests to WEBHNDLR. This may require additional configuration to indicate the path to necessary static files (for example, CSS stylesheets or javascript files).

2.	Configure WEBHNDLR to load the application or middleware handler (for frameworks like Rails).

Example(s)

Ruby Rack Lobster

Listing 3‑10 shows an Apache (or OHS) configuration example.

Listing 3‑10 Apache (or OHS) Configuration Example

<VirtualHost 10.143.7.223:2380>

DocumentRoot "/media/src/tests"

<Directory "/media/src/tests">

<IfModule mod_tuxedo.c>

SetHandler tuxedo-script

Tuxconfig "/media/src/TUX11g/web/tests/tuxconfig"

TuxService RBWEB

</IfModule>

</Directory>

</VirtualHost>

 

The ubbconfig file WEBHNDLR setting is as follows:

WEBHNDLR SRVGRP=PHPGRP SRVID=1 MIN=5 MAX=8

CLOPT="-A -- -l Ruby -S RBWEB"

Set APP_CONFIG.

Ruby Rails Application

For an Apache (or OHS) configuration, you must note e the RewriteEngine rules and AddHandler directive (as opposed to SetHandler). These are there to re-direct the HTTP server to static files (CSS, images, javascript, etc.) as shown in Listing 3‑11.

Listing 3‑11 Ruby Rails Application

<VirtualHost 10.143.7.223:2380>

SetEnv RAILS_RELATIVE_URL_ROOT /media/src/rails_test

DocumentRoot "/media/src/rails_test/public"

 

RewriteEngine On

 

RewriteRule ^(/stylesheets/.*)$ - [L]

RewriteRule ^(/javascripts/.*)$ - [L]

RewriteRule ^(/images/.*)$ - [L]

 

RewriteRule ^$ index.html [QSA]

RewriteRule ^([^.]+)$ $1.html [QSA]

RewriteCond %{REQUEST_FILENAME} !-f

 

RewriteRule ^/(.*)$ /rails3.tuxrb [QSA,L]

 

<Directory "/media/src/rails_test/public">

Allow from All

<IfModule mod_tuxedo.c>

AddHandler tuxedo-script .tuxrb

Tuxconfig "/media/src/TUX11g/web/tests/tuxconfig"

TuxService RBWEB

</IfModule>

</Directory>

 

</VirtualHost>

 

The ubbconfig file WEBHNDLR setting (assuming the Rails application has been set up in the /media/src/rails_test directory and is named RailsTest) is as follows:

WEBHNDLR SRVGRP=PHPGRP SRVID=1 MIN=5 MAX=8

CLOPT="-A -- -l Ruby -S RBWEB'. That is, remove the "-a /media..." portion

Before booting WEBHNDLR, you must either:

•	set APP_CONFIG to path to rack up script ('export APP_CONFIG=" /media/src/rails_test/config.ru"' on Unix), or use an ENVFILE with the value APP_CONFIG=" /media/src/rails_test/config.ru".

Developing PHP Web Applications

PHP scripts are directly supported by WEBHNDLR and no specific changes are required for applications to run in an Oracle Tuxedo environment. Configuring the location of PHP scripts in the HTTP server is sufficient. Once the framework is configured to run PHP scripts in WEBHNDLR, PHP applications are automatically supported.

For more information, see Oracle SALT Command Reference Guide.

•	Prerequisites

•

Usage

•	Example(s)

Prerequisites

•	PHP 5.3.2 or higher installation.

•	PHP must be built using the --enable-embed configure option.

•	There are no known database or third-party library support restrictions.

Usage

PHP scripts are directly supported by WEBHNDLR; no specific changes are required for applications to run in an Oracle Tuxedo environment. Configuring the location of PHP scripts in the HTTP server is sufficient. Once the framework is configured to run PHP scripts in WEBHNDLR, PHP applications are automatically supported.

Example(s)

Place a script named "test.php" (as shown in Listing 3‑12) in the document root folder of the HTTP server:

Listing 3‑12 test. php Script

-- listing x-x test.php script

<?php

phpinfo();

?>

--

 

Point your browser to: http://<your_host>:<port>/test.php.

See Also

•	Oracle SALT Administration Guide

•	Oracle SALT Reference Guide