README twiki 20040901 OO

## TWiki 20040901

## - in Object Oriented

## - multiple configurations

## - a program to trasform your twiki installation

## using modperl2

- why

- what transformation does

- how to use this package

- transform twiki in Object Oriented

- transform twiki in Object Oriented and install it with modperl2

- install twiki with multiple configurations

- requirements to transform twiki with other plugins

- transform other versions of twiki

- benchmark

· benchmark twiki

· benchmark twiki OO with modperl2

· conclusions

## -why

Twiki in Object Oriented prevents conflits between multiple twiki session opened on an Apache server with mod_perl. So twiki installation with multiple configuration becomes possible and stable.
Moreover having multiple configurations working on the same web server without conflits also allows you to reduce the number of processes and web server instances running on a single system.

## -what transformation does

-Each package is trasformed in a class.

-All subs are transformed in methods and all call to sub are substituted in call to method.

-"sub new" is added to each package and sets an attribute 'config' to host the address to a hash $config.

-Main programs in directory bin declar the variable $config as an address to a hash containing value of variables (first was global variables) and pointers to objects.

-All global variables are substituted with local variables named as
$config->{<package_name_of_global_var>}->{<global_var_name>}.
The $config variable is an address to a hash where each key refer to a single twiki global variable.
Example: the global variable "templateDir" of the package "TWiki.pm", will be replaced with "$config->{TWiki}->{templateDir}".
-In every method, the first operation is fecthing value of attribute 'config' from $self and saved to a local variable named $config.
All changes of values of $config keys are visible to every methods using it.
-A new method called init_config has been created to contain global variable initializations not included in any subroutine ( the same for code in BEGIN blocks ).
-The .pm files composed of several packages, generate a single file for each package. For example the file Prefs.pm generates the files Prefs.pm , Prefs/PrefsCache.pm, Prefs/TopicPrefs.pm.

## -how to use this package

This package contains a modified version of TWiki ( 20040901 version ) transformed in Object Oriented ( tested on a Red Hat 9 ), it is composed of:
- the directories ./bin and ./lib
- some configuration files
(NOTE: The name of the url and the name of configuration files are strictly related )

- lib/alphaPort80twikioo.pm will deploy http://alpha:80/twikioo/bin/view
(twiki code have to be installed in the directory /home/httpd/twikioo )

- lib/alphaPort80twikioo2.pm will deploy http://alpha:80/twikioo2/bin/view
(twiki code have to be installed in the directory /home/httpd/twikioo , pubDir in /home/httpd/twikioo/pub2 and dataDir in /home/httpd/twikioo/data2 and templateDir in /home/httpd/twikioo/templates2 )

The package also contains :
- modperlize20040901oo.pl and twiki.diff.20040901oo used to "transform" the original twiki20040901. You can use them to transform also your own twiki code as described in this document.
- README20040901oo.html (this document)
To use this package you need to:

- copy twiki directory in twikioo

cd /home/httpd/
cp -r twiki twikioo

- untar package in /home/httpd/twikioo/

cd /home/httpd/twikioo/

rm –rf bin lib

tar -xvzf twiki20040901oo.tar.gz ./bin ./lib

- check that all files in bin directory have execution permission

- modify perl.conf as described in transform twiki in OO and install it with modperl2 in step 3

- copy alphaPort80twikioo.pm in <your server name>Port<your port>twikioo.pm

cd /home/httpd/twikioo/lib
cp alphaPort80twikioo.pm <your server name>Port<your port>twikioo.pm

- edit file <your server name>Port<your port>twikioo.pm and set correct pubDir, templateDir, dataDir
- edit file bin/setlib.cfg and set correct twikiLibPath

- stop and start Apache

- now url http://<your server name>:<your port>/twikioo/bin/view is available for browsing.

To use the second configuration file lib/alphaPort80twikioo2.pm, you need to:

- execute the steps above

- execute the steps described in install twiki with multiple configurations in step 1,2,and 4

## -transform twiki in Object Oriented

