WDKInstallComments-Maria.doc

seasoningalluringΔιαχείριση Δεδομένων

29 Νοε 2012 (πριν από 4 χρόνια και 6 μήνες)

250 εμφανίσεις






Installing the WDK

Installing the WDK is a multistep process. Expect it to take on the order of an hour to
complete.

Understanding the install targets

There are two targets of the installatio
n


$GUS_HOME
-

This is the location that you install the model to when testing it


The web application server
-

This is the location you install the whole WDK when it
will run as a website

To get started, you will install and test the WDK model facilities. F
or this, you can set
your GUS_HOME to be anywhere, such as a gushome directory in your home directory.

Once these facilities are in place, you will be able to design your own model against the
data in your database. You will be able to do significant devel
opment and testing of your
model without running in the trickier context of a web application.

After you are satisfied with your model, it will be time to move to the web application
server. To do so, set up a GUS_HOME that is in the same file system as yo
ur web
application directories. (You will be creating symbolic links from the web application
directory into GUS_HOME.) Then follow the instructions below for installing the
webapp.

System requirements


Java: the WDK require Java 1.5


Operating system: the W
DK has been tested on Linux


Application server: the WDK has been tested on Tomcat 5.0.
It does not run under
Tomcat 4.x.


Database: the WDK has been tested on Oracle (version 9i and 10g) and PostgreSQL

Using the GUS install system

The WDK uses the GUS insta
ll system, which is included with the WDK releases.
Follow the
GUS Installer instructions

to set it up.

Downloading

Get the latest release of the WDK from
here

Unpack it into the $PROJECT_HOME you set up for the GUS install system.

Then, install the WDK into $GUS_HOME


need more detail for how to do it.


1.) setup $PROJECT_HOME and $GUS_HOME as an system variable. The better to
put
them under the same root, such as //gus


2.) Unzip the condensed file into $PROJECT_HOME directory.


build WDK install
-
append

Installing the database driver

The current release supports Oracle and PostgreSQL.

The PostgreSQL JDBC driver is included in t
he distribution

But, for licensing reasons,
the Oracle JDBC driver is not included in the distribution
. To
include it:


get a copy

(such as ojdbc14.jar)

from your system administator or visit the
Oracle

downloads site


copy it into $GUS_HOME/lib/java/db_driver


(the build system provides an "IMPORTANT REMINDER" to alert you to this)

Installing the Toy model

The WDK release includes a Toy Site. You will need to install and p
lay with it before
you are ready to build your own site. The Toy Site has a model and a view (just like
yours will). We discuss the model first.

After you have installed the WDK into $GUS_HOME, there are three additional steps to
installing the Toy model.
You must configure the model, create a query cache and create
the toy database.

Understanding the cache

Before going on to configure the model and then create the query cache, it will help if
you understand the purpose of the cache.

The WDK model stores qu
ery results in a "cache." The cache is in your database. (In the
section
#Configuring the model

you will configure the model to tell it where to create the
cach
e tables.) The main table is called "QueryInstance" by default (though you can name
it whatever you want). Each row in that table represents the running of a query. The row
stores the name of the query and the parameter values it was run with. It also stor
es the
name of a result table that holds the actual result. If the same query is requested again
with the exact same parameter values (regardless of which user requests it), the result is
fetched from the cache, avoiding the expense of running the query al
l over again.

When you define your model (see
#The Model XML File
), you will designate which
queries to cache and not to cache, based on your expectations of yo
ur system's use. By
default, queries that are used in Questions are cached, and you can turn that off by setting
the isCacheable attribute to false. Queries that are used in Records are not cached.

NOTE:

Whenever you change the definition in your model of
a cached query then
you
must reset the cache (see
#Creating and managing the cache
)
.

Configuring the Toy model

To configure the Toy model, you m
ust edit its configuration file:

copy toyModel
-
config.xml.sample from
$PROJECT_HOME/WDKToySite/Model/config into
$GUS_HOME/config/toyModel
-
config.xml

$GUS_HOME/config/toyModel
-
config.xml

NOTE
: some of the properties you set control the database connection
pooling in the
WDK. The WDK is delivered with the
Jakarta

Commons DBCP

connection pooler.

The properties you set in the file are:

login

your login for the database

password

your password for the data
base

connectionUrl

the information describing how to connect to your database

webServiceUrl

the url where a web service is running. You only need to config this if you want to take advantage of the process query (eg
BLAST) facility of WDK.

queryInsta
nceTa
ble

the name of the table that the cache system should use to store information about queries that have been run

maxQueryParam
s

