ki-OpenRequest-Manual.doc - Developer - Knowledge Integration

completemiscreantData Management

Nov 28, 2012 (4 years and 8 months ago)

225 views







Open Request Installation Guide

Applies to OpenRequest 1.0 beta 1























Version 0.9

Released 18/10/2002

Ian Ibbotson

Knowledge Integration Ltd.


Table of Contents
OPEN REQUEST INST
ALLATION GUIDE

................................
................................
.................

1

A
PPLIES TO
O
PEN
R
EQUEST
1.0

BETA
1

................................
................................
.............................

1

2

INTRODUCTION

................................
................................
................................
......................

3

3

INSTALLATION

................................
................................
................................
.......................

3

3.1

S
ET
-
U
P

................................
................................
................................
................................
..

3

3.1.1

PostgreSQL

................................
................................
................................
..................

3

3.1.2

Sybase
................................
................................
................................
...........................

3

3.2

C
REATING THE DATABASE

SCHEMA

................................
................................
......................

4

3.3

P
OPULATING REFERENCE
DATA AND EXAMPLE LOC
ATIONS

................................
...................

4

4

IN THE ETC DIRECTORY

RUN THE COMMAND

................................
...........................

4

5

TESTING

................................
................................
................................
................................
....

4

5.1

C
HECKING OUT THE DATA
BASE

................................
................................
.............................

4

6

SELECT * FROM LOCATI
ONSYMBOL

................................
................................
.............

4

6.1

C
HECKING OUT THE SERV
ICES

................................
................................
...............................

5

6.2

S
ENDING
M
ESSAGES

................................
................................
................................
.............

6

6.2.1

Creating a first request

................................
................................
................................

6

6.2.2

Sending a Shipped message as Responder

................................
................................
...

6

6.2.3

Sending a Received message

................................
................................
........................

7



2

Introduction

3

Installation

The OpenRequest ILL Management Engine makes extensive use of relational database
technology to store details of requests both made and sent by individual locations. I
n order to
provide the most simple API for database objects extensive use of the Hibernate library is made.
Hibernate abstracts out many of the vendor specific features of relational databases and will
produce SQL according to the correct “Dialect” of data
base. The cost of this flexibility is a little
extra configuration at installation time.

3.1

Set
-
Up

There are three files which must be adapted depending upon the database dialect:



hibernate.properties : This file is a bootstrap file and used by the schema gen
eration tool



hibernate.cfg.xml

: This file is used to configure the session factory made available to all
application components. It controls all runtime aspects of database connection management.



OpenRequest.xml :
This is the actual file that defines the mapping between our java classes
and the structure of the database. Because some database features are not only semantically
different, but structurally different (IE, Sequence numbers vs Identity columns) we need t
o
provide two different versions of this file: One which uses Sequence numbers and one which
uses Identity columns.

3.1.1

PostgreSQL

OpenRequest was initially developed against PostgreSQL. To use PostgreSQL follow the
following steps:



Change directory to etc und
er the OpenRequest directory



copy
hibernate.properties.postgres

to hibernate.properties



Edit hibernate.properties for your local environment


copy
hibernat
e.cfg.xml.postgres

to
hibernate.cfg.xml



Edit
hibernate.cfg.xml

for your local environment



Ensure that Postgres is set up to accept internet connections (
-
i flag)



3.1.2

Sybase



Ch
ange directory to etc under the OpenRequest directory



copy
hibernate.properties.sybase

to hibernate.properties



Edit hibernate.properties for your local environment


copy
hibernate.cfg.xml.sybase

to
hibernate.cfg.xml



Edit
hibernate.cfg.xml

for your local environment



3.2

Creating the database schema

In the etc directory edit run the command

./gen.sh

This will populate your database schema.

3.3

Populatin
g reference data and example locations


4

In the etc directory run the command

./setup.sh

This will fill your database with reference data needed for general operation and to perfrom the
initial tests.

5

Testing

5.1

Checking out the database

Start up your database

client using the connection parameters supplied to the previous scripts.

Run the following queries and observe the output:

Select * from location;

This query list all canonical locations known to the system. There will normally be one Location
record for
each Institution known to a system.

Should return the following data:


defaultsymbol | name | type | id

------------------
+
------------------------------------------
+
------
+
----


k
-
int:TCPTEST | K
-
Int, Sheffield Si
cence and Tech. Parks | 11 | 10


fantasy:hogwarts | Hogwarts Library | 11 | 11


fantasy:unseen | The Unseen University Library | 11 | 12


KI:REQ | REQ | 13 | 13


KI
:RESP | RESP | 13 | 14


tlc:TCPTESTING | TLC Test Simplex server | 11 | 15


tlc:ILLTESTING | TLC Test Mime server | 11 | 16



Select * from LocationSymbol


This que
ry lists all the alises known for a particular location (The foreign key canonical_location
links back to the location table).

serviceforthissymbol | symbol | authority | canonical_location | id

----------------------
+
-----------------------------------------------
+
-----------
+
--------------------
+
----


10 | uid=TestServer, o=Knowledge Integration, c=GB | 43 | 10 | 10


10 | TCPTEST

| 45 | 10 | 11


10 | uid=TestServer, o=Hogwarts, c=GB | 43 | 11 | 12


10 | hogwarts | 44 | 1
1 | 13


10 | uid=TestServer, o=The Unseen University, c=DW | 43 | 12 | 14


10 | unseen | 44 | 12 | 15


13 | TCPTESTIN
G | 40 | 15 | 16