Following this steps it is possible to make a version of your own twiki (20040901) in OO and run it on a webserver without modperl.
Settings, twiki users, installed plugins will be remain unchanged.
For the plugins verify their prerequisities as described in "requirements to transform twiki with other plugins".
STEPS
------------------
1 - Copy files twiki.diff.20040901oo and modperlize20040901oo.pl in the parent directory of twiki
2 - Run ./modperlize20040901oo.pl
(The script will apply the patch and will ask confirm before continue, so you can check the result of patch process)
During transformation the script shows several messagges on standard output.

At last, it will ask the informations to create your twiki configuration file:

-host name

-web server port

-twiki REQUEST_URI setted in your file perl.conf

(You can modify the file or create a new file follow the steps below )

Estimated time : few minutes .
3 - Choose A or B :

- A: (replace running twiki installation)

- backup your twiki directory ( for example you can copy the directory twiki )
- replace bin and lib directories with the bin and lib ones just created by step 2 in twiki.modperlOneKey directory.
- check that all files in bin directory have execution permission.
- if not created in step 2, create the configuration file lib/<host_name>Port<web_server_port>twiki.pm :

- cp TWikicfg.pm <host_name>Port<web_server_port>twiki.pm

- B : (create a new twiki installation inheriting settings, users, etc. )

- copy twiki directory in a directory named twikioo.
- replace bin and lib directories (in twikioo) with the bin and lib ones just created by step 2 in twiki.modperlOneKey directory
- check that the directory pub, data have write pernission for webserver user.
- check that all files in bin directory have execution permission.
- if not correctly created in step 2, modify twikioo/lib/TWikicfg.pm file, replacing string twiki with twikioo where necessary, use the commands:

    cd twikioo/bin

    perl -pi~ -e 's/\/twiki\//\/twikioo\//' TWikicfg.pm

- copy TWikicfg.pm in twikioo.pm :

                cp TWikicfg.pm alpahPort80twikioo.pm

- Add in the configuration file perl.conf:

    #
    # FOR twiki oo without global variable
    #
     ScriptAlias /twikioo/bin/ "/home/httpd/twikioo/bin/"
     Alias /twikioo/ "/home/httpd/twikioo/"
     <Directory "/home/httpd/twikioo/bin">
        Options +ExecCGI
        SetHandler cgi-script
        Allow from all
     </Directory>
     <Directory "/home/httpd/twikioo/pub">
        Options FollowSymLinks +Includes
        AllowOverride None
        Allow from all
     </Directory>
     <Directory "/home/httpd/twikioo/data">
        deny from all
     </Directory>
     <Directory "/home/httpd/twikioo/templates">
        deny from all
     </Directory>

4 - now you can remove twiki.patched and twiki.modperlOneKey directories.
Stop and start Apache. Now url http://alpha:80/twiki/bin/view is available for browsing ( for case B, the url will be http://<hostname>/twikioo/bin/view) . Twiki pages will appear as usual, but in twiki/bin/testenv page you can see the new local variable that replaced the global ones, i.e. you can read "$config->{TWiki}->{pubDir}" instead of "pubDir".

## -transform twiki in OO and install it with modperl2

If you have installed modperl2 , ( included in Linux-Red Hat 9 installation ), you can transform twiki in Object Oriented using modperl, following described steps.
STEPS
--------------------------

1 - Apply changes as described in steps 1,2: transform twiki in Object Oriented
2 -

- copy twiki directory in a directory named twikioo .

- replace bin and lib directories (in twikioo) with the bin and lib ones just created by step 2 in twiki.modperlOneKey directory

- check that all files in bin directory have execution permission.

- if not correctly created in step 1,modify twikioo/lib/TWikicfg.pm file, replacing string twiki with twikioo where necessary, use the commands:

          cd twikioo/lib
          perl -pi~ -e 's/\/twiki\//\/twikioo\//' TWikicfg.pm

- create configuration file alphaPort80twikioo.pm : cp TWikicfg.pm alphaPort80twikioo.pm ( this guide assumes "alpha" the name of your name server )