the maximum number of parameters that a query is allowed to have. This controls the number of columns created in the cach
e's
queryInstanceTable. The table has columns to hold parameter values with names param1, param2, etc. If you chose 20 (suggested
)
the table will be able to hold 20 parameter values per query (which is probably more than enough). This means that you may no
t
define any queries in your model that have greater than 20 parameters. (see
#The Model XML File
).

platformClass

a Java class which provides RDBMS
-
specific f
unctionality. The WDK comes with these classes:

Oracle

org.gusdb.wdk.model.implementation.Oracle

PostgreSQL

org.gusdb.wdk.model.implementation.PostgreSQL

MySQL

not yet

initialSize

connection pool: the number of connections that are created on start
up.

maxActive

connection pool: the maximum number of active connections that can be allocated from this pool at the same time, or zero for
no
limit.

maxIdle

connection pool: the maximum number of active connections that can remain idle in the pool, wit
hout extra ones being released, or
zero for no limit.

minIdle

connection pool: the minimum number of active connections that can remain idle in the pool, without extra ones being created,

or
zero to create none.

maxWait

connection pool: the maximum num
ber of milliseconds that the pool will wait (when there are no available connections) for a
connection to be returned before throwing an exception, or
-
1 to wait indefinitely.

Creating and managing the cache

Even I give different value for
queryInstanceT
able property, the table generated in
database is still QueryInstance. This is a bug.

After you have edited the model config file, create an empty cache by using the
wdkCache command.

Here is its usage:

% wdkCache


usage: wdkCache
-
model model_name
-
new|
-
r
eset|
-
drop


Create, reset or drop a query cache. The name of the cache
table is found

in the Model config file (the table is placed in the schema
owned by login).

Resetting the cache drops all results tables and deletes
all rows from the

cache table. Drop
ping the cache first resets it then drops
the cache table

and sequence.

Options:


-
model <model> the name of the model. This is
used to find the Model config file ($GUS_HOME/config/model
-
name
-
config.xml)


-
drop drop the qu
ery cache


-
new create a new query cache


-
reset reset the query cache

To set up the Toy model's cache use this command:

% wdkCache
-
model toyModel
-
new

Setting up the toy database


 

The WDK release includes a toy
database. It is packaged
in a set of files in $GUS_HOME/data/WDK/ToyModel/testTables. The model regression
test makes use of the toy database (as does the toy website). When you run the regression
test it optionally creates the toy database in your RDBMS,
moving the data from the files
into tables. If you want to manage the toy database yourself, use the wdkTestDb
command:

copy testTables from $PROJECT_HOME/WDKToySite/Model/data into
$GUS_HOME/data/WDK/Model/testTables


% wdkTestDb


Create a toy database to

use in testing the WDK. (The
database is created from files included in the WDK
distribution.)


usage: wdkTestDb
-
model model_name [
-
create |
-
drop]


Options:

-
model <model> The name of the model. This is used
to find the Model config file ($GUS
_HOME/config/model_name
-
config.xml)

Use this command to create the toy database:

% wdkTestDb
-
model toyModel
-
create


Running the toy Model sanity test

The toy Model has a companion set of sanity test. Running it is a good way to exercise
the WDK code inst
alled.

usage: wdkSanityTest
-
model model_name
-
verbose


Run a test on all queries and records in a wdk model, using
a provided sanity model, to ensure that the course of
development hasn't dramatically affected wdk functionality.

Options:


-
model <model>

the name of the model. This is used to
find the Model XML file ($GUS_HOME/config/model_name.xml),
the Model property file
($GUS_HOME/config/model_name.prop), the Sanity Test file
($GUS_HOME/config/model_name
-
sanity.xml) and the Model
config file ($GUS_
HOME/config/model_name
-
config.xml)


-
verbose Print out more information while running
test.

Use this command to test the toy model:

% wdkSanityTest
-
model toyModel

Running the toy Model regression test


 

The regression test runs a set of wdk
comman
ds, and compares the results to a previously run, manually
-
validated expected
result. If the output matches, the test passes, otherwise it fails. The test ensures that
expected behavior of the codebase remains consistent even when behind
-
the
-
scenes
changes

are made. The WDK release provides a standard regression test to use with the
toy model; if this test fails when run after installing the toy model, something is seriously
wrong. The test can be found at


copy regressionTest from $PROJECT_HOME/WDKToySite/Model/data into
$GUS_HOME/data/WDK/Model/regressionTest

$GUS_HOME/data/WDKToySite/Model/regressionTest/sampleRegres
sionTestCommands


The test uses data in the toy database. Set the
--
commandListFile flag
to point to this
file when running the wdkRegressionTest command:


usage: Runs wdk executables from provided file and
compares output to an expected result for testing purposes


wdkRegressionTest


