Permalink
Browse files

add documetations

  • Loading branch information...
1 parent 6e26443 commit 9fcdc556c39509c081317abe4433e3cb962f4c51 @kaven276 committed Mar 22, 2012
Showing with 486 additions and 0 deletions.
  1. +223 −0 doc/coding_guide.md
  2. +83 −0 doc/deployment.md
  3. +82 −0 doc/history/history.md
  4. +95 −0 doc/introduction.md
  5. +3 −0 lib/readme.md
View
@@ -0,0 +1,223 @@
+<link type="text/css" rel="stylesheet" href="doc.css" />
+
+<div id="title"> PSP.WEB Coding Guide </div>
+
+Basic PL/SQL programming
+==============
+
+features that save the amount of code
+--------------
+
+### use of table%rowtype
+
+
+ Using table%rowtype will eliminate most of the data-structure matching variable declarations, it greatly ease your development than other web development language.
+
+ procedure a
+ is
+ v table1%rowtype;
+ u table2%rowtype;
+ w table3%rowtype;
+ -- normally 3 rowtype variables is enough
+ begin
+ v.col1 := xxx;
+ u.col2 := xxx;
+ insert into table1 values v;
+ update table2 a set row = u where a.col2 = u.col2;
+ w.col1 := v.col1;
+ w.col2 := u.col2;
+ end;
+
+ declaration
+ sql binding
+
+### use tmp.xxx to save variable declaration
+
+ Using tmp.xxx, you don't need to declare your own local variables for temporary work, such save declaration lines, If you need to a variable to hold the temporary result or staging info, using tmp.xxx is very handy.
+
+ select count(*) into tmp.cnt from table;
+ tmp.s := 'This is ';
+ tmp.s := tmp.s || ' a exmample';
+ p.p(tmp.s);
+ tmp.i = 0;
+ loop
+ tmp.i := tmp.i + 1;
+ exit when ???
+ ...
+ end loop;
+ tmp.st := st(1,2,3);
+ p.ps(tmp.s, tmp.st);
+
+
+advanced sql parameter binding
+-------------------
+
+ Using PL/SQL, you can embed advanced sql that is far more powerful and convenience than any of the API-based, embed sql or OR-Mapping ways that J2EE, .NET, PHP, Ruby use.
+
+### use returning in sql
+
+ Only in PL/SQL, You can use returning in sql, so you can save a select sql when executing DML.
+
+ update table a set a.col1 = ... where ... returning a.col2 into tmp.s;
+
+### bulk sql
+
+ Normal, you use loop cursor to process data, but you can use bulk sql to do DML more efficiently.
+
+ select bulk collect into tmp.st from table a where ...;
+
+### package cursor
+
+ Package cursor can take parameters
+
+ create or replace package test is
+
+ cursor object is
+ select * from user_objects a;
+
+ cursor object_by_type(p_type varchar2) is
+ select * from user_objects a where a.object_type = p_type;
+
+ end test;
+
+other advanced sql that can have better performance and avoid your otherwise complex code
+---------
+
+### set sql : union, union all, minus, intersect
+
+### hierachical sql
+
+### stats sql
+
+### analytical sql
+
+### sample data sql
+
+
+common sql writing skill
+---------------
+
+### Existence Check
+
+ If we scan all rows for existence check, we do waste computing resource, we can break if we meet the first matching row, there are two ways for that, see below:
+
+ select count(*) into tmp.cnt from table a where a.xxx='???' and rownum=1;
+ if tmp.cnt=0 then
+ -- none exist
+ else
+ -- exist
+ end if;
+
+ or
+
+ for i in (select /*+ first_rows */ from table a where a.xxx='???') loop
+ -- exist
+ exit; -- quit loop
+ end loop;
+
+ If we want a matching row together, see below:
+
+ begin
+ select a.* into v_row_type_val from table a where a.xxx = '???' and rownum = 1;
+ -- exist
+ exception
+ when no_data_found then
+ -- none exist
+ end;
+
+Naming convention
+==============
+
+### unit(package or standalone procedure) suffix naming convention (_b, _c, _h, _e)
+
+* _b is for unit that is read only and generating http result page
+* _c is for unit that do data process according to http request info, and guide user to feedback page or next page
+* _h is for unit that accept ajax http requests
+* _e is for internal(not accessible from url) data manipulation
+
+### specialized package (pv, rcpv, rc)
+
+ Use package pv (or some other short name) to hold package variables.
+
+ Use package rcv to hold any result-cached table rows for the current request
+
+ Use package rc for populating rcv data
+
+### local variable (v,u,w, v_xxx)
+
+* v,u,w for %rowtype
+* v_xxx for other local variables
+
+### package variable (gv_xxx)
+
+ PSP.WEB doesn't recommand use of package variables with package body or package code, if you need package variables, do define them in dedicated package specification that do not have a package body. But if you do want it, name it gv_xxx, gv stand for global varaible.
+
+### parameter (p_xxx)
+
+ All DHC layer unit will not have any parameter, then get the http request into through API r, but entity layer unit do have parameters, because entity layer unit will including lot of sql text that will use the parameter as bind variable, to avoid the naming conflicts of table's column names and procedure parameters, PSP.WEB recommand using p_xxx to name parameters, prefix *p_* stand for parameter
+
+layers of code
+==============
+ 1. compare to J2EE
+
+
+basic web developing
+==============
+
+basic output using h.xxx API
+--------------
+
+
+basic html printing by p.xxx API
+--------------
+
+get request info by r.xxx API
+--------------
+
+### get basic request line info
+
+### get form submit info
+
+ Html form can submit using get or post methods, PSP.WEB can accept them both.
+
+### get the cookie info
+
+### get http request header line info
+
+advanced topics
+==============
+
+http header control with h.xxx API
+--------------
+
+### specify response page's charset
+
+### streaming of response
+
+### control caching
+
+### specify response page as other mime-type of doc-type
+
+### take response as file download
+
+### cookie
+
+### ensure response entity's integrity with content-md5
+
+### control request method match the requested PL/SQL unit
+
+how to write URL
+--------------
+
+advanced p.xxx APIs
+--------------
+
+### bulk binding
+
+### extension APIs
+
+### component css
+
+### scalable css
+
+
View
@@ -0,0 +1,83 @@
+<link type="text/css" rel="stylesheet" href="doc.css" />
+
+<div id="title"> Deployment & Configuration & Administration of PSP.WEB </div>
+
+Install at oracle's side
+===
+
+## Install PSP.WEB engine schema objects and demo schema objects.
+
+ Change working directory into oracle, use sqlplus to login into the target oracle database as sysdba, then execute install.sql script file. Example like this:
+
+ sqlplus "sys/password@targetdb as sysdba"
+ SQL> @install
+
+ Note that the psp user and demo user should be created beforehand, then you will be prompted to specify the names of the two database users.
+
+## Configure oracle to nodeJS TCP/IP connection
+
+ Oracle DB is able to make TCP/IP connection to outside world by `UTL_TCP` pl/sql API, but by default, oracle forbit network ACL to make connection to any address, you must use `DBMS_NETWORK_ACL_ADMIN` package to create a new ACL to allow access to nodeJS listener. NodeJS http server will manage all the connections made by oracle, and use them as communication path for the http gateway behavior.The configuration script is as the following code:
+
+ exec dbms_network_acl_admin.create_acl('pwgw.xml','oracle2nodejs',principal => 'PSP',is_grant => true,privilege=> 'connect');
+ -- dbms_network_acl_admin.add_privilege('pwgw.xml',principal => 'PSP2',is_grant => true,privilege => 'connect')
+ exec dbms_network_acl_admin.assign_acl(acl => 'pwgw.xml', host => '192.168.177.1')
+ commit;
+
+ -- The "principal" parameter in "dbms_network_acl_admin.create_acl" must specify the schema that hold the PSP.WEB engine software, it's case sensitive. use "dbms_network_acl_admin.add_privilege" to grant right to other db user that act as PSP.WEB engine user.
+ -- The "host" parameter in "dbms_network_acl_admin.assign_acl" must specify where the nodeJS http gateway is for dns/hostname or ip address.
+
+## Configure core parameter for server_config_t table
+
+ Upon completion of installation, The SERVER_CONTROL_T table is configured by the following insert statement
+
+ insert into SERVER_CONTROL_T (GW_HOST, GW_PORT, MIN_SERVERS, MAX_SERVERS, MAX_REQUESTS, MAX_LIFETIME, STATIC_URL)
+ values ('127.0.0.1', 1522, 6, 12, 1000, '+0001 00:00:30','http://127.0.0.1:81');
+
+ To let PSP.WEB known where the nodeJS http gateway is, You must specify `GW_HOST and GW_PORT columns for SERVER_CONTROL_T`. The nodeJS http server as PL/SQL gateway is listening for oracle connection at tcp address of `GW_HOST:GW_PORT`.
+
+
+## Make sure there is enough processes/sessions and background job process for PSP.WEB service.
+
+ The value `in SERVER_CONTROL_T.MIN_SERVERS` control how many server processes PSP.WEB use to service the client(through nodeJS gateway), but PSP.WEB server process is just oracle's background processes, the actual number of them is controled under the following oracle init parameters, so ensure it's set big enough to run the amount of PSP.WEB server processes required.
+
+ * JOB_QUEUE_PROCESSES
+ specifies the maximum number of processes that can be created for the execution of jobs. It specifies the number of job queue processes per instance (J000, ... J999).
+ * PROCESSES
+ specifies the maximum number of operating system user processes that can simultaneously connect to Oracle. Its value should allow for all background processes such as locks, job queue processes, and parallel execution processes.
+ * SESSIONS
+ specifies the maximum number of database sessions that can be created in the system. Because every login requires a session, this parameter effectively determines the maximum number of concurrent users in the system.
+
+ To know the current value of the parameters above, use "show parameters {parameter-name}"
+
+ To change the setting., use "alter system set {parameter-name}={value}"
+
+
+
+## Start and Stop PSP.WEB server on oracle side
+
+ PSP.WEB server is run as scheduler managed background job processes, They run as the PSP.WEB engine software database user, normally is "PSP". PSP.WEB provide `K_PMON` package to manager the server.
+
+ K_PMON.RUN_JOB : It will run PSP.WEB's pmon as repeating BG job and start all the parallel server job processes
+ K_PMON.STOP : It will send signal to PSP.WEB'S pmon and server processes, and then they will quit
+
+ To start/stop PSP.WEB server, just login as PSP.WEB engine user (normally "PSP") in sqlplus, and execute `k_pmon.run_job and k_pmon.stop`.
+
+
+## Configure for the demo
+
+ insert into ext_url_v(key, prefix) values('myself', 'http://localhost:81/');
+ where the url prefix should specify the static server address, so the demo of URL will function
+
+
+Install at nodeJS's side
+===
+
+## Install nodeJS and npm
+
+## Install static server nodeJS package
+
+ For advanced static server, it can provide services to PSP.WEB's documentation by converting .md files to .html files.
+
+## Start and Stop node gateway server
+
+ node lib/plsql_gateway.js will start the server
@@ -0,0 +1,82 @@
+<link type="text/css" rel="stylesheet" href="../doc.css" />
+
+<div id="title"> PSP.WEB History Breaf </div>
+
+# PSP.WEB v0 ( Original Oracle PSP )
+
+ Oracle support mod_plsql apache module in Companion CD for 10G and Web Tier for 11G. The oracle's PSP has many shortcuts, including:
+
+* The HTP and HTF API is not natural and hard to use
+* Can not provide exactly every http request header info
+* Can not provide http request body info
+* Front-end web server can not support well for keep-alive requests
+* Configuration Apache is a burdden
+* Configuration one dad for one database user or application
+* Do not support streaming of http response
+
+
+# PSP.WEB v1 (2006)
+
+## support another page writing,
+
+* use `p.tag, p.tag_open, p.tag_close` series API
+* support procedure and function version of the same API, function version just return the string of output but do not print to the http output
+* support bulk API such as `p.ths, p.tds, p.options, p.input_checkboxes ...`
+* provide UI HTC js component for tab-page, tree, menu, folder, pop-up input, form check ...
+
+
+## PSP.WEB v2
+
+ This version is toward a enterprise cluster server with high security level.
+
+* Native SSO support, across multiple apache and multiple oracle.
+* support layers control, including Boundary(print page),Control(process data),Hidden(for ajax...),Entity layers(for data DML)
+* Native authentication mechanism support additional check such as SMS, support more security
+* Can balance among the apache servers
+* provide configuration of page group, role, right, menu, page parameter
+
+# PSP.WEB v3
+
+## use blob for every response produced by PSP.WEB
+
+* Support set http header after http body has ready write something
+* Allow for gzip compression
+* Allow for md5 digest computation
+
+## support filter mechanism
+
+ You can code `k_gw.cancel_page` to
+
+# PSP.WEB v4 (2011)
+
+## Unified DAD
+
+* transfer gateway logic from modplsql into internal pl/sql servlet/k_gw
+* k_gw can switch to the target db user's identity and privilege
+
+## Simplified and unified url reference
+
+ can move all static files into any server that can be any server(apache/node/...)
+
+## Unified request info package R
+
+ R has http headers, cookies, parameters, url parts all in it
+
+# PSP.WEB v5 (current) concentrate on fundamental function
+
+ The new version 5 PSP.WEB is based on nodeJS http gateway, it's no longer based on Apache's mod_plsql module.
+
+ A nodeJS http gateway will accept all http request from clients, parse the request and send them to oracle. Oracle use `UTL_TCP` to establish TCP connections to nodeJS gateway, so oracle can accept all parsed http request info and print back the http response to nodeJS gateway. The NodeJS gateway is to act as the front-end http server to listen and keep-alive http connection, the main work is done at ORACLE's side by PL/SQL.
+
+ This version of PSP.WEB will provide full http protocol support, http request line, header lines, form-sumit info, file-upload, entity body info can all be got with API R, and response can be full control, you can stream output, gzip, computed etag and content-md5, use of last-modified, etag, if-modified-since, if-none-match to generate 304 response, support any charset output, can take varchar2 or nvarchar2 both, support page as file download. It can response with all types of http error status.
+
+ Beside above, This version of PSP.WEB have it's own unique feathers:
+
+* component css (in html head or link to)
+* scalable css
+* post to control lay unit and generate(when process is successful) page as a feedback page to avoid repeating post
+
+ For oracle side's process, you can
+
+* leverage the power of result-cache at row level using versioned result-cache
+* proper use of browser session info to store login user-id, and other info.
Oops, something went wrong.

0 comments on commit 9fcdc55

Please sign in to comment.