14 | ILLTESTING | 40 | 16 | 17


10 | REQ |

45 | 13 | 18


10 | RESP | 45 | 14 | 20



There are a number of other tables that should be investigated...

<<insert data model diagram here>>

5.2

Checking o
ut the services


Open request uses a number of core services to implement message passing and administration
of the ILL system. The design has followed the directions laid down in ISO
-
10161 as closely as
we found possible. There are currently three core pr
ocesses:



The OpenRequest server : This server deals with all message passing and utility functions
that help create request messages. The messaging object deals with routing requests to the
correct message handling agent (E.G. The Loopback handler, the TCP
Hander or the
MimeHandler) and invokes the appropriate handlers on recipit of incoming protocol
messages.



The Loopback server : Because OpenRequest is capable of providing request management
services to a consortial system (IE where many requesting organis
ations share the same
request management system) identifiying the sender and recipient of certain ILL messages
can be difficult without use of the ILL_APDU_Delivery_Info extension. Although
OpenRequest implements this extension, the loopback server negates

the need for this by
directly passing messages from one internal location to another.



The TCP server : Is responsible for passing messages to remote ILL systems using
connection oriented TCP.

In order to test message passing, it is necessary to start thes
e services. The default OpenRequest
system uses Java RMI to locate these services (Corba adapters will follow soon) and hence, it is
essential that the Java RMI server is started with access to all the relevant classes. The script
start_rmi_server.sh in th
e etc directory ensures that RMI is correctly started for OpenRequest. To
start the services, take the following steps in the etc directory:



run ./start_rmi_server



run ./start_OR_server.sh



run ./start_loopback_server.sh



Optionally run ./start_ill_tcp_serve
r.sh to start the ILL delivery module.

5.3

Sending Messages

5.3.1

Creating a first request

At this stage, it’s worth starting a database session again to check the progress of your requests
in the database.

The following SQL will list all transactions in your datab
ase and their current status:

select request_id as id, location as loc , initialrequestersymbol as req, tgq, tq, role,
transactiongroup as tg, code from ill_transaction, status_code where
requeststatuscode=status_code.id;

Initially, this should result in n
o rows.

In the etc directory run the command
./test_send_request.sh

This script invokes a test case which
creates a request being sent from the location KI:REQ to the location KI:RESP for the book
“Brain of the firm” by author “Beer, Stafford”. After runni
ng this command, our handy SQL
fragment above returns

id | loc | req | tgq | tq | role | tg | code

---
+
-----
+
--------
+
----------------------
+
----------------------
+
------
+
----
+
------------

10 | 13 | KI:REQ | OR:678
25227269996544 | OR:67825227270127617 | REQ | 10 | PENDING

11 | 14 | KI:REQ | OR:67825227269996544 | OR:67825227270127617 | RESP | 11 | IN
-
PROCESS

Here we can see the two new requests (Since both locations are internal to the OpenRequests
system. If the
responder was an external one, only the requester details would be present). The
rquests have been allocated the internal ID 10 and 11 for the Requester (KI
-
REQ) and Responder
(KI
-
RESP) parties. We can see that the requester is the same for both records a
nd that the group
transaction qualifier and transaction qualifier are the same. Because OpenRequest
only

updates the
state model when the programmer asks the ASE to send a message, we generate transaction and
transaction group id’s using a unique key gener
ator seperate from the underlying database system.
This means requests can be created and abandoned with no database state change.

OK, that’s our first ILL request created. You can look at the actual details of the request in the
request_message, iso_reque
st_message_details and generic_request_details tables. To list the title
of the book for request 11, use the following SQL:

Select title, author from generic_request_details where id = 11;

5.3.2

Sending a Shipped message as Responder

The test_send_shipped.sh scr
ipt invokes a test case for sending a shipped message for a specified
transaction. In order to send the shipped message from our imaginary responder back to the inital
requester, invoke the test_send_shipped.sh script with the single parameter 11 (the int
ernal
transaction id of the responder transaction).
./test_send_shipped.sh

11

This should produce the
following database state:

id | loc | req | tgq | tq | role | tg | code

---
+
-----
+
--------
+
----------------------
+
--
--------------------
+
------
+
----
+
---------

10 | 13 | KI:REQ | OR:67825227269996544 | OR:67825227270127617 | REQ | 10 | SHIPPED

11 | 14 | KI:REQ | OR:67825227269996544 | OR:67825227270127617 | RESP | 11 | SHIPPED

(2
rows)



5.3.3

Sending a Received message

The l
ast step in test case 100 is for the requester to issue a received message. The
test_send_received.sh script takes a single parameter, the ID of the transaction for which the
message is required.

./test_send_received.sh 10

id | loc | req | tgq

| tq | role | tg | code

---
+
-----
+
--------
+
----------------------
+
----------------------
+
------
+
----
+
----------

11 | 14 | KI:REQ | OR:67825227269996544 | OR:67825227270127617 | RESP | 11 | SHIPPED

10 | 13 | KI:REQ | OR:6782522
7269996544 | OR:67825227270127617 | REQ | 10 | RECEIVED

(2
rows)



5.4

Request Messages

The request message table is used to track individual ILL messages sent back and forth. The
following query will list all messages for a given transaction:

select str_service
_date, str_service_time, iso_message_type from request_message where
parentrequest = 10;



str_service_date | str_service_time | iso_message_type

------------------
+
------------------
+
------------------


181002 | 0947 | ISOREQUEST


18
1002 | 1009 | ISOSHIPPED


181002 | 1021 | ISOREC

(3 rows)