3 - Add in the configuration file perl.conf ( usually you can find it in /etc/httpd/conf.d/ ) :

    LoadModule perl_module modules/mod_perl.so
    #
    # FOR twiki modperl installation and without global variable
    #
    Alias /twikioo /home/httpd/twikioo/
    <Directory /home/httpd/twikioo/bin>
        SetHandler perl-script
        PerlHandler ModPerl::Registry::handler
        PerlOptions +ParseHeaders
        Options +ExecCGI
     </Directory>
     <Directory "/home/httpd/twikioo/pub">
        Options FollowSymLinks +Includes
        AllowOverride None
        Allow from all
     </Directory>
     <Directory "/home/httpd/twikioo/data">
        deny from all
     </Directory>
     <Directory "/home/httpd/twikioo/templates">
        deny from all
     </Directory>

4 - now you can remove twiki.patched and twiki.modperlOneKey directories.
Stop and start Apache. Now url http://alpha:80/twikioo/bin/view is available for browsing. Twiki pages will appear as usual, but in twikioo/bin/testenv page you can see the new local variable that replaced the global ones, i.e. you can read "$config->{TWiki}->{pubDir}" instead of "pubDir", and you can read :

MOD_PERLmod_perl/1.99_07-dev
mod_perl:Used for this script (mod_perl not loaded into Apache) - mod_perl version 1.9907

## -install twiki with multiple configurations

When you have a twiki Object Oriented version without using global variable and installed on modperl2, you can define multi configuration files.
The name of the url and the name of configuration files are strictly related; the name of configuration file are composed of:
-the server name
-the server port
-the twiki REQUEST_URI setted in your file perl.conf and ".pm" .
i.e. url http://alpha:80/twikioo2/bin/view will serch for configuration file lib/alphaPort80twikioo2.pm.
Following the steps to define multi configurations.
STEPS
--------------------------
1 - Apply all steps described in transform twiki in Object Oriented and install it with modperl2
2 - Create pub2 data2 and templates2 directory in twikioo directory :

- Copy pub directory in pub2 , data directory in data2 and templates directory in templates2

- Check that the directory pub2, data2 have write pernission for webserver user.

3 - Create twikioo/lib/alphaPort80twikioo2.pm file and replace references as described here :

        cd twikioo/lib
        cp alphaPort80twikioo.pm alphaPort80twikioo2.pm
        perl -pi~ -e 's/\/twikioo\/bin/\/twikioo2\/bin/' alphaPort80twikioo2.pm
        perl -pi~ -e 's/\/data/\/data2/' alphaPort80twikioo2.pm
        perl -pi~ -e 's/\/pub/\/pub2/' alphaPort80twikioo2.pm
        perl -pi~ -e 's/\/templates/\/templates2/' alphaPort80twikioo2.pm

4 - Add in the configuration file perl.conf ( usually you can find it in /etc/httpd/conf.d/ ) :

    LoadModule perl_module modules/mod_perl.so
    #
    # FOR twiki oo with modperl installation and without global variable
    #
    Alias /twikioo2 /home/httpd/twikioo/
     <Directory "/home/httpd/twikioo/pub2">
        Options FollowSymLinks +Includes
        AllowOverride None
        Allow from all
     </Directory>
     <Directory "/home/httpd/twikioo/data2">
        deny from all
     </Directory>
     <Directory "/home/httpd/twikioo/templates2">
        deny from all
     </Directory>

Stop and start Apache. Now url http://<hostname>/twikioo2/bin/view is available for browsing.

## -requirements to transform twiki with other plugins

You can apply the transformation on your twiki installation ( 20040901 ) with any installed plugin, you just need to :
-verify Plugin file in lib/TWiki/Plugins/ to check it for local variables name equal to any its global variable name. If you found any, you need to change the name of conflicting local variable.
-with plugins using object classes, methods must use the self variable for properties of the object.

## -transform other versions of twiki

This trasformation can be applied to different versions of twiki, with the same improvement achieved in 20040901.
This is possible because modperlize20040901oo.pl it isn't strictly related to the twiki version ( except for the patch twiki.diff.20040901oo ).
Steps to transform your twiki:
- run modperlize20040901oo.pl