--
configFile (database configuration file to use
w
ith wdk model)


--
loadNewDatabase! (flag to create database from
provided test flat files; set this flag


when running the regression test for the first
time and when data in the files have changed)


--
createNewExpectedResult! (overw
rite existing
regression test expected result)


--
outputDirectory (all results of test including
error files will be placed in this directory)


--
commandListFile (file that contains lists of
commands to run in test)


--
verbose (prints
out names of shell commands being
executed)


 

In typical usage, you should run the regression test provided with the WDK release. If
you find a reason to create your own regression test, then create a separate command list
file. The command list file inclu
des one or more tests. Each test is composed of three
lines, and the next test, if any, follows beginning on the fourth line. The expected input
for a test is as follows:


name="[name of test]"

command="[command to run with parameters conforming to the
no
rmal usage of the command, EXCEPT any global parameters (configFile) passed to the
wdkRegressionTest commmand]"

critical="[true or false; if true, the regression test will
immediately exit on failure, without running any more of the provided tests]"


Insta
lling the Toy View

Configuring Tomcat

The WDK uses a slightly unconventional installation strategy. It installs a complete and
working GUS_HOME in the same file system as the web application directory, and uses
symbolic links to link into it from the web a
pplication directory. The reason is that this
provides a working GUS_HOME so that you can test your model using the extensive
command line tools available for the model. Because it is linked in, you know for sure
that the model you are testing is the same
model that is running on your site.

The complication with this strategy is that it requires you to configure Tomcat to allow
symlinks. This is not a default configuration because Tomcat feels that it may open a
security issue. We believe that as long as no
body on your team makes symlinks to bad
places, this is not a security problem. However, if you do not want to use links, then
replace them with direct copies.

The above two paragraph is not clear. it can merge into one paragraph and take out the
sentences

which describe reason of using the symbolic link.

It will be great to give out an example of symbolic link in web server directory structure.
Such as:

1.) create webapps directory under $GUS_HOME

2.) create WEB_INF under $GUS_HOME/webapps

3.) in $TOMCAT_
HOME/webapps, create a link which links to $GUS_HOME/webapps

To configure Tomcat to allow symlinks


do not use symlinks that are cross file system boundaries


you may not use Tomcat's optional security mode


in Tomcat's $TOMCAT_HOME/conf/server.xml file, the
<Context path=/> directive
for the web application must have allowLinking="true" like this (substituting
values specific to your site):

<host ...>

<Context path="/wdktoysite"


docBase="/www/wdktoysite/webapp"


debug="1"


privi
leged="false" allowLinking="true" >


<Logger
className="org.apache.catalina.logger.~FileLogger"


prefix="wdktoysite
-
log."


suffix=".txt"


timestamp="true"


docBase="/www/wdktoysite/logs/" />

</Context>


The above

example can be modified with the example I gave
above. Such as path=/gushome docBase="$TOMCAT_HOME/webapps,
and such


Building the WDK on your site

Here are the steps required


if you do not already have a GUS_HOME in the same file system as your web
appli
cation directory, create an empty directory named, say, gushome.


set the GUS_HOME environment variable to that directory


set up a "webapp" directory for your web application where tomcat will find it. You
must also create a WEB
-
INF directory within your we
bapp directory.


create a property file your_web_prop_file with the following information

webappTargetDir=your_webapp_directory

The above is better to give an example. Such as create
WDKToy.propery file under
$GUS_HOME/webapps/WEB_INF with the
above line in

the file.


run the build command

build WDKToySite webinstall
-
append
-
webPropFile
your_web_prop_file

cd your_webapp_directory

$ ls

error.jsp images/ misc/ questionSets.jsp
summary.jsp

error.user.jsp index.jsp question.jsp record.jsp

WEB
-
INF/


if you haven't already done so, copy your oracle JDBC .jar file into
$GUS_HOME/lib/java/db_driver


copy the oracle or postgres JDBC driver file (depends on which on you use) to your
$TOMCAT_HOME/common/lib if it does not already contain the dr
iver file

Testing the toy website

The WDK is now installed on your site. Bring up the toy WDK site to test it.

Here are the steps


if you haven't already done so, edit $GUS_HOME/config/toyModelConfig.xml to
reflect your site.



The config file name should be

toyModel
-
config.xml.


set up the header and footer files and the web.xml file

cd your_webapp_directory

cd WEB
-
INF

cp web.xml.toy web.xml

cd tags/site

cp footer.tag.toy footer.tag

cp header.tag.toy header.tag


edit your_webapp_directory/WEB
-
INF/web.xml to pr
ovide a correct logging directory


work with your system administrator to start up the application in Tomcat