- this will apply the patch twiki.diff.20040901oo
- probably this patch won't be able to complete successfully due to different source code
- in this case you need to reply no at the question "Check patching and press y to continue: " prompted by the perl script
- check .rej files created in twiki.patched directory
- make patches rejected by editing manually source in twiki.package directory.
- make the new patch file:
diff -uwbBr twiki twiki.patched > twiki.diff.20040901oo
- run again modperlize20040901oo.pl

-now go to step 3 transform twiki in Object Oriented and install it with modperl2 .

## -benchmark

As benchmark program has been used "ab", a tool for benchmarking Apache HyperText Transfer Protocol server distibuited with Linux RedHat 9. The command used to perform 500 http requests was :

ab -n 500 http://myhost/twiki/bin/view

### -benchmark twiki

The following output is the result of "ab" requesting twiki/bin/view page in a twiki standard installation version 20040901.

    --------------------------------------------------
    This is This is ApacheBench, Version 2.0.40-dev <$Revision: 1.116 $> apache-2.0
    Copyright (c) 1996 Adam Twiss, Zeus Technology Ltd, http://www.zeustech.net/
    Copyright (c) 1998-2002 The Apache Software Foundation, http://www.apache.org/

    Server Software:        Apache/2.0.40
    Server Hostname:        alpha
    Server Port:            80

    Document Path:          /twiki/bin/view
    Document Length:        16640 bytes

    Concurrency Level:      1
    Time taken for tests:   1810.591098 seconds
    Complete requests:      500
    Failed requests:        0
    Write errors:           0
    Total transferred:      8411000 bytes
    HTML transferred:       8320000 bytes
    Requests per second:    0.28 [#/sec] (mean)
    Time per request:       3621.182 [ms] (mean)
    Time per request:       3621.182 [ms] (mean, across all concurrent requests)
    Transfer rate:          4.54 [Kbytes/sec] received

    Connection Times (ms)
                  min  mean[+/-sd] median   max
    Connect:        0    0   0.0      0       1
    Processing:  3579 3620  35.1   3607    4050
    Waiting:     3538 3619  34.9   3607    4050
    Total:       3579 3620  35.1   3607    4050

    Percentage of the requests served within a certain time (ms)
      50%   3607
      66%   3637
      75%   3647
      80%   3651
      90%   3662
      95%   3669
      98%   3677
      99%   3680
     100%   4050 (longest request)
    --------------------------------------------------

### -benchmark twiki OO

The following output is the result of "ab" requesting twikioo/bin/view page in a twiki version 20040901 Object Oriented installed on a server mod_perl.

    --------------------------------------------------
    This is ApacheBench, Version 2.0.40-dev <$Revision: 1.116 $> apache-2.0
    Copyright (c) 1996 Adam Twiss, Zeus Technology Ltd, http://www.zeustech.net/
    Copyright (c) 1998-2002 The Apache Software Foundation, http://www.apache.org/

    Server Software:        Apache/2.0.40
    Server Hostname:        alpha
    Server Port:            80

    Document Path:          /twikioo/bin/view
    Document Length:        16842 bytes

    Concurrency Level:      1
    Time taken for tests:   1271.439796 seconds
    Complete requests:      500
    Failed requests:        0
    Write errors:           0
    Total transferred:      8512000 bytes
    HTML transferred:       8421000 bytes
    Requests per second:    0.39 [#/sec] (mean)
    Time per request:       2542.880 [ms] (mean)
    Time per request:       2542.880 [ms] (mean, across all concurrent requests)
    Transfer rate:          6.54 [Kbytes/sec] received

    Connection Times (ms)
                  min  mean[+/-sd] median   max
    Connect:        0    0   2.6      0      58
    Processing:  2280 2541 803.8   2366   15401
    Waiting:     2189 2538 800.6   2362   15391
    Total:       2280 2541 803.8   2366   15401

    Percentage of the requests served within a certain time (ms)
      50%   2366
      66%   2427
      75%   2493
      80%   2536
      90%   2771
      95%   3188
      98%   4876
      99%   5411
     100%  15401 (longest request)
    --------------------------------------------------

## -conclusions

Run time of twiki OO with modperl2 are less than standard installation of about 29,8%.