Index: openacs-4/packages/acs-core-docs/www/acs-admin.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/acs-admin.html,v
diff -u -r1.7 -r1.7.2.1
--- openacs-4/packages/acs-core-docs/www/acs-admin.html 7 Mar 2002 06:55:36 -0000 1.7
+++ openacs-4/packages/acs-core-docs/www/acs-admin.html 15 May 2002 23:26:18 -0000 1.7.2.1
@@ -1,80 +1,4 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type">
-<title>Part Part II. For OpenACS Admins</title>
-<meta name="generator" content="DocBook XSL Stylesheets V1.45">
-<link rel="home" href="index.html" title="OpenACS Documentation">
-<link rel="up" href="index.html" title="OpenACS Documentation">
-<link rel="previous" href="release-notes.html" title="OpenACS 4.5 Release Notes">
-<link rel="next" href="unix-install.html" title="Chapter 2. Installing on Unix/Linux">
-<link rel="stylesheet" href="openacs.css" type="text/css">
-</head>
-<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-<div class="navheader">
-<a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr>
-<td width="20%" align="left">
-<a accesskey="p" href="release-notes.html">Prev</a> </td>
-<th width="60%" align="center"> </th>
-<td width="20%" align="right"> <a accesskey="n" href="unix-install.html">Next</a>
-</td>
-</tr></table>
-<hr>
-</div>
-<div class="part">
-<div class="titlepage"><div><h1 class="title">
-<a name="acs-admin"></a>For OpenACS Admins</h1></div></div>
-<div class="partintro">
-<div></div>
-<p>Help to the folks keeping an OpenACS installation up and running.</p>
-<div class="toc">
-<p><b>Table of Contents</b></p>
-<dl>
-<dt>2. <a href="unix-install.html">Installing on Unix/Linux</a>
-</dt>
-<dd><dl>
-<dt><a href="install-overview.html">Overview</a></dt>
-<dt><a href="operating-system.html">Install an Operating System</a></dt>
-<dt><a href="oracle.html">Install Oracle 8.1.7</a></dt>
-<dt><a href="postgres.html">Install PostgreSQL 7.1.3</a></dt>
-<dt><a href="aolserver.html">Install AOLserver 3.3+ad13</a></dt>
-<dt><a href="openacs.html">Install OpenACS 4.5</a></dt>
-<dt><a href="nextsteps.html">Next Steps</a></dt>
-<dt><a href="credits.html">Credits</a></dt>
-</dl></dd>
-<dt>3. <a href="win-install.html">Installing on Windows</a>
-</dt>
-<dd><dl>
-<dt><a href="win-overview.html">Overview</a></dt>
-<dt><a href="win2k-installation.html">OpenACS Installation Guide for Windows2000</a></dt>
-</dl></dd>
-</dl>
-</div>
-</div>
-</div>
-<div class="navfooter">
-<hr>
-<table width="100%" summary="Navigation footer">
-<tr>
-<td width="40%" align="left">
-<a accesskey="p" href="release-notes.html">Prev</a> </td>
-<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
-<td width="40%" align="right"> <a accesskey="n" href="unix-install.html">Next</a>
-</td>
-</tr>
-<tr>
-<td width="40%" align="left">OpenACS 4.5 Release Notes </td>
-<td width="20%" align="center"><a accesskey="u" href="index.html">Up</a></td>
-<td width="40%" align="right"> Chapter 2. Installing on Unix/Linux</td>
-</tr>
-</table>
-<hr>
-<address>
- rmello at fslc.usu.edu
- </address>
-<address><a href="mailto:vinod@kurup.com">
+<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"><title>Part Part II. For OpenACS Admins</title><meta name="generator" content="DocBook XSL Stylesheets V1.50.0"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="index.html" title="OpenACS Documentation"><link rel="previous" href="release-notes.html" title="OpenACS 4.5 Release Notes"><link rel="next" href="unix-install.html" title="Chapter 2. Installing on Unix/Linux"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="release-notes.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="unix-install.html">Next</a></td></tr></table><hr></div><div class="part"><div class="titlepage"><div><h1 class="title"><a name="acs-admin"></a>For OpenACS Admins</h1></div></div><div class="partintro"><div></div><p>Help to the folks keeping an OpenACS installation up and running.</p><div class="toc"><p><b>Table of Contents</b></p><dl><dt>2. <a href="unix-install.html">Installing on Unix/Linux</a></dt><dd><dl><dt><a href="install-overview.html">Overview</a></dt><dt><a href="operating-system.html">Install an Operating System</a></dt><dt><a href="oracle.html">Install Oracle 8.1.7</a></dt><dt><a href="postgres.html">Install PostgreSQL 7.1.3</a></dt><dt><a href="aolserver.html">Install AOLserver 3.3+ad13</a></dt><dt><a href="openacs.html">Install OpenACS 4.5</a></dt><dt><a href="nextsteps.html">Next Steps</a></dt><dt><a href="credits.html">Credits</a></dt></dl></dd><dt>3. <a href="win-install.html">Installing on Windows</a></dt><dd><dl><dt><a href="win-overview.html">Overview</a></dt><dt><a href="win2k-installation.html">OpenACS Installation Guide for Windows2000</a></dt></dl></dd></dl></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="release-notes.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="unix-install.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS 4.5 Release Notes </td><td width="20%" align="center"><a accesskey="u" href="index.html">Up</a></td><td width="40%" align="right"> Chapter 2. Installing on Unix/Linux</td></tr></table><hr><address>rmello at fslc.usu.edu</address><address><a href="mailto:vinod@kurup.com">
vinod@kurup.com
- </a></address>
-</div>
-</body>
-</html>
+ </a></address></div></body></html>
Index: openacs-4/packages/acs-core-docs/www/acs-dev.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/Attic/acs-dev.html,v
diff -u -r1.7 -r1.7.2.1
--- openacs-4/packages/acs-core-docs/www/acs-dev.html 7 Mar 2002 06:55:36 -0000 1.7
+++ openacs-4/packages/acs-core-docs/www/acs-dev.html 15 May 2002 23:26:18 -0000 1.7.2.1
@@ -1,118 +1,5 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type">
-<title>Part Part III. For OpenACS Developers</title>
-<meta name="generator" content="DocBook XSL Stylesheets V1.45">
-<link rel="home" href="index.html" title="OpenACS Documentation">
-<link rel="up" href="index.html" title="OpenACS Documentation">
-<link rel="previous" href="win2k-installation.html" title="OpenACS Installation Guide for Windows2000">
-<link rel="next" href="dev-guide.html" title="Chapter 4. OpenACS Developer's Guide">
-<link rel="stylesheet" href="openacs.css" type="text/css">
-</head>
-<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-<div class="navheader">
-<a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr>
-<td width="20%" align="left">
-<a accesskey="p" href="win2k-installation.html">Prev</a> </td>
-<th width="60%" align="center"> </th>
-<td width="20%" align="right"> <a accesskey="n" href="dev-guide.html">Next</a>
-</td>
-</tr></table>
-<hr>
-</div>
-<div class="part">
-<div class="titlepage"><div><h1 class="title">
-<a name="acs-dev"></a>For OpenACS Developers</h1></div></div>
-<div class="partintro">
-<div></div>
-<p>This is the place to look if you want to extend OpenACS and build on top
- of what's already here. Here you can find out about the guts of the system.</p>
-<div class="toc">
-<p><b>Table of Contents</b></p>
-<dl>
-<dt>4. <a href="dev-guide.html">OpenACS Developer's Guide</a>
-</dt>
-<dd><dl>
-<dt><a href="developers-overview.html">Overview</a></dt>
-<dt><a href="objects.html">OpenACS 4.5 Data Models and the Object System</a></dt>
-<dt><a href="packages.html">OpenACS 4.5 Packages</a></dt>
-<dt><a href="request-processor.html">The Request Processor</a></dt>
-<dt><a href="db-api.html">The OpenACS Database Access API</a></dt>
-<dt><a href="templates.html">Using Templates in OpenACS 4.5</a></dt>
-<dt><a href="permissions.html">Groups, Context, Permissions</a></dt>
-<dt><a href="subsites.html">Writing OpenACS 4.5 Application Pages</a></dt>
-</dl></dd>
-<dt>5. <a href="more-developer-info.html">Other Developer Resources</a>
-</dt>
-<dd><dl>
-<dt><a href="other-developer-overview.html">Overview</a></dt>
-<dt><a href="parties.html">Parties in OpenACS 4.5</a></dt>
-<dt><a href="object-identity.html">Object Identity</a></dt>
-<dt><a href="programming-with-aolserver.html">Programming with AOLserver</a></dt>
-</dl></dd>
-<dt>6. <a href="eng-standards.html">Engineering Standards</a>
-</dt>
-<dd><dl>
-<dt><a href="docbook-primer.html">OpenACS Documentation Guide</a></dt>
-<dt><a href="psgml-mode.html">Using PSGML mode in Emacs</a></dt>
-<dt><a href="filename.html">Detailed Design Documentation Template</a></dt>
-<dt><a href="requirements-template.html">System/Application Requirements Template</a></dt>
-<dt><a href="eng-standards-versioning.html">Release Version Numbering</a></dt>
-<dt><a href="eng-standards-constraint-naming.html">Constraint naming standard</a></dt>
-<dt><a href="eng-standards-filenaming.html">ACS File Naming and Formatting Standards</a></dt>
-<dt><a href="eng-standards-plsql.html">PL/SQL Standards</a></dt>
-</dl></dd>
-<dt>7. <a href="kernel-doc.html">Kernel Documentation</a>
-</dt>
-<dd><dl>
-<dt><a href="kernel-overview.html">Overview</a></dt>
-<dt><a href="object-system-requirements.html">OpenACS 4 Object Model Requirements</a></dt>
-<dt><a href="object-system-design.html">OpenACS 4 Object Model Design</a></dt>
-<dt><a href="permissions-requirements.html">OpenACS 4 Permissions Requirements</a></dt>
-<dt><a href="permissions-design.html">OpenACS 4 Permissions Design</a></dt>
-<dt><a href="groups-requirements.html">OpenACS 4 Groups Requirements</a></dt>
-<dt><a href="groups-design.html">OpenACS 4 Groups Design</a></dt>
-<dt><a href="subsites-requirements.html">OpenACS 4 Subsites Requirements</a></dt>
-<dt><a href="subsites-design.html">OpenACS 4 Subsites Design Document</a></dt>
-<dt><a href="apm-requirements.html">OpenACS 4.5 Package Manager Requirements</a></dt>
-<dt><a href="apm-design.html">OpenACS 4.5 Package Manager Design</a></dt>
-<dt><a href="security-requirements.html">OpenACS 4 Security Requirements</a></dt>
-<dt><a href="security-design.html">OpenACS 4 Security Design</a></dt>
-<dt><a href="security-notes.html">OpenACS 4 Security Notes</a></dt>
-<dt><a href="rp-requirements.html">OpenACS 4 Request Processor Requirements</a></dt>
-<dt><a href="rp-design.html">OpenACS 4 Request Processor Design</a></dt>
-<dt><a href="db-api-detailed.html">Database Access API</a></dt>
-<dt><a href="tcl-doc.html">Documenting Tcl Files: Page Contracts and Libraries</a></dt>
-<dt><a href="bootstrap-acs.html">Bootstrapping OpenACS</a></dt>
-</dl></dd>
-</dl>
-</div>
-</div>
-</div>
-<div class="navfooter">
-<hr>
-<table width="100%" summary="Navigation footer">
-<tr>
-<td width="40%" align="left">
-<a accesskey="p" href="win2k-installation.html">Prev</a> </td>
-<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
-<td width="40%" align="right"> <a accesskey="n" href="dev-guide.html">Next</a>
-</td>
-</tr>
-<tr>
-<td width="40%" align="left">OpenACS Installation Guide for Windows2000 </td>
-<td width="20%" align="center"><a accesskey="u" href="index.html">Up</a></td>
-<td width="40%" align="right"> Chapter 4. OpenACS Developer's Guide</td>
-</tr>
-</table>
-<hr>
-<address>
- rmello at fslc.usu.edu
- </address>
-<address><a href="mailto:vinod@kurup.com">
+<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"><title>Part Part III. For OpenACS Developers</title><meta name="generator" content="DocBook XSL Stylesheets V1.50.0"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="index.html" title="OpenACS Documentation"><link rel="previous" href="win2k-installation.html" title="OpenACS Installation Guide for Windows2000"><link rel="next" href="dev-guide.html" title="Chapter 4. OpenACS Developer's Guide"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="win2k-installation.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="dev-guide.html">Next</a></td></tr></table><hr></div><div class="part"><div class="titlepage"><div><h1 class="title"><a name="acs-dev"></a>For OpenACS Developers</h1></div></div><div class="partintro"><div></div><p>This is the place to look if you want to extend OpenACS and build on top
+ of what's already here. Here you can find out about the guts of the system.</p><div class="toc"><p><b>Table of Contents</b></p><dl><dt>4. <a href="dev-guide.html">OpenACS Developer's Guide</a></dt><dd><dl><dt><a href="developers-overview.html">Overview</a></dt><dt><a href="objects.html">OpenACS 4.5 Data Models and the Object System</a></dt><dt><a href="packages.html">OpenACS 4.5 Packages</a></dt><dt><a href="request-processor.html">The Request Processor</a></dt><dt><a href="db-api.html">The OpenACS Database Access API</a></dt><dt><a href="templates.html">Using Templates in OpenACS 4.5</a></dt><dt><a href="permissions.html">Groups, Context, Permissions</a></dt><dt><a href="subsites.html">Writing OpenACS 4.5 Application Pages</a></dt></dl></dd><dt>5. <a href="more-developer-info.html">Other Developer Resources</a></dt><dd><dl><dt><a href="other-developer-overview.html">Overview</a></dt><dt><a href="parties.html">Parties in OpenACS 4.5</a></dt><dt><a href="object-identity.html">Object Identity</a></dt><dt><a href="programming-with-aolserver.html">Programming with AOLserver</a></dt></dl></dd><dt>6. <a href="eng-standards.html">Engineering Standards</a></dt><dd><dl><dt><a href="docbook-primer.html">OpenACS Documentation Guide</a></dt><dt><a href="psgml-mode.html">Using PSGML mode in Emacs</a></dt><dt><a href="filename.html">Detailed Design Documentation Template</a></dt><dt><a href="requirements-template.html">System/Application Requirements Template</a></dt><dt><a href="eng-standards-versioning.html">Release Version Numbering</a></dt><dt><a href="eng-standards-constraint-naming.html">Constraint naming standard</a></dt><dt><a href="eng-standards-filenaming.html">ACS File Naming and Formatting Standards</a></dt><dt><a href="eng-standards-plsql.html">PL/SQL Standards</a></dt></dl></dd><dt>7. <a href="kernel-doc.html">Kernel Documentation</a></dt><dd><dl><dt><a href="kernel-overview.html">Overview</a></dt><dt><a href="object-system-requirements.html">OpenACS 4 Object Model Requirements</a></dt><dt><a href="object-system-design.html">OpenACS 4 Object Model Design</a></dt><dt><a href="permissions-requirements.html">OpenACS 4 Permissions Requirements</a></dt><dt><a href="permissions-design.html">OpenACS 4 Permissions Design</a></dt><dt><a href="groups-requirements.html">OpenACS 4 Groups Requirements</a></dt><dt><a href="groups-design.html">OpenACS 4 Groups Design</a></dt><dt><a href="subsites-requirements.html">OpenACS 4 Subsites Requirements</a></dt><dt><a href="subsites-design.html">OpenACS 4 Subsites Design Document</a></dt><dt><a href="apm-requirements.html">OpenACS 4.5 Package Manager Requirements</a></dt><dt><a href="apm-design.html">OpenACS 4.5 Package Manager Design</a></dt><dt><a href="security-requirements.html">OpenACS 4 Security Requirements</a></dt><dt><a href="security-design.html">OpenACS 4 Security Design</a></dt><dt><a href="security-notes.html">OpenACS 4 Security Notes</a></dt><dt><a href="rp-requirements.html">OpenACS 4 Request Processor Requirements</a></dt><dt><a href="rp-design.html">OpenACS 4 Request Processor Design</a></dt><dt><a href="db-api-detailed.html">Database Access API</a></dt><dt><a href="tcl-doc.html">Documenting Tcl Files: Page Contracts and Libraries</a></dt><dt><a href="bootstrap-acs.html">Bootstrapping OpenACS</a></dt></dl></dd></dl></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="win2k-installation.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="dev-guide.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS Installation Guide for Windows2000 </td><td width="20%" align="center"><a accesskey="u" href="index.html">Up</a></td><td width="40%" align="right"> Chapter 4. OpenACS Developer's Guide</td></tr></table><hr><address>rmello at fslc.usu.edu</address><address><a href="mailto:vinod@kurup.com">
vinod@kurup.com
- </a></address>
-</div>
-</body>
-</html>
+ </a></address></div></body></html>
Index: openacs-4/packages/acs-core-docs/www/aolserver.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/aolserver.html,v
diff -u -r1.7 -r1.7.2.1
--- openacs-4/packages/acs-core-docs/www/aolserver.html 7 Mar 2002 06:55:36 -0000 1.7
+++ openacs-4/packages/acs-core-docs/www/aolserver.html 15 May 2002 23:26:18 -0000 1.7.2.1
@@ -1,110 +1,64 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type">
-<title>Install AOLserver 3.3+ad13</title>
-<meta name="generator" content="DocBook XSL Stylesheets V1.45">
-<link rel="home" href="index.html" title="OpenACS Documentation">
-<link rel="up" href="unix-install.html" title="Chapter 2. Installing on Unix/Linux">
-<link rel="previous" href="postgres.html" title="Install PostgreSQL 7.1.3">
-<link rel="next" href="openacs.html" title="Install OpenACS 4.5">
-<link rel="stylesheet" href="openacs.css" type="text/css">
-</head>
-<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-<div class="navheader">
-<a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr>
-<td width="20%" align="left">
-<a accesskey="p" href="postgres.html">Prev</a> </td>
-<th width="60%" align="center">Chapter 2. Installing on Unix/Linux</th>
-<td width="20%" align="right"> <a accesskey="n" href="openacs.html">Next</a>
-</td>
-</tr></table>
-<hr>
-</div>
-<div class="sect1">
-<div class="titlepage"><div><h2 class="title" style="clear: both">
-<a name="aolserver"></a>Install AOLserver 3.3+ad13</h2></div></div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="install-aolserver-download"></a>Download the Distribution</h3></div></div>
-<p>
+<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"><title>Install AOLserver 3.3+ad13</title><meta name="generator" content="DocBook XSL Stylesheets V1.50.0"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="unix-install.html" title="Chapter 2. Installing on Unix/Linux"><link rel="previous" href="postgres.html" title="Install PostgreSQL 7.1.3"><link rel="next" href="openacs.html" title="Install OpenACS 4.5"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="postgres.html">Prev</a> </td><th width="60%" align="center">Chapter 2. Installing on Unix/Linux</th><td width="20%" align="right"> <a accesskey="n" href="openacs.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="aolserver"></a>Install AOLserver 3.3+ad13</h2></div></div><div class="authorblurb"><p>
+ by <a href="mailto:vinod@kurup.com" target="_top">Vinod Kurup</a><br>
+ OpenACS docs are written by the named authors, but may be edited
+ by OpenACS documentation staff.
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="install-aolserver-download"></a>Download the Distribution</h3></div></div><p>
Mat Kovach is graciously maintaining an AOLServer distribution that
includes all the patches and modules needed to run OpenACS 4.5. These
instructions will describe how to install using his source
distribution. He also has binaries for SuSE 7.3 and OpenBSD 2.8 (and
perhaps more to come), currently located at <a href="http://uptime.openacs.org/aolserver-openacs/" target="_top">uptime.openacs.org</a>.
- </p>
-<p>
+ </p><p>
It's also possible to download all the pieces and patches yourself:
- </p>
-<div class="itemizedlist"><ul>
-<li><p>
+ </p><div class="itemizedlist"><ul type="disc"><li><p>
AOLServer is available at <a href="http://aolserver.com" target="_top">aolserver.com</a>
- </p></li>
-<li><p>
+ </p></li><li><p>
ArsDigita's AOLServer distribution (including
internationalization patches, nscache, nsrewrite, nssha1 and the
oracle driver) is available at <a href="http://www.arsdigita.com/acs-repository/download-verify?version_id=2081" target="_top">arsdigita.com</a>
- </p></li>
-<li><p>
+ </p></li><li><p>
The OpenACS PostgreSQL driver is available from <a href="http://openacs.org/software" target="_top">OpenACS</a>
- </p></li>
-<li><p>
+ </p></li><li><p>
nsxml is available at <a href="http://acs-misc.sourceforge.net/dl/nsxml.tgz" target="_top">http://acs-misc.sourceforge.net</a>.
- </p></li>
-<li><p>
+ </p></li><li><p>
The patch that makes <tt>exec</tt> work
- on BSD is available at <a href="http://sourceforge.net/tracker/index.php?func=detail&aid=415475&group_id=3152&atid=303152" target="_top">sourceforge.net</a>
- </p></li>
-<li><p>
+ on BSD is available at <a href="http://sourceforge.net/tracker/index.php?func=detail%26amp;aid=415475%26amp;group_id=3152%26amp;atid=303152" target="_top">sourceforge.net</a>
+ </p></li><li><p>
The patch that makes <tt>ns_uuencode</tt>
- work for binary files is available at <a href="http://sourceforge.net/tracker/index.php?func=detail&aid=474259&group_id=3152&atid=303152" target="_top">sourceforge.net</a>
- </p></li>
-<li><p>
+ work for binary files is available at <a href="http://sourceforge.net/tracker/index.php?func=detail%26amp;aid=474259%26amp;group_id=3152%26amp;atid=303152" target="_top">sourceforge.net</a>
+ </p></li><li><p>
The patch that makes AOLServer respect the
- <tt>-g</tt> flag is available at <a href="http://sourceforge.net/tracker/index.php?func=detail&aid=509413&group_id=3152&atid=303152" target="_top">sourceforge.net</a>
- </p></li>
-</ul></div>
-<p>
+ <tt>-g</tt> flag is available at <a href="http://sourceforge.net/tracker/index.php?func=detail%26amp;aid=509413%26amp;group_id=3152%26amp;atid=303152" target="_top">sourceforge.net</a>
+ </p></li></ul></div><p>
.... or just Download <a href="http://uptime.openacs.org/aolserver-openacs/aolserver3.3ad13-oacs1-beta-src.tar.gz" target="_top">Mat's
AOLServer distribution</a> to
<tt>/tmp</tt>
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
joeuser:~$ cd /tmp
joeuser:/tmp$ wget -c http://uptime.openacs.org/aolserver-openacs/aolserver3.3ad13-oacs1-beta-src.tar.gz
-joeuser:/tmp$ cd</pre>
-<p>
+joeuser:/tmp$ cd</pre><p>
As <tt>root</tt>, untar
<tt>aolserver3.3ad13-oacs1-beta-src.tar.gz</tt>
into <tt>/usr/local/src</tt>
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
joeuser:~$ su -
Password: **********
root:~$ cd /usr/local/src
-root:/usr/local/src# tar xzf /tmp/aolserver3.3ad13-oacs1-beta-src.tar.gz</pre>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="install-aolserver-user-accounts"></a>Create the nsadmin user</h3></div></div>
-<p>
+root:/usr/local/src# tar xzf /tmp/aolserver3.3ad13-oacs1-beta-src.tar.gz</pre></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="install-aolserver-user-accounts"></a>Create the nsadmin user</h3></div></div><p>
You will need a special user account for running AOLServer. This user
will be called <tt>nsadmin</tt> and belong
top the special group <tt>web</tt>.
<tt>nsadmin</tt>'s home directory will
be <tt>/usr/local/aolserver</tt>.You must
execute these steps as <tt>root</tt>.
- </p>
-<div class="itemizedlist"><ul><li>
-<p>
+ </p><div class="itemizedlist"><ul type="disc"><li><p>
Run these commands:
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
root:/usr/local/src# cd
root:~# groupadd nsadmin
root:~# groupadd web
@@ -115,33 +69,23 @@
root:~# mkdir -p /web /usr/local/aolserver
root:~# chown -R nsadmin.web /usr/local/aolserver /web /usr/local/src/aolserver
root:~# chmod 775 /usr/local/aolserver /web
-root:~# exit</pre>
-</li></ul></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="install-aolserver-env"></a>Set up nsadmin's environment variables</h3></div></div>
-<div class="itemizedlist"><ul><li>
-<p> At this point, you should customize the
+root:~# exit</pre></li></ul></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="install-aolserver-env"></a>Set up nsadmin's environment variables</h3></div></div><div class="itemizedlist"><ul type="disc"><li><p> At this point, you should customize the
<tt>nsadmin</tt> login scripts. Login as
<tt>nsadmin</tt> and add the following
lines to your
<tt>/usr/local/aolserver/.bash_profile</tt>:
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
joeuser:~$ su - nsadmin
Password: ***********
-nsadmin:~$ emacs .bash_profile</pre>
-<p>
+nsadmin:~$ emacs .bash_profile</pre><p>
Add the first set of lines, if you're using Oracle. The 2nd set
- of lines, if you're using PostgreSQL. <span class="emphasis"><i>Oracle
- Note:</i></span> These environment variables are specific for a
+ of lines, if you're using PostgreSQL. <span class="emphasis"><em>Oracle
+ Note:</em></span> These environment variables are specific for a
local Oracle installation communicating via IPC. If you are
connecting to a remote Oracle installation, you'll need to adjust
these appropriately. Also, make sure that the '8.1.7' matches
your Oracle version.
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
# For Oracle
export ORACLE_BASE=/ora8/m01/app/oracle
export ORACLE_HOME=$ORACLE_BASE/product/8.1.7
@@ -153,34 +97,25 @@
# For PostgreSQL
export PATH=$PATH:/usr/local/pgsql/bin
-export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/pgsql/lib</pre>
-<p>
+export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/pgsql/lib</pre><p>
Be absolutely certain that you have entered these lines correctly
and that you have saved the file - a slight error in these lines
can lead to many inscrutable error messages. Logout and log back
in so these settings will take effect. Use the
<tt>echo</tt> command to be sure that the
environment variables have been properly assigned.
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
nsadmin:~$ exit
joeuser:~$ su - nsadmin
Password: *********
nsadmin:~$ echo $PATH
...some other directory paths...:/usr/local/pgsql/bin
nsadmin:~$ echo $LD_LIBRARY_PATH
-:/usr/local/pgsql/lib</pre>
-<p>
+:/usr/local/pgsql/lib</pre><p>
Note: The result should be different if you're using Oracle.
<tt>/ora8/m01/app/oracle/product/8.1.7</tt>
should have been in <tt>$PATH</tt>.
- </p>
-</li></ul></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="install-aolserver-libxml2"></a>Install libxml2 & headers</h3></div></div>
-<p>
+ </p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="install-aolserver-libxml2"></a>Install libxml2 & headers</h3></div></div><p>
In order for nsxml to compile, you need libxml2
(available from <a href="http://xmlsoft.org" target="_top">http://xmlsoft.org</a>). On Debian,
@@ -189,103 +124,62 @@
download rpms from <a href="ftp://ftp.gnome.org/pub/GNOME/stable/redhat/i386/libxml/" target="_top">ftp.gnome.org</a>. You'll
need the <tt>libxml2</tt> and
<tt>libxml2-devel</tt> packages.
- </p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="install-aolserver-compile"></a>Compile and install AOLserver</h3></div></div>
-<div class="itemizedlist"><ul>
-<li>
-<p>Prepare the distribution</p>
-<pre class="programlisting">
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="install-aolserver-compile"></a>Compile and install AOLserver</h3></div></div><div class="itemizedlist"><ul type="disc"><li><p>Prepare the distribution</p><pre class="programlisting">
nsadmin:~$ cd /usr/local/src/aolserver
nsadmin:/usr/local/src/aolserver$ ./conf-clean
cat: BUILD-MODULES: No such file or directory
-Done.</pre>
-</li>
-<li>
-<p>
+Done.</pre></li><li><p>
Put the name of the driver(s) that you want into
<tt>conf-db</tt>. This can be
<tt>"postgresql"</tt>,
<tt>"oracle"</tt>, or the word
<tt>"both"</tt> if you want both drivers
installed.
- </p>
-<pre class="programlisting">
-nsadmin:/usr/local/src/aolserver$ echo "postgresql" > conf-db</pre>
-</li>
-<li><p>
+ </p><pre class="programlisting">
+nsadmin:/usr/local/src/aolserver$ echo "postgresql" > conf-db</pre></li><li><p>
<tt>conf-inst</tt> should contain the
location where AOLserver is to be installed. This defaults to
<tt>/usr/local/aolserver</tt>, so we
don't need to change it.
- </p></li>
-<li>
-<p>
+ </p></li><li><p>
<tt>conf-make</tt> should contain the
name of the GNU Make command on your system. It defaults to
<tt>gmake</tt>. You may need to change
this to <tt>make</tt>.
- </p>
-<pre class="programlisting">
-nsadmin:/usr/local/src/aolserver$ echo "make" > conf-make</pre>
-</li>
-<li>
-<p>
+ </p><pre class="programlisting">
+nsadmin:/usr/local/src/aolserver$ echo "make" > conf-make</pre></li><li><p>
If you're going to be installing the Postgresql driver, you'll
have to adjust the makefile first. This will hopefully be cleaned
up in future versions of this distribution.
- </p>
-<pre class="programlisting">
-nsadmin:/usr/local/src/aolserver$ emacs pgdriver/makefile</pre>
-<p>
+ </p><pre class="programlisting">
+nsadmin:/usr/local/src/aolserver$ emacs pgdriver/makefile</pre><p>
Edit the lines containing PGLIB and PGINC so they look like this:
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
PGINC=/usr/local/pgsql/include
-PGLIB=/usr/local/pgsql/lib</pre>
-</li>
-<li>
-<p>Compile and install AOLserver and modules</p>
-<pre class="programlisting">
-nsadmin:/usr/local/src/aolserver$ ./conf</pre>
-<p>
+PGLIB=/usr/local/pgsql/lib</pre></li><li><p>Compile and install AOLserver and modules</p><pre class="programlisting">
+nsadmin:/usr/local/src/aolserver$ ./conf</pre><p>
This takes about 5 minutes. All of the results are logged to
files in
<tt>/usr/local/src/aolserver/log</tt>. Make
sure to check these files to see if any errors occurred.
- </p>
-</li>
-</ul></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="install-aolserver-test"></a>Test AOLserver</h3></div></div>
-<div class="itemizedlist"><ul>
-<li>
-<p>
+ </p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="install-aolserver-test"></a>Test AOLserver</h3></div></div><div class="itemizedlist"><ul type="disc"><li><p>
You will now test to ensure AOLserver is running correctly. We'll
use the sample config file provided with AOLserver. This file
will attempt to guess your IP address and hostname. It will then
set up the server at port 8000 of that IP address.
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
nsadmin:/usr/local/src/aolserver$ cd
-nsadmin:~$ ./bin/nsd -t sample-config.tcl</pre>
-<p>
+nsadmin:~$ ./bin/nsd -t sample-config.tcl</pre><p>
As the AOLserver daemon starts up, you should see a few normal
warnings (listed below), which are safe to ignore.
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
Warning: nsd.tcl: nsssl not loaded -- key/cert files do not exist.
-Warning: nsd.tcl: nscp not loaded -- user/password is not set.</pre>
-<p>
+Warning: nsd.tcl: nscp not loaded -- user/password is not set.</pre><p>
The first warning means that the server is missing files for
running <tt>ssl</tt>, a necessary module
for encrypted HTTPS. See Scott Goodwin's <a href="http://scottg.net/webtools/opennsd/modules/nsopenssl/" target="_top">excellent
@@ -294,97 +188,46 @@
for administering AOLserver, could not be loaded. If you're
interested in configuring nscp, please see the <a href="http://www.aolserver.com/docs" target="_top">AOLserver
documentation</a>.
- </p>
-</li>
-<li>
-<p>
+ </p></li><li><p>
Test to see if AOLserver is working by starting
<tt>Mozilla</tt> or
<tt>Lynx</tt>, and surfing over to your
web page:
- </p>
-<pre class="programlisting">
-nsadmin:~$ lynx localhost:8000</pre>
-<p>
+ </p><pre class="programlisting">
+nsadmin:~$ lynx localhost:8000</pre><p>
You should see a "Welcome to AOLserver" page. If this
doesn't work, try going to
<tt>http://127.0.0.1:8000/</tt>. If this
still doesn't work, check out the <a href="aolserver.html#install-aolserver-troubleshooting">Troubleshooting AOLServer</a> section below.
- </p>
-</li>
-<li>
-<p>
- Shutdown the test server: </p>
-<pre class="programlisting">
-nsadmin:~$ killall nsd</pre>
-<p>
+ </p></li><li><p>
+ Shutdown the test server: </p><pre class="programlisting">
+nsadmin:~$ killall nsd</pre><p>
The <tt>killall</tt> command will kill
all processes with the name <tt>nsd</tt>,
but clearly this is not a good tool to use for managing your
services in general. We cover this topic in the <a href="openacs.html#install-openacs-keepalive">Keep AOLServer alive</a> section.
- </p>
-</li>
-</ul></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="install-aolserver-troubleshooting"></a>Troubleshooting the AOLserver Install</h3></div></div>
-<p>If you can't view the welcome page, it's likely
+ </p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="install-aolserver-troubleshooting"></a>Troubleshooting the AOLserver Install</h3></div></div><p>If you can't view the welcome page, it's likely
there's a problem with your server configuration. Start by
viewing your AOLserver log, which is in
<tt>/usr/local/aolserver/log/server.log</tt>.
- You should also try to find lines of the form:</p>
-<pre class="programlisting">
+ You should also try to find lines of the form:</p><pre class="programlisting">
[01/Jun/2000:12:11:20][5914.2051][-nssock-] Notice: nssock: listening on http://localhost.localdomain:8000 (127.0.0.1:8000)
-[01/Jun/2000:12:11:20][5914.2051][-nssock-] Notice: accepting connections</pre>
-<p>If you can find these lines, try entering the URL the server is
+[01/Jun/2000:12:11:20][5914.2051][-nssock-] Notice: accepting connections</pre><p>If you can find these lines, try entering the URL the server is
listening on. If you cannot find these lines, there must be an error
somewhere in the file. Search for lines beginning with the word
<tt>Error</tt> instead of
- <tt>Notice</tt>.</p>
-<p>The <tt>sample-config.tcl</tt> file grabs
- your address and hostname from your OS settings. </p>
-<pre class="programlisting">
+ <tt>Notice</tt>.</p><p>The <tt>sample-config.tcl</tt> file grabs
+ your address and hostname from your OS settings. </p><pre class="programlisting">
set hostname [ns_info hostname]
-set address [ns_info address]</pre>
-<p>If you get an error that nssock can't get the requested address,
- you can set these manually:</p>
-<pre class="programlisting">
+set address [ns_info address]</pre><p>If you get an error that nssock can't get the requested address,
+ you can set these manually:</p><pre class="programlisting">
#set hostname [ns_info hostname]
set hostname 127.0.0.1
#set address [ns_info address]
-set address 127.0.0.1</pre>
-<p>
+set address 127.0.0.1</pre><p>
If you get an error that nssock can't assign the requested port,
then that port may already be taken by another service. Try specifying
a different port in the config file.
- </p>
-</div>
-<p><div class="cvstag">($Id$)</div></p>
-</div>
-<div class="navfooter">
-<hr>
-<table width="100%" summary="Navigation footer">
-<tr>
-<td width="40%" align="left">
-<a accesskey="p" href="postgres.html">Prev</a> </td>
-<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
-<td width="40%" align="right"> <a accesskey="n" href="openacs.html">Next</a>
-</td>
-</tr>
-<tr>
-<td width="40%" align="left">Install PostgreSQL 7.1.3 </td>
-<td width="20%" align="center"><a accesskey="u" href="unix-install.html">Up</a></td>
-<td width="40%" align="right"> Install OpenACS 4.5</td>
-</tr>
-</table>
-<hr>
-<address>
- rmello at fslc.usu.edu
- </address>
-<address><a href="mailto:vinod@kurup.com">
+ </p></div><p><div class="cvstag">($Id$)</div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="postgres.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="openacs.html">Next</a></td></tr><tr><td width="40%" align="left">Install PostgreSQL 7.1.3 </td><td width="20%" align="center"><a accesskey="u" href="unix-install.html">Up</a></td><td width="40%" align="right"> Install OpenACS 4.5</td></tr></table><hr><address>rmello at fslc.usu.edu</address><address><a href="mailto:vinod@kurup.com">
vinod@kurup.com
- </a></address>
-</div>
-</body>
-</html>
+ </a></address></div></body></html>
Index: openacs-4/packages/acs-core-docs/www/apm-design.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/apm-design.html,v
diff -u -r1.5 -r1.5.2.1
--- openacs-4/packages/acs-core-docs/www/apm-design.html 7 Mar 2002 06:55:36 -0000 1.5
+++ openacs-4/packages/acs-core-docs/www/apm-design.html 15 May 2002 23:26:18 -0000 1.5.2.1
@@ -1,97 +1,36 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type">
-<title>OpenACS 4.5 Package Manager Design</title>
-<meta name="generator" content="DocBook XSL Stylesheets V1.45">
-<link rel="home" href="index.html" title="OpenACS Documentation">
-<link rel="up" href="kernel-doc.html" title="Chapter 7. Kernel Documentation">
-<link rel="previous" href="apm-requirements.html" title="OpenACS 4.5 Package Manager Requirements">
-<link rel="next" href="security-requirements.html" title="OpenACS 4 Security Requirements">
-<link rel="stylesheet" href="openacs.css" type="text/css">
-</head>
-<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-<div class="navheader">
-<a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr>
-<td width="20%" align="left">
-<a accesskey="p" href="apm-requirements.html">Prev</a> </td>
-<th width="60%" align="center">Chapter 7. Kernel Documentation</th>
-<td width="20%" align="right"> <a accesskey="n" href="security-requirements.html">Next</a>
-</td>
-</tr></table>
-<hr>
-</div>
-<div class="sect1">
-<div class="titlepage"><div><h2 class="title" style="clear: both">
-<a name="apm-design"></a>OpenACS 4.5 Package Manager Design</h2></div></div>
-<div class="authorblurb"><p>
-by <a href="mailto:bquinn@arsdigita.com" target="_top">Bryan Quinn</a>
-</p></div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="apm-design-essentials"></a>Essentials</h3></div></div>
-<div class="itemizedlist"><ul>
-<li><p><a href="/acs-admin/apm" target="_top">OpenACS Administrator directory</a></p></li>
-<li><p><a href="apm-requirements.html">OpenACS 4.5 Package Manager Requirements</a></p></li>
-<li><p><a href="packages.html">Packages</a></p></li>
-<li><p><a href="images/apm.pdf" target="_top">ER diagram</a></p></li>
-<li>
-<p>Tcl API </p>
-<div class="itemizedlist"><ul>
-<li><p><a href="/api-doc/procs-file-view?path=packages%2facs%2dkernel%2ftcl%2fapm%2dprocs%2etcl" target="_top">
-apm-procs.tcl</a></p></li>
-<li><p>
-<a href="/api-doc/procs-file-view?path=packages%2facs%2dkernel%2ftcl%2fapm%2dinstall%2dprocs%2etcl" target="_top">
-apm-install-procs.tcl</a> (Supports installation of packages)</p></li>
-<li><p>
-<a href="/api-doc/procs-file-view?path=packages%2facs%2dkernel%2ftcl%2f20%2dapm%2dload%2dprocs%2etcl" target="_top">
-20-apm-load-procs.tcl</a> (Bootstraps APM for server startup)</p></li>
-<li><p>
-<a href="/api-doc/procs-file-view?path=packages%2facs%2dkernel%2ftcl%2fapm%2dadmin%2dprocs%2etcl" target="_top">
-apm-admin-procs.tcl</a> (Supports APM UI)</p></li>
-</ul></div>
-</li>
-<li>
-<p>PL/SQL file </p>
-<div class="itemizedlist"><ul><li><p><a href="/doc/sql/display-sql?url=apm-create.sql&package_key=acs-kernel" target="_top">apm-create.sql</a></p></li></ul></div>
-</li>
-</ul></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="apm-design-intro"></a>Introduction</h3></div></div>
-<p>
-In general terms, a <span class="strong"><i>package</i></span> is a unit of software that
+<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"><title>OpenACS 4.5 Package Manager Design</title><meta name="generator" content="DocBook XSL Stylesheets V1.50.0"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="kernel-doc.html" title="Chapter 7. Kernel Documentation"><link rel="previous" href="apm-requirements.html" title="OpenACS 4.5 Package Manager Requirements"><link rel="next" href="security-requirements.html" title="OpenACS 4 Security Requirements"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="apm-requirements.html">Prev</a> </td><th width="60%" align="center">Chapter 7. Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="security-requirements.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="apm-design"></a>OpenACS 4.5 Package Manager Design</h2></div></div><div class="authorblurb"><p>
+by <a href="mailto:bquinn@arsdigita.com" target="_top">Bryan Quinn</a><br>
+ OpenACS docs are written by the named authors, but may be edited
+ by OpenACS documentation staff.
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="apm-design-essentials"></a>Essentials</h3></div></div><div class="itemizedlist"><ul type="disc"><li><p><a href="/acs-admin/apm" target="_top">OpenACS Administrator directory</a></p></li><li><p><a href="apm-requirements.html">OpenACS 4.5 Package Manager Requirements</a></p></li><li><p><a href="packages.html">Packages</a></p></li><li><p><a href="images/apm.pdf" target="_top">ER diagram</a></p></li><li><p>Tcl API </p><div class="itemizedlist"><ul type="round"><li><p><a href="/api-doc/procs-file-view?path=packages%2facs%2dkernel%2ftcl%2fapm%2dprocs%2etcl" target="_top">
+apm-procs.tcl</a></p></li><li><p><a href="/api-doc/procs-file-view?path=packages%2facs%2dkernel%2ftcl%2fapm%2dinstall%2dprocs%2etcl" target="_top">
+apm-install-procs.tcl</a> (Supports installation of packages)</p></li><li><p><a href="/api-doc/procs-file-view?path=packages%2facs%2dkernel%2ftcl%2f20%2dapm%2dload%2dprocs%2etcl" target="_top">
+20-apm-load-procs.tcl</a> (Bootstraps APM for server startup)</p></li><li><p><a href="/api-doc/procs-file-view?path=packages%2facs%2dkernel%2ftcl%2fapm%2dadmin%2dprocs%2etcl" target="_top">
+apm-admin-procs.tcl</a> (Supports APM UI)</p></li></ul></div></li><li><p>PL/SQL file </p><div class="itemizedlist"><ul type="round"><li><p><a href="/doc/sql/display-sql?url=apm-create.sql%26amp;package_key=acs-kernel" target="_top">apm-create.sql</a></p></li></ul></div></li></ul></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="apm-design-intro"></a>Introduction</h3></div></div><p>
+In general terms, a <span class="strong"><em>package</em></span> is a unit of software that
serves a single well-defined purpose. That purpose may be to provide a
service directly to one or more classes of end-user, (e.g., discussion forums
and file storage for community members, user profiling tools for the site
publisher), or it may be to act as a building block for other packages (e.g.,
an application programming interface (API) for storing and querying access
control rules, or an API for scheduling email alerts). Thus, packages fall
into one of two categories:
-</p>
-<div class="itemizedlist"><ul>
-<li><p>
-<span class="strong"><i>OpenACS Applications:</i></span> a "program or group of programs
+</p><div class="itemizedlist"><ul type="disc"><li><p><span class="strong"><em>OpenACS Applications:</em></span> a "program or group of programs
designed for end users" (the <a href="http://www.pcwebopaedia.com/TERM/a/application.html" target="_top">Webopedia
-definition</a>); also known as <span class="emphasis"><i>modules</i></span>, for historical reasons.
+definition</a>); also known as <span class="emphasis"><em>modules</em></span>, for historical reasons.
Examples of applications include <a href="/doc/bboard" target="_top">Bboard</a> and <a href="/doc/news" target="_top">News</a>.
-</p></li>
-<li><p>
-<span class="strong"><i>OpenACS Services:</i></span> the aforementioned building blocks.
+</p></li><li><p><span class="strong"><em>OpenACS Services:</em></span> the aforementioned building blocks.
Examples of services include the <a href="/doc/acs-content-repository" target="_top">OpenACS
Content Repository</a>, the <a href="/doc/acs-templating" target="_top">OpenACS Templating
System</a>, and the <a href="kernel-doc.html" title="Chapter 7. Kernel Documentation">OpenACS Kernel</a>, which includes
-APM.</p></li>
-</ul></div>
-<p>An installation of the OpenACS includes the OpenACS Kernel, some services that
+APM.</p></li></ul></div><p>An installation of the OpenACS includes the OpenACS Kernel, some services that
extend the kernel's functionality, and some applications intended for
end-users. Packages function as individual pieces of <a href="subsites-design.html" title="OpenACS 4 Subsites Design Document">subsites</a>. A subsite can contain multiple
application and service instances that provide the end-user with capabilities
-and content customized to the particular subsite.</p>
-<p>This architecture supports the growth of collaborative commerce. For
+and content customized to the particular subsite.</p><p>This architecture supports the growth of collaborative commerce. For
example, Jane User starts a forum focusing on the merits of View Cameras by
creating an instance of the Bboard application for her personal subsite on an
OpenACS Installation. Jack User discovers Jane's forum and includes a link to
@@ -103,214 +42,91 @@
view cameras and a portal application that links to reliable camera models
and resellers. Any subsite enabled package that is added to the OpenACS
installation through APM is another potential package instance that can
-become part of Jane's View Camera subsite.</p>
-<p>The APM provides an architecture for packaging software, making instances
+become part of Jane's View Camera subsite.</p><p>The APM provides an architecture for packaging software, making instances
of that software available to subsites, specifying configuration parameters
-for each instance, and managing the creation and release of new packages.</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="apm-design-hist-considerations"></a>Historical Considerations</h3></div></div>
-<p>
+for each instance, and managing the creation and release of new packages.</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="apm-design-hist-considerations"></a>Historical Considerations</h3></div></div><p>
Prior to ACS 3.3, all packages were lumped together into one monolithic
distribution without explicit boundaries; the only way to ascertain what
comprised a given package was to look at the top of the corresponding
documentation page, where, by convention, the package developer would specify
where to find:
-</p>
-<div class="itemizedlist"><ul>
-<li><p>the data model</p></li>
-<li><p>the Tcl procedures</p></li>
-<li><p>the user-accessible pages</p></li>
-<li><p>the administration pages</p></li>
-</ul></div>
-<p>Experience has shown us that this lack of explicit boundaries causes a
-number of maintainability problems for pre-3.3 installations:</p>
-<div class="orderedlist"><ol type="1">
-<li>
-<p>Package interfaces were not guaranteed to be stable in any formal way, so
+</p><div class="itemizedlist"><ul type="disc"><li><p>the data model</p></li><li><p>the Tcl procedures</p></li><li><p>the user-accessible pages</p></li><li><p>the administration pages</p></li></ul></div><p>Experience has shown us that this lack of explicit boundaries causes a
+number of maintainability problems for pre-3.3 installations:</p><div class="orderedlist"><ol type="1"><li><p>Package interfaces were not guaranteed to be stable in any formal way, so
a change in the interface of one package would often break dependent packages
(which we would only discover through manual regression testing). In this
context, any of the following could constitute an interface change:
-</p>
-<div class="itemizedlist"><ul>
-<li><p>renaming a file or directory that appears in a URL</p></li>
-<li><p>changing what form variables are expected as input by a page</p></li>
-<li><p>changing a procedural abstraction, e.g., a PL/SQL or Java stored
-procedure or a Tcl procedure</p></li>
-<li><p>changing a functional abstraction, e.g., a database view or a PL/SQL or
-Java stored function</p></li>
-<li><p>changing the data model</p></li>
-</ul></div>
-<p>This last point is especially important. In most cases, changing the data
-model should <span class="emphasis"><i>not</i></span> affect dependent packages. Rather, the package
+</p><div class="itemizedlist"><ul type="disc"><li><p>renaming a file or directory that appears in a URL</p></li><li><p>changing what form variables are expected as input by a page</p></li><li><p>changing a procedural abstraction, e.g., a PL/SQL or Java stored
+procedure or a Tcl procedure</p></li><li><p>changing a functional abstraction, e.g., a database view or a PL/SQL or
+Java stored function</p></li><li><p>changing the data model</p></li></ul></div><p>This last point is especially important. In most cases, changing the data
+model should <span class="emphasis"><em>not</em></span> affect dependent packages. Rather, the package
interface should provide a level of abstraction above the data model (as well
as the rest of the package implementation). Then, users of the package can
take advantage of implementation improvements that don't affect the
interface (e.g., faster performance from intelligent denormalization of the
data model), without having to worry that code outside the package will now
-break.</p>
-</li>
-<li><p>A typical ACS-backed site only uses a few of the modules included in the
+break.</p></li><li><p>A typical ACS-backed site only uses a few of the modules included in the
distribution, yet there was no well-understood way to pick only what you
needed when installing the ACS, or even to uninstall what you didn't
need, post-installation. Unwanted code had to be removed manually.
-</p></li>
-<li><p>Releasing a new version of the ACS was complicated, owing again to the
+</p></li><li><p>Releasing a new version of the ACS was complicated, owing again to the
monolithic nature of the software. Since we released everything in the ACS
together, all threads of ACS development had to converge on a single
deadline, after which we would undertake a focused QA effort whose scale
increased in direct proportion to the expansion of the ACS codebase.
-</p></li>
-<li><p>There was no standard way for developers outside of ArsDigita to extend
+</p></li><li><p>There was no standard way for developers outside of ArsDigita to extend
the ACS with their own packages. Along the same lines, ArsDigita programmers
working on client projects had no standard way to keep custom development
cleanly separated from ACS code. Consequently, upgrading an already installed
-ACS was an error-prone and time-consuming process.</p></li>
-</ol></div>
-<p>Consistent use of the APM format and tools will go a long way toward
+ACS was an error-prone and time-consuming process.</p></li></ol></div><p>Consistent use of the APM format and tools will go a long way toward
solving the maintainability problems listed above. Moreover, APM is the
substrate that will enable us to soon establish a central package repository,
where both ArsDigita and third-party developers will be able publish their
-packages for other ACS users to download and install.</p>
-<p>For a simple illustration of the difference between ACS without APM
+packages for other ACS users to download and install.</p><p>For a simple illustration of the difference between ACS without APM
(pre-3.3) and ACS with APM (3.3 and beyond), consider a hypothetical ACS
installation that uses only two of the thirty-odd modules available circa ACS
-3.2 (say, bboard and e-commerce):</p>
-<div class="mediaobject"><img src="images/acs-without-apm-vs-with-apm.png" align="center"></div>
-<p>APM itself is part of a package, the <span class="strong"><i>OpenACS Kernel</i></span>, an OpenACS
-service that is the only mandatory component of an OpenACS installation.</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="apm-design-competitors"></a>Competitive Analysis</h3></div></div>
-<p>The OpenACS is a platform for web-based application software, and any software
+3.2 (say, bboard and e-commerce):</p><div class="mediaobject"><img src="images/acs-without-apm-vs-with-apm.png" align="center" longdesc="ld-id5455081.html"><div class="longdesc-link" align="right"><br clear="all"><span style="font-size: 8pt;">[<a href="ld-id5455081.html" target="longdesc">D</a>]</span></div></div><p>APM itself is part of a package, the <span class="strong"><em>OpenACS Kernel</em></span>, an OpenACS
+service that is the only mandatory component of an OpenACS installation.</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="apm-design-competitors"></a>Competitive Analysis</h3></div></div><p>The OpenACS is a platform for web-based application software, and any software
platform has the potential to develop problems like those described above.
Fortunately, there are many precedents for systematic solutions,
-including:</p>
-<div class="itemizedlist"><ul>
-<li><p>
-<a href="http://www.debian.org/" target="_top">Debian GNU/Linux</a> and the <a href="http://www.debian.org/doc/packaging-manuals/packaging.html/" target="_top">Debian
-Packaging manual</a>
-</p></li>
-<li><p>
-<a href="http://www.freebsd.org/" target="_top">FreeBSD</a> has <a href="http://www.freebsd.org/handbook/ports.html" target="_top">the Ports
-collection</a>
-</p></li>
-<li><p>
-<a href="http://www.redhat.com/" target="_top">Red Hat Linux</a> has <a href="http://rpm.redhat.com/" target="_top">the Red Hat Package Manager (RPM)</a>
-</p></li>
-</ul></div>
-<p>Borrowing from all of the above, OpenACS 3.3 introduces its own package
-management system, the OpenACS Package Manager (APM), which consists of:</p>
-<div class="itemizedlist"><ul>
-<li>
-<p>
-<span class="strong"><i>a standard format for APM packages</i></span> (also called
-"OpenACS packages"), including: </p>
-<div class="itemizedlist"><ul>
-<li><p>version numbering, independent of any other package and the OpenACS as a
-whole</p></li>
-<li><p>specification of the package interface</p></li>
-<li><p>specification of dependencies on other packages (if any)</p></li>
-<li><p>attribution (who wrote it) and ownership (who maintains it)</p></li>
-</ul></div>
-</li>
-<li>
-<p>
-<span class="strong"><i>web-based tools for package management:</i></span> </p>
-<div class="itemizedlist"><ul>
-<li><p>obtaining packages from a remote distribution point</p></li>
-<li>
-<p>installing packages, if and only if: </p>
-<div class="orderedlist"><ol type="1">
-<li><p>all prerequisite packages are installed</p></li>
-<li><p>no conflicts will be created by the installation</p></li>
-</ol></div>
-</li>
-<li><p>configuring packages (obsoleting the monolithic OpenACS configuration
-file)</p></li>
-<li><p>upgrading packages, without clobbering local modifications</p></li>
-<li><p>uninstalling unwanted packages</p></li>
-</ul></div>
-</li>
-<li><p>
-<span class="strong"><i>a registry of installed packages</i></span>, database-backed and
+including:</p><div class="itemizedlist"><ul type="disc"><li><p><a href="http://www.debian.org/" target="_top">Debian GNU/Linux</a> and the <a href="http://www.debian.org/doc/packaging-manuals/packaging.html/" target="_top">Debian
+Packaging manual</a></p></li><li><p><a href="http://www.freebsd.org/" target="_top">FreeBSD</a> has <a href="http://www.freebsd.org/handbook/ports.html" target="_top">the Ports
+collection</a></p></li><li><p><a href="http://www.redhat.com/" target="_top">Red Hat Linux</a> has <a href="http://rpm.redhat.com/" target="_top">the Red Hat Package Manager (RPM)</a></p></li></ul></div><p>Borrowing from all of the above, OpenACS 3.3 introduces its own package
+management system, the OpenACS Package Manager (APM), which consists of:</p><div class="itemizedlist"><ul type="disc"><li><p><span class="strong"><em>a standard format for APM packages</em></span> (also called
+"OpenACS packages"), including: </p><div class="itemizedlist"><ul type="round"><li><p>version numbering, independent of any other package and the OpenACS as a
+whole</p></li><li><p>specification of the package interface</p></li><li><p>specification of dependencies on other packages (if any)</p></li><li><p>attribution (who wrote it) and ownership (who maintains it)</p></li></ul></div></li><li><p><span class="strong"><em>web-based tools for package management:</em></span> </p><div class="itemizedlist"><ul type="round"><li><p>obtaining packages from a remote distribution point</p></li><li><p>installing packages, if and only if: </p><div class="orderedlist"><ol type="1"><li><p>all prerequisite packages are installed</p></li><li><p>no conflicts will be created by the installation</p></li></ol></div></li><li><p>configuring packages (obsoleting the monolithic OpenACS configuration
+file)</p></li><li><p>upgrading packages, without clobbering local modifications</p></li><li><p>uninstalling unwanted packages</p></li></ul></div></li><li><p><span class="strong"><em>a registry of installed packages</em></span>, database-backed and
integrated with filesystem-based version control
-</p></li>
-<li>
-<p>
-<span class="strong"><i>web-based tools for package development:</i></span> </p>
-<div class="itemizedlist"><ul>
-<li><p>creating new packages locally</p></li>
-<li><p>releasing new versions of locally-created packages</p></li>
-</ul></div>
-</li>
-</ul></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="apm-design-design-tradeoffs"></a>Design Tradeoffs</h3></div></div>
-<p>
+</p></li><li><p><span class="strong"><em>web-based tools for package development:</em></span> </p><div class="itemizedlist"><ul type="round"><li><p>creating new packages locally</p></li><li><p>releasing new versions of locally-created packages</p></li></ul></div></li></ul></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="apm-design-design-tradeoffs"></a>Design Tradeoffs</h3></div></div><p>
The design chosen for APM was meant to satisfy the following constraints:
-</p>
-<div class="itemizedlist"><ul>
-<li><p>The process of authoring a package must be as simple as possible.</p></li>
-<li><p>Strict conventions must be established that provide a set of canonical
+</p><div class="itemizedlist"><ul type="disc"><li><p>The process of authoring a package must be as simple as possible.</p></li><li><p>Strict conventions must be established that provide a set of canonical
locations and names for files and patterns, for OpenACS application
-development.</p></li>
-<li><p>The processes of installing, upgrading, and using packages must be
-straightforward and accessible through a web-based UI.</p></li>
-<li><p>Package instances must be able to have subsite-specific content available
-at an easily configurable URL.</p></li>
-</ul></div>
-<p>All of these requirements were met, but at the cost of development
+development.</p></li><li><p>The processes of installing, upgrading, and using packages must be
+straightforward and accessible through a web-based UI.</p></li><li><p>Package instances must be able to have subsite-specific content available
+at an easily configurable URL.</p></li></ul></div><p>All of these requirements were met, but at the cost of development
simplicity. As <a href="packages.html">Packages</a> demonstrates, a set of strict directory conventions are
required in order for a package to use APM. This contrasts with the apparent
simplicity available to developers of the OpenACS 3.3 system. However, while the
system has become more complex for developers to build packages, this
complexity is easily managed and is compensated for by additional
-capabilities.</p>
-<p>For example, to make a new application available to the system, a
-developer must:</p>
-<div class="orderedlist"><ol type="1">
-<li><p>Create the necessary files to support the data model, Tcl API, and UI
-pages.</p></li>
-<li><p>Put the files in the correct locations for APM to be aware of them.</p></li>
-<li><p>Use APM to create a new package and enable it.</p></li>
-<li><p>Use the Site Map facility to create an instance of the package, mount it
-on an appropriate URL, and set parameters for that particular instance.</p></li>
-</ol></div>
-<p>While this is complex, especially to a new OpenACS developer, the
+capabilities.</p><p>For example, to make a new application available to the system, a
+developer must:</p><div class="orderedlist"><ol type="1"><li><p>Create the necessary files to support the data model, Tcl API, and UI
+pages.</p></li><li><p>Put the files in the correct locations for APM to be aware of them.</p></li><li><p>Use APM to create a new package and enable it.</p></li><li><p>Use the Site Map facility to create an instance of the package, mount it
+on an appropriate URL, and set parameters for that particular instance.</p></li></ol></div><p>While this is complex, especially to a new OpenACS developer, the
documentation walks the developer through each of these steps. Moreover, from
following these steps, the package can be subsite specific, available to
subsites across the system, and be available for distribution to other OpenACS
-installations without doing a monolithic upgrade or reinstall.</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="apm-design-api"></a>API</h3></div></div>
-<p>The APM is composed of systems for accomplishing a set of package-related
+installations without doing a monolithic upgrade or reinstall.</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="apm-design-api"></a>API</h3></div></div><p>The APM is composed of systems for accomplishing a set of package-related
tasks. Each of these tasks comprise a feature area that has an API, data
-model, and a UI:</p>
-<div class="itemizedlist"><ul>
-<li><p>Authoring a Package</p></li>
-<li><p>Maintaining Multiple Versions of a Package</p></li>
-<li><p>Creating Instances of the Package</p></li>
-<li><p>Specifying Configuration Parameters for each Instance</p></li>
-</ul></div>
-<p><span class="strong"><i>Authoring a Package</i></span></p>
-<p>Full instructions on how to prepare an OpenACS package are available in <a href="packages.html">Packages</a>. The API here can be invoked manually by a package's data model
-creation script, but need not to be used. This API is part of the <a href="/api-doc/plsql-subprogram-one?type=PACKAGE&name=APM" target="_top">APM PL/SQL
-package</a>.</p>
-<pre class="programlisting">
+model, and a UI:</p><div class="itemizedlist"><ul type="disc"><li><p>Authoring a Package</p></li><li><p>Maintaining Multiple Versions of a Package</p></li><li><p>Creating Instances of the Package</p></li><li><p>Specifying Configuration Parameters for each Instance</p></li></ul></div><p><span class="strong"><em>Authoring a Package</em></span></p><p>Full instructions on how to prepare an OpenACS package are available in <a href="packages.html">Packages</a>. The API here can be invoked manually by a package's data model
+creation script, but need not to be used. This API is part of the <a href="/api-doc/plsql-subprogram-one?type=PACKAGE%26amp;name=APM" target="_top">APM PL/SQL
+package</a>.</p><pre class="programlisting">
-- Informs the APM that this application is available for use.
procedure register_application (
@@ -326,15 +142,12 @@
default null
);
-</pre>
-<p>The procedure above registers an OpenACS application in the APM. It creates a
+</pre><p>The procedure above registers an OpenACS application in the APM. It creates a
new OpenACS object and stores information about the package, such as its name, in
the APM data model. There is an analogous procedure for OpenACS services, called
-<tt>apm.register_service</tt>.</p>
-<p>To remove an application from the system, there are the calls
+<tt>apm.register_service</tt>.</p><p>To remove an application from the system, there are the calls
<tt>apm.unregister_application</tt> and
-<tt>apm.unregister_service</tt>.</p>
-<pre class="programlisting">
+<tt>apm.unregister_service</tt>.</p><pre class="programlisting">
-- Remove the application from the system.
procedure unregister_application (
@@ -343,29 +156,22 @@
cascade_p in char default 'f'
);
-</pre>
-<p>Use the <tt>cascade_p</tt> only if you want to completely remove the
-package from the OpenACS.</p>
-<p>In order to determine if a particular package exists in the system, use
+</pre><p>Use the <tt>cascade_p</tt> only if you want to completely remove the
+package from the OpenACS.</p><p>In order to determine if a particular package exists in the system, use
the <tt>register_p</tt> predicate. It returns 1 if the specified
-<tt>package_key</tt> exists in the system, 0 otherwise.</p>
-<pre class="programlisting">
+<tt>package_key</tt> exists in the system, 0 otherwise.</p><pre class="programlisting">
function register_p (
package_key in apm_package_types.package_key%TYPE
) return integer;
-</pre>
-<p><span class="strong"><i>Maintaining Multiple Versions of a Package</i></span></p>
-<p>While the package authoring API provides a means for registering a
+</pre><p><span class="strong"><em>Maintaining Multiple Versions of a Package</em></span></p><p>While the package authoring API provides a means for registering a
package, some information about a package is version dependent. For example,
between versions, the owner of a package, its vendor, its URI, and its
dependency information may change. The API for package versions allows this
-information to be specified. All of these APIs are part of the <a href="/api-doc/plsql-subprogram-one?type=PACKAGE&name=APM%5fPACKAGE%5fVERSION" target="_top">
-<tt>apm_package_version</tt> PL/SQL package</a>.</p>
-<p>To create a new package version, use the
-<tt>apm_package_version.new</tt> constructor function.</p>
-<pre class="programlisting">
+information to be specified. All of these APIs are part of the <a href="/api-doc/plsql-subprogram-one?type=PACKAGE%26amp;name=APM%5fPACKAGE%5fVERSION" target="_top">
+<tt>apm_package_version</tt> PL/SQL package</a>.</p><p>To create a new package version, use the
+<tt>apm_package_version.new</tt> constructor function.</p><pre class="programlisting">
function new (
version_id in apm_package_versions.version_id%TYPE
@@ -386,49 +192,26 @@
default 'f'
) return apm_package_versions.version_id%TYPE;
-</pre>
-<p>In order to use this function, an existing <tt>package_key</tt> must
+</pre><p>In order to use this function, an existing <tt>package_key</tt> must
be specified. The <tt>version_name</tt> parameter must follow a strict
-convention:</p>
-<div class="orderedlist"><ol type="1">
-<li><p>A major version number</p></li>
-<li><p>at least one minor version number. Although any number of minor version
+convention:</p><div class="orderedlist"><ol type="1"><li><p>A major version number</p></li><li><p>at least one minor version number. Although any number of minor version
numbers may be included, three minor version numbers is sufficient and is the
-convention of software developers.</p></li>
-<li>
-<p>One of the following: </p>
-<div class="itemizedlist"><ul>
-<li><p>The letter <tt>d</tt>, indicating a development-only version</p></li>
-<li><p>The letter <tt>a</tt>, indicating an alpha release</p></li>
-<li><p>The letter <tt>b</tt>, indicating a beta release</p></li>
-<li><p>No letter at all, indicating a final production release</p></li>
-</ul></div>
-</li>
-</ol></div>
-<p>In addition, the letters <tt>d</tt>, <tt>a</tt>, and
+convention of software developers.</p></li><li><p>One of the following: </p><div class="itemizedlist"><ul type="disc"><li><p>The letter <tt>d</tt>, indicating a development-only version</p></li><li><p>The letter <tt>a</tt>, indicating an alpha release</p></li><li><p>The letter <tt>b</tt>, indicating a beta release</p></li><li><p>No letter at all, indicating a final production release</p></li></ul></div></li></ol></div><p>In addition, the letters <tt>d</tt>, <tt>a</tt>, and
<tt>b</tt> may be followed by another integer, indicating a version
-within the release.</p>
-<p>For those who like regular expressions:</p>
-<pre class="programlisting">
+within the release.</p><p>For those who like regular expressions:</p><pre class="programlisting">
version_number := ^[0-9]+((\.[0-9]+)+((d|a|b|)[0-9]?)?)$
-</pre>
-<p>So the following is a valid progression for version numbers:</p>
-<blockquote class="blockquote"><p><tt>0.9d, 0.9d1, 0.9a1, 0.9b1, 0.9b2, 0.9, 1.0, 1.0.1, 1.1b1,
-1.1</tt></p></blockquote>
-<p>To delete a given version of a package, use the
-<tt>apm_package_version.delete</tt> procedure:</p>
-<pre class="programlisting">
+</pre><p>So the following is a valid progression for version numbers:</p><blockquote class="blockquote"><p><tt>0.9d, 0.9d1, 0.9a1, 0.9b1, 0.9b2, 0.9, 1.0, 1.0.1, 1.1b1,
+1.1</tt></p></blockquote><p>To delete a given version of a package, use the
+<tt>apm_package_version.delete</tt> procedure:</p><pre class="programlisting">
procedure delete (
package_id in apm_packages.package_id%TYPE
);
-</pre>
-<p>After creating a version, it is possible to edit the information
-associated with it using <tt>apm_package_version.edit</tt>.</p>
-<pre class="programlisting">
+</pre><p>After creating a version, it is possible to edit the information
+associated with it using <tt>apm_package_version.edit</tt>.</p><pre class="programlisting">
function edit (
new_version_id in apm_package_versions.version_id%TYPE
@@ -449,11 +232,9 @@
default 'f'
) return apm_package_versions.version_id%TYPE;
-</pre>
-<p>Versions can be enabled or disabled. Enabling a version instructs APM to
+</pre><p>Versions can be enabled or disabled. Enabling a version instructs APM to
source the package's libraries on startup and to make the package
-available to the OpenACS.</p>
-<pre class="programlisting">
+available to the OpenACS.</p><pre class="programlisting">
procedure enable (
version_id in apm_package_versions.version_id%TYPE
@@ -463,11 +244,9 @@
version_id in apm_package_versions.version_id%TYPE
);
-</pre>
-<p>Files associated with a version can be added and removed. The path is
-relative to the <span class="strong"><i>package-root</i></span> which is
-<tt>acs-server-root/packages/package-key</tt>.</p>
-<pre class="programlisting">
+</pre><p>Files associated with a version can be added and removed. The path is
+relative to the <span class="strong"><em>package-root</em></span> which is
+<tt>acs-server-root/packages/package-key</tt>.</p><pre class="programlisting">
-- Add a file to the indicated version.
function add_file(
file_id in apm_package_files.file_id%TYPE
@@ -482,12 +261,10 @@
version_id in apm_package_versions.version_id%TYPE,
path in apm_package_files.path%TYPE
);
-</pre>
-<p>Package versions need to indicate that they provide interfaces for other
+</pre><p>Package versions need to indicate that they provide interfaces for other
software. An interface is an API that other packages can access and utilize.
Interfaces are identified as a URI and a version name, that comply with the
-specification of a version name for package URIs.</p>
-<pre class="programlisting">
+specification of a version name for package URIs.</p><pre class="programlisting">
-- Add an interface provided by this version.
function add_interface(
@@ -509,11 +286,9 @@
version_id in apm_package_versions.version_id%TYPE
);
-</pre>
-<p>The primary use of interfaces is for other packages to specify required
+</pre><p>The primary use of interfaces is for other packages to specify required
interfaces, known as dependencies. A package cannot be correctly installed
-unless all of its dependencies have been satisfied.</p>
-<pre class="programlisting">
+unless all of its dependencies have been satisfied.</p><pre class="programlisting">
-- Add a requirement for this version. A requirement is some interface that this
-- version depends on.
@@ -536,10 +311,8 @@
version_id in apm_package_versions.version_id%TYPE
);
-</pre>
-<p>As new versions of packages are created, it is necessary to compare their
-version names. These two functions assist in that task.</p>
-<pre class="programlisting">
+</pre><p>As new versions of packages are created, it is necessary to compare their
+version names. These two functions assist in that task.</p><pre class="programlisting">
-- Given a version_name (e.g. 3.2a), return
-- something that can be lexicographically sorted.
@@ -554,12 +327,9 @@
version_name_two in apm_package_versions.version_name%TYPE
) return integer;
-</pre>
-<p><span class="strong"><i>Creating Instances of a Package</i></span></p>
-<p>Once a package is registered in the system, it is possible to create
+</pre><p><span class="strong"><em>Creating Instances of a Package</em></span></p><p>Once a package is registered in the system, it is possible to create
instances of it. Each instance can maintain its own content and
-parameters.</p>
-<pre class="programlisting">
+parameters.</p><pre class="programlisting">
create or replace package apm_application
as
@@ -582,12 +352,10 @@
);
end apm_application;
-</pre>
-<p>Just creating a package instance is not sufficient for it to be served
+</pre><p>Just creating a package instance is not sufficient for it to be served
from the web server. A corresponding site node must be created for it. As an
example, here is how the <a href="/api-doc" target="_top">OpenACS API Documentation</a> service
-makes itself available on the OpenACS main site:</p>
-<pre class="programlisting">
+makes itself available on the OpenACS main site:</p><pre class="programlisting">
declare
api_doc_id integer;
@@ -614,20 +382,16 @@
show errors
-</pre>
-<p><span class="strong"><i>Specifying Configuration Parameters for each Instance</i></span></p>
-<p>A parameter is a setting that can be changed on a package instance basis.
+</pre><p><span class="strong"><em>Specifying Configuration Parameters for each Instance</em></span></p><p>A parameter is a setting that can be changed on a package instance basis.
Parameters are registered on each <tt>package_key</tt>, and the values
are associated with each instance. Parameters can have default values and can
be of type 'string' or 'number.' There is support with this
API for setting a number of minimum and maximum values for each parameter,
but for most instances, the minimum and maximum should be 1. It is useful to
allow or require multiple values for packages that need to store multiple
pieces of information under one parameter. Default values are automatically
-set when instances are created, but can be changed for each instance.</p>
-<p>All of the functions below are in the <a href="/api-doc/plsql-subprogram-one?type=PACKAGE&name=APM" target="_top">APM PL/SQL
-package</a>.</p>
-<pre class="programlisting">
+set when instances are created, but can be changed for each instance.</p><p>All of the functions below are in the <a href="/api-doc/plsql-subprogram-one?type=PACKAGE%26amp;name=APM" target="_top">APM PL/SQL
+package</a>.</p><pre class="programlisting">
-- Indicate to APM that a parameter is available to the system.
function register_parameter (
@@ -673,10 +437,8 @@
default null
);
-</pre>
-<p>The following functions are used to associate values with parameters and
-instances:</p>
-<pre class="programlisting">
+</pre><p>The following functions are used to associate values with parameters and
+instances:</p><pre class="programlisting">
-- Return the value of this parameter for a specific package and parameter.
function get_value (
@@ -702,218 +464,84 @@
attr_value in apm_parameter_values.attr_value%TYPE
);
-</pre>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="apm-design-data-model"></a>Data Model Discussion</h3></div></div>
-<p>The central piece of the data model is the <tt>apm_package_types</tt>
+</pre></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="apm-design-data-model"></a>Data Model Discussion</h3></div></div><p>The central piece of the data model is the <tt>apm_package_types</tt>
table where each package is registered. When a new application or service is
installed on an OpenACS instance, a corresponding row in this table is inserted
with information about the type of package, e.g. if the <a href="/doc/bboard" target="_top">bboard package</a> is installed on your OpenACS server, a row
in <tt>apm_package_types</tt> will be created, noting that it's an
-application package type.</p>
-<p>The <tt>apm_packages</tt> table is used to contain information about
-the <span class="emphasis"><i>instances</i></span> of packages currently created in the system. The
+application package type.</p><p>The <tt>apm_packages</tt> table is used to contain information about
+the <span class="emphasis"><em>instances</em></span> of packages currently created in the system. The
<tt>package_key</tt> column references the <tt>apm_package_types</tt>
table to ensure that no package instance can be created for a type that does
-not exist.</p>
-<p>The <tt>apm_package_versions</tt> table contains information specific
+not exist.</p><p>The <tt>apm_package_versions</tt> table contains information specific
to a particular version of a package. Several tables reference this one to
-provide further information about the particular version:</p>
-<div class="itemizedlist"><ul>
-<li><p>
-<tt>apm_package_owners</tt>
+provide further information about the particular version:</p><div class="itemizedlist"><ul type="disc"><li><p><tt>apm_package_owners</tt>
Stores information about the owners of a particular version of a package.
-</p></li>
-<li><p>
-<tt>apm_package_files</tt>
+</p></li><li><p><tt>apm_package_files</tt>
Stores information about the files that are part of a version.
-</p></li>
-<li><p>
-<tt>apm_package_dependencies</tt>
+</p></li><li><p><tt>apm_package_dependencies</tt>
Stores information about what interfaces the package provides and
-requires.</p></li>
-</ul></div>
-<p>Parameter information is maintained through two tables:</p>
-<div class="itemizedlist"><ul>
-<li><p>
-<tt>apm_parameters</tt>
+requires.</p></li></ul></div><p>Parameter information is maintained through two tables:</p><div class="itemizedlist"><ul type="disc"><li><p><tt>apm_parameters</tt>
This table contains the definition of each of the parameters for a package.
-</p></li>
-<li><p>
-<tt>apm_parameter_values</tt>
+</p></li><li><p><tt>apm_parameter_values</tt>
This table holds all of the values of parameters for specific package
instances.
-</p></li>
-</ul></div>
-<p>A number of views are available for obtaining information about packages
-registered in the APM.</p>
-<div class="itemizedlist"><ul>
-<li><p>
-<tt>apm_package_version_info</tt>
+</p></li></ul></div><p>A number of views are available for obtaining information about packages
+registered in the APM.</p><div class="itemizedlist"><ul type="disc"><li><p><tt>apm_package_version_info</tt>
Provides information about all of the versions in the system with
information available from the <tt>apm_package_types</tt> table.
-</p></li>
-<li><p>
-<tt>apm_enabled_package_versions</tt>
+</p></li><li><p><tt>apm_enabled_package_versions</tt>
A view (subset) of the above table with only enabled versions.
-</p></li>
-<li><p>
-<tt>apm_file_info</tt>
- Provides a public interface for querying file information.</p></li>
-</ul></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="apm-design-ui"></a>User Interface</h3></div></div>
-<p>The <a href="/acs-admin/apm" target="_top">APM's user interface</a> is part of the
+</p></li><li><p><tt>apm_file_info</tt>
+ Provides a public interface for querying file information.</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="apm-design-ui"></a>User Interface</h3></div></div><p>The <a href="/acs-admin/apm" target="_top">APM's user interface</a> is part of the
<a href="/acs-admin" target="_top">OpenACS Administration Service</a>. The UI is the primary
point of contact with APM by developers and administrators. It is part of OpenACS
Administration, because only the site-wide administrator should be able to
access it. Thus in order to develop a package, the developer must be granted
-site-wide administration.</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="apm-design-config"></a>Configuration/Parameters</h3></div></div>
-<p>APM has two parameters for configuring how it interacts with the UNIX
+site-wide administration.</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="apm-design-config"></a>Configuration/Parameters</h3></div></div><p>APM has two parameters for configuring how it interacts with the UNIX
filesystem, accessible via the <a href="/admin/site-map/" target="_top">Site Map admin</a>
page. These parameters need not be changed under most circumstances, but may
-need to be tweaked for Windows compatibility.</p>
-<div class="itemizedlist"><ul>
-<li><p>
-<span class="strong"><i>GzipExecutableDirectory</i></span>
+need to be tweaked for Windows compatibility.</p><div class="itemizedlist"><ul type="disc"><li><p><span class="strong"><em>GzipExecutableDirectory</em></span>
This directory points to where the <tt>gunzip</tt> program can be found
for uncompressing <tt>gzip</tt> archives. This is needed for the
installation of <tt>.apm</tt> files which are simply <tt>gzip</tt>ed
tarballs. Default is <tt>/usr/local/bin</tt>
-</p></li>
-<li><p>
-<span class="strong"><i>InfoFilePermissionsMode</i></span>
+</p></li><li><p><span class="strong"><em>InfoFilePermissionsMode</em></span>
This sets the default UNIX permissions used when creating files using the
-APM. Default is 775.</p></li>
-</ul></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="apm-design-future"></a>Future Improvements/Areas of Likely Change</h3></div></div>
-<p>APM has been in production since OpenACS 3.3, and as of version 4.0 offers a
+APM. Default is 775.</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="apm-design-future"></a>Future Improvements/Areas of Likely Change</h3></div></div><p>APM has been in production since OpenACS 3.3, and as of version 4.0 offers a
stable set of features. One major feature planned is integration with the OpenACS
Package Repository for automatic dependency satisfaction. When a user tries
to install a package that depends on other packages, the APM will contact the
package repository, determine what packages depend on it, and offer the user
a chance to download and install them all. This improvement offers value to
-end users by facilitating the extension of their OpenACS systems.</p>
-<p>Architecturally, minor improvements to the data model and the
+end users by facilitating the extension of their OpenACS systems.</p><p>Architecturally, minor improvements to the data model and the
specification file are planned to increase modularity. The current
implementation puts all package specification information in a single file.
This approach has certain advantages, such as centralization, but splitting
this information into several files allows for flexible extensions to the APM
-architecture over time.</p>
-<p>APM packages currently lack provisions to verify security information.
+architecture over time.</p><p>APM packages currently lack provisions to verify security information.
There are plans to add MD5 time stamps and PGP signatures to packages to
enable secure authentication of packages. These steps are necessary for APM
to be usable as a scalable method to distribute packages on multiple
-repositories worldwide.</p>
-<p>Another anticipated change is to split the APM UI into separate systems
+repositories worldwide.</p><p>Another anticipated change is to split the APM UI into separate systems
for authoring, maintaining, and installing packages. The current UI presents
all of this functionality in one interface and it can be confusing from a
-usability perspective.</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="apm-design-authors"></a>Authors</h3></div></div>
-<div class="itemizedlist"><ul>
-<li><p>System creator: Bryan Quinn, Jon Salz, Michael Yoon, Lars Pind, Todd
-Nightingale.</p></li>
-<li><p>System owner: Bryan Quinn</p></li>
-<li><p>Documentation author: Bryan Quinn, building from earlier versions by Jon
-Salz, Michael Yoon, and Lars Pind.</p></li>
-</ul></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="apm-design-rev-history"></a>Revision History</h3></div></div>
-<div class="informaltable"><table border="1">
-<colgroup>
-<col>
-<col>
-<col>
-<col>
-</colgroup>
-<tbody>
-<tr>
-<td><span class="strong"><i>Document Revision #</i></span></td>
-<td><span class="strong"><i>Action Taken, Notes</i></span></td>
-<td><span class="strong"><i>When?</i></span></td>
-<td><span class="strong"><i>By Whom?</i></span></td>
-</tr>
-<tr>
-<td>0.1</td>
-<td>Creation</td>
-<td>9/25/2000</td>
-<td>Bryan Quinn</td>
-</tr>
-<tr>
-<td>0.8</td>
-<td>Ready for QA</td>
-<td>9/29/2000</td>
-<td>Bryan Quinn</td>
-</tr>
-<tr>
-<td>0.9</td>
-<td>Edited for ACS 4 Beta release</td>
-<td>10/02/2000</td>
-<td>Kai Wu</td>
-</tr>
-<tr>
-<td>1.0</td>
-<td>Edited for OpenACS 4.5 Beta release</td>
-<td>03/02/2002</td>
-<td>Roberto Mello</td>
-</tr>
-</tbody>
-</table></div>
-</div>
-</div>
-<div class="navfooter">
-<hr>
-<table width="100%" summary="Navigation footer">
-<tr>
-<td width="40%" align="left">
-<a accesskey="p" href="apm-requirements.html">Prev</a> </td>
-<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
-<td width="40%" align="right"> <a accesskey="n" href="security-requirements.html">Next</a>
-</td>
-</tr>
-<tr>
-<td width="40%" align="left">OpenACS 4.5 Package Manager Requirements </td>
-<td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td>
-<td width="40%" align="right"> OpenACS 4 Security Requirements</td>
-</tr>
-</table>
-<hr>
-<address>
- rmello at fslc.usu.edu
- </address>
-<address><a href="mailto:vinod@kurup.com">
+usability perspective.</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="apm-design-authors"></a>Authors</h3></div></div><div class="itemizedlist"><ul type="disc"><li><p>System creator: Bryan Quinn, Jon Salz, Michael Yoon, Lars Pind, Todd
+Nightingale.</p></li><li><p>System owner: Bryan Quinn</p></li><li><p>Documentation author: Bryan Quinn, building from earlier versions by Jon
+Salz, Michael Yoon, and Lars Pind.</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="apm-design-rev-history"></a>Revision History</h3></div></div><div class="informaltable"><table border="1"><colgroup><col><col><col><col></colgroup><tbody><tr><td><span class="strong"><em>Document Revision #</em></span></td><td><span class="strong"><em>Action Taken, Notes</em></span></td><td><span class="strong"><em>When?</em></span></td><td><span class="strong"><em>By Whom?</em></span></td></tr><tr><td>0.1</td><td>Creation</td><td>9/25/2000</td><td>Bryan Quinn</td></tr><tr><td>0.8</td><td>Ready for QA</td><td>9/29/2000</td><td>Bryan Quinn</td></tr><tr><td>0.9</td><td>Edited for ACS 4 Beta release</td><td>10/02/2000</td><td>Kai Wu</td></tr><tr><td>1.0</td><td>Edited for OpenACS 4.5 Beta release</td><td>03/02/2002</td><td>Roberto Mello</td></tr></tbody></table></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="apm-requirements.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="security-requirements.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS 4.5 Package Manager Requirements </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> OpenACS 4 Security Requirements</td></tr></table><hr><address>rmello at fslc.usu.edu</address><address><a href="mailto:vinod@kurup.com">
vinod@kurup.com
- </a></address>
-</div>
-</body>
-</html>
+ </a></address></div></body></html>
Index: openacs-4/packages/acs-core-docs/www/apm-requirements.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/apm-requirements.html,v
diff -u -r1.5 -r1.5.2.1
--- openacs-4/packages/acs-core-docs/www/apm-requirements.html 7 Mar 2002 06:55:36 -0000 1.5
+++ openacs-4/packages/acs-core-docs/www/apm-requirements.html 15 May 2002 23:26:18 -0000 1.5.2.1
@@ -1,60 +1,19 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type">
-<title>OpenACS 4.5 Package Manager Requirements</title>
-<meta name="generator" content="DocBook XSL Stylesheets V1.45">
-<link rel="home" href="index.html" title="OpenACS Documentation">
-<link rel="up" href="kernel-doc.html" title="Chapter 7. Kernel Documentation">
-<link rel="previous" href="subsites-design.html" title="OpenACS 4 Subsites Design Document">
-<link rel="next" href="apm-design.html" title="OpenACS 4.5 Package Manager Design">
-<link rel="stylesheet" href="openacs.css" type="text/css">
-</head>
-<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-<div class="navheader">
-<a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr>
-<td width="20%" align="left">
-<a accesskey="p" href="subsites-design.html">Prev</a> </td>
-<th width="60%" align="center">Chapter 7. Kernel Documentation</th>
-<td width="20%" align="right"> <a accesskey="n" href="apm-design.html">Next</a>
-</td>
-</tr></table>
-<hr>
-</div>
-<div class="sect1">
-<div class="titlepage"><div><h2 class="title" style="clear: both">
-<a name="apm-requirements"></a>OpenACS 4.5 Package Manager Requirements</h2></div></div>
-<div class="authorblurb"><p>
-by <a href="mailto:bquinn@arsdigita.com" target="_top">Bryan Quinn</a> and <a href="mailto:tnight@arsdigita.com" target="_top">Todd Nightingale</a>
-</p></div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="apm-requirements-intro"></a>Introduction</h3></div></div>
-<p>The following is a requirements document for the OpenACS Package Manager
+<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"><title>OpenACS 4.5 Package Manager Requirements</title><meta name="generator" content="DocBook XSL Stylesheets V1.50.0"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="kernel-doc.html" title="Chapter 7. Kernel Documentation"><link rel="previous" href="subsites-design.html" title="OpenACS 4 Subsites Design Document"><link rel="next" href="apm-design.html" title="OpenACS 4.5 Package Manager Design"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="subsites-design.html">Prev</a> </td><th width="60%" align="center">Chapter 7. Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="apm-design.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="apm-requirements"></a>OpenACS 4.5 Package Manager Requirements</h2></div></div><div class="authorblurb"><p>
+by <a href="mailto:bquinn@arsdigita.com" target="_top">Bryan Quinn</a> and <a href="mailto:tnight@arsdigita.com" target="_top">Todd Nightingale</a><br>
+ OpenACS docs are written by the named authors, but may be edited
+ by OpenACS documentation staff.
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="apm-requirements-intro"></a>Introduction</h3></div></div><p>The following is a requirements document for the OpenACS Package Manager
(APM), version 4.0 (APM4). APM4 offers a superset of APM v3.3 functionality
-with the following specific enhancements:</p>
-<div class="itemizedlist"><ul>
-<li><p>A public procedural API. (v 3.3 only has web-based UI)</p></li>
-<li><p>Support for dependency checking.</p></li>
-<li><p>Support for compound packages (to support installation chaining).</p></li>
-<li><p>Support for on-line parameter setting.</p></li>
-<li><p>Support for sub-site level configuration (requires revised ad_parameter
+with the following specific enhancements:</p><div class="itemizedlist"><ul type="disc"><li><p>A public procedural API. (v 3.3 only has web-based UI)</p></li><li><p>Support for dependency checking.</p></li><li><p>Support for compound packages (to support installation chaining).</p></li><li><p>Support for on-line parameter setting.</p></li><li><p>Support for sub-site level configuration (requires revised ad_parameter
and /admin pages at sub-site level; deprecation of site-wide parameter
-file).</p></li>
-</ul></div>
-<p>To differentiate these new requirements from the requirements of version
+file).</p></li></ul></div><p>To differentiate these new requirements from the requirements of version
3.3, all requirements new in v4 are prefaced with the number
-<span class="strong"><i>4</i></span>.</p>
-<p>We gratefully acknowledge the authors of APM 3 for their original design
+<span class="strong"><em>4</em></span>.</p><p>We gratefully acknowledge the authors of APM 3 for their original design
documentation which suggested these features, as well as the influence of the
design and open-source implementation of the Red Hat Package manager, the
Debian packaging system, and PERL's CPAN in the development of the ideas
-behind this document.</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="apm-requirements-vision"></a>Vision Statement</h3></div></div>
-<p>A typical website will tend to offer its users a number of web-based
+behind this document.</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="apm-requirements-vision"></a>Vision Statement</h3></div></div><p>A typical website will tend to offer its users a number of web-based
services or applications, e.g. a bulletin board, calendaring, classified ads,
etc. A website may also have underlying subsystems, such as a permissions
system, content management system, etc. For such applications and subsystem
@@ -65,116 +24,41 @@
disturbance to the rest of the system. This allows site owners to steadily
offer users new and improved services, and also allows programmers to quickly
and easily distribute their OpenACS components in a standardized manner to other
-OpenACS sites.</p>
-<p>In general terms, a package is a unit of software that serves a single
+OpenACS sites.</p><p>In general terms, a package is a unit of software that serves a single
well-defined purpose. The OpenACS Package Manager (APM) provides a mechanism for
packaging, installing, and configuring OpenACS software in a consistent,
-user-friendly, and subsite-aware manner.</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="apm-requirements-system-overview"></a>System Overview</h3></div></div>
-<p>
+user-friendly, and subsite-aware manner.</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="apm-requirements-system-overview"></a>System Overview</h3></div></div><p>
The OpenACS Package Manager (APM) consists of:
-</p>
-<div class="itemizedlist"><ul>
-<li>
-<p>
-<span class="strong"><i>A standard format for APM packages</i></span> including: </p>
-<div class="itemizedlist"><ul>
-<li><p>Version numbering, independent of any other package and the OpenACS as a
-whole</p></li>
-<li><p>Specification of the package interface</p></li>
-<li><p>Specification of dependencies on other packages (if any)</p></li>
-<li><p>Attribution (who wrote it) and ownership (who maintains it)</p></li>
-</ul></div>
-</li>
-<li>
-<p>
-<span class="strong"><i>Web-based tools for package management:</i></span> </p>
-<div class="itemizedlist"><ul>
-<li><p>Obtaining packages from a remote distribution point</p></li>
-<li>
-<p>Installing packages, if and only if: </p>
-<div class="orderedlist"><ol type="1">
-<li><p>All prerequisite packages are installed</p></li>
-<li><p>No conflicts will be created by the installation</p></li>
-</ol></div>
-</li>
-<li><p>Configuring packages (obsoleting the monolithic OpenACS configuration
-file)</p></li>
-<li><p>Upgrading packages, without clobbering local modifications</p></li>
-<li><p>Uninstalling unwanted packages</p></li>
-</ul></div>
-</li>
-<li><p>
-<span class="strong"><i>A registry of installed packages</i></span>, database-backed and
+</p><div class="itemizedlist"><ul type="disc"><li><p><span class="strong"><em>A standard format for APM packages</em></span> including: </p><div class="itemizedlist"><ul type="round"><li><p>Version numbering, independent of any other package and the OpenACS as a
+whole</p></li><li><p>Specification of the package interface</p></li><li><p>Specification of dependencies on other packages (if any)</p></li><li><p>Attribution (who wrote it) and ownership (who maintains it)</p></li></ul></div></li><li><p><span class="strong"><em>Web-based tools for package management:</em></span> </p><div class="itemizedlist"><ul type="round"><li><p>Obtaining packages from a remote distribution point</p></li><li><p>Installing packages, if and only if: </p><div class="orderedlist"><ol type="1"><li><p>All prerequisite packages are installed</p></li><li><p>No conflicts will be created by the installation</p></li></ol></div></li><li><p>Configuring packages (obsoleting the monolithic OpenACS configuration
+file)</p></li><li><p>Upgrading packages, without clobbering local modifications</p></li><li><p>Uninstalling unwanted packages</p></li></ul></div></li><li><p><span class="strong"><em>A registry of installed packages</em></span>, database-backed and
integrated with file system-based version control
-</p></li>
-<li>
-<p>
-<span class="strong"><i>Web-based tools for package development:</i></span> </p>
-<div class="itemizedlist"><ul>
-<li><p>Creating new packages locally</p></li>
-<li><p>Releasing new versions of locally-created packages</p></li>
-<li><p>Uploading packages to a global package repository on the web</p></li>
-<li><p>Use of these tools should be safe, i.e. installing or removing a package
-should never break an OpenACS installation</p></li>
-</ul></div>
-</li>
-<li>
-<p>
-<span class="strong"><i>Web-based tools for package configuration:</i></span> </p>
-<div class="itemizedlist"><ul>
-<li><p>The ability to change package parameter values on-line through a simple
-web interface.</p></li>
-<li><p>A new ad_parameter which does not require a monolithic site-wide
-parameter's file or server restarts for changes to take effect.</p></li>
-<li><p>The ability to manage multiple package instances at the sub-site
-level.</p></li>
-</ul></div>
-</li>
-</ul></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="apm-requirements-use-cases"></a>Use-cases and User-scenarios</h3></div></div>
-<p>
+</p></li><li><p><span class="strong"><em>Web-based tools for package development:</em></span> </p><div class="itemizedlist"><ul type="round"><li><p>Creating new packages locally</p></li><li><p>Releasing new versions of locally-created packages</p></li><li><p>Uploading packages to a global package repository on the web</p></li><li><p>Use of these tools should be safe, i.e. installing or removing a package
+should never break an OpenACS installation</p></li></ul></div></li><li><p><span class="strong"><em>Web-based tools for package configuration:</em></span> </p><div class="itemizedlist"><ul type="round"><li><p>The ability to change package parameter values on-line through a simple
+web interface.</p></li><li><p>A new ad_parameter which does not require a monolithic site-wide
+parameter's file or server restarts for changes to take effect.</p></li><li><p>The ability to manage multiple package instances at the sub-site
+level.</p></li></ul></div></li></ul></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="apm-requirements-use-cases"></a>Use-cases and User-scenarios</h3></div></div><p>
The APM is intended for the following classes of users, which may or may not
-overlap: </p>
-<div class="orderedlist"><ol type="1">
-<li><p>
-<span class="strong"><i>Developers</i></span> (referred to as 'the developer') use
+overlap: </p><div class="orderedlist"><ol type="1"><li><p><span class="strong"><em>Developers</em></span> (referred to as 'the developer') use
the APM to create a software package for distribution and use the procedural
-API for direct control of the APM system.</p></li>
-<li><p>
-<span class="strong"><i>Site-wide administrators</i></span> (referred to as 'the
+API for direct control of the APM system.</p></li><li><p><span class="strong"><em>Site-wide administrators</em></span> (referred to as 'the
administrator') use the APM to install packages for their OpenACS instance,
-and optionally make them available to sub-sites.</p></li>
-<li><p>
-<span class="strong"><i>Sub-site administrators</i></span> (referred to as 'the
+and optionally make them available to sub-sites.</p></li><li><p><span class="strong"><em>Sub-site administrators</em></span> (referred to as 'the
sub-admin') use an administration interface to configure and enable
-packages for their sub-site.</p></li>
-</ol></div>
-<p><span class="strong"><i>Initial Package Development</i></span></p>
-<p>
-<span class="strong"><i>David Developer</i></span> writes a piece of software used to do
+packages for their sub-site.</p></li></ol></div><p><span class="strong"><em>Initial Package Development</em></span></p><p><span class="strong"><em>David Developer</em></span> writes a piece of software used to do
knowledge management (km) for the OpenACS. He distributes his data model,
procedure code, UI pages, and his documentation according to the APM
specification. He splits the documentation and the code into sub-packages,
and creates a KM installation-chain to install both with the APM developer
-UI. Noting that his software was built with <span class="strong"><i>Patricia
-Programmer</i></span>'s Super Widget toolkit, he specifies that as a
+UI. Noting that his software was built with <span class="strong"><em>Patricia
+Programmer</em></span>'s Super Widget toolkit, he specifies that as a
dependency. Moreover, since this package is capable of being used at the
sub-site level, David configures this option in the package. When the package
development is complete, David uses the APM developer UI to construct a
distribution file. He assigns it a version number, 1.0, and makes the package
-available for download at the OpenACS package repository.</p>
-<p><span class="strong"><i>Initial Package Installation</i></span></p>
-<p>
-<span class="strong"><i>Annie Admin</i></span> learns of David's KM system by browsing
+available for download at the OpenACS package repository.</p><p><span class="strong"><em>Initial Package Installation</em></span></p><p><span class="strong"><em>Annie Admin</em></span> learns of David's KM system by browsing
the OpenACS package repository. Annie Admin uses the APM administrator UI
on her system. She selects to install a package from a URL and types the URL
displayed on the system. The APM automatically downloads the package. The
@@ -185,685 +69,230 @@
toolkit. Annie confirms this option. After successfully installing Jim's
toolkit, Annie proceeds to install David's KM system. The data model is
loaded and all of the files necessary for the software are installed. Because
-installation was successful, the package is available for use.</p>
-<p>Since the package is available for use, its initialization routines are
+installation was successful, the package is available for use.</p><p>Since the package is available for use, its initialization routines are
set to run automatically on server startup. Annie is warned that since there
are initialization routines, she must restart the server for the package to
-be ready for use. Annie restarts the server.</p>
-<p><span class="strong"><i>Initial Subsite Use of Package</i></span></p>
-<p>Annie Admin decides to make the KM module available only to a particular
+be ready for use. Annie restarts the server.</p><p><span class="strong"><em>Initial Subsite Use of Package</em></span></p><p>Annie Admin decides to make the KM module available only to a particular
sub-site type on her OpenACS system, and not others. She specifies this option
-using the Sub-site type UI (not part of APM).</p>
-<p>Annie Admin notifies <span class="strong"><i>Sally SubAdmin</i></span> by e-mail that a new
+using the Sub-site type UI (not part of APM).</p><p>Annie Admin notifies <span class="strong"><em>Sally SubAdmin</em></span> by e-mail that a new
package is now available for use. Sally goes to her sub-site /admin page and
sees that a new entry, KM, is available. Sally clicks on it and finds links
to the installed KM documentation and to the web based configuration utility.
Then, Sally configures the package using an automatically generated web
interface and enables KM for use on her sub-site. After some initial use of
the package, Sally decides to change some parameters using the SubAdmin UI.
-These changes take effect immediately, without any server restarts.</p>
-<p><span class="strong"><i>Upgrade Process</i></span></p>
-<p>Sally SubAdmin finds a bug in the KM system and sends a report to David
+These changes take effect immediately, without any server restarts.</p><p><span class="strong"><em>Upgrade Process</em></span></p><p>Sally SubAdmin finds a bug in the KM system and sends a report to David
Developer. David reads the bug report and verifies that the bugs are present
in the current version. Because the bugs are present in the shared procedure
file, David assigns a watch to the file. David makes the necessary
modifications to the source code and saves the file. Because a watch was
assigned to the file, the APM automatically reloads the updated code. David
tests the program and confirms that the bug is fixed. He increments the minor
version number and makes km v 1.1 available for download at the
-repository.</p>
-<p>Sally SubAdmin asks Annie Administrator to upgrade the package using the
+repository.</p><p>Sally SubAdmin asks Annie Administrator to upgrade the package using the
APM UI. This upgrade supersedes the old version of KM at the site-wide level.
Once Annie upgrades the package, the new version starts working immediately
-in Sally's sub-site.</p>
-<p><span class="strong"><i>Procedural API</i></span></p>
-<p>
-<span class="strong"><i>Danielle Developer</i></span> wants her software to perform
+in Sally's sub-site.</p><p><span class="strong"><em>Procedural API</em></span></p><p><span class="strong"><em>Danielle Developer</em></span> wants her software to perform
different actions depending on what version of another package is installed.
She uses the APM procedural API to check if KM version 1.0 is installed or
version 1.1. Based on the results of this procedural call, the software
-exhibits different behavior.</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="apm-requirements-links"></a>Related Links</h3></div></div>
-<div class="itemizedlist"><ul>
-<li><p><a href="/doc/core-arch-guide/apm" target="_top">APM 3.3 Design document</a></p></li>
-<li><p><a href="/doc/packaging" target="_top">Five minute guide to packaging a module</a></p></li>
-<li><p><a href="/doc/core-arch-guide/subcommunities" target="_top">Sub-communities</a></p></li>
-</ul></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="apm-requirements-data-model"></a>Requirements: Data Model</h3></div></div>
-<div class="itemizedlist"><ul>
-<li>
-<p>
-<span class="strong"><i>4.500.0 Package Identification</i></span>
-(All of these items are entered by the developer using the developer UI.) </p>
-<p>
-<span class="strong"><i>4.500.1</i></span> A human readable package key that is guaranteed
+exhibits different behavior.</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="apm-requirements-links"></a>Related Links</h3></div></div><div class="itemizedlist"><ul type="disc"><li><p><a href="/doc/core-arch-guide/apm" target="_top">APM 3.3 Design document</a></p></li><li><p><a href="/doc/packaging" target="_top">Five minute guide to packaging a module</a></p></li><li><p><a href="/doc/core-arch-guide/subcommunities" target="_top">Sub-communities</a></p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="apm-requirements-data-model"></a>Requirements: Data Model</h3></div></div><div class="itemizedlist"><ul type="disc"><li><p><span class="strong"><em>4.500.0 Package Identification</em></span>
+(All of these items are entered by the developer using the developer UI.) </p><p><span class="strong"><em>4.500.1</em></span> A human readable package key that is guaranteed
to be unique to the local OpenACS site must be maintained by the APM. For
-example, "apm."</p>
-<p>
-<span class="strong"><i>4.500.5</i></span> A package id (primary key) that is guaranteed to
+example, "apm."</p><p><span class="strong"><em>4.500.5</em></span> A package id (primary key) that is guaranteed to
be unique to the local site must be maintained by the APM. For example,
-"25."</p>
-<p>
-<span class="strong"><i>4.500.10</i></span> A package URL that is guaranteed to be unique
+"25."</p><p><span class="strong"><em>4.500.10</em></span> A package URL that is guaranteed to be unique
across all sites must be maintained by the APM. The package URL should point
to a server that allows download of the latest version of the package. For
example, "http://openacs.org/software."
-</p>
-</li>
-<li>
-<p>
-<span class="strong"><i>4.505.0 Version Identification</i></span>
- (All of these items are entered by the developer using the developer UI.) </p>
-<p>
-<span class="strong"><i>4.505.1</i></span> A version id (primary key) that is guaranteed to
-be unique to the local site must be maintained by the APM.</p>
-<p>
-<span class="strong"><i>4.505.5</i></span> A version URL that is guaranteed to be unique
+</p></li><li><p><span class="strong"><em>4.505.0 Version Identification</em></span>
+ (All of these items are entered by the developer using the developer UI.) </p><p><span class="strong"><em>4.505.1</em></span> A version id (primary key) that is guaranteed to
+be unique to the local site must be maintained by the APM.</p><p><span class="strong"><em>4.505.5</em></span> A version URL that is guaranteed to be unique
across all sites must be maintained by the APM. The version URL should point
to a server that allows download of a specific version of the package.
-</p>
-</li>
-</ul></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="apm-requirements-api"></a>Requirements: API</h3></div></div>
-<p>The API for APM v3 is explicitly a private API. However, it would be
+</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="apm-requirements-api"></a>Requirements: API</h3></div></div><p>The API for APM v3 is explicitly a private API. However, it would be
useful to obtain information from the APM through a procedural API.
Implementing the API specified below is quite easy given that there are pages
-that already do all of the below in raw SQL.</p>
-<div class="itemizedlist"><ul>
-<li>
-<p>
-<span class="strong"><i>4.400.0 Packages Status Predicates</i></span> </p>
-<p>
-<span class="strong"><i>4.400.1</i></span> Given defining information such as a package URL,
+that already do all of the below in raw SQL.</p><div class="itemizedlist"><ul type="disc"><li><p><span class="strong"><em>4.400.0 Packages Status Predicates</em></span> </p><p><span class="strong"><em>4.400.1</em></span> Given defining information such as a package URL,
the APM API can return the status of the package on the local OpenACS
-instance.</p>
-</li>
-<li>
-<p>
-<span class="strong"><i>4.405.0 Package Information Procedures</i></span> </p>
-<p>
-<span class="strong"><i>4.405.1</i></span> The APM API can return information for any
+instance.</p></li><li><p><span class="strong"><em>4.405.0 Package Information Procedures</em></span> </p><p><span class="strong"><em>4.405.1</em></span> The APM API can return information for any
locally installed packages, including the version number, paths and files,
-and package key.</p>
-</li>
-<li>
-<p>
-<span class="strong"><i>4.410.0 Sub-site Procedures</i></span> </p>
-<p>
-<span class="strong"><i>4.410.1</i></span> After a package has been installed at the
+and package key.</p></li><li><p><span class="strong"><em>4.410.0 Sub-site Procedures</em></span> </p><p><span class="strong"><em>4.410.1</em></span> After a package has been installed at the
site-wide level, the system API will provide means to check for package
-presence, creation, enabling, disabling, and destruction on a subsite.</p>
-</li>
-<li>
-<p>
-<span class="strong"><i>4.415.0 Parameter Values (replaces ad_parameter)</i></span> </p>
-<p>
-<span class="strong"><i>4.415.1</i></span> The system API shall allow subsite parameters for
+presence, creation, enabling, disabling, and destruction on a subsite.</p></li><li><p><span class="strong"><em>4.415.0 Parameter Values (replaces ad_parameter)</em></span> </p><p><span class="strong"><em>4.415.1</em></span> The system API shall allow subsite parameters for
an installed package to be set by either site-wide administrators or sub-site
admins. The subsite parameter can be set to be non-persistent (but default is
to survive server restarts). The subsite parameter can also be set to only
-take effect after a server restart (default is immediate).</p>
-<p>
-<span class="strong"><i>4.415.5</i></span> Parameters for a given subsite and package can be
-returned by the system API.</p>
-</li>
-</ul></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="apm-requirements-security"></a>Requirements: Security</h3></div></div>
-<p>
+take effect after a server restart (default is immediate).</p><p><span class="strong"><em>4.415.5</em></span> Parameters for a given subsite and package can be
+returned by the system API.</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="apm-requirements-security"></a>Requirements: Security</h3></div></div><p>
Provisions will be made to assure that packages are securely
-identified.</p>
-<div class="itemizedlist"><ul>
-<li><p>
-<span class="strong"><i>4.600.1</i></span> Each package will have a PGP signature and there
+identified.</p><div class="itemizedlist"><ul type="disc"><li><p><span class="strong"><em>4.600.1</em></span> Each package will have a PGP signature and there
will be MD5 time stamps for each file within the package.
-</p></li>
-<li><p>
-<span class="strong"><i>4.600.5</i></span> The APM will provide a facility to validate both
-the PGP signature and MD5 stamps information before a package install.</p></li>
-</ul></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="apm-requirements-ui"></a>Requirements: The User Interface</h3></div></div>
-<p>The user interface is a set of HTML pages that are used to drive the
+</p></li><li><p><span class="strong"><em>4.600.5</em></span> The APM will provide a facility to validate both
+the PGP signature and MD5 stamps information before a package install.</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="apm-requirements-ui"></a>Requirements: The User Interface</h3></div></div><p>The user interface is a set of HTML pages that are used to drive the
underlying API. It is restricted to site-wide administrators because the
-actions taken here can dramatically affect the state of the running OpenACS.</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="apm-requirements-dev-interface"></a>Requirements: The Developer's Interface</h3></div></div>
-<p>The intent of the developer's interface is to enable the developer to
+actions taken here can dramatically affect the state of the running OpenACS.</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="apm-requirements-dev-interface"></a>Requirements: The Developer's Interface</h3></div></div><p>The intent of the developer's interface is to enable the developer to
construct and maintain APM packages. It will be possible to disable the
developer's interface for production sites to help reduce the chance of
site failure; much of the functionality here can have cascading effects
-throughout the OpenACS and should not be used on a production site.</p>
-<div class="itemizedlist"><ul>
-<li>
-<p><span class="strong"><i>10.0 Define a package.</i></span></p>
-<p>The developer must be able to create a new package by specifying some
+throughout the OpenACS and should not be used on a production site.</p><div class="itemizedlist"><ul type="disc"><li><p><span class="strong"><em>10.0 Define a package.</em></span></p><p>The developer must be able to create a new package by specifying some
identifying information for the package. This includes a package name, a
-package key, version information, owner information, and a canonical URL.</p>
-<p>
-<span class="strong"><i>10.1</i></span> The APM must maintain the state of all locally
-generated packages.</p>
-<p>
-<span class="strong"><i>10.50</i></span> If the developer fails to provide the required
-information, the package cannot be created.</p>
-<p>
-<span class="strong"><i>10.55</i></span> All of the package information should be editable
-after creation, except for the package key.</p>
-<p>
-<span class="strong"><i>4.10.60</i></span> The package creator must specify whether the
+package key, version information, owner information, and a canonical URL.</p><p><span class="strong"><em>10.1</em></span> The APM must maintain the state of all locally
+generated packages.</p><p><span class="strong"><em>10.50</em></span> If the developer fails to provide the required
+information, the package cannot be created.</p><p><span class="strong"><em>10.55</em></span> All of the package information should be editable
+after creation, except for the package key.</p><p><span class="strong"><em>4.10.60</em></span> The package creator must specify whether the
package is capable of being used in sub-sites, or if only a single, global
-instance of the package is permitted.</p>
-<p>
-<span class="strong"><i>4.10.65</i></span> If the developer fails to provide unique
+instance of the package is permitted.</p><p><span class="strong"><em>4.10.65</em></span> If the developer fails to provide unique
information for unique fields specified in the data model requirements, the
-package cannot be created.</p>
-</li>
-<li>
-<p>
-<span class="strong"><i>20.0 Add files to a package</i></span> </p>
-<p>
-<span class="strong"><i>20.1</i></span> The developer must be able to add files to the
+package cannot be created.</p></li><li><p><span class="strong"><em>20.0 Add files to a package</em></span> </p><p><span class="strong"><em>20.1</em></span> The developer must be able to add files to the
package. This is done by copying the files into the package directory in the
host OS's file system. Files can be added at any point after package
-creation.</p>
-<p>
-<span class="strong"><i>20.3</i></span> Once a package has been versioned and distributed,
+creation.</p><p><span class="strong"><em>20.3</em></span> Once a package has been versioned and distributed,
no new files should be added to the package without incrementing the version
-number.</p>
-<p>
-<span class="strong"><i>20.5</i></span> The APM's UI should facilitate the process of
+number.</p><p><span class="strong"><em>20.5</em></span> The APM's UI should facilitate the process of
adding new files, by scanning the file system for new files automatically,
-and allowing the developer to confirm adding them.</p>
-<p>
-<span class="strong"><i>20.10</i></span> The developer cannot add files to a given package
-via the UI that do not exist in the file system already.</p>
-<p>
-<span class="strong"><i>20.15</i></span> Package file structure must follow a specified
+and allowing the developer to confirm adding them.</p><p><span class="strong"><em>20.10</em></span> The developer cannot add files to a given package
+via the UI that do not exist in the file system already.</p><p><span class="strong"><em>20.15</em></span> Package file structure must follow a specified
convention. Please see the <a href="apm-design.html" title="OpenACS 4.5 Package Manager Design">design
-document</a> for what we do currently.</p>
-</li>
-<li>
-<p><span class="strong"><i>30.0 Remove files from a package</i></span></p>
-<p>The developer must be able to remove files from a package. This can be
-done in two ways.</p>
-<div class="itemizedlist"><ul>
-<li>
-<p>
-<span class="strong"><i>30.1</i></span> Access the APM UI, browse the file list, and remove
-files.</p>
-<p>
-<span class="strong"><i>30.1.1</i></span>If a file is removed from the package list, but not
-from the file system, an error should be generated at package load time.</p>
-</li>
-<li>
-<p>
-<span class="strong"><i>30.5</i></span> Remove the file from file system. </p>
-<p>
-<span class="strong"><i>30.5.1</i></span> The APM UI should take note of the fact that the
+document</a> for what we do currently.</p></li><li><p><span class="strong"><em>30.0 Remove files from a package</em></span></p><p>The developer must be able to remove files from a package. This can be
+done in two ways.</p><div class="itemizedlist"><ul type="round"><li><p><span class="strong"><em>30.1</em></span> Access the APM UI, browse the file list, and remove
+files.</p><p><span class="strong"><em>30.1.1</em></span>If a file is removed from the package list, but not
+from the file system, an error should be generated at package load time.</p></li><li><p><span class="strong"><em>30.5</em></span> Remove the file from file system. </p><p><span class="strong"><em>30.5.1</em></span> The APM UI should take note of the fact that the
file is gone and offer the developer an option to confirm the file's
deletion.
-</p>
-</li>
-</ul></div>
-</li>
-<li>
-<p>
-<span class="strong"><i>40.0 Modify files in a package</i></span>. </p>
-<p>
-<span class="strong"><i>40.1</i></span> The developer should be able to modify files in the
-file system. The APM UI should not interfere with this.</p>
-<p>
-<span class="strong"><i>40.5</i></span> However, if the developer modifies files containing
-procedural definitions, APM UI should allow a means to <span class="strong"><i>watch</i></span>
+</p></li></ul></div></li><li><p><span class="strong"><em>40.0 Modify files in a package</em></span>. </p><p><span class="strong"><em>40.1</em></span> The developer should be able to modify files in the
+file system. The APM UI should not interfere with this.</p><p><span class="strong"><em>40.5</em></span> However, if the developer modifies files containing
+procedural definitions, APM UI should allow a means to <span class="strong"><em>watch</em></span>
those files and automatically reload them if changed. See requirement 50.0
-for more detail.</p>
-<p>
-<span class="strong"><i>40.10</i></span> Also, although a change in files implies that the
+for more detail.</p><p><span class="strong"><em>40.10</em></span> Also, although a change in files implies that the
package distribution file is out of date, it is the developer's
-responsibility to update it.</p>
-</li>
-<li>
-<p>
-<span class="strong"><i>4.45.0 Manage Package Dependency Information</i></span>. </p>
-<p>
-<span class="strong"><i>4.45.1</i></span> The developer should be able to specify which
-interfaces the package requires.</p>
-<p>
-<span class="strong"><i>4.45.5</i></span> The developer should be able to specify which
-interfaces the package provides.</p>
-<p>
-<span class="strong"><i>4.45.10</i></span> Circular dependencies are not allowed.</p>
-</li>
-<li>
-<p>
-<span class="strong"><i>50.0 Watch a file</i></span> </p>
-<p>
-<span class="strong"><i>4.50.1</i></span> The developer should be able to assign a watch to
-any Tcl procedure file, whether in /packages or /tcl.</p>
-<p>
-<span class="strong"><i>50.5</i></span> If a watched file is locally modified, then it will
+responsibility to update it.</p></li><li><p><span class="strong"><em>4.45.0 Manage Package Dependency Information</em></span>. </p><p><span class="strong"><em>4.45.1</em></span> The developer should be able to specify which
+interfaces the package requires.</p><p><span class="strong"><em>4.45.5</em></span> The developer should be able to specify which
+interfaces the package provides.</p><p><span class="strong"><em>4.45.10</em></span> Circular dependencies are not allowed.</p></li><li><p><span class="strong"><em>50.0 Watch a file</em></span> </p><p><span class="strong"><em>4.50.1</em></span> The developer should be able to assign a watch to
+any Tcl procedure file, whether in /packages or /tcl.</p><p><span class="strong"><em>50.5</em></span> If a watched file is locally modified, then it will
be automatically reloaded, thus allowing for any changes made to take affect
-immediately.</p>
-<p>
-<span class="strong"><i>4.50.10</i></span> The setting of a watch should be persistent
+immediately.</p><p><span class="strong"><em>4.50.10</em></span> The setting of a watch should be persistent
across server restarts.
-</p>
-</li>
-<li>
-<p>
-<span class="strong"><i>60.0 Display an XML package specification</i></span> </p>
-<p>
-<span class="strong"><i>60.1</i></span> The developer should be able to view the XML package
+</p></li><li><p><span class="strong"><em>60.0 Display an XML package specification</em></span> </p><p><span class="strong"><em>60.1</em></span> The developer should be able to view the XML package
specification that encodes all package information.
-</p>
-</li>
-<li>
-<p>
-<span class="strong"><i>70.0 Write an XML package specification to the file
-system</i></span> </p>
-<p>
-<span class="strong"><i>70.1</i></span> The developer should be able to write an up-to-date
-XML specification to disk.</p>
-<p>
-<span class="strong"><i>70.5</i></span> The developer should be able to request the current
-XML specification for all installed, locally generated packages.</p>
-</li>
-<li>
-<p>
-<span class="strong"><i>130.0 Distribution file generation</i></span> </p>
-<p>
-<span class="strong"><i>130.1</i></span> The developer should be able to generate a .APM
-distribution file for the package with just one click.</p>
-<p>
-<span class="strong"><i>130.5</i></span> Generating a distribution file implies doing an
+</p></li><li><p><span class="strong"><em>70.0 Write an XML package specification to the file
+system</em></span> </p><p><span class="strong"><em>70.1</em></span> The developer should be able to write an up-to-date
+XML specification to disk.</p><p><span class="strong"><em>70.5</em></span> The developer should be able to request the current
+XML specification for all installed, locally generated packages.</p></li><li><p><span class="strong"><em>130.0 Distribution file generation</em></span> </p><p><span class="strong"><em>130.1</em></span> The developer should be able to generate a .APM
+distribution file for the package with just one click.</p><p><span class="strong"><em>130.5</em></span> Generating a distribution file implies doing an
"up-to-date" check on all of the files. If any of the files have
changed since package installation, then a new version of the package is
created.
-</p>
-</li>
-<li>
-<p>
-<span class="strong"><i>140.0 Access CVS information</i></span> </p>
-<p>
-<span class="strong"><i>140.1</i></span> The developer should be able to determine the CVS
+</p></li><li><p><span class="strong"><em>140.0 Access CVS information</em></span> </p><p><span class="strong"><em>140.1</em></span> The developer should be able to determine the CVS
status of a package, or all packages, with a single click.
-</p>
-</li>
-<li>
-<p>
-<span class="strong"><i>4.200.0 Compound Package Construction</i></span> </p>
-<p>
-<span class="strong"><i>4.200.1</i></span> The developer can include .APM packages
+</p></li><li><p><span class="strong"><em>4.200.0 Compound Package Construction</em></span> </p><p><span class="strong"><em>4.200.1</em></span> The developer can include .APM packages
(sub-packages) within a package (the compound package) like any other
-file.</p>
-<p>
-<span class="strong"><i>4.200.5</i></span> The recommended usage for this feature is to
+file.</p><p><span class="strong"><em>4.200.5</em></span> The recommended usage for this feature is to
allow for separation of optional and required components from the
installation as well as better organization of files once installed. For
example, all documentation for the community-core can be packages as
<tt>community-core-doc.apm</tt>. It is legal to include sub-packages with
dependencies that are not satisfied by the packages in the compound package,
but this is discouraged. In such a case, the sub-package should really be a
-separate package that is required by the compound package.</p>
-<p>
-<span class="strong"><i>4.200.10</i></span> If a sub-package is required for the
+separate package that is required by the compound package.</p><p><span class="strong"><em>4.200.10</em></span> If a sub-package is required for the
installation of the compound package, the compound package should have a
-registered dependency on the sub-package.</p>
-</li>
-</ul></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="apm-requirements-admin-interface"></a>Requirements: The Site-Wide Administrator's Interface</h3></div></div>
-<p>The requirement of the administrator's interface is to enable the
+registered dependency on the sub-package.</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="apm-requirements-admin-interface"></a>Requirements: The Site-Wide Administrator's Interface</h3></div></div><p>The requirement of the administrator's interface is to enable the
administrator to install, enable, upgrade, disable, deinstall, and delete
-packages.</p>
-<div class="itemizedlist"><ul>
-<li>
-<p>
-<span class="strong"><i>80.0 Package Enable/Disable</i></span> </p>
-<p>
-<span class="strong"><i>4.80.1</i></span> The administrator should be able mark an installed
+packages.</p><div class="itemizedlist"><ul type="disc"><li><p><span class="strong"><em>80.0 Package Enable/Disable</em></span> </p><p><span class="strong"><em>4.80.1</em></span> The administrator should be able mark an installed
package as enabled. This means that the package is activated and its
functionality is delivered through the Request Processor. As of OpenACS 4, this
-is done through the sub-site system.</p>
-<p>
-<span class="strong"><i>4.80.5</i></span> Moreover, the administrator must be able to
+is done through the sub-site system.</p><p><span class="strong"><em>4.80.5</em></span> Moreover, the administrator must be able to
disable a package, thereby removing the functionality provided to a sub-site.
As of OpenACS 4, this is done through the sub-site system.
-</p>
-</li>
-<li>
-<p>
-<span class="strong"><i>90.0 Package Install</i></span> </p>
-<p>
-<span class="strong"><i>90.1</i></span> The administrator must be able to install new
-packages either from locally maintained .APM files or from URLs.</p>
-<p>
-<span class="strong"><i>90.5</i></span> In the case of an URL, the APM transparently
+</p></li><li><p><span class="strong"><em>90.0 Package Install</em></span> </p><p><span class="strong"><em>90.1</em></span> The administrator must be able to install new
+packages either from locally maintained .APM files or from URLs.</p><p><span class="strong"><em>90.5</em></span> In the case of an URL, the APM transparently
downloads the APM file off the web, proceeds with a file based installation,
-and then optionally removes the .APM file just downloaded.</p>
-<p>
-<span class="strong"><i>90.10.1</i></span> If .APM files are present in a package, then it
-is considered a compound package (use 4.210.0).</p>
-<p>
-<span class="strong"><i>90.15.0</i></span> Installation requires these steps:</p>
-<div class="orderedlist"><ol type="1">
-<li><p>
-<span class="strong"><i>90.15.1</i></span>The package dependencies are scanned. If some
+and then optionally removes the .APM file just downloaded.</p><p><span class="strong"><em>90.10.1</em></span> If .APM files are present in a package, then it
+is considered a compound package (use 4.210.0).</p><p><span class="strong"><em>90.15.0</em></span> Installation requires these steps:</p><div class="orderedlist"><ol type="1"><li><p><span class="strong"><em>90.15.1</em></span>The package dependencies are scanned. If some
dependencies are not present, the system warns the administrator that
-installation cannot proceed until those packages are installed.</p></li>
-<li><p>
-<span class="strong"><i>90.15.2</i></span> Assuming all dependencies are present, APM
-extracts the contents of the APM file into the /packages directory.</p></li>
-<li><p>
-<span class="strong"><i>90.15.3</i></span> The administrator is offered the option of
-importing directly into CVS.</p></li>
-<li><p>
-<span class="strong"><i>90.15.4</i></span> The administrator is given a list of data model
-scripts found in the package and can select which ones to be executed.</p></li>
-<li><p>
-<span class="strong"><i>90.15.5</i></span> If no errors are recorded during this process,
-the package is enabled.</p></li>
-</ol></div>
-</li>
-<li>
-<p>
-<span class="strong"><i>4.210.0 Compound package Install</i></span> </p>
-<p>
-<span class="strong"><i>4.210.1</i></span> If .APM files are present in a package, then it
-is considered a compound package.</p>
-<p>
-<span class="strong"><i>4.210.5.0</i></span> Installation of a compound package proceeds
-according to the following sequence:</p>
-<div class="orderedlist"><ol type="1">
-<li><p>
-<span class="strong"><i>4.210.5.1</i></span> Identify the set of all sub-packages within
-the compound package by scanning for all files with .APM.</p></li>
-<li><p>
-<span class="strong"><i>4.210.5.2</i></span> Identify which sub-packages are required by
+installation cannot proceed until those packages are installed.</p></li><li><p><span class="strong"><em>90.15.2</em></span> Assuming all dependencies are present, APM
+extracts the contents of the APM file into the /packages directory.</p></li><li><p><span class="strong"><em>90.15.3</em></span> The administrator is offered the option of
+importing directly into CVS.</p></li><li><p><span class="strong"><em>90.15.4</em></span> The administrator is given a list of data model
+scripts found in the package and can select which ones to be executed.</p></li><li><p><span class="strong"><em>90.15.5</em></span> If no errors are recorded during this process,
+the package is enabled.</p></li></ol></div></li><li><p><span class="strong"><em>4.210.0 Compound package Install</em></span> </p><p><span class="strong"><em>4.210.1</em></span> If .APM files are present in a package, then it
+is considered a compound package.</p><p><span class="strong"><em>4.210.5.0</em></span> Installation of a compound package proceeds
+according to the following sequence:</p><div class="orderedlist"><ol type="1"><li><p><span class="strong"><em>4.210.5.1</em></span> Identify the set of all sub-packages within
+the compound package by scanning for all files with .APM.</p></li><li><p><span class="strong"><em>4.210.5.2</em></span> Identify which sub-packages are required by
checking the dependencies of the compound package. If there dependencies not
satisfied by the current system or the packages included with the compound
package, halt installation and inform user to install these packages
-first.</p></li>
-<li><p>
-<span class="strong"><i>4.210.5.3</i></span> Present Administrator with the ability to
+first.</p></li><li><p><span class="strong"><em>4.210.5.3</em></span> Present Administrator with the ability to
choose which sub-packages to install. Required sub-packages must be
-installed.</p></li>
-<li><p>
-<span class="strong"><i>4.210.5.4</i></span> Proceed with the installation of each
+installed.</p></li><li><p><span class="strong"><em>4.210.5.4</em></span> Proceed with the installation of each
sub-package, starting with required packages. If the sub-package is already
installed, then do nothing. Else, If the sub-package is a normal package,
-proceed according to <span class="strong"><i>90.15.0</i></span>, otherwise if it is a compound
-package, proceed according to <span class="strong"><i>4.210.5.0</i></span>.</p></li>
-<li><p>
-<span class="strong"><i>4.210.5.5</i></span> If all required sub-packages are installed,
+proceed according to <span class="strong"><em>90.15.0</em></span>, otherwise if it is a compound
+package, proceed according to <span class="strong"><em>4.210.5.0</em></span>.</p></li><li><p><span class="strong"><em>4.210.5.5</em></span> If all required sub-packages are installed,
proceed to install non-required sub-packages. If there was a failure during
the installation of a required sub-package, then the installation of the
-compound package is also a failure.</p></li>
-<li><p>
-<span class="strong"><i>4.210.5.6</i></span> Any attempt to install a compound package in
+compound package is also a failure.</p></li><li><p><span class="strong"><em>4.210.5.6</em></span> Any attempt to install a compound package in
the future involves a choice presented to the admin of installing any
-uninstalled sub-packages.</p></li>
-</ol></div>
-</li>
-<li>
-<p><span class="strong"><i>4.220.0 Recovering from failed package installation</i></span></p>
-<p>
-<span class="strong"><i>4.220.1</i></span> If any error is generated during package
+uninstalled sub-packages.</p></li></ol></div></li><li><p><span class="strong"><em>4.220.0 Recovering from failed package installation</em></span></p><p><span class="strong"><em>4.220.1</em></span> If any error is generated during package
installation, the package is not considered installed. To recover from this
-failure, the package should be selected for installation again.</p>
-</li>
-<li>
-<p>
-<span class="strong"><i>100.0 Version Upgrade</i></span> </p>
-<p>
-<span class="strong"><i>100.1</i></span> The administrator can upgrade to a new version of a
-package. This entails</p>
-<div class="orderedlist"><ol type="1">
-<li><p>
-<span class="strong"><i>100.1.1</i></span> Running any necessary and included upgrade
-scripts.</p></li>
-<li><p>
-<span class="strong"><i>100.1.5</i></span> Replacing any old files with new versions.</p></li>
-<li><p>
-<span class="strong"><i>100.1.10</i></span> Marking the old version of the package as
-'superseded' and disabling it.</p></li>
-<li><p>
-<span class="strong"><i>100.1.15</i></span> Assuming no errors from above, the new package
-is enabled.</p></li>
-</ol></div>
-</li>
-<li>
-<p>
-<span class="strong"><i>110.0 Package Deinstall</i></span> </p>
-<p>
-<span class="strong"><i>110.1</i></span> The administrator must be able to deinstall a
-package that has already been installed. Deinstallation entails:</p>
-<div class="orderedlist"><ol type="1">
-<li><p>
-<span class="strong"><i>110.1.1</i></span> Running any data model scripts necessary to drop
-the package.</p></li>
-<li><p>
-<span class="strong"><i>110.1.5</i></span> Moving all of the files into a separate location
-in the file system from the installed packages.</p></li>
-<li><p>
-<span class="strong"><i>4.110.1.10</i></span> If the package is a compound package, then
+failure, the package should be selected for installation again.</p></li><li><p><span class="strong"><em>100.0 Version Upgrade</em></span> </p><p><span class="strong"><em>100.1</em></span> The administrator can upgrade to a new version of a
+package. This entails</p><div class="orderedlist"><ol type="1"><li><p><span class="strong"><em>100.1.1</em></span> Running any necessary and included upgrade
+scripts.</p></li><li><p><span class="strong"><em>100.1.5</em></span> Replacing any old files with new versions.</p></li><li><p><span class="strong"><em>100.1.10</em></span> Marking the old version of the package as
+'superseded' and disabling it.</p></li><li><p><span class="strong"><em>100.1.15</em></span> Assuming no errors from above, the new package
+is enabled.</p></li></ol></div></li><li><p><span class="strong"><em>110.0 Package Deinstall</em></span> </p><p><span class="strong"><em>110.1</em></span> The administrator must be able to deinstall a
+package that has already been installed. Deinstallation entails:</p><div class="orderedlist"><ol type="1"><li><p><span class="strong"><em>110.1.1</em></span> Running any data model scripts necessary to drop
+the package.</p></li><li><p><span class="strong"><em>110.1.5</em></span> Moving all of the files into a separate location
+in the file system from the installed packages.</p></li><li><p><span class="strong"><em>4.110.1.10</em></span> If the package is a compound package, then
the administrator must confirm removing all sub-packages. Optionally, some
-sub-packages can be kept.</p></li>
-</ol></div>
-<p>
-<span class="strong"><i>110.5</i></span> Deinstalled packages can be re-installed at a later
-date.</p>
-<p>
-<span class="strong"><i>4.110.10</i></span> If deinstalling a package or any of its
+sub-packages can be kept.</p></li></ol></div><p><span class="strong"><em>110.5</em></span> Deinstalled packages can be re-installed at a later
+date.</p><p><span class="strong"><em>4.110.10</em></span> If deinstalling a package or any of its
sub-packages breaks a dependency, then deinstallation cannot proceed until
-the package registering the dependency is removed.</p>
-</li>
-<li>
-<p>
-<span class="strong"><i>120.0 Package Deletion</i></span> </p>
-<p>
-<span class="strong"><i>120.1</i></span> The administrator should be able to completely
+the package registering the dependency is removed.</p></li><li><p><span class="strong"><em>120.0 Package Deletion</em></span> </p><p><span class="strong"><em>120.1</em></span> The administrator should be able to completely
erase all records of the package. This involves removing all instances of the
-package, all related database tables and content.</p>
-<p>
-<span class="strong"><i>120.5</i></span> This option can only be used if all package
+package, all related database tables and content.</p><p><span class="strong"><em>120.5</em></span> This option can only be used if all package
instances are deleted or marked as disabled. This is purposefully cumbersome
because deleting all instances of a package can have far-sweeping
-consequences throughout a site and should almost never be done.</p>
-</li>
-<li>
-<p>
-<span class="strong"><i>150.0 Scan for new or modified packages</i></span> </p>
-<p>
-<span class="strong"><i>150.1</i></span> The administrator should be able to scan the file
-system for any changes made in any of the installed package files.</p>
-<p>
-<span class="strong"><i>150.5</i></span> The administrator should be able to scan the file
+consequences throughout a site and should almost never be done.</p></li><li><p><span class="strong"><em>150.0 Scan for new or modified packages</em></span> </p><p><span class="strong"><em>150.1</em></span> The administrator should be able to scan the file
+system for any changes made in any of the installed package files.</p><p><span class="strong"><em>150.5</em></span> The administrator should be able to scan the file
system for any newly installed packages.
-</p>
-</li>
-</ul></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="apm-requirements-sub-admin-intf"></a>Requirements: The Sub-Site Administrator's Interface</h3></div></div>
-<p>
+</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="apm-requirements-sub-admin-intf"></a>Requirements: The Sub-Site Administrator's Interface</h3></div></div><p>
If the developer is in charge of creating packages and the administrator for
installing them, then the sub-site administrator is responsible for
configuring and enabling packages. In order for a package to be available for
a sub-site it must be associated with the sub-site's type specification.
This interface is part of the sub-site /admin interface.
-</p>
-<div class="itemizedlist"><ul>
-<li>
-<p>
-<span class="strong"><i>4.300</i></span> Creating a package instance. </p>
-<p>
-<span class="strong"><i>4.300.1</i></span> From the sub-site /admin interface, there should
+</p><div class="itemizedlist"><ul type="disc"><li><p><span class="strong"><em>4.300</em></span> Creating a package instance. </p><p><span class="strong"><em>4.300.1</em></span> From the sub-site /admin interface, there should
be an option to view all packages available in the system as well as an
-option to add a package to the subsite.</p>
-<p>
-<span class="strong"><i>4.300.5</i></span> From the "add" option, the sub-admin
+option to add a package to the subsite.</p><p><span class="strong"><em>4.300.5</em></span> From the "add" option, the sub-admin
can select from a list of packages registered as available in the sub-site
-type to which the sub-site belongs.</p>
-<p>
-<span class="strong"><i>4.300.19</i></span> Once a package instance is added, it is
-available on the list of the subsite's available packages.</p>
-</li>
-<li>
-<p>
-<span class="strong"><i>4.305</i></span> Configuring a package instance. </p>
-<p>
-<span class="strong"><i>4.305.1</i></span> An automatic web interface that lists all
-parameters with current values must be available.</p>
-<p>
-<span class="strong"><i>4.305.5</i></span> Changing the values for the parameters is
-accomplished simply by submitting an HTML form.</p>
-</li>
-<li>
-<p>
-<span class="strong"><i>4.310</i></span> Enabling a package instance. </p>
-<p>
-<span class="strong"><i>4.310.1</i></span> The sub-admin should be able to enable a package
+type to which the sub-site belongs.</p><p><span class="strong"><em>4.300.19</em></span> Once a package instance is added, it is
+available on the list of the subsite's available packages.</p></li><li><p><span class="strong"><em>4.305</em></span> Configuring a package instance. </p><p><span class="strong"><em>4.305.1</em></span> An automatic web interface that lists all
+parameters with current values must be available.</p><p><span class="strong"><em>4.305.5</em></span> Changing the values for the parameters is
+accomplished simply by submitting an HTML form.</p></li><li><p><span class="strong"><em>4.310</em></span> Enabling a package instance. </p><p><span class="strong"><em>4.310.1</em></span> The sub-admin should be able to enable a package
with a single click. Enabling a package means that the OpenACS will serve its
URLs properly.
-</p>
-</li>
-<li>
-<p>
-<span class="strong"><i>4.315</i></span> Disabling a package instance. </p>
-<p>
-<span class="strong"><i>4.315.1</i></span> The sub-admin should be able to disable a package
+</p></li><li><p><span class="strong"><em>4.315</em></span> Disabling a package instance. </p><p><span class="strong"><em>4.315.1</em></span> The sub-admin should be able to disable a package
with a single click. Disabling a package means that the OpenACS will no longer
-serve those URLs.</p>
-</li>
-<li>
-<p>
-<span class="strong"><i>4.320</i></span> Deleting a package instance. </p>
-<p>
-<span class="strong"><i>4.320.1</i></span> Deleting a package instance involves deleting not
+serve those URLs.</p></li><li><p><span class="strong"><em>4.320</em></span> Deleting a package instance. </p><p><span class="strong"><em>4.320.1</em></span> Deleting a package instance involves deleting not
only the package instance, but any and all content associated with it. It is
questionable whether this option should even be available due to its drastic
consequences. Reviewer comments appreciated.
-</p>
-</li>
-</ul></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="apm-requirements-implementation"></a>Implementation notes</h3></div></div>
-<p>Despite the fact that requirements are meant to be design/implementation
+</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="apm-requirements-implementation"></a>Implementation notes</h3></div></div><p>Despite the fact that requirements are meant to be design/implementation
neutral, the following thoughts were in our head when specifying these
requirements. You must be familiar with the new object design for this to be
-comprehensible.</p>
-<p>When a package is installed system-wide, a corresponding acs_object_type
+comprehensible.</p><p>When a package is installed system-wide, a corresponding acs_object_type
is created for it. All parameters registered for the package are registered
-for that acs_object_type.</p>
-<p>When a package instance is created, it is an acs_object. Its parameters
+for that acs_object_type.</p><p>When a package instance is created, it is an acs_object. Its parameters
are set using the acs_attribute_values table. The automatic web interface for
setting package parameters should be one and the same with the interface for
setting acs object attribute values. Consequently, the implementation of
-these features should be quite straightforward.</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="apm-requirements-rev-history"></a>Revision History</h3></div></div>
-<div class="informaltable"><table border="1">
-<colgroup>
-<col>
-<col>
-<col>
-<col>
-</colgroup>
-<tbody>
-<tr>
-<td><span class="strong"><i>Document Revision #</i></span></td>
-<td><span class="strong"><i>Action Taken, Notes</i></span></td>
-<td><span class="strong"><i>When?</i></span></td>
-<td><span class="strong"><i>By Whom?</i></span></td>
-</tr>
-<tr>
-<td>0.1</td>
-<td>Creation</td>
-<td>8/10/2000</td>
-<td>Bryan Quinn, Todd Nightingale</td>
-</tr>
-<tr>
-<td>�</td>
-<td>Reviewed</td>
-<td>8/11/2000</td>
-<td>John Prevost, Mark Thomas, and Pete Su</td>
-</tr>
-<tr>
-<td>0.2</td>
-<td>Revised and updated</td>
-<td>8/12/2000</td>
-<td>Bryan Quinn</td>
-</tr>
-<tr>
-<td>0.3</td>
-<td>Reviewed, revised, and updated - conforms to requirements template.</td>
-<td>8/18/2000</td>
-<td>Kai Wu</td>
-</tr>
-<tr>
-<td>0.4</td>
-<td>Minor edits before ACS 4 Beta.</td>
-<td>9/30/2000</td>
-<td>Kai Wu</td>
-</tr>
-</tbody>
-</table></div>
-</div>
-</div>
-<div class="navfooter">
-<hr>
-<table width="100%" summary="Navigation footer">
-<tr>
-<td width="40%" align="left">
-<a accesskey="p" href="subsites-design.html">Prev</a> </td>
-<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
-<td width="40%" align="right"> <a accesskey="n" href="apm-design.html">Next</a>
-</td>
-</tr>
-<tr>
-<td width="40%" align="left">OpenACS 4 Subsites Design Document </td>
-<td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td>
-<td width="40%" align="right"> OpenACS 4.5 Package Manager Design</td>
-</tr>
-</table>
-<hr>
-<address>
- rmello at fslc.usu.edu
- </address>
-<address><a href="mailto:vinod@kurup.com">
+these features should be quite straightforward.</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="apm-requirements-rev-history"></a>Revision History</h3></div></div><div class="informaltable"><table border="1"><colgroup><col><col><col><col></colgroup><tbody><tr><td><span class="strong"><em>Document Revision #</em></span></td><td><span class="strong"><em>Action Taken, Notes</em></span></td><td><span class="strong"><em>When?</em></span></td><td><span class="strong"><em>By Whom?</em></span></td></tr><tr><td>0.1</td><td>Creation</td><td>8/10/2000</td><td>Bryan Quinn, Todd Nightingale</td></tr><tr><td>�</td><td>Reviewed</td><td>8/11/2000</td><td>John Prevost, Mark Thomas, and Pete Su</td></tr><tr><td>0.2</td><td>Revised and updated</td><td>8/12/2000</td><td>Bryan Quinn</td></tr><tr><td>0.3</td><td>Reviewed, revised, and updated - conforms to requirements template.</td><td>8/18/2000</td><td>Kai Wu</td></tr><tr><td>0.4</td><td>Minor edits before ACS 4 Beta.</td><td>9/30/2000</td><td>Kai Wu</td></tr></tbody></table></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="subsites-design.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="apm-design.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS 4 Subsites Design Document </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> OpenACS 4.5 Package Manager Design</td></tr></table><hr><address>rmello at fslc.usu.edu</address><address><a href="mailto:vinod@kurup.com">
vinod@kurup.com
- </a></address>
-</div>
-</body>
-</html>
+ </a></address></div></body></html>
Index: openacs-4/packages/acs-core-docs/www/bootstrap-acs.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/bootstrap-acs.html,v
diff -u -r1.7 -r1.7.2.1
--- openacs-4/packages/acs-core-docs/www/bootstrap-acs.html 7 Mar 2002 06:55:36 -0000 1.7
+++ openacs-4/packages/acs-core-docs/www/bootstrap-acs.html 15 May 2002 23:26:18 -0000 1.7.2.1
@@ -1,179 +1,92 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type">
-<title>Bootstrapping OpenACS</title>
-<meta name="generator" content="DocBook XSL Stylesheets V1.45">
-<link rel="home" href="index.html" title="OpenACS Documentation">
-<link rel="up" href="kernel-doc.html" title="Chapter 7. Kernel Documentation">
-<link rel="previous" href="tcl-doc.html" title="Documenting Tcl Files: Page Contracts and Libraries">
-<link rel="stylesheet" href="openacs.css" type="text/css">
-</head>
-<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-<div class="navheader">
-<a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr>
-<td width="20%" align="left">
-<a accesskey="p" href="tcl-doc.html">Prev</a> </td>
-<th width="60%" align="center">Chapter 7. Kernel Documentation</th>
-<td width="20%" align="right"> </td>
-</tr></table>
-<hr>
-</div>
-<div class="sect1">
-<div class="titlepage"><div><h2 class="title" style="clear: both">
-<a name="bootstrap-acs"></a>Bootstrapping OpenACS</h2></div></div>
-<div class="authorblurb"><p>
-by <a href="mailto:jsalz@mit.edu" target="_top">Jon Salz</a>
-</p></div>
-<div class="itemizedlist"><ul><li><p>Tcl code: /tcl/0-acs-init.tcl and /packages/acs-kernel/bootstrap.tcl</p></li></ul></div>
-<p>This document describes the startup (bootstrapping) process for an AOLserver
+<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"><title>Bootstrapping OpenACS</title><meta name="generator" content="DocBook XSL Stylesheets V1.50.0"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="kernel-doc.html" title="Chapter 7. Kernel Documentation"><link rel="previous" href="tcl-doc.html" title="Documenting Tcl Files: Page Contracts and Libraries"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tcl-doc.html">Prev</a> </td><th width="60%" align="center">Chapter 7. Kernel Documentation</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="bootstrap-acs"></a>Bootstrapping OpenACS</h2></div></div><div class="authorblurb"><p>
+by <a href="mailto:jsalz@mit.edu" target="_top">Jon Salz</a><br>
+ OpenACS docs are written by the named authors, but may be edited
+ by OpenACS documentation staff.
+ </p></div><div class="itemizedlist"><ul type="disc"><li><p>Tcl code: /tcl/0-acs-init.tcl and /packages/acs-kernel/bootstrap.tcl</p></li></ul></div><p>This document describes the startup (bootstrapping) process for an AOLserver
running OpenACS.
-</p>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="bootstrap-acs-bigpicture"></a>The Big Picture</h3></div></div>
-<p>
+</p><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="bootstrap-acs-bigpicture"></a>The Big Picture</h3></div></div><p>
Before OpenACS 3.3, the OpenACS startup process was extremely simple: after AOLserver
performed its internal initialization (reading the configuration file,
loading shared libraries and module code, etc.) it scanned through the Tcl
-library directory (generally <tt>/web/</tt><span class="emphasis"><i><tt>yourservername</tt></i></span><tt>/tcl</tt>),
+library directory (generally <tt>/web/</tt><span class="emphasis"><em><tt>yourservername</tt></em></span><tt>/tcl</tt>),
sourcing each file in sequence.
-</p>
-<p>While this overall structure for initialization is still intact, package
+</p><p>While this overall structure for initialization is still intact, package
management has thrown a wrench into the works - there are a few extra things
-to do during initialization, most notably:</p>
-<div class="itemizedlist"><ul>
-<li><p>Examine the OpenACS file tree for files that should not be present in OpenACS
+to do during initialization, most notably:</p><div class="itemizedlist"><ul type="disc"><li><p>Examine the OpenACS file tree for files that should not be present in OpenACS
(i.e., that were once part of the OpenACS distribution but have since been
-removed).</p></li>
-<li><p>Scan the <tt>/packages</tt> directory for new packages.</p></li>
-<li><p>Initialize enabled packages by sourcing their <tt>*-procs.tcl</tt>
-and <tt>*-init.tcl</tt> files.</p></li>
-</ul></div>
-<p>
+removed).</p></li><li><p>Scan the <tt>/packages</tt> directory for new packages.</p></li><li><p>Initialize enabled packages by sourcing their <tt>*-procs.tcl</tt>
+and <tt>*-init.tcl</tt> files.</p></li></ul></div><p>
This document examines in detail each of the steps involved in AOLserver/OpenACS
startup.
-</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="bootstrap-acs-startup-process"></a>The Startup Process</h3></div></div>
-<p>
+</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="bootstrap-acs-startup-process"></a>The Startup Process</h3></div></div><p>
As soon as the <tt>nsd</tt> daemon is executed by the <tt>init</tt>
process (or otherwise), AOLserver reads its configuration file and
<tt>chroot</tt>s itself if necessary. It then loads shared libraries
indicated in the <tt>.ini</tt> file (e.g., the Oracle driver and
<tt>nssock</tt>), and sources Tcl module files (generally in
<tt>/home/aol30/modules/tcl</tt>). This step is, and has always been, the
same for all AOLservers, regardless of whether they are running OpenACS.
-</p>
-<p>Next AOLserver sources, in lexicographical order, each file in the
+</p><p>Next AOLserver sources, in lexicographical order, each file in the
<tt>/tcl</tt> directory. The first such file is
<tt>0-acs-init.tcl</tt>, which doesn't do much directly except to
-determine the OpenACS path root (e.g., <tt>/web/</tt><span class="emphasis"><i><tt>yourservername</tt></i></span>)
+determine the OpenACS path root (e.g., <tt>/web/</tt><span class="emphasis"><em><tt>yourservername</tt></em></span>)
by trimming the final component from the path to the Tcl library directory
-(<tt>/web/</tt><span class="emphasis"><i><tt>yourservername</tt></i></span><tt>/tcl</tt>). But
+(<tt>/web/</tt><span class="emphasis"><em><tt>yourservername</tt></em></span><tt>/tcl</tt>). But
<tt>0-acs-init.tcl</tt>'s has an important function, namely sourcing
-<tt>/packages/acs-core/bootstrap.tcl</tt>, which does the following:</p>
-<div class="orderedlist"><ol type="1">
-<li><p>
-<span class="strong"><i>Initialize some NSVs used by the core</i></span>. These NSVs are
+<tt>/packages/acs-core/bootstrap.tcl</tt>, which does the following:</p><div class="orderedlist"><ol type="1"><li><p><span class="strong"><em>Initialize some NSVs used by the core</em></span>. These NSVs are
documented in <tt>/packages/acs-core/apm-procs.tcl</tt> - no need to
worry about them unless you're an OpenACS core hacker.
-</p></li>
-<li><p>
-<span class="strong"><i>Verify the deletion of obsolete OpenACS files</i></span>. The
+</p></li><li><p><span class="strong"><em>Verify the deletion of obsolete OpenACS files</em></span>. The
<tt>/tcl</tt> directory has evolved quite a bit over the months and
years, and a few files have come and gone. The
<tt>/www/doc/removed-files.txt</tt> file contains a list of files which
-<span class="emphasis"><i>must be deleted</i></span> from the AOLserver installation, at the risk of
+<span class="emphasis"><em>must be deleted</em></span> from the AOLserver installation, at the risk of
causing weird conflicts, e.g., having several security filters registered.
<tt>bootstrap.tcl</tt> scans through this list, logging error messages to
the log if any of these files exist.
-</p></li>
-<li><p>
-<span class="strong"><i>Source <tt>*-procs.tcl</tt> files in the OpenACS core</i></span>.
+</p></li><li><p><span class="strong"><em>Source <tt>*-procs.tcl</tt> files in the OpenACS core</em></span>.
We source each file matching the <tt>*-procs.tcl</tt> glob in the
<tt>/packages/acs-kernel</tt> directory, in lexicographical order. These
procedure are needed to perform any of the following steps.
-</p></li>
-<li><p>
-<span class="strong"><i>Ensure that the database is available</i></span> by grabbing and
+</p></li><li><p><span class="strong"><em>Ensure that the database is available</em></span> by grabbing and
releasing a handle. If we can't obtain a handle, we terminate
initialization (since OpenACS couldn't possibly start up the server without
access to the database).
-</p></li>
-<li><p>
-<span class="strong"><i>Register any new packages in the <tt>/packages</tt>
-directory</i></span>. In each directory inside <tt>/packages</tt>, we look
+</p></li><li><p><span class="strong"><em>Register any new packages in the <tt>/packages</tt>
+directory</em></span>. In each directory inside <tt>/packages</tt>, we look
for a <tt>.info</tt> file; if we find a package that hasn't yet been
registered with the package manager (i.e., it's been copied there
manually), we insert information about it into the database. (The first time
-OpenACS starts up, <span class="emphasis"><i>no</i></span> packages will have been registered in the database
+OpenACS starts up, <span class="emphasis"><em>no</em></span> packages will have been registered in the database
yet, so this step will registers every single package in the
<tt>/packages</tt> directory.) Note that packages discovered here are
initially disabled; they must be manually enabled in the package manager
before they can be used.
-</p></li>
-<li><p>
-<span class="strong"><i>Ensure that the <tt>acs-kernel</tt> package is
-enabled</i></span>. If the OpenACS core isn't initialized, the server
+</p></li><li><p><span class="strong"><em>Ensure that the <tt>acs-kernel</tt> package is
+enabled</em></span>. If the OpenACS core isn't initialized, the server
couldn't possibly be operational, so if there's no enabled version of
the OpenACS core we simply mark the latest installed one as enabled.
-</p></li>
-<li><p>
-<span class="strong"><i>Load <tt>*-procs.tcl</tt> files for enabled
-packages</i></span>, activating their APIs.
+</p></li><li><p><span class="strong"><em>Load <tt>*-procs.tcl</tt> files for enabled
+packages</em></span>, activating their APIs.
-</p></li>
-<li><p>
-<span class="strong"><i>Load <tt>*-init.tcl</tt> files for enabled packages</i></span>,
+</p></li><li><p><span class="strong"><em>Load <tt>*-init.tcl</tt> files for enabled packages</em></span>,
giving packages a chance to register filters and procedures, initialize data
structures, etc.
-</p></li>
-<li><p>
-<span class="strong"><i>Verify that the core has been properly initialized</i></span> by
+</p></li><li><p><span class="strong"><em>Verify that the core has been properly initialized</em></span> by
checking for the existence of an NSV created by the request processor
initialization code. If it's not present, the server won't be
-operational, so we log an error.</p></li>
-</ol></div>
-<p>
+operational, so we log an error.</p></li></ol></div><p>
At this point, <tt>bootstrap.tcl</tt> is done executing. AOLserver
proceeds to source the remaining files in the <tt>/tcl</tt> directory
(i.e., unpackaged libraries) and begins listening for connections.
-</p>
-<p><div class="cvstag">($Id$)</div></p>
-</div>
-</div>
-<div class="navfooter">
-<hr>
-<table width="100%" summary="Navigation footer">
-<tr>
-<td width="40%" align="left">
-<a accesskey="p" href="tcl-doc.html">Prev</a> </td>
-<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
-<td width="40%" align="right"> </td>
-</tr>
-<tr>
-<td width="40%" align="left">Documenting Tcl Files: Page Contracts and Libraries </td>
-<td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td>
-<td width="40%" align="right"> </td>
-</tr>
-</table>
-<hr>
-<address>
- rmello at fslc.usu.edu
- </address>
-<address><a href="mailto:vinod@kurup.com">
+</p><p><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tcl-doc.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left">Documenting Tcl Files: Page Contracts and Libraries </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> </td></tr></table><hr><address>rmello at fslc.usu.edu</address><address><a href="mailto:vinod@kurup.com">
vinod@kurup.com
- </a></address>
-</div>
-</body>
-</html>
+ </a></address></div></body></html>
Index: openacs-4/packages/acs-core-docs/www/credits.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/credits.html,v
diff -u -r1.7 -r1.7.2.1
--- openacs-4/packages/acs-core-docs/www/credits.html 7 Mar 2002 06:55:36 -0000 1.7
+++ openacs-4/packages/acs-core-docs/www/credits.html 15 May 2002 23:26:18 -0000 1.7.2.1
@@ -1,50 +1,21 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type">
-<title>Credits</title>
-<meta name="generator" content="DocBook XSL Stylesheets V1.45">
-<link rel="home" href="index.html" title="OpenACS Documentation">
-<link rel="up" href="unix-install.html" title="Chapter 2. Installing on Unix/Linux">
-<link rel="previous" href="nextsteps.html" title="Next Steps">
-<link rel="next" href="win-install.html" title="Chapter 3. Installing on Windows">
-<link rel="stylesheet" href="openacs.css" type="text/css">
-</head>
-<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-<div class="navheader">
-<a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr>
-<td width="20%" align="left">
-<a accesskey="p" href="nextsteps.html">Prev</a> </td>
-<th width="60%" align="center">Chapter 2. Installing on Unix/Linux</th>
-<td width="20%" align="right"> <a accesskey="n" href="win-install.html">Next</a>
-</td>
-</tr></table>
-<hr>
-</div>
-<div class="sect1">
-<div class="titlepage"><div><h2 class="title" style="clear: both">
-<a name="credits"></a>Credits</h2></div></div>
-<p>
-<a href="mailto:vinod@kurup.com" target="_top">Vinod Kurup</a> put
+<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"><title>Credits</title><meta name="generator" content="DocBook XSL Stylesheets V1.50.0"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="unix-install.html" title="Chapter 2. Installing on Unix/Linux"><link rel="previous" href="nextsteps.html" title="Next Steps"><link rel="next" href="win-install.html" title="Chapter 3. Installing on Windows"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="nextsteps.html">Prev</a> </td><th width="60%" align="center">Chapter 2. Installing on Unix/Linux</th><td width="20%" align="right"> <a accesskey="n" href="win-install.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="credits"></a>Credits</h2></div></div><div class="authorblurb"><p>
+ by <a href="mailto:vinod@kurup.com" target="_top">Vinod Kurup</a><br>
+ OpenACS docs are written by the named authors, but may be edited
+ by OpenACS documentation staff.
+ </p></div><p><a href="mailto:vinod@kurup.com" target="_top">Vinod Kurup</a> put
together the January 2002 version of this guide from many sources of
- information.</p>
-<div class="itemizedlist"><ul>
-<li><p>
+ information.</p><div class="itemizedlist"><ul type="disc"><li><p>
<a href="operating-system.html">Install an Operating System</a>
- </p></li>
-<li><p>
+ </p></li><li><p>
<a href="http://openacs.org/doc/openacs/install/" target="_top">OpenACS 3.x Installation Guide</a>
- </p></li>
-<li><p>
+ </p></li><li><p>
<a href="http://www.orchardlabs.com/freebsd/" target="_top">Gilbert Wong's FreeBSD
installation guide</a>
- </p></li>
-<li><p>
+ </p></li><li><p>
<a href="http://www.kurup.com/acs/openacs-4.html" target="_top">My own Brief OpenACS4
installation guide</a>
- </p></li>
-</ul></div>
-<p>
+ </p></li></ul></div><p>
Acknowledgments for versions of the above documents go (in no
particular order) to Bryan Quinn, Adam Farkas, Brian Stein, Doug
Hoffman, Ravi Jasuja, Hiro Iwashima, Ryan Lee, Jonathan Goler, Audrey
@@ -55,41 +26,13 @@
Richard Li, Jon Griffin, Roberto Mello, Gilbert Wong, Don Baccus, Ben
Adida, Michael Cleverly, Janne Blonqvist, Jonathan Ellis, Janine Sisk,
Jade Rubick, Chris Hardy, Jonathan Marsden, Vinod Kurup, Charles Hall,
- Tom Jackson and Karl Lehenbauer.</p>
-<p>
+ Tom Jackson and Karl Lehenbauer.</p><p>
Several people have helped with this document, including Torben
Brosten, Don Baccus, Roberto Mello, Talli Somekh, Dave Bauer, Jim
Lynch, Jon Griffin and Daryl Biberdorf.
- </p>
-<p>
- <span class="strong"><i>All questions and comments</i></span> regarding
- this guide should be sent to <a href="mailto:vinod@kurup.com" target="_top">vinod@kurup.com</a> or on the <a href="http://openacs.org/bboard" target="_top">OpenACS bboards</a>.
- </p>
-<p><div class="cvstag">($Id$)</div></p>
-</div>
-<div class="navfooter">
-<hr>
-<table width="100%" summary="Navigation footer">
-<tr>
-<td width="40%" align="left">
-<a accesskey="p" href="nextsteps.html">Prev</a> </td>
-<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
-<td width="40%" align="right"> <a accesskey="n" href="win-install.html">Next</a>
-</td>
-</tr>
-<tr>
-<td width="40%" align="left">Next Steps </td>
-<td width="20%" align="center"><a accesskey="u" href="unix-install.html">Up</a></td>
-<td width="40%" align="right"> Chapter 3. Installing on Windows</td>
-</tr>
-</table>
-<hr>
-<address>
- rmello at fslc.usu.edu
- </address>
-<address><a href="mailto:vinod@kurup.com">
+ </p><p>
+ <span class="strong"><em>All questions and comments</em></span> regarding
+ this guide should be posted on the <a href="http://openacs.org/bboard" target="_top">OpenACS bboards</a>.
+ </p><p><div class="cvstag">($Id$)</div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="nextsteps.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="win-install.html">Next</a></td></tr><tr><td width="40%" align="left">Next Steps </td><td width="20%" align="center"><a accesskey="u" href="unix-install.html">Up</a></td><td width="40%" align="right"> Chapter 3. Installing on Windows</td></tr></table><hr><address>rmello at fslc.usu.edu</address><address><a href="mailto:vinod@kurup.com">
vinod@kurup.com
- </a></address>
-</div>
-</body>
-</html>
+ </a></address></div></body></html>
Index: openacs-4/packages/acs-core-docs/www/db-api-detailed.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/db-api-detailed.html,v
diff -u -r1.7 -r1.7.2.1
--- openacs-4/packages/acs-core-docs/www/db-api-detailed.html 7 Mar 2002 06:55:36 -0000 1.7
+++ openacs-4/packages/acs-core-docs/www/db-api-detailed.html 15 May 2002 23:26:18 -0000 1.7.2.1
@@ -1,66 +1,27 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type">
-<title>Database Access API</title>
-<meta name="generator" content="DocBook XSL Stylesheets V1.45">
-<link rel="home" href="index.html" title="OpenACS Documentation">
-<link rel="up" href="kernel-doc.html" title="Chapter 7. Kernel Documentation">
-<link rel="previous" href="rp-design.html" title="OpenACS 4 Request Processor Design">
-<link rel="next" href="tcl-doc.html" title="Documenting Tcl Files: Page Contracts and Libraries">
-<link rel="stylesheet" href="openacs.css" type="text/css">
-</head>
-<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-<div class="navheader">
-<a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr>
-<td width="20%" align="left">
-<a accesskey="p" href="rp-design.html">Prev</a> </td>
-<th width="60%" align="center">Chapter 7. Kernel Documentation</th>
-<td width="20%" align="right"> <a accesskey="n" href="tcl-doc.html">Next</a>
-</td>
-</tr></table>
-<hr>
-</div>
-<div class="sect1">
-<div class="titlepage"><div><h2 class="title" style="clear: both">
-<a name="db-api-detailed"></a>Database Access API</h2></div></div>
-<div class="authorblurb"><p>
-by <a href="mailto:jsalz@mit.edu" target="_top">Jon Salz</a>
-</p></div>
-<div class="itemizedlist"><ul>
-<li><p>Tcl procedures: /packages/acs-kernel/10-database-procs.tcl</p></li>
-<li><p>Tcl initialization: /packages/acs-kernel/database-init.tcl</p></li>
-</ul></div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="db-api-detailed-bigpicture"></a>The Big Picture</h3></div></div>
-<p>
+<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"><title>Database Access API</title><meta name="generator" content="DocBook XSL Stylesheets V1.50.0"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="kernel-doc.html" title="Chapter 7. Kernel Documentation"><link rel="previous" href="rp-design.html" title="OpenACS 4 Request Processor Design"><link rel="next" href="tcl-doc.html" title="Documenting Tcl Files: Page Contracts and Libraries"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="rp-design.html">Prev</a> </td><th width="60%" align="center">Chapter 7. Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="tcl-doc.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="db-api-detailed"></a>Database Access API</h2></div></div><div class="authorblurb"><p>
+by <a href="mailto:jsalz@mit.edu" target="_top">Jon Salz</a><br>
+ OpenACS docs are written by the named authors, but may be edited
+ by OpenACS documentation staff.
+ </p></div><div class="itemizedlist"><ul type="disc"><li><p>Tcl procedures: /packages/acs-kernel/10-database-procs.tcl</p></li><li><p>Tcl initialization: /packages/acs-kernel/database-init.tcl</p></li></ul></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="db-api-detailed-bigpicture"></a>The Big Picture</h3></div></div><p>
One of OpenACS's great strengths is that code written for it is very close to
the database. It is very easy to interact with the database from anywhere
within OpenACS. Our goal is to develop a coherent API for database access which
makes this even easier.
-</p>
-<p>There were four significant problems with the way OpenACS previously used the
-database (i.e., directly through the <tt>ns_db</tt> interface):</p>
-<div class="orderedlist"><ol type="1">
-<li><p>
-<span class="strong"><i>Handle management</i></span>. We required code to pass database
+</p><p>There were four significant problems with the way OpenACS previously used the
+database (i.e., directly through the <tt>ns_db</tt> interface):</p><div class="orderedlist"><ol type="1"><li><p><span class="strong"><em>Handle management</em></span>. We required code to pass database
handles around, and for routines which needed to perform database access but
didn't receive a database handle as input, it was difficult to know from
which of the three "magic pools" (main, subquery, and log) to
allocate a new handle.
-</p></li>
-<li>
-<p>
-<span class="strong"><i>Nested transactions</i></span>. In our Oracle driver, <tt>begin
+</p></li><li><p><span class="strong"><em>Nested transactions</em></span>. In our Oracle driver, <tt>begin
transaction</tt> really means "turn auto-commit mode off" and
<tt>end transaction</tt> means "commit the current transaction and
turn auto-commit mode on." Thus if transactional code needed to call a
routine which needed to operate transactionally, the semantics were
-non-obvious. Consider: </p>
-<pre class="programlisting">
+non-obvious. Consider: </p><pre class="programlisting">
proc foo { db args } {
db_transaction {
@@ -74,8 +35,7 @@
db_dml unused "insert into greeble(bork) values(50)"
}
-</pre>
-<p>
+</pre><p>
This would insert greeble #33 and do all the stuff in <tt>foo</tt>
transactionally, but the <tt>end transaction</tt> in <tt>foo</tt>
would actually cause a commit, and greeble #50 would later be inserted in
@@ -84,82 +44,55 @@
already have been committed!. This is not a good thing.
-</p>
-</li>
-<li><p>
-<span class="strong"><i>Unorthodox use of variables</i></span>. The standard mechanism for
+</p></li><li><p><span class="strong"><em>Unorthodox use of variables</em></span>. The standard mechanism for
mapping column values into variables involved the use of the
<tt>set_variables_after_query</tt> routine, which relies on an uplevel
variable named <tt>selection</tt> (likewise for
<tt>set_variables_after_subquery</tt> and <tt>subselection</tt>).
-</p></li>
-<li><p>
-<span class="strong"><i>Hard-coded reliance on Oracle</i></span>. It's difficult to
+</p></li><li><p><span class="strong"><em>Hard-coded reliance on Oracle</em></span>. It's difficult to
write code supporting various different databases (dynamically using the
appropriate dialect based on the type of database being used, e.g., using
<tt>DECODE</tt> on Oracle and <tt>CASE ... WHEN</tt> on
-Postgres).</p></li>
-</ol></div>
-<p>
+Postgres).</p></li></ol></div><p>
The Database Access API addresses the first three problems by:
-</p>
-<div class="orderedlist"><ol type="1">
-<li><p>making use of database handles transparent</p></li>
-<li><p>wrapping common database operations (including transaction management) in
-Tcl control structures (this is, after all, what Tcl is good at!)</p></li>
-</ol></div>
-<p>
+</p><div class="orderedlist"><ol type="1"><li><p>making use of database handles transparent</p></li><li><p>wrapping common database operations (including transaction management) in
+Tcl control structures (this is, after all, what Tcl is good at!)</p></li></ol></div><p>
It lays the groundwork for addressing the fourth problem by assigning each
SQL statement a logical name. In a future version of the OpenACS Core, this API
will translate logical statement names into actual SQL, based on the type of
database in use. (To smooth the learning curve, we provide a facility for
writing SQL inline for a "default SQL dialect", which we assume to
be Oracle for now.)
-</p>
-<p>To be clear, SQL abstraction is <span class="emphasis"><i>not</i></span> fully implemented in OpenACS
+</p><p>To be clear, SQL abstraction is <span class="emphasis"><em>not</em></span> fully implemented in OpenACS
3.3.1. The statement names supplied to each call are not used by the API at
all. The API's design for SQL abstraction is in fact incomplete;
-unresolved issues include:</p>
-<div class="itemizedlist"><ul>
-<li><p>how to add <tt>WHERE</tt> clause criteria dynamically</p></li>
-<li><p>how to build a dynamic <tt>ORDER BY</tt> clause (Ben Adida has a
-proposed solution for this)</p></li>
-<li><p>how to define a statement's formal interface (i.e., what bind
+unresolved issues include:</p><div class="itemizedlist"><ul type="disc"><li><p>how to add <tt>WHERE</tt> clause criteria dynamically</p></li><li><p>how to build a dynamic <tt>ORDER BY</tt> clause (Ben Adida has a
+proposed solution for this)</p></li><li><p>how to define a statement's formal interface (i.e., what bind
variables it expects, what columns its <tt>SELECT</tt> clause must
contain if it's a query) without actually implementing the statement in a
-specific SQL dialect</p></li>
-</ul></div>
-<p>
+specific SQL dialect</p></li></ul></div><p>
So why is the incremental change of adding statement naming to the API worth
the effort? It is worth the effort because we know that giving each SQL
statement a logical name will be required by the complete SQL abstraction
design. Therefore, we know that the effort will not be wasted, and taking
advantage of the new support for bind variables will already require code
that uses 3.3.0 version of the API to be updated.
-</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="db-api-detailed-set-var-aft-query"></a>The Bell Tolls for <tt>set_variables_after_query</tt></h3></div></div>
-<p>
+</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="db-api-detailed-set-var-aft-query"></a>The Bell Tolls for <tt>set_variables_after_query</tt></h3></div></div><p>
<tt>set_variables_after_query</tt> is gone! (Well, it's still there,
but you'll never need to use it.) The new API routines set local
variables automatically. For instance:
-</p>
-<pre class="programlisting">
+</p><pre class="programlisting">
db_1row select_names "select first_names, last_name from users where user_id = [ad_get_user_id]"
doc_body_append "Hello, $first_names $last_name!"
-</pre>
-<p>
+</pre><p>
Like <tt>ns_db 1row</tt>, this will bomb if the query doesn't return
any rows (no such user exists). If this isn't what you want, you can
write:
-</p>
-<pre class="programlisting">
+</p><pre class="programlisting">
if { [db_0or1row select_names "select first_names, last_name from users where user_id = [ad_get_user_id]"] } {
doc_body_append "Hello, $first_names $last_name!"
@@ -168,44 +101,34 @@
doc_body_append "There's no such user!"
}
-</pre>
-<p>
+</pre><p>
Selecting a bunch of rows is a lot prettier now:
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
db_foreach select_names "select first_names, last_name from users" {
doc_body_append "Say hi to $first_names $last_name for me!<br>"
}
-</pre>
-<p>
+</pre><p>
That's right, <tt>db_foreach</tt> is now like <tt>ns_db
select</tt> plus a <tt>while</tt> loop plus
<tt>set_variables_after_query</tt> plus an <tt>if</tt> statement
(containing code to be executed if no rows are returned).
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
db_foreach select_names "select first_names, last_name from users where last_name like 'S%'" {
doc_body_append "Say hi to $first_names $last_name for me!<br>"
} if_no_rows {
doc_body_append "There aren't any users with last names beginnings with S!"
}
-</pre>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="db-api-detailed-handles"></a>Handle Management</h3></div></div>
-<p>
+</pre></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="db-api-detailed-handles"></a>Handle Management</h3></div></div><p>
The new API keeps track of which handles are in use, and automatically
allocates new handles when they are necessary (e.g., to perform subqueries
while a select is active). For example:
-</p>
-<pre class="programlisting">
+</p><pre class="programlisting">
doc_body_append "<ul>"
db_foreach select_names "select first_names, last_name, user_id from users" {
@@ -224,101 +147,79 @@
doc_body_append "</ul>"
db_release_unused_handles
-</pre>
-<p>
+</pre><p>
A new handle isn't actually allocated and released for every selection,
of course - as a performance optimization, the API keeps old handles around
until <tt>db_release_unused_handles</tt> is invoked (or the script
terminates).
-</p>
-<p>Note that there is no analogue to <tt>ns_db gethandle</tt> - the
-handle is always automatically allocated the first time it's needed.</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="db-api-detailed-bindvars"></a>Bind Variables</h3></div></div>
-<p><span class="strong"><i>Introduction</i></span></p>
-<p>
+</p><p>Note that there is no analogue to <tt>ns_db gethandle</tt> - the
+handle is always automatically allocated the first time it's needed.</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="db-api-detailed-bindvars"></a>Bind Variables</h3></div></div><p><span class="strong"><em>Introduction</em></span></p><p>
Most SQL statements require that the code invoking the statement pass along
data associated with that statement, usually obtained from the user. For
instance, in order to delete a WimpyPoint presentation, a Tcl script might
use the SQL statement
-</p>
-<pre class="programlisting">
+</p><pre class="programlisting">
-delete from wp_presentations where presentation_id = <span class="emphasis"><i>some_presentation_id</i></span>
+delete from wp_presentations where presentation_id = <span class="emphasis"><em>some_presentation_id</em></span>
-</pre>
-<p>
-where <span class="emphasis"><i><tt>some_presentation_id</tt></i></span> is a number which is a valid
+</pre><p>
+where <span class="emphasis"><em><tt>some_presentation_id</tt></em></span> is a number which is a valid
presentation ID of the presentation I want to delete. It's easy to write
code handling situations like this since SQL statements can include
-<span class="strong"><i>bind variables</i></span>, which represent placeholders for actual
+<span class="strong"><em>bind variables</em></span>, which represent placeholders for actual
data. A bind variable is specified as a colon followed by an identifier, so
the statement above can be coded as:
-</p>
-<pre class="programlisting">
+</p><pre class="programlisting">
db_dml presentation_delete {
delete from wp_presentations where presentation_id = :some_presentation_id
}
-</pre>
-<p>
+</pre><p>
When this SQL statement is invoked, the value for the bind variable
<tt>:some_presentation_id</tt> is pulled from the Tcl variable
<tt>$some_presentation_id</tt> (in the caller's environment). Note
that bind variables are not limited to one per statement; you can use an
arbitrary number, and each will pull from the correspondingly named Tcl
variable. (Alternatively, you can also specify an list or <tt>ns_set</tt>
-providing bind variables' values; see <span class="emphasis"><i>Usage</i></span>.)
-</p>
-<p>The value of a bind variable is taken literally by the database driver, so
+providing bind variables' values; see <span class="emphasis"><em>Usage</em></span>.)
+</p><p>The value of a bind variable is taken literally by the database driver, so
there is never any need to put single-quotes around the value for a bind
variable, or to use <tt>db_quote</tt> to escape single-quotes contained
-in the value. The following works fine, despite the apostrophe:</p>
-<pre class="programlisting">
+in the value. The following works fine, despite the apostrophe:</p><pre class="programlisting">
set exclamation "That's all, folks!"
db_dml exclamation_insert { insert into exclamations(exclamation) values(:exclamation) }
-</pre>
-<p>Note that you can use a bind variable in a SQL statement only where you
+</pre><p>Note that you can use a bind variable in a SQL statement only where you
could use a literal (a number or single-quoted string). Bind variables cannot
be placeholders for things like SQL keywords, table names, or column names,
so the following will not work, even if <tt>$table_name</tt> is set
-properly:</p>
-<pre class="programlisting">
+properly:</p><pre class="programlisting">
select * from :table_name
-</pre>
-<p><span class="strong"><i>Why Bind Variables Are Useful</i></span></p>
-<p>
+</pre><p><span class="strong"><em>Why Bind Variables Are Useful</em></span></p><p>
Why bother with bind variables at all - why not just write the Tcl statement
above like this:
-</p>
-<pre class="programlisting">
+</p><pre class="programlisting">
db_dml presentation_delete "
delete from wp_presentations where presentation_id = $some_presentation_id
"
-</pre>
-<p>
+</pre><p>
(Note the use of double-quotes to allow the variable reference to
<tt>$some_presentation_id</tt> to be interpolated in.) This will work,
but consider the case where some devious user causes
<tt>some_presentation_id</tt> to be set to something like <tt>'3 or
1 = 1'</tt>, which would result in the following statement being
executed:
-</p>
-<pre class="programlisting">
+</p><pre class="programlisting">
delete from wp_presentations where presentation_id = 3 or 1 = 1
-</pre>
-<p>
+</pre><p>
This deletes every presentation in the database! Using bind variables
eliminates this gaping security hole: since bind variable values are taken
literally. Oracle will attempt to delete presentations whose presentation ID
@@ -328,24 +229,15 @@
always considers the values of bind variables to be literals, it becomes more
difficult for users to perform URL surgery to trick scripts into running
dangerous queries and DML.
-</p>
-<p><span class="strong"><i>Usage</i></span></p>
-<p>Every <tt>db_*</tt> command accepting a SQL command as an argument
-supports bind variables. You can either</p>
-<div class="itemizedlist"><ul>
-<li><p>specify the <tt>-bind</tt> switch to provide a set with bind variable
-values, or</p></li>
-<li><p>specify the <tt>-bind</tt> switch to explicitly provide a list of
-bind variable names and values, or</p></li>
-<li><p>not specify a bind variable list at all, in which case Tcl variables are
-used as bind variables.</p></li>
-</ul></div>
-<p>
+</p><p><span class="strong"><em>Usage</em></span></p><p>Every <tt>db_*</tt> command accepting a SQL command as an argument
+supports bind variables. You can either</p><div class="itemizedlist"><ul type="disc"><li><p>specify the <tt>-bind</tt> switch to provide a set with bind variable
+values, or</p></li><li><p>specify the <tt>-bind</tt> switch to explicitly provide a list of
+bind variable names and values, or</p></li><li><p>not specify a bind variable list at all, in which case Tcl variables are
+used as bind variables.</p></li></ul></div><p>
The default behavior (i.e., if the <tt>-bind</tt> switch is omitted) is
that these procedures expect to find local variables that correspond in name
to the referenced bind variables, e.g.:
-</p>
-<pre class="programlisting">
+</p><pre class="programlisting">
set user_id 123456
set role "administrator"
@@ -361,14 +253,11 @@
# of "administrator"
}
-</pre>
-<p>
+</pre><p>
The value of the local Tcl variable <tt>user_id</tt> (123456) is bound to
the <tt>user_id</tt> bind variable.
-</p>
-<p>The <tt>-bind</tt> switch can takes the name of an <tt>ns_set</tt>
-containing keys for each bind variable named in the query, e.g.:</p>
-<pre class="programlisting">
+</p><p>The <tt>-bind</tt> switch can takes the name of an <tt>ns_set</tt>
+containing keys for each bind variable named in the query, e.g.:</p><pre class="programlisting">
set bind_vars [ns_set create]
ns_set put $bind_vars user_id 123456
@@ -385,12 +274,10 @@
# of "administrator"
}
-</pre>
-<p>
+</pre><p>
Alternatively, as an argument to <tt>-bind</tt> you can specify a list of
alternating name/value pairs for bind variables:
-</p>
-<pre class="programlisting">
+</p><pre class="programlisting">
db_foreach user_group_memberships_by_role {
select g.group_id, g.group_name
@@ -403,23 +290,18 @@
# of "administrator"
}
-</pre>
-<p><span class="strong"><i><a name="kernel.dbapi_nulls_and_bind_vars"></a>Nulls and Bind Variables</i></span></p>
-<p>
+</pre><p><span class="strong"><em><a name="kernel.dbapi_nulls_and_bind_vars"></a>Nulls and Bind Variables</em></span></p><p>
When processing a DML statement, Oracle coerces empty strings into
-<tt>null</tt>. (This coercion does <span class="emphasis"><i>not</i></span> occur in the
+<tt>null</tt>. (This coercion does <span class="emphasis"><em>not</em></span> occur in the
<tt>WHERE</tt> clause of a query, i.e.
<tt>col = ''</tt> and
<tt>col is null</tt> are not equivalent.)
-</p>
-<p>As a result, when using bind variables, the only way to make Oracle set a
+</p><p>As a result, when using bind variables, the only way to make Oracle set a
column value to <tt>null</tt> is to set the corresponding bind variable
to the empty string, since a bind variable whose value is the string
"null" will be interpreted as the literal string
-"null".</p>
-<p>These Oracle quirks complicate the process of writing clear and abstract
-DML difficult. Here is an example that illustrates why:</p>
-<pre class="programlisting">
+"null".</p><p>These Oracle quirks complicate the process of writing clear and abstract
+DML difficult. Here is an example that illustrates why:</p><pre class="programlisting">
#
# Given the table:
@@ -439,19 +321,15 @@
# null, because Oracle has coerced the empty string (even for the
# numeric column "bar") into null in both cases
-</pre>
-<p>
+</pre><p>
Since databases other than Oracle do not coerce empty strings into
<tt>null</tt>, this code has different semantics depending on the
underlying database (i.e., the row that gets inserted may not have null as
its column values), which defeats the purpose of SQL abstraction.
-</p>
-<p>Therefore, the Database Access API provides a database-independent way to
+</p><p>Therefore, the Database Access API provides a database-independent way to
represent <tt>null</tt> (instead of the Oracle-specific idiom of the
-empty string): <span class="strong"><i><tt>db_null</tt></i></span>.</p>
-<p>Use it instead of the empty string whenever you want to set a column value
-explicitly to <tt>null</tt>, e.g.:</p>
-<pre class="programlisting">
+empty string): <span class="strong"><em><tt>db_null</tt></em></span>.</p><p>Use it instead of the empty string whenever you want to set a column value
+explicitly to <tt>null</tt>, e.g.:</p><pre class="programlisting">
set bar [db_null]
set baz [db_null]
@@ -460,35 +338,23 @@
#
# sets the values for both the "bar" and "baz" columns to null
-</pre>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="db-api-detailed-sql-abstraction"></a>SQL Abstraction</h3></div></div>
-<p>
+</pre></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="db-api-detailed-sql-abstraction"></a>SQL Abstraction</h3></div></div><p>
We now require that each SQL statement be assigned a logical name for the
statement that is unique to the procedure or page in which it is defined.
This is so that (eventually) we can implement logically named statements with
alternative SQL for non-Oracle databases (e.g., Postgres). More on this
later.
-</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="db-api-detailed-placing-values"></a>Placing Column Values in Arrays and Sets</h3></div></div>
-<p>
+</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="db-api-detailed-placing-values"></a>Placing Column Values in Arrays and Sets</h3></div></div><p>
Normally, <tt>db_foreach</tt>, <tt>db_0or1row</tt>, and
<tt>db_1row</tt> places the results of queries in Tcl variables, so you
can say:
-</p>
-<pre class="programlisting">
+</p><pre class="programlisting">
db_foreach users_select "select first_names, last_name from users" {
doc_body_append "<li>$first_names $last_name\n"
}
-</pre>
-<p>
+</pre><p>
However, sometimes this is not sufficient: you may need to examine the rows
returned, to dynamically determine the set of columns returned by the query,
or to avoid collisions with existing variables. You can use the
@@ -497,8 +363,7 @@
instruct the database routines to place the results in a Tcl array or
<tt>ns_set</tt>, respectively, where the keys are the column names and
the values are the column values. For example:
-</p>
-<pre class="programlisting">
+</p><pre class="programlisting">
db_foreach users_select "select first_names, last_name from users" -column_set columns {
# Now $columns is an ns_set.
@@ -508,20 +373,9 @@
}
}
-</pre>
-<p>
+</pre><p>
will write something like:
-</p>
-<div class="itemizedlist"><ul>
-<li><p>first_names is Jon. last_name is Salz.</p></li>
-<li><p>first_names is Lars. last_name is Pind.</p></li>
-<li><p>first_names is Michael. last_name is Yoon.</p></li>
-</ul></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="db-api-detailed-pooling"></a>Sequence Pooling</h3></div></div>
-<p>
+</p><div class="itemizedlist"><ul type="disc"><li><p>first_names is Jon. last_name is Salz.</p></li><li><p>first_names is Lars. last_name is Pind.</p></li><li><p>first_names is Michael. last_name is Yoon.</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="db-api-detailed-pooling"></a>Sequence Pooling</h3></div></div><p>
The database library can transparently maintain pools of sequence values, so
that each request for a new sequence value (using <tt>db_nextval</tt>)
does not incur a roundtrip to the server. For instance, this functionality is
@@ -530,260 +384,170 @@
functionality for a particular sequence, register the sequence to be pooled,
either using the <tt>db_register_pooled_sequence</tt> procedure at server
startup time, or by including a configuration parameter of the form
-</p>
-<pre class="programlisting">
+</p><pre class="programlisting">
-PoolSequence.<span class="emphasis"><i>sequence_name_seq</i></span>=<span class="emphasis"><i>count</i></span>
+PoolSequence.<span class="emphasis"><em>sequence_name_seq</em></span>=<span class="emphasis"><em>count</em></span>
-</pre>
-<p>
-in <span class="emphasis"><i>any</i></span> configuration section in the <tt>yourservername.ini</tt>
+</pre><p>
+in <span class="emphasis"><em>any</em></span> configuration section in the <tt>yourservername.ini</tt>
file, e.g., e.g.,
-</p>
-<pre class="programlisting">
+</p><pre class="programlisting">
-[ns/server/<span class="emphasis"><i>yourservername</i></span>/acs/security]
+[ns/server/<span class="emphasis"><em>yourservername</em></span>/acs/security]
PoolSequence.sec_id_seq=20
-</pre>
-<p>
+</pre><p>
The database library will allocate this number of sequence values at server
startup. It will periodically scan pools and allocate new values for
sequences which are less than half-full. (This normally occurs every 60
seconds, and is configurable via the
<tt>PooledSequenceUpdateInterval</tt> parameter in the
-<tt>[ns/server/</tt><span class="emphasis"><i><tt>yourservername</tt></i></span><tt>/acs/database]</tt> configuration
+<tt>[ns/server/</tt><span class="emphasis"><em><tt>yourservername</tt></em></span><tt>/acs/database]</tt> configuration
section.)
-</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="dp-api-detailed-api"></a>API</h3></div></div>
-<p>
+</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="dp-api-detailed-api"></a>API</h3></div></div><p>
Note that you never have to use <tt>ns_db</tt> anymore (including
<tt>ns_db gethandle</tt>)! Just start doing stuff, and (if you want) call
<tt>db_release_unused_handles</tt> when you're done as a hint to
release the database handle.
-</p>
-<div class="variablelist"><dl>
-<dt><span class="term"><span class="strong"><i><tt><a name="kernel.dbapi_db_abort_transaction"></a>db_abort_transaction</tt></i></span>
-</span></dt>
-<dd>
-<pre class="programlisting">
-<span class="strong"><i>db_abort_transaction</i></span>
-</pre>
-<p>Aborts all levels of a transaction. That is if this is called within
+</p><div class="variablelist"><dl><dt><span class="term"><span class="strong"><em><tt><a name="kernel.dbapi_db_abort_transaction"></a>db_abort_transaction</tt></em></span>
+</span></dt><dd><pre class="programlisting">
+<span class="strong"><em>db_abort_transaction</em></span>
+</pre><p>Aborts all levels of a transaction. That is if this is called within
several nested transactions, all of them are terminated. Use this insetead of
<tt>db_dml "abort" "abort transaction"</tt>.
-</p>
-</dd>
-<dt><span class="term"><span class="strong"><i><tt><a name="kernel.dbapi_db_null"></a>db_null</tt></i></span>
+</p></dd><dt><span class="term"><span class="strong"><em><tt><a name="kernel.dbapi_db_null"></a>db_null</tt></em></span>
-</span></dt>
-<dd>
-<pre class="programlisting">
-<span class="strong"><i><tt>db_null</tt></i></span>
-</pre>
-<p>Returns a value which can be used in a bind variable to represent the SQL
+</span></dt><dd><pre class="programlisting">
+<span class="strong"><em><tt>db_null</tt></em></span>
+</pre><p>Returns a value which can be used in a bind variable to represent the SQL
value <tt>null</tt>. See <a href="db-api.html#dbapi_nulls_and_bind_vars" title="Nulls and Bind Variables">Nulls and Bind Variables</a>
-above.</p>
-</dd>
-<dt><span class="term">
-<span class="strong"><i><tt><a name="kernel.dbapi_db_foreach"></a>db_foreach</tt></i></span>
-</span></dt>
-<dd>
-<pre class="programlisting">
-<span class="strong"><i>db_foreach</i></span> <span class="emphasis"><i>statement-name sql</i></span> [ -bind <span class="emphasis"><i>bind_set_id</i></span> | -bind <span class="emphasis"><i>bind_value_list</i></span> ] \
- [ -column_array <span class="emphasis"><i>array_name</i></span> | -column_set <span class="emphasis"><i>set_name</i></span> ] \
- <span class="emphasis"><i>code_block</i></span> [ if_no_rows <span class="emphasis"><i>if_no_rows_block ]</i></span>
-</pre>
-<p>Performs the SQL query <span class="emphasis"><i><tt>sql</tt></i></span>, executing
-<span class="emphasis"><i><tt>code_block</tt></i></span> once for each row with variables set to
+above.</p></dd><dt><span class="term">
+<span class="strong"><em><tt><a name="kernel.dbapi_db_foreach"></a>db_foreach</tt></em></span>
+</span></dt><dd><pre class="programlisting">
+<span class="strong"><em>db_foreach</em></span> <span class="emphasis"><em>statement-name sql</em></span> [ -bind <span class="emphasis"><em>bind_set_id</em></span> | -bind <span class="emphasis"><em>bind_value_list</em></span> ] \
+ [ -column_array <span class="emphasis"><em>array_name</em></span> | -column_set <span class="emphasis"><em>set_name</em></span> ] \
+ <span class="emphasis"><em>code_block</em></span> [ if_no_rows <span class="emphasis"><em>if_no_rows_block ]</em></span>
+</pre><p>Performs the SQL query <span class="emphasis"><em><tt>sql</tt></em></span>, executing
+<span class="emphasis"><em><tt>code_block</tt></em></span> once for each row with variables set to
column values (or a set or array populated if <tt>-column_array</tt> or
<tt>column_set</tt> is specified). If the query returns no rows, executes
-<span class="emphasis"><i><tt>if_no_rows_block</tt></i></span> (if provided). </p>
-<p>Example:</p>
-<pre class="programlisting">
+<span class="emphasis"><em><tt>if_no_rows_block</tt></em></span> (if provided). </p><p>Example:</p><pre class="programlisting">
db_foreach select_foo "select foo, bar from greeble" {
doc_body_append "<li>foo=$foo; bar=$bar\n"
} if_no_rows {
doc_body_append "<li>There are no greebles in the database.\n"
}
-</pre>
-<p>
+</pre><p>
The code block may contain <tt>break</tt> statements (which terminate the
loop and flush the database handle) and <tt>continue</tt> statements
-(which continue to the next row of the loop). </p>
-</dd>
-<dt><span class="term"><span class="strong"><i><tt><a name="kernel.dbapi_db_1row"></a>db_1row</tt></i></span></span></dt>
-<dd>
-<pre class="programlisting">
-<span class="strong"><i>db_1row</i></span> <span class="emphasis"><i>statement-name</i></span> <span class="emphasis"><i>sql</i></span> [ -bind <span class="emphasis"><i>bind_set_id</i></span> | -bind <span class="emphasis"><i>bind_value_list</i></span> ] \
- [ -column_array <span class="emphasis"><i>array_name</i></span> | -column_set <span class="emphasis"><i>set_name</i></span> ]
-</pre>
-<p>Performs the SQL query <span class="emphasis"><i><tt>sql</tt></i></span>, setting variables to
-column values. Raises an error if the query does not return exactly 1 row. </p>
-<p>Example:</p>
-<pre class="programlisting">
+(which continue to the next row of the loop). </p></dd><dt><span class="term"><span class="strong"><em><tt><a name="kernel.dbapi_db_1row"></a>db_1row</tt></em></span></span></dt><dd><pre class="programlisting">
+<span class="strong"><em>db_1row</em></span> <span class="emphasis"><em>statement-name</em></span> <span class="emphasis"><em>sql</em></span> [ -bind <span class="emphasis"><em>bind_set_id</em></span> | -bind <span class="emphasis"><em>bind_value_list</em></span> ] \
+ [ -column_array <span class="emphasis"><em>array_name</em></span> | -column_set <span class="emphasis"><em>set_name</em></span> ]
+</pre><p>Performs the SQL query <span class="emphasis"><em><tt>sql</tt></em></span>, setting variables to
+column values. Raises an error if the query does not return exactly 1 row. </p><p>Example:</p><pre class="programlisting">
db_1row select_foo "select foo, bar from greeble where greeble_id = $greeble_id"
# Bombs if there's no such greeble!
# Now $foo and $bar are set.
-</pre>
-</dd>
-<dt><span class="term"><span class="strong"><i><tt><a name="kernel.dbapi_db_0or1row"></a>db_0or1row</tt></i></span> </span></dt>
-<dd>
-<pre class="programlisting">
-<span class="strong"><i>db_0or1row</i></span> <span class="emphasis"><i>statement-name</i></span> <span class="emphasis"><i>sql</i></span> [ -bind <span class="emphasis"><i>bind_set_id</i></span> | -bind <span class="emphasis"><i>bind_value_list</i></span> ] \
- [ -column_array <span class="emphasis"><i>array_name</i></span> | -column_set <span class="emphasis"><i>set_name</i></span> ]
-</pre>
-<p>Performs the SQL query <span class="emphasis"><i><tt>sql</tt></i></span>. If a row is returned,
+</pre></dd><dt><span class="term"><span class="strong"><em><tt><a name="kernel.dbapi_db_0or1row"></a>db_0or1row</tt></em></span> </span></dt><dd><pre class="programlisting">
+<span class="strong"><em>db_0or1row</em></span> <span class="emphasis"><em>statement-name</em></span> <span class="emphasis"><em>sql</em></span> [ -bind <span class="emphasis"><em>bind_set_id</em></span> | -bind <span class="emphasis"><em>bind_value_list</em></span> ] \
+ [ -column_array <span class="emphasis"><em>array_name</em></span> | -column_set <span class="emphasis"><em>set_name</em></span> ]
+</pre><p>Performs the SQL query <span class="emphasis"><em><tt>sql</tt></em></span>. If a row is returned,
sets variables to column values and returns 1. If no rows are returned,
-returns 0. If more than one row is returned, throws an error. </p>
-</dd>
-<dt><span class="term"><span class="strong"><i><tt><a name="kernel.dbapi_db_nextval"></a>db_nextval</tt></i></span> </span></dt>
-<dd>
-<pre class="programlisting">
-<span class="strong"><i>db_nextval</i></span> <span class="emphasis"><i>sequence-name</i></span>
-</pre>
-<p>Returns the next value for the sequence <span class="emphasis"><i>sequence-name</i></span> (using a
-SQL statement like <tt>SELECT</tt> <span class="emphasis"><i><tt>sequence-name</tt></i></span><tt>.nextval FROM
+returns 0. If more than one row is returned, throws an error. </p></dd><dt><span class="term"><span class="strong"><em><tt><a name="kernel.dbapi_db_nextval"></a>db_nextval</tt></em></span> </span></dt><dd><pre class="programlisting">
+<span class="strong"><em>db_nextval</em></span> <span class="emphasis"><em>sequence-name</em></span>
+</pre><p>Returns the next value for the sequence <span class="emphasis"><em>sequence-name</em></span> (using a
+SQL statement like <tt>SELECT</tt> <span class="emphasis"><em><tt>sequence-name</tt></em></span><tt>.nextval FROM
DUAL</tt>). If sequence pooling is enabled for the sequence, transparently
uses a value from the pool if available to save a round-trip to the database
-(see <span class="emphasis"><i><a href="db-api-detailed.html#db-api-detailed-pooling">Sequence Pooling</a></i></span>).
+(see <span class="emphasis"><em><a href="db-api-detailed.html#db-api-detailed-pooling">Sequence Pooling</a></em></span>).
-</p>
-</dd>
-<dt><span class="term"><span class="strong"><i><tt><a name="kernel.dbapi_db_register_pooled_sequence"></a>db_register_pooled_sequence</tt></i></span> </span></dt>
-<dd>
-<pre class="programlisting">
-<span class="strong"><i>db_register_pooled_sequence</i></span> <span class="emphasis"><i>sequence-name</i></span> <span class="emphasis"><i>pool-size</i></span>
-</pre>
-<p>Registers the sequence <span class="emphasis"><i>sequence-name</i></span> to be pooled, with a pool
-size of <span class="emphasis"><i>pool-size</i></span> sequence values (see <span class="emphasis"><i><a href="db-api-detailed.html#db-api-detailed-pooling">Sequence Pooling</a></i></span>).
+</p></dd><dt><span class="term"><span class="strong"><em><tt><a name="kernel.dbapi_db_register_pooled_sequence"></a>db_register_pooled_sequence</tt></em></span> </span></dt><dd><pre class="programlisting">
+<span class="strong"><em>db_register_pooled_sequence</em></span> <span class="emphasis"><em>sequence-name</em></span> <span class="emphasis"><em>pool-size</em></span>
+</pre><p>Registers the sequence <span class="emphasis"><em>sequence-name</em></span> to be pooled, with a pool
+size of <span class="emphasis"><em>pool-size</em></span> sequence values (see <span class="emphasis"><em><a href="db-api-detailed.html#db-api-detailed-pooling">Sequence Pooling</a></em></span>).
-</p>
-</dd>
-<dt><span class="term"><span class="strong"><i><tt><a name="kernel.dbapi_db_string"></a>db_string</tt></i></span> </span></dt>
-<dd>
-<pre class="programlisting">
-<span class="strong"><i>db_string</i></span> <span class="emphasis"><i>statement-name</i></span> <span class="emphasis"><i>sql</i></span> [ -default <span class="emphasis"><i>default</i></span> ] [ -bind <span class="emphasis"><i>bind_set_id</i></span> | -bind <span class="emphasis"><i>bind_value_list</i></span> ]
-</pre>
-<p>Returns the first column of the result of SQL query
-<span class="emphasis"><i><tt>sql</tt></i></span>. If <span class="emphasis"><i><tt>sql</tt></i></span> doesn't return a
-row, returns <span class="emphasis"><i><tt>default</tt></i></span> (or throws an error if
-<span class="emphasis"><i><tt>default</tt></i></span> is unspecified). Analogous to
+</p></dd><dt><span class="term"><span class="strong"><em><tt><a name="kernel.dbapi_db_string"></a>db_string</tt></em></span> </span></dt><dd><pre class="programlisting">
+<span class="strong"><em>db_string</em></span> <span class="emphasis"><em>statement-name</em></span> <span class="emphasis"><em>sql</em></span> [ -default <span class="emphasis"><em>default</em></span> ] [ -bind <span class="emphasis"><em>bind_set_id</em></span> | -bind <span class="emphasis"><em>bind_value_list</em></span> ]
+</pre><p>Returns the first column of the result of SQL query
+<span class="emphasis"><em><tt>sql</tt></em></span>. If <span class="emphasis"><em><tt>sql</tt></em></span> doesn't return a
+row, returns <span class="emphasis"><em><tt>default</tt></em></span> (or throws an error if
+<span class="emphasis"><em><tt>default</tt></em></span> is unspecified). Analogous to
<tt>database_to_tcl_string</tt> and
<tt>database_to_tcl_string_or_null</tt>.
-</p>
-</dd>
-<dt><span class="term"><span class="strong"><i><tt><a name="kernel.dbapi_db_list"></a>db_list</tt></i></span></span></dt>
-<dd>
-<pre class="programlisting">
-<span class="strong"><i>db_list</i></span> <span class="emphasis"><i>statement-name</i></span> <span class="emphasis"><i>sql</i></span> [ -bind <span class="emphasis"><i>bind_set_id</i></span> | -bind <span class="emphasis"><i>bind_value_list</i></span> ]
-</pre>
-<p>Returns a Tcl list of the values in the first column of the result of SQL
-query <span class="emphasis"><i><tt>sql</tt></i></span>. If <span class="emphasis"><i><tt>sql</tt></i></span> doesn't
+</p></dd><dt><span class="term"><span class="strong"><em><tt><a name="kernel.dbapi_db_list"></a>db_list</tt></em></span></span></dt><dd><pre class="programlisting">
+<span class="strong"><em>db_list</em></span> <span class="emphasis"><em>statement-name</em></span> <span class="emphasis"><em>sql</em></span> [ -bind <span class="emphasis"><em>bind_set_id</em></span> | -bind <span class="emphasis"><em>bind_value_list</em></span> ]
+</pre><p>Returns a Tcl list of the values in the first column of the result of SQL
+query <span class="emphasis"><em><tt>sql</tt></em></span>. If <span class="emphasis"><em><tt>sql</tt></em></span> doesn't
return any rows, returns an empty list. Analogous to
<tt>database_to_tcl_list</tt>.
-</p>
-</dd>
-<dt><span class="term"><span class="strong"><i><tt><a name="kernel.dbapi_db_list_of_lists"></a>db_list_of_lists</tt></i></span></span></dt>
-<dd>
-<pre class="programlisting">
-<span class="strong"><i>db_list_of_lists</i></span> <span class="emphasis"><i>statement-name</i></span> <span class="emphasis"><i>sql</i></span> [ -bind <span class="emphasis"><i>bind_set_id</i></span> | -bind <span class="emphasis"><i>bind_value_list</i></span> ]
-</pre>
-<p>Returns a Tcl list, each element of which is a list of all column values
-in a row of the result of SQL query <span class="emphasis"><i><tt>sql</tt></i></span>. If
-<span class="emphasis"><i><tt>sql</tt></i></span> doesn't return any rows, returns an empty list.
+</p></dd><dt><span class="term"><span class="strong"><em><tt><a name="kernel.dbapi_db_list_of_lists"></a>db_list_of_lists</tt></em></span></span></dt><dd><pre class="programlisting">
+<span class="strong"><em>db_list_of_lists</em></span> <span class="emphasis"><em>statement-name</em></span> <span class="emphasis"><em>sql</em></span> [ -bind <span class="emphasis"><em>bind_set_id</em></span> | -bind <span class="emphasis"><em>bind_value_list</em></span> ]
+</pre><p>Returns a Tcl list, each element of which is a list of all column values
+in a row of the result of SQL query <span class="emphasis"><em><tt>sql</tt></em></span>. If
+<span class="emphasis"><em><tt>sql</tt></em></span> doesn't return any rows, returns an empty list.
(Analogous to <tt>database_to_tcl_list_list</tt>.)
-</p>
-</dd>
-<dt><span class="term"><span class="strong"><i><tt><a name="kernel.dbapi_db_dml"></a>db_dml</tt></i></span></span></dt>
-<dd>
-<pre class="programlisting">
-<span class="strong"><i>db_dml</i></span> <span class="emphasis"><i>statement-name</i></span> <span class="emphasis"><i>sql</i></span> \
- [ -bind <span class="emphasis"><i>bind_set_id</i></span> | -bind <span class="emphasis"><i>bind_value_list</i></span> ] \
- [ -blobs <span class="emphasis"><i>blob_list</i></span> | -clobs <span class="emphasis"><i>clob_list</i></span> |
- -blob_files <span class="emphasis"><i>blob_file_list</i></span> | -clob_files <span class="emphasis"><i>clob_file_list</i></span> ]
-</pre>
-<p>Performs the DML or DDL statement <span class="emphasis"><i><tt>sql</tt></i></span>. </p>
-<p>If a length-<span class="emphasis"><i>n</i></span> list of blobs or clobs is provided, then the SQL
-should return <span class="emphasis"><i>n</i></span> blobs or clobs into the bind variables
-<tt>:1</tt>, <tt>:2</tt>, ... :<span class="emphasis"><i><tt>n</tt></i></span>.
-<span class="emphasis"><i><tt>blobs</tt></i></span> or <span class="emphasis"><i><tt>clobs</tt></i></span>, if specified,
+</p></dd><dt><span class="term"><span class="strong"><em><tt><a name="kernel.dbapi_db_dml"></a>db_dml</tt></em></span></span></dt><dd><pre class="programlisting">
+<span class="strong"><em>db_dml</em></span> <span class="emphasis"><em>statement-name</em></span> <span class="emphasis"><em>sql</em></span> \
+ [ -bind <span class="emphasis"><em>bind_set_id</em></span> | -bind <span class="emphasis"><em>bind_value_list</em></span> ] \
+ [ -blobs <span class="emphasis"><em>blob_list</em></span> | -clobs <span class="emphasis"><em>clob_list</em></span> |
+ -blob_files <span class="emphasis"><em>blob_file_list</em></span> | -clob_files <span class="emphasis"><em>clob_file_list</em></span> ]
+</pre><p>Performs the DML or DDL statement <span class="emphasis"><em><tt>sql</tt></em></span>. </p><p>If a length-<span class="emphasis"><em>n</em></span> list of blobs or clobs is provided, then the SQL
+should return <span class="emphasis"><em>n</em></span> blobs or clobs into the bind variables
+<tt>:1</tt>, <tt>:2</tt>, ... :<span class="emphasis"><em><tt>n</tt></em></span>.
+<span class="emphasis"><em><tt>blobs</tt></em></span> or <span class="emphasis"><em><tt>clobs</tt></em></span>, if specified,
should be a list of individual BLOBs or CLOBs to insert;
-<span class="emphasis"><i><tt>blob_files</tt></i></span> or <span class="emphasis"><i><tt>clob_files</tt></i></span>, if
-specified, should be a list of <span class="emphasis"><i>paths to files</i></span> containing the data to
+<span class="emphasis"><em><tt>blob_files</tt></em></span> or <span class="emphasis"><em><tt>clob_files</tt></em></span>, if
+specified, should be a list of <span class="emphasis"><em>paths to files</em></span> containing the data to
insert. Only one of <tt>-blobs</tt>, <tt>-clobs</tt>,
-<tt>-blob_files</tt>, and <tt>-clob_files</tt> may be provided.</p>
-<p>Example:</p>
-<pre class="programlisting">
+<tt>-blob_files</tt>, and <tt>-clob_files</tt> may be provided.</p><p>Example:</p><pre class="programlisting">
db_dml insert_photos "
insert photos(photo_id, image, thumbnail_image)
values(photo_id_seq.nextval, empty_blob(), empty_blob())
returning image, thumbnail_image into :1, :2
" -blob_files [list "/var/tmp/the_photo" "/var/tmp/the_thumbnail"]
-</pre>
-<p>
+</pre><p>
This inserts a new row into the <tt>photos</tt> table, with the contents
of the files <tt>/var/tmp/the_photo</tt> and
<tt>/var/tmp/the_thumbnail</tt> in the <tt>image</tt> and
<tt>thumbnail</tt> columns, respectively.
-</p>
-</dd>
-<dt><span class="term">
-<span class="strong"><i><tt><a name="kernel.dbapi_db_write_clob"></a>db_write_clob</tt></i></span>,
-<span class="strong"><i><tt><a name="kernel.dbapi_db_write_blob"></a>db_write_blob</tt></i></span>,
-<span class="strong"><i><tt><a name="kernel.dbapi_db_blob_get_file"></a>db_blob_get_file</tt></i></span>
-</span></dt>
-<dd>
-<pre class="programlisting">
-<span class="strong"><i>db_write_clob</i></span> <span class="emphasis"><i>statement-name</i></span> <span class="emphasis"><i>sql</i></span> [ -bind <span class="emphasis"><i>bind_set_id</i></span> | -bind <span class="emphasis"><i>bind_value_list</i></span> ]
+</p></dd><dt><span class="term">
+<span class="strong"><em><tt><a name="kernel.dbapi_db_write_clob"></a>db_write_clob</tt></em></span>,
+<span class="strong"><em><tt><a name="kernel.dbapi_db_write_blob"></a>db_write_blob</tt></em></span>,
+<span class="strong"><em><tt><a name="kernel.dbapi_db_blob_get_file"></a>db_blob_get_file</tt></em></span>
+</span></dt><dd><pre class="programlisting">
+<span class="strong"><em>db_write_clob</em></span> <span class="emphasis"><em>statement-name</em></span> <span class="emphasis"><em>sql</em></span> [ -bind <span class="emphasis"><em>bind_set_id</em></span> | -bind <span class="emphasis"><em>bind_value_list</em></span> ]
-<span class="strong"><i>db_write_blob</i></span> <span class="emphasis"><i>statement-name</i></span> <span class="emphasis"><i>sql</i></span> [ -bind <span class="emphasis"><i>bind_set_id</i></span> | -bind <span class="emphasis"><i>bind_value_list</i></span> ]
+<span class="strong"><em>db_write_blob</em></span> <span class="emphasis"><em>statement-name</em></span> <span class="emphasis"><em>sql</em></span> [ -bind <span class="emphasis"><em>bind_set_id</em></span> | -bind <span class="emphasis"><em>bind_value_list</em></span> ]
-<span class="strong"><i>db_blob_get_file</i></span> <span class="emphasis"><i>statement-name</i></span> <span class="emphasis"><i>sql</i></span> [ -bind <span class="emphasis"><i>bind_set_id</i></span> | -bind <span class="emphasis"><i>bind_value_list</i></span> ]
-</pre>
-<p>Analagous to <tt>ns_ora write_clob/write_blob/blob_get_file</tt>.
+<span class="strong"><em>db_blob_get_file</em></span> <span class="emphasis"><em>statement-name</em></span> <span class="emphasis"><em>sql</em></span> [ -bind <span class="emphasis"><em>bind_set_id</em></span> | -bind <span class="emphasis"><em>bind_value_list</em></span> ]
+</pre><p>Analagous to <tt>ns_ora write_clob/write_blob/blob_get_file</tt>.
-</p>
-</dd>
-<dt><span class="term"><span class="strong"><i><tt><a name="kernel.dbapi_db_release_unused_handles"></a>db_release_unused_handles</tt></i></span></span></dt>
-<dd>
-<pre class="programlisting">
-<span class="strong"><i>db_release_unused_handles</i></span>
-</pre>
-<p>Releases any allocated, unused database handles. </p>
-</dd>
-<dt><span class="term"><span class="strong"><i><tt><a name="kernel.dbapi_db_transaction"></a>db_transaction</tt></i></span></span></dt>
-<dd>
-<pre class="programlisting">
-<span class="strong"><i>db_transaction</i></span> <span class="emphasis"><i>code_block</i></span> [ on_error { <span class="emphasis"><i>code_block</i></span> } ]
-</pre>
-<p>Executes <span class="emphasis"><i><tt>code_block</tt></i></span> transactionally. Nested
+</p></dd><dt><span class="term"><span class="strong"><em><tt><a name="kernel.dbapi_db_release_unused_handles"></a>db_release_unused_handles</tt></em></span></span></dt><dd><pre class="programlisting">
+<span class="strong"><em>db_release_unused_handles</em></span>
+</pre><p>Releases any allocated, unused database handles. </p></dd><dt><span class="term"><span class="strong"><em><tt><a name="kernel.dbapi_db_transaction"></a>db_transaction</tt></em></span></span></dt><dd><pre class="programlisting">
+<span class="strong"><em>db_transaction</em></span> <span class="emphasis"><em>code_block</em></span> [ on_error { <span class="emphasis"><em>code_block</em></span> } ]
+</pre><p>Executes <span class="emphasis"><em><tt>code_block</tt></em></span> transactionally. Nested
transactions are supported (<tt>end transaction</tt> is transparently
<tt>ns_db dml</tt>'ed when the outermost transaction completes). The
<tt>db_abort_transaction</tt> command can be used to abort all levels of
transactions. It is possible to specify an optional <tt>on_error</tt>
-code block that will be executed if some code in <span class="emphasis"><i>code_block</i></span> throws
+code block that will be executed if some code in <span class="emphasis"><em>code_block</em></span> throws
an exception. The variable <tt>errmsg</tt> will be bound in that scope.
-If there is no <tt>on_error</tt> code, any errors will be propagated. </p>
-<p>Example:</p>
-<pre class="programlisting">
+If there is no <tt>on_error</tt> code, any errors will be propagated. </p><p>Example:</p><pre class="programlisting">
proc replace_the_foo { col } {
db_transaction {
@@ -812,30 +576,18 @@
print_the_foo ; # Writes out "foo is 8"
-</pre>
-</dd>
-<dt><span class="term"><span class="strong"><i><tt><a name="kernel.dbapi_db_resultrows"></a>db_resultrows</tt></i></span></span></dt>
-<dd>
-<pre class="programlisting">
-<span class="strong"><i>db_resultrows</i></span>
-</pre>
-<p>Returns the number of rows affected or returned by the previous
+</pre></dd><dt><span class="term"><span class="strong"><em><tt><a name="kernel.dbapi_db_resultrows"></a>db_resultrows</tt></em></span></span></dt><dd><pre class="programlisting">
+<span class="strong"><em>db_resultrows</em></span>
+</pre><p>Returns the number of rows affected or returned by the previous
statement.
-</p>
-</dd>
-<dt><span class="term"><span class="strong"><i><tt><a name="kernel.dbapi_db_with_handle"></a>db_with_handle</tt></i></span></span></dt>
-<dd>
-<pre class="programlisting">
-<span class="strong"><i>db_with_handle</i></span> <span class="emphasis"><i>var</i></span> <span class="emphasis"><i>code_block</i></span>
-</pre>
-<p>Places a database handle into the variable <span class="emphasis"><i><tt>var</tt></i></span> and
-executes <span class="emphasis"><i><tt>code_block</tt></i></span>. This is useful when you don't
+</p></dd><dt><span class="term"><span class="strong"><em><tt><a name="kernel.dbapi_db_with_handle"></a>db_with_handle</tt></em></span></span></dt><dd><pre class="programlisting">
+<span class="strong"><em>db_with_handle</em></span> <span class="emphasis"><em>var</em></span> <span class="emphasis"><em>code_block</em></span>
+</pre><p>Places a database handle into the variable <span class="emphasis"><em><tt>var</tt></em></span> and
+executes <span class="emphasis"><em><tt>code_block</tt></em></span>. This is useful when you don't
want to have to use the new API (<tt>db_foreach</tt>,
-<tt>db_1row</tt>, etc.), but need to use database handles explicitly. </p>
-<p>Example:</p>
-<pre class="programlisting">
+<tt>db_1row</tt>, etc.), but need to use database handles explicitly. </p><p>Example:</p><pre class="programlisting">
proc lookup_the_foo { foo } {
db_with_handle db {
@@ -853,18 +605,12 @@
}
}
-</pre>
-</dd>
-<dt><span class="term"><span class="strong"><i><tt><a name="kernel.dbapi_db_nullify_empty_string"></a>db_nullify_empty_string</tt></i></span></span></dt>
-<dd>
-<pre class="programlisting">
-<span class="strong"><i>db_nullify_empty_string</i></span> <span class="emphasis"><i>string</i></span>
-</pre>
-<p>For true SQL purists, we provide the convenience function
-<span class="strong"><i><tt>db_nullify_empty_string</tt></i></span>, which returns
-[db_null] if its <span class="emphasis"><i><tt>string</tt></i></span> argument is the empty string
-and can be used to encapsulate another Oracle quirk: </p>
-<pre class="programlisting">
+</pre></dd><dt><span class="term"><span class="strong"><em><tt><a name="kernel.dbapi_db_nullify_empty_string"></a>db_nullify_empty_string</tt></em></span></span></dt><dd><pre class="programlisting">
+<span class="strong"><em>db_nullify_empty_string</em></span> <span class="emphasis"><em>string</em></span>
+</pre><p>For true SQL purists, we provide the convenience function
+<span class="strong"><em><tt>db_nullify_empty_string</tt></em></span>, which returns
+[db_null] if its <span class="emphasis"><em><tt>string</tt></em></span> argument is the empty string
+and can be used to encapsulate another Oracle quirk: </p><pre class="programlisting">
set baz ""
@@ -880,44 +626,13 @@
# the empty string we just inserted (because of Oracle's coercion
# quirk)
-</pre>
-<p>
+</pre><p>
To balance out this asymmetry, you can explicitly set <tt>baz</tt> to
<tt>null</tt> by writing:
-</p>
-<pre class="programlisting">
+</p><pre class="programlisting">
db_dml foo_insert "insert into foo(baz) values(:1)" {[db_nullify_empty_string $baz]}
-</pre>
-</dd>
-</dl></div>
-<p><div class="cvstag">($Id$)</div></p>
-</div>
-</div>
-<div class="navfooter">
-<hr>
-<table width="100%" summary="Navigation footer">
-<tr>
-<td width="40%" align="left">
-<a accesskey="p" href="rp-design.html">Prev</a> </td>
-<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
-<td width="40%" align="right"> <a accesskey="n" href="tcl-doc.html">Next</a>
-</td>
-</tr>
-<tr>
-<td width="40%" align="left">OpenACS 4 Request Processor Design </td>
-<td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td>
-<td width="40%" align="right"> Documenting Tcl Files: Page Contracts and Libraries</td>
-</tr>
-</table>
-<hr>
-<address>
- rmello at fslc.usu.edu
- </address>
-<address><a href="mailto:vinod@kurup.com">
+</pre></dd></dl></div><p><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="rp-design.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="tcl-doc.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS 4 Request Processor Design </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> Documenting Tcl Files: Page Contracts and Libraries</td></tr></table><hr><address>rmello at fslc.usu.edu</address><address><a href="mailto:vinod@kurup.com">
vinod@kurup.com
- </a></address>
-</div>
-</body>
-</html>
+ </a></address></div></body></html>
Index: openacs-4/packages/acs-core-docs/www/db-api.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/db-api.html,v
diff -u -r1.7 -r1.7.2.1
--- openacs-4/packages/acs-core-docs/www/db-api.html 7 Mar 2002 06:55:36 -0000 1.7
+++ openacs-4/packages/acs-core-docs/www/db-api.html 15 May 2002 23:26:18 -0000 1.7.2.1
@@ -1,51 +1,16 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type">
-<title>The OpenACS Database Access API</title>
-<meta name="generator" content="DocBook XSL Stylesheets V1.45">
-<link rel="home" href="index.html" title="OpenACS Documentation">
-<link rel="up" href="dev-guide.html" title="Chapter 4. OpenACS Developer's Guide">
-<link rel="previous" href="request-processor.html" title="The Request Processor">
-<link rel="next" href="templates.html" title="Using Templates in OpenACS 4.5">
-<link rel="stylesheet" href="openacs.css" type="text/css">
-</head>
-<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-<div class="navheader">
-<a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr>
-<td width="20%" align="left">
-<a accesskey="p" href="request-processor.html">Prev</a> </td>
-<th width="60%" align="center">Chapter 4. OpenACS Developer's Guide</th>
-<td width="20%" align="right"> <a accesskey="n" href="templates.html">Next</a>
-</td>
-</tr></table>
-<hr>
-</div>
-<div class="sect1">
-<div class="titlepage"><div><h2 class="title" style="clear: both">
-<a name="db-api"></a>The OpenACS Database Access API</h2></div></div>
-<p>
+<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"><title>The OpenACS Database Access API</title><meta name="generator" content="DocBook XSL Stylesheets V1.50.0"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="dev-guide.html" title="Chapter 4. OpenACS Developer's Guide"><link rel="previous" href="request-processor.html" title="The Request Processor"><link rel="next" href="templates.html" title="Using Templates in OpenACS 4.5"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="request-processor.html">Prev</a> </td><th width="60%" align="center">Chapter 4. OpenACS Developer's Guide</th><td width="20%" align="right"> <a accesskey="n" href="templates.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="db-api"></a>The OpenACS Database Access API</h2></div></div><p>
By <a href="mailto:psu@arsdigita.com" target="_top">Pete Su</a> and
<a href="mailto:jsalz@mit.edu" target="_top">Jon Salz</a>. Modified
by Roberto Mello.
- </p>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="db-api-overview"></a>Overview</h3></div></div>
-<p>
+ </p><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="db-api-overview"></a>Overview</h3></div></div><p>
One of OpenACS's great strengths is that code written for it is
very close to the database. It is very easy to interact with the
database from anywhere within OpenACS. Our goal is to develop a
coherent API for database access which makes this even easier.
- </p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="db-api-theoldway"></a>The Old Way</h3></div></div>
-<p>
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="db-api-theoldway"></a>The Old Way</h3></div></div><p>
Here's a typical block of code from an OpenACS 3.x dynamic page:
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
set tcl_var "foo"
set db [ns_db gethandle]
@@ -74,47 +39,33 @@
}
ns_db releasehandle $db
- </pre>
-<p>
+ </pre><p>
Writing code like this had the following annoyances:
- <div class="itemizedlist"><ul>
-<li style="list-style-type: opencircle"><p>
+ </p><div class="itemizedlist"><ul type="opencircle"><li style="list-style-type: opencircle"><p>
It was repetitive, tedious and error prone to write the same type of
loops over and over again.
- </p></li>
-<li style="list-style-type: opencircle"><p>
+ </p></li><li style="list-style-type: opencircle"><p>
Using Tcl variable interpolation in a literal string, to pass values
from the page to the database, is error prone, relatively inefficient,
and a good way to compromise the security of a web site.
- </p></li>
-<li style="list-style-type: opencircle"><p>
+ </p></li><li style="list-style-type: opencircle"><p>
Magic like <tt>set_variables_after_query</tt> made code confusing.
- </p></li>
-<li style="list-style-type: opencircle"><p>
+ </p></li><li style="list-style-type: opencircle"><p>
The scope of transactions is not clear from reading the code.
- </p></li>
-<li style="list-style-type: opencircle"><p>
+ </p></li><li style="list-style-type: opencircle"><p>
Passing handles around explicitly made it easy to use them in bad
ways, like holding a handle for too long while returning data to a
user's browser.
- </p></li>
-</ul></div>
+ </p></li></ul></div><p>
- </p>
-<p>
+ </p><p>
Introduced in ACS 3.4, the new Database API is meant to save
developers from the above tedium and provide a more structured syntax
for specifying database operations, including transactions.
- </p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="db-api-thenewway"></a>The New Way</h3></div></div>
-<p>
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="db-api-thenewway"></a>The New Way</h3></div></div><p>
Here is how you would code up the example above using the new API.
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
set count 0
set tcl_var "foo"
@@ -136,82 +87,62 @@
incr count
}
}
- </pre>
-<p>
+ </pre><p>
There are several things to note here:
- <div class="orderedlist"><ol type="1">
-<li><p>
+ </p><div class="orderedlist"><ol type="1"><li><p>
No explicit code for grabbing and releasing handles. Usage of the
Database API implicitly deals with all handle management issues.
- </p></li>
-<li><p>
+ </p></li><li><p>
The new command <tt>db_transaction</tt>
makes the scope of a transaction
clear. <tt>db_transaction</tt> takes the
code block argument and automatically runs it in the context of a
transaction.
- </p></li>
-<li><p>
+ </p></li><li><p>
The new command <tt>db_foreach</tt> writes
our old while loop for us.
- </p></li>
-<li><p>
+ </p></li><li><p>
Every SQL query has a name, meant to be unique within the server
instance (though this is not enforced).
- </p></li>
-<li><p>
+ </p></li><li><p>
Finally and most importantly, there is a new scheme for passing data
from a Tcl variable to the database, which we'll cover next.
- </p></li>
-</ol></div>
+ </p></li></ol></div><p>
- </p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="db-api-bindvariables"></a>Bind Variables</h3></div></div>
-<p>
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="db-api-bindvariables"></a>Bind Variables</h3></div></div><p>
Bind variables are placeholders for literal values in an SQL query
being sent to the server. Take the example query above: in the old
way, data was generally passed to Oracle directly, via Tcl string
interpolation. So in the example above, the actual query we send would
look like this:
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
select
foo,
bar,
baz
from some_table, some_other_table
where some_table.id=some_other_table.id
and some_table.condition_p = 'foo'
- </pre>
-<p>
+ </pre><p>
There are a few problems with this:
- </p>
-<div class="orderedlist"><ol type="1">
-<li>
+ </p><div class="orderedlist"><ol type="1"><li>
If the literal value is a
huge string, then we waste a lot of time in the database server doing
useless parsing.
- </li>
-<li>
+ </li><li>
Second, if the literal value contains characters like
single quotes, we have to be careful to double-quote them, because not
quoting them will lead to surprising errors.
- </li>
-<li>
-<p>
+ </li><li><p>
Third, no type checking
occurs on the literal value. Finally, if the Tcl variable is passed in
or between web forms or otherwise subject to external modification,
there is nothing keeping malicious users from setting the Tcl variable
to some string that changes the query textually.
- </p>
-<p>
+ </p><p>
This type of attack,
- called <span class="emphasis"><i>SQL smuggling</i></span>, can be very
+ called <span class="emphasis"><em>SQL smuggling</em></span>, can be very
damaging - entire tables can be
exposed or have their contents deleted, for example. Another very
important reason for using bind variables is performance. Oracle caches
@@ -222,28 +153,22 @@
the same) while SQL statements that do not use bind variables will not
match unless the values in the statement are exactly the same. This will
improve performance considerably.
- </p>
-</li>
-</ol></div>
-<p>
+ </p></li></ol></div><p>
To fix all these problems, we replace literal values in the query with
a placeholder character, and then send the data along after. So the
query looks like this:
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
select
foo,
bar,
baz
from some_table, some_other_table
where some_table.id = some_other_table.id
and some_table.condition_p = ?
- </pre>
-<p>
+ </pre><p>
The '?' character means "This will be filled in later with literal
data". In use, you might write code that looks like this:
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
set statement [prepare_query "
select
foo,
@@ -255,93 +180,73 @@
"]
[bind_param $statement 1 $tcl_var]
- </pre>
-<p>
+ </pre><p>
The above example is meant to be psuedo-Tcl - no API like this
actually exists. What happens is that we first send the SQL statement
- to the server for parsing, then later we <span class="emphasis"><i>bind</i></span> values to the
+ to the server for parsing, then later we <span class="emphasis"><em>bind</em></span> values to the
placeholders, and send those values along seperately. This seperate
- binding step is where the term <span class="emphasis"><i>bind variable</i></span> comes from.
- </p>
-<p>
+ binding step is where the term <span class="emphasis"><em>bind variable</em></span> comes from.
+ </p><p>
This split has several advantages. First, type checking happens on the
literal. If the column we are comparing against holds numbers, and we
send a string, we get a nice error. Second, since string literals are
no longer in the query, no extra quoting is required. Third,
substitution of bind variables cannot change the actual text of the
query, only the literal values in the placeholders.
- </p>
-<p>
+ </p><p>
The database API makes bind variables easy to use by hooking them
smoothly into the Tcl runtime. Rather than using a '?' as a generic
placeholder, you use a colon followed by the name of the Tcl variable
that you wish to pass as a literal. So here's the final, real-life
form of the example query:
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
select
foo,
bar,
baz
from some_table, some_other_table
where some_table.id = some_other_table.id
and some_table.condition_p = :tcl_var
- </pre>
-<p>
+ </pre><p>
The database API parses the query and pulls out all the bind variable
specifications and replaces them with generic placeholders. It then
automatically pulls the values of the named Tcl vars out of the
runtime environment of the script, and passes them to the database.
- </p>
-<p>
+ </p><p>
Note that while this looks like a simple syntactic change, it really
is very different from how we've written queries in the past. You use
bind variables to replace what would otherwise be a literal value in a
query, and Tcl style string interpolation does not happen. So you
cannot do something like:
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
set table "baz"
set condition "where foo = bar"
db_foreach my_query { select :table from some_table where :condition }
- </pre>
-<p>
+ </pre><p>
SQL will not allow a literal to occur where we've put the bind
variables, so the query is syntactically incorrect. You have to
remember that while the bind variable syntax looks similar to variable
- interpolation in Tcl, it is <span class="emphasis"><i>not the same thing at all</i></span>.
- </p>
-<p>
+ interpolation in Tcl, it is <span class="emphasis"><em>not the same thing at all</em></span>.
+ </p><p>
Finally, the DB API has several different styles for passing bind
variable values to queries. In general, use the style presented here
because it is the most convenient.
- </p>
-<div class="sect3">
-<div class="titlepage"><div><h4 class="title">
-<a name="db-api-bind-vars-usage"></a>Usage</h4></div></div>
-<p>Every <tt>db_*</tt> command accepting a SQL command as an argument
- supports bind variables. You can either</p>
-<div class="itemizedlist"><ul>
-<li><p>
+ </p><div class="sect3"><div class="titlepage"><div><h4 class="title"><a name="db-api-bind-vars-usage"></a>Usage</h4></div></div><p>Every <tt>db_*</tt> command accepting a SQL command as an argument
+ supports bind variables. You can either</p><div class="itemizedlist"><ul type="disc"><li><p>
Specify the <tt>-bind</tt> switch to provide a set with bind variable
values, or
- </p></li>
-<li><p>
+ </p></li><li><p>
Specify the <tt>-bind</tt> switch to explicitly provide a list of
bind variable names and values, or
- </p></li>
-<li><p>
+ </p></li><li><p>
Not specify a bind variable list at all, in which case Tcl variables are
used as bind variables.
- </p></li>
-</ul></div>
-<p>
+ </p></li></ul></div><p>
The default behavior (i.e., if the <tt>-bind</tt> switch is omitted) is
that these procedures expect to find local variables that correspond in name
to the referenced bind variables, e.g.:
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
set user_id 123456
set role "administrator"
@@ -357,14 +262,11 @@
# of "administrator"
}
- </pre>
-<p>
+ </pre><p>
The value of the local Tcl variable <tt>user_id</tt> (123456) is bound to
the <tt>user_id</tt> bind variable.
- </p>
-<p>The <tt>-bind</tt> switch can takes the name of an <tt>ns_set</tt>
- containing keys for each bind variable named in the query, e.g.:</p>
-<pre class="programlisting">
+ </p><p>The <tt>-bind</tt> switch can takes the name of an <tt>ns_set</tt>
+ containing keys for each bind variable named in the query, e.g.:</p><pre class="programlisting">
set bind_vars [ns_set create]
ns_set put $bind_vars user_id 123456
@@ -381,12 +283,10 @@
# of "administrator"
}
- </pre>
-<p>
+ </pre><p>
Alternatively, as an argument to <tt>-bind</tt> you can specify a list of
alternating name/value pairs for bind variables:
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
db_foreach user_group_memberships_by_role {
select g.group_id, g.group_name
@@ -399,26 +299,18 @@
# of "administrator"
}
- </pre>
-</div>
-<div class="sect3">
-<div class="titlepage"><div><h4 class="title">
-<a name="dbapi_nulls_and_bind_vars"></a>Nulls and Bind Variables</h4></div></div>
-<p>
+ </pre></div><div class="sect3"><div class="titlepage"><div><h4 class="title"><a name="dbapi_nulls_and_bind_vars"></a>Nulls and Bind Variables</h4></div></div><p>
When processing a DML statement, Oracle coerces empty strings into
- <tt>null</tt>. (This coercion does <span class="emphasis"><i>not</i></span> occur in the
+ <tt>null</tt>. (This coercion does <span class="emphasis"><em>not</em></span> occur in the
<tt>WHERE</tt> clause of a query, i.e.
<tt>col = ''</tt> and
<tt>col is null</tt> are not equivalent.)
- </p>
-<p>As a result, when using bind variables, the only way to make Oracle set a
+ </p><p>As a result, when using bind variables, the only way to make Oracle set a
column value to <tt>null</tt> is to set the corresponding bind variable
to the empty string, since a bind variable whose value is the string
"null" will be interpreted as the literal string
- "null".</p>
-<p>These Oracle quirks complicate the process of writing clear and abstract
- DML difficult. Here is an example that illustrates why:</p>
-<pre class="programlisting">
+ "null".</p><p>These Oracle quirks complicate the process of writing clear and abstract
+ DML difficult. Here is an example that illustrates why:</p><pre class="programlisting">
#
# Given the table:
@@ -438,19 +330,15 @@
# null, because Oracle has coerced the empty string (even for the
# numeric column "bar") into null in both cases
- </pre>
-<p>
+ </pre><p>
Since databases other than Oracle do not coerce empty strings into
<tt>null</tt>, this code has different semantics depending on the
underlying database (i.e., the row that gets inserted may not have null as
its column values), which defeats the purpose of SQL abstraction.
- </p>
-<p>Therefore, the Database Access API provides a database-independent way to
+ </p><p>Therefore, the Database Access API provides a database-independent way to
represent <tt>null</tt> (instead of the Oracle-specific idiom of the
- empty string): <tt>db_null</tt>.</p>
-<p>Use it instead of the empty string whenever you want to set a column value
- explicitly to <tt>null</tt>, e.g.:</p>
-<pre class="programlisting">
+ empty string): <tt>db_null</tt>.</p><p>Use it instead of the empty string whenever you want to set a column value
+ explicitly to <tt>null</tt>, e.g.:</p><pre class="programlisting">
set bar [db_null]
set baz [db_null]
@@ -459,13 +347,7 @@
#
# sets the values for both the "bar" and "baz" columns to null
- </pre>
-</div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="db-api-pooling"></a>Sequence Pooling</h3></div></div>
-<p>
+ </pre></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="db-api-pooling"></a>Sequence Pooling</h3></div></div><p>
The database library can transparently maintain pools of sequence values, so
that each request for a new sequence value (using <tt>db_nextval</tt>)
does not incur a roundtrip to the server. For instance, this functionality is
@@ -474,324 +356,233 @@
functionality for a particular sequence, register the sequence to be pooled,
either using the <tt>db_register_pooled_sequence</tt> procedure at server
startup time, or by including a configuration parameter of the form
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
-PoolSequence.<span class="emphasis"><i>sequence_name_seq</i></span>=<span class="emphasis"><i>count</i></span>
+PoolSequence.<span class="emphasis"><em>sequence_name_seq</em></span>=<span class="emphasis"><em>count</em></span>
- </pre>
-<p>
- in <span class="emphasis"><i>any</i></span> configuration section in the <tt>yourservername.ini</tt>
+ </pre><p>
+ in <span class="emphasis"><em>any</em></span> configuration section in the <tt>yourservername.ini</tt>
file, e.g., e.g.,
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
-[ns/server/<span class="emphasis"><i>yourservername</i></span>/acs/security]
+[ns/server/<span class="emphasis"><em>yourservername</em></span>/acs/security]
PoolSequence.sec_id_seq=20
- </pre>
-<p>
+ </pre><p>
The database library will allocate this number of sequence values at server
startup. It will periodically scan pools and allocate new values for
sequences which are less than half-full. (This normally occurs every 60
seconds, and is configurable via the
<tt>PooledSequenceUpdateInterval</tt> parameter in the
<tt>[ns/server/</tt>
- <span class="emphasis"><i><tt>yourservername</tt></i></span>
+ <span class="emphasis"><em><tt>yourservername</tt></em></span>
<tt>/acs/database]</tt> configuration
section.)
- </p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="db-api-basicapi"></a>Basic API</h3></div></div>
-<p>
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="db-api-basicapi"></a>Basic API</h3></div></div><p>
The Database API has several functions that wrap familiar parts of the
AOLserver database API.
- </p>
-<p>
+ </p><p>
Note that you never have to use <tt>ns_db</tt> anymore (including
<tt>ns_db gethandle</tt>)! Just start doing stuff, and (if you want) call
<tt>db_release_unused_handles</tt> when you're done as a hint to
release the database handle.
- </p>
-<div class="variablelist"><dl>
-<dt><span class="term">
+ </p><div class="variablelist"><dl><dt><span class="term">
<tt>
<a name="devguide.dbapi_db_abort_transaction"></a>db_abort_transaction
</tt>
- </span></dt>
-<dd>
-<pre class="programlisting">
+ </span></dt><dd><pre class="programlisting">
db_abort_transaction
- </pre>
-<p>Aborts all levels of a transaction. That is if this is called within
+ </pre><p>Aborts all levels of a transaction. That is if this is called within
several nested transactions, all of them are terminated. Use this insetead of
<tt>db_dml "abort" "abort transaction"</tt>.
- </p>
-</dd>
-<dt><span class="term">
+ </p></dd><dt><span class="term">
<tt>
<a name="devguide.dbapi_db_null"></a>db_null
</tt>
- </span></dt>
-<dd>
-<pre class="programlisting">
+ </span></dt><dd><pre class="programlisting">
<tt>db_null</tt>
- </pre>
-<p>
+ </pre><p>
Returns a value which can be used in a bind variable
to represent the SQL value
<tt>null</tt>.
See <a href="db-api.html#dbapi_nulls_and_bind_vars" title="Nulls and Bind Variables">Nulls and
Bind Variables</a> above.
- </p>
-</dd>
-<dt><span class="term">
+ </p></dd><dt><span class="term">
<tt>
<a name="devguide.dbapi_db_foreach"></a>db_foreach
</tt>
- </span></dt>
-<dd>
-<pre class="programlisting">
-db_foreach <span class="emphasis"><i>statement-name sql</i></span> [ -bind <span class="emphasis"><i>bind_set_id</i></span> | -bind <span class="emphasis"><i>bind_value_list</i></span> ] \
- [ -column_array <span class="emphasis"><i>array_name</i></span> | -column_set <span class="emphasis"><i>set_name</i></span> ] \
- <span class="emphasis"><i>code_block</i></span> [ if_no_rows <span class="emphasis"><i>if_no_rows_block ]</i></span>
- </pre>
-<p>
- Performs the SQL query <span class="emphasis"><i>
+ </span></dt><dd><pre class="programlisting">
+db_foreach <span class="emphasis"><em>statement-name sql</em></span> [ -bind <span class="emphasis"><em>bind_set_id</em></span> | -bind <span class="emphasis"><em>bind_value_list</em></span> ] \
+ [ -column_array <span class="emphasis"><em>array_name</em></span> | -column_set <span class="emphasis"><em>set_name</em></span> ] \
+ <span class="emphasis"><em>code_block</em></span> [ if_no_rows <span class="emphasis"><em>if_no_rows_block ]</em></span>
+ </pre><p>
+ Performs the SQL query <span class="emphasis"><em>
<tt>sql</tt>
- </i></span>, executing
- <span class="emphasis"><i><tt>code_block
- </tt></i></span> once for each row
+ </em></span>, executing
+ <span class="emphasis"><em><tt>code_block
+ </tt></em></span> once for each row
with variables set to column values (or a set or array
populated if
<tt>-column_array</tt> or
<tt>column_set</tt> is
specified). If the query returns no rows, executes
- <span class="emphasis"><i><tt>if_no_rows_block
- </tt></i></span> (if provided).
- </p>
-<p>Example:</p>
-<pre class="programlisting">
+ <span class="emphasis"><em><tt>if_no_rows_block
+ </tt></em></span> (if provided).
+ </p><p>Example:</p><pre class="programlisting">
db_foreach select_foo "select foo, bar from greeble" {
doc_body_append "<li>foo=$foo; bar=$bar\n"
} if_no_rows {
doc_body_append "<li>There are no greebles in the database.\n"
}
- </pre>
-<p>
+ </pre><p>
The code block may contain <tt>break</tt> statements (which terminate the
loop and flush the database handle) and <tt>continue</tt> statements
- (which continue to the next row of the loop). </p>
-</dd>
-<dt><span class="term">
+ (which continue to the next row of the loop). </p></dd><dt><span class="term">
<tt>
<a name="devguide.dbapi_db_1row"></a>db_1row
</tt>
- </span></dt>
-<dd>
-<pre class="programlisting">
-db_1row <span class="emphasis"><i>statement-name</i></span> <span class="emphasis"><i>sql</i></span> [ -bind <span class="emphasis"><i>bind_set_id</i></span> | -bind <span class="emphasis"><i>bind_value_list</i></span> ] \
- [ -column_array <span class="emphasis"><i>array_name</i></span> | -column_set <span class="emphasis"><i>set_name</i></span> ]
- </pre>
-<p>
- Performs the SQL query <span class="emphasis"><i>
- <tt>sql</tt></i></span>,
+ </span></dt><dd><pre class="programlisting">
+db_1row <span class="emphasis"><em>statement-name</em></span> <span class="emphasis"><em>sql</em></span> [ -bind <span class="emphasis"><em>bind_set_id</em></span> | -bind <span class="emphasis"><em>bind_value_list</em></span> ] \
+ [ -column_array <span class="emphasis"><em>array_name</em></span> | -column_set <span class="emphasis"><em>set_name</em></span> ]
+ </pre><p>
+ Performs the SQL query <span class="emphasis"><em>
+ <tt>sql</tt></em></span>,
setting variables to column values. Raises an error if the
query does not return exactly 1 row.
- </p>
-<p>Example:</p>
-<pre class="programlisting">
+ </p><p>Example:</p><pre class="programlisting">
db_1row select_foo "select foo, bar from greeble where greeble_id = $greeble_id"
# Bombs if there's no such greeble!
# Now $foo and $bar are set.
- </pre>
-</dd>
-<dt><span class="term">
+ </pre></dd><dt><span class="term">
<tt>
<a name="devguide.dbapi_db_0or1row"></a>db_0or1row
</tt>
- </span></dt>
-<dd>
-<pre class="programlisting">
-db_0or1row <span class="emphasis"><i>statement-name</i></span> <span class="emphasis"><i>sql</i></span> [ -bind <span class="emphasis"><i>bind_set_id</i></span> | -bind <span class="emphasis"><i>bind_value_list</i></span> ] \
- [ -column_array <span class="emphasis"><i>array_name</i></span> | -column_set <span class="emphasis"><i>set_name</i></span> ]
- </pre>
-<p>
+ </span></dt><dd><pre class="programlisting">
+db_0or1row <span class="emphasis"><em>statement-name</em></span> <span class="emphasis"><em>sql</em></span> [ -bind <span class="emphasis"><em>bind_set_id</em></span> | -bind <span class="emphasis"><em>bind_value_list</em></span> ] \
+ [ -column_array <span class="emphasis"><em>array_name</em></span> | -column_set <span class="emphasis"><em>set_name</em></span> ]
+ </pre><p>
Performs the SQL query
- <span class="emphasis"><i><tt>sql</tt></i></span>.
+ <span class="emphasis"><em><tt>sql</tt></em></span>.
If a row is returned, sets variables to column values and
returns 1. If no rows are returned, returns 0. If more
than one row is returned, throws an error.
- </p>
-</dd>
-<dt><span class="term"><tt><a name="devguide.dbapi_db_nextval"></a>db_nextval</tt> </span></dt>
-<dd>
-<pre class="programlisting">
-db_nextval <span class="emphasis"><i>sequence-name</i></span>
- </pre>
-<p>
- Returns the next value for the sequence <span class="emphasis"><i>sequence-name</i></span> (using a
+ </p></dd><dt><span class="term"><tt><a name="devguide.dbapi_db_nextval"></a>db_nextval</tt> </span></dt><dd><pre class="programlisting">
+db_nextval <span class="emphasis"><em>sequence-name</em></span>
+ </pre><p>
+ Returns the next value for the sequence <span class="emphasis"><em>sequence-name</em></span> (using a
SQL statement like <tt>SELECT</tt>
- <span class="emphasis"><i><tt>sequence-name</tt></i></span><tt>.nextval FROM
+ <span class="emphasis"><em><tt>sequence-name</tt></em></span><tt>.nextval FROM
DUAL</tt>). If sequence pooling is enabled for the sequence, transparently
uses a value from the pool if available to save a round-trip to the database
- (see <span class="emphasis"><i><a href="db-api.html#db-api-pooling">Sequence Pooling</a></i></span>).
- </p>
-</dd>
-<dt><span class="term">
+ (see <span class="emphasis"><em><a href="db-api.html#db-api-pooling">Sequence Pooling</a></em></span>).
+ </p></dd><dt><span class="term">
<tt>
<a name="devguide.dbapi_db_register_pooled_sequence"></a>db_register_pooled_sequence
</tt>
- </span></dt>
-<dd>
-<pre class="programlisting">
-db_register_pooled_sequence <span class="emphasis"><i>sequence-name</i></span> <span class="emphasis"><i>pool-size</i></span>
- </pre>
-<p>Registers the sequence <span class="emphasis"><i>sequence-name</i></span> to be pooled, with a pool
- size of <span class="emphasis"><i>pool-size</i></span> sequence values
- (see <span class="emphasis"><i><a href="db-api.html#db-api-pooling">Sequence Pooling</a></i></span>).
+ </span></dt><dd><pre class="programlisting">
+db_register_pooled_sequence <span class="emphasis"><em>sequence-name</em></span> <span class="emphasis"><em>pool-size</em></span>
+ </pre><p>Registers the sequence <span class="emphasis"><em>sequence-name</em></span> to be pooled, with a pool
+ size of <span class="emphasis"><em>pool-size</em></span> sequence values
+ (see <span class="emphasis"><em><a href="db-api.html#db-api-pooling">Sequence Pooling</a></em></span>).
- </p>
-</dd>
-<dt><span class="term"><tt><a name="devguide.dbapi_db_string"></a>db_string</tt> </span></dt>
-<dd>
-<pre class="programlisting">
-db_string <span class="emphasis"><i>statement-name</i></span> <span class="emphasis"><i>sql</i></span> [ -default <span class="emphasis"><i>default</i></span> ] [ -bind <span class="emphasis"><i>bind_set_id</i></span> | -bind <span class="emphasis"><i>bind_value_list</i></span> ]
- </pre>
-<p>Returns the first column of the result of SQL query
- <span class="emphasis"><i><tt>sql</tt></i></span>.
- If <span class="emphasis"><i><tt>sql</tt></i></span> doesn't return a
+ </p></dd><dt><span class="term"><tt><a name="devguide.dbapi_db_string"></a>db_string</tt> </span></dt><dd><pre class="programlisting">
+db_string <span class="emphasis"><em>statement-name</em></span> <span class="emphasis"><em>sql</em></span> [ -default <span class="emphasis"><em>default</em></span> ] [ -bind <span class="emphasis"><em>bind_set_id</em></span> | -bind <span class="emphasis"><em>bind_value_list</em></span> ]
+ </pre><p>Returns the first column of the result of SQL query
+ <span class="emphasis"><em><tt>sql</tt></em></span>.
+ If <span class="emphasis"><em><tt>sql</tt></em></span> doesn't return a
row, returns
- <span class="emphasis"><i><tt>default</tt></i></span>
+ <span class="emphasis"><em><tt>default</tt></em></span>
(or throws an error if
- <span class="emphasis"><i><tt>default</tt></i></span> is unspecified). Analogous to
+ <span class="emphasis"><em><tt>default</tt></em></span> is unspecified). Analogous to
<tt>database_to_tcl_string</tt> and
<tt>database_to_tcl_string_or_null</tt>.
- </p>
-</dd>
-<dt><span class="term"><tt><a name="devguide.dbapi_db_list"></a>db_list</tt></span></dt>
-<dd>
-<pre class="programlisting">
-db_list <span class="emphasis"><i>statement-name</i></span> <span class="emphasis"><i>sql</i></span> [ -bind <span class="emphasis"><i>bind_set_id</i></span> | -bind <span class="emphasis"><i>bind_value_list</i></span> ]
- </pre>
-<p>Returns a Tcl list of the values in the first column of the result of SQL
+ </p></dd><dt><span class="term"><tt><a name="devguide.dbapi_db_list"></a>db_list</tt></span></dt><dd><pre class="programlisting">
+db_list <span class="emphasis"><em>statement-name</em></span> <span class="emphasis"><em>sql</em></span> [ -bind <span class="emphasis"><em>bind_set_id</em></span> | -bind <span class="emphasis"><em>bind_value_list</em></span> ]
+ </pre><p>Returns a Tcl list of the values in the first column of the result of SQL
query
- <span class="emphasis"><i><tt>sql</tt></i></span>.
- If <span class="emphasis"><i><tt>sql</tt></i></span> doesn't
+ <span class="emphasis"><em><tt>sql</tt></em></span>.
+ If <span class="emphasis"><em><tt>sql</tt></em></span> doesn't
return any rows, returns an empty list. Analogous to
<tt>database_to_tcl_list</tt>.
- </p>
-</dd>
-<dt><span class="term"><tt><a name="devguide.dbapi_db_list_of_lists"></a>db_list_of_lists</tt></span></dt>
-<dd>
-<pre class="programlisting">
-db_list_of_lists <span class="emphasis"><i>statement-name</i></span> <span class="emphasis"><i>sql</i></span> [ -bind <span class="emphasis"><i>bind_set_id</i></span> | -bind <span class="emphasis"><i>bind_value_list</i></span> ]
- </pre>
-<p>Returns a Tcl list, each element of which is a list of all column values
- in a row of the result of SQL query <span class="emphasis"><i><tt>sql</tt></i></span>. If
- <span class="emphasis"><i><tt>sql</tt></i></span> doesn't return any rows, returns an empty list.
+ </p></dd><dt><span class="term"><tt><a name="devguide.dbapi_db_list_of_lists"></a>db_list_of_lists</tt></span></dt><dd><pre class="programlisting">
+db_list_of_lists <span class="emphasis"><em>statement-name</em></span> <span class="emphasis"><em>sql</em></span> [ -bind <span class="emphasis"><em>bind_set_id</em></span> | -bind <span class="emphasis"><em>bind_value_list</em></span> ]
+ </pre><p>Returns a Tcl list, each element of which is a list of all column values
+ in a row of the result of SQL query <span class="emphasis"><em><tt>sql</tt></em></span>. If
+ <span class="emphasis"><em><tt>sql</tt></em></span> doesn't return any rows, returns an empty list.
(Analogous to <tt>database_to_tcl_list_list</tt>.)
- </p>
-</dd>
-<dt><span class="term"><tt><a name="devguide.dbapi_db_dml"></a>db_dml</tt></span></dt>
-<dd>
-<pre class="programlisting">
-db_dml <span class="emphasis"><i>statement-name</i></span> <span class="emphasis"><i>sql</i></span> \
- [ -bind <span class="emphasis"><i>bind_set_id</i></span> | -bind <span class="emphasis"><i>bind_value_list</i></span> ] \
- [ -blobs <span class="emphasis"><i>blob_list</i></span> | -clobs <span class="emphasis"><i>clob_list</i></span> |
- -blob_files <span class="emphasis"><i>blob_file_list</i></span> | -clob_files <span class="emphasis"><i>clob_file_list</i></span> ]
- </pre>
-<p>Performs the DML or DDL statement <span class="emphasis"><i><tt>sql</tt></i></span>. </p>
-<p>If a length-<span class="emphasis"><i>n</i></span> list of blobs or clobs is provided, then the SQL
- should return <span class="emphasis"><i>n</i></span> blobs or clobs into the bind variables
- <tt>:1</tt>, <tt>:2</tt>, ... :<span class="emphasis"><i><tt>n</tt></i></span>.
- <span class="emphasis"><i><tt>blobs</tt></i></span> or <span class="emphasis"><i><tt>clobs</tt></i></span>, if specified,
+ </p></dd><dt><span class="term"><tt><a name="devguide.dbapi_db_dml"></a>db_dml</tt></span></dt><dd><pre class="programlisting">
+db_dml <span class="emphasis"><em>statement-name</em></span> <span class="emphasis"><em>sql</em></span> \
+ [ -bind <span class="emphasis"><em>bind_set_id</em></span> | -bind <span class="emphasis"><em>bind_value_list</em></span> ] \
+ [ -blobs <span class="emphasis"><em>blob_list</em></span> | -clobs <span class="emphasis"><em>clob_list</em></span> |
+ -blob_files <span class="emphasis"><em>blob_file_list</em></span> | -clob_files <span class="emphasis"><em>clob_file_list</em></span> ]
+ </pre><p>Performs the DML or DDL statement <span class="emphasis"><em><tt>sql</tt></em></span>. </p><p>If a length-<span class="emphasis"><em>n</em></span> list of blobs or clobs is provided, then the SQL
+ should return <span class="emphasis"><em>n</em></span> blobs or clobs into the bind variables
+ <tt>:1</tt>, <tt>:2</tt>, ... :<span class="emphasis"><em><tt>n</tt></em></span>.
+ <span class="emphasis"><em><tt>blobs</tt></em></span> or <span class="emphasis"><em><tt>clobs</tt></em></span>, if specified,
should be a list of individual BLOBs or CLOBs to insert;
- <span class="emphasis"><i><tt>blob_files</tt></i></span> or <span class="emphasis"><i><tt>clob_files</tt></i></span>, if
- specified, should be a list of <span class="emphasis"><i>paths to files</i></span> containing the data to
+ <span class="emphasis"><em><tt>blob_files</tt></em></span> or <span class="emphasis"><em><tt>clob_files</tt></em></span>, if
+ specified, should be a list of <span class="emphasis"><em>paths to files</em></span> containing the data to
insert. Only one of <tt>-blobs</tt>, <tt>-clobs</tt>,
- <tt>-blob_files</tt>, and <tt>-clob_files</tt> may be provided.</p>
-<p>Example:</p>
-<pre class="programlisting">
+ <tt>-blob_files</tt>, and <tt>-clob_files</tt> may be provided.</p><p>Example:</p><pre class="programlisting">
db_dml insert_photos "
insert photos(photo_id, image, thumbnail_image)
values(photo_id_seq.nextval, empty_blob(), empty_blob())
returning image, thumbnail_image into :1, :2
" -blob_files [list "/var/tmp/the_photo" "/var/tmp/the_thumbnail"]
- </pre>
-<p>
+ </pre><p>
This inserts a new row into the <tt>photos</tt> table, with the contents
of the files <tt>/var/tmp/the_photo</tt> and
<tt>/var/tmp/the_thumbnail</tt> in the <tt>image</tt> and
<tt>thumbnail</tt> columns, respectively.
- </p>
-</dd>
-<dt><span class="term">
+ </p></dd><dt><span class="term">
<tt><a name="devguide.dbapi_db_write_clob"></a>db_write_clob</tt>,
<tt><a name="devguide.dbapi_db_write_blob"></a>db_write_blob</tt>,
<tt><a name="devguide.dbapi_db_blob_get_file"></a>db_blob_get_file</tt>
- </span></dt>
-<dd>
-<pre class="programlisting">
-db_write_clob <span class="emphasis"><i>statement-name</i></span> <span class="emphasis"><i>sql</i></span> [ -bind <span class="emphasis"><i>bind_set_id</i></span> | -bind <span class="emphasis"><i>bind_value_list</i></span> ]
+ </span></dt><dd><pre class="programlisting">
+db_write_clob <span class="emphasis"><em>statement-name</em></span> <span class="emphasis"><em>sql</em></span> [ -bind <span class="emphasis"><em>bind_set_id</em></span> | -bind <span class="emphasis"><em>bind_value_list</em></span> ]
-db_write_blob <span class="emphasis"><i>statement-name</i></span> <span class="emphasis"><i>sql</i></span> [ -bind <span class="emphasis"><i>bind_set_id</i></span> | -bind <span class="emphasis"><i>bind_value_list</i></span> ]
+db_write_blob <span class="emphasis"><em>statement-name</em></span> <span class="emphasis"><em>sql</em></span> [ -bind <span class="emphasis"><em>bind_set_id</em></span> | -bind <span class="emphasis"><em>bind_value_list</em></span> ]
-db_blob_get_file <span class="emphasis"><i>statement-name</i></span> <span class="emphasis"><i>sql</i></span> [ -bind <span class="emphasis"><i>bind_set_id</i></span> | -bind <span class="emphasis"><i>bind_value_list</i></span> ]
- </pre>
-<p>Analagous to <tt>ns_ora write_clob/write_blob/blob_get_file</tt>.
+db_blob_get_file <span class="emphasis"><em>statement-name</em></span> <span class="emphasis"><em>sql</em></span> [ -bind <span class="emphasis"><em>bind_set_id</em></span> | -bind <span class="emphasis"><em>bind_value_list</em></span> ]
+ </pre><p>Analagous to <tt>ns_ora write_clob/write_blob/blob_get_file</tt>.
- </p>
-</dd>
-<dt><span class="term"><tt><a name="devguide.dbapi_db_release_unused_handles"></a>db_release_unused_handles</tt></span></dt>
-<dd>
-<pre class="programlisting">
+ </p></dd><dt><span class="term"><tt><a name="devguide.dbapi_db_release_unused_handles"></a>db_release_unused_handles</tt></span></dt><dd><pre class="programlisting">
db_release_unused_handles
- </pre>
-<p>Releases any allocated, unused database handles. </p>
-</dd>
-<dt><span class="term"><tt><a name="devguide.dbapi_db_transaction"></a>db_transaction</tt></span></dt>
-<dd>
-<pre class="programlisting">
-db_transaction <span class="emphasis"><i>code_block</i></span> [ on_error { <span class="emphasis"><i>code_block</i></span> } ]
- </pre>
-<p>Executes <span class="emphasis"><i><tt>code_block</tt></i></span> transactionally. Nested
+ </pre><p>Releases any allocated, unused database handles. </p></dd><dt><span class="term"><tt><a name="devguide.dbapi_db_transaction"></a>db_transaction</tt></span></dt><dd><pre class="programlisting">
+db_transaction <span class="emphasis"><em>code_block</em></span> [ on_error { <span class="emphasis"><em>code_block</em></span> } ]
+ </pre><p>Executes <span class="emphasis"><em><tt>code_block</tt></em></span> transactionally. Nested
transactions are supported (<tt>end transaction</tt> is transparently
<tt>ns_db dml</tt>'ed when the outermost transaction completes). The
<tt>db_abort_transaction</tt> command can be used to abort all levels of
transactions. It is possible to specify an optional <tt>on_error</tt>
- code block that will be executed if some code in <span class="emphasis"><i>code_block</i></span> throws
+ code block that will be executed if some code in <span class="emphasis"><em>code_block</em></span> throws
an exception. The variable <tt>errmsg</tt> will be bound in that scope.
- If there is no <tt>on_error</tt> code, any errors will be propagated. </p>
-<p>Example:</p>
-<pre class="programlisting">
+ If there is no <tt>on_error</tt> code, any errors will be propagated. </p><p>Example:</p><pre class="programlisting">
proc replace_the_foo { col } {
db_transaction {
@@ -820,30 +611,18 @@
print_the_foo ; # Writes out "foo is 8"
- </pre>
-</dd>
-<dt><span class="term"><tt><a name="devguide.dbapi_db_resultrows"></a>db_resultrows</tt></span></dt>
-<dd>
-<pre class="programlisting">
+ </pre></dd><dt><span class="term"><tt><a name="devguide.dbapi_db_resultrows"></a>db_resultrows</tt></span></dt><dd><pre class="programlisting">
db_resultrows
- </pre>
-<p>Returns the number of rows affected or returned by the previous
+ </pre><p>Returns the number of rows affected or returned by the previous
statement.
- </p>
-</dd>
-<dt><span class="term"><tt><a name="devguide.dbapi_db_with_handle"></a>db_with_handle</tt></span></dt>
-<dd>
-<pre class="programlisting">
-db_with_handle <span class="emphasis"><i>var</i></span> <span class="emphasis"><i>code_block</i></span>
- </pre>
-<p>Places a database handle into the variable <span class="emphasis"><i><tt>var</tt></i></span> and
- executes <span class="emphasis"><i><tt>code_block</tt></i></span>. This is useful when you don't
+ </p></dd><dt><span class="term"><tt><a name="devguide.dbapi_db_with_handle"></a>db_with_handle</tt></span></dt><dd><pre class="programlisting">
+db_with_handle <span class="emphasis"><em>var</em></span> <span class="emphasis"><em>code_block</em></span>
+ </pre><p>Places a database handle into the variable <span class="emphasis"><em><tt>var</tt></em></span> and
+ executes <span class="emphasis"><em><tt>code_block</tt></em></span>. This is useful when you don't
want to have to use the new API (<tt>db_foreach</tt>,
- <tt>db_1row</tt>, etc.), but need to use database handles explicitly. </p>
-<p>Example:</p>
-<pre class="programlisting">
+ <tt>db_1row</tt>, etc.), but need to use database handles explicitly. </p><p>Example:</p><pre class="programlisting">
proc lookup_the_foo { foo } {
db_with_handle db {
@@ -861,24 +640,18 @@
}
}
- </pre>
-</dd>
-<dt><span class="term">
+ </pre></dd><dt><span class="term">
<tt>
<a name="devguide.dbapi_db_nullify_empty_string"></a>db_nullify_empty_string
</tt>
- </span></dt>
-<dd>
-<pre class="programlisting">
-db_nullify_empty_string <span class="emphasis"><i>string</i></span>
- </pre>
-<p>For true SQL purists, we provide the convenience function
+ </span></dt><dd><pre class="programlisting">
+db_nullify_empty_string <span class="emphasis"><em>string</em></span>
+ </pre><p>For true SQL purists, we provide the convenience function
<tt>db_nullify_empty_string</tt>, which returns
- [db_null] if its <span class="emphasis"><i><tt>string</tt></i></span> argument is the empty string
- and can be used to encapsulate another Oracle quirk: </p>
-<pre class="programlisting">
+ [db_null] if its <span class="emphasis"><em><tt>string</tt></em></span> argument is the empty string
+ and can be used to encapsulate another Oracle quirk: </p><pre class="programlisting">
set baz ""
@@ -894,46 +667,15 @@
# the empty string we just inserted (because of Oracle's coercion
# quirk)
- </pre>
-<p>
+ </pre><p>
To balance out this asymmetry, you can explicitly set <tt>baz</tt> to
<tt>null</tt> by writing:
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
db_dml foo_insert "insert into foo(baz) values(:1)" {[db_nullify_empty_string $baz]}
- </pre>
-</dd>
-</dl></div>
-<p>
- <div class="cvstag">($Id$)</div>
- </p>
-</div>
-</div>
-<div class="navfooter">
-<hr>
-<table width="100%" summary="Navigation footer">
-<tr>
-<td width="40%" align="left">
-<a accesskey="p" href="request-processor.html">Prev</a> </td>
-<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
-<td width="40%" align="right"> <a accesskey="n" href="templates.html">Next</a>
-</td>
-</tr>
-<tr>
-<td width="40%" align="left">The Request Processor </td>
-<td width="20%" align="center"><a accesskey="u" href="dev-guide.html">Up</a></td>
-<td width="40%" align="right"> Using Templates in OpenACS 4.5</td>
-</tr>
-</table>
-<hr>
-<address>
- rmello at fslc.usu.edu
- </address>
-<address><a href="mailto:vinod@kurup.com">
+ </pre></dd></dl></div><p>
+ </p><div class="cvstag">($Id$)</div><p>
+ </p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="request-processor.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="templates.html">Next</a></td></tr><tr><td width="40%" align="left">The Request Processor </td><td width="20%" align="center"><a accesskey="u" href="dev-guide.html">Up</a></td><td width="40%" align="right"> Using Templates in OpenACS 4.5</td></tr></table><hr><address>rmello at fslc.usu.edu</address><address><a href="mailto:vinod@kurup.com">
vinod@kurup.com
- </a></address>
-</div>
-</body>
-</html>
+ </a></address></div></body></html>
Index: openacs-4/packages/acs-core-docs/www/dev-guide.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/dev-guide.html,v
diff -u -r1.6 -r1.6.2.1
--- openacs-4/packages/acs-core-docs/www/dev-guide.html 7 Mar 2002 06:55:36 -0000 1.6
+++ openacs-4/packages/acs-core-docs/www/dev-guide.html 15 May 2002 23:26:18 -0000 1.6.2.1
@@ -1,66 +1,4 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type">
-<title>Chapter 4. OpenACS Developer's Guide</title>
-<meta name="generator" content="DocBook XSL Stylesheets V1.45">
-<link rel="home" href="index.html" title="OpenACS Documentation">
-<link rel="up" href="acs-dev.html" title="Part Part III. For OpenACS Developers">
-<link rel="previous" href="acs-dev.html" title="Part Part III. For OpenACS Developers">
-<link rel="next" href="developers-overview.html" title="Overview">
-<link rel="stylesheet" href="openacs.css" type="text/css">
-</head>
-<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-<div class="navheader">
-<a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr>
-<td width="20%" align="left">
-<a accesskey="p" href="acs-dev.html">Prev</a> </td>
-<th width="60%" align="center">Part Part III. For OpenACS Developers</th>
-<td width="20%" align="right"> <a accesskey="n" href="developers-overview.html">Next</a>
-</td>
-</tr></table>
-<hr>
-</div>
-<div class="chapter">
-<div class="titlepage"><div><h2 class="title">
-<a name="dev-guide"></a>Chapter 4. OpenACS Developer's Guide</h2></div></div>
-<div class="toc">
-<p><b>Table of Contents</b></p>
-<dl>
-<dt><a href="developers-overview.html">Overview</a></dt>
-<dt><a href="objects.html">OpenACS 4.5 Data Models and the Object System</a></dt>
-<dt><a href="packages.html">OpenACS 4.5 Packages</a></dt>
-<dt><a href="request-processor.html">The Request Processor</a></dt>
-<dt><a href="db-api.html">The OpenACS Database Access API</a></dt>
-<dt><a href="templates.html">Using Templates in OpenACS 4.5</a></dt>
-<dt><a href="permissions.html">Groups, Context, Permissions</a></dt>
-<dt><a href="subsites.html">Writing OpenACS 4.5 Application Pages</a></dt>
-</dl>
-</div>
-</div>
-<div class="navfooter">
-<hr>
-<table width="100%" summary="Navigation footer">
-<tr>
-<td width="40%" align="left">
-<a accesskey="p" href="acs-dev.html">Prev</a> </td>
-<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
-<td width="40%" align="right"> <a accesskey="n" href="developers-overview.html">Next</a>
-</td>
-</tr>
-<tr>
-<td width="40%" align="left">Part Part III. For OpenACS Developers </td>
-<td width="20%" align="center"><a accesskey="u" href="acs-dev.html">Up</a></td>
-<td width="40%" align="right"> Overview</td>
-</tr>
-</table>
-<hr>
-<address>
- rmello at fslc.usu.edu
- </address>
-<address><a href="mailto:vinod@kurup.com">
+<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"><title>Chapter 4. OpenACS Developer's Guide</title><meta name="generator" content="DocBook XSL Stylesheets V1.50.0"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="acs-dev.html" title="Part Part III. For OpenACS Developers"><link rel="previous" href="acs-dev.html" title="Part Part III. For OpenACS Developers"><link rel="next" href="developers-overview.html" title="Overview"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="acs-dev.html">Prev</a> </td><th width="60%" align="center">Part Part III. For OpenACS Developers</th><td width="20%" align="right"> <a accesskey="n" href="developers-overview.html">Next</a></td></tr></table><hr></div><div class="chapter"><div class="titlepage"><div><h2 class="title"><a name="dev-guide"></a>Chapter 4. OpenACS Developer's Guide</h2></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a href="developers-overview.html">Overview</a></dt><dt><a href="objects.html">OpenACS 4.5 Data Models and the Object System</a></dt><dt><a href="packages.html">OpenACS 4.5 Packages</a></dt><dt><a href="request-processor.html">The Request Processor</a></dt><dt><a href="db-api.html">The OpenACS Database Access API</a></dt><dt><a href="templates.html">Using Templates in OpenACS 4.5</a></dt><dt><a href="permissions.html">Groups, Context, Permissions</a></dt><dt><a href="subsites.html">Writing OpenACS 4.5 Application Pages</a></dt></dl></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="acs-dev.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="developers-overview.html">Next</a></td></tr><tr><td width="40%" align="left">Part Part III. For OpenACS Developers </td><td width="20%" align="center"><a accesskey="u" href="acs-dev.html">Up</a></td><td width="40%" align="right"> Overview</td></tr></table><hr><address>rmello at fslc.usu.edu</address><address><a href="mailto:vinod@kurup.com">
vinod@kurup.com
- </a></address>
-</div>
-</body>
-</html>
+ </a></address></div></body></html>
Index: openacs-4/packages/acs-core-docs/www/developers-overview.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/Attic/developers-overview.html,v
diff -u -r1.2 -r1.2.2.1
--- openacs-4/packages/acs-core-docs/www/developers-overview.html 7 Mar 2002 06:55:36 -0000 1.2
+++ openacs-4/packages/acs-core-docs/www/developers-overview.html 15 May 2002 23:26:18 -0000 1.2.2.1
@@ -1,54 +1,4 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type">
-<title>Overview</title>
-<meta name="generator" content="DocBook XSL Stylesheets V1.45">
-<link rel="home" href="index.html" title="OpenACS Documentation">
-<link rel="up" href="dev-guide.html" title="Chapter 4. OpenACS Developer's Guide">
-<link rel="previous" href="dev-guide.html" title="Chapter 4. OpenACS Developer's Guide">
-<link rel="next" href="objects.html" title="OpenACS 4.5 Data Models and the Object System">
-<link rel="stylesheet" href="openacs.css" type="text/css">
-</head>
-<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-<div class="navheader">
-<a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr>
-<td width="20%" align="left">
-<a accesskey="p" href="dev-guide.html">Prev</a> </td>
-<th width="60%" align="center">Chapter 4. OpenACS Developer's Guide</th>
-<td width="20%" align="right"> <a accesskey="n" href="objects.html">Next</a>
-</td>
-</tr></table>
-<hr>
-</div>
-<div class="sect1">
-<div class="titlepage"><div><h2 class="title" style="clear: both">
-<a name="developers-overview"></a>Overview</h2></div></div>
-<p>A tour of what you need to know in order to extend OpenACS.</p>
-</div>
-<div class="navfooter">
-<hr>
-<table width="100%" summary="Navigation footer">
-<tr>
-<td width="40%" align="left">
-<a accesskey="p" href="dev-guide.html">Prev</a> </td>
-<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
-<td width="40%" align="right"> <a accesskey="n" href="objects.html">Next</a>
-</td>
-</tr>
-<tr>
-<td width="40%" align="left">Chapter 4. OpenACS Developer's Guide </td>
-<td width="20%" align="center"><a accesskey="u" href="dev-guide.html">Up</a></td>
-<td width="40%" align="right"> OpenACS 4.5 Data Models and the Object System</td>
-</tr>
-</table>
-<hr>
-<address>
- rmello at fslc.usu.edu
- </address>
-<address><a href="mailto:vinod@kurup.com">
+<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"><title>Overview</title><meta name="generator" content="DocBook XSL Stylesheets V1.50.0"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="dev-guide.html" title="Chapter 4. OpenACS Developer's Guide"><link rel="previous" href="dev-guide.html" title="Chapter 4. OpenACS Developer's Guide"><link rel="next" href="objects.html" title="OpenACS 4.5 Data Models and the Object System"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="dev-guide.html">Prev</a> </td><th width="60%" align="center">Chapter 4. OpenACS Developer's Guide</th><td width="20%" align="right"> <a accesskey="n" href="objects.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="developers-overview"></a>Overview</h2></div></div><p>A tour of what you need to know in order to extend OpenACS.</p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="dev-guide.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="objects.html">Next</a></td></tr><tr><td width="40%" align="left">Chapter 4. OpenACS Developer's Guide </td><td width="20%" align="center"><a accesskey="u" href="dev-guide.html">Up</a></td><td width="40%" align="right"> OpenACS 4.5 Data Models and the Object System</td></tr></table><hr><address>rmello at fslc.usu.edu</address><address><a href="mailto:vinod@kurup.com">
vinod@kurup.com
- </a></address>
-</div>
-</body>
-</html>
+ </a></address></div></body></html>
Index: openacs-4/packages/acs-core-docs/www/docbook-primer.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/docbook-primer.html,v
diff -u -r1.7 -r1.7.2.1
--- openacs-4/packages/acs-core-docs/www/docbook-primer.html 7 Mar 2002 06:55:36 -0000 1.7
+++ openacs-4/packages/acs-core-docs/www/docbook-primer.html 15 May 2002 23:26:18 -0000 1.7.2.1
@@ -1,85 +1,42 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type">
-<title>OpenACS Documentation Guide</title>
-<meta name="generator" content="DocBook XSL Stylesheets V1.45">
-<link rel="home" href="index.html" title="OpenACS Documentation">
-<link rel="up" href="eng-standards.html" title="Chapter 6. Engineering Standards">
-<link rel="previous" href="eng-standards.html" title="Chapter 6. Engineering Standards">
-<link rel="next" href="psgml-mode.html" title="Using PSGML mode in Emacs">
-<link rel="stylesheet" href="openacs.css" type="text/css">
-</head>
-<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-<div class="navheader">
-<a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr>
-<td width="20%" align="left">
-<a accesskey="p" href="eng-standards.html">Prev</a> </td>
-<th width="60%" align="center">Chapter 6. Engineering Standards</th>
-<td width="20%" align="right"> <a accesskey="n" href="psgml-mode.html">Next</a>
-</td>
-</tr></table>
-<hr>
-</div>
-<div class="sect1">
-<div class="titlepage"><div><h2 class="title" style="clear: both">
-<a name="docbook-primer"></a>OpenACS Documentation Guide</h2></div></div>
-<p>
+<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"><title>OpenACS Documentation Guide</title><meta name="generator" content="DocBook XSL Stylesheets V1.50.0"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="eng-standards.html" title="Chapter 6. Engineering Standards"><link rel="previous" href="eng-standards.html" title="Chapter 6. Engineering Standards"><link rel="next" href="psgml-mode.html" title="Using PSGML mode in Emacs"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="eng-standards.html">Prev</a> </td><th width="60%" align="center">Chapter 6. Engineering Standards</th><td width="20%" align="right"> <a accesskey="n" href="psgml-mode.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="docbook-primer"></a>OpenACS Documentation Guide</h2></div></div><p>
By <a href="mailto:claus@arsdigita.com" target="_top">claus@arsdigita.com</a>, with
additions by <a href="mailto:rmello@fslc.usu.edu" target="_top">Roberto
Mello</a> and the OpenACS Community
- </p>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="dbprimer-overview"></a>Overview of OpenACS 4.5 Documentation</h3></div></div>
-<p>
+ </p><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="dbprimer-overview"></a>Overview of OpenACS 4.5 Documentation</h3></div></div><p>
ArsDigita created a good documentation ground for us to build
upon. Some sections of the documentation however, lack details
and examples, others simply are inexistent.Our goal is to give
OpenACS a superb documentation, so that users, developers and
administrators of OpenACS installations can enjoy the system.
- </p>
-<p>
+ </p><p>
OpenACS™ is a powerful system, with
incredible possibilities and applications, but with this power
comes some complexity and a learning curve that will only be
atenuated by good documentation. This is what we are after.
- </p>
-<p>
+ </p><p>
The documentation for OpenACS™ is
written using DocBook XML. The reasons why we are using
DocBook are explained in more details in the
<a href="docbook-primer.html#dbprimer-why">Why DocBook?</a> section. I will add the reasons why
we are using Docbook XML instead of Docbook SGML:
- </p>
-<div class="itemizedlist"><ul>
-<li>
-<span class="emphasis"><i>Consistency</i></span>. We already have a bunch of
+ </p><div class="itemizedlist"><ul type="disc"><li><span class="emphasis"><em>Consistency</em></span>. We already have a bunch of
.xml files that ArsDigita wrote. Trying to re-write them to
conform to the SGML DTD would be unnecessary work (I tried).
- </li>
-<li>
-<span class="emphasis"><i>It does not require extra
- effort</i></span>. Writing in XML is almost identical to
+ </li><li><span class="emphasis"><em>It does not require extra
+ effort</em></span>. Writing in XML is almost identical to
SGML, with a couple extra rules. More details in the
<a href="http://www.linuxdoc.org/LDP/LDP-Author-Guide/docbookxml.html" target="_top">LDP
Author Guide</a>.
- </li>
-</ul></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="dbprimer-why"></a>Why DocBook?</h3></div></div>
-<p>
+ </li></ul></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="dbprimer-why"></a>Why DocBook?</h3></div></div><p>
In order to separate content and presentation, all OpenACS documentation will be marked up to conform to the
<a href="http://docbook.org/xml/index.html" target="_top">DocBook XML DTD</a>
- <a class="indexterm" name="id5388321"></a>
+ <a class="indexterm" name="id5430366"></a>
This enables us to publish in a variety
of formats and relieves each contributor of the burden of presentation, freeing him to focus
on content and sharing knowledge.
- </p>
-<p>
+ </p><p>
Theoretically any strict DTD would have been sufficient - we could even write our own. But DocBook has been around
for a while (since <a href="http://docbook.org/tdg/html/ch01.html#AEN971" target="_top">early 90's</a>),
it's well-tested, it's complete, it's extremely well-suited for technical documents
@@ -88,200 +45,137 @@
and a number of free and commercial
<a href="http://www.oasis-open.org/docbook/tools/index.html" target="_top">tools</a> are available
for editing and publishing DocBook documents.
- </p>
-<p>
+ </p><p>
This primer walks you through the basics, and should cover the
needs for 95 percent of the documentation we produce. However,
you're always welcome to check out DocBook's
<a href="http://docbook.org/tdg/html/refelem.html" target="_top">
list of elements</a> and use more exotic features in your
documents. The list is made up of SGML-elements but basically
- the same elements are valid in the XML DTD <span class="strong"><i>as long as you remember to</i></span>:
- <a class="indexterm" name="id5388544"></a>
- </p>
-<div class="itemizedlist"><ul>
-<li><p>
+ the same elements are valid in the XML DTD <span class="strong"><em>as long as you remember to</em></span>:
+ <a class="indexterm" name="id5430588"></a>
+ </p><div class="itemizedlist"><ul type="disc"><li><p>
Always close your tags with corresponding end-tags and to
- <span class="strong"><i>not use other tag minimization</i></span>
- </p></li>
-<li><p>
+ <span class="strong"><em>not use other tag minimization</em></span>
+ </p></li><li><p>
Write all elements and attributes in lowercase
- </p></li>
-<li><p>
+ </p></li><li><p>
Quote all attributes
- </p></li>
-</ul></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="dbprimer-validation"></a>Tools</h3></div></div>
-<p>
+ </p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="dbprimer-validation"></a>Tools</h3></div></div><p>
You are going to need the following to work with the OpenACS
Docbook XML documentation:
- </p>
-<div class="itemizedlist"><ul>
-<li>
-<a href="http://docbook.org/xml/index.html" target="_top">Docbook XML
+ </p><div class="itemizedlist"><ul type="disc"><li><a href="http://docbook.org/xml/index.html" target="_top">Docbook XML
DTD</a> - The document type definition for XML. You can
find an RPM or DEB package or you can download a zip file from
the site linked from here.
- </li>
-<li>
-<a href="http://sourceforge.net/projects/docbook/" target="_top">XSL
+ </li><li><a href="http://sourceforge.net/projects/docbook/" target="_top">XSL
Stylesheets</a> (docbook-xsl) - The stylesheets to convert
to HTML. We have been using a stylesheet based upon
NWalsh's chunk.xsl.
- </li>
-<li>
-<tt>xsltproc</tt> - The processor that
+ </li><li><tt>xsltproc</tt> - The processor that
will take an XML document and, given a xsl stylesheet, convert
it to HTML. It needs libxml2 and libxslt (available in RPM and
DEB formats or from <a href="http://xmlsoft.org/" target="_top">xmlsoft.org</a>.
- </li>
-<li>
+ </li><li>
Some editing tool. A popular one is Emacs with the psgml
mode. We have a <a href="psgml-mode.html" title="Using PSGML mode in Emacs">intro to the PSGML
Mode in Emacs</a> as part of our documentation. You can
read about other editing tools in the <a href="http://www.linuxdoc.org/LDP/LDP-Author-Guide/" target="_top">LDP Author Guide</a>.
- </li>
-</ul></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="dbprimer-new-doc"></a>Writing New Docs</h3></div></div>
-<p>
+ </li></ul></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="dbprimer-new-doc"></a>Writing New Docs</h3></div></div><p>
After you have the tools mentioned above, you need to define a
title for your document. Then start thinking about the possible
sections and subsections you will have in your document. Make
sure you coordinate with the OpenACS Gatekeepers to make sure
you're not writing something that someone else is already
writing. Also, if you desire to use the OpenACS CVS repository,
please e-mail the gatekeeper in charge of documentation.
- </p>
-<p>
+ </p><p>
You can look at some templates for documents (in Docbook XML) in
- the <a href="http://openacs.org/sdm/package-repository.tcl?current_entry=DIRECTORY%20%2fopenacs%2d4%2fpackages%2facs%2dcore%2ddocs%2fwww%20xml&package_id=9" target="_top">sources
- for acs-core-docs</a>, especially the <span class="emphasis"><i>
- Detailed Design Documentation Template</i></span> and the
- <span class="emphasis"><i>System/Application Requirements Template</i></span>.
- </p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="dbprimer-structure"></a>Document Structure</h3></div></div>
-<p>
+ the <a href="http://openacs.org/sdm/package-repository.tcl?current_entry=DIRECTORY%20%2fopenacs%2d4%2fpackages%2facs%2dcore%2ddocs%2fwww%20xml%26amp;package_id=9" target="_top">sources
+ for acs-core-docs</a>, especially the <span class="emphasis"><em>
+ Detailed Design Documentation Template</em></span> and the
+ <span class="emphasis"><em>System/Application Requirements Template</em></span>.
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="dbprimer-structure"></a>Document Structure</h3></div></div><p>
The documentation for each package will make up a little "book" that is structured like this
- - examples are <span class="emphasis"><i>emphasized</i></span>:
+ - examples are <span class="emphasis"><em>emphasized</em></span>:
- <a class="indexterm" name="id5388766"></a>
+ <a class="indexterm" name="id5430808"></a>
- </p>
-<pre class="programlisting">
- book : <span class="strong"><i>Docs for one package</i></span> - <span class="emphasis"><i>templating</i></span>
+ </p><pre class="programlisting">
+ book : <span class="strong"><em>Docs for one package</em></span> - <span class="emphasis"><em>templating</em></span>
|
- +--chapter : <span class="strong"><i>One section</i></span> - <span class="emphasis"><i>for developers</i></span>
+ +--chapter : <span class="strong"><em>One section</em></span> - <span class="emphasis"><em>for developers</em></span>
|
---------+------------------------------------------------------
|
- +--sect1 : <span class="strong"><i>Single document</i></span> - <span class="emphasis"><i>requirements</i></span>
+ +--sect1 : <span class="strong"><em>Single document</em></span> - <span class="emphasis"><em>requirements</em></span>
|
- +--sect2 : <span class="strong"><i>Sections</i></span> - <span class="emphasis"><i>functional requirements</i></span>
+ +--sect2 : <span class="strong"><em>Sections</em></span> - <span class="emphasis"><em>functional requirements</em></span>
|
- +--sect3 : <span class="strong"><i>Subsections</i></span> - <span class="emphasis"><i>Programmer's API</i></span>
+ +--sect3 : <span class="strong"><em>Subsections</em></span> - <span class="emphasis"><em>Programmer's API</em></span>
|
- ... : <span class="strong"><i>...</i></span>
- </pre>
-<p>
+ ... : <span class="strong"><em>...</em></span>
+ </pre><p>
The actual content is split up into documents that start at a
<tt>sect1</tt>-level. These are then tied together in a top-level document that
contains all the information above the line. This will be explained in more detail in a later document,
- and we will provide a set of templates for documenting an entire package. </p>
-<p>For now you can take a look at the
- <a href="http://openacs.org/sdm/package-repository.tcl?current_entry=DIRECTORY%20%2fopenacs%2d4%2fpackages%2facs%2dcore%2ddocs%2fwww%20xml&package_id=9" target="_top">sources of these DocBook documents</a>
+ and we will provide a set of templates for documenting an entire package. </p><p>For now you can take a look at the
+ <a href="http://openacs.org/sdm/package-repository.tcl?current_entry=DIRECTORY%20%2fopenacs%2d4%2fpackages%2facs%2dcore%2ddocs%2fwww%20xml%26amp;package_id=9" target="_top">sources of these DocBook documents</a>
to get an idea of how they are tied together.
- </p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="dbprimer-sections"></a>Headlines, Sections</h3></div></div>
-<p>
- <a class="indexterm" name="id5388901"></a>
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="dbprimer-sections"></a>Headlines, Sections</h3></div></div><p>
+ <a class="indexterm" name="id5430943"></a>
Given that your job starts at the <tt>sect1</tt>-level, all your documents should open with a
<a href="http://docbook.org/tdg/html/sect1.html" target="_top"><tt><sect1></tt></a>-tag and end
with the corresponding <tt></sect1></tt>.
- </p>
-<p>
- <a class="indexterm" name="id5388944"></a>
+ </p><p>
+ <a class="indexterm" name="id5430986"></a>
You need to feed every <tt><sect1></tt> two attributes. The first attribute,
<tt>id</tt>, is standard and can be used with all elements. It comes in very
handy when interlinking between documents (more about this when talking about links in <a href="docbook-primer.html#dbprimer-links" title="Links">the section called “Links”</a>).
The value of <tt>id</tt> has to be unique
throughout the book you're making since the <tt>id</tt>'s in your
<tt>sect1</tt>'s will turn into filenames when the book is parsed into HTML.
- </p>
-<p>
- <a class="indexterm" name="id5389006"></a>
+ </p><p>
+ <a class="indexterm" name="id5431049"></a>
The other attribute is <tt>xreflabel</tt>. The value of this is the text that will appear
as the link when referring to this <tt>sect1</tt>.
- </p>
-<p>
+ </p><p>
Right after the opening tag you put the title of the document - this is usually the same as
<tt>xreflabel</tt>-attribute. E.g. the top level of the document you're
reading right now looks like this:
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
<sect1 id="docbook-primer" xreflabel="aD DocBook Primer">
<title>aD DocBook Primer</title>
...
</sect1>
- </pre>
-<p>
- <a class="indexterm" name="id5389059"></a>
+ </pre><p>
+ <a class="indexterm" name="id5431102"></a>
Inside this container your document will be split up into
<a href="http://docbook.org/tdg/html/sect2.html" target="_top"><tt><sect2></tt></a>'s,
each with the same requirements - <tt>id</tt> and <tt>xreflabel</tt>
attributes, and a <tt><title></tt>-tag inside. Actually, the <tt>xreflabel</tt> is never required in sections, but it makes linking to that section a lot easier.
- </p>
-<p>
+ </p><p>
When it comes to naming your
<tt>sect2</tt>'s and below, prefix them with some abbreviation of the <tt>id</tt> in the <tt>sect1</tt> such as <tt>requirements-overview</tt>.
- </p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="dbprimer-code"></a>Code</h3></div></div>
-<p>
- <a class="indexterm" name="id5389163"></a>
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="dbprimer-code"></a>Code</h3></div></div><p>
+ <a class="indexterm" name="id5431205"></a>
For displaying a snippet of code, a filename or anything else you just want to appear as a part of
a sentence, we will use the tag
<a href="http://docbook.org/tdg/html/computeroutput.html" target="_top"><tt><computeroutput></tt></a>.
This takes the place of the HTML-tag <tt><code></tt>
- </p>
-<p>
+ </p><p>
For bigger chunks of code such as SQL-blocks, the tag
<a href="http://docbook.org/tdg/html/programlisting.html" target="_top"><tt><programlisting></tt></a> is used. Just wrap your code block in it; mono-spacing, indents and all that stuff is taken care of
automatically.
- </p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="dbprimer-links"></a>Links</h3></div></div>
-<p>
- <a class="indexterm" name="id5389234"></a>
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="dbprimer-links"></a>Links</h3></div></div><p>
+ <a class="indexterm" name="id5431276"></a>
Linking falls into two different categories: inside the book you're making and outside:
- </p>
-<div class="variablelist"><dl>
-<dt><span class="term"><span class="strong"><i>1. Inside linking, cross-referencing other parts of your book</i></span></span></dt>
-<dd>
-<p>
+ </p><div class="variablelist"><dl><dt><span class="term"><span class="strong"><em>1. Inside linking, cross-referencing other parts of your book</em></span></span></dt><dd><p>
By having unique <tt>id</tt>'s you can cross-reference any part of your book
with a simple tag, regardless of where that part is.
- </p>
-<p>
-<a class="indexterm" name="id5389278"></a>Check out how I link to a subsection of the Developer's Guide:</p>
-<pre class="programlisting">
+ </p><p><a class="indexterm" name="id5431320"></a>Check out how I link to a subsection of the Developer's Guide:</p><pre class="programlisting">
Put this in your XML:
@@ -294,21 +188,14 @@
- Find information about creating a package in
<a href="packages.html#packages-making-a-package">Making a Package</a>
- </pre>
-<p>
+ </pre><p>
Note that even though this is an empty tag, you have to either:
- </p>
-<div class="orderedlist"><ol type="1">
-<li><p>
+ </p><div class="orderedlist"><ol type="1"><li><p>
Provide the end-tag, <tt></xref></tt>, or
- </p></li>
-<li><p>
+ </p></li><li><p>
Put a slash before the ending-bracket: <tt><xref linkend="blahblah"/></tt>
- </p></li>
-</ol></div>
-<p>If the section you link to hasn't a specified <tt>xreflabel</tt>-attribute,
- the link is going to look like this:</p>
-<pre class="programlisting">
+ </p></li></ol></div><p>If the section you link to hasn't a specified <tt>xreflabel</tt>-attribute,
+ the link is going to look like this:</p><pre class="programlisting">
Put this in your XML:
@@ -321,51 +208,33 @@
- Find information about what a package looks like in
<a href="packages.html#packages-looks" title="What a Package Looks Like">the section called “What a Package Looks Like”</a>
- </pre>
-<p>
+ </pre><p>
Note that since I haven't provided an <tt>xreflabel</tt> for the subsection,
<tt>packages-looks</tt>, the
parser will try its best to explain where the link takes you.
- </p>
-</dd>
-<dt><span class="term"><span class="strong"><i>2. Linking outside the documentation</i></span></span></dt>
-<dd>
-<p>
- <a class="indexterm" name="id5389430"></a>
+ </p></dd><dt><span class="term"><span class="strong"><em>2. Linking outside the documentation</em></span></span></dt><dd><p>
+ <a class="indexterm" name="id5431472"></a>
If you're hyper-linking out of the documentation, it works almost the same way as HTML - the tag is just
a little different
(<a href="http://docbook.org/tdg/html/ulink.html" target="_top"><tt><ulink></tt></a>):
- </p>
-<pre class="programlisting"><ulink url="http://www.oracle.com/">Oracle Corporation</ulink></pre>
-<p>
+ </p><pre class="programlisting"><ulink url="http://www.oracle.com/">Oracle Corporation</ulink></pre><p>
....will create a hyper-link to Oracle in the HTML-version of the documentation.
- </p>
-<p>
-<span class="strong"><i>NOTE:</i></span> Do NOT use ampersands in your hyper links. These are reserved for referencing
+ </p><p><span class="strong"><em>NOTE:</em></span> Do NOT use ampersands in your hyper links. These are reserved for referencing
entities, which is exactly how you'll make an ampersand: <tt>&amp;</tt>
- </p>
-</dd>
-</dl></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="dbprimer-graphics"></a>Graphics</h3></div></div>
-<p>
- <span class="emphasis"><i><span class="strong"><i>NOTE:</i></span> Currently this section currently only takes HTML-output into consideration -
- not a printed version</i></span>
- </p>
-<p>
- <span class="emphasis"><i>
- <span class="strong"><i>Another Note:</i></span> Also, it's still not a 100 percent sure that this is how we are going to
+ </p></dd></dl></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="dbprimer-graphics"></a>Graphics</h3></div></div><p>
+ <span class="emphasis"><em><span class="strong"><em>NOTE:</em></span> Currently this section currently only takes HTML-output into consideration -
+ not a printed version</em></span>
+ </p><p>
+ <span class="emphasis"><em>
+ <span class="strong"><em>Another Note:</em></span> Also, it's still not a 100 percent sure that this is how we are going to
do it, so if you want to start converting your documents right away, start out with the ones without graphics ;)
- </i></span>
- </p>
-<p>
- <a class="indexterm" name="id5389538"></a>
+ </em></span>
+ </p><p>
+ <a class="indexterm" name="id5431580"></a>
To insert a graphic we use the elements
<a href="http://docbook.org/tdg/html/mediaobject.html" target="_top"><tt><mediaobject></tt></a>,
<a href="http://docbook.org/tdg/html/imageobject.html" target="_top"><tt><imageobject></tt></a>,
@@ -375,8 +244,7 @@
and one for print (EPS). Finally you should provide a brief description wrapped in
<a href="http://docbook.org/tdg/html/textobject.html" target="_top"><tt><textobject></tt></a> -
in HTML this will be the ALT text.
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
<mediaobject>
<imageobject>
<imagedata fileref="../images/rp-flow.gif" format="GIF" align="center"/>
@@ -388,62 +256,41 @@
<phrase>This is an image of the flow in the Request Processor</phrase>
</textobject>
</mediaobject>
- </pre>
-<p>
+ </pre><p>
Put your graphics in a separate directory ("images") and link to them
only with relative paths.
- </p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="dbprimer-lists"></a>Lists</h3></div></div>
-<p>
- <a class="indexterm" name="id5389641"></a>
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="dbprimer-lists"></a>Lists</h3></div></div><p>
+ <a class="indexterm" name="id5431683"></a>
Here's how you make the DocBook equivalent of the three usual HTML-lists:
- </p>
-<div class="variablelist"><dl>
-<dt><span class="term"><span class="strong"><i>1. How to make an <ul></i></span></span></dt>
-<dd>
-<p>
+ </p><div class="variablelist"><dl><dt><span class="term"><span class="strong"><em>1. How to make an <ul></em></span></span></dt><dd><p>
Making an unordered list is pretty much like doing the same thing in HTML - if you close your <tt><li></tt>, that is. The only differences are that each list item has to be wrapped in something more, such as
<tt><para></tt>, and that the tags are called
<a href="http://docbook.org/tdg/html/itemizedlist.html" target="_top"><tt><itemizedlist></tt></a>
and
<a href="http://docbook.org/tdg/html/listitem.html" target="_top"><tt><listitem></tt></a>:
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
<itemizedlist>
<listitem><para>Stuff goes here</para><listitem>
<listitem><para>More stuff goes here</para><listitem>
</itemizedlist>
- </pre>
-</dd>
-<dt><span class="term"><span class="strong"><i>2. How to make an <ol></i></span></span></dt>
-<dd>
-<p>
+ </pre></dd><dt><span class="term"><span class="strong"><em>2. How to make an <ol></em></span></span></dt><dd><p>
The ordered list is like the preceding, except that you use
- <a href="http://docbook.org/tdg/html/orderedlist.html" target="_top"><tt><orderedlist></tt></a> instead:</p>
-<pre class="programlisting">
+ <a href="http://docbook.org/tdg/html/orderedlist.html" target="_top"><tt><orderedlist></tt></a> instead:</p><pre class="programlisting">
<orderedlist>
<listitem><para>Stuff goes here</para><listitem>
<listitem><para>More stuff goes here</para><listitem>
</orderedlist>
- </pre>
-</dd>
-<dt><span class="term"><span class="strong"><i>3. How to make a <dl></i></span></span></dt>
-<dd>
-<p>
+ </pre></dd><dt><span class="term"><span class="strong"><em>3. How to make a <dl></em></span></span></dt><dd><p>
This kind of list is called a <tt>variablelist</tt> and these are the tags you'll need to
make it happen:
<a href="http://docbook.org/tdg/html/variablelist.html" target="_top"><tt><variablelist></tt></a>,
<a href="http://docbook.org/tdg/html/varlistentry.html" target="_top"><tt><varlistentry></tt></a>,
<a href="http://docbook.org/tdg/html/term.html" target="_top"><tt><term></tt></a> and
- <a href="http://docbook.org/tdg/html/listitem.html" target="_top"><tt><listitem></tt></a>:</p>
-<pre class="programlisting">
+ <a href="http://docbook.org/tdg/html/listitem.html" target="_top"><tt><listitem></tt></a>:</p><pre class="programlisting">
<variablelist>
<varlistentry>
@@ -457,20 +304,12 @@
</varlistentry>
</variablelist>
- </pre>
-</dd>
-</dl></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="dbprimer-tables"></a>Tables</h3></div></div>
-<p>
- <a class="indexterm" name="id5389879"></a>
+ </pre></dd></dl></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="dbprimer-tables"></a>Tables</h3></div></div><p>
+ <a class="indexterm" name="id5431921"></a>
DocBook supports several types of tables, but in most cases, the
<a href="http://docbook.org/tdg/html/informaltable.html" target="_top"><tt><informaltable></tt></a>
is enough:
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
<informaltable frame="all">
<tgroup cols="3">
<tbody>
@@ -496,218 +335,90 @@
</tbody>
</tgroup>
</informaltable>
- </pre>
-<p>
+ </pre><p>
With our current XSL-style-sheet, the output of the markup above will be a simple HTML-table:
- </p>
-<blockquote class="blockquote"><div class="informaltable"><table border="1">
-<colgroup>
-<col>
-<col>
-<col>
-</colgroup>
-<tbody>
-<tr>
-<td>a1</td>
-<td>b1</td>
-<td>c1</td>
-</tr>
-<tr>
-<td>a2</td>
-<td>b2</td>
-<td>c2</td>
-</tr>
-<tr>
-<td>a3</td>
-<td>b3</td>
-<td>c3</td>
-</tr>
-</tbody>
-</table></div></blockquote>
-<p>
+ </p><blockquote class="blockquote"><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><tbody><tr><td>a1</td><td>b1</td><td>c1</td></tr><tr><td>a2</td><td>b2</td><td>c2</td></tr><tr><td>a3</td><td>b3</td><td>c3</td></tr></tbody></table></div></blockquote><p>
If you want cells to span more than one row or column, it gets a bit more complicated - check out
<a href="http://docbook.org/tdg/html/table.html" target="_top"><tt><table></tt></a>
for an example.
- </p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="dbprimer-emphasis"></a>Emphasis</h3></div></div>
-<p>
- <a class="indexterm" name="id5390033"></a>
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="dbprimer-emphasis"></a>Emphasis</h3></div></div><p>
+ <a class="indexterm" name="id5432076"></a>
Our documentation uses two flavors of emphasis - italics and bold type. DocBook uses one -
<a href="http://docbook.org/tdg/html/emphasis.html" target="_top"><tt><emphasis></tt></a>.
- </p>
-<p>
+ </p><p>
The <tt><emphasis></tt> tag defaults to italics when parsed. If you're looking for
emphasizing with bold type, use <tt><emphasis role="strong"></tt>.
- </p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="dbprimer-indexing"></a>Indexing Your DocBook Documents</h3></div></div>
-<p>
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="dbprimer-indexing"></a>Indexing Your DocBook Documents</h3></div></div><p>
Marking up index-words may not have any importance for the HTML-output, but in order to make it easier to make
a nice print-version of the documentation, you should mark up words in your documents that you would like to
see show up in an index one day.
- </p>
-<p>
+ </p><p>
Use
<a href="http://docbook.org/tdg/html/indexterm.html" target="_top"><tt><indexterm></tt></a>,
<a href="http://docbook.org/tdg/html/primary.html" target="_top"><tt><primary></tt></a> and
<a href="http://docbook.org/tdg/html/secondary.html" target="_top"><tt><secondary></tt></a>
for this. See these links for an explanation.
- </p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="dbprimer-converting"></a>Converting to HTML</h3></div></div>
-<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
-<h3 class="title">Note</h3>
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="dbprimer-converting"></a>Converting to HTML</h3></div></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
This section is quoted almost verbatim from the LDP Author Guide.
- </div>
-<p>
+ </div><p>
Once you have the <a href="docbook-primer.html#dbprimer-validation">Docbook Tools</a>
installed, you can convert your xml documents to HTML (or other
formats. Let me know if you are able to convert to other
formats).
- </p>
-<p>
+ </p><p>
With the DocBook XSL stylesheets, generation of multiple files
is controlled by the stylesheet. If you want to generate a
single file, you call one stylesheet. If you want to generate
multiple files, you call a different stylesheet.
- </p>
-<p>
+ </p><p>
To generate a single HTML file from your DocBook XML file,
use the command:
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
bash$ xsltproc -o outputfilename.xml /usr/share/sgml/docbook/stylesheet/xsl/nwalsh/html/html.xsl filename.xml
- </pre>
-<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
-<h3 class="title">Note</h3>
- This example uses Daniel Veillard's <span class="strong"><i>xsltproc</i></span> command available
+ </pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
+ This example uses Daniel Veillard's <span class="strong"><em>xsltproc</em></span> command available
as part of libxslt from <a href="http://www.xmlsoft.org/XSLT/" target="_top">http://www.xmlsoft.org/XSLT/</a>.
If you are using other XML processors such as Xalan or Saxon,
you will need to change the command line appropriately.
- </div>
-<p>
+ </div><p>
To generate a set of linked HTML pages, with a separate page
for each <chapter>, <sect1> or <appendix> tag, use the
following command:
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
bash$ xsltproc /usr/share/sgml/docbook/stylesheet/xsl/nwalsh/html/chunk.xsl filename.xml
- </pre>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="db-primer-further-reading"></a>Further Reading</h3></div></div>
-<div class="itemizedlist"><ul>
-<li>
+ </pre></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="db-primer-further-reading"></a>Further Reading</h3></div></div><div class="itemizedlist"><ul type="disc"><li>
The <a href="http://www.linuxdoc.org/LDP/LDP-Author-Guide/" target="_top">LDP Author
Guide</a> has a lot of good information, a table of
docbook elements and their "look" in HTML and lots of good links
for tools.
- </li>
-<li><p>
+ </li><li><p>
<a href="mailto:lutter@arsdigita.com" target="_top">David
Lutterkort</a>
wrote an <a href="psgml-mode.html" title="Using PSGML mode in Emacs">intro to the PSGML Mode in Emacs</a>
- </p></li>
-<li><p>
+ </p></li><li><p>
For checking if your document is well-formed, James Clark's free Java parser,
<a href="http://www.jclark.com/xml/xp/index.html" target="_top">XP</a>, is recommended. (note that
it is not a validating parser, but as long as you follow the guidelines set forth in this
- document, your XML will validate)</p></li>
-<li><p>
+ document, your XML will validate)</p></li><li><p>
<a href="http://sources.redhat.com/docbook-tools/" target="_top">DocBook Tool for Linux</a>:
Let's you convert your docbook documents to a number of formats. Sometimes it's nice to see
- how you stuff looks. <span class="emphasis"><i>NOTE: I only got these to
+ how you stuff looks. <span class="emphasis"><em>NOTE: I only got these to
work with Docbook SGML, NOT with Docbook XML. If you are
- able to make it work with our XML, please let us know.</i></span>
- </p></li>
-<li><p>
+ able to make it work with our XML, please let us know.</em></span>
+ </p></li><li><p>
AptConvert from <a href="http://www.pixware.fr/" target="_top">PIXware</a> is a Java editor that will produce
DocBook documents and let you transform them into HTML and PDF for a local preview before you submit.
- </p></li>
-<li><p>
+ </p></li><li><p>
In the process of transforming your HTML into XML,
<a href="http://www.w3.org/People/Raggett/tidy/" target="_top">HTML tidy</a>
can be a a handy tool to make your HTML "regexp'able".
<a href="mailto:bcalef@arsdigita.com" target="_top">Brandoch Calef</a> has made a
<a href="http://developer.arsdigita.com/working-papers/bcalef/html-to-docbook.html#html2docbook" target="_top">Perl script</a>
that gets you most of the way.
- </p></li>
-</ul></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="dbprimer-rev-history"></a>Revision History</h3></div></div>
-<div class="informaltable"><table border="1">
-<colgroup>
-<col>
-<col>
-<col>
-<col>
-</colgroup>
-<thead><tr>
-<th>Document Revision #</th>
-<th>Action Taken, Notes</th>
-<th>When?</th>
-<th>By Whom?</th>
-</tr></thead>
-<tbody>
-<tr>
-<td>0.3</td>
-<td>
+ </p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="dbprimer-rev-history"></a>Revision History</h3></div></div><div class="informaltable"><table border="1"><colgroup><col><col><col><col></colgroup><thead><tr><th>Document Revision #</th><th>Action Taken, Notes</th><th>When?</th><th>By Whom?</th></tr></thead><tbody><tr><td>0.3</td><td>
Added OpenACS information, updated tools, added
extra links and added info to the Publishing section.
- </td>
-<td>12/24/2001</td>
-<td>Roberto Mello</td>
-</tr>
-<tr>
-<td>0.2</td>
-<td>Changed recommendation from <phrase> to <emphasis role="strong"></td>
-<td>01/19/2000</td>
-<td>Claus Rasmussen</td>
-</tr>
-<tr>
-<td>0.1</td>
-<td>Creation</td>
-<td>12/2000</td>
-<td>Claus Rasmussen</td>
-</tr>
-</tbody>
-</table></div>
-</div>
-</div>
-<div class="navfooter">
-<hr>
-<table width="100%" summary="Navigation footer">
-<tr>
-<td width="40%" align="left">
-<a accesskey="p" href="eng-standards.html">Prev</a> </td>
-<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
-<td width="40%" align="right"> <a accesskey="n" href="psgml-mode.html">Next</a>
-</td>
-</tr>
-<tr>
-<td width="40%" align="left">Chapter 6. Engineering Standards </td>
-<td width="20%" align="center"><a accesskey="u" href="eng-standards.html">Up</a></td>
-<td width="40%" align="right"> Using PSGML mode in Emacs</td>
-</tr>
-</table>
-<hr>
-<address>
- rmello at fslc.usu.edu
- </address>
-<address><a href="mailto:vinod@kurup.com">
+ </td><td>12/24/2001</td><td>Roberto Mello</td></tr><tr><td>0.2</td><td>Changed recommendation from <phrase> to <emphasis role="strong"></td><td>01/19/2000</td><td>Claus Rasmussen</td></tr><tr><td>0.1</td><td>Creation</td><td>12/2000</td><td>Claus Rasmussen</td></tr></tbody></table></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="eng-standards.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="psgml-mode.html">Next</a></td></tr><tr><td width="40%" align="left">Chapter 6. Engineering Standards </td><td width="20%" align="center"><a accesskey="u" href="eng-standards.html">Up</a></td><td width="40%" align="right"> Using PSGML mode in Emacs</td></tr></table><hr><address>rmello at fslc.usu.edu</address><address><a href="mailto:vinod@kurup.com">
vinod@kurup.com
- </a></address>
-</div>
-</body>
-</html>
+ </a></address></div></body></html>
Index: openacs-4/packages/acs-core-docs/www/eng-standards-constraint-naming.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/eng-standards-constraint-naming.html,v
diff -u -r1.7 -r1.7.2.1
--- openacs-4/packages/acs-core-docs/www/eng-standards-constraint-naming.html 7 Mar 2002 06:55:36 -0000 1.7
+++ openacs-4/packages/acs-core-docs/www/eng-standards-constraint-naming.html 15 May 2002 23:26:18 -0000 1.7.2.1
@@ -1,124 +1,34 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type">
-<title>Constraint naming standard</title>
-<meta name="generator" content="DocBook XSL Stylesheets V1.45">
-<link rel="home" href="index.html" title="OpenACS Documentation">
-<link rel="up" href="eng-standards.html" title="Chapter 6. Engineering Standards">
-<link rel="previous" href="eng-standards-versioning.html" title="Release Version Numbering">
-<link rel="next" href="eng-standards-filenaming.html" title="ACS File Naming and Formatting Standards">
-<link rel="stylesheet" href="openacs.css" type="text/css">
-</head>
-<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-<div class="navheader">
-<a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr>
-<td width="20%" align="left">
-<a accesskey="p" href="eng-standards-versioning.html">Prev</a> </td>
-<th width="60%" align="center">Chapter 6. Engineering Standards</th>
-<td width="20%" align="right"> <a accesskey="n" href="eng-standards-filenaming.html">Next</a>
-</td>
-</tr></table>
-<hr>
-</div>
-<div class="sect1">
-<div class="titlepage"><div><h2 class="title" style="clear: both">
-<a name="eng-standards-constraint-naming"></a>Constraint naming standard</h2></div></div>
-<div class="authorblurb"><p>By <a href="mailto:mbryzek@arsdigita.com" target="_top">mbryzek@arsdigita.com</a>
-</p></div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="eng-standards-constraint-naming-big-picture"></a>The Big Picture</h3></div></div>
-<p>
+<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"><title>Constraint naming standard</title><meta name="generator" content="DocBook XSL Stylesheets V1.50.0"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="eng-standards.html" title="Chapter 6. Engineering Standards"><link rel="previous" href="eng-standards-versioning.html" title="Release Version Numbering"><link rel="next" href="eng-standards-filenaming.html" title="ACS File Naming and Formatting Standards"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="eng-standards-versioning.html">Prev</a> </td><th width="60%" align="center">Chapter 6. Engineering Standards</th><td width="20%" align="right"> <a accesskey="n" href="eng-standards-filenaming.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="eng-standards-constraint-naming"></a>Constraint naming standard</h2></div></div><div class="authorblurb"><p><p>By <a href="mailto:mbryzek@arsdigita.com" target="_top">mbryzek@arsdigita.com</a></p><br>
+ OpenACS docs are written by the named authors, but may be edited
+ by OpenACS documentation staff.
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="eng-standards-constraint-naming-big-picture"></a>The Big Picture</h3></div></div><p>
Constraint naming standard is important for one reason: The SYS_* name oracle
assigns to unnamed constraints is not very understandable. By correctly
naming all contraints, we can quickly associate a particular constraint
with our data model. This gives us two real advantages:
-</p>
-<div class="itemizedlist"><ul>
-<li><p> We can quickly identify and fix any errors. </p></li>
-<li><p> We can reliabily modify or drop constraints </p></li>
-</ul></div>
-<p>
-<div>Why do we need a naming convention? </div>
+</p><div class="itemizedlist"><ul type="disc"><li><p> We can quickly identify and fix any errors. </p></li><li><p> We can reliabily modify or drop constraints </p></li></ul></div><p>
+</p><div>Why do we need a naming convention? </div><p>
<a href="http://oradoc.photo.net/ora8doc/DOC/server803/A54647_01/ch2.htm#2956" target="_top">Oracle limits names</a>,
in general, to 30 characters, which is hardly enough for a human readable constraint name.
-</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="eng-standards-constraint-naming-abbr"></a>Abbreviations</h3></div></div>
-<p>
+</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="eng-standards-constraint-naming-abbr"></a>Abbreviations</h3></div></div><p>
We propose the following naming convention for all constraints, with
the following abbreviations taken from Oracle Docs at
<a href="http://oradoc.photo.net/ora81/DOC/server.815/a67779/ch4e.htm#8953" target="_top">
http://oradoc.photo.net/ora81/DOC/server.815/a67779/ch4e.htm#8953</a>.
Note that we shortened all of the constraint abbrevations to
two characters to save room.
-</p>
-<div class="informaltable"><table border="1">
-<colgroup>
-<col>
-<col>
-</colgroup>
-<thead><tr>
-<th>Constraint type</th>
-<th>Abbreviation</th>
-</tr></thead>
-<tbody>
-<tr>
-<td>references (foreign key)</td>
-<td>fk</td>
-</tr>
-<tr>
-<td>unique</td>
-<td>un</td>
-</tr>
-<tr>
-<td>primary key</td>
-<td>pk</td>
-</tr>
-<tr>
-<td>check</td>
-<td>ck</td>
-</tr>
-<tr>
-<td>not null</td>
-<td>nn</td>
-</tr>
-</tbody>
-</table></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="eng-standards-constraint-naming-format"></a>Format of constraint name</h3></div></div>
-<p>
+</p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Constraint type</th><th>Abbreviation</th></tr></thead><tbody><tr><td>references (foreign key)</td><td>fk</td></tr><tr><td>unique</td><td>un</td></tr><tr><td>primary key</td><td>pk</td></tr><tr><td>check</td><td>ck</td></tr><tr><td>not null</td><td>nn</td></tr></tbody></table></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="eng-standards-constraint-naming-format"></a>Format of constraint name</h3></div></div><p>
<table name>_<column_name>_<constraint abbreviation>
-</p>
-<p>
+</p><p>
In reality, this won't be possible because of the character limitation on
names inside oracle. When the name is too long, we will follow these two
steps in order:
-</p>
-<div class="orderedlist"><ol type="1">
-<li><p> Abbreviate the table name with the table's initials (e.g. users -> u and users_contact -> uc).
-</p></li>
-<li><p> Truncate the column name until it fits.</p></li>
-</ol></div>
-<p>
+</p><div class="orderedlist"><ol type="1"><li><p> Abbreviate the table name with the table's initials (e.g. users -> u and users_contact -> uc).
+</p></li><li><p> Truncate the column name until it fits.</p></li></ol></div><p>
If the constraint name is still too long, you should consider rewriting your
entire data model :)
-</p>
-<p><span class="strong"><i>Notes:</i></span></p>
-<div class="itemizedlist"><ul>
-<li><p> If you have to abbreviate the table name for one of the constraints, abbreviate it for all the constraints</p></li>
-<li><p> If you are defining a multi column constraint, try to truncate the two column names evenly </p></li>
-</ul></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="eng-standards-constraint-naming-example"></a>Example</h3></div></div>
-<pre class="programlisting">
+</p><p><span class="strong"><em>Notes:</em></span></p><div class="itemizedlist"><ul type="disc"><li><p> If you have to abbreviate the table name for one of the constraints, abbreviate it for all the constraints</p></li><li><p> If you are defining a multi column constraint, try to truncate the two column names evenly </p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="eng-standards-constraint-naming-example"></a>Example</h3></div></div><pre class="programlisting">
create table example_topics (
topic_id integer
constraint example_topics_topic_id_pk
@@ -142,17 +52,11 @@
constraint cne_example_id_one_line_unq unique(example_id, one_line_description)
);
-</pre>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="eng-standards-constraint-naming-pk"></a>Why it's good to name primary keys</h3></div></div>
-<p>
+</pre></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="eng-standards-constraint-naming-pk"></a>Why it's good to name primary keys</h3></div></div><p>
Naming primary keys might not have any obvious advantages. However, here's an
example where naming the primary key really helps (and this is by no means
a rare case!
-</p>
-<pre class="programlisting">
+</p><pre class="programlisting">
SQL> set autotrace traceonly explain;
@@ -166,53 +70,18 @@
2 1 TABLE ACCESS (FULL) OF 'CONSTRAINT_NAMING_EXAMPLE'
3 1 INDEX (UNIQUE SCAN) OF 'EXAMPLE_TOPICS_TOPIC_ID_PK' (UNI
QUE)
-</pre>
-<p>
+</pre><p>
Isn't it nice to see "EXAMPLE_TOPICS_TOPIC_ID_PK" in the trace
and know exactly which table oracle is using at each step?
-</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="eng-standards-constraint-naming-nn"></a>Naming not null constraints is optional...</h3></div></div>
-<p>
+</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="eng-standards-constraint-naming-nn"></a>Naming not null constraints is optional...</h3></div></div><p>
ArsDigita is split on whether or not we should be naming not null constraints... So, if you want to name them, please do so and follow the above naming standard. But, naming not null constraints is not a requirement at ArsDigita.
-</p>
-<p>
-<div>About Naming the not null constraints</div>
-</p>
-<p>
+</p><p>
+</p><div>About Naming the not null constraints</div><p>
+</p><p>
Though naming "not null" constraints doesn't help immeditately in error
debugging (e.g. the error will say something like
"Cannot insert null value into column"), we recommend naming not null
constraints to be consistent in our naming of all constraints.
-</p>
-<p><div class="cvstag">($Id$)</div></p>
-</div>
-</div>
-<div class="navfooter">
-<hr>
-<table width="100%" summary="Navigation footer">
-<tr>
-<td width="40%" align="left">
-<a accesskey="p" href="eng-standards-versioning.html">Prev</a> </td>
-<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
-<td width="40%" align="right"> <a accesskey="n" href="eng-standards-filenaming.html">Next</a>
-</td>
-</tr>
-<tr>
-<td width="40%" align="left">Release Version Numbering </td>
-<td width="20%" align="center"><a accesskey="u" href="eng-standards.html">Up</a></td>
-<td width="40%" align="right"> ACS File Naming and Formatting Standards</td>
-</tr>
-</table>
-<hr>
-<address>
- rmello at fslc.usu.edu
- </address>
-<address><a href="mailto:vinod@kurup.com">
+</p><p><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="eng-standards-versioning.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="eng-standards-filenaming.html">Next</a></td></tr><tr><td width="40%" align="left">Release Version Numbering </td><td width="20%" align="center"><a accesskey="u" href="eng-standards.html">Up</a></td><td width="40%" align="right"> ACS File Naming and Formatting Standards</td></tr></table><hr><address>rmello at fslc.usu.edu</address><address><a href="mailto:vinod@kurup.com">
vinod@kurup.com
- </a></address>
-</div>
-</body>
-</html>
+ </a></address></div></body></html>
Index: openacs-4/packages/acs-core-docs/www/eng-standards-filenaming.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/eng-standards-filenaming.html,v
diff -u -r1.7 -r1.7.2.1
--- openacs-4/packages/acs-core-docs/www/eng-standards-filenaming.html 7 Mar 2002 06:55:36 -0000 1.7
+++ openacs-4/packages/acs-core-docs/www/eng-standards-filenaming.html 15 May 2002 23:26:18 -0000 1.7.2.1
@@ -1,161 +1,65 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type">
-<title>ACS File Naming and Formatting Standards</title>
-<meta name="generator" content="DocBook XSL Stylesheets V1.45">
-<link rel="home" href="index.html" title="OpenACS Documentation">
-<link rel="up" href="eng-standards.html" title="Chapter 6. Engineering Standards">
-<link rel="previous" href="eng-standards-constraint-naming.html" title="Constraint naming standard">
-<link rel="next" href="eng-standards-plsql.html" title="PL/SQL Standards">
-<link rel="stylesheet" href="openacs.css" type="text/css">
-</head>
-<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-<div class="navheader">
-<a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr>
-<td width="20%" align="left">
-<a accesskey="p" href="eng-standards-constraint-naming.html">Prev</a> </td>
-<th width="60%" align="center">Chapter 6. Engineering Standards</th>
-<td width="20%" align="right"> <a accesskey="n" href="eng-standards-plsql.html">Next</a>
-</td>
-</tr></table>
-<hr>
-</div>
-<div class="sect1">
-<div class="titlepage"><div><h2 class="title" style="clear: both">
-<a name="eng-standards-filenaming"></a>ACS File Naming and Formatting Standards</h2></div></div>
-<div class="authorblurb"><p>By <a href="mailto:michael@arsdigita.com" target="_top">michael@arsdigita.com</a> and
-<a href="mailto:aure@arsdigita.com" target="_top">aure@arsdigita.com</a>
-</p></div>
-<p>
+<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"><title>ACS File Naming and Formatting Standards</title><meta name="generator" content="DocBook XSL Stylesheets V1.50.0"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="eng-standards.html" title="Chapter 6. Engineering Standards"><link rel="previous" href="eng-standards-constraint-naming.html" title="Constraint naming standard"><link rel="next" href="eng-standards-plsql.html" title="PL/SQL Standards"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="eng-standards-constraint-naming.html">Prev</a> </td><th width="60%" align="center">Chapter 6. Engineering Standards</th><td width="20%" align="right"> <a accesskey="n" href="eng-standards-plsql.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="eng-standards-filenaming"></a>ACS File Naming and Formatting Standards</h2></div></div><div class="authorblurb"><p><p>By <a href="mailto:michael@arsdigita.com" target="_top">michael@arsdigita.com</a> and
+<a href="mailto:aure@arsdigita.com" target="_top">aure@arsdigita.com</a></p><br>
+ OpenACS docs are written by the named authors, but may be edited
+ by OpenACS documentation staff.
+ </p></div><p>
To ensure consistency (and its collateral benefit, maintainability),
we define and adhere to standards in the following areas:
-</p>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="eng-standards-filenaming-nomenclature"></a>File Nomenclature</h3></div></div>
-<p>
+</p><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="eng-standards-filenaming-nomenclature"></a>File Nomenclature</h3></div></div><p>
Usually we organize our files so that they mainly serve one of the following three purposes:
-</p>
-<div class="itemizedlist"><ul>
-<li><p> displaying objects and their properties</p></li>
-<li><p> manipulating or acting on objects in some way (by creating, editing, linking, etc)</p></li>
-<li><p> housing procedures, packages, data models and other prerequisite code
-Essentially, we want our files named in a fashion that reflects their purpose.</p></li>
-</ul></div>
-<p>
+</p><div class="itemizedlist"><ul type="disc"><li><p> displaying objects and their properties</p></li><li><p> manipulating or acting on objects in some way (by creating, editing, linking, etc)</p></li><li><p> housing procedures, packages, data models and other prerequisite code
+Essentially, we want our files named in a fashion that reflects their purpose.</p></li></ul></div><p>
Under the page root (and the template root if using the <a href="style" target="_top">Style package</a>):
-</p>
-<div class="itemizedlist"><ul>
-<li>
-<p>For naming files that enable a specific action on an object, use this format:</p>
-<blockquote class="blockquote"><p>
-<span class="emphasis"><i><tt>object-verb.extension</tt></i></span>
-</p></blockquote>
-<p>
+</p><div class="itemizedlist"><ul type="disc"><li><p>For naming files that enable a specific action on an object, use this format:</p><blockquote class="blockquote"><p>
+<span class="emphasis"><em><tt>object-verb.extension</tt></em></span>
+</p></blockquote><p>
For example, the page to erase a user's portrait from the database is
<tt>/admin/users/portrait-erase.tcl</tt>.
-</p>
-</li>
-<li>
-<p>However, modules typically deal with only one primary type of object -
+</p></li><li><p>However, modules typically deal with only one primary type of object -
e.g.,
the Bookmarks module deals mainly with bookmarks - and so action-type files in modules don't need to be specified by the object they act on. Example: the user pages
for the Bookmarks module live in the <tt>/bookmarks/</tt>
directory, and so there is no need to name the bookmark editing page with a redundant url: <tt>/bookmarks/bookmark-edit.tcl</tt>. Instead, we omit the object type, and use this convention:
-</p>
-<blockquote class="blockquote"><p>
-<span class="emphasis"><i><tt>verb.extension</tt></i></span>
-</p></blockquote>
-<p>
+</p><blockquote class="blockquote"><p>
+<span class="emphasis"><em><tt>verb.extension</tt></em></span>
+</p></blockquote><p>
Thus, the page to edit a bookmark is <tt>/bookmarks/edit.tcl</tt>.
-</p>
-</li>
-<li>
-<p>For naming files that display the properties of a primary object - such as the bookmark object within the bookmark module - use this convention:</p>
-<blockquote class="blockquote"><p>
-<tt>one.</tt><span class="emphasis"><i><tt>extension</tt></i></span>
-</p></blockquote>
-<p>
+</p></li><li><p>For naming files that display the properties of a primary object - such as the bookmark object within the bookmark module - use this convention:</p><blockquote class="blockquote"><p>
+<tt>one.</tt><span class="emphasis"><em><tt>extension</tt></em></span>
+</p></blockquote><p>
For example, the page to view one bookmark is
<tt>/bookmarks/one.tcl</tt>. Note that no verb is necessary for display-type files.
-</p>
-</li>
-<li>
-<p>Otherwise, if the object to be displayed is not the primary feature of a module, simply omit the verb and use the object name:</p>
-<blockquote class="blockquote"><p>
-<span class="emphasis"><i><tt>object.extension</tt></i></span>
-</p></blockquote>
-<p>
+</p></li><li><p>Otherwise, if the object to be displayed is not the primary feature of a module, simply omit the verb and use the object name:</p><blockquote class="blockquote"><p>
+<span class="emphasis"><em><tt>object.extension</tt></em></span>
+</p></blockquote><p>
For example, the page to view the properties of an
ecommerce product is
<tt>/ecommerce/product.tcl</tt>.
-</p>
-</li>
-<li>
-<p>For naming files in a page flow, use the convention:</p>
-<div class="itemizedlist"><ul>
-<li><p>
-<span class="emphasis"><i><tt>foobar.extension</tt></i></span> (Step 1)</p></li>
-<li><p>
-<span class="emphasis"><i><tt>foobar-2.extension</tt></i></span> (Step 2)</p></li>
-<li><p>...</p></li>
-<li><p>
-<span class="emphasis"><i><tt>foobar-N.extension</tt></i></span> (Step N)</p></li>
-</ul></div>
-<p>
-where <span class="emphasis"><i><tt>foobar</tt></i></span> is determined by the above
+</p></li><li><p>For naming files in a page flow, use the convention:</p><div class="itemizedlist"><ul type="round"><li><p><span class="emphasis"><em><tt>foobar.extension</tt></em></span> (Step 1)</p></li><li><p><span class="emphasis"><em><tt>foobar-2.extension</tt></em></span> (Step 2)</p></li><li><p>...</p></li><li><p><span class="emphasis"><em><tt>foobar-N.extension</tt></em></span> (Step N)</p></li></ul></div><p>
+where <span class="emphasis"><em><tt>foobar</tt></em></span> is determined by the above
rules.
-</p>
-<p>
+</p><p>
Typically, we use a three-step page flow when taking user information:
-</p>
-<div class="orderedlist"><ol type="1">
-<li><p>Present a form to the user</p></li>
-<li><p>Present a confirmation page to the user</p></li>
-<li><p>Perform the database transaction, then redirect</p></li>
-</ol></div>
-</li>
-<li>
-<p>Put data model files in <tt>/www/doc/sql</tt>, and name them
+</p><div class="orderedlist"><ol type="1"><li><p>Present a form to the user</p></li><li><p>Present a confirmation page to the user</p></li><li><p>Perform the database transaction, then redirect</p></li></ol></div></li><li><p>Put data model files in <tt>/www/doc/sql</tt>, and name them
for the modules towards which they are used:
-</p>
-<blockquote class="blockquote"><p>
-<span class="emphasis"><i><tt>module</tt></i></span><tt>.sql</tt>
-</p></blockquote>
-</li>
-</ul></div>
-<p>
+</p><blockquote class="blockquote"><p>
+<span class="emphasis"><em><tt>module</tt></em></span><tt>.sql</tt>
+</p></blockquote></li></ul></div><p>
In the Tcl library directory:
-</p>
-<div class="itemizedlist"><ul>
-<li>
-<p>For files that contain module-specific procedures, use the
-convention:</p>
-<blockquote class="blockquote"><p>
-<span class="emphasis"><i><tt>module</tt></i></span><tt>-procs.tcl</tt>
-</p></blockquote>
-</li>
-<li>
-<p>For files that contain procedures that are part of the core ACS,
-use the convention:</p>
-<blockquote class="blockquote"><p>
-<tt>ad-</tt><span class="emphasis"><i>description</i></span><tt>-procs.tcl</tt>
-</p></blockquote>
-</li>
-</ul></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="eng-standards-filenaming-urls"></a>URLs</h3></div></div>
-<p>
-File names also appear <span class="emphasis"><i>within</i></span> pages, as linked URLs and
+</p><div class="itemizedlist"><ul type="disc"><li><p>For files that contain module-specific procedures, use the
+convention:</p><blockquote class="blockquote"><p>
+<span class="emphasis"><em><tt>module</tt></em></span><tt>-procs.tcl</tt>
+</p></blockquote></li><li><p>For files that contain procedures that are part of the core ACS,
+use the convention:</p><blockquote class="blockquote"><p>
+<tt>ad-</tt><span class="emphasis"><em>description</em></span><tt>-procs.tcl</tt>
+</p></blockquote></li></ul></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="eng-standards-filenaming-urls"></a>URLs</h3></div></div><p>
+File names also appear <span class="emphasis"><em>within</em></span> pages, as linked URLs and
form targets. When they do, always use <a href="abstract-url" target="_top">abstract
URLs</a> (e.g., <tt>user-delete</tt> instead of
<tt>user-delete.tcl</tt>), because they enhance maintainability.
-</p>
-<p>
+</p><p>
Similarly, when linking to the index page of a directory, do not
explicitly name the index file (<tt>index.tcl</tt>,
<tt>index.adp</tt>, <tt>index.html</tt>, etc.). Instead, use
@@ -164,56 +68,40 @@
(<tt>/top-level-dir/</tt>). If linking to the directory in which
the page is located, use the empty string (<tt>""</tt>), which
browsers will resolve correctly.
-</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="eng-standards-filenaming-headers"></a>File Headers and Page Input</h3></div></div>
-<p>
+</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="eng-standards-filenaming-headers"></a>File Headers and Page Input</h3></div></div><p>
Include the appropriate standard header in all scripts. The first
line should be a comment specifying the file path relative to the
ACS root directory. e.g.
-</p>
-<blockquote class="blockquote"><p><tt>
+</p><blockquote class="blockquote"><p><tt>
# /www/index.tcl
-</tt></p></blockquote>
-<p>
+</tt></p></blockquote><p>
or
-</p>
-<blockquote class="blockquote"><p><tt>
+</p><blockquote class="blockquote"><p><tt>
# /tcl/module-defs.tcl
-</tt></p></blockquote>
-<p>
+</tt></p></blockquote><p>
For static content files (html or adp), include a CVS identification tag as a
comment at the top of the file, e.g.
-</p>
-<pre class="programlisting">
+</p><pre class="programlisting">
<!-- file-standards.html,v 1.2 2000/09/19 07:22:45 ron Exp -->
-</pre>
-<p>
+</pre><p>
In addition, all static HTML files, documentation and other pages
should have a visible CVS ID stamp, at least during development. These
can be removed at release times. This should take the form of a line
like this:
-</p>
-<pre class="programlisting">
+</p><pre class="programlisting">
<p>
Last Modified: file-standards.html,v 1.2 2000/09/19 07:22:45 ron Exp
</p>
-</pre>
-<p>
+</pre><p>
This can be at the top or bottom of the file.
-</p>
-<p><div>Using ad_page_contract</div></p>
-<p>
+</p><p><div>Using ad_page_contract</div><p>
For non-library Tcl files (those not in the private Tcl directory),
use <a href="tcl-doc.html#tcl-doc-ad-page-contract" title="ad_page_contract"><tt>ad_page_contract</tt></a>
after the file path comment (this supersedes set_the_usual_form_variables and
ad_return_complaint). Here is an example of using
ad_page_contract, which serves both documentation and page input
validation purposes:
-</p>
-<pre class="programlisting">
+</p><pre class="programlisting">
# www/register/user-login-2.tcl
ad_page_contract {
@@ -231,47 +119,35 @@
{return_url {[ad_pvt_home]}}
{persistent_cookie_p f}
}
-</pre>
-<p>
+</pre><p>
Salient features of <tt>ad_page_contract</tt>:
-</p>
-<div class="itemizedlist"><ul>
-<li><p>A mandatory documentation string is the first argument. This has
-the standard form with javadoc-style @author, @cvs-id, etc, and should contain a short description of the recieved variables and any necessary explanations. </p></li>
-<li><p>The second argument specifies the page
+</p><div class="itemizedlist"><ul type="disc"><li><p>A mandatory documentation string is the first argument. This has
+the standard form with javadoc-style @author, @cvs-id, etc, and should contain a short description of the recieved variables and any necessary explanations. </p></li><li><p>The second argument specifies the page
inputs. The syntax for switches/flags (e.g. multiple-list, array,
etc.) uses a colon (:) followed by any number of flags
separated by commas (,),
e.g. <tt>foo:integer,multiple,trim</tt>. In particular, <tt>multiple</tt> and
<tt>array</tt> are the flags that correspond to the old
-<tt>ad_page_variables</tt> flags.</p></li>
-<li><p>There are new flags: <tt>trim</tt>, <tt>notnull</tt> and
+<tt>ad_page_variables</tt> flags.</p></li><li><p>There are new flags: <tt>trim</tt>, <tt>notnull</tt> and
<tt>optional</tt>. They do what you'd expect; values will not be
trimmed, unless you mark them for it; empty strings are valid input, unless
you specify notnull; and a specified variable will be considered required,
-unless you declare it optional.</p></li>
-<li><p>
-<tt>ad_page_contract</tt> can do validation for you: the flags <tt>integer</tt>
+unless you declare it optional.</p></li><li><p><tt>ad_page_contract</tt> can do validation for you: the flags <tt>integer</tt>
and <tt>sql_identifier</tt> will make sure that the values
supplied are integers/sql_identifiers. The <tt>integer</tt> flag
will also trim leading zeros. Note that unless you specify
<tt>notnull</tt>, both will accept the empty string.
-</p></li>
-<li><p>Note that <tt>ad_page_contract</tt> does not generate
+</p></li><li><p>Note that <tt>ad_page_contract</tt> does not generate
QQvariables, which were automatically created by ad_page_variables and
set_the_usual_form_variables. The use of bind variables makes such
previous variable syntax obsolete.
-</p></li>
-</ul></div>
-<p><div>Using ad_library</div></p>
-<p>
+</p></li></ul></div><p><div>Using ad_library</div><p>
For shared Tcl library files, use <a href="tcl-doc.html#tcl-doc-ad-library" title="ad_library"><tt>ad_library</tt></a> after
the file path comment. Its only argument is a doc_string in the
standard (javadoc-style) format, like
<tt>ad_page_contract</tt>. Don't forget to put the @cvs-id in
there. Here is an example of using ad_library:
-</p>
-<pre class="programlisting">
+</p><pre class="programlisting">
# tcl/wp-defs.tcl
ad_library {
@@ -280,43 +156,32 @@
@author John Doe (jdoe@arsdigita.com)
@cvs-id file-standards.html,v 1.2 2000/09/19 07:22:45 ron Exp
}
-</pre>
-<p><div>Non-Tcl Files</div></p>
-<p>
+</pre><p><div>Non-Tcl Files</div><p>
For SQL and other non-Tcl source files, the following file header structure is recommended:
-</p>
-<pre class="programlisting">
--- <span class="emphasis"><i>path relative to the ACS root directory</i></span>
+</p><pre class="programlisting">
+-- <span class="emphasis"><em>path relative to the ACS root directory</em></span>
--
--- <span class="emphasis"><i>brief description of the file's purpose</i></span>
+-- <span class="emphasis"><em>brief description of the file's purpose</em></span>
--
--- <span class="emphasis"><i>author</i></span>
--- <span class="emphasis"><i>created</i></span>
+-- <span class="emphasis"><em>author</em></span>
+-- <span class="emphasis"><em>created</em></span>
--
-- <a href="http://www.loria.fr/~molli/cvs/doc/cvs_12.html#SEC93" target="_top">$Id$</a>
-</pre>
-<p>
+</pre><p>
Of course, replace "<tt>--</tt>" with the comment delimiter
appropriate for the language in which you are programming.
-</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="eng-standards-filenaming-pages"></a>Page Construction</h3></div></div>
-<p>
+</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="eng-standards-filenaming-pages"></a>Page Construction</h3></div></div><p>
Construct the page as one Tcl variable (name it
<tt>page_content</tt>), and then send it back to the browser with
one call to <tt>doc_return</tt>, which will call
db_release_unused_handles prior to executing ns_return, effectively
combining the two operations.
-</p>
-<p>
+</p><p>
For example:
-</p>
-<pre class="programlisting">
-set page_content "[ad_header "<span class="emphasis"><i>Page Title</i></span>"]
+</p><pre class="programlisting">
+set page_content "[ad_header "<span class="emphasis"><em>Page Title</em></span>"]
-<h2><span class="emphasis"><i>Page Title</i></span></h2>
+<h2><span class="emphasis"><em>Page Title</em></span></h2>
<hr>
@@ -327,16 +192,15 @@
select row_information
from bar
} {
- append page_content "<li><span class="emphasis"><i>row_information</i></span>\n"
+ append page_content "<li><span class="emphasis"><em>row_information</em></span>\n"
}
append page_content "</ul>
[ad_footer]"
doc_return 200 text/html $page_content
-</pre>
-<p>
+</pre><p>
The old convention was to call <tt>ReturnHeaders</tt> and
then <tt>ns_write</tt> for each distinct chunk of the page. This
approach has the disadvantage of tying up a scarce and valuable
@@ -349,56 +213,22 @@
first, so that the user is not left to stare at an empty page while
the query is running.)
-</p>
-<p>
+</p><p>
Local procedures (i.e., procedures defined and used only within one
-page) should be prefixed with "<span class="emphasis"><i><tt>module_</tt></i></span>" and
+page) should be prefixed with "<span class="emphasis"><em><tt>module_</tt></em></span>" and
should be used rarely, only when they are exceedingly useful.
-</p>
-<p>
+</p><p>
All files that prepare HTML to display should end with [ad_footer] or
-[<span class="emphasis"><i>module</i></span>_footer]. If your module requires its own footer,
+[<span class="emphasis"><em>module</em></span>_footer]. If your module requires its own footer,
this footer should call ad_footer within it. Why? Because when we
adapt the ACS to a new site, it is often the case that the client will
want a much fancier display than the ACS standard. We like to be able to
edit ad_header (which quite possibly can start a <table>) and
ad_footer (which may need to end the table started in ad_footer) to
customize the look and feel of the entire site.
-</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="eng-standards-filenaming-tcllib"></a>Tcl Library Files</h3></div></div>
-<p>
+</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="eng-standards-filenaming-tcllib"></a>Tcl Library Files</h3></div></div><p>
Further standards for Tcl library files are under discussion; we plan to
include naming conventions for procs.
-</p>
-<p><div class="cvstag">($Id$)</div></p>
-</div>
-</div>
-<div class="navfooter">
-<hr>
-<table width="100%" summary="Navigation footer">
-<tr>
-<td width="40%" align="left">
-<a accesskey="p" href="eng-standards-constraint-naming.html">Prev</a> </td>
-<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
-<td width="40%" align="right"> <a accesskey="n" href="eng-standards-plsql.html">Next</a>
-</td>
-</tr>
-<tr>
-<td width="40%" align="left">Constraint naming standard </td>
-<td width="20%" align="center"><a accesskey="u" href="eng-standards.html">Up</a></td>
-<td width="40%" align="right"> PL/SQL Standards</td>
-</tr>
-</table>
-<hr>
-<address>
- rmello at fslc.usu.edu
- </address>
-<address><a href="mailto:vinod@kurup.com">
+</p><p><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="eng-standards-constraint-naming.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="eng-standards-plsql.html">Next</a></td></tr><tr><td width="40%" align="left">Constraint naming standard </td><td width="20%" align="center"><a accesskey="u" href="eng-standards.html">Up</a></td><td width="40%" align="right"> PL/SQL Standards</td></tr></table><hr><address>rmello at fslc.usu.edu</address><address><a href="mailto:vinod@kurup.com">
vinod@kurup.com
- </a></address>
-</div>
-</body>
-</html>
+ </a></address></div></body></html>
Index: openacs-4/packages/acs-core-docs/www/eng-standards-plsql.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/eng-standards-plsql.html,v
diff -u -r1.7 -r1.7.2.1
--- openacs-4/packages/acs-core-docs/www/eng-standards-plsql.html 7 Mar 2002 06:55:36 -0000 1.7
+++ openacs-4/packages/acs-core-docs/www/eng-standards-plsql.html 15 May 2002 23:26:18 -0000 1.7.2.1
@@ -1,79 +1,40 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type">
-<title>PL/SQL Standards</title>
-<meta name="generator" content="DocBook XSL Stylesheets V1.45">
-<link rel="home" href="index.html" title="OpenACS Documentation">
-<link rel="up" href="eng-standards.html" title="Chapter 6. Engineering Standards">
-<link rel="previous" href="eng-standards-filenaming.html" title="ACS File Naming and Formatting Standards">
-<link rel="next" href="kernel-doc.html" title="Chapter 7. Kernel Documentation">
-<link rel="stylesheet" href="openacs.css" type="text/css">
-</head>
-<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-<div class="navheader">
-<a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr>
-<td width="20%" align="left">
-<a accesskey="p" href="eng-standards-filenaming.html">Prev</a> </td>
-<th width="60%" align="center">Chapter 6. Engineering Standards</th>
-<td width="20%" align="right"> <a accesskey="n" href="kernel-doc.html">Next</a>
-</td>
-</tr></table>
-<hr>
-</div>
-<div class="sect1">
-<div class="titlepage"><div><h2 class="title" style="clear: both">
-<a name="eng-standards-plsql"></a>PL/SQL Standards</h2></div></div>
-<div class="authorblurb"><p>
+<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"><title>PL/SQL Standards</title><meta name="generator" content="DocBook XSL Stylesheets V1.50.0"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="eng-standards.html" title="Chapter 6. Engineering Standards"><link rel="previous" href="eng-standards-filenaming.html" title="ACS File Naming and Formatting Standards"><link rel="next" href="kernel-doc.html" title="Chapter 7. Kernel Documentation"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="eng-standards-filenaming.html">Prev</a> </td><th width="60%" align="center">Chapter 6. Engineering Standards</th><td width="20%" align="right"> <a accesskey="n" href="kernel-doc.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="eng-standards-plsql"></a>PL/SQL Standards</h2></div></div><div class="authorblurb"><p><p>
By <a href="mailto:richardl@arsdigita.com" target="_top">richardl@arsdigita.com</a>
and <a href="mailto:yon@arsdigita.com" target="_top">yon@arsdigita.com</a>
-</p></div>
-<p>
+</p><br>
+ OpenACS docs are written by the named authors, but may be edited
+ by OpenACS documentation staff.
+ </p></div><p>
Like any other part of the OpenACS, PL/SQL (or pl/pgsql) code must be
maintainable and professional. This means that it must be consistent and
therefore must abide by certain standards. The standards will ensure that
our product will be useful long after the current people building and
maintaining it are around. Following are some standards and guidelines
that will help us achieve this goal:
-</p>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="eng-standards-plsql-general"></a>General</h3></div></div>
-<div class="orderedlist"><ol type="1">
-<li><p>
+</p><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="eng-standards-plsql-general"></a>General</h3></div></div><div class="orderedlist"><ol type="1"><li><p>
All PL/SQL code must be well documented. We must write code that
is maintainable by others, this is especially true in our case
because we are building an open source toolkit than anyone can
download and browse the source code. So document like you are
trying to impress your "Introduction to Programming" professor or
TA.
- </p></li>
-<li><p>
+ </p></li><li><p>
It is important to be consistent throughout an application as much
as is possible given the nature of team development. This means
carrying style and other conventions suchs as naming within an
application, not just within one file.
- </p></li>
-</ol></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="eng-standards-plsql-code"></a>Code</h3></div></div>
-<div class="orderedlist"><ol type="1">
-<li><p>
+ </p></li></ol></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="eng-standards-plsql-code"></a>Code</h3></div></div><div class="orderedlist"><ol type="1"><li><p>
Encapsulation of related fuctionality is key to maintainability
and upgradeability of our software. Try to bundle your code into
<a href="http://oradoc.photo.net/ora816/appdev.816/a77069/08_packs.htm#4376" target="_top">packages</a>
whenever possible. This will make upgrading, bug fixing, and
customizing, among other things, a possibility.
- </p></li>
-<li>
-<p>
+ </p></li><li><p>
When creating functions or procedures use the following template,
it demonstrates most of the guidelines set forth in this document
that correspond to functions and procedures:
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
create or replace procedure|function <proc_or_func_name> (
<param_1> in|out|inout <datatype>,
@@ -93,31 +54,24 @@
/
show errors
-</pre>
-</li>
-<li><p>
+</pre></li><li><p>
Always use <tt>create or replace procedure|function
<proc_or_func_name></tt>. It makes reloading packages much
easier and painless to someone who is upgrading or fixing a bug.
- </p></li>
-<li><p>
+ </p></li><li><p>
Always qualify <tt>end</tt> statements, i.e., the
<tt>end</tt> statement for a package should be <tt>end
<package_name>;</tt>, not just <tt>end;</tt>; same
goes for procedures, functions, package bodies, and triggers.
- </p></li>
-<li><p>
+ </p></li><li><p>
Always use the "show errors" SQL*Plus command after each PL/SQL
block. It will help you debug when there are compilation errors in
your PL/SQL code.
- </p></li>
-<li>
-<p>
+ </p></li><li><p>
Name parameters as simply as possible, i.e., use the column name
if the parameter corresponds to a table column. We're deprecating
the v_* and *_in syntax in favor of named parameters notation:
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
<tt>
acs_user.create(first_names => 'Jane', last_name => 'Doe', etc.)
@@ -127,16 +81,14 @@
acs_user.create(first_names_in => 'Jane', last_name_in => 'Doe', etc.)
</tt>
-</pre>
-<p>
+</pre><p>
To achieve this we must fully qualify arguements passed into
procedures or functions when using them inside a SQL
statement. This will get rid of any ambiguities in your code,
i.e. it will tell the parser when you want the value of the column
and when you want the value from the local variable. Here is an
example:
-</p>
-<pre class="programlisting">
+</p><pre class="programlisting">
create or replace package body mypackage
.
@@ -156,29 +108,21 @@
/
show errors
-</pre>
-</li>
-<li><p>
+</pre></li><li><p>
Explicitly designate each parameter as "in," "out," or "inout."
- </p></li>
-<li><p>
+ </p></li><li><p>
Each parameter should be on its own line, with a tab after the
parameter name, then in/out/inout, then a space, and finally the
datatype.
- </p></li>
-<li><p>
+ </p></li><li><p>
Use %TYPE and %ROWTYPE whenever possible.
- </p></li>
-<li><p>
+ </p></li><li><p>
Use 't' and 'f' for booleans, not the PL/SQL "boolean" datatype
because it can't be used in SQL queries.
- </p></li>
-<li>
-<p>
+ </p></li><li><p>
All <tt>new</tt> functions (e.g., <tt>acs_object.new,
party.new,</tt> etc.) should optionally accept an ID:
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
<tt>
create or replace package acs_object
@@ -193,61 +137,22 @@
) return acs_objects.object_id%TYPE;
</tt>
-</pre>
-<p>
+</pre><p>
takes the optional argument <tt>object_id</tt>. Do this to
allow people to use the same API call when they are doing double
click protection, that is, tehy have already gotten an
<tt>object_id</tt> and now they want to create the object with
that <tt>object_id</tt>.
- </p>
-</li>
-</ol></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="eng-standards-style"></a>Style</h3></div></div>
-<p>
+ </p></li></ol></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="eng-standards-style"></a>Style</h3></div></div><p>
Some general style guidelines to follow for the purpose of
consistency across applications.
-</p>
-<div class="orderedlist"><ol type="1">
-<li><p>
+</p><div class="orderedlist"><ol type="1"><li><p>
Standard indentation is 4 spaces. Our PL/SQL code is not only
viewable in the SQL files but also through our SQL and PL/SQL
browsers. This means that we should try to make it as consistent
as possible to all source code readers.
- </p></li>
-<li><p>
+ </p></li><li><p>
Lowercase everything, with the exception of %TYPE and %ROWTYPE.
- </p></li>
-</ol></div>
-<p><div class="cvstag">($Id$)</div></p>
-</div>
-</div>
-<div class="navfooter">
-<hr>
-<table width="100%" summary="Navigation footer">
-<tr>
-<td width="40%" align="left">
-<a accesskey="p" href="eng-standards-filenaming.html">Prev</a> </td>
-<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
-<td width="40%" align="right"> <a accesskey="n" href="kernel-doc.html">Next</a>
-</td>
-</tr>
-<tr>
-<td width="40%" align="left">ACS File Naming and Formatting Standards </td>
-<td width="20%" align="center"><a accesskey="u" href="eng-standards.html">Up</a></td>
-<td width="40%" align="right"> Chapter 7. Kernel Documentation</td>
-</tr>
-</table>
-<hr>
-<address>
- rmello at fslc.usu.edu
- </address>
-<address><a href="mailto:vinod@kurup.com">
+ </p></li></ol></div><p><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="eng-standards-filenaming.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="kernel-doc.html">Next</a></td></tr><tr><td width="40%" align="left">ACS File Naming and Formatting Standards </td><td width="20%" align="center"><a accesskey="u" href="eng-standards.html">Up</a></td><td width="40%" align="right"> Chapter 7. Kernel Documentation</td></tr></table><hr><address>rmello at fslc.usu.edu</address><address><a href="mailto:vinod@kurup.com">
vinod@kurup.com
- </a></address>
-</div>
-</body>
-</html>
+ </a></address></div></body></html>
Index: openacs-4/packages/acs-core-docs/www/eng-standards-versioning.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/eng-standards-versioning.html,v
diff -u -r1.7 -r1.7.2.1
--- openacs-4/packages/acs-core-docs/www/eng-standards-versioning.html 7 Mar 2002 06:55:36 -0000 1.7
+++ openacs-4/packages/acs-core-docs/www/eng-standards-versioning.html 15 May 2002 23:26:18 -0000 1.7.2.1
@@ -1,77 +1,43 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type">
-<title>Release Version Numbering</title>
-<meta name="generator" content="DocBook XSL Stylesheets V1.45">
-<link rel="home" href="index.html" title="OpenACS Documentation">
-<link rel="up" href="eng-standards.html" title="Chapter 6. Engineering Standards">
-<link rel="previous" href="requirements-template.html" title="System/Application Requirements Template">
-<link rel="next" href="eng-standards-constraint-naming.html" title="Constraint naming standard">
-<link rel="stylesheet" href="openacs.css" type="text/css">
-</head>
-<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-<div class="navheader">
-<a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr>
-<td width="20%" align="left">
-<a accesskey="p" href="requirements-template.html">Prev</a> </td>
-<th width="60%" align="center">Chapter 6. Engineering Standards</th>
-<td width="20%" align="right"> <a accesskey="n" href="eng-standards-constraint-naming.html">Next</a>
-</td>
-</tr></table>
-<hr>
-</div>
-<div class="sect1">
-<div class="titlepage"><div><h2 class="title" style="clear: both">
-<a name="eng-standards-versioning"></a>Release Version Numbering</h2></div></div>
-<div class="authorblurb"><p>By <a href="mailto:ron@arsdigita.com" target="_top">Ron Henderson</a>
-</p></div>
-<p>
+<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"><title>Release Version Numbering</title><meta name="generator" content="DocBook XSL Stylesheets V1.50.0"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="eng-standards.html" title="Chapter 6. Engineering Standards"><link rel="previous" href="requirements-template.html" title="System/Application Requirements Template"><link rel="next" href="eng-standards-constraint-naming.html" title="Constraint naming standard"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="requirements-template.html">Prev</a> </td><th width="60%" align="center">Chapter 6. Engineering Standards</th><td width="20%" align="right"> <a accesskey="n" href="eng-standards-constraint-naming.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="eng-standards-versioning"></a>Release Version Numbering</h2></div></div><div class="authorblurb"><p><p>By <a href="mailto:ron@arsdigita.com" target="_top">Ron Henderson</a></p><br>
+ OpenACS docs are written by the named authors, but may be edited
+ by OpenACS documentation staff.
+ </p></div><p>
OpenACS version numbers help identify at a high-level what is in a
particular release and what has changed since the last release. A
"version number" is really just a string of the form:
-</p>
-<blockquote class="blockquote"><p>
-<span class="emphasis"><i>major</i></span>-<span class="emphasis"><i>minor</i></span>-<span class="emphasis"><i>release</i></span>
-</p></blockquote>
-<p>
-A change in the <span class="emphasis"><i>major</i></span> version number indicates a fundamental
+</p><blockquote class="blockquote"><p><span class="emphasis"><em>major</em></span>-<span class="emphasis"><em>minor</em></span>-<span class="emphasis"><em>release</em></span></p></blockquote><p>
+A change in the <span class="emphasis"><em>major</em></span> version number indicates a fundamental
change in the architecture of the system, e.g. OpenACS 3 to ACS 4. A
-change in the <span class="emphasis"><i>minor</i></span> version number signifies the addition of
+change in the <span class="emphasis"><em>minor</em></span> version number signifies the addition of
new modules and minor data model changes, e.g. OpenACS 3.1 to OpenACS 3.2.
-The final <span class="emphasis"><i>release</i></span> number indicates the relative maturity of a
+The final <span class="emphasis"><em>release</em></span> number indicates the relative maturity of a
release and marks things like bug fixes; it follows the ordered
progression:
-</p>
-<pre class="programlisting">
+</p><pre class="programlisting">
alpha
beta
0 (production release)
1
2
...
-</pre>
-<p>
+</pre><p>
So typical release version numbers would be:
-</p>
-<pre class="programlisting">
+</p><pre class="programlisting">
openacs-3.2.5
openacs-4.0.beta
-</pre>
-<p>
+</pre><p>
The first is a relatively mature release of the OpenACS 3.2 base code
and the second is a non-public release of OpenACS 4.0 that probably still
has lots of bugs.
-</p>
-<p>
+</p><p>
Version numbers are also recorded in the CVS repository so that the
code tree can be restored to the exact state it was in for a
particular release. To translate between a distribution tar file
(acs-3.2.2.tar.gz) and a CVS tag, just swap '.' for '-' and add the
release date. The entire release history of the toolkit is recorded
in the tags for the top-level <tt>readme.txt</tt> file:
-</p>
-<pre class="programlisting">
+</p><pre class="programlisting">
> cvs log readme.txt
RCS file: /usr/local/cvsroot/acs/readme.txt,v
Working file: readme.txt
@@ -103,72 +69,28 @@
total revisions: 13; selected revisions: 13
description:
...
-</pre>
-<p>
+</pre><p>
In the future, OpenACS packages should follow this same
convention on version numbers.
-</p>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="eng-standards-transition-rules"></a>Transition Rules</h3></div></div>
-<p>So what distinguishes an <span class="emphasis"><i>alpha</i></span> release from a <span class="emphasis"><i>beta</i></span>
+</p><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="eng-standards-transition-rules"></a>Transition Rules</h3></div></div><p>So what distinguishes an <span class="emphasis"><em>alpha</em></span> release from a <span class="emphasis"><em>beta</em></span>
release? Or from a production release? We follow a specific set of
rules for how OpenACS makes the transition from one state of maturity to
-the next.</p>
-<p> Every release must pass the minimum requirements that it cleanly
+the next.</p><p> Every release must pass the minimum requirements that it cleanly
installs and cleanly upgrades from the previous version of OpenACS. In
-addition to this the <span class="emphasis"><i>release</i></span> label implies:</p>
-<blockquote class="blockquote"><div class="variablelist"><dl>
-<dt><span class="term"><span class="emphasis"><i>development</i></span>
-</span></dt>
-<dd><p>This is the default state for the head of the current release branch. We
-make no guarantees about this code.</p></dd>
-<dt><span class="term"><span class="emphasis"><i>alpha</i></span>
-</span></dt>
-<dd><p>All tickets of severity <span class="emphasis"><i>critical</i></span> have been closed and the
-distribution has no known installation or upgrade problems.</p></dd>
-<dt><span class="term"><span class="emphasis"><i>beta</i></span>
-</span></dt>
-<dd><p>All tickets of severity <span class="emphasis"><i>serious</i></span> or greater have been closed
+addition to this the <span class="emphasis"><em>release</em></span> label implies:</p><blockquote class="blockquote"><div class="variablelist"><dl><dt><span class="term"><span class="emphasis"><em>development</em></span>
+</span></dt><dd><p>This is the default state for the head of the current release branch. We
+make no guarantees about this code.</p></dd><dt><span class="term"><span class="emphasis"><em>alpha</em></span>
+</span></dt><dd><p>All tickets of severity <span class="emphasis"><em>critical</em></span> have been closed and the
+distribution has no known installation or upgrade problems.</p></dd><dt><span class="term"><span class="emphasis"><em>beta</em></span>
+</span></dt><dd><p>All tickets of severity <span class="emphasis"><em>serious</em></span> or greater have been closed
and all documentation is up to date (version history, release notes,
-new module docs, etc.).</p></dd>
-<dt><span class="term"><span class="emphasis"><i>production</i></span> [0, 1, ...]
-</span></dt>
-<dd><p>All tickets of severity <span class="emphasis"><i>medium</i></span> or greater have been closed,
-including issues reported from outside users.</p></dd>
-</dl></div></blockquote>
-<p> In the future we will guarantee that more mature releases
+new module docs, etc.).</p></dd><dt><span class="term"><span class="emphasis"><em>production</em></span> [0, 1, ...]
+</span></dt><dd><p>All tickets of severity <span class="emphasis"><em>medium</em></span> or greater have been closed,
+including issues reported from outside users.</p></dd></dl></div></blockquote><p> In the future we will guarantee that more mature releases
incorporate all the fixes for earlier problems by developing a
detailed set of regression tests. For now we try to enforce this by
restricting work on the release branch to fixing reported problem in
the current release, e.g. no new features or big changes to
-fundamental behavior.</p>
-<p><div class="cvstag">($Id$)</div></p>
-</div>
-</div>
-<div class="navfooter">
-<hr>
-<table width="100%" summary="Navigation footer">
-<tr>
-<td width="40%" align="left">
-<a accesskey="p" href="requirements-template.html">Prev</a> </td>
-<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
-<td width="40%" align="right"> <a accesskey="n" href="eng-standards-constraint-naming.html">Next</a>
-</td>
-</tr>
-<tr>
-<td width="40%" align="left">System/Application Requirements Template </td>
-<td width="20%" align="center"><a accesskey="u" href="eng-standards.html">Up</a></td>
-<td width="40%" align="right"> Constraint naming standard</td>
-</tr>
-</table>
-<hr>
-<address>
- rmello at fslc.usu.edu
- </address>
-<address><a href="mailto:vinod@kurup.com">
+fundamental behavior.</p><p><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="requirements-template.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="eng-standards-constraint-naming.html">Next</a></td></tr><tr><td width="40%" align="left">System/Application Requirements Template </td><td width="20%" align="center"><a accesskey="u" href="eng-standards.html">Up</a></td><td width="40%" align="right"> Constraint naming standard</td></tr></table><hr><address>rmello at fslc.usu.edu</address><address><a href="mailto:vinod@kurup.com">
vinod@kurup.com
- </a></address>
-</div>
-</body>
-</html>
+ </a></address></div></body></html>
Index: openacs-4/packages/acs-core-docs/www/eng-standards.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/eng-standards.html,v
diff -u -r1.5 -r1.5.2.1
--- openacs-4/packages/acs-core-docs/www/eng-standards.html 7 Mar 2002 06:55:36 -0000 1.5
+++ openacs-4/packages/acs-core-docs/www/eng-standards.html 15 May 2002 23:26:18 -0000 1.5.2.1
@@ -1,66 +1,4 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type">
-<title>Chapter 6. Engineering Standards</title>
-<meta name="generator" content="DocBook XSL Stylesheets V1.45">
-<link rel="home" href="index.html" title="OpenACS Documentation">
-<link rel="up" href="acs-dev.html" title="Part Part III. For OpenACS Developers">
-<link rel="previous" href="programming-with-aolserver.html" title="Programming with AOLserver">
-<link rel="next" href="docbook-primer.html" title="OpenACS Documentation Guide">
-<link rel="stylesheet" href="openacs.css" type="text/css">
-</head>
-<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-<div class="navheader">
-<a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr>
-<td width="20%" align="left">
-<a accesskey="p" href="programming-with-aolserver.html">Prev</a> </td>
-<th width="60%" align="center">Part Part III. For OpenACS Developers</th>
-<td width="20%" align="right"> <a accesskey="n" href="docbook-primer.html">Next</a>
-</td>
-</tr></table>
-<hr>
-</div>
-<div class="chapter">
-<div class="titlepage"><div><h2 class="title">
-<a name="eng-standards"></a>Chapter 6. Engineering Standards</h2></div></div>
-<div class="toc">
-<p><b>Table of Contents</b></p>
-<dl>
-<dt><a href="docbook-primer.html">OpenACS Documentation Guide</a></dt>
-<dt><a href="psgml-mode.html">Using PSGML mode in Emacs</a></dt>
-<dt><a href="filename.html">Detailed Design Documentation Template</a></dt>
-<dt><a href="requirements-template.html">System/Application Requirements Template</a></dt>
-<dt><a href="eng-standards-versioning.html">Release Version Numbering</a></dt>
-<dt><a href="eng-standards-constraint-naming.html">Constraint naming standard</a></dt>
-<dt><a href="eng-standards-filenaming.html">ACS File Naming and Formatting Standards</a></dt>
-<dt><a href="eng-standards-plsql.html">PL/SQL Standards</a></dt>
-</dl>
-</div>
-</div>
-<div class="navfooter">
-<hr>
-<table width="100%" summary="Navigation footer">
-<tr>
-<td width="40%" align="left">
-<a accesskey="p" href="programming-with-aolserver.html">Prev</a> </td>
-<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
-<td width="40%" align="right"> <a accesskey="n" href="docbook-primer.html">Next</a>
-</td>
-</tr>
-<tr>
-<td width="40%" align="left">Programming with AOLserver </td>
-<td width="20%" align="center"><a accesskey="u" href="acs-dev.html">Up</a></td>
-<td width="40%" align="right"> OpenACS Documentation Guide</td>
-</tr>
-</table>
-<hr>
-<address>
- rmello at fslc.usu.edu
- </address>
-<address><a href="mailto:vinod@kurup.com">
+<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"><title>Chapter 6. Engineering Standards</title><meta name="generator" content="DocBook XSL Stylesheets V1.50.0"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="acs-dev.html" title="Part Part III. For OpenACS Developers"><link rel="previous" href="programming-with-aolserver.html" title="Programming with AOLserver"><link rel="next" href="docbook-primer.html" title="OpenACS Documentation Guide"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="programming-with-aolserver.html">Prev</a> </td><th width="60%" align="center">Part Part III. For OpenACS Developers</th><td width="20%" align="right"> <a accesskey="n" href="docbook-primer.html">Next</a></td></tr></table><hr></div><div class="chapter"><div class="titlepage"><div><h2 class="title"><a name="eng-standards"></a>Chapter 6. Engineering Standards</h2></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a href="docbook-primer.html">OpenACS Documentation Guide</a></dt><dt><a href="psgml-mode.html">Using PSGML mode in Emacs</a></dt><dt><a href="filename.html">Detailed Design Documentation Template</a></dt><dt><a href="requirements-template.html">System/Application Requirements Template</a></dt><dt><a href="eng-standards-versioning.html">Release Version Numbering</a></dt><dt><a href="eng-standards-constraint-naming.html">Constraint naming standard</a></dt><dt><a href="eng-standards-filenaming.html">ACS File Naming and Formatting Standards</a></dt><dt><a href="eng-standards-plsql.html">PL/SQL Standards</a></dt></dl></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="programming-with-aolserver.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="docbook-primer.html">Next</a></td></tr><tr><td width="40%" align="left">Programming with AOLserver </td><td width="20%" align="center"><a accesskey="u" href="acs-dev.html">Up</a></td><td width="40%" align="right"> OpenACS Documentation Guide</td></tr></table><hr><address>rmello at fslc.usu.edu</address><address><a href="mailto:vinod@kurup.com">
vinod@kurup.com
- </a></address>
-</div>
-</body>
-</html>
+ </a></address></div></body></html>
Index: openacs-4/packages/acs-core-docs/www/filename.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/filename.html,v
diff -u -r1.7 -r1.7.2.1
--- openacs-4/packages/acs-core-docs/www/filename.html 7 Mar 2002 06:55:36 -0000 1.7
+++ openacs-4/packages/acs-core-docs/www/filename.html 15 May 2002 23:26:18 -0000 1.7.2.1
@@ -1,36 +1,6 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type">
-<title>Detailed Design Documentation Template</title>
-<meta name="generator" content="DocBook XSL Stylesheets V1.45">
-<link rel="home" href="index.html" title="OpenACS Documentation">
-<link rel="up" href="eng-standards.html" title="Chapter 6. Engineering Standards">
-<link rel="previous" href="psgml-mode.html" title="Using PSGML mode in Emacs">
-<link rel="next" href="requirements-template.html" title="System/Application Requirements Template">
-<link rel="stylesheet" href="openacs.css" type="text/css">
-</head>
-<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-<div class="navheader">
-<a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr>
-<td width="20%" align="left">
-<a accesskey="p" href="psgml-mode.html">Prev</a> </td>
-<th width="60%" align="center">Chapter 6. Engineering Standards</th>
-<td width="20%" align="right"> <a accesskey="n" href="requirements-template.html">Next</a>
-</td>
-</tr></table>
-<hr>
-</div>
-<div class="sect1">
-<div class="titlepage"><div><h2 class="title" style="clear: both">
-<a name="filename"></a>Detailed Design Documentation Template</h2></div></div>
-<p>By <a href="mailto:youremail@arsdigita.com" target="_top">You</a>
-</p>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="yourpackage-design-start-note"></a>Start Note</h3></div></div>
-<p>
- <span class="emphasis"><i>NOTE: Some of the sections of this template may not apply to your
+<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"><title>Detailed Design Documentation Template</title><meta name="generator" content="DocBook XSL Stylesheets V1.50.0"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="eng-standards.html" title="Chapter 6. Engineering Standards"><link rel="previous" href="psgml-mode.html" title="Using PSGML mode in Emacs"><link rel="next" href="requirements-template.html" title="System/Application Requirements Template"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="psgml-mode.html">Prev</a> </td><th width="60%" align="center">Chapter 6. Engineering Standards</th><td width="20%" align="right"> <a accesskey="n" href="requirements-template.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="filename"></a>Detailed Design Documentation Template</h2></div></div><p>By <a href="mailto:youremail@arsdigita.com" target="_top">You</a></p><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="yourpackage-design-start-note"></a>Start Note</h3></div></div><p>
+ <span class="emphasis"><em>NOTE: Some of the sections of this template may not apply to your
package, e.g. there may be no user-visible UI elements for a component
of the OpenACS Core. Furthermore, it may be easier in some circumstances
to join certain sections together, e.g. it may make sense to discuss
@@ -39,101 +9,50 @@
structure the design discussion by the structure used in the
requirements document. As this template is just a starting point, use
your own judgment, consult with peers when possible, and adapt
- intelligently.</i></span>
- </p>
-<p>
- <span class="emphasis"><i>Also, bear in mind <span class="strong"><i>the audience</i></span> for detailed design: fellow
+ intelligently.</em></span>
+ </p><p>
+ <span class="emphasis"><em>Also, bear in mind <span class="strong"><em>the audience</em></span> for detailed design: fellow
programmers who want to maintain/extend the software, AND parties
- interested in evaluating software quality. </i></span>
- </p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="yourpackage-design-essentials"></a>Essentials</h3></div></div>
-<p>
+ interested in evaluating software quality. </em></span>
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="yourpackage-design-essentials"></a>Essentials</h3></div></div><p>
When applicable, each of the following items should receive its own link:
- </p>
-<div class="itemizedlist"><ul>
-<li><p> User directory </p></li>
-<li><p> OpenACS administrator directory </p></li>
-<li><p> Subsite administrator directory </p></li>
-<li><p> Tcl script directory (link to the API browser page for the package) </p></li>
-<li><p> PL/SQL file (link to the API browser page for the package) </p></li>
-<li><p> Data model </p></li>
-<li><p> Requirements document </p></li>
-<li><p> ER diagram </p></li>
-<li><p> Transaction flow diagram </p></li>
-</ul></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="yourpackage-design-introduction"></a>Introduction</h3></div></div>
-<p>
+ </p><div class="itemizedlist"><ul type="disc"><li><p> User directory </p></li><li><p> OpenACS administrator directory </p></li><li><p> Subsite administrator directory </p></li><li><p> Tcl script directory (link to the API browser page for the package) </p></li><li><p> PL/SQL file (link to the API browser page for the package) </p></li><li><p> Data model </p></li><li><p> Requirements document </p></li><li><p> ER diagram </p></li><li><p> Transaction flow diagram </p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="yourpackage-design-introduction"></a>Introduction</h3></div></div><p>
This section should provide an overview of the package
and address at least the following issues:
- </p>
-<div class="itemizedlist"><ul>
-<li><p> What this package is intended to allow the user (or different
- classes of users) to accomplish. </p></li>
-<li><p> Within reasonable bounds, what this package is not intended to allow users to
- accomplish. </p></li>
-<li><p> The application domains where this package is most likely to be of use. </p></li>
-<li><p> A high-level overview of how the package meets its
+ </p><div class="itemizedlist"><ul type="disc"><li><p> What this package is intended to allow the user (or different
+ classes of users) to accomplish. </p></li><li><p> Within reasonable bounds, what this package is not intended to allow users to
+ accomplish. </p></li><li><p> The application domains where this package is most likely to be of use. </p></li><li><p> A high-level overview of how the package meets its
requirements (which should have been documented elsewhere). This
is to include relevant material from the "features" section of the
cover sheet (the cover sheet is a wrapper doc with links to all
- other package docs). </p></li>
-</ul></div>
-<p>
+ other package docs). </p></li></ul></div><p>
Also worthy of treatment in this section:
- </p>
-<div class="itemizedlist"><ul><li><p> When applicable, a careful demarcation between the
+ </p><div class="itemizedlist"><ul type="disc"><li><p> When applicable, a careful demarcation between the
functionality of this package and others which - at least
- superficially - appear to address the same requirements. </p></li></ul></div>
-<p>
+ superficially - appear to address the same requirements. </p></li></ul></div><p>
Note: it's entirely possible that a discussion of what a package
is not intended to do differs from a discussion of future
improvements for the package.
- </p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="yourpackage-design-historical-consid"></a>Historical Considerations</h3></div></div>
-<p>
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="yourpackage-design-historical-consid"></a>Historical Considerations</h3></div></div><p>
For a given set of requirements, typically many possible
implementations and solutions exist. Although eventually only one
solution is implemented, a discussion of the alternative solutions
canvassed - noting why they were rejected - proves helpful to both
current and future developers. All readers would be reminded as to
why and how the particular solution developed over time, avoiding
re-analysis of problems already solved.
- </p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="yourpackage-design-competitive-analysis"></a>Competitive Analysis</h3></div></div>
-<p>
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="yourpackage-design-competitive-analysis"></a>Competitive Analysis</h3></div></div><p>
Although currently only a few package documentation pages contain a
discussion of competing software, (e.g. chat, portals), this section
should be present whenever such competition exists.
- </p>
-<div class="itemizedlist"><ul>
-<li><p> If your package exhibits features missing from competing
- software, this fact should be underscored. </p></li>
-<li><p> If your package lacks features which are present in competing
+ </p><div class="itemizedlist"><ul type="disc"><li><p> If your package exhibits features missing from competing
+ software, this fact should be underscored. </p></li><li><p> If your package lacks features which are present in competing
software, the reasons for this should be discussed here; our sales
team needs to be ready for inquiries regarding features our software
- lacks. </p></li>
-</ul></div>
-<p>
+ lacks. </p></li></ul></div><p>
Note that such a discussion may differ from a discussion of a
package's potential future improvements.
- </p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="yourpackage-design-design-tradeoffs"></a>Design Tradeoffs</h3></div></div>
-<p>
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="yourpackage-design-design-tradeoffs"></a>Design Tradeoffs</h3></div></div><p>
No single design solution can optimize every desirable software
attribute. For example, an increase in the security of a system will
likely entail a decrease in its ease-of-use, and an increase in the
@@ -143,42 +62,16 @@
should include a discussion of the tradeoffs involved with the design
chosen, and the reasons for your choices. Some areas of importance to
keep in mind are:
- </p>
-<p>Areas of interest to users:</p>
-<div class="itemizedlist"><ul>
-<li><p> Performance: availability and efficiency </p></li>
-<li><p> Flexibility </p></li>
-<li><p> Interoperability </p></li>
-<li><p> Reliability and robustness </p></li>
-<li><p> Usability </p></li>
-</ul></div>
-<p>Areas of interest to developers:</p>
-<div class="itemizedlist"><ul>
-<li><p> Maintainability </p></li>
-<li><p> Portability </p></li>
-<li><p> Reusability </p></li>
-<li><p> Testability </p></li>
-</ul></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="yourpackage-design-api"></a>API</h3></div></div>
-<p>
+ </p><p>Areas of interest to users:</p><div class="itemizedlist"><ul type="disc"><li><p> Performance: availability and efficiency </p></li><li><p> Flexibility </p></li><li><p> Interoperability </p></li><li><p> Reliability and robustness </p></li><li><p> Usability </p></li></ul></div><p>Areas of interest to developers:</p><div class="itemizedlist"><ul type="disc"><li><p> Maintainability </p></li><li><p> Portability </p></li><li><p> Reusability </p></li><li><p> Testability </p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="yourpackage-design-api"></a>API</h3></div></div><p>
Here's where you discuss the abstractions used by your package, such
as the procedures encapsulating the legal transactions on the data
model. Explain the organization of procedures and their
particulars (detail above and beyond what is documented in the
code), including:
- </p>
-<div class="itemizedlist"><ul>
-<li><p> Problem-domain components: key algorithms, e.g. a specialized
- statistics package would implement specific mathematical procedures. </p></li>
-<li><p> User-interface components: e.g. HTML widgets that the package may need. </p></li>
-<li><p> Data management components: procedures that provide a stable
+ </p><div class="itemizedlist"><ul type="disc"><li><p> Problem-domain components: key algorithms, e.g. a specialized
+ statistics package would implement specific mathematical procedures. </p></li><li><p> User-interface components: e.g. HTML widgets that the package may need. </p></li><li><p> Data management components: procedures that provide a stable
interface to database objects and legal transactions - the latter
- often correspond to tasks. </p></li>
-</ul></div>
-<p>
+ often correspond to tasks. </p></li></ul></div><p>
Remember that the correctness, completeness, and stability of the API
and interface are what experienced members of our audience are looking
for. This is a cultural shift for us at aD (as of mid-year 2000), in
@@ -187,183 +80,66 @@
handle transactions, instead of encapsulating them via procedures).
Experience has taught us that we need to focus on the API for
maintainability of our systems in the face of constant change.
- </p>
-<p>
+ </p><p>
Also noteworthy is that although the OpenACS currently utilizes the
AOLserver Tcl API, the current drive towards Java is likely to effect
a change in the content of these sections in the future.
- </p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="yourpackage-design-data-model"></a>Data Model Discussion</h3></div></div>
-<p>
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="yourpackage-design-data-model"></a>Data Model Discussion</h3></div></div><p>
The data model discussion should do more than merely display the SQL
code, since this information is already be available via a link in the
"essentials" section above. Instead, there should be a high-level
discussion of how your data model meets your solution requirements:
why the database entities were defined as they are, and what
transactions you expect to occur. (There may be some overlap with the
API section.) Here are some starting points:
- </p>
-<div class="itemizedlist"><ul>
-<li><p> The data model discussion should address the intended usage
+ </p><div class="itemizedlist"><ul type="disc"><li><p> The data model discussion should address the intended usage
of each entity (table, trigger, view, procedure, etc.) when this
information is not obvious from an inspection of the data model
- itself. </p></li>
-<li><p> If a core service or other subsystem is being used (e.g., the
+ itself. </p></li><li><p> If a core service or other subsystem is being used (e.g., the
new parties and groups, permissions, etc.) this should also be
- mentioned. </p></li>
-<li><p> Any default permissions should be identified herein. </p></li>
-<li><p> Discuss any data model extensions which tie into other
- packages. </p></li>
-<li>
-<p><span class="strong"><i>Transactions</i></span></p>
-<p> Discuss modifications which the database may undergo from
+ mentioned. </p></li><li><p> Any default permissions should be identified herein. </p></li><li><p> Discuss any data model extensions which tie into other
+ packages. </p></li><li><p><span class="strong"><em>Transactions</em></span></p><p> Discuss modifications which the database may undergo from
your package. Consider grouping legal transactions according to
the invoking user class, i.e. transactions by an OpenACS-admin, by
- subsite-admin, by a user, by a developer, etc. </p>
-</li>
-</ul></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="yourpackage-design-ui"></a>User Interface</h3></div></div>
-<p>
+ subsite-admin, by a user, by a developer, etc. </p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="yourpackage-design-ui"></a>User Interface</h3></div></div><p>
In this section, discuss user interface issues and pages to be built;
you can organize by the expected classes of users. These may include:
- </p>
-<div class="itemizedlist"><ul>
-<li><p> Developers</p></li>
-<li><p> OpenACS administrators (previously known as site-wide administrators)</p></li>
-<li><p> Subsite administrators</p></li>
-<li><p> End users</p></li>
-</ul></div>
-<p>
+ </p><div class="itemizedlist"><ul type="disc"><li><p> Developers</p></li><li><p> OpenACS administrators (previously known as site-wide administrators)</p></li><li><p> Subsite administrators</p></li><li><p> End users</p></li></ul></div><p>
You may want to include page mockups, site-maps, or other visual aids.
Ideally this section is informed by some prototyping you've done, to
establish the package's usability with the client and other interested
parties.
- </p>
-<p>
- <span class="emphasis"><i>Note: In order that developer documentation be uniform across
+ </p><p>
+ <span class="emphasis"><em>Note: In order that developer documentation be uniform across
different system documents, these users should herein be designated as
"the developer," "the OpenACS-admin," "the sub-admin," and "the user,"
- respectively. </i></span>
- </p>
-<p>
+ respectively. </em></span>
+ </p><p>
Finally, note that as our templating system becomes more entrenched
within the OpenACS, this section's details are likely to shift from UI
specifics to template interface specifics.
- </p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="yourpackage-design-config"></a>Configuration/Parameters</h3></div></div>
-<p>
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="yourpackage-design-config"></a>Configuration/Parameters</h3></div></div><p>
Under OpenACS 4.5, parameters are set at two levels: at the global level by
the OpenACS-admin, and at the subsite level by a sub-admin. In this
section, list and discuss both levels of parameters.
- </p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="yourpackage-design-future"></a>Future Improvements/Areas of Likely Change</h3></div></div>
-<p>
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="yourpackage-design-future"></a>Future Improvements/Areas of Likely Change</h3></div></div><p>
If the system presently lacks useful/desirable features, note details
here. You could also comment on non-functional improvements to the
package, such as usability.
- </p>
-<p>
+ </p><p>
Note that a careful treatment of the earlier "competitive analysis"
section can greatly facilitate the documenting of this section.
- </p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="yourpackage-design-authors"></a>Authors</h3></div></div>
-<p>
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="yourpackage-design-authors"></a>Authors</h3></div></div><p>
Although a system's data model file often contains this information,
this isn't always the case. Furthermore, data model files often
undergo substantial revision, making it difficult to track down the
system creator. An additional complication: package documentation may
be authored by people not directly involved in coding. Thus to avoid
unnecessary confusion, include email links to the following roles as
they may apply:
- </p>
-<div class="itemizedlist"><ul>
-<li><p> System creator</p></li>
-<li><p> System owner</p></li>
-<li><p> Documentation author</p></li>
-</ul></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="yourpackage-design-revision-history"></a>Revision History</h3></div></div>
-<p>
- <span class="emphasis"><i>The revision history table below is for this template - modify it
- as needed for your actual design document. </i></span>
- </p>
-<div class="informaltable"><table border="1">
-<colgroup>
-<col>
-<col>
-<col>
-<col>
-</colgroup>
-<thead><tr>
-<th>Document Revision #</th>
-<th>Action Taken, Notes</th>
-<th>When?</th>
-<th>By Whom?</th>
-</tr></thead>
-<tbody>
-<tr>
-<td>0.3</td>
-<td>Edited further, incorporated feedback from Michael Yoon</td>
-<td>9/05/2000</td>
-<td>Kai Wu</td>
-</tr>
-<tr>
-<td>0.2</td>
-<td>Edited</td>
-<td>8/22/2000</td>
-<td>Kai Wu</td>
-</tr>
-<tr>
-<td>0.1</td>
-<td>Creation</td>
-<td>8/21/2000</td>
-<td>Josh Finkler, Audrey McLoghlin</td>
-</tr>
-</tbody>
-</table></div>
-<p><div class="cvstag">($Id$)</div></p>
-</div>
-</div>
-<div class="navfooter">
-<hr>
-<table width="100%" summary="Navigation footer">
-<tr>
-<td width="40%" align="left">
-<a accesskey="p" href="psgml-mode.html">Prev</a> </td>
-<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
-<td width="40%" align="right"> <a accesskey="n" href="requirements-template.html">Next</a>
-</td>
-</tr>
-<tr>
-<td width="40%" align="left">Using PSGML mode in Emacs </td>
-<td width="20%" align="center"><a accesskey="u" href="eng-standards.html">Up</a></td>
-<td width="40%" align="right"> System/Application Requirements Template</td>
-</tr>
-</table>
-<hr>
-<address>
- rmello at fslc.usu.edu
- </address>
-<address><a href="mailto:vinod@kurup.com">
+ </p><div class="itemizedlist"><ul type="disc"><li><p> System creator</p></li><li><p> System owner</p></li><li><p> Documentation author</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="yourpackage-design-revision-history"></a>Revision History</h3></div></div><p>
+ <span class="emphasis"><em>The revision history table below is for this template - modify it
+ as needed for your actual design document. </em></span>
+ </p><div class="informaltable"><table border="1"><colgroup><col><col><col><col></colgroup><thead><tr><th>Document Revision #</th><th>Action Taken, Notes</th><th>When?</th><th>By Whom?</th></tr></thead><tbody><tr><td>0.3</td><td>Edited further, incorporated feedback from Michael Yoon</td><td>9/05/2000</td><td>Kai Wu</td></tr><tr><td>0.2</td><td>Edited</td><td>8/22/2000</td><td>Kai Wu</td></tr><tr><td>0.1</td><td>Creation</td><td>8/21/2000</td><td>Josh Finkler, Audrey McLoghlin</td></tr></tbody></table></div><p><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="psgml-mode.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="requirements-template.html">Next</a></td></tr><tr><td width="40%" align="left">Using PSGML mode in Emacs </td><td width="20%" align="center"><a accesskey="u" href="eng-standards.html">Up</a></td><td width="40%" align="right"> System/Application Requirements Template</td></tr></table><hr><address>rmello at fslc.usu.edu</address><address><a href="mailto:vinod@kurup.com">
vinod@kurup.com
- </a></address>
-</div>
-</body>
-</html>
+ </a></address></div></body></html>
Index: openacs-4/packages/acs-core-docs/www/for-everyone.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/for-everyone.html,v
diff -u -r1.6 -r1.6.2.1
--- openacs-4/packages/acs-core-docs/www/for-everyone.html 7 Mar 2002 06:55:36 -0000 1.6
+++ openacs-4/packages/acs-core-docs/www/for-everyone.html 15 May 2002 23:26:18 -0000 1.6.2.1
@@ -1,68 +1,4 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type">
-<title>Part Part I. OpenACS For Everyone</title>
-<meta name="generator" content="DocBook XSL Stylesheets V1.45">
-<link rel="home" href="index.html" title="OpenACS Documentation">
-<link rel="up" href="index.html" title="OpenACS Documentation">
-<link rel="previous" href="index.html" title="OpenACS Documentation">
-<link rel="next" href="general-documents.html" title="Chapter 1. High level information: What is OpenACS?">
-<link rel="stylesheet" href="openacs.css" type="text/css">
-</head>
-<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-<div class="navheader">
-<a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr>
-<td width="20%" align="left">
-<a accesskey="p" href="index.html">Prev</a> </td>
-<th width="60%" align="center"> </th>
-<td width="20%" align="right"> <a accesskey="n" href="general-documents.html">Next</a>
-</td>
-</tr></table>
-<hr>
-</div>
-<div class="part">
-<div class="titlepage"><div><h1 class="title">
-<a name="for-everyone"></a>OpenACS For Everyone</h1></div></div>
-<div class="partintro">
-<div></div>
-<p>High level information: What is OpenACS?</p>
-<div class="toc">
-<p><b>Table of Contents</b></p>
-<dl>
-<dt>1. <a href="general-documents.html">High level information: What is OpenACS?</a>
-</dt>
-<dd><dl>
-<dt><a href="openacs-overview.html">Overview</a></dt>
-<dt><a href="release-notes.html">OpenACS 4.5 Release Notes</a></dt>
-</dl></dd>
-</dl>
-</div>
-</div>
-</div>
-<div class="navfooter">
-<hr>
-<table width="100%" summary="Navigation footer">
-<tr>
-<td width="40%" align="left">
-<a accesskey="p" href="index.html">Prev</a> </td>
-<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
-<td width="40%" align="right"> <a accesskey="n" href="general-documents.html">Next</a>
-</td>
-</tr>
-<tr>
-<td width="40%" align="left">OpenACS Documentation </td>
-<td width="20%" align="center"><a accesskey="u" href="index.html">Up</a></td>
-<td width="40%" align="right"> Chapter 1. High level information: What is OpenACS?</td>
-</tr>
-</table>
-<hr>
-<address>
- rmello at fslc.usu.edu
- </address>
-<address><a href="mailto:vinod@kurup.com">
+<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"><title>Part Part I. OpenACS For Everyone</title><meta name="generator" content="DocBook XSL Stylesheets V1.50.0"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="index.html" title="OpenACS Documentation"><link rel="previous" href="index.html" title="OpenACS Documentation"><link rel="next" href="general-documents.html" title="Chapter 1. High level information: What is OpenACS?"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="index.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="general-documents.html">Next</a></td></tr></table><hr></div><div class="part"><div class="titlepage"><div><h1 class="title"><a name="for-everyone"></a>OpenACS For Everyone</h1></div></div><div class="partintro"><div></div><p>High level information: What is OpenACS?</p><div class="toc"><p><b>Table of Contents</b></p><dl><dt>1. <a href="general-documents.html">High level information: What is OpenACS?</a></dt><dd><dl><dt><a href="openacs-overview.html">Overview</a></dt><dt><a href="release-notes.html">OpenACS 4.5 Release Notes</a></dt></dl></dd></dl></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="index.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="general-documents.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS Documentation </td><td width="20%" align="center"><a accesskey="u" href="index.html">Up</a></td><td width="40%" align="right"> Chapter 1. High level information: What is OpenACS?</td></tr></table><hr><address>rmello at fslc.usu.edu</address><address><a href="mailto:vinod@kurup.com">
vinod@kurup.com
- </a></address>
-</div>
-</body>
-</html>
+ </a></address></div></body></html>
Index: openacs-4/packages/acs-core-docs/www/general-documents.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/general-documents.html,v
diff -u -r1.6 -r1.6.2.1
--- openacs-4/packages/acs-core-docs/www/general-documents.html 7 Mar 2002 06:55:36 -0000 1.6
+++ openacs-4/packages/acs-core-docs/www/general-documents.html 15 May 2002 23:26:18 -0000 1.6.2.1
@@ -1,60 +1,4 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type">
-<title>Chapter 1. High level information: What is OpenACS?</title>
-<meta name="generator" content="DocBook XSL Stylesheets V1.45">
-<link rel="home" href="index.html" title="OpenACS Documentation">
-<link rel="up" href="for-everyone.html" title="Part Part I. OpenACS For Everyone">
-<link rel="previous" href="for-everyone.html" title="Part Part I. OpenACS For Everyone">
-<link rel="next" href="openacs-overview.html" title="Overview">
-<link rel="stylesheet" href="openacs.css" type="text/css">
-</head>
-<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-<div class="navheader">
-<a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr>
-<td width="20%" align="left">
-<a accesskey="p" href="for-everyone.html">Prev</a> </td>
-<th width="60%" align="center">Part Part I. OpenACS For Everyone</th>
-<td width="20%" align="right"> <a accesskey="n" href="openacs-overview.html">Next</a>
-</td>
-</tr></table>
-<hr>
-</div>
-<div class="chapter">
-<div class="titlepage"><div><h2 class="title">
-<a name="general-documents"></a>Chapter 1. High level information: What is OpenACS?</h2></div></div>
-<div class="toc">
-<p><b>Table of Contents</b></p>
-<dl>
-<dt><a href="openacs-overview.html">Overview</a></dt>
-<dt><a href="release-notes.html">OpenACS 4.5 Release Notes</a></dt>
-</dl>
-</div>
-</div>
-<div class="navfooter">
-<hr>
-<table width="100%" summary="Navigation footer">
-<tr>
-<td width="40%" align="left">
-<a accesskey="p" href="for-everyone.html">Prev</a> </td>
-<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
-<td width="40%" align="right"> <a accesskey="n" href="openacs-overview.html">Next</a>
-</td>
-</tr>
-<tr>
-<td width="40%" align="left">Part Part I. OpenACS For Everyone </td>
-<td width="20%" align="center"><a accesskey="u" href="for-everyone.html">Up</a></td>
-<td width="40%" align="right"> Overview</td>
-</tr>
-</table>
-<hr>
-<address>
- rmello at fslc.usu.edu
- </address>
-<address><a href="mailto:vinod@kurup.com">
+<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"><title>Chapter 1. High level information: What is OpenACS?</title><meta name="generator" content="DocBook XSL Stylesheets V1.50.0"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="for-everyone.html" title="Part Part I. OpenACS For Everyone"><link rel="previous" href="for-everyone.html" title="Part Part I. OpenACS For Everyone"><link rel="next" href="openacs-overview.html" title="Overview"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="for-everyone.html">Prev</a> </td><th width="60%" align="center">Part Part I. OpenACS For Everyone</th><td width="20%" align="right"> <a accesskey="n" href="openacs-overview.html">Next</a></td></tr></table><hr></div><div class="chapter"><div class="titlepage"><div><h2 class="title"><a name="general-documents"></a>Chapter 1. High level information: What is OpenACS?</h2></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a href="openacs-overview.html">Overview</a></dt><dt><a href="release-notes.html">OpenACS 4.5 Release Notes</a></dt></dl></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="for-everyone.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="openacs-overview.html">Next</a></td></tr><tr><td width="40%" align="left">Part Part I. OpenACS For Everyone </td><td width="20%" align="center"><a accesskey="u" href="for-everyone.html">Up</a></td><td width="40%" align="right"> Overview</td></tr></table><hr><address>rmello at fslc.usu.edu</address><address><a href="mailto:vinod@kurup.com">
vinod@kurup.com
- </a></address>
-</div>
-</body>
-</html>
+ </a></address></div></body></html>
Index: openacs-4/packages/acs-core-docs/www/groups-design.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/groups-design.html,v
diff -u -r1.5 -r1.5.2.1
--- openacs-4/packages/acs-core-docs/www/groups-design.html 7 Mar 2002 06:55:36 -0000 1.5
+++ openacs-4/packages/acs-core-docs/www/groups-design.html 15 May 2002 23:26:18 -0000 1.5.2.1
@@ -1,101 +1,32 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type">
-<title>OpenACS 4 Groups Design</title>
-<meta name="generator" content="DocBook XSL Stylesheets V1.45">
-<link rel="home" href="index.html" title="OpenACS Documentation">
-<link rel="up" href="kernel-doc.html" title="Chapter 7. Kernel Documentation">
-<link rel="previous" href="groups-requirements.html" title="OpenACS 4 Groups Requirements">
-<link rel="next" href="subsites-requirements.html" title="OpenACS 4 Subsites Requirements">
-<link rel="stylesheet" href="openacs.css" type="text/css">
-</head>
-<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-<div class="navheader">
-<a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr>
-<td width="20%" align="left">
-<a accesskey="p" href="groups-requirements.html">Prev</a> </td>
-<th width="60%" align="center">Chapter 7. Kernel Documentation</th>
-<td width="20%" align="right"> <a accesskey="n" href="subsites-requirements.html">Next</a>
-</td>
-</tr></table>
-<hr>
-</div>
-<div class="sect1">
-<div class="titlepage"><div><h2 class="title" style="clear: both">
-<a name="groups-design"></a>OpenACS 4 Groups Design</h2></div></div>
-<div class="authorblurb"><p>
-by <a href="http://planitia.org" target="_top">Rafael H. Schloming</a> and <a href="mailto:mthomas@arsdigita.com" target="_top">Mark Thomas</a>
-</p></div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="groups-design-essentials"></a>Essentials</h3></div></div>
-<div class="itemizedlist"><ul>
-<li><p>User directory</p></li>
-<li><p>Sitewide administrator directory</p></li>
-<li><p>Subsite administrator directory</p></li>
-<li><p>TCL script directory</p></li>
-<li><p><a href="groups-requirements.html">OpenACS 4 Groups Requirements</a></p></li>
-<li><p>Data model</p></li>
-<li>
-<p>PL/SQL file </p>
-<div class="itemizedlist"><ul>
-<li><p><a href="/doc/sql/display-sql?url=community-core-create.sql&package_key=acs-kernel" target="_top">
-community-core-create.sql</a></p></li>
-<li><p><a href="/doc/sql/display-sql?url=groups-create.sql&package_key=acs-kernel" target="_top">groups-create.sql</a></p></li>
-</ul></div>
-</li>
-<li><p>ER diagram</p></li>
-<li><p>Transaction flow diagram</p></li>
-</ul></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="groups-design-intro"></a>Introduction</h3></div></div>
-<p>Almost all database-backed websites have users, and need to model the
+<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"><title>OpenACS 4 Groups Design</title><meta name="generator" content="DocBook XSL Stylesheets V1.50.0"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="kernel-doc.html" title="Chapter 7. Kernel Documentation"><link rel="previous" href="groups-requirements.html" title="OpenACS 4 Groups Requirements"><link rel="next" href="subsites-requirements.html" title="OpenACS 4 Subsites Requirements"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="groups-requirements.html">Prev</a> </td><th width="60%" align="center">Chapter 7. Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="subsites-requirements.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="groups-design"></a>OpenACS 4 Groups Design</h2></div></div><div class="authorblurb"><p>
+by <a href="http://planitia.org" target="_top">Rafael H. Schloming</a> and <a href="mailto:mthomas@arsdigita.com" target="_top">Mark Thomas</a><br>
+ OpenACS docs are written by the named authors, but may be edited
+ by OpenACS documentation staff.
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="groups-design-essentials"></a>Essentials</h3></div></div><div class="itemizedlist"><ul type="disc"><li><p>User directory</p></li><li><p>Sitewide administrator directory</p></li><li><p>Subsite administrator directory</p></li><li><p>TCL script directory</p></li><li><p><a href="groups-requirements.html">OpenACS 4 Groups Requirements</a></p></li><li><p>Data model</p></li><li><p>PL/SQL file </p><div class="itemizedlist"><ul type="round"><li><p><a href="/doc/sql/display-sql?url=community-core-create.sql%26amp;package_key=acs-kernel" target="_top">
+community-core-create.sql</a></p></li><li><p><a href="/doc/sql/display-sql?url=groups-create.sql%26amp;package_key=acs-kernel" target="_top">groups-create.sql</a></p></li></ul></div></li><li><p>ER diagram</p></li><li><p>Transaction flow diagram</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="groups-design-intro"></a>Introduction</h3></div></div><p>Almost all database-backed websites have users, and need to model the
grouping of users. The OpenACS 4 Parties and Groups system is intended to provide
the flexibility needed to model complex real-world organizational structures,
particularly to support powerful subsite services; that is, where one OpenACS
installation can support what appears to the user as distinct web services
-for different user communities.</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="groups-design-hist-considerations"></a>Historical Considerations</h3></div></div>
-<p>The primary limitation of the OpenACS 3.x user group system is that it
+for different user communities.</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="groups-design-hist-considerations"></a>Historical Considerations</h3></div></div><p>The primary limitation of the OpenACS 3.x user group system is that it
restricts the application developer to representing a "flat group"
that contains only users: The <tt>user_groups</tt> table may contain the
<tt>group_id</tt> of a parent group, but parent-child relationship
support is limited because it only allows one kind of relationship between
groups to be represented. Moreover, the Oracle database's limited support
for tree-like structures makes the queries over these relationships
-expensive.</p>
-<p>In addition, the Module Scoping design in OpenACS 3.0 introduced a
-<span class="emphasis"><i>party</i></span> abstraction - a thing that is a person or a group of people -
+expensive.</p><p>In addition, the Module Scoping design in OpenACS 3.0 introduced a
+<span class="emphasis"><em>party</em></span> abstraction - a thing that is a person or a group of people -
though not in the form of an explicit table. Rather, the triple of
<tt>scope</tt>, <tt>user_id</tt>, and <tt>group_id</tt> columns
was used to identify the party. One disadvantage of this design convention is
that it increases a data model's complexity by requiring the programmer
-to:</p>
-<div class="itemizedlist"><ul>
-<li><p>add these three columns to each "scoped" table</p></li>
-<li><p>define a multi-column check constraint to protect against data corruption
+to:</p><div class="itemizedlist"><ul type="disc"><li><p>add these three columns to each "scoped" table</p></li><li><p>define a multi-column check constraint to protect against data corruption
(e.g., a row with a <tt>scope</tt> value of "group" but a null
-<tt>group_id</tt>)</p></li>
-<li><p>perform extra checks in <tt>Tcl</tt> and <tt>PL/SQL</tt>
+<tt>group_id</tt>)</p></li><li><p>perform extra checks in <tt>Tcl</tt> and <tt>PL/SQL</tt>
functions and procedures to check both the <tt>user_id</tt> and
-<tt>group_id</tt> values</p></li>
-</ul></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="groups-design-competitors"></a>Competitive Analysis</h3></div></div>
-<p>...</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="groups-design-design-tradeoffs"></a>Design Tradeoffs</h3></div></div>
-<p>The core of the Group Systems data model is quite simple, but it was
+<tt>group_id</tt> values</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="groups-design-competitors"></a>Competitive Analysis</h3></div></div><p>...</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="groups-design-design-tradeoffs"></a>Design Tradeoffs</h3></div></div><p>The core of the Group Systems data model is quite simple, but it was
designed in the hopes of modeling "real world" organizations which
can be complex graph structures. The Groups System only considers groups that
can be modeled using directed acyclic graphs, but queries over these
@@ -104,78 +35,48 @@
views, and auxiliary tables have been created in the hopes of increasing
performance. To keep the triggers simple and the number of triggers small,
the data model disallows updates on the membership and composition tables,
-only inserts and deletes are permitted.</p>
-<p>The data model has tried to balance the need to model actual organizations
+only inserts and deletes are permitted.</p><p>The data model has tried to balance the need to model actual organizations
without making the system too complex or too slow. The added triggers, views,
and tables and will increase storage requirements and the insert and delete
times in an effort to speed access time. The limited flexibility (no updates
-on membership) trades against the complexity of the code.</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="groups-design-data-model"></a>Data Model Discussion</h3></div></div>
-<p>The Group System data model consists of the following tables:</p>
-<div class="variablelist"><dl>
-<dt><span class="term"><tt>parties</tt>
+on membership) trades against the complexity of the code.</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="groups-design-data-model"></a>Data Model Discussion</h3></div></div><p>The Group System data model consists of the following tables:</p><div class="variablelist"><dl><dt><span class="term"><tt>parties</tt>
-</span></dt>
-<dd><p>The set of all defined parties: any <span class="emphasis"><i>person</i></span>, <span class="emphasis"><i>user</i></span>, or
-<span class="emphasis"><i>group</i></span> must have a corresponding row in this table.</p></dd>
-<dt><span class="term"><tt>persons</tt>
+</span></dt><dd><p>The set of all defined parties: any <span class="emphasis"><em>person</em></span>, <span class="emphasis"><em>user</em></span>, or
+<span class="emphasis"><em>group</em></span> must have a corresponding row in this table.</p></dd><dt><span class="term"><tt>persons</tt>
-</span></dt>
-<dd><p>The set of all defined persons. To allow easy sorting of persons, the
+</span></dt><dd><p>The set of all defined persons. To allow easy sorting of persons, the
name requirement <a href="groups-requirements.html#groups-requirements-30-10">30.10</a> is met by
splitting the person's name into two columns: <tt>first_names</tt> and
-<tt>last_name</tt>.</p></dd>
-<dt><span class="term"><tt>users</tt>
+<tt>last_name</tt>.</p></dd><dt><span class="term"><tt>users</tt>
-</span></dt>
-<dd><p>The set of all registered users; this table includes information about
-the user's email address and the user's visits to the site.</p></dd>
-<dt><span class="term"><tt>user_preferences</tt>
+</span></dt><dd><p>The set of all registered users; this table includes information about
+the user's email address and the user's visits to the site.</p></dd><dt><span class="term"><tt>user_preferences</tt>
-</span></dt>
-<dd><p>Preferences for the user.</p></dd>
-<dt><span class="term"><tt>groups</tt>
+</span></dt><dd><p>Preferences for the user.</p></dd><dt><span class="term"><tt>groups</tt>
-</span></dt>
-<dd><p>The set of all defined groups.</p></dd>
-<dt><span class="term"><tt>group_types</tt>
+</span></dt><dd><p>The set of all defined groups.</p></dd><dt><span class="term"><tt>group_types</tt>
-</span></dt>
-<dd><p>When a new type of group is created, this table holds additional
-knowledge level attributes for the group and its subtypes.</p></dd>
-<dt><span class="term"><tt>membership_rels</tt>
+</span></dt><dd><p>When a new type of group is created, this table holds additional
+knowledge level attributes for the group and its subtypes.</p></dd><dt><span class="term"><tt>membership_rels</tt>
-</span></dt>
-<dd><p>The set of direct membership relationships between a group and a
-party.</p></dd>
-<dt><span class="term"><tt>group_member_index</tt>
+</span></dt><dd><p>The set of direct membership relationships between a group and a
+party.</p></dd><dt><span class="term"><tt>group_member_index</tt>
-</span></dt>
-<dd><p>A mapping of a party <span class="strong"><i>P</i></span> to the groups
-{<span class="strong"><i>G<sub>i</sub></i></span>}the party is a member of; this mapping
+</span></dt><dd><p>A mapping of a party <span class="strong"><em>P</em></span> to the groups
+{<span class="strong"><em>G<sub>i</sub></em></span>}the party is a member of; this mapping
includes the type of relationship by including the appropriate<tt>rel_id</tt>
-from the <tt>membership_rels</tt> table.</p></dd>
-<dt><span class="term"><tt>composition_rels</tt>
+from the <tt>membership_rels</tt> table.</p></dd><dt><span class="term"><tt>composition_rels</tt>
-</span></dt>
-<dd><p>The set of direct component relationships between a group and another
-group.</p></dd>
-<dt><span class="term"><tt>group_component_index</tt>
+</span></dt><dd><p>The set of direct component relationships between a group and another
+group.</p></dd><dt><span class="term"><tt>group_component_index</tt>
-</span></dt>
-<dd><p>A mapping of a group <span class="strong"><i>G</i></span>to the set of groups
-{<span class="strong"><i>G<sub>i</sub></i></span>} that <span class="strong"><i>G</i></span> is a component of;
+</span></dt><dd><p>A mapping of a group <span class="strong"><em>G</em></span>to the set of groups
+{<span class="strong"><em>G<sub>i</sub></em></span>} that <span class="strong"><em>G</em></span> is a component of;
this mapping includes the type of relationship by including the
-appropriate<tt>rel_id</tt> from the <tt>composition_rels</tt> table.</p></dd>
-</dl></div>
-<p>New groups are created through the <tt>group.new</tt> constructor.
+appropriate<tt>rel_id</tt> from the <tt>composition_rels</tt> table.</p></dd></dl></div><p>New groups are created through the <tt>group.new</tt> constructor.
When a specialized type of group is required, the group type can be extended
by an application developer. Membership constraints can be specified at
-creation time by passing a parent group to the constructor.</p>
-<p>The <tt>membership_rels</tt> and <tt>composition_rels</tt> tables indicate
+creation time by passing a parent group to the constructor.</p><p>The <tt>membership_rels</tt> and <tt>composition_rels</tt> tables indicate
a group's direct members and direct components; these tables do not
provide a record of the members or components that are in the group by virtue
of being a member or component of one of the group's component groups.
@@ -186,104 +87,60 @@
paragraph) which watch for changes in membership or composition and update
tables that maintain the group party mappings, i.e.,
<tt>group_member_index</tt> and <tt>group_component_index</tt>. One can think
-of these tables as a manually maintained index.</p>
-<p>The following triggers keep the <tt>group_*_index</tt> tables up to
-date:</p>
-<div class="variablelist"><dl>
-<dt><span class="term"><tt>membership_rels_in_tr</tt>
+of these tables as a manually maintained index.</p><p>The following triggers keep the <tt>group_*_index</tt> tables up to
+date:</p><div class="variablelist"><dl><dt><span class="term"><tt>membership_rels_in_tr</tt>
-</span></dt>
-<dd><p>Is executed when a new group/member relationship is created (an insert on
-<tt>membership_rels</tt>)</p></dd>
-<dt><span class="term"><tt>membership_rels_del_tr</tt>
+</span></dt><dd><p>Is executed when a new group/member relationship is created (an insert on
+<tt>membership_rels</tt>)</p></dd><dt><span class="term"><tt>membership_rels_del_tr</tt>
-</span></dt>
-<dd><p>Is executed when a group/member relationship is deleted (a delete on
-<tt>membership_rels</tt>)</p></dd>
-<dt><span class="term"><tt>composition_rels_in_tr</tt>
+</span></dt><dd><p>Is executed when a group/member relationship is deleted (a delete on
+<tt>membership_rels</tt>)</p></dd><dt><span class="term"><tt>composition_rels_in_tr</tt>
-</span></dt>
-<dd><p>Is executed when a new group/component relationship is created (an insert
-on <tt>composition_rels</tt>)</p></dd>
-<dt><span class="term"><tt>composition_rels_del_tr</tt>
+</span></dt><dd><p>Is executed when a new group/component relationship is created (an insert
+on <tt>composition_rels</tt>)</p></dd><dt><span class="term"><tt>composition_rels_del_tr</tt>
-</span></dt>
-<dd><p>Is executed when a group/component relationship is deleted (a delete on
-<tt>composition_rels</tt>)</p></dd>
-</dl></div>
-<p>The data model provides the following views onto the
+</span></dt><dd><p>Is executed when a group/component relationship is deleted (a delete on
+<tt>composition_rels</tt>)</p></dd></dl></div><p>The data model provides the following views onto the
<tt>group_member_index</tt> and <tt>group_component_index</tt> tables. No
code outside of Groups System should modify the <tt>group_*_index</tt>
-tables.</p>
-<div class="variablelist"><dl>
-<dt><span class="term"><tt>group_member_map</tt>
+tables.</p><div class="variablelist"><dl><dt><span class="term"><tt>group_member_map</tt>
-</span></dt>
-<dd><p>A mapping of a party to the groups the party is a member of; this mapping
+</span></dt><dd><p>A mapping of a party to the groups the party is a member of; this mapping
includes the type of relationship by including the appropriate<tt>rel_id</tt>
-from the <tt>membership_rels</tt> table.</p></dd>
-<dt><span class="term"><tt>group_approved_member_map</tt>
+from the <tt>membership_rels</tt> table.</p></dd><dt><span class="term"><tt>group_approved_member_map</tt>
-</span></dt>
-<dd><p>A mapping of a party to the groups the party is an approved member of
+</span></dt><dd><p>A mapping of a party to the groups the party is an approved member of
(<tt>member_state</tt> is 'approved'); this mapping includes the type
of relationship by including the appropriate<tt>rel_id</tt> from the
-<tt>membership_rels</tt> table.</p></dd>
-<dt><span class="term"><tt>group_distinct_member_map</tt>
+<tt>membership_rels</tt> table.</p></dd><dt><span class="term"><tt>group_distinct_member_map</tt>
-</span></dt>
-<dd><p>A person may appear in the group member map multiple times, for example,
+</span></dt><dd><p>A person may appear in the group member map multiple times, for example,
by being a member of two different groups that are both components of a third
-group. This view is strictly a mapping of <span class="strong"><i>approved</i></span> members
-to groups.</p></dd>
-<dt><span class="term"><tt>group_component_map</tt>
+group. This view is strictly a mapping of <span class="strong"><em>approved</em></span> members
+to groups.</p></dd><dt><span class="term"><tt>group_component_map</tt>
-</span></dt>
-<dd><p>A mapping of a group <span class="strong"><i>G</i></span>to the set of groups
-{<span class="strong"><i>G<sub>i</sub></i></span>} group <span class="strong"><i>G</i></span> is a component of;
+</span></dt><dd><p>A mapping of a group <span class="strong"><em>G</em></span>to the set of groups
+{<span class="strong"><em>G<sub>i</sub></em></span>} group <span class="strong"><em>G</em></span> is a component of;
this mapping includes the type of relationship by including the
-appropriate<tt>rel_id</tt> from the <tt>composition_rels</tt> table.</p></dd>
-<dt><span class="term"><tt>party_member_map</tt>
+appropriate<tt>rel_id</tt> from the <tt>composition_rels</tt> table.</p></dd><dt><span class="term"><tt>party_member_map</tt>
-</span></dt>
-<dd><p>A mapping of a party <span class="strong"><i>P</i></span> to the set of parties
-{<span class="strong"><i>P<sub>i</sub></i></span>} party <span class="strong"><i>P</i></span> is a member
-of.</p></dd>
-<dt><span class="term"><tt>party_approved_member_map</tt>
+</span></dt><dd><p>A mapping of a party <span class="strong"><em>P</em></span> to the set of parties
+{<span class="strong"><em>P<sub>i</sub></em></span>} party <span class="strong"><em>P</em></span> is a member
+of.</p></dd><dt><span class="term"><tt>party_approved_member_map</tt>
-</span></dt>
-<dd><p>A mapping of a party <span class="strong"><i>P</i></span> to the set of parties
-{<span class="strong"><i>P<sub>i</sub></i></span>} party <span class="strong"><i>P</i></span> is an
-<span class="strong"><i>approved</i></span> member of.</p></dd>
-</dl></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="groups-design-api"></a>API</h3></div></div>
-<p>
+</span></dt><dd><p>A mapping of a party <span class="strong"><em>P</em></span> to the set of parties
+{<span class="strong"><em>P<sub>i</sub></em></span>} party <span class="strong"><em>P</em></span> is an
+<span class="strong"><em>approved</em></span> member of.</p></dd></dl></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="groups-design-api"></a>API</h3></div></div><p>
The API consists of tables and views and PL/SQL functions.
-</p>
-<div class="sect3">
-<div class="titlepage"><div><h4 class="title">
-<a name="groups-design-tables-views"></a>Tables and Views</h4></div></div>
-<p>The <tt>group_types</tt> table is used to create new types of groups.</p>
-<p>The <tt>group_member_map</tt>, <tt>group_approved_member_map</tt>,
+</p><div class="sect3"><div class="titlepage"><div><h4 class="title"><a name="groups-design-tables-views"></a>Tables and Views</h4></div></div><p>The <tt>group_types</tt> table is used to create new types of groups.</p><p>The <tt>group_member_map</tt>, <tt>group_approved_member_map</tt>,
<tt>group_distinct_member_map</tt>, <tt>group_component_map</tt>,
<tt>party_member_map</tt>, and <tt>party_approved_member_map</tt> views are
-used to query group membership and composition.</p>
-</div>
-<div class="sect3">
-<div class="titlepage"><div><h4 class="title">
-<a name="groups-design-pl-sql-api"></a>PL/SQL API</h4></div></div>
-<p><span class="strong"><i>Person</i></span></p>
-<p>
-<tt>person.new</tt> creates a new person and returns the
+used to query group membership and composition.</p></div><div class="sect3"><div class="titlepage"><div><h4 class="title"><a name="groups-design-pl-sql-api"></a>PL/SQL API</h4></div></div><p><span class="strong"><em>Person</em></span></p><p><tt>person.new</tt> creates a new person and returns the
<tt>person_id</tt>. The function must be given the full name of the person in
two pieces: <tt>first_names</tt> and <tt>last_name</tt>. All other fields are
optional and default to null except for <tt>object_type</tt> which defaults
to person and <tt>creation_date</tt> which defaults to <tt>sysdate</tt>. The
-interface for this function is:</p>
-<pre class="programlisting">
+interface for this function is:</p><pre class="programlisting">
function person.new (
person_id persons.person_id%TYPE,
object_type acs_objects.object_type%TYPE,
@@ -295,30 +152,20 @@
first_names persons.first_names%TYPE,
last_name persons.last_name%TYPE
) return persons.person_id%TYPE;
-</pre>
-<p>
-<tt>person.delete</tt> deletes the person whose <tt>person_id</tt> is
-passed to it. The interface for this procedure is:</p>
-<pre class="programlisting">
+</pre><p><tt>person.delete</tt> deletes the person whose <tt>person_id</tt> is
+passed to it. The interface for this procedure is:</p><pre class="programlisting">
procedure person.delete (
person_id persons.person_id%TYPE
);
-</pre>
-<p>
-<tt>person.name</tt> returns the name of the person whose
-<tt>person_id</tt> is passed to it. The interface for this function is:</p>
-<pre class="programlisting">
+</pre><p><tt>person.name</tt> returns the name of the person whose
+<tt>person_id</tt> is passed to it. The interface for this function is:</p><pre class="programlisting">
function person.name (
person_id persons.person_id%TYPE
) return varchar;
-</pre>
-<p><span class="strong"><i>User</i></span></p>
-<p>
-<tt>acs_user.new</tt> creates a new user and returns the <tt>user_id</tt>.
+</pre><p><span class="strong"><em>User</em></span></p><p><tt>acs_user.new</tt> creates a new user and returns the <tt>user_id</tt>.
The function must be given the user's email address and the full name of
the user in two pieces: <tt>first_names</tt> and <tt>last_name</tt>. All
-other fields are optional. The interface for this function is:</p>
-<pre class="programlisting">
+other fields are optional. The interface for this function is:</p><pre class="programlisting">
function acs_user.new (
user_id users.user_id%TYPE,
object_type acs_objects.object_type%TYPE,
@@ -336,45 +183,33 @@
screen_name users.screen_name%TYPE,
email_verified_p users.email_verified_p%TYPE
) return users.user_id%TYPE;
-</pre>
-<p>
-<tt>acs_user.delete</tt> deletes the user whose <tt>user_id</tt> is passed
-to it. The interface for this procedure is:</p>
-<pre class="programlisting">
+</pre><p><tt>acs_user.delete</tt> deletes the user whose <tt>user_id</tt> is passed
+to it. The interface for this procedure is:</p><pre class="programlisting">
procedure acs_user.delete (
user_id users.user_id%TYPE
);
-</pre>
-<p>
-<tt>acs_user.receives_alerts_p</tt> returns 't' if the user should
+</pre><p><tt>acs_user.receives_alerts_p</tt> returns 't' if the user should
receive email alerts and 'f' otherwise. The interface for this
-function is:</p>
-<pre class="programlisting">
+function is:</p><pre class="programlisting">
function acs_user.receives_alerts_p (
user_id users.user_id%TYPE
) return varchar;
-</pre>
-<p>Use the procedures <tt>acs_user.approve_email</tt> and
+</pre><p>Use the procedures <tt>acs_user.approve_email</tt> and
<tt>acs_user.unapprove_email</tt> to specify whether the user's email
-address is valid. The interface for these procedures are:</p>
-<pre class="programlisting">
+address is valid. The interface for these procedures are:</p><pre class="programlisting">
procedure acs_user.approve_email (
user_id users.user_id%TYPE
);
procedure acs_user.unapprove_email (
user_id users.user_id%TYPE
);
-</pre>
-<p><span class="strong"><i>Group</i></span></p>
-<p>
-<tt>acs_group.new</tt> creates a new group and returns the
+</pre><p><span class="strong"><em>Group</em></span></p><p><tt>acs_group.new</tt> creates a new group and returns the
<tt>group_id</tt>. All fields are optional and default to null except for
<tt>object_type</tt> which defaults to 'group',
<tt>creation_date</tt> which defaults to <tt>sysdate</tt>, and
<tt>group_name</tt> which is required. The interface for
-this function is:</p>
-<pre class="programlisting">
+this function is:</p><pre class="programlisting">
function acs_group.new (
group_id groups.group_id%TYPE,
object_type acs_objects.object_type%TYPE,
@@ -385,32 +220,22 @@
url parties.url%TYPE,
group_name groups.group_name%TYPE
) return groups.group_id%TYPE;
-</pre>
-<p>
-<tt>acs_group.name</tt> returns the name of the group whose
-<tt>group_id</tt> is passed to it. The interface for this function is:</p>
-<pre class="programlisting">
+</pre><p><tt>acs_group.name</tt> returns the name of the group whose
+<tt>group_id</tt> is passed to it. The interface for this function is:</p><pre class="programlisting">
function acs_group.name (
group_id groups.group_id%TYPE
) return varchar;
-</pre>
-<p>
-<tt>acs_group.member_p</tt> returns 't' if the specified party is
+</pre><p><tt>acs_group.member_p</tt> returns 't' if the specified party is
a member of the specified group. Returns 'f' otherwise. The interface
-for this function is:</p>
-<pre class="programlisting">
+for this function is:</p><pre class="programlisting">
function acs_group.member_p (
group_id groups.group_id%TYPE,
party_id parties.party_id%TYPE,
) return char;
-</pre>
-<p><span class="strong"><i>Membership Relationship</i></span></p>
-<p>
-<tt>membership_rel.new</tt> creates a new membership relationship type
+</pre><p><span class="strong"><em>Membership Relationship</em></span></p><p><tt>membership_rel.new</tt> creates a new membership relationship type
between two parties and returns the relationship type's <tt>rel_id</tt>.
All fields are optional and default to null except for <tt>rel_type</tt>
-which defaults to membership_rel. The interface for this function is:</p>
-<pre class="programlisting">
+which defaults to membership_rel. The interface for this function is:</p><pre class="programlisting">
function membership_rel.new (
rel_id membership_rels.rel_id%TYPE,
rel_type acs_rels.rel_type%TYPE,
@@ -420,65 +245,43 @@
creation_user acs_objects.creation_user%TYPE,
creation_ip acs_objects.creation_ip%TYPE,
) return membership_rels.rel_id%TYPE;
-</pre>
-<p>
-<tt>membership_rel.ban</tt> sets the <tt>member_state</tt> of the given
-<tt>rel_id</tt> to 'banned'. The interface for this procedure is:</p>
-<pre class="programlisting">
+</pre><p><tt>membership_rel.ban</tt> sets the <tt>member_state</tt> of the given
+<tt>rel_id</tt> to 'banned'. The interface for this procedure is:</p><pre class="programlisting">
procedure membership_rel.ban (
rel_id membership_rels.rel_id%TYPE
);
-</pre>
-<p>
-<tt>membership_rel.approve</tt> sets the <tt>member_state</tt> of the
+</pre><p><tt>membership_rel.approve</tt> sets the <tt>member_state</tt> of the
given <tt>rel_id</tt> to 'approved'. The interface for this procedure
-is:</p>
-<pre class="programlisting">
+is:</p><pre class="programlisting">
procedure membership_rel.approve (
rel_id membership_rels.rel_id%TYPE
);
-</pre>
-<p>
-<tt>membership_rel.reject</tt> sets the <tt>member_state</tt> of the given
-<tt>rel_id</tt> to 'rejected. The interface for this procedure is:</p>
-<pre class="programlisting">
+</pre><p><tt>membership_rel.reject</tt> sets the <tt>member_state</tt> of the given
+<tt>rel_id</tt> to 'rejected. The interface for this procedure is:</p><pre class="programlisting">
procedure membership_rel.reject (
rel_id membership_rels.rel_id%TYPE
);
-</pre>
-<p>
-<tt>membership_rel.unapprove</tt> sets the <tt>member_state</tt> of the
+</pre><p><tt>membership_rel.unapprove</tt> sets the <tt>member_state</tt> of the
given <tt>rel_id</tt> to an empty string ''. The interface for this
-procedure is:</p>
-<pre class="programlisting">
+procedure is:</p><pre class="programlisting">
procedure membership_rel.unapprove (
rel_id membership_rels.rel_id%TYPE
);
-</pre>
-<p>
-<tt>membership_rel.deleted</tt> sets the <tt>member_state</tt> of the
+</pre><p><tt>membership_rel.deleted</tt> sets the <tt>member_state</tt> of the
given <tt>rel_id</tt> to 'deleted'. The interface for this procedure
-is:</p>
-<pre class="programlisting">
+is:</p><pre class="programlisting">
procedure membership_rel.deleted (
rel_id membership_rels.rel_id%TYPE
);
-</pre>
-<p>
-<tt>membership_rel.delete</tt> deletes the given <tt>rel_id</tt>. The
-interface for this procedure is:</p>
-<pre class="programlisting">
+</pre><p><tt>membership_rel.delete</tt> deletes the given <tt>rel_id</tt>. The
+interface for this procedure is:</p><pre class="programlisting">
procedure membership_rel.delete (
rel_id membership_rels.rel_id%TYPE
);
-</pre>
-<p><span class="strong"><i>Composition Relationship</i></span></p>
-<p>
-<tt>composition_rel.new</tt> creates a new composition relationship type
+</pre><p><span class="strong"><em>Composition Relationship</em></span></p><p><tt>composition_rel.new</tt> creates a new composition relationship type
and returns the relationship's <tt>rel_id</tt>. All fields are optional
and default to null except for <tt>rel_type</tt> which defaults to
-composition_rel. The interface for this function is:</p>
-<pre class="programlisting">
+composition_rel. The interface for this function is:</p><pre class="programlisting">
function membership_rel.new (
rel_id composition_rels.rel_id%TYPE,
rel_type acs_rels.rel_type%TYPE,
@@ -487,117 +290,17 @@
creation_user acs_objects.creation_user%TYPE,
creation_ip acs_objects.creation_ip%TYPE,
) return composition_rels.rel_id%TYPE;
-</pre>
-<p>
-<tt>composition_rel.delete</tt> deletes the given <tt>rel_id</tt>. The
-interface for this procedure is:</p>
-<pre class="programlisting">
+</pre><p><tt>composition_rel.delete</tt> deletes the given <tt>rel_id</tt>. The
+interface for this procedure is:</p><pre class="programlisting">
procedure membership_rel.delete (
rel_id composition_rels.rel_id%TYPE
);
-</pre>
-</div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="groups-design-ui"></a>User Interface</h3></div></div>
-<p>Describe the admin pages.</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="groups-design-config"></a>Configuration/Parameters</h3></div></div>
-<p>...</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="groups-design-acc-tests"></a>Acceptance Tests</h3></div></div>
-<p>...</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="groups-design-future"></a>Future Improvements/Areas of Likely Change</h3></div></div>
-<p>...</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="groups-design-authors"></a>Authors</h3></div></div>
-<div class="variablelist"><dl>
-<dt><span class="term">System creator
+</pre></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="groups-design-ui"></a>User Interface</h3></div></div><p>Describe the admin pages.</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="groups-design-config"></a>Configuration/Parameters</h3></div></div><p>...</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="groups-design-acc-tests"></a>Acceptance Tests</h3></div></div><p>...</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="groups-design-future"></a>Future Improvements/Areas of Likely Change</h3></div></div><p>...</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="groups-design-authors"></a>Authors</h3></div></div><div class="variablelist"><dl><dt><span class="term">System creator
-</span></dt>
-<dd><p><a href="mailto:rhs@mit.edu" target="_top">Rafael H. Schloming</a></p></dd>
-<dt><span class="term">System owner
+</span></dt><dd><p><a href="mailto:rhs@mit.edu" target="_top">Rafael H. Schloming</a></p></dd><dt><span class="term">System owner
-</span></dt>
-<dd><p><a href="mailto:rhs@mit.edu" target="_top">Rafael H. Schloming</a></p></dd>
-<dt><span class="term">Documentation author
+</span></dt><dd><p><a href="mailto:rhs@mit.edu" target="_top">Rafael H. Schloming</a></p></dd><dt><span class="term">Documentation author
-</span></dt>
-<dd><p><a href="mailto:mthomas@arsdigita.com" target="_top">Mark Thomas</a></p></dd>
-</dl></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="groups-design-rev-history"></a>Revision History</h3></div></div>
-<div class="informaltable"><table border="1">
-<colgroup>
-<col>
-<col>
-<col>
-<col>
-</colgroup>
-<tbody>
-<tr>
-<td><span class="strong"><i>Document Revision #</i></span></td>
-<td><span class="strong"><i>Action Taken, Notes</i></span></td>
-<td><span class="strong"><i>When?</i></span></td>
-<td><span class="strong"><i>By Whom?</i></span></td>
-</tr>
-<tr>
-<td>0.1</td>
-<td>Creation</td>
-<td>08/22/2000</td>
-<td><a href="mailto:rhs@mit.edu" target="_top">Rafael H. Schloming</a></td>
-</tr>
-<tr>
-<td>0.2</td>
-<td>Initial Revision</td>
-<td>08/30/2000</td>
-<td><a href="mailto:mthomas@arsdigita.com" target="_top">Mark Thomas</a></td>
-</tr>
-<tr>
-<td>0.3</td>
-<td>Additional revisions; tried to clarify membership/compostion</td>
-<td>09/08/2000</td>
-<td><a href="mailto:mthomas@arsdigita.com" target="_top">Mark Thomas</a></td>
-</tr>
-</tbody>
-</table></div>
-</div>
-</div>
-<div class="navfooter">
-<hr>
-<table width="100%" summary="Navigation footer">
-<tr>
-<td width="40%" align="left">
-<a accesskey="p" href="groups-requirements.html">Prev</a> </td>
-<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
-<td width="40%" align="right"> <a accesskey="n" href="subsites-requirements.html">Next</a>
-</td>
-</tr>
-<tr>
-<td width="40%" align="left">OpenACS 4 Groups Requirements </td>
-<td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td>
-<td width="40%" align="right"> OpenACS 4 Subsites Requirements</td>
-</tr>
-</table>
-<hr>
-<address>
- rmello at fslc.usu.edu
- </address>
-<address><a href="mailto:vinod@kurup.com">
+</span></dt><dd><p><a href="mailto:mthomas@arsdigita.com" target="_top">Mark Thomas</a></p></dd></dl></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="groups-design-rev-history"></a>Revision History</h3></div></div><div class="informaltable"><table border="1"><colgroup><col><col><col><col></colgroup><tbody><tr><td><span class="strong"><em>Document Revision #</em></span></td><td><span class="strong"><em>Action Taken, Notes</em></span></td><td><span class="strong"><em>When?</em></span></td><td><span class="strong"><em>By Whom?</em></span></td></tr><tr><td>0.1</td><td>Creation</td><td>08/22/2000</td><td><a href="mailto:rhs@mit.edu" target="_top">Rafael H. Schloming</a></td></tr><tr><td>0.2</td><td>Initial Revision</td><td>08/30/2000</td><td><a href="mailto:mthomas@arsdigita.com" target="_top">Mark Thomas</a></td></tr><tr><td>0.3</td><td>Additional revisions; tried to clarify membership/compostion</td><td>09/08/2000</td><td><a href="mailto:mthomas@arsdigita.com" target="_top">Mark Thomas</a></td></tr></tbody></table></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="groups-requirements.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="subsites-requirements.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS 4 Groups Requirements </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> OpenACS 4 Subsites Requirements</td></tr></table><hr><address>rmello at fslc.usu.edu</address><address><a href="mailto:vinod@kurup.com">
vinod@kurup.com
- </a></address>
-</div>
-</body>
-</html>
+ </a></address></div></body></html>
Index: openacs-4/packages/acs-core-docs/www/groups-requirements.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/groups-requirements.html,v
diff -u -r1.5 -r1.5.2.1
--- openacs-4/packages/acs-core-docs/www/groups-requirements.html 7 Mar 2002 06:55:36 -0000 1.5
+++ openacs-4/packages/acs-core-docs/www/groups-requirements.html 15 May 2002 23:26:18 -0000 1.5.2.1
@@ -1,546 +1,227 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type">
-<title>OpenACS 4 Groups Requirements</title>
-<meta name="generator" content="DocBook XSL Stylesheets V1.45">
-<link rel="home" href="index.html" title="OpenACS Documentation">
-<link rel="up" href="kernel-doc.html" title="Chapter 7. Kernel Documentation">
-<link rel="previous" href="permissions-design.html" title="OpenACS 4 Permissions Design">
-<link rel="next" href="groups-design.html" title="OpenACS 4 Groups Design">
-<link rel="stylesheet" href="openacs.css" type="text/css">
-</head>
-<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-<div class="navheader">
-<a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr>
-<td width="20%" align="left">
-<a accesskey="p" href="permissions-design.html">Prev</a> </td>
-<th width="60%" align="center">Chapter 7. Kernel Documentation</th>
-<td width="20%" align="right"> <a accesskey="n" href="groups-design.html">Next</a>
-</td>
-</tr></table>
-<hr>
-</div>
-<div class="sect1">
-<div class="titlepage"><div><h2 class="title" style="clear: both">
-<a name="groups-requirements"></a>OpenACS 4 Groups Requirements</h2></div></div>
-<div class="authorblurb"><p>
-by <a href="http://planitia.org" target="_top">Rafael H. Schloming</a>, <a href="mailto:mthomas@arsdigita.com" target="_top">Mark Thomas</a>
-</p></div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="groups-requirements-intro"></a>Introduction</h3></div></div>
-<p>Almost all database-backed websites have users, and need to model the
+<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"><title>OpenACS 4 Groups Requirements</title><meta name="generator" content="DocBook XSL Stylesheets V1.50.0"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="kernel-doc.html" title="Chapter 7. Kernel Documentation"><link rel="previous" href="permissions-design.html" title="OpenACS 4 Permissions Design"><link rel="next" href="groups-design.html" title="OpenACS 4 Groups Design"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="permissions-design.html">Prev</a> </td><th width="60%" align="center">Chapter 7. Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="groups-design.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="groups-requirements"></a>OpenACS 4 Groups Requirements</h2></div></div><div class="authorblurb"><p>
+by <a href="http://planitia.org" target="_top">Rafael H. Schloming</a>, <a href="mailto:mthomas@arsdigita.com" target="_top">Mark Thomas</a><br>
+ OpenACS docs are written by the named authors, but may be edited
+ by OpenACS documentation staff.
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="groups-requirements-intro"></a>Introduction</h3></div></div><p>Almost all database-backed websites have users, and need to model the
grouping of users. The OpenACS 4 Parties and Groups system is intended to provide
the flexibility needed to model complex real-world organizational structures,
particularly to support powerful subsite services; that is, where one OpenACS
installation can support what appears to the user as distinct web services
-for different user communities.</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="groups-requirements-vision"></a>Vision Statement</h3></div></div>
-<p>A powerful web service that can meet the needs of large enterprises must
+for different user communities.</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="groups-requirements-vision"></a>Vision Statement</h3></div></div><p>A powerful web service that can meet the needs of large enterprises must
be able to model the the real world's very rich organizational structures
and many ways of decomposing the same organization. For example, a
corporation can be broken into structures (the corporation, its divisions,
and their departments) or regions (the Boston office, the LA office); a
person who is employed by (is a member of) a specific department is also a
member of the division and the corporation, and works at (is a member of, but
in a different sense) a particular office. OpenACS 4's Parties and Groups
-system will support such complex relations faithfully.</p>
-<p><span class="strong"><i>Historical Motivations</i></span></p>
-<p>The primary limitation of the OpenACS 3.x user group system is that it
+system will support such complex relations faithfully.</p><p><span class="strong"><em>Historical Motivations</em></span></p><p>The primary limitation of the OpenACS 3.x user group system is that it
restricts the application developer to representing a "flat group"
that contains only users: The <tt>user_groups</tt> table may contain the
<tt>group_id</tt> of a parent group, but parent-child relationship
support is limited because it only allows one kind of relationship between
groups to be represented. Moreover, the Oracle database's limited support
for tree-like structures makes the queries over these relationships
-expensive.</p>
-<p>In addition, the Module Scoping design in OpenACS 3.0 introduced a
-<span class="emphasis"><i>party</i></span> abstraction - a thing that is a person or a group of people -
+expensive.</p><p>In addition, the Module Scoping design in OpenACS 3.0 introduced a
+<span class="emphasis"><em>party</em></span> abstraction - a thing that is a person or a group of people -
though not in the form of an explicit table. Rather, the triple of
<tt>scope</tt>, <tt>user_id</tt>, and <tt>group_id</tt> columns
was used to identify the party. One disadvantage of this design convention is
that it increases a data model's complexity by requiring the programmer
-to:</p>
-<div class="itemizedlist"><ul>
-<li><p>add these three columns to each "scoped" table</p></li>
-<li><p>define a multi-column check constraint to protect against data corruption
+to:</p><div class="itemizedlist"><ul type="disc"><li><p>add these three columns to each "scoped" table</p></li><li><p>define a multi-column check constraint to protect against data corruption
(e.g., a row with a <tt>scope</tt> value of "group" but a null
-<tt>group_id</tt>)</p></li>
-<li><p>perform extra checks in <tt>Tcl</tt> and <tt>PL/SQL</tt>
+<tt>group_id</tt>)</p></li><li><p>perform extra checks in <tt>Tcl</tt> and <tt>PL/SQL</tt>
functions and procedures to check both the <tt>user_id</tt> and
-<tt>group_id</tt> values</p></li>
-</ul></div>
-<p>In sum, the goal of the <span class="strong"><i>Parties and Groups</i></span> system is to
+<tt>group_id</tt> values</p></li></ul></div><p>In sum, the goal of the <span class="strong"><em>Parties and Groups</em></span> system is to
provide OpenACS programmers and site administrators with simple tools that fully
describe the complex relationships that exist among groups in the real
-world.</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="groups-requirements-user-scenarios"></a>User Scenarios</h3></div></div>
-<p>Pat Developer has a client project and wants to model the company, its
+world.</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="groups-requirements-user-scenarios"></a>User Scenarios</h3></div></div><p>Pat Developer has a client project and wants to model the company, its
offices, its divisions, and its departments as groups and the employees as
-users.</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="groups-requirements-system-overview"></a>System Overview</h3></div></div>
-<p>We start with <span class="strong"><i>Groups</i></span>, which contain members; the
-<span class="strong"><i>member can be either a person or another group</i></span> (i.e. a
-member is a party).</p>
-<p>In addition to membership, the party and groups system defines a
-<span class="strong"><i>composition</i></span> relationship that may exist between groups: A
-group can be a <span class="strong"><i>component</i></span> of another group. The child group
-is called a <span class="emphasis"><i>component group</i></span>; the parent group is called a
-<span class="emphasis"><i>composite group</i></span>.</p>
-<p>A group <span class="strong"><i>G<sub>c</sub></i></span> can be a member and/or a component
-of another group <span class="strong"><i>G<sub>p</sub></i></span>; the difference is in the way
-the members of <span class="strong"><i>G<sub>c</sub></i></span> are related to
-<span class="strong"><i>G<sub>p</sub></i></span>:</p>
-<div class="itemizedlist"><ul>
-<li><p>If a party <span class="strong"><i>P</i></span> is a member (or a component) of
-<span class="strong"><i>G<sub>c</sub></i></span> and if <span class="strong"><i>G<sub>c</sub></i></span> is a
-component of <span class="strong"><i>G<sub>p</sub></i></span>, then <span class="strong"><i>P</i></span> is also
-a member (or a component) of <span class="strong"><i>G<sub>p</sub></i></span>
-</p></li>
-<li><p>If a party <span class="strong"><i>P</i></span> is a member (or a component) of
-<span class="strong"><i>G<sub>c</sub></i></span> and if <span class="strong"><i>G<sub>c</sub></i></span> is a
-member of <span class="strong"><i>G<sub>p</sub></i></span>, then <span class="strong"><i>no
-relationship</i></span> between <span class="strong"><i>P</i></span> and
-<span class="strong"><i>G<sub>p</sub></i></span> exists as a result of the relationship between
-<span class="strong"><i>G<sub>p</sub></i></span> and <span class="strong"><i>G<sub>p</sub></i></span>.</p></li>
-</ul></div>
-<p>Consider an example to make this less abstract: Pretend that the Sierra
-Club is a <span class="emphasis"><i>member</i></span> of Greenpeace. The Sierra Club has chapters; each
-chapter is a <span class="emphasis"><i>component</i></span> of the Sierra Club. If Eddie Environmentalist
+users.</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="groups-requirements-system-overview"></a>System Overview</h3></div></div><p>We start with <span class="strong"><em>Groups</em></span>, which contain members; the
+<span class="strong"><em>member can be either a person or another group</em></span> (i.e. a
+member is a party).</p><p>In addition to membership, the party and groups system defines a
+<span class="strong"><em>composition</em></span> relationship that may exist between groups: A
+group can be a <span class="strong"><em>component</em></span> of another group. The child group
+is called a <span class="emphasis"><em>component group</em></span>; the parent group is called a
+<span class="emphasis"><em>composite group</em></span>.</p><p>A group <span class="strong"><em>G<sub>c</sub></em></span> can be a member and/or a component
+of another group <span class="strong"><em>G<sub>p</sub></em></span>; the difference is in the way
+the members of <span class="strong"><em>G<sub>c</sub></em></span> are related to
+<span class="strong"><em>G<sub>p</sub></em></span>:</p><div class="itemizedlist"><ul type="disc"><li><p>If a party <span class="strong"><em>P</em></span> is a member (or a component) of
+<span class="strong"><em>G<sub>c</sub></em></span> and if <span class="strong"><em>G<sub>c</sub></em></span> is a
+component of <span class="strong"><em>G<sub>p</sub></em></span>, then <span class="strong"><em>P</em></span> is also
+a member (or a component) of <span class="strong"><em>G<sub>p</sub></em></span></p></li><li><p>If a party <span class="strong"><em>P</em></span> is a member (or a component) of
+<span class="strong"><em>G<sub>c</sub></em></span> and if <span class="strong"><em>G<sub>c</sub></em></span> is a
+member of <span class="strong"><em>G<sub>p</sub></em></span>, then <span class="strong"><em>no
+relationship</em></span> between <span class="strong"><em>P</em></span> and
+<span class="strong"><em>G<sub>p</sub></em></span> exists as a result of the relationship between
+<span class="strong"><em>G<sub>p</sub></em></span> and <span class="strong"><em>G<sub>p</sub></em></span>.</p></li></ul></div><p>Consider an example to make this less abstract: Pretend that the Sierra
+Club is a <span class="emphasis"><em>member</em></span> of Greenpeace. The Sierra Club has chapters; each
+chapter is a <span class="emphasis"><em>component</em></span> of the Sierra Club. If Eddie Environmentalist
is a member of the Massachusetts Chapter of the Sierra Club, Eddie is
automatically a member of the Sierra Club, but being a Sierra Club member
-does not make Eddie a member of Greenpeace.</p>
-<p>In the OpenACS, Greenpeace, Sierra Club, and the Sierra Club chapters would be
+does not make Eddie a member of Greenpeace.</p><p>In the OpenACS, Greenpeace, Sierra Club, and the Sierra Club chapters would be
modeled as groups, and Eddie would be a user. There would be a composition
relationship between each Sierra Club chapter and the Sierra Club. Membership
relationships would exist between Eddie and the Massachusetts Chapter,
between Eddie and the Sierra Club (due to Eddie's membership in the
-Massachusetts chapter), and between the Sierra Club and Greenpeace.</p>
-<p>Membership requirements can vary from group to group. The parties and
+Massachusetts chapter), and between the Sierra Club and Greenpeace.</p><p>Membership requirements can vary from group to group. The parties and
groups system must provide a base type that specifies the bare minimum
-necessary to join a group.</p>
-<p>The parties and groups system must support constraints between a composite
-group <span class="strong"><i>G<sub>P</sub></i></span> and any of its component groups,
-<span class="strong"><i>G<sub>C</sub></i></span>. For example, the system should be able to
-enforce a rule like: Do not allow a party <span class="strong"><i>P</i></span> to become a
-member of <span class="strong"><i>G<sub>C</sub></i></span> unless <span class="strong"><i>P</i></span> is already
-a member of <span class="strong"><i>G<sub>P</sub></i></span>.</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="groups-requirements-links"></a>Related Links</h3></div></div>
-<div class="itemizedlist"><ul><li><p><a href="groups-design.html">OpenACS 4 Groups Design</a></p></li></ul></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="groups-requirements-data-model"></a>Requirements: Data Model</h3></div></div>
-<p>The data model for the parties and groups system must provide support for
-the following types of entities:</p>
-<div class="variablelist"><dl>
-<dt><span class="term"><span class="strong"><i>10.0 Parties</i></span>
+necessary to join a group.</p><p>The parties and groups system must support constraints between a composite
+group <span class="strong"><em>G<sub>P</sub></em></span> and any of its component groups,
+<span class="strong"><em>G<sub>C</sub></em></span>. For example, the system should be able to
+enforce a rule like: Do not allow a party <span class="strong"><em>P</em></span> to become a
+member of <span class="strong"><em>G<sub>C</sub></em></span> unless <span class="strong"><em>P</em></span> is already
+a member of <span class="strong"><em>G<sub>P</sub></em></span>.</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="groups-requirements-links"></a>Related Links</h3></div></div><div class="itemizedlist"><ul type="disc"><li><p><a href="groups-design.html">OpenACS 4 Groups Design</a></p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="groups-requirements-data-model"></a>Requirements: Data Model</h3></div></div><p>The data model for the parties and groups system must provide support for
+the following types of entities:</p><div class="variablelist"><dl><dt><span class="term"><span class="strong"><em>10.0 Parties</em></span>
-</span></dt>
-<dd>
-<p>A <span class="strong"><i>party</i></span> is an entity used to represent either a
-<span class="emphasis"><i>group</i></span> or a <span class="emphasis"><i>person</i></span>.</p>
-<p>The data model should enforce these constraints:</p>
-<p>
-<span class="strong"><i>10.10</i></span> A party has an email address, which can be
-empty.</p>
-<p>
-<span class="strong"><i>10.20</i></span> A party may have multiple email addresses
-associated with it.</p>
-<p>
-<span class="strong"><i>10.30</i></span> The email address of a party must be unique within
-an OpenACS system.</p>
-</dd>
-<dt><span class="term"><span class="strong"><i>20.0 Groups</i></span>
+</span></dt><dd><p>A <span class="strong"><em>party</em></span> is an entity used to represent either a
+<span class="emphasis"><em>group</em></span> or a <span class="emphasis"><em>person</em></span>.</p><p>The data model should enforce these constraints:</p><p><span class="strong"><em>10.10</em></span> A party has an email address, which can be
+empty.</p><p><span class="strong"><em>10.20</em></span> A party may have multiple email addresses
+associated with it.</p><p><span class="strong"><em>10.30</em></span> The email address of a party must be unique within
+an OpenACS system.</p></dd><dt><span class="term"><span class="strong"><em>20.0 Groups</em></span>
-</span></dt>
-<dd>
-<p>A <span class="strong"><i>group</i></span> is a collection of zero or more parties.</p>
-<p>
-<span class="strong"><i>20.10</i></span> The data model should support the subclassing of
-groups via OpenACS Objects.</p>
-</dd>
-<dt><span class="term"><span class="strong"><i>30.0 Persons</i></span>
+</span></dt><dd><p>A <span class="strong"><em>group</em></span> is a collection of zero or more parties.</p><p><span class="strong"><em>20.10</em></span> The data model should support the subclassing of
+groups via OpenACS Objects.</p></dd><dt><span class="term"><span class="strong"><em>30.0 Persons</em></span>
-</span></dt>
-<dd>
-<p>A <span class="strong"><i>person</i></span> represents an actual human being, past or
-present.</p>
-<p>
-<a name="groups-requirements-30-10"></a><span class="strong"><i>30.10.</i></span> A person must have
-an associated name.</p>
-</dd>
-<dt><span class="term"><span class="strong"><i>40.0 Users</i></span>
+</span></dt><dd><p>A <span class="strong"><em>person</em></span> represents an actual human being, past or
+present.</p><p><a name="groups-requirements-30-10"></a><span class="strong"><em>30.10.</em></span> A person must have
+an associated name.</p></dd><dt><span class="term"><span class="strong"><em>40.0 Users</em></span>
-</span></dt>
-<dd>
-<p>A <span class="strong"><i>user</i></span> is a person who has registered with an OpenACS site. A
-user may have additional attributes, such as a screen name.</p>
-<p>The data model should enforce these constraints:</p>
-<p>
-<span class="strong"><i>40.10</i></span> A user must have a non-empty email address.</p>
-<p>
-<span class="strong"><i>40.20</i></span> Two different users may not have the same email
+</span></dt><dd><p>A <span class="strong"><em>user</em></span> is a person who has registered with an OpenACS site. A
+user may have additional attributes, such as a screen name.</p><p>The data model should enforce these constraints:</p><p><span class="strong"><em>40.10</em></span> A user must have a non-empty email address.</p><p><span class="strong"><em>40.20</em></span> Two different users may not have the same email
address on a single OpenACS installation; i.e., an email address identifies a
-single user on the system.</p>
-<p>
-<span class="strong"><i>40.30</i></span> A user may have multiple email addresses; for
-example, two or more email addresses may identify a single user.</p>
-<p>
-<span class="strong"><i>40.40</i></span> A user must have password field which can be
-empty.</p>
-</dd>
-</dl></div>
-<p>The data model for the parties and groups system must provide support for
-the following types of relationships between entities:</p>
-<div class="variablelist"><dl>
-<dt><span class="term"><span class="strong"><i>50.0 Membership</i></span>
+single user on the system.</p><p><span class="strong"><em>40.30</em></span> A user may have multiple email addresses; for
+example, two or more email addresses may identify a single user.</p><p><span class="strong"><em>40.40</em></span> A user must have password field which can be
+empty.</p></dd></dl></div><p>The data model for the parties and groups system must provide support for
+the following types of relationships between entities:</p><div class="variablelist"><dl><dt><span class="term"><span class="strong"><em>50.0 Membership</em></span>
-</span></dt>
-<dd>
-<p>
-A party <span class="strong"><i>P</i></span> is considered a <span class="strong"><i>member</i></span> of a
-group <span class="strong"><i>G</i></span>
-</p>
-<div class="itemizedlist"><ul>
-<li><p>when a direct membership relationship exists between <span class="strong"><i>P</i></span>
-and <span class="strong"><i>G</i></span>
-</p></li>
-<li><p>or when there exists a direct membership relationship between
-<span class="strong"><i>P</i></span> and some group <span class="strong"><i>G<sub>C</sub></i></span> and
-<span class="strong"><i>G<sub>C</sub></i></span> has a composition relationship (c.f., <a href="groups-requirements.html#groups-requirements-60-0">60.0</a>) with <span class="strong"><i>G</i></span>.</p></li>
-</ul></div>
-<p>
-<span class="strong"><i>50.10</i></span> A party may be a member of multiple groups.</p>
-<p>
-<span class="strong"><i>50.20</i></span> A party may be a member of the same group multiple
+</span></dt><dd><p>
+A party <span class="strong"><em>P</em></span> is considered a <span class="strong"><em>member</em></span> of a
+group <span class="strong"><em>G</em></span></p><div class="itemizedlist"><ul type="disc"><li><p>when a direct membership relationship exists between <span class="strong"><em>P</em></span>
+and <span class="strong"><em>G</em></span></p></li><li><p>or when there exists a direct membership relationship between
+<span class="strong"><em>P</em></span> and some group <span class="strong"><em>G<sub>C</sub></em></span> and
+<span class="strong"><em>G<sub>C</sub></em></span> has a composition relationship (c.f., <a href="groups-requirements.html#groups-requirements-60-0">60.0</a>) with <span class="strong"><em>G</em></span>.</p></li></ul></div><p><span class="strong"><em>50.10</em></span> A party may be a member of multiple groups.</p><p><span class="strong"><em>50.20</em></span> A party may be a member of the same group multiple
times only when all the memberships have different types; for example, Jane
may be a member of The Company by being both an Employee and an
-Executive.</p>
-<p>
-<span class="strong"><i>50.30</i></span> A party as a member of itself is not supported.</p>
-<p>
-<span class="strong"><i>50.40</i></span> The data model must support membership
-constraints.</p>
-<p>
-<span class="strong"><i>50.50</i></span>The data model should support the subclassing of
-membership via OpenACS Relationships.</p>
-</dd>
-</dl></div>
-<div class="variablelist"><dl>
-<dt><span class="term">
+Executive.</p><p><span class="strong"><em>50.30</em></span> A party as a member of itself is not supported.</p><p><span class="strong"><em>50.40</em></span> The data model must support membership
+constraints.</p><p><span class="strong"><em>50.50</em></span>The data model should support the subclassing of
+membership via OpenACS Relationships.</p></dd></dl></div><div class="variablelist"><dl><dt><span class="term">
<a name="groups-requirements-60-0"></a>
-<span class="strong"><i>60.0 Composition</i></span>
-</span></dt>
-<dd>
-<p>A group <span class="strong"><i>G<sub>C</sub></i></span> is considered a
-<span class="strong"><i>component</i></span> of a second group
-<span class="strong"><i>G<sub>P</sub></i></span>
-</p>
-<div class="itemizedlist"><ul>
-<li><p>when a direct composition relationship exists between
-<span class="strong"><i>G<sub>C</sub></i></span> and <span class="strong"><i>G<sub>P</sub></i></span>
-</p></li>
-<li><p>or when there exists a direct composition relationship between
-<span class="strong"><i>G<sub>C</sub></i></span> and some group <span class="strong"><i>G<sub>i</sub></i></span>
-and <span class="strong"><i>G<sub>i</sub></i></span> has a composition relationship with
-<span class="strong"><i>G<sub>P</sub></i></span>.</p></li>
-</ul></div>
-<p>
-<span class="strong"><i>60.10</i></span>A group may be a component of multiple groups.</p>
-<p>
-<span class="strong"><i>60.20</i></span>A group as a component of itself is not
-supported.</p>
-<p>
-<span class="strong"><i>60.30</i></span>The data model must support component
-constraints.</p>
-<p>
-<span class="strong"><i>60.40</i></span>The data model should support the subclassing of
-composition via OpenACS Relationships.</p>
-</dd>
-</dl></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="groups-requirements-api"></a>Requirements: API</h3></div></div>
-<p>The API should let programmers accomplish the following tasks:</p>
-<div class="variablelist"><dl>
-<dt><span class="term"><span class="strong"><i>70.10 Create a group</i></span>
+<span class="strong"><em>60.0 Composition</em></span>
+</span></dt><dd><p>A group <span class="strong"><em>G<sub>C</sub></em></span> is considered a
+<span class="strong"><em>component</em></span> of a second group
+<span class="strong"><em>G<sub>P</sub></em></span></p><div class="itemizedlist"><ul type="disc"><li><p>when a direct composition relationship exists between
+<span class="strong"><em>G<sub>C</sub></em></span> and <span class="strong"><em>G<sub>P</sub></em></span></p></li><li><p>or when there exists a direct composition relationship between
+<span class="strong"><em>G<sub>C</sub></em></span> and some group <span class="strong"><em>G<sub>i</sub></em></span>
+and <span class="strong"><em>G<sub>i</sub></em></span> has a composition relationship with
+<span class="strong"><em>G<sub>P</sub></em></span>.</p></li></ul></div><p><span class="strong"><em>60.10</em></span>A group may be a component of multiple groups.</p><p><span class="strong"><em>60.20</em></span>A group as a component of itself is not
+supported.</p><p><span class="strong"><em>60.30</em></span>The data model must support component
+constraints.</p><p><span class="strong"><em>60.40</em></span>The data model should support the subclassing of
+composition via OpenACS Relationships.</p></dd></dl></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="groups-requirements-api"></a>Requirements: API</h3></div></div><p>The API should let programmers accomplish the following tasks:</p><div class="variablelist"><dl><dt><span class="term"><span class="strong"><em>70.10 Create a group</em></span>
-</span></dt>
-<dd><p>The parties and groups system provides a well defined API call that
+</span></dt><dd><p>The parties and groups system provides a well defined API call that
creates a new group by running the appropriate transactions on the parties
and groups system data model. This API is subject to the constraints laid out
-in the data model.</p></dd>
-<dt><span class="term"><span class="strong"><i>70.20 Create a person</i></span>
+in the data model.</p></dd><dt><span class="term"><span class="strong"><em>70.20 Create a person</em></span>
-</span></dt>
-<dd><p>The parties and groups system provides a well defined API call that
+</span></dt><dd><p>The parties and groups system provides a well defined API call that
creates a new person by running the appropriate transactions on the parties
and groups system data model. This API is subject to the constraints laid out
-in the data model.</p></dd>
-<dt><span class="term"><span class="strong"><i>70.30 Create a user</i></span>
+in the data model.</p></dd><dt><span class="term"><span class="strong"><em>70.30 Create a user</em></span>
-</span></dt>
-<dd><p>The parties and groups system provides a well defined API call that
+</span></dt><dd><p>The parties and groups system provides a well defined API call that
creates a new user by running the appropriate transactions on the parties and
groups system data model. This API is subject to the constraints laid out in
-the data model.</p></dd>
-<dt><span class="term"><span class="strong"><i>80.10 Refine a person to a user</i></span>
+the data model.</p></dd><dt><span class="term"><span class="strong"><em>80.10 Refine a person to a user</em></span>
-</span></dt>
-<dd><p>The parties and groups system provides a well defined API call that
+</span></dt><dd><p>The parties and groups system provides a well defined API call that
creates a new user by running the appropriate transactions on an existing
person entity. This API is subject to the constraints laid out in the data
-model.</p></dd>
-<dt><span class="term"><span class="strong"><i>80.30 Demote a user to a person</i></span>
+model.</p></dd><dt><span class="term"><span class="strong"><em>80.30 Demote a user to a person</em></span>
-</span></dt>
-<dd><p>The parties and groups system provides a well defined API call that
+</span></dt><dd><p>The parties and groups system provides a well defined API call that
demotes an existing user entity to a person entity by running the appropriate
transactions on the existing user. This API is subject to the constraints
-laid out in the data model.</p></dd>
-<dt><span class="term"><span class="strong"><i>90.10 Update a party</i></span>
+laid out in the data model.</p></dd><dt><span class="term"><span class="strong"><em>90.10 Update a party</em></span>
-</span></dt>
-<dd><p>The programmer should be able to modify, add, and delete attributes on any
-party. This API is subject to the constraints laid out in the data model.</p></dd>
-<dt><span class="term"><span class="strong"><i>95.10 Get the attributes of a party</i></span>
+</span></dt><dd><p>The programmer should be able to modify, add, and delete attributes on any
+party. This API is subject to the constraints laid out in the data model.</p></dd><dt><span class="term"><span class="strong"><em>95.10 Get the attributes of a party</em></span>
-</span></dt>
-<dd><p>The programmer should be able to view the attributes on any party. This
-API is subject to the constraints laid out in the data model.</p></dd>
-<dt><span class="term"><span class="strong"><i>100.10 Delete a party</i></span>
+</span></dt><dd><p>The programmer should be able to view the attributes on any party. This
+API is subject to the constraints laid out in the data model.</p></dd><dt><span class="term"><span class="strong"><em>100.10 Delete a party</em></span>
-</span></dt>
-<dd>
-<p>The system provides an API for deleting a party. This API is subject to
-the constraints laid out in the data model.</p>
-<p>
-<span class="strong"><i>100.30</i></span> The system may provide a single API call to remove
-the party from all groups and then delete the party.</p>
-<p>
-<span class="strong"><i>100.40</i></span> In the case of a group, the system may provide a
+</span></dt><dd><p>The system provides an API for deleting a party. This API is subject to
+the constraints laid out in the data model.</p><p><span class="strong"><em>100.30</em></span> The system may provide a single API call to remove
+the party from all groups and then delete the party.</p><p><span class="strong"><em>100.40</em></span> In the case of a group, the system may provide a
single API call to remove all parties from a group and then delete the
-group.</p>
-</dd>
-<dt><span class="term"><span class="strong"><i>110.0 Add a party as a member of a group</i></span>
+group.</p></dd><dt><span class="term"><span class="strong"><em>110.0 Add a party as a member of a group</em></span>
-</span></dt>
-<dd><p>The parties and groups system provides an API for adding a party as a
+</span></dt><dd><p>The parties and groups system provides an API for adding a party as a
member of a group. This API is subject to the constraints laid out in the
-data model.</p></dd>
-<dt><span class="term"><span class="strong"><i>115.0 Add a group as a component of a second group</i></span>
+data model.</p></dd><dt><span class="term"><span class="strong"><em>115.0 Add a group as a component of a second group</em></span>
-</span></dt>
-<dd><p>The parties and groups system provides an API for adding a group as a
+</span></dt><dd><p>The parties and groups system provides an API for adding a group as a
component of a second group. This API is subject to the constraints laid out
-in the data model.</p></dd>
-<dt><span class="term"><span class="strong"><i>120.0 Remove a party as a member of a group</i></span>
+in the data model.</p></dd><dt><span class="term"><span class="strong"><em>120.0 Remove a party as a member of a group</em></span>
-</span></dt>
-<dd><p>The parties and groups system provides an API for deleting a party's
+</span></dt><dd><p>The parties and groups system provides an API for deleting a party's
membership in a group. This API is subject to the constraints laid out in the
-data model.</p></dd>
-<dt><span class="term"><span class="strong"><i>125.0 Remove a group as a component of a second
-group</i></span>
+data model.</p></dd><dt><span class="term"><span class="strong"><em>125.0 Remove a group as a component of a second
+group</em></span>
-</span></dt>
-<dd><p>The parties and groups system provides an API for deleting a group's
+</span></dt><dd><p>The parties and groups system provides an API for deleting a group's
composition in a second group. This API is subject to the constraints laid
-out in the data model.</p></dd>
-<dt><span class="term"><span class="strong"><i>130.0 Membership check</i></span>
+out in the data model.</p></dd><dt><span class="term"><span class="strong"><em>130.0 Membership check</em></span>
-</span></dt>
-<dd><p>The parties and groups system provides an API for answering the question:
-"Is party <span class="strong"><i>P</i></span> a member of group
-<span class="strong"><i>G</i></span>?"</p></dd>
-<dt><span class="term"><span class="strong"><i>135.0 Composition check</i></span>
+</span></dt><dd><p>The parties and groups system provides an API for answering the question:
+"Is party <span class="strong"><em>P</em></span> a member of group
+<span class="strong"><em>G</em></span>?"</p></dd><dt><span class="term"><span class="strong"><em>135.0 Composition check</em></span>
-</span></dt>
-<dd><p>The parties and groups system provides an API for answering the question:
-"Is group <span class="strong"><i>G<sub>C</sub></i></span> a component of group
-<span class="strong"><i>G<sub>P</sub></i></span>?"</p></dd>
-<dt><span class="term"><span class="strong"><i>140.0 Get members query</i></span>
+</span></dt><dd><p>The parties and groups system provides an API for answering the question:
+"Is group <span class="strong"><em>G<sub>C</sub></em></span> a component of group
+<span class="strong"><em>G<sub>P</sub></em></span>?"</p></dd><dt><span class="term"><span class="strong"><em>140.0 Get members query</em></span>
-</span></dt>
-<dd><p>The parties and groups system provides an API for answering the question:
-"Which parties are members of group <span class="strong"><i>G</i></span>?"</p></dd>
-<dt><span class="term"><span class="strong"><i>145.0 Get components query</i></span>
+</span></dt><dd><p>The parties and groups system provides an API for answering the question:
+"Which parties are members of group <span class="strong"><em>G</em></span>?"</p></dd><dt><span class="term"><span class="strong"><em>145.0 Get components query</em></span>
-</span></dt>
-<dd><p>The parties and groups system provides an API for answering the question:
-"Which groups are components of group <span class="strong"><i>G</i></span>?"</p></dd>
-<dt><span class="term"><span class="strong"><i>150.0 Member-of-groups query</i></span>
+</span></dt><dd><p>The parties and groups system provides an API for answering the question:
+"Which groups are components of group <span class="strong"><em>G</em></span>?"</p></dd><dt><span class="term"><span class="strong"><em>150.0 Member-of-groups query</em></span>
-</span></dt>
-<dd><p>The parties and groups system provides an API for answering the question:
-"Of which groups is party <span class="strong"><i>P</i></span> a member?"</p></dd>
-<dt><span class="term"><span class="strong"><i>155.0 Component-of-groups query</i></span>
+</span></dt><dd><p>The parties and groups system provides an API for answering the question:
+"Of which groups is party <span class="strong"><em>P</em></span> a member?"</p></dd><dt><span class="term"><span class="strong"><em>155.0 Component-of-groups query</em></span>
-</span></dt>
-<dd><p>The parties and groups system provides an API for answering the question:
-"Of which groups is group <span class="strong"><i>G</i></span> a component?"</p></dd>
-<dt><span class="term"><span class="strong"><i>160.0 Allowed membership check</i></span>
+</span></dt><dd><p>The parties and groups system provides an API for answering the question:
+"Of which groups is group <span class="strong"><em>G</em></span> a component?"</p></dd><dt><span class="term"><span class="strong"><em>160.0 Allowed membership check</em></span>
-</span></dt>
-<dd><p>The parties and groups system provides an API for answering the question:
-"Is party <span class="strong"><i>P</i></span> allowed to become a member of group
-<span class="strong"><i>G</i></span>?"</p></dd>
-<dt><span class="term"><span class="strong"><i>165.0 Allowed composition check</i></span>
+</span></dt><dd><p>The parties and groups system provides an API for answering the question:
+"Is party <span class="strong"><em>P</em></span> allowed to become a member of group
+<span class="strong"><em>G</em></span>?"</p></dd><dt><span class="term"><span class="strong"><em>165.0 Allowed composition check</em></span>
-</span></dt>
-<dd><p>The parties and groups system provides an API for answering the question:
-"Is group <span class="strong"><i>G<sub>C</sub></i></span> allowed to become a component
-of group <span class="strong"><i>G<sub>P</sub></i></span>?"</p></dd>
-<dt><span class="term"><span class="strong"><i>170.0 Efficiency</i></span>
+</span></dt><dd><p>The parties and groups system provides an API for answering the question:
+"Is group <span class="strong"><em>G<sub>C</sub></em></span> allowed to become a component
+of group <span class="strong"><em>G<sub>P</sub></em></span>?"</p></dd><dt><span class="term"><span class="strong"><em>170.0 Efficiency</em></span>
-</span></dt>
-<dd><p>Since many pages at a site may check membership in a group before serving
+</span></dt><dd><p>Since many pages at a site may check membership in a group before serving
a page (e.g., as part of a general permissions check), the data model must
support the efficient storage and retrieval of party attributes and
-membership.</p></dd>
-<dt><span class="term"><span class="strong"><i>180.0 Ease of Use</i></span>
+membership.</p></dd><dt><span class="term"><span class="strong"><em>180.0 Ease of Use</em></span>
-</span></dt>
-<dd><p>Since many SQL queries will check membership in a group as part of the
+</span></dt><dd><p>Since many SQL queries will check membership in a group as part of the
<tt>where</tt> clause, whatever mechanism is used to check membership in SQL
-should be fairly small and simple.</p></dd>
-</dl></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="groups-requirements-ui"></a>Requirements: User Interface</h3></div></div>
-<p>The user interface is a set of HTML pages that are used to drive the
-underlying API. The user interface may provide the following functions:</p>
-<div class="itemizedlist"><ul>
-<li><p>
-<span class="strong"><i>200.0</i></span> Create a party</p></li>
-<li><p>
-<span class="strong"><i>210.0</i></span> View the attributes of a party</p></li>
-<li><p>
-<span class="strong"><i>220.0</i></span> Update the attributes of a party</p></li>
-<li><p>
-<span class="strong"><i>240.0</i></span> Delete a party</p></li>
-<li><p>
-<span class="strong"><i>250.0</i></span> Add a party to a group</p></li>
-<li><p>
-<span class="strong"><i>260.0</i></span> Remove a party from a group</p></li>
-<li><p>
-<span class="strong"><i>270.0</i></span> Perform the membership and composition checks
-outlined in 130.x to 165.x</p></li>
-</ul></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="groups-requirements-rev-history"></a>Revision History</h3></div></div>
-<div class="informaltable"><table border="1">
-<colgroup>
-<col>
-<col>
-<col>
-<col>
-</colgroup>
-<tbody>
-<tr>
-<td><span class="strong"><i>Document Revision #</i></span></td>
-<td><span class="strong"><i>Action Taken, Notes</i></span></td>
-<td><span class="strong"><i>When?</i></span></td>
-<td><span class="strong"><i>By Whom?</i></span></td>
-</tr>
-<tr>
-<td>0.1</td>
-<td>Creation</td>
-<td>08/16/2000</td>
-<td>Rafael Schloming</td>
-</tr>
-<tr>
-<td>0.2</td>
-<td>Initial revision</td>
-<td>08/19/2000</td>
-<td>Mark Thomas</td>
-</tr>
-<tr>
-<td>0.3</td>
-<td>Edited and reviewed, conforms to requirements template</td>
-<td>08/23/2000</td>
-<td>Kai Wu</td>
-</tr>
-<tr>
-<td>0.4</td>
-<td>Further revised, added UI requirements</td>
-<td>08/24/2000</td>
-<td>Mark Thomas</td>
-</tr>
-<tr>
-<td>0.5</td>
-<td>Final edits, pending freeze</td>
-<td>08/24/2000</td>
-<td>Kai Wu</td>
-</tr>
-<tr>
-<td>0.6</td>
-<td>More revisions, added composition requirements</td>
-<td>08/30/2000</td>
-<td>Mark Thomas</td>
-</tr>
-<tr>
-<td>0.7</td>
-<td>More revisions, added composition requirements</td>
-<td>09/08/2000</td>
-<td>Mark Thomas</td>
-</tr>
-</tbody>
-</table></div>
-</div>
-</div>
-<div class="navfooter">
-<hr>
-<table width="100%" summary="Navigation footer">
-<tr>
-<td width="40%" align="left">
-<a accesskey="p" href="permissions-design.html">Prev</a> </td>
-<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
-<td width="40%" align="right"> <a accesskey="n" href="groups-design.html">Next</a>
-</td>
-</tr>
-<tr>
-<td width="40%" align="left">OpenACS 4 Permissions Design </td>
-<td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td>
-<td width="40%" align="right"> OpenACS 4 Groups Design</td>
-</tr>
-</table>
-<hr>
-<address>
- rmello at fslc.usu.edu
- </address>
-<address><a href="mailto:vinod@kurup.com">
+should be fairly small and simple.</p></dd></dl></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="groups-requirements-ui"></a>Requirements: User Interface</h3></div></div><p>The user interface is a set of HTML pages that are used to drive the
+underlying API. The user interface may provide the following functions:</p><div class="itemizedlist"><ul type="disc"><li><p><span class="strong"><em>200.0</em></span> Create a party</p></li><li><p><span class="strong"><em>210.0</em></span> View the attributes of a party</p></li><li><p><span class="strong"><em>220.0</em></span> Update the attributes of a party</p></li><li><p><span class="strong"><em>240.0</em></span> Delete a party</p></li><li><p><span class="strong"><em>250.0</em></span> Add a party to a group</p></li><li><p><span class="strong"><em>260.0</em></span> Remove a party from a group</p></li><li><p><span class="strong"><em>270.0</em></span> Perform the membership and composition checks
+outlined in 130.x to 165.x</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="groups-requirements-rev-history"></a>Revision History</h3></div></div><div class="informaltable"><table border="1"><colgroup><col><col><col><col></colgroup><tbody><tr><td><span class="strong"><em>Document Revision #</em></span></td><td><span class="strong"><em>Action Taken, Notes</em></span></td><td><span class="strong"><em>When?</em></span></td><td><span class="strong"><em>By Whom?</em></span></td></tr><tr><td>0.1</td><td>Creation</td><td>08/16/2000</td><td>Rafael Schloming</td></tr><tr><td>0.2</td><td>Initial revision</td><td>08/19/2000</td><td>Mark Thomas</td></tr><tr><td>0.3</td><td>Edited and reviewed, conforms to requirements template</td><td>08/23/2000</td><td>Kai Wu</td></tr><tr><td>0.4</td><td>Further revised, added UI requirements</td><td>08/24/2000</td><td>Mark Thomas</td></tr><tr><td>0.5</td><td>Final edits, pending freeze</td><td>08/24/2000</td><td>Kai Wu</td></tr><tr><td>0.6</td><td>More revisions, added composition requirements</td><td>08/30/2000</td><td>Mark Thomas</td></tr><tr><td>0.7</td><td>More revisions, added composition requirements</td><td>09/08/2000</td><td>Mark Thomas</td></tr></tbody></table></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="permissions-design.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="groups-design.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS 4 Permissions Design </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> OpenACS 4 Groups Design</td></tr></table><hr><address>rmello at fslc.usu.edu</address><address><a href="mailto:vinod@kurup.com">
vinod@kurup.com
- </a></address>
-</div>
-</body>
-</html>
+ </a></address></div></body></html>
Index: openacs-4/packages/acs-core-docs/www/index.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/index.html,v
diff -u -r1.5 -r1.5.2.1
--- openacs-4/packages/acs-core-docs/www/index.html 7 Mar 2002 06:55:36 -0000 1.5
+++ openacs-4/packages/acs-core-docs/www/index.html 15 May 2002 23:26:18 -0000 1.5.2.1
@@ -1,148 +1,4 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type">
-<title>OpenACS Documentation</title>
-<meta name="generator" content="DocBook XSL Stylesheets V1.45">
-<link rel="home" href="index.html" title="OpenACS Documentation">
-<link rel="next" href="for-everyone.html" title="Part Part I. OpenACS For Everyone">
-<link rel="stylesheet" href="openacs.css" type="text/css">
-</head>
-<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-<div class="navheader">
-<a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr>
-<td width="20%" align="left"> </td>
-<th width="60%" align="center"> </th>
-<td width="20%" align="right"> <a accesskey="n" href="for-everyone.html">Next</a>
-</td>
-</tr></table>
-<hr>
-</div>
-<div class="book">
-<div class="titlepage">
-<div><h1 class="title">
-<a name="id5351595"></a>OpenACS Documentation</h1></div>
-<hr>
-</div>
-<div class="toc">
-<p><b>Table of Contents</b></p>
-<dl>
-<dt>Part I. <a href="for-everyone.html">OpenACS For Everyone</a>
-</dt>
-<dd><dl>
-<dt>1. <a href="general-documents.html">High level information: What is OpenACS?</a>
-</dt>
-<dd><dl>
-<dt><a href="openacs-overview.html">Overview</a></dt>
-<dt><a href="release-notes.html">OpenACS 4.5 Release Notes</a></dt>
-</dl></dd>
-</dl></dd>
-<dt>Part II. <a href="acs-admin.html">For OpenACS Admins</a>
-</dt>
-<dd><dl>
-<dt>2. <a href="unix-install.html">Installing on Unix/Linux</a>
-</dt>
-<dd><dl>
-<dt><a href="install-overview.html">Overview</a></dt>
-<dt><a href="operating-system.html">Install an Operating System</a></dt>
-<dt><a href="oracle.html">Install Oracle 8.1.7</a></dt>
-<dt><a href="postgres.html">Install PostgreSQL 7.1.3</a></dt>
-<dt><a href="aolserver.html">Install AOLserver 3.3+ad13</a></dt>
-<dt><a href="openacs.html">Install OpenACS 4.5</a></dt>
-<dt><a href="nextsteps.html">Next Steps</a></dt>
-<dt><a href="credits.html">Credits</a></dt>
-</dl></dd>
-<dt>3. <a href="win-install.html">Installing on Windows</a>
-</dt>
-<dd><dl>
-<dt><a href="win-overview.html">Overview</a></dt>
-<dt><a href="win2k-installation.html">OpenACS Installation Guide for Windows2000</a></dt>
-</dl></dd>
-</dl></dd>
-<dt>Part III. <a href="acs-dev.html">For OpenACS Developers</a>
-</dt>
-<dd><dl>
-<dt>4. <a href="dev-guide.html">OpenACS Developer's Guide</a>
-</dt>
-<dd><dl>
-<dt><a href="developers-overview.html">Overview</a></dt>
-<dt><a href="objects.html">OpenACS 4.5 Data Models and the Object System</a></dt>
-<dt><a href="packages.html">OpenACS 4.5 Packages</a></dt>
-<dt><a href="request-processor.html">The Request Processor</a></dt>
-<dt><a href="db-api.html">The OpenACS Database Access API</a></dt>
-<dt><a href="templates.html">Using Templates in OpenACS 4.5</a></dt>
-<dt><a href="permissions.html">Groups, Context, Permissions</a></dt>
-<dt><a href="subsites.html">Writing OpenACS 4.5 Application Pages</a></dt>
-</dl></dd>
-<dt>5. <a href="more-developer-info.html">Other Developer Resources</a>
-</dt>
-<dd><dl>
-<dt><a href="other-developer-overview.html">Overview</a></dt>
-<dt><a href="parties.html">Parties in OpenACS 4.5</a></dt>
-<dt><a href="object-identity.html">Object Identity</a></dt>
-<dt><a href="programming-with-aolserver.html">Programming with AOLserver</a></dt>
-</dl></dd>
-<dt>6. <a href="eng-standards.html">Engineering Standards</a>
-</dt>
-<dd><dl>
-<dt><a href="docbook-primer.html">OpenACS Documentation Guide</a></dt>
-<dt><a href="psgml-mode.html">Using PSGML mode in Emacs</a></dt>
-<dt><a href="filename.html">Detailed Design Documentation Template</a></dt>
-<dt><a href="requirements-template.html">System/Application Requirements Template</a></dt>
-<dt><a href="eng-standards-versioning.html">Release Version Numbering</a></dt>
-<dt><a href="eng-standards-constraint-naming.html">Constraint naming standard</a></dt>
-<dt><a href="eng-standards-filenaming.html">ACS File Naming and Formatting Standards</a></dt>
-<dt><a href="eng-standards-plsql.html">PL/SQL Standards</a></dt>
-</dl></dd>
-<dt>7. <a href="kernel-doc.html">Kernel Documentation</a>
-</dt>
-<dd><dl>
-<dt><a href="kernel-overview.html">Overview</a></dt>
-<dt><a href="object-system-requirements.html">OpenACS 4 Object Model Requirements</a></dt>
-<dt><a href="object-system-design.html">OpenACS 4 Object Model Design</a></dt>
-<dt><a href="permissions-requirements.html">OpenACS 4 Permissions Requirements</a></dt>
-<dt><a href="permissions-design.html">OpenACS 4 Permissions Design</a></dt>
-<dt><a href="groups-requirements.html">OpenACS 4 Groups Requirements</a></dt>
-<dt><a href="groups-design.html">OpenACS 4 Groups Design</a></dt>
-<dt><a href="subsites-requirements.html">OpenACS 4 Subsites Requirements</a></dt>
-<dt><a href="subsites-design.html">OpenACS 4 Subsites Design Document</a></dt>
-<dt><a href="apm-requirements.html">OpenACS 4.5 Package Manager Requirements</a></dt>
-<dt><a href="apm-design.html">OpenACS 4.5 Package Manager Design</a></dt>
-<dt><a href="security-requirements.html">OpenACS 4 Security Requirements</a></dt>
-<dt><a href="security-design.html">OpenACS 4 Security Design</a></dt>
-<dt><a href="security-notes.html">OpenACS 4 Security Notes</a></dt>
-<dt><a href="rp-requirements.html">OpenACS 4 Request Processor Requirements</a></dt>
-<dt><a href="rp-design.html">OpenACS 4 Request Processor Design</a></dt>
-<dt><a href="db-api-detailed.html">Database Access API</a></dt>
-<dt><a href="tcl-doc.html">Documenting Tcl Files: Page Contracts and Libraries</a></dt>
-<dt><a href="bootstrap-acs.html">Bootstrapping OpenACS</a></dt>
-</dl></dd>
-</dl></dd>
-</dl>
-</div>
-</div>
-<div class="navfooter">
-<hr>
-<table width="100%" summary="Navigation footer">
-<tr>
-<td width="40%" align="left"> </td>
-<td width="20%" align="center"> </td>
-<td width="40%" align="right"> <a accesskey="n" href="for-everyone.html">Next</a>
-</td>
-</tr>
-<tr>
-<td width="40%" align="left"> </td>
-<td width="20%" align="center"> </td>
-<td width="40%" align="right"> Part Part I. OpenACS For Everyone</td>
-</tr>
-</table>
-<hr>
-<address>
- rmello at fslc.usu.edu
- </address>
-<address><a href="mailto:vinod@kurup.com">
+<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"><title>OpenACS Documentation</title><meta name="generator" content="DocBook XSL Stylesheets V1.50.0"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="next" href="for-everyone.html" title="Part Part I. OpenACS For Everyone"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="for-everyone.html">Next</a></td></tr></table><hr></div><div class="book"><div class="titlepage"><div><h1 class="title"><a name="id5393262"></a>OpenACS Documentation</h1></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt>Part I. <a href="for-everyone.html">OpenACS For Everyone</a></dt><dd><dl><dt>1. <a href="general-documents.html">High level information: What is OpenACS?</a></dt><dd><dl><dt><a href="openacs-overview.html">Overview</a></dt><dt><a href="release-notes.html">OpenACS 4.5 Release Notes</a></dt></dl></dd></dl></dd><dt>Part II. <a href="acs-admin.html">For OpenACS Admins</a></dt><dd><dl><dt>2. <a href="unix-install.html">Installing on Unix/Linux</a></dt><dd><dl><dt><a href="install-overview.html">Overview</a></dt><dt><a href="operating-system.html">Install an Operating System</a></dt><dt><a href="oracle.html">Install Oracle 8.1.7</a></dt><dt><a href="postgres.html">Install PostgreSQL 7.1.3</a></dt><dt><a href="aolserver.html">Install AOLserver 3.3+ad13</a></dt><dt><a href="openacs.html">Install OpenACS 4.5</a></dt><dt><a href="nextsteps.html">Next Steps</a></dt><dt><a href="credits.html">Credits</a></dt></dl></dd><dt>3. <a href="win-install.html">Installing on Windows</a></dt><dd><dl><dt><a href="win-overview.html">Overview</a></dt><dt><a href="win2k-installation.html">OpenACS Installation Guide for Windows2000</a></dt></dl></dd></dl></dd><dt>Part III. <a href="acs-dev.html">For OpenACS Developers</a></dt><dd><dl><dt>4. <a href="dev-guide.html">OpenACS Developer's Guide</a></dt><dd><dl><dt><a href="developers-overview.html">Overview</a></dt><dt><a href="objects.html">OpenACS 4.5 Data Models and the Object System</a></dt><dt><a href="packages.html">OpenACS 4.5 Packages</a></dt><dt><a href="request-processor.html">The Request Processor</a></dt><dt><a href="db-api.html">The OpenACS Database Access API</a></dt><dt><a href="templates.html">Using Templates in OpenACS 4.5</a></dt><dt><a href="permissions.html">Groups, Context, Permissions</a></dt><dt><a href="subsites.html">Writing OpenACS 4.5 Application Pages</a></dt></dl></dd><dt>5. <a href="more-developer-info.html">Other Developer Resources</a></dt><dd><dl><dt><a href="other-developer-overview.html">Overview</a></dt><dt><a href="parties.html">Parties in OpenACS 4.5</a></dt><dt><a href="object-identity.html">Object Identity</a></dt><dt><a href="programming-with-aolserver.html">Programming with AOLserver</a></dt></dl></dd><dt>6. <a href="eng-standards.html">Engineering Standards</a></dt><dd><dl><dt><a href="docbook-primer.html">OpenACS Documentation Guide</a></dt><dt><a href="psgml-mode.html">Using PSGML mode in Emacs</a></dt><dt><a href="filename.html">Detailed Design Documentation Template</a></dt><dt><a href="requirements-template.html">System/Application Requirements Template</a></dt><dt><a href="eng-standards-versioning.html">Release Version Numbering</a></dt><dt><a href="eng-standards-constraint-naming.html">Constraint naming standard</a></dt><dt><a href="eng-standards-filenaming.html">ACS File Naming and Formatting Standards</a></dt><dt><a href="eng-standards-plsql.html">PL/SQL Standards</a></dt></dl></dd><dt>7. <a href="kernel-doc.html">Kernel Documentation</a></dt><dd><dl><dt><a href="kernel-overview.html">Overview</a></dt><dt><a href="object-system-requirements.html">OpenACS 4 Object Model Requirements</a></dt><dt><a href="object-system-design.html">OpenACS 4 Object Model Design</a></dt><dt><a href="permissions-requirements.html">OpenACS 4 Permissions Requirements</a></dt><dt><a href="permissions-design.html">OpenACS 4 Permissions Design</a></dt><dt><a href="groups-requirements.html">OpenACS 4 Groups Requirements</a></dt><dt><a href="groups-design.html">OpenACS 4 Groups Design</a></dt><dt><a href="subsites-requirements.html">OpenACS 4 Subsites Requirements</a></dt><dt><a href="subsites-design.html">OpenACS 4 Subsites Design Document</a></dt><dt><a href="apm-requirements.html">OpenACS 4.5 Package Manager Requirements</a></dt><dt><a href="apm-design.html">OpenACS 4.5 Package Manager Design</a></dt><dt><a href="security-requirements.html">OpenACS 4 Security Requirements</a></dt><dt><a href="security-design.html">OpenACS 4 Security Design</a></dt><dt><a href="security-notes.html">OpenACS 4 Security Notes</a></dt><dt><a href="rp-requirements.html">OpenACS 4 Request Processor Requirements</a></dt><dt><a href="rp-design.html">OpenACS 4 Request Processor Design</a></dt><dt><a href="db-api-detailed.html">Database Access API</a></dt><dt><a href="tcl-doc.html">Documenting Tcl Files: Page Contracts and Libraries</a></dt><dt><a href="bootstrap-acs.html">Bootstrapping OpenACS</a></dt></dl></dd></dl></dd></dl></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="for-everyone.html">Next</a></td></tr><tr><td width="40%" align="left"> </td><td width="20%" align="center"> </td><td width="40%" align="right"> Part Part I. OpenACS For Everyone</td></tr></table><hr><address>rmello at fslc.usu.edu</address><address><a href="mailto:vinod@kurup.com">
vinod@kurup.com
- </a></address>
-</div>
-</body>
-</html>
+ </a></address></div></body></html>
Index: openacs-4/packages/acs-core-docs/www/install-overview.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-overview.html,v
diff -u -r1.6 -r1.6.2.1
--- openacs-4/packages/acs-core-docs/www/install-overview.html 7 Mar 2002 06:55:36 -0000 1.6
+++ openacs-4/packages/acs-core-docs/www/install-overview.html 15 May 2002 23:26:18 -0000 1.6.2.1
@@ -1,49 +1,22 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type">
-<title>Overview</title>
-<meta name="generator" content="DocBook XSL Stylesheets V1.45">
-<link rel="home" href="index.html" title="OpenACS Documentation">
-<link rel="up" href="unix-install.html" title="Chapter 2. Installing on Unix/Linux">
-<link rel="previous" href="unix-install.html" title="Chapter 2. Installing on Unix/Linux">
-<link rel="next" href="operating-system.html" title="Install an Operating System">
-<link rel="stylesheet" href="openacs.css" type="text/css">
-</head>
-<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-<div class="navheader">
-<a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr>
-<td width="20%" align="left">
-<a accesskey="p" href="unix-install.html">Prev</a> </td>
-<th width="60%" align="center">Chapter 2. Installing on Unix/Linux</th>
-<td width="20%" align="right"> <a accesskey="n" href="operating-system.html">Next</a>
-</td>
-</tr></table>
-<hr>
-</div>
-<div class="sect1">
-<div class="titlepage"><div><h2 class="title" style="clear: both">
-<a name="install-overview"></a>Overview</h2></div></div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="install-description"></a>What is OpenACS?</h3></div></div>
-<p>
+<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"><title>Overview</title><meta name="generator" content="DocBook XSL Stylesheets V1.50.0"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="unix-install.html" title="Chapter 2. Installing on Unix/Linux"><link rel="previous" href="unix-install.html" title="Chapter 2. Installing on Unix/Linux"><link rel="next" href="operating-system.html" title="Install an Operating System"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="unix-install.html">Prev</a> </td><th width="60%" align="center">Chapter 2. Installing on Unix/Linux</th><td width="20%" align="right"> <a accesskey="n" href="operating-system.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="install-overview"></a>Overview</h2></div></div><div class="authorblurb"><p>
+ by <a href="mailto:vinod@kurup.com" target="_top">Vinod Kurup</a><br>
+ OpenACS docs are written by the named authors, but may be edited
+ by OpenACS documentation staff.
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="install-description"></a>What is OpenACS?</h3></div></div><p>
According to Philip Greenspun:
- </p>
-<p>
+ </p><p>
“The ArsDigita Community System (ACS) is a toolkit of software
that will help you build Web services with a collaborative dimension,
ranging from knowledge management within companies to B2C ecommerce
to product support and community among the customers. The software is
free and open-source and has been tested in heavy use since
1995.”
- </p>
-<p>
+ </p><p>
What's OpenACS? OpenACS was born when Don Baccus, Ben Adida,
et al decided to port ACS from Oracle to
PostgreSQL, thus making it a fully open-source solution.
- </p>
-<p>
+ </p><p>
OpenACS 4.5 is the next generation of the web toolkit. It's based on
ACS 4, but no longer follows ArsDigita development. Unlike both ACS
(which required Oracle) and OpenACS 3.x (which required PostgreSQL),
@@ -52,287 +25,164 @@
the word) to extend it to other databases. Don Baccus leads
the development and numerous developers (and non-developers)
contribute from around the world.
- </p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="install-purpose"></a>Purpose of this document</h3></div></div>
-<p>
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="install-purpose"></a>Purpose of this document</h3></div></div><p>
This document will describe how to install OpenACS 4.5 from scratch,
using the source code. We will assume that you have an OS installed,
but we'll discuss this more in the next section. For most of this
guide, we will assume that you are using Linux on a PC, but we'll
also point you to excellent step-by-step guides for other operating
systems.
- </p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="install-requirements"></a>Requirements</h3></div></div>
-<p>
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="install-requirements"></a>Requirements</h3></div></div><p>
You will need a PC (or equivalent) with at least these minimum
requirements:
- </p>
-<div class="itemizedlist"><ul>
-<li><p>Pentium processor</p></li>
-<li><p>128 MB RAM
- (much more if you want Oracle)</p></li>
-<li><p>4 GB hard drive</p></li>
-</ul></div>
-<p>
+ </p><div class="itemizedlist"><ul type="disc"><li><p>Pentium processor</p></li><li><p>128 MB RAM
+ (much more if you want Oracle)</p></li><li><p>4 GB hard drive</p></li></ul></div><p>
If you want to serve pages to people outside of your machine, you'll
need a network connection of some type.
- </p>
-<p>
+ </p><p>
Note that these are minimum requirements to get a development system
up and running. For a production system, we recommend you read about
the <a href="http://www.arsdigita.com/asj/arsdigita-server-architecture" target="_top">ArsDigita
Server Architecture</a>
- </p>
-<p>
+ </p><p>
Running a reliable database-backed web server requires experience
with the server's environment, in this case UNIX. UNIX is not always
an intuitive environment and this guide cannot hope to explain every
nuance. You should be comfortable with the following tasks before
attempting an installation:
- </p>
-<div class="itemizedlist"><ul>
-<li><p>
+ </p><div class="itemizedlist"><ul type="disc"><li><p>
Adding users, groups, setting passwords
- </p></li>
-<li><p>
+ </p></li><li><p>
Starting an X server and running an X program remotely
- </p></li>
-<li><p>
+ </p></li><li><p>
Basic file management using <tt>cp, rm,
mv,</tt> and <tt>cd</tt>
- </p></li>
-<li><p>
+ </p></li><li><p>
Compiling a program using a Makefile
- </p></li>
-</ul></div>
-<p>
+ </p></li></ul></div><p>
If you've never done these things before, consider exploring UNIX in
greater depth before installing OpenACS. Some useful resources for
doing this are described in the <a href="install-overview.html#install-resources">Resources</a>
section.
- </p>
-<p>
+ </p><p>
All of the software that you will need is free and open-source,
except for Oracle. You can obtain a free copy of Oracle for
development purposes. This is described in the <a href="oracle.html#install-oracle-getit">Acquire Oracle</a> section.
- </p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="install-steps"></a>Steps involved</h3></div></div>
-<p>
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="install-steps"></a>Steps involved</h3></div></div><p>
The basic steps to getting OpenACS up and running are:
- </p>
-<div class="orderedlist"><ol type="1">
-<li><p>Install an OS</p></li>
-<li><p>Install a webserver (AOLServer)</p></li>
-<li><p>Install a database (Oracle or
- PostgreSQL)</p></li>
-<li><p> Install a database
+ </p><div class="orderedlist"><ol type="1"><li><p>Install an OS</p></li><li><p>Install a webserver (AOLServer)</p></li><li><p>Install a database (Oracle or
+ PostgreSQL)</p></li><li><p> Install a database
driver (allows the webserver to talk to the database)
- </p></li>
-<li><p>Configure the webserver and
- database</p></li>
-<li><p>Start the OpenACS
- installer</p></li>
-</ol></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="install-stuck"></a>What if I get stuck?</h3></div></div>
-<p>
+ </p></li><li><p>Configure the webserver and
+ database</p></li><li><p>Start the OpenACS
+ installer</p></li></ol></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="install-stuck"></a>What if I get stuck?</h3></div></div><p>
We'll do our best to assure that following our instructions will get
you to the promised land. If something goes wrong, don't
- panic. There's plenty of ways to get help. Here are some tips:
- </p>
-<div class="itemizedlist"><ul>
-<li><p>
- Make sure that you keep track of what commands you are running
- and their output. I like to do my installations in a shell inside
- of emacs (M-x shell) so that I can save the output if needed. An
- alternative would be to use the
+ panic. There are plenty of ways to get help. Here are some tips:
+ </p><div class="itemizedlist"><ul type="disc"><li><p>
+ Keep track of the commands you are run and record their output. I
+ like to do my installations in a shell inside of emacs
+ (<tt>M-x shell</tt>) so that I can save
+ the output if needed. An alternative would be to use the
<tt>script</tt> command.
- </p></li>
-<li><p>
+ </p></li><li><p>
We'll point out where the error logs for the various pieces of
software are. Output from those logs will help us help you. Don't
worry if you feel overwhelmed by all the information in the error
logs. Over time, you'll find that they make more and more
sense. Soon, you'll actually look forward to errors so that you
can run to the log and diagnose the problem.
- </p></li>
-<li><p>
+ </p></li><li><p>
Search the <a href="http://openacs.org/bboard/" target="_top">bboards at
openacs.org</a> - you'll often find many people who have
struggled through the same spot that you're in.
- </p></li>
-<li><p>
+ </p></li><li><p>
Ask questions at the irc channel on openprojects.net
(#openacs). They're knowledgeable and quite friendly if you can
keep them on topic.
- </p></li>
-<li><p>
+ </p></li><li><p>
Post a question on the <a href="http://openacs.org/bboard/" target="_top">bboards</a>. Make sure
you've done a search first. When you do post, be sure to include
your setup information (OS, etc) as well as the exact commands
that are failing with the accompanying error. If you want to post
stuff from your logs (please do!), be sure to enclose them in
<PRE></PRE> tags so that they don't get all jumbled
together.
- </p></li>
-<li><p>
+ </p></li><li><p>
If you find errors in this document or if you have ideas about
making it better, please post them in our bug tracker - the
- <a href="http://openacs.org/sdm/open-bafs.tcl?module_id=54&package_id=9" target="_top">SDM</a>.
- </p></li>
-</ul></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="install-rpms"></a>Is there an easier way?</h3></div></div>
-<p>
+ <a href="http://openacs.org/sdm/open-bafs.tcl?module_id=54%26amp;package_id=9" target="_top">SDM</a>.
+ </p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="install-rpms"></a>Is there an easier way?</h3></div></div><p>
After reading through this tome, you may ask yourself if there is a
better way. And there is! Jonathan Marsden has done all the dirty
work to create RPMs for OpenACS 4.5. These RPMs will install AOLServer,
all the AOLServer modules, PostgreSQL and OpenACS 4.5 simply by typing
one magic command. They're currently at <a href="http://www.xc.org/jonathan/openacs/openacs4-rpm-based-install.html" target="_top">http://www.xc.org</a>,
but will eventually also be available at <a href="http://openacs.org/software/" target="_top">http://openacs.org/software</a>. They're
quite new and Jonathan invites (and is quite responsive to)
- feedback. Leave comments at this <a href="http://openacs.org/bboard/q-and-a-fetch-msg.tcl?msg_id=0003hx&topic_id=11&topic=OpenACS" target="_top">thread</a>.
- </p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="install-origins"></a>Where did this document come from?</h3></div></div>
-<p>
+ feedback. Leave comments at this <a href="http://openacs.org/bboard/q-and-a-fetch-msg.tcl?msg_id=0003hx%26amp;topic_id=11%26amp;topic=OpenACS" target="_top">thread</a>.
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="install-origins"></a>Where did this document come from?</h3></div></div><p>
This document was created by <a href="mailto:vinod@kurup.com" target="_top">Vinod Kurup</a>, but it's really
just plagiarism from a number of documents that came before it. If
I've used something that you've written without proper credit, let me
know and I'll fix it right away.
- </p>
-<p>These are a few of my sources:</p>
-<div class="itemizedlist"><ul>
-<li><p>
+ </p><p>These are a few of my sources:</p><div class="itemizedlist"><ul type="disc"><li><p>
<a href="http://developer.arsdigita.com/doc/unix-install.html" target="_top">ArsDigita installation guide</a>
- </p></li>
-<li><p>
+ </p></li><li><p>
<a href="http://openacs.org/doc/openacs/install/" target="_top">OpenACS 3.x installation guide</a>
- </p></li>
-<li><p>
+ </p></li><li><p>
<a href="http://www.orchardlabs.com/freebsd/" target="_top">Gilbert Wong's FreeBSD
installation guide</a>
- </p></li>
-<li><p>
+ </p></li><li><p>
<a href="http://kurup.com/acs/openacs-4.html" target="_top">My own Brief OpenACS4
installation guide</a>
- </p></li>
-</ul></div>
-<p>
+ </p></li></ul></div><p>
Please also see the <a href="credits.html">Credits</a> section for more acknowledgements.
- </p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="install-resources"></a>Resources</h3></div></div>
-<p>
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="install-resources"></a>Resources</h3></div></div><p>
Here are some resources that OpenACS users have found useful.
- </p>
-<div class="sect3">
-<div class="titlepage"><div><h4 class="title">
-<a name="install-resources-books"></a>Books</h4></div></div>
-<div class="itemizedlist"><ul>
-<li><p>
+ </p><div class="sect3"><div class="titlepage"><div><h4 class="title"><a name="install-resources-books"></a>Books</h4></div></div><div class="itemizedlist"><ul type="disc"><li><p>
<a href="http://www.amazon.com/exec/obidos/ASIN/1558605347/photonetA" target="_top">Philip
and Alex's Guide to Web Publishing</a> - A very readable
guide to database-backed community websites.
- </p></li>
-<li><p>
+ </p></li><li><p>
<a href="http://www.amazon.com/exec/obidos/ISBN=1565922603/photonetA/" target="_top">UNIX
Power Tools</a> - An excellent introduction to the
command line tools and basic programs of UNIX
- </p></li>
-<li><p>
+ </p></li><li><p>
<a href="http://www.amazon.com/exec/obidos/ASIN/0130206016/photonetA" target="_top">UNIX
System Administration Handbook</a> (formerly the "red book"
- now the "purple" book)
- </p></li>
-<li><p>
+ </p></li><li><p>
<a href="http://www.amazon.com/exec/obidos/ASIN/076453162X/photonetA" target="_top">UNIX
System Administrator's Bible</a> - (LePage and Iarerra 1998;
IDG)
- </p></li>
-<li><p>
+ </p></li><li><p>
<a href="http://www.amazon.com/exec/obidos/ASIN/1565921518/photonetA" target="_top">Running
- Linux</a> </p></li>
-<li><p> <a href="http://www.amazon.com/exec/obidos/ASIN/1565921526/photonetA" target="_top">Learning
- Gnu Emacs</a> </p></li>
-<li><p>
+ Linux</a> </p></li><li><p> <a href="http://www.amazon.com/exec/obidos/ASIN/1565921526/photonetA" target="_top">Learning
+ Gnu Emacs</a> </p></li><li><p>
<a href="http://www.amazon.com/exec/obidos/ASIN/1565925858/photonetA" target="_top">Linux
in a Nutshell</a>
- </p></li>
-</ul></div>
-</div>
-<div class="sect3">
-<div class="titlepage"><div><h4 class="title">
-<a name="install-resources-web"></a>Web Sites</h4></div></div>
-<div class="itemizedlist"><ul>
-<li><p>
+ </p></li></ul></div></div><div class="sect3"><div class="titlepage"><div><h4 class="title"><a name="install-resources-web"></a>Web Sites</h4></div></div><div class="itemizedlist"><ul type="disc"><li><p>
<a href="http://www.geek-girl.com/unix.html" target="_top">The UNIX
Reference Desk</a>
- </p></li>
-<li><p>
+ </p></li><li><p>
<a href="http://www.linuxdoc.org/" target="_top">The Linux Documentation
Project</a>
- </p></li>
-</ul></div>
-</div>
-</div>
-<p><div class="cvstag">($Id$)</div></p>
-</div>
-<div class="navfooter">
-<hr>
-<table width="100%" summary="Navigation footer">
-<tr>
-<td width="40%" align="left">
-<a accesskey="p" href="unix-install.html">Prev</a> </td>
-<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
-<td width="40%" align="right"> <a accesskey="n" href="operating-system.html">Next</a>
-</td>
-</tr>
-<tr>
-<td width="40%" align="left">Chapter 2. Installing on Unix/Linux </td>
-<td width="20%" align="center"><a accesskey="u" href="unix-install.html">Up</a></td>
-<td width="40%" align="right"> Install an Operating System</td>
-</tr>
-</table>
-<hr>
-<address>
- rmello at fslc.usu.edu
- </address>
-<address><a href="mailto:vinod@kurup.com">
+ </p></li></ul></div></div></div><p><div class="cvstag">($Id$)</div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="unix-install.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="operating-system.html">Next</a></td></tr><tr><td width="40%" align="left">Chapter 2. Installing on Unix/Linux </td><td width="20%" align="center"><a accesskey="u" href="unix-install.html">Up</a></td><td width="40%" align="right"> Install an Operating System</td></tr></table><hr><address>rmello at fslc.usu.edu</address><address><a href="mailto:vinod@kurup.com">
vinod@kurup.com
- </a></address>
-</div>
-</body>
-</html>
+ </a></address></div></body></html>
Index: openacs-4/packages/acs-core-docs/www/kernel-doc.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/kernel-doc.html,v
diff -u -r1.5 -r1.5.2.1
--- openacs-4/packages/acs-core-docs/www/kernel-doc.html 7 Mar 2002 06:55:36 -0000 1.5
+++ openacs-4/packages/acs-core-docs/www/kernel-doc.html 15 May 2002 23:26:18 -0000 1.5.2.1
@@ -1,77 +1,4 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type">
-<title>Chapter 7. Kernel Documentation</title>
-<meta name="generator" content="DocBook XSL Stylesheets V1.45">
-<link rel="home" href="index.html" title="OpenACS Documentation">
-<link rel="up" href="acs-dev.html" title="Part Part III. For OpenACS Developers">
-<link rel="previous" href="eng-standards-plsql.html" title="PL/SQL Standards">
-<link rel="next" href="kernel-overview.html" title="Overview">
-<link rel="stylesheet" href="openacs.css" type="text/css">
-</head>
-<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-<div class="navheader">
-<a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr>
-<td width="20%" align="left">
-<a accesskey="p" href="eng-standards-plsql.html">Prev</a> </td>
-<th width="60%" align="center">Part Part III. For OpenACS Developers</th>
-<td width="20%" align="right"> <a accesskey="n" href="kernel-overview.html">Next</a>
-</td>
-</tr></table>
-<hr>
-</div>
-<div class="chapter">
-<div class="titlepage"><div><h2 class="title">
-<a name="kernel-doc"></a>Chapter 7. Kernel Documentation</h2></div></div>
-<div class="toc">
-<p><b>Table of Contents</b></p>
-<dl>
-<dt><a href="kernel-overview.html">Overview</a></dt>
-<dt><a href="object-system-requirements.html">OpenACS 4 Object Model Requirements</a></dt>
-<dt><a href="object-system-design.html">OpenACS 4 Object Model Design</a></dt>
-<dt><a href="permissions-requirements.html">OpenACS 4 Permissions Requirements</a></dt>
-<dt><a href="permissions-design.html">OpenACS 4 Permissions Design</a></dt>
-<dt><a href="groups-requirements.html">OpenACS 4 Groups Requirements</a></dt>
-<dt><a href="groups-design.html">OpenACS 4 Groups Design</a></dt>
-<dt><a href="subsites-requirements.html">OpenACS 4 Subsites Requirements</a></dt>
-<dt><a href="subsites-design.html">OpenACS 4 Subsites Design Document</a></dt>
-<dt><a href="apm-requirements.html">OpenACS 4.5 Package Manager Requirements</a></dt>
-<dt><a href="apm-design.html">OpenACS 4.5 Package Manager Design</a></dt>
-<dt><a href="security-requirements.html">OpenACS 4 Security Requirements</a></dt>
-<dt><a href="security-design.html">OpenACS 4 Security Design</a></dt>
-<dt><a href="security-notes.html">OpenACS 4 Security Notes</a></dt>
-<dt><a href="rp-requirements.html">OpenACS 4 Request Processor Requirements</a></dt>
-<dt><a href="rp-design.html">OpenACS 4 Request Processor Design</a></dt>
-<dt><a href="db-api-detailed.html">Database Access API</a></dt>
-<dt><a href="tcl-doc.html">Documenting Tcl Files: Page Contracts and Libraries</a></dt>
-<dt><a href="bootstrap-acs.html">Bootstrapping OpenACS</a></dt>
-</dl>
-</div>
-</div>
-<div class="navfooter">
-<hr>
-<table width="100%" summary="Navigation footer">
-<tr>
-<td width="40%" align="left">
-<a accesskey="p" href="eng-standards-plsql.html">Prev</a> </td>
-<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
-<td width="40%" align="right"> <a accesskey="n" href="kernel-overview.html">Next</a>
-</td>
-</tr>
-<tr>
-<td width="40%" align="left">PL/SQL Standards </td>
-<td width="20%" align="center"><a accesskey="u" href="acs-dev.html">Up</a></td>
-<td width="40%" align="right"> Overview</td>
-</tr>
-</table>
-<hr>
-<address>
- rmello at fslc.usu.edu
- </address>
-<address><a href="mailto:vinod@kurup.com">
+<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"><title>Chapter 7. Kernel Documentation</title><meta name="generator" content="DocBook XSL Stylesheets V1.50.0"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="acs-dev.html" title="Part Part III. For OpenACS Developers"><link rel="previous" href="eng-standards-plsql.html" title="PL/SQL Standards"><link rel="next" href="kernel-overview.html" title="Overview"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="eng-standards-plsql.html">Prev</a> </td><th width="60%" align="center">Part Part III. For OpenACS Developers</th><td width="20%" align="right"> <a accesskey="n" href="kernel-overview.html">Next</a></td></tr></table><hr></div><div class="chapter"><div class="titlepage"><div><h2 class="title"><a name="kernel-doc"></a>Chapter 7. Kernel Documentation</h2></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a href="kernel-overview.html">Overview</a></dt><dt><a href="object-system-requirements.html">OpenACS 4 Object Model Requirements</a></dt><dt><a href="object-system-design.html">OpenACS 4 Object Model Design</a></dt><dt><a href="permissions-requirements.html">OpenACS 4 Permissions Requirements</a></dt><dt><a href="permissions-design.html">OpenACS 4 Permissions Design</a></dt><dt><a href="groups-requirements.html">OpenACS 4 Groups Requirements</a></dt><dt><a href="groups-design.html">OpenACS 4 Groups Design</a></dt><dt><a href="subsites-requirements.html">OpenACS 4 Subsites Requirements</a></dt><dt><a href="subsites-design.html">OpenACS 4 Subsites Design Document</a></dt><dt><a href="apm-requirements.html">OpenACS 4.5 Package Manager Requirements</a></dt><dt><a href="apm-design.html">OpenACS 4.5 Package Manager Design</a></dt><dt><a href="security-requirements.html">OpenACS 4 Security Requirements</a></dt><dt><a href="security-design.html">OpenACS 4 Security Design</a></dt><dt><a href="security-notes.html">OpenACS 4 Security Notes</a></dt><dt><a href="rp-requirements.html">OpenACS 4 Request Processor Requirements</a></dt><dt><a href="rp-design.html">OpenACS 4 Request Processor Design</a></dt><dt><a href="db-api-detailed.html">Database Access API</a></dt><dt><a href="tcl-doc.html">Documenting Tcl Files: Page Contracts and Libraries</a></dt><dt><a href="bootstrap-acs.html">Bootstrapping OpenACS</a></dt></dl></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="eng-standards-plsql.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="kernel-overview.html">Next</a></td></tr><tr><td width="40%" align="left">PL/SQL Standards </td><td width="20%" align="center"><a accesskey="u" href="acs-dev.html">Up</a></td><td width="40%" align="right"> Overview</td></tr></table><hr><address>rmello at fslc.usu.edu</address><address><a href="mailto:vinod@kurup.com">
vinod@kurup.com
- </a></address>
-</div>
-</body>
-</html>
+ </a></address></div></body></html>
Index: openacs-4/packages/acs-core-docs/www/kernel-overview.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/kernel-overview.html,v
diff -u -r1.2 -r1.2.2.1
--- openacs-4/packages/acs-core-docs/www/kernel-overview.html 7 Mar 2002 06:55:36 -0000 1.2
+++ openacs-4/packages/acs-core-docs/www/kernel-overview.html 15 May 2002 23:26:18 -0000 1.2.2.1
@@ -1,81 +1,24 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type">
-<title>Overview</title>
-<meta name="generator" content="DocBook XSL Stylesheets V1.45">
-<link rel="home" href="index.html" title="OpenACS Documentation">
-<link rel="up" href="kernel-doc.html" title="Chapter 7. Kernel Documentation">
-<link rel="previous" href="kernel-doc.html" title="Chapter 7. Kernel Documentation">
-<link rel="next" href="object-system-requirements.html" title="OpenACS 4 Object Model Requirements">
-<link rel="stylesheet" href="openacs.css" type="text/css">
-</head>
-<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-<div class="navheader">
-<a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr>
-<td width="20%" align="left">
-<a accesskey="p" href="kernel-doc.html">Prev</a> </td>
-<th width="60%" align="center">Chapter 7. Kernel Documentation</th>
-<td width="20%" align="right"> <a accesskey="n" href="object-system-requirements.html">Next</a>
-</td>
-</tr></table>
-<hr>
-</div>
-<div class="sect1">
-<div class="titlepage"><div><h2 class="title" style="clear: both">
-<a name="kernel-overview"></a>Overview</h2></div></div>
-<p>
+<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"><title>Overview</title><meta name="generator" content="DocBook XSL Stylesheets V1.50.0"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="kernel-doc.html" title="Chapter 7. Kernel Documentation"><link rel="previous" href="kernel-doc.html" title="Chapter 7. Kernel Documentation"><link rel="next" href="object-system-requirements.html" title="OpenACS 4 Object Model Requirements"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="kernel-doc.html">Prev</a> </td><th width="60%" align="center">Chapter 7. Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="object-system-requirements.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="kernel-overview"></a>Overview</h2></div></div><p>
Compared to its predecessors, version 4.5 of OpenACS has a much
more structured organization, i.e. the most
significant change is found at the system architecture level,
reflected in the following hierarchy:
- </p>
-<div class="itemizedlist"><ul>
-<li><p>The <span class="emphasis"><i>OpenACS 4.5 Kernel</i></span>, which handles system-wide necessities
+ </p><div class="itemizedlist"><ul type="disc"><li><p>The <span class="emphasis"><em>OpenACS 4.5 Kernel</em></span>, which handles system-wide necessities
such as metadata, security, users and groups, subsites, and
package management and deployment.
- </p></li>
-<li><p>The <span class="emphasis"><i>OpenACS 4.5 Core</i></span>, which comprises all the other packages
+ </p></li><li><p>The <span class="emphasis"><em>OpenACS 4.5 Core</em></span>, which comprises all the other packages
that ship with the kernel and are most frequently needed by users,
such as templating, bboard, and user registration/management. The
packages tend to be developed and distributed with the kernel.
- </p></li>
-<li><p>
-<span class="emphasis"><i>OpenACS 4.5 Application packages</i></span>, which typically provide
+ </p></li><li><p><span class="emphasis"><em>OpenACS 4.5 Application packages</em></span>, which typically provide
user-level web services built on top of the Kernel and Core. Such
packages include those built by ArsDigita as well as external
contributors. Application packages are developed separately from
the Kernel, and are typically released independently of it.
- </p></li>
-</ul></div>
-<p>
+ </p></li></ul></div><p>
This document provides a high level overview of the kernel
package. Documentation for the other packages can be found <a href="index.html" target="_top">elsewhere</a>.
- </p>
-</div>
-<div class="navfooter">
-<hr>
-<table width="100%" summary="Navigation footer">
-<tr>
-<td width="40%" align="left">
-<a accesskey="p" href="kernel-doc.html">Prev</a> </td>
-<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
-<td width="40%" align="right"> <a accesskey="n" href="object-system-requirements.html">Next</a>
-</td>
-</tr>
-<tr>
-<td width="40%" align="left">Chapter 7. Kernel Documentation </td>
-<td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td>
-<td width="40%" align="right"> OpenACS 4 Object Model Requirements</td>
-</tr>
-</table>
-<hr>
-<address>
- rmello at fslc.usu.edu
- </address>
-<address><a href="mailto:vinod@kurup.com">
+ </p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="kernel-doc.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="object-system-requirements.html">Next</a></td></tr><tr><td width="40%" align="left">Chapter 7. Kernel Documentation </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> OpenACS 4 Object Model Requirements</td></tr></table><hr><address>rmello at fslc.usu.edu</address><address><a href="mailto:vinod@kurup.com">
vinod@kurup.com
- </a></address>
-</div>
-</body>
-</html>
+ </a></address></div></body></html>
Index: openacs-4/packages/acs-core-docs/www/more-developer-info.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/Attic/more-developer-info.html,v
diff -u -r1.6 -r1.6.2.1
--- openacs-4/packages/acs-core-docs/www/more-developer-info.html 7 Mar 2002 06:55:36 -0000 1.6
+++ openacs-4/packages/acs-core-docs/www/more-developer-info.html 15 May 2002 23:26:18 -0000 1.6.2.1
@@ -1,62 +1,4 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type">
-<title>Chapter 5. Other Developer Resources</title>
-<meta name="generator" content="DocBook XSL Stylesheets V1.45">
-<link rel="home" href="index.html" title="OpenACS Documentation">
-<link rel="up" href="acs-dev.html" title="Part Part III. For OpenACS Developers">
-<link rel="previous" href="subsites.html" title="Writing OpenACS 4.5 Application Pages">
-<link rel="next" href="other-developer-overview.html" title="Overview">
-<link rel="stylesheet" href="openacs.css" type="text/css">
-</head>
-<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-<div class="navheader">
-<a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr>
-<td width="20%" align="left">
-<a accesskey="p" href="subsites.html">Prev</a> </td>
-<th width="60%" align="center">Part Part III. For OpenACS Developers</th>
-<td width="20%" align="right"> <a accesskey="n" href="other-developer-overview.html">Next</a>
-</td>
-</tr></table>
-<hr>
-</div>
-<div class="chapter">
-<div class="titlepage"><div><h2 class="title">
-<a name="more-developer-info"></a>Chapter 5. Other Developer Resources</h2></div></div>
-<div class="toc">
-<p><b>Table of Contents</b></p>
-<dl>
-<dt><a href="other-developer-overview.html">Overview</a></dt>
-<dt><a href="parties.html">Parties in OpenACS 4.5</a></dt>
-<dt><a href="object-identity.html">Object Identity</a></dt>
-<dt><a href="programming-with-aolserver.html">Programming with AOLserver</a></dt>
-</dl>
-</div>
-</div>
-<div class="navfooter">
-<hr>
-<table width="100%" summary="Navigation footer">
-<tr>
-<td width="40%" align="left">
-<a accesskey="p" href="subsites.html">Prev</a> </td>
-<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
-<td width="40%" align="right"> <a accesskey="n" href="other-developer-overview.html">Next</a>
-</td>
-</tr>
-<tr>
-<td width="40%" align="left">Writing OpenACS 4.5 Application Pages </td>
-<td width="20%" align="center"><a accesskey="u" href="acs-dev.html">Up</a></td>
-<td width="40%" align="right"> Overview</td>
-</tr>
-</table>
-<hr>
-<address>
- rmello at fslc.usu.edu
- </address>
-<address><a href="mailto:vinod@kurup.com">
+<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"><title>Chapter 5. Other Developer Resources</title><meta name="generator" content="DocBook XSL Stylesheets V1.50.0"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="acs-dev.html" title="Part Part III. For OpenACS Developers"><link rel="previous" href="subsites.html" title="Writing OpenACS 4.5 Application Pages"><link rel="next" href="other-developer-overview.html" title="Overview"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="subsites.html">Prev</a> </td><th width="60%" align="center">Part Part III. For OpenACS Developers</th><td width="20%" align="right"> <a accesskey="n" href="other-developer-overview.html">Next</a></td></tr></table><hr></div><div class="chapter"><div class="titlepage"><div><h2 class="title"><a name="more-developer-info"></a>Chapter 5. Other Developer Resources</h2></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a href="other-developer-overview.html">Overview</a></dt><dt><a href="parties.html">Parties in OpenACS 4.5</a></dt><dt><a href="object-identity.html">Object Identity</a></dt><dt><a href="programming-with-aolserver.html">Programming with AOLserver</a></dt></dl></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="subsites.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="other-developer-overview.html">Next</a></td></tr><tr><td width="40%" align="left">Writing OpenACS 4.5 Application Pages </td><td width="20%" align="center"><a accesskey="u" href="acs-dev.html">Up</a></td><td width="40%" align="right"> Overview</td></tr></table><hr><address>rmello at fslc.usu.edu</address><address><a href="mailto:vinod@kurup.com">
vinod@kurup.com
- </a></address>
-</div>
-</body>
-</html>
+ </a></address></div></body></html>
Index: openacs-4/packages/acs-core-docs/www/nextsteps.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/Attic/nextsteps.html,v
diff -u -r1.5 -r1.5.2.1
--- openacs-4/packages/acs-core-docs/www/nextsteps.html 7 Mar 2002 06:55:36 -0000 1.5
+++ openacs-4/packages/acs-core-docs/www/nextsteps.html 15 May 2002 23:26:18 -0000 1.5.2.1
@@ -1,54 +1,22 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type">
-<title>Next Steps</title>
-<meta name="generator" content="DocBook XSL Stylesheets V1.45">
-<link rel="home" href="index.html" title="OpenACS Documentation">
-<link rel="up" href="unix-install.html" title="Chapter 2. Installing on Unix/Linux">
-<link rel="previous" href="openacs.html" title="Install OpenACS 4.5">
-<link rel="next" href="credits.html" title="Credits">
-<link rel="stylesheet" href="openacs.css" type="text/css">
-</head>
-<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-<div class="navheader">
-<a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr>
-<td width="20%" align="left">
-<a accesskey="p" href="openacs.html">Prev</a> </td>
-<th width="60%" align="center">Chapter 2. Installing on Unix/Linux</th>
-<td width="20%" align="right"> <a accesskey="n" href="credits.html">Next</a>
-</td>
-</tr></table>
-<hr>
-</div>
-<div class="sect1">
-<div class="titlepage"><div><h2 class="title" style="clear: both">
-<a name="nextsteps"></a>Next Steps</h2></div></div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="install-next-backups"></a>Backup Strategy</h3></div></div>
-<p>Here are some tips from Don Baccus regarding backup strategy:</p>
-<p>
+<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"><title>Next Steps</title><meta name="generator" content="DocBook XSL Stylesheets V1.50.0"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="unix-install.html" title="Chapter 2. Installing on Unix/Linux"><link rel="previous" href="openacs.html" title="Install OpenACS 4.5"><link rel="next" href="credits.html" title="Credits"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="openacs.html">Prev</a> </td><th width="60%" align="center">Chapter 2. Installing on Unix/Linux</th><td width="20%" align="right"> <a accesskey="n" href="credits.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="nextsteps"></a>Next Steps</h2></div></div><div class="authorblurb"><p>
+ by <a href="mailto:vinod@kurup.com" target="_top">Vinod Kurup</a><br>
+ OpenACS docs are written by the named authors, but may be edited
+ by OpenACS documentation staff.
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="install-next-backups"></a>Backup Strategy</h3></div></div><p>Here are some tips from Don Baccus regarding backup strategy:</p><p>
The need for making backups should be self-explanatory. There are
several strategies you can use. My own strategy for minimizing the
odds that I'll lose all my data is quite simple:
- </p>
-<div class="itemizedlist"><ul>
-<li><p>
+ </p><div class="itemizedlist"><ul type="disc"><li><p>
The database is stored on a mirrored (RAID 1) disk.
- </p></li>
-<li><p>
+ </p></li><li><p>
The machine has battery backup.
- </p></li>
-<li><p>
+ </p></li><li><p>
Backups are made nightly onto a third disk on another controller
- </p></li>
-<li><p>
+ </p></li><li><p>
FTP is used to copy the resulting backup to two separate remote
servers in two locations
- </p></li>
-</ul></div>
-<p>
+ </p></li></ul></div><p>
Rather than making remote copies, you might choose to dump to tape or
writeable CD media. Whatever strategy you use, it is important to
routinely check dumps to make sure they can be reloaded. The strategy
@@ -61,46 +29,29 @@
use your nightly backup. Despite this, it is important to take
backups seriously if the data stored at your site is valuable to you
or your users.
- </p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="install-export-oracle"></a>Set Up Nightly Oracle Exports</h3></div></div>
-<p>
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="install-export-oracle"></a>Set Up Nightly Oracle Exports</h3></div></div><p>
While you're working with Oracle, you should configure it to do
automatic exports. An export is a separate backup copy of the
database. This copy includes all of the database's state at the
time that the export was initiated. If your database is corrupted,
you can restore from one of these backups. You should do this step as
<tt>root</tt>.
- </p>
-<div class="itemizedlist"><ul>
-<li><p>
+ </p><div class="itemizedlist"><ul type="disc"><li><p>
Download the backup script. Save the file <a href="files/export-oracle.txt" target="_top">export-oracle.txt</a> as
<tt>/tmp/export-oracle.txt</tt>
- </p></li>
-<li>
-<p>
+ </p></li><li><p>
Login as root. The following commands will install the export script:
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
nsadmin:~$ su -
Password: ***********
root:~# cp /tmp/export-oracle.txt /usr/sbin/export-oracle
-root:~# chmod 700 /usr/sbin/export-oracle</pre>
-</li>
-<li>
-<p>
+root:~# chmod 700 /usr/sbin/export-oracle</pre></li><li><p>
Setup the export directory; this is the directory where backups will
be stored. We recommend the directory
- <tt>/ora8/m02/oracle-exports</tt>. </p>
-<pre class="programlisting">
+ <tt>/ora8/m02/oracle-exports</tt>. </p><pre class="programlisting">
root:~# mkdir /ora8/m02/oracle-exports
root:~# chown oracle.dba /ora8/m02/oracle-exports
-root:~# chmod 770 /ora8/m02/oracle-exports</pre>
-</li>
-<li>
-<p>
+root:~# chmod 770 /ora8/m02/oracle-exports</pre></li><li><p>
Now edit
<tt>/usr/sbin/export-oracle</tt> and
change the <tt>SERVICE_NAME</tt> and
@@ -109,11 +60,9 @@
<tt>/ora8/m02/oracle-exports</tt>, you
also need to change the
<tt>exportdir</tt> setting.
- </p>
-<p>
+ </p><p>
Test the export procedure by running the command:
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
root:~# /usr/sbin/export-oracle
mv: /ora8/m02/oracle-exports/oraexport-service_name.dmp.gz: No such file or directory
@@ -150,92 +99,58 @@
. exporting dimensions
. exporting post-schema procedural objects and actions
. exporting statistics
-Export terminated successfully without warnings.</pre>
-<p>If you don't have any warnings, proceed to automate the
- backups.</p>
-</li>
-<li>
-<p>
+Export terminated successfully without warnings.</pre><p>If you don't have any warnings, proceed to automate the
+ backups.</p></li><li><p>
Automating backups is accomplished using the UNIX
- <tt>crontab</tt> facility.</p>
-<p>
+ <tt>crontab</tt> facility.</p><p>
While still <tt>root</tt>, run the
following command. You can replace the
<tt>EDITOR="emacs -nw"</tt>
portion with whatever editor your prefer, such as
<tt>EDITOR=vi</tt>.
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
root:~# export EDITOR="emacs -nw"
-root:~# crontab -e</pre>
-<p>Now add the following line on a line by itself </p>
-<pre class="programlisting">
-0 23 * * * /usr/sbin/export-oracle</pre>
-<p>
+root:~# crontab -e</pre><p>Now add the following line on a line by itself </p><pre class="programlisting">
+0 23 * * * /usr/sbin/export-oracle</pre><p>
Save the file, exit the editor. Verify that the addition
- succeeded by checking the output of the following command.</p>
-<pre class="programlisting">
+ succeeded by checking the output of the following command.</p><pre class="programlisting">
root:~# crontab -l | grep export-oracle
0 23 * * * /usr/sbin/export-oracle
root:~# exit
-; Logout</pre>
-<p>If you see the line, go ahead and log out.</p>
-</li>
-</ul></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="install-export-postgres"></a>Set up nightly Postgres exports</h3></div></div>
-<p>
+; Logout</pre><p>If you see the line, go ahead and log out.</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="install-export-postgres"></a>Set up nightly Postgres exports</h3></div></div><p>
Dowload <a href="files/acs-pgbackup-init.txt" target="_top">this script</a>
to <tt>/tmp</tt>. At the top of the script
are several variables that you'll need to customize:
- </p>
-<div class="itemizedlist"><ul>
-<li><p>
+ </p><div class="itemizedlist"><ul type="disc"><li><p>
<tt>bak</tt> - location where you want
local backups to be saved
- </p></li>
-<li><p>
+ </p></li><li><p>
<tt>servername</tt> - name of your server
(and database instance)
- </p></li>
-<li><p>
+ </p></li><li><p>
<tt>ftp_user</tt> - username on your ftp
account
- </p></li>
-<li><p>
+ </p></li><li><p>
<tt>ftp_password</tt> - password on your
ftp account
- </p></li>
-<li><p>
+ </p></li><li><p>
<tt>ftp_dir</tt> - path on the remote
server where your backups will be uploaded
- </p></li>
-<li><p>
+ </p></li><li><p>
<tt>ftp_server</tt> - your ftp server
- </p></li>
-</ul></div>
-<p>
+ </p></li></ul></div><p>
Next, we'll save this file to our server's
<tt>tcl</tt> directory so that it will be
loaded on startup. It will automatically be run every night at
midnight. Note that this script only backs up the database - not the
OpenACS scripts and file content.
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
nsadmin:~$ cp /tmp/acs-pgbackup-init.txt /web/birdnotes/tcl/acs-pgbackup-init.tcl
-nsadmin:~$ restart-aolserver birdnotes</pre>
-<p>
+nsadmin:~$ restart-aolserver birdnotes</pre><p>
That's it! The script will email you with each successful backup (or
if it fails, it will send you an email with the reason)
- </p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="install-next-nightly-vacuum"></a>Vacuum Postgres nightly</h3></div></div>
-<p>
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="install-next-nightly-vacuum"></a>Vacuum Postgres nightly</h3></div></div><p>
The "vacuum" command must be run periodically to reclaim space. The
"vacuum analyze" form additionally collects statistics on the
disbursion of columns in the database, which the optimizer uses when
@@ -248,252 +163,154 @@
backup! The "vacuum" command is very reliable, but conservatism is
the key to good system management. So, if you're using the export
procedure described above, you don't need to do this extra step.
- </p>
-<p>Edit your crontab:</p>
-<pre class="programlisting">
-nsadmin:~$ crontab -e</pre>
-<p>We'll set vacuum up to run nightly at 1 AM. Add the following
- line:</p>
-<pre class="programlisting">
-0 1 * * * /usr/local/pgsql/bin/vacuumdb birdnotes</pre>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="install-next-add-server"></a>How to add a second server on a different port</h3></div></div>
-<p>Starting another server is simply a matter of configuring another
+ </p><p>Edit your crontab:</p><pre class="programlisting">
+nsadmin:~$ crontab -e</pre><p>We'll set vacuum up to run nightly at 1 AM. Add the following
+ line:</p><pre class="programlisting">
+0 1 * * * /usr/local/pgsql/bin/vacuumdb birdnotes</pre></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="install-next-add-server"></a>How to add a second server on a different port</h3></div></div><p>Starting another server is simply a matter of configuring another
aolserver instance, creating another database and pointing this
aolserver instance at a fresh copy of the OpenACS-4 code. We'll call
- our new server <span class="emphasis"><i>birdnotes-dev</i></span>
-</p>
-<div class="orderedlist"><ol type="1">
-<li>
-<p>
+ our new server <span class="emphasis"><em>birdnotes-dev</em></span></p><div class="orderedlist"><ol type="1"><li><p>
Download another copy of <a href="files/openacs4.tcl.txt" target="_top"><tt>openacs4.tcl.txt</tt></a>
- into <tt>/tmp</tt>. </p>
-<pre class="programlisting">
-nsadmin:~$ cp /tmp/openacs4.tcl.txt ./<span class="emphasis"><i>birdnotes-dev</i></span>.tcl
-nsadmin:~$ chmod 660 <span class="emphasis"><i>birdnotes-dev</i></span>.tcl
-nsadmin:~$ emacs <span class="emphasis"><i>birdnotes-dev</i></span>.tcl</pre>
-<p>Just like in <a href="openacs.html#install-openacs-configure-aol" title="Configuring AOLserver">the section called “Configuring AOLserver”</a>,
+ into <tt>/tmp</tt>. </p><pre class="programlisting">
+nsadmin:~$ cp /tmp/openacs4.tcl.txt ./<span class="emphasis"><em>birdnotes-dev</em></span>.tcl
+nsadmin:~$ chmod 660 <span class="emphasis"><em>birdnotes-dev</em></span>.tcl
+nsadmin:~$ emacs <span class="emphasis"><em>birdnotes-dev</em></span>.tcl</pre><p>Just like in <a href="openacs.html#install-openacs-configure-aol" title="Configuring AOLserver">the section called “Configuring AOLserver”</a>,
you'll need to set the server parameters appropriately. Be sure to
choose a different port than your original server and to set
<tt>server</tt> to
- <span class="emphasis"><i>birdnotes-dev</i></span>.</p>
-</li>
-<li><p>
+ <span class="emphasis"><em>birdnotes-dev</em></span>.</p></li><li><p>
Create a new database instance called
- <span class="emphasis"><i>birdnotes-dev</i></span>. Follow the instructions in
+ <span class="emphasis"><em>birdnotes-dev</em></span>. Follow the instructions in
<a href="openacs.html#install-openacs-prepare-oracle">Prepare Oracle for OpenACS</a> or <a href="openacs.html#install-openacs-prepare-postgres">Prepare PostgreSQL for OpenACS</a>.
- </p></li>
-<li>
-<p>
+ </p></li><li><p>
You can either copy your current OpenACS installation:
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
nsadmin:~$ cd /web
-nsadmin:~$ cp -r birdnotes birdnotes-dev</pre>
-<p>
+nsadmin:~$ cp -r birdnotes birdnotes-dev</pre><p>
Or Download the <a href="http://www.openacs.org/software" target="_top">OpenACS
4 software</a> into <tt>/tmp</tt> again.
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
nsadmin:~$ cd /web
nsadmin:/web$ tar xzvf /tmp/alpha2.tgz
-nsadmin:/web$ mv openacs-4 birdnotes-dev</pre>
-</li>
-<li>
-<p>
+nsadmin:/web$ mv openacs-4 birdnotes-dev</pre></li><li><p>
Start your new server!
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
nsadmin:/web$ cd
-nsadmin:~$ /usr/local/aolserver/bin/nsd-postgres -t /usr/local/aolserver/<span class="emphasis"><i>birdnotes-dev</i></span>.tcl</pre>
-<p>
+nsadmin:~$ /usr/local/aolserver/bin/nsd-postgres -t /usr/local/aolserver/<span class="emphasis"><em>birdnotes-dev</em></span>.tcl</pre><p>
Visit the site with a web browser (using the port that you set
above). You should see the OpenACS installer. Once you install
the OpenACS datamodel, you'll also need to add your new aolserver
instance to <tt>/etc/inittab</tt> (or
- daemontools) so it restarts automatically.</p>
-</li>
-</ol></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="install-next-openfts"></a>Set up site-wide search</h3></div></div>
-<p>
+ daemontools) so it restarts automatically.</p></li></ol></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="install-next-openfts"></a>Set up site-wide search</h3></div></div><p>
OpenACS uses the <a href="http://openfts.sourceforge.net/" target="_top">OpenFTS</a> package to
implement site-wide-search. You'll need to have the Tcl development
libraries and headers installed. (Debian users:
<tt>apt-get install tcl8.3-dev</tt>)
- </p>
-<div class="orderedlist"><ol type="1">
-<li>
-<p>
+ </p><div class="orderedlist"><ol type="1"><li><p>
As <tt>root</tt>, download the
Search-OpenFTS driver.
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
nsadmin:~$ su -
Password: **********
root:~# cd /tmp
root:/tmp# wget http://prdownloads.sourceforge.net/openfts/Search-OpenFTS-tcl-0.2.tar.gz
root:~# cd /usr/local/src
root:/usr/local/src# tar xzf /tmp/Search-OpenFTS-tcl-0.2.tar.gz
root:/usr/local/src# chown -R nsadmin.web Search-OpenFTS-tcl-0.2
-root:/usr/local/src# exit</pre>
-</li>
-<li>
-<p>
+root:/usr/local/src# exit</pre></li><li><p>
Configure it. Note that you may need to set
<tt>--with-tcl=</tt>(your Tcl library
location). For Debian, add this to the end of the
<tt>./configure</tt> command:
<tt>--with-tcl=/usr/lib/tcl8.3</tt>
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
nsadmin:~$ cd /usr/local/src/Search-OpenFTS-tcl-0.2
-nsadmin:/usr/local/src/Search-OpenFTS-tcl-0.2$ ./configure --with-aolserver-src=/usr/local/src/aolserver/aolserver</pre>
-</li>
-<li>
-<p>
+nsadmin:/usr/local/src/Search-OpenFTS-tcl-0.2$ ./configure --with-aolserver-src=/usr/local/src/aolserver/aolserver</pre></li><li><p>
In order to compile on Debian, I had to edit my
<tt>Makefile.global</tt>. Add
<tt>-I/usr/include/tcl8.3</tt> to the
line where INC is defined, so it looks like this:
- </p>
-<pre class="programlisting">
-INC = ../include -I/usr/include/tcl8.3</pre>
-<p>Then compile it:</p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
+INC = ../include -I/usr/include/tcl8.3</pre><p>Then compile it:</p><pre class="programlisting">
nsadmin:/usr/local/src/Search-OpenFTS-tcl-0.2$ make
nsadmin:/usr/local/src/Search-OpenFTS-tcl-0.2$ cd aolserver
-nsadmin:/usr/local/src/Search-OpenFTS-tcl-0.2/aolserver$ make</pre>
-</li>
-<li>
-<p>
+nsadmin:/usr/local/src/Search-OpenFTS-tcl-0.2/aolserver$ make</pre></li><li><p>
Install it. You need to do this step as root since some of the
libraries will be installed alongside your TCL libraries and some
alongside your PostgreSQL libraries.
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
nsadmin:/usr/local/src/Search-OpenFTS-tcl-0.2/aolserver$ su -
Password: ***********
root:~# cd /usr/local/src/Search-OpenFTS-tcl-0.2
root:/usr/local/src/Search-OpenFTS-tcl-0.2# make install
root:/usr/local/src/Search-OpenFTS-tcl-0.2# exit
-nsadmin:/usr/local/src/Search-OpenFTS-tcl-0.2/aolserver$ cp nsfts.so /usr/local/aolserver/bin/</pre>
-</li>
-<li>
-<p>
+nsadmin:/usr/local/src/Search-OpenFTS-tcl-0.2/aolserver$ cp nsfts.so /usr/local/aolserver/bin/</pre></li><li><p>
Add the following line to your aolserver config file (in our
example:
<tt>/usr/local/aolserver/birdnotes.tcl</tt>)
in the "ns_section ns/server/${server}/modules" section:
- </p>
-<pre class="programlisting">
- ns_param nsfts ${bindir}/nsfts.so</pre>
-</li>
-<li>
-<p>
+ </p><pre class="programlisting">
+ ns_param nsfts ${bindir}/nsfts.so</pre></li><li><p>
Load the openFTS code into your database:
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
nsadmin:/usr/local/src/Search-OpenFTS-tcl-0.2/aolserver$ cd
-nsadmin:~$ psql -f /web/<span class="emphasis"><i>birdnotes</i></span>/packages/openfts-driver/sql/postgresql/load.sql <span class="emphasis"><i>birdnotes</i></span>
-nsadmin:~$ restart-aolserver <span class="emphasis"><i>birdnotes</i></span></pre>
-</li>
-<li><p>
+nsadmin:~$ psql -f /web/<span class="emphasis"><em>birdnotes</em></span>/packages/openfts-driver/sql/postgresql/load.sql <span class="emphasis"><em>birdnotes</em></span>
+nsadmin:~$ restart-aolserver <span class="emphasis"><em>birdnotes</em></span></pre></li><li><p>
Open a browser and go to your server
(http://yourserver:port). Click on the "Package Manager" link in
the "Quick Links" section on the right side of the page.
- </p></li>
-<li><p>
+ </p></li><li><p>
Click on the "Install packages" link and follow the instructions
to install the Note package and the OpenFTS Driver 4.2 package.
- </p></li>
-<li><p>
+ </p></li><li><p>
Restart your server.
<pre class="programlisting">
-nsadmin:~$ restart-aolserver <span class="emphasis"><i>birdnotes</i></span></pre>
- </p></li>
-<li><p>
+nsadmin:~$ restart-aolserver <span class="emphasis"><em>birdnotes</em></span></pre>
+ </p></li><li><p>
Give the server a few minutes to restart and then go back to your
server's front page and click on "Site Map" from the "Quick
Links"
- </p></li>
-<li><p>
+ </p></li><li><p>
Create a "new sub folder" under "Main Site". Call the url
"openfts".
- </p></li>
-<li><p> Click "mount" to mount the OpenFTS driver at the url
+ </p></li><li><p> Click "mount" to mount the OpenFTS driver at the url
"openfts" (despite what the system says about these packages not
being meant to be mounted)
- </p></li>
-<li><p>
+ </p></li><li><p>Click on "Set parameters" for the OpenFTS instance
+ and make sure that openfts_tcl_src_path properly points to your
+ local copy of the Search package source code. If you've followed
+ these directions strictly, you shouldn't need to change it.
+ </p></li><li><p>
Create another folder under "Main Site" at the url
"search". Create a "new application". Call the application
"Search" and choose the "Search" package from the drop-down list.
- </p></li>
-<li><p>
+ </p></li><li><p>
Create a third folder under "Main Site" at the url
"notes". Create a "new application". Call the application "Notes"
and choose the "Note" package from the drop-down list.
- </p></li>
-<li><p>
+ </p></li><li><p>
Restart the server.
- </p></li>
-<li><p>
+ </p></li><li><p>
Return to your home page. Near the bottom of the page, Click on
the "OpenFTS Driver" link. Then click on
"Administration". Finally, click on "Initialize OpenFTS
Engine". Accept the defaults and continue.
- </p></li>
-<li><p>
+ </p></li><li><p>
Click on the "Main Site" link to get back to the home page. Now,
click on the "ACS Service Contract" link near the bottom of the
home page.
- </p></li>
-<li><p>
+ </p></li><li><p>
Click on the link to "install" the FtsEngineDriver. Also, click
the link to install the Note content provider.
- </p></li>
-<li><p>
+ </p></li><li><p>
Restart the server. You can try inserting some notes and then
going to the search page to search for stuff. Note that the
content may not get indexed immediately, so give it a few
minutes.
- </p></li>
-</ol></div>
-</div>
-<p><div class="cvstag">($Id$)</div></p>
-</div>
-<div class="navfooter">
-<hr>
-<table width="100%" summary="Navigation footer">
-<tr>
-<td width="40%" align="left">
-<a accesskey="p" href="openacs.html">Prev</a> </td>
-<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
-<td width="40%" align="right"> <a accesskey="n" href="credits.html">Next</a>
-</td>
-</tr>
-<tr>
-<td width="40%" align="left">Install OpenACS 4.5 </td>
-<td width="20%" align="center"><a accesskey="u" href="unix-install.html">Up</a></td>
-<td width="40%" align="right"> Credits</td>
-</tr>
-</table>
-<hr>
-<address>
- rmello at fslc.usu.edu
- </address>
-<address><a href="mailto:vinod@kurup.com">
+ </p></li></ol></div></div><p><div class="cvstag">($Id$)</div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="openacs.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="credits.html">Next</a></td></tr><tr><td width="40%" align="left">Install OpenACS 4.5 </td><td width="20%" align="center"><a accesskey="u" href="unix-install.html">Up</a></td><td width="40%" align="right"> Credits</td></tr></table><hr><address>rmello at fslc.usu.edu</address><address><a href="mailto:vinod@kurup.com">
vinod@kurup.com
- </a></address>
-</div>
-</body>
-</html>
+ </a></address></div></body></html>
Index: openacs-4/packages/acs-core-docs/www/object-identity.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/object-identity.html,v
diff -u -r1.7 -r1.7.2.1
--- openacs-4/packages/acs-core-docs/www/object-identity.html 7 Mar 2002 06:55:36 -0000 1.7
+++ openacs-4/packages/acs-core-docs/www/object-identity.html 15 May 2002 23:26:18 -0000 1.7.2.1
@@ -1,92 +1,38 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type">
-<title>Object Identity</title>
-<meta name="generator" content="DocBook XSL Stylesheets V1.45">
-<link rel="home" href="index.html" title="OpenACS Documentation">
-<link rel="up" href="more-developer-info.html" title="Chapter 5. Other Developer Resources">
-<link rel="previous" href="parties.html" title="Parties in OpenACS 4.5">
-<link rel="next" href="programming-with-aolserver.html" title="Programming with AOLserver">
-<link rel="stylesheet" href="openacs.css" type="text/css">
-</head>
-<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-<div class="navheader">
-<a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr>
-<td width="20%" align="left">
-<a accesskey="p" href="parties.html">Prev</a> </td>
-<th width="60%" align="center">Chapter 5. Other Developer Resources</th>
-<td width="20%" align="right"> <a accesskey="n" href="programming-with-aolserver.html">Next</a>
-</td>
-</tr></table>
-<hr>
-</div>
-<div class="sect1">
-<div class="titlepage"><div><h2 class="title" style="clear: both">
-<a name="object-identity"></a>Object Identity</h2></div></div>
-<div class="authorblurb"><p>
-by <a href="http://planitia.org" target="_top">Rafael H. Schloming</a>
-</p></div>
-<p>One of the major design features of OpenACS 4.5 is the explicit representation
-of <span class="emphasis"><i>object identity</i></span>. The reason I say "explicit
+<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"><title>Object Identity</title><meta name="generator" content="DocBook XSL Stylesheets V1.50.0"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="more-developer-info.html" title="Chapter 5. Other Developer Resources"><link rel="previous" href="parties.html" title="Parties in OpenACS 4.5"><link rel="next" href="programming-with-aolserver.html" title="Programming with AOLserver"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="parties.html">Prev</a> </td><th width="60%" align="center">Chapter 5. Other Developer Resources</th><td width="20%" align="right"> <a accesskey="n" href="programming-with-aolserver.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="object-identity"></a>Object Identity</h2></div></div><div class="authorblurb"><p>
+by <a href="http://planitia.org" target="_top">Rafael H. Schloming</a><br>
+ OpenACS docs are written by the named authors, but may be edited
+ by OpenACS documentation staff.
+ </p></div><p>One of the major design features of OpenACS 4.5 is the explicit representation
+of <span class="emphasis"><em>object identity</em></span>. The reason I say "explicit
representation" is because the concept of object identity has been
around forever. It is inherent to our problem domain. Consider the example of
3.x style scoping. The 3.x data models use the triple (user_id, group_id,
-scope) to <span class="emphasis"><i>identify</i></span> an <span class="emphasis"><i>object</i></span>. In the 4.5 data model this
-object is <span class="emphasis"><i>explicitly represented</i></span> by a single party_id.</p>
-<p>Another good example of this is can be found in the user groups data
+scope) to <span class="emphasis"><em>identify</em></span> an <span class="emphasis"><em>object</em></span>. In the 4.5 data model this
+object is <span class="emphasis"><em>explicitly represented</em></span> by a single party_id.</p><p>Another good example of this is can be found in the user groups data
model. The 3.x user groups data model contains another example of an
-<span class="emphasis"><i>implied identity</i></span>. Every mapping between a user and a group could
+<span class="emphasis"><em>implied identity</em></span>. Every mapping between a user and a group could
have an arbitrary number of attached values (user_group_member_fields, etc.).
In this case it is the pair (group_id, user_id) that implicitly refers to an
object (the person's membership in a group). In the 4.5 data model this
object identity is made explicit by adding an integer primary key to the
-table that maps users to groups.</p>
-<p>Coming from a purely relational world, this might seem slightly weird at
+table that maps users to groups.</p><p>Coming from a purely relational world, this might seem slightly weird at
first. The pair (group_id, user_id) is sufficient to uniquely identify the
object in question, so why have the redundant integer primary key? If you
take a closer look, it actually isn't quite so redundant. If you want to
be able to use the object model's permissioning features, and generic
attribute features on a table, you need an integer primary key for that
table. This is because you can't really write a data model in oracle that
-uses more than one way to represent identity.</p>
-<p>So, this apparently redundant primary key has saved us the trouble of
+uses more than one way to represent identity.</p><p>So, this apparently redundant primary key has saved us the trouble of
duplicating the entire generic storage system for the special case of the
user_group_map, and has saved us from implementing ad-hoc security instead of
just using acs-permissions. This design choice is further validated by the
fact that services like journals that weren't previously thought to be
generic can in fact be generically applied to membership objects, thereby
allowing us to eliminated membership state auditing columns that weren't
-even capable of fully tracking the history of membership state.</p>
-<p>The design choice of explicitly representing object identity with an
+even capable of fully tracking the history of membership state.</p><p>The design choice of explicitly representing object identity with an
integer primary key that is derived from a globally unique sequence is the
-key to eliminating redundant code and replacing it with generic <span class="emphasis"><i>object
-level services</i></span>.</p>
-<p><div class="cvstag">($Id$)</div></p>
-</div>
-<div class="navfooter">
-<hr>
-<table width="100%" summary="Navigation footer">
-<tr>
-<td width="40%" align="left">
-<a accesskey="p" href="parties.html">Prev</a> </td>
-<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
-<td width="40%" align="right"> <a accesskey="n" href="programming-with-aolserver.html">Next</a>
-</td>
-</tr>
-<tr>
-<td width="40%" align="left">Parties in OpenACS 4.5 </td>
-<td width="20%" align="center"><a accesskey="u" href="more-developer-info.html">Up</a></td>
-<td width="40%" align="right"> Programming with AOLserver</td>
-</tr>
-</table>
-<hr>
-<address>
- rmello at fslc.usu.edu
- </address>
-<address><a href="mailto:vinod@kurup.com">
+key to eliminating redundant code and replacing it with generic <span class="emphasis"><em>object
+level services</em></span>.</p><p><div class="cvstag">($Id$)</div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="parties.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="programming-with-aolserver.html">Next</a></td></tr><tr><td width="40%" align="left">Parties in OpenACS 4.5 </td><td width="20%" align="center"><a accesskey="u" href="more-developer-info.html">Up</a></td><td width="40%" align="right"> Programming with AOLserver</td></tr></table><hr><address>rmello at fslc.usu.edu</address><address><a href="mailto:vinod@kurup.com">
vinod@kurup.com
- </a></address>
-</div>
-</body>
-</html>
+ </a></address></div></body></html>
Index: openacs-4/packages/acs-core-docs/www/object-system-design.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/object-system-design.html,v
diff -u -r1.5 -r1.5.2.1
--- openacs-4/packages/acs-core-docs/www/object-system-design.html 7 Mar 2002 06:55:36 -0000 1.5
+++ openacs-4/packages/acs-core-docs/www/object-system-design.html 15 May 2002 23:26:18 -0000 1.5.2.1
@@ -1,164 +1,58 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type">
-<title>OpenACS 4 Object Model Design</title>
-<meta name="generator" content="DocBook XSL Stylesheets V1.45">
-<link rel="home" href="index.html" title="OpenACS Documentation">
-<link rel="up" href="kernel-doc.html" title="Chapter 7. Kernel Documentation">
-<link rel="previous" href="object-system-requirements.html" title="OpenACS 4 Object Model Requirements">
-<link rel="next" href="permissions-requirements.html" title="OpenACS 4 Permissions Requirements">
-<link rel="stylesheet" href="openacs.css" type="text/css">
-</head>
-<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-<div class="navheader">
-<a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr>
-<td width="20%" align="left">
-<a accesskey="p" href="object-system-requirements.html">Prev</a> </td>
-<th width="60%" align="center">Chapter 7. Kernel Documentation</th>
-<td width="20%" align="right"> <a accesskey="n" href="permissions-requirements.html">Next</a>
-</td>
-</tr></table>
-<hr>
-</div>
-<div class="sect1">
-<div class="titlepage"><div><h2 class="title" style="clear: both">
-<a name="object-system-design"></a>OpenACS 4 Object Model Design</h2></div></div>
-<div class="authorblurb"><p>
+<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"><title>OpenACS 4 Object Model Design</title><meta name="generator" content="DocBook XSL Stylesheets V1.50.0"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="kernel-doc.html" title="Chapter 7. Kernel Documentation"><link rel="previous" href="object-system-requirements.html" title="OpenACS 4 Object Model Requirements"><link rel="next" href="permissions-requirements.html" title="OpenACS 4 Permissions Requirements"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="object-system-requirements.html">Prev</a> </td><th width="60%" align="center">Chapter 7. Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="permissions-requirements.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="object-system-design"></a>OpenACS 4 Object Model Design</h2></div></div><div class="authorblurb"><p>
by <a href="mailto:psu@arsdigita.com" target="_top">Pete Su</a>,
<a href="mailto:mcyoon@arsdigita.com" target="_top">Michael Yoon</a>,
<a href="mailto:richardl@arsdigita.com" target="_top">Richard Li</a>
- and <a href="mailto:rhs@arsdigita.com" target="_top">Rafael Schloming</a>
-</p></div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="object-system-design-essentials"></a>Essentials</h3></div></div>
-<div class="sect3">
-<div class="titlepage"><div><h4 class="title">
-<a name="objects-design-data-model"></a>Data Model</h4></div></div>
-<div class="itemizedlist"><ul>
-<li><p><a href="/doc/sql/display-sql?url=acs-metadata-create.sql&package_key=acs-kernel" target="_top">
-acs-metadata-create.sql</a></p></li>
-<li><p><a href="/doc/sql/display-sql?url=acs-objects-create.sql&package_key=acs-kernel" target="_top">
-acs-objects-create.sql</a></p></li>
-<li><p><a href="/doc/sql/display-sql?url=acs-relationships-create.sql&package_key=acs-kernel" target="_top">
-acs-relationships-create.sql</a></p></li>
-</ul></div>
-</div>
-<div class="sect3">
-<div class="titlepage"><div><h4 class="title">
-<a name="objects-design-tcl-files"></a>Tcl Files</h4></div></div>
-<p><span class="emphasis"><i>Not yet linked.</i></span></p>
-</div>
-<div class="sect3">
-<div class="titlepage"><div><h4 class="title">
-<a name="objects-design-requirements"></a>Requirements</h4></div></div>
-<div class="itemizedlist"><ul>
-<li><p><a href="object-system-requirements.html" title="OpenACS 4 Object Model Requirements">Object Model
-Requirements</a></p></li>
-<li><p><a href="groups-requirements.html" title="OpenACS 4 Groups Requirements">Groups
-Requirements</a></p></li>
-<li><p><a href="permissions-requirements.html" title="OpenACS 4 Permissions Requirements">Permissions
-Requirements</a></p></li>
-</ul></div>
-</div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="object-system-design-introduction"></a>Introduction</h3></div></div>
-<p>Before OpenACS 4, software developers writing OpenACS applications or modules
+ and <a href="mailto:rhs@arsdigita.com" target="_top">Rafael Schloming</a><br>
+ OpenACS docs are written by the named authors, but may be edited
+ by OpenACS documentation staff.
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="object-system-design-essentials"></a>Essentials</h3></div></div><div class="sect3"><div class="titlepage"><div><h4 class="title"><a name="objects-design-data-model"></a>Data Model</h4></div></div><div class="itemizedlist"><ul type="disc"><li><p><a href="/doc/sql/display-sql?url=acs-metadata-create.sql%26amp;package_key=acs-kernel" target="_top">
+acs-metadata-create.sql</a></p></li><li><p><a href="/doc/sql/display-sql?url=acs-objects-create.sql%26amp;package_key=acs-kernel" target="_top">
+acs-objects-create.sql</a></p></li><li><p><a href="/doc/sql/display-sql?url=acs-relationships-create.sql%26amp;package_key=acs-kernel" target="_top">
+acs-relationships-create.sql</a></p></li></ul></div></div><div class="sect3"><div class="titlepage"><div><h4 class="title"><a name="objects-design-tcl-files"></a>Tcl Files</h4></div></div><p><span class="emphasis"><em>Not yet linked.</em></span></p></div><div class="sect3"><div class="titlepage"><div><h4 class="title"><a name="objects-design-requirements"></a>Requirements</h4></div></div><div class="itemizedlist"><ul type="disc"><li><p><a href="object-system-requirements.html" title="OpenACS 4 Object Model Requirements">Object Model
+Requirements</a></p></li><li><p><a href="groups-requirements.html" title="OpenACS 4 Groups Requirements">Groups
+Requirements</a></p></li><li><p><a href="permissions-requirements.html" title="OpenACS 4 Permissions Requirements">Permissions
+Requirements</a></p></li></ul></div></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="object-system-design-introduction"></a>Introduction</h3></div></div><p>Before OpenACS 4, software developers writing OpenACS applications or modules
would develop each data model separately. However, many applications built on
OpenACS share certain characteristics or require certain common services.
-Examples of such services include:</p>
-<div class="itemizedlist"><ul>
-<li><p>User comments</p></li>
-<li><p>Storage of user-defined or extensible sets of attributes</p></li>
-<li><p>Access control</p></li>
-<li><p>General auditing and bookkeeping (e.g. creation date, IP addresses, and
-so forth)</p></li>
-<li><p>Presentation tools (e.g. how to display a field in a form or on a
-page)</p></li>
-</ul></div>
-<p>All of these services involve relating additional service-related
+Examples of such services include:</p><div class="itemizedlist"><ul type="disc"><li><p>User comments</p></li><li><p>Storage of user-defined or extensible sets of attributes</p></li><li><p>Access control</p></li><li><p>General auditing and bookkeeping (e.g. creation date, IP addresses, and
+so forth)</p></li><li><p>Presentation tools (e.g. how to display a field in a form or on a
+page)</p></li></ul></div><p>All of these services involve relating additional service-related
information to application data objects. Examples of application objects
-include:</p>
-<div class="itemizedlist"><ul>
-<li><p>Bboard messages</p></li>
-<li><p>A user home page</p></li>
-<li><p>A ticket in the ticket tracker</p></li>
-</ul></div>
-<p>In the past, developers had to use ad-hoc and inconsistent schemes to
+include:</p><div class="itemizedlist"><ul type="disc"><li><p>Bboard messages</p></li><li><p>A user home page</p></li><li><p>A ticket in the ticket tracker</p></li></ul></div><p>In the past, developers had to use ad-hoc and inconsistent schemes to
interface to various "general" services. OpenACS 4 defines a central
data model that keeps track of the application objects that we wish to
-manage, and serves as a primary store of <span class="emphasis"><i>metadata</i></span>. By
-<span class="emphasis"><i>metadata</i></span>, we mean data stored on behalf of an application
-<span class="emphasis"><i>outside</i></span> of the application's data model in order to enable
+manage, and serves as a primary store of <span class="emphasis"><em>metadata</em></span>. By
+<span class="emphasis"><em>metadata</em></span>, we mean data stored on behalf of an application
+<span class="emphasis"><em>outside</em></span> of the application's data model in order to enable
certain central services. The OpenACS 4 Object Model (or object system) manages
several different kinds of data and metadata to allow us to provide general
-services to applications:</p>
-<div class="itemizedlist"><ul>
-<li>
-<p>
-<a href="object-system-design.html#objects-design-object-ident">Object Identification</a> </p>
-<p>Every application object is given a unique identifier in the system. This
+services to applications:</p><div class="itemizedlist"><ul type="disc"><li><p><a href="object-system-design.html#objects-design-object-ident">Object Identification</a> </p><p>Every application object is given a unique identifier in the system. This
identifier can be used to find all data related to a particular object.
-</p>
-</li>
-<li>
-<p>
-<a href="object-system-design.html#objects-design-obj-context">Object Context and Access Control</a> </p>
-<p>Every object is created in a particular security context, so the system
+</p></li><li><p><a href="object-system-design.html#objects-design-obj-context">Object Context and Access Control</a> </p><p>Every object is created in a particular security context, so the system
can provide centralized access control.
-</p>
-</li>
-<li>
-<p>
-<a href="object-system-design.html#objects-design-object-types">Object Types and Attributes</a> </p>
-<p>Objects are instances of developer-defined object types. Object types
+</p></li><li><p><a href="object-system-design.html#objects-design-object-types">Object Types and Attributes</a> </p><p>Objects are instances of developer-defined object types. Object types
allow developers to customize the data that is stored with each object.
-</p>
-</li>
-<li>
-<p>
-<a href="object-system-design.html#objects-design-relation-types">Relation Types</a> </p>
-<p>Relation types provide a general mechanism for mapping instances of one
+</p></li><li><p><a href="object-system-design.html#objects-design-relation-types">Relation Types</a> </p><p>Relation types provide a general mechanism for mapping instances of one
object type (e.g. users) to instances of another object type (e.g.
groups).
-</p>
-</li>
-</ul></div>
-<p>The next section will explore these facilities in the context of the the
-particular programming idioms that we wish to generalize.</p>
-<p><span class="strong"><i>Related Links</i></span></p>
-<p>This design document should be read along with the design documents for <a href="groups-design.html" title="OpenACS 4 Groups Design">the new groups system</a>, <a href="subsites-design.html" title="OpenACS 4 Subsites Design Document">subsites</a> and <a href="permissions-design.html" title="OpenACS 4 Permissions Design">the permissions system</a>
-</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="object-system-design-history"></a>History</h3></div></div>
-<p>The motivation for most of the facilities in the OpenACS 4 Object Model can be
+</p></li></ul></div><p>The next section will explore these facilities in the context of the the
+particular programming idioms that we wish to generalize.</p><p><span class="strong"><em>Related Links</em></span></p><p>This design document should be read along with the design documents for <a href="groups-design.html" title="OpenACS 4 Groups Design">the new groups system</a>, <a href="subsites-design.html" title="OpenACS 4 Subsites Design Document">subsites</a> and <a href="permissions-design.html" title="OpenACS 4 Permissions Design">the permissions system</a></p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="object-system-design-history"></a>History</h3></div></div><p>The motivation for most of the facilities in the OpenACS 4 Object Model can be
understood in the context of the 3.x code base and the kinds of programming
-idioms that evolved there. These are listed and discussed below.</p>
-<div class="sect3">
-<div class="titlepage"><div><h4 class="title">
-<a name="objects-design-object-ident"></a>Object Identification</h4></div></div>
-<p>Object identification is a central mechanism in OpenACS 4. Every application
+idioms that evolved there. These are listed and discussed below.</p><div class="sect3"><div class="titlepage"><div><h4 class="title"><a name="objects-design-object-ident"></a>Object Identification</h4></div></div><p>Object identification is a central mechanism in OpenACS 4. Every application
object in OpenACS 4 has a unique ID which is mapped to a row in a central table
called <tt>acs_objects</tt>. Developers that wish to use OpenACS 4 services
need only take a few simple steps to make sure that their application objects
appear in this table. The fact that every object has a known unique
identifier means that the core can deal with all objects in a generic way. In
other words, we use object identifiers to enable centralized services in a
-global and uniform manner.</p>
-<p><span class="emphasis"><i>Implicit Object Identifiers in OpenACS 3.x</i></span></p>
-<p>The motivation for implementing general object identifiers comes from
+global and uniform manner.</p><p><span class="emphasis"><em>Implicit Object Identifiers in OpenACS 3.x</em></span></p><p>The motivation for implementing general object identifiers comes from
several observations of data models in OpenACS 3.x. Many modules use a
<tt>(user_id, group_id, scope)</tt> column-triple for the purpose of
recording ownership information on objects, for access control. User/groups
also uses <tt>(user_id, group_id)</tt> pairs in its
<tt>user_group_map</tt> table as a way to identify data associated with a
-single membership relation.</p>
-<p>Also, in OpenACS 3.x many utility modules exist that do nothing more than
+single membership relation.</p><p>Also, in OpenACS 3.x many utility modules exist that do nothing more than
attach some extra attributes to existing application data. For example,
general comments maintains a table that maps application "page"
data (static or dynamic pages on the website) to one or more user comments on
@@ -168,14 +62,11 @@
as the "(on_which_table + on_what_id)" method for identifying
application data. In particular, general comments stores its map from pages
to comments using a "(on_which_table + on_what_id)" key plus the ID
-of the comment itself.</p>
-<p>All of these composite key constructions are implicit object identifiers -
+of the comment itself.</p><p>All of these composite key constructions are implicit object identifiers -
they build a unique ID out of other pieces of the data model. The problem is
that their definition and use is ad-hoc and inconsistent, making the
construction of generic application-independent services unnecessarily
-difficult.</p>
-<p><span class="emphasis"><i>Object Identifiers in OpenACS 4</i></span></p>
-<p>The OpenACS 4 Object Model defines a single mechanism that applications use to
+difficult.</p><p><span class="emphasis"><em>Object Identifiers in OpenACS 4</em></span></p><p>The OpenACS 4 Object Model defines a single mechanism that applications use to
attach unique identifiers to application data. This identifier is the primary
key of the <tt>acs_objects</tt> table. This table forms the core of what
we need to provide generic services like access control, general attribute
@@ -186,122 +77,60 @@
make sure every object the system is to manage is associated with a row in
<tt>acs_objects</tt>. More importantly, if they do this, new services
like general comments can be created without requiring existing applications
-to "hook into" them via new metadata.</p>
-<p>
-<span class="strong"><i>Note:</i></span> Object identifiers are a good example of metadata
+to "hook into" them via new metadata.</p><p><span class="strong"><em>Note:</em></span> Object identifiers are a good example of metadata
in the new system. Each row in <tt>acs_objects</tt> stores information
-<span class="emphasis"><i>about</i></span> the application object, but not the application object itself.
+<span class="emphasis"><em>about</em></span> the application object, but not the application object itself.
This becomes more clear if you skip ahead and look at the SQL schema code
-that defines this table.</p>
-</div>
-<div class="sect3">
-<div class="titlepage"><div><h4 class="title">
-<a name="objects-design-obj-context"></a>Object Context and Access Control</h4></div></div>
-<p>Until the implementation of the general permissions system, every OpenACS
+that defines this table.</p></div><div class="sect3"><div class="titlepage"><div><h4 class="title"><a name="objects-design-obj-context"></a>Object Context and Access Control</h4></div></div><p>Until the implementation of the general permissions system, every OpenACS
application had to manage access control to its data separately. Later on, a
-notion of "scoping" was introduced into the core data model.</p>
-<p>"Scope" is a term best explained by example. Consider some
-hypothetical rows in the <tt>address_book</tt> table:</p>
-<blockquote class="blockquote"><div class="informaltable"><table border="1">
-<colgroup>
-<col>
-<col>
-<col>
-</colgroup>
-<tbody>
-<tr>
-<td><span class="strong"><i>...</i></span></td>
-<td><span class="strong"><i><tt>scope</tt></i></span></td>
-<td><span class="strong"><i><tt>user_id</tt></i></span></td>
-<td><span class="strong"><i><tt>group_id</tt></i></span></td>
-<td><span class="strong"><i>...</i></span></td>
-</tr>
-<tr>
-<td>...</td>
-<td><tt>user</tt></td>
-<td><tt>123</tt></td>
-<td>�</td>
-<td>...</td>
-</tr>
-<tr>
-<td>...</td>
-<td><tt>group</tt></td>
-<td>�</td>
-<td><tt>456</tt></td>
-<td>...</td>
-</tr>
-<tr>
-<td>...</td>
-<td><tt>public</tt></td>
-<td>�</td>
-<td>�</td>
-<td>...</td>
-</tr>
-</tbody>
-</table></div></blockquote>
-<p>The first row represents an entry in User 123's personal address book,
+notion of "scoping" was introduced into the core data model.</p><p>"Scope" is a term best explained by example. Consider some
+hypothetical rows in the <tt>address_book</tt> table:</p><blockquote class="blockquote"><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><tbody><tr><td><span class="strong"><em>...</em></span></td><td><span class="strong"><em><tt>scope</tt></em></span></td><td><span class="strong"><em><tt>user_id</tt></em></span></td><td><span class="strong"><em><tt>group_id</tt></em></span></td><td><span class="strong"><em>...</em></span></td></tr><tr><td>...</td><td><tt>user</tt></td><td><tt>123</tt></td><td>�</td><td>...</td></tr><tr><td>...</td><td><tt>group</tt></td><td>�</td><td><tt>456</tt></td><td>...</td></tr><tr><td>...</td><td><tt>public</tt></td><td>�</td><td>�</td><td>...</td></tr></tbody></table></div></blockquote><p>The first row represents an entry in User 123's personal address book,
the second row represents an entry in User Group 456's shared address
book, and the third row represents an entry in the site's public address
-book.</p>
-<p>In this way, the scoping columns identify the security context in which a
-given object belongs, where each context is <span class="emphasis"><i>either</i></span> a person
-<span class="emphasis"><i>or</i></span> a group of people <span class="emphasis"><i>or</i></span> the general public (itself a group
-of people).</p>
-<p>In OpenACS 4, rather than breaking the world into a limited set of scopes,
-every object lives in a single <span class="emphasis"><i>context</i></span>. A context is just an
+book.</p><p>In this way, the scoping columns identify the security context in which a
+given object belongs, where each context is <span class="emphasis"><em>either</em></span> a person
+<span class="emphasis"><em>or</em></span> a group of people <span class="emphasis"><em>or</em></span> the general public (itself a group
+of people).</p><p>In OpenACS 4, rather than breaking the world into a limited set of scopes,
+every object lives in a single <span class="emphasis"><em>context</em></span>. A context is just an
abstract name for the default security domain to which the object belongs.
Each context has a unique identifier, and all the contexts in a system form a
tree. Often this tree will reflect an observed hierarchy in a site, e.g. a
bboard message would probably list a bboard topic as its context, and a
bboard topic might list a subsite as its context. Thus, contexts make it
easier to break the site up into security domains according to its natural
structure. An object's context is stored in the <tt>context_id</tt>
-column of the <tt>acs_objects</tt> table.</p>
-<p>We use an object's context to provide a default answer to questions
+column of the <tt>acs_objects</tt> table.</p><p>We use an object's context to provide a default answer to questions
regarding access control. Whenever we ask a question of the form "can
user X perform action Y on object Z", the OpenACS security model will defer
to an object's context if there is no information about user X's
-permission to perform action Y on object Z.</p>
-<p>The context system forms the basis for the rest of the OpenACS access control
+permission to perform action Y on object Z.</p><p>The context system forms the basis for the rest of the OpenACS access control
system, which is described in in two separate documents: one for the <a href="permissions-design.html" title="OpenACS 4 Permissions Design">permissions system</a> and another for the
<a href="groups-design.html" title="OpenACS 4 Groups Design">party groups</a> system. The context system
-is also used to implement <a href="subsites-design.html" title="OpenACS 4 Subsites Design Document">subsites</a>.</p>
-</div>
-<div class="sect3">
-<div class="titlepage"><div><h4 class="title">
-<a name="objects-design-obj-types"></a>Object Types</h4></div></div>
-<p>As mentioned above, many OpenACS modules provide extensible data models, and
+is also used to implement <a href="subsites-design.html" title="OpenACS 4 Subsites Design Document">subsites</a>.</p></div><div class="sect3"><div class="titlepage"><div><h4 class="title"><a name="objects-design-obj-types"></a>Object Types</h4></div></div><p>As mentioned above, many OpenACS modules provide extensible data models, and
need to use application specific mechanisms to keep track of user defined
attributes and to map application data to these attributes. In the past,
modules either used user/groups or their own ad hoc data model to provide
-this functionality.</p>
-<p><span class="emphasis"><i>User/Groups in OpenACS 3.x</i></span></p>
-<p>The user/group system allowed developers to define <span class="emphasis"><i>group types</i></span>
+this functionality.</p><p><span class="emphasis"><em>User/Groups in OpenACS 3.x</em></span></p><p>The user/group system allowed developers to define <span class="emphasis"><em>group types</em></span>
along with attributes to be stored with each instance of a group type. Each
group type could define a helper table that stored attributes on each
instance of the group type. This table was called the
"<tt>_info</tt>" table because the name was generated by
-appending <tt>_info</tt> to the name of the group type.</p>
-<p>The user/groups data model also provided the
+appending <tt>_info</tt> to the name of the group type.</p><p>The user/groups data model also provided the
<tt>user_group_type_member_fields</tt> and
<tt>user_group_member_fields</tt> tables to define attributes for members
of groups of a specific type and for members of a specific group,
respectively. The <tt>user_group_member_field_map</tt> table stored
values for both categories of attributes in its <tt>field_value</tt>
column. These tables allowed developers and users to define custom sets of
attributes to store on groups and group members without changing the data
-model at the code level.</p>
-<p>Many applications in OpenACS 3.x and earlier used the group type mechanism in
+model at the code level.</p><p>Many applications in OpenACS 3.x and earlier used the group type mechanism in
ways that were only tangentially related to groups of users, just to obtain
access to this group types mechanism. Thus the motivation for generalizing
-the group types mechanism in OpenACS 4.</p>
-<p><span class="emphasis"><i>Object Types and Subtypes</i></span></p>
-<p>In OpenACS 4 <span class="emphasis"><i>object types</i></span> generalize the OpenACS 3.x notion of group
+the group types mechanism in OpenACS 4.</p><p><span class="emphasis"><em>Object Types and Subtypes</em></span></p><p>In OpenACS 4 <span class="emphasis"><em>object types</em></span> generalize the OpenACS 3.x notion of group
types. Each object type can define one or more attributes to be attached to
instances of the type. This allows developers to define new types without
-being artificially tied to a particular module (i.e. user/groups).</p>
-<p>In addition, the OpenACS 4 object model provides mechanism for defining
-<span class="emphasis"><i>subtypes</i></span> of existing types. A subtype of a parent type inherits all
+being artificially tied to a particular module (i.e. user/groups).</p><p>In addition, the OpenACS 4 object model provides mechanism for defining
+<span class="emphasis"><em>subtypes</em></span> of existing types. A subtype of a parent type inherits all
the attributes defined in the parent type, and can define some of its own.
The motivation for subtypes comes from the need for OpenACS to be more
extensible. In OpenACS 3.x, many applications extended the core data models by
@@ -310,50 +139,34 @@
containing a hodge podge of unrelated information that should have been
normalized away. The canonical example of this is the explosion of the
<tt>users</tt> table in OpenACS 3.x. In addition to being sloppy technically,
-these fat tables have a couple of other problems:</p>
-<div class="itemizedlist"><ul>
-<li><p>They degrade performance.</p></li>
-<li><p>Denormalization can make it hard to maintain consistency constraints on
-the data.</p></li>
-</ul></div>
-<p>Object subtypes provide a way to factor the data model while still keeping
+these fat tables have a couple of other problems:</p><div class="itemizedlist"><ul type="disc"><li><p>They degrade performance.</p></li><li><p>Denormalization can make it hard to maintain consistency constraints on
+the data.</p></li></ul></div><p>Object subtypes provide a way to factor the data model while still keeping
track of the fact that each member of a subtype (i.e. for each row in the
subtype's table), is also a member of the parent type (i.e. there is a
corresponding row in the parent type table). Therefore, applications an use
this mechanism without worrying about this bookkeeping themselves, and we
avoid having applications pollute the core data model with their specific
-information.</p>
-</div>
-<div class="sect3">
-<div class="titlepage"><div><h4 class="title">
-<a name="objects-design-attributes"></a>Object Attributes, Skinny Tables</h4></div></div>
-<p>As we described above, the OpenACS 3.x user/groups system stored object
+information.</p></div><div class="sect3"><div class="titlepage"><div><h4 class="title"><a name="objects-design-attributes"></a>Object Attributes, Skinny Tables</h4></div></div><p>As we described above, the OpenACS 3.x user/groups system stored object
attributes in two ways. The first was to use columns in the helper table. The
second consisted of two tables, one describing attributes and one storing
values, to provide a flexible means for attaching attributes to metadata
objects. This style of attribute storage is used in several other parts of
OpenACS 3.x, and we will refer to it as "skinny tables". For
-example:</p>
-<div class="itemizedlist"><ul>
-<li><p>In the Ecommerce data model, the <tt>ec_custom_product_fields</tt>
+example:</p><div class="itemizedlist"><ul type="disc"><li><p>In the Ecommerce data model, the <tt>ec_custom_product_fields</tt>
table defines attributes for catalog products, and the
<tt>ec_custom_product_field_values</tt> table stores values for those
-attributes.</p></li>
-<li><p>In the Photo DB data model, the <tt>ph_custom_photo_fields</tt> table
+attributes.</p></li><li><p>In the Photo DB data model, the <tt>ph_custom_photo_fields</tt> table
defines attributes for the photographs owned by a specific user, and tables
named according to the convention
"<tt>ph_user_<user_id>_custom_info</tt>" are used to
-store values for those attributes.</p></li>
-</ul></div>
-<p>In addition, there are some instances where we are not using this model
-but <span class="emphasis"><i>should</i></span>, e.g. the <tt>users_preferences</tt> table, which
+store values for those attributes.</p></li></ul></div><p>In addition, there are some instances where we are not using this model
+but <span class="emphasis"><em>should</em></span>, e.g. the <tt>users_preferences</tt> table, which
stores preferences for registered users in columns such as
<tt>prefer_text_only_p</tt> and <tt>dont_spam_me_p</tt>. The
"standard" way for an OpenACS 3.x-based application to add to the list
of user preferences is to add a column to the <tt>users_preferences</tt>
table (exactly the kind of data model change that has historically
-complicated the process of upgrading to a more recent OpenACS version).</p>
-<p>The Objet Model generalizes the scheme used in the old OpenACS 3.x user/groups
+complicated the process of upgrading to a more recent OpenACS version).</p><p>The Objet Model generalizes the scheme used in the old OpenACS 3.x user/groups
system. It defines a table called <tt>acs_attributes</tt> that record
what attributes belong to which object types, and how the attributes are
stored. As before, attributes can either be stored in helper tables, or in a
@@ -364,12 +177,7 @@
skinny tables because doing so allows developers and users to dynamically
update the set of attributes stored on an object without updating the data
model at the code level. The bottom line: Helper tables are more functional
-and more efficient, skinny tables are more flexible but limited.</p>
-</div>
-<div class="sect3">
-<div class="titlepage"><div><h4 class="title">
-<a name="objects-design-relation-types"></a>Relation Types</h4></div></div>
-<p>Many OpenACS 3.x modules use <span class="emphasis"><i>mapping tables</i></span> to model relationships
+and more efficient, skinny tables are more flexible but limited.</p></div><div class="sect3"><div class="titlepage"><div><h4 class="title"><a name="objects-design-relation-types"></a>Relation Types</h4></div></div><p>Many OpenACS 3.x modules use <span class="emphasis"><em>mapping tables</em></span> to model relationships
between application objects. Again, the 3.x user/groups system provides the
canonical example of this design style. In that system, there was a single
table called <tt>user_group_map</tt> that kept track of which users
@@ -378,45 +186,31 @@
<tt>user_group_member_fields_map</tt> tables to allow developers to
attach custom attributes to group members. In fact, these attributes were not
really attached to the users, but to the fact that a user was a member of a
-particular group - a subtle but important distinction.</p>
-<p>In OpenACS 4, <span class="emphasis"><i>relation types</i></span> generalize this mechanism. Relation
+particular group - a subtle but important distinction.</p><p>In OpenACS 4, <span class="emphasis"><em>relation types</em></span> generalize this mechanism. Relation
types allow developers to define general mappings from objects of a given
type T, to other objects of a given type R. Each relation type is a subtype
of <tt>acs_object</tt>, extended with extra attributes that store
constraints on the relation, and the types of objects the relation actually
maps. In turn, each instance of a relation type is an object that represents
a single fact of the form "the object t of type T is related to the
object r of type R." That is, each instance of a relation type is
-essentially just a pair of objects.</p>
-<p>Relation types generalize mapping tables. For example, the 3.x user/groups
+essentially just a pair of objects.</p><p>Relation types generalize mapping tables. For example, the 3.x user/groups
data model can be largely duplicated using a single relation type describing
the "group membership" relation. Group types would then be subtypes
of this membership relation type. Group type attributes would be attached to
the relation type itself. Group member attributes would be attached to
instances of the membership relation. Finally, the mapping table would be
-replaced by a central skinny table that the relation type system defines.</p>
-<p>Relation types should be used when you want to be able to attach data to
+replaced by a central skinny table that the relation type system defines.</p><p>Relation types should be used when you want to be able to attach data to
the "fact" that object X and object Y are related to each other. On
the face of it, they seem like a redundant mechanism however, since one could
easily create a mapping table to do the same thing. The advantage of
registering this table as a relation type is that in principle the OpenACS 4
object system could use the meta data in the types table to do useful things
in a generic way on all relation types. But this mechanism doesn't really
-exist yet.</p>
-<p>Relation types are a somewhat abstract idea. To get a better feel for
-them, you should just skip to the <a href="object-system-design.html#object-system-design-relsmodel">data model</a>.</p>
-</div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="object-system-design-summary"></a>Summary and Design Considerations</h3></div></div>
-<p>The OpenACS 4 Object Model is designed to generalize and unify the following
+exist yet.</p><p>Relation types are a somewhat abstract idea. To get a better feel for
+them, you should just skip to the <a href="object-system-design.html#object-system-design-relsmodel">data model</a>.</p></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="object-system-design-summary"></a>Summary and Design Considerations</h3></div></div><p>The OpenACS 4 Object Model is designed to generalize and unify the following
mechanisms that are repeatedly implemented in OpenACS-based systems to manage
-generic and application specific metadata:</p>
-<div class="sect3">
-<div class="titlepage"><div><h4 class="title">
-<a name="objects-design-why-not-objdb"></a>Why not Object Databases?</h4></div></div>
-<p>The presence of a framework for subtyping and inheritance always brings up
+generic and application specific metadata:</p><div class="sect3"><div class="titlepage"><div><h4 class="title"><a name="objects-design-why-not-objdb"></a>Why not Object Databases?</h4></div></div><p>The presence of a framework for subtyping and inheritance always brings up
the question of why we don't just use an object database. The main reason
is that all of the major object database vendors ship products that are
effectively tied to some set of object oriented programming languages. Their
@@ -429,8 +223,7 @@
expressible in the host language. In particular, we lose many of the best
features of the relational database model. This is a disaster from an ease of
use standpoint.
- </p>
-<p>The "Object relational" systems provide an interesting
+ </p><p>The "Object relational" systems provide an interesting
alternative. Here, some notion of subtyping is embedded into an existing SQL
or SQL-like database engine. Examples of systems like this include the new
Informix, PostgreSQL 7, and Oracle has something like this too. The main
@@ -441,64 +234,34 @@
practice. Finally, object databases are not as widely used as traditional
relational systems. They have not been tested as extensively and their
scalability to very large databases is not proven (though some will disagree
-with this statement).</p>
-</div>
-<div class="sect3">
-<div class="titlepage"><div><h4 class="title">
-<a name="objects-design-oracle"></a>Oracle</h4></div></div>
-<p>The conclusion: the best design is to add a limited notion of subtyping to
+with this statement).</p></div><div class="sect3"><div class="titlepage"><div><h4 class="title"><a name="objects-design-oracle"></a>Oracle</h4></div></div><p>The conclusion: the best design is to add a limited notion of subtyping to
our existing relational data model. By doing this, we retain all the power of
the relational data model while gaining the object oriented features we need
-most.</p>
-<p>In the context of OpenACS 4, this means using the object model to make our
+most.</p><p>In the context of OpenACS 4, this means using the object model to make our
data models more flexible, so that new modules can easily gain access to
generic features. However, while the API itself doesn't enforce the idea
that applications only use the object model for metadata, it is also the case
that the data model is not designed to scale to large type hierarchies. In
the more limited domain of the metadata model, this is acceptable since the
type hierarchy is fairly small. But the object system data model is not
designed to support, for example, a huge type tree like the Java runtime
-libraries might define.</p>
-<p>This last point cannot be over-stressed: <span class="strong"><i>the object model is not
-meant to be used for large scale application data storage</i></span>. It is
-meant to represent and store metadata, not application data.</p>
-</div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="object-system-design-datamodel"></a>Data Model</h3></div></div>
-<p>Like most data models, the OpenACS Core data model has two levels:</p>
-<div class="orderedlist"><ol type="1">
-<li><p>The <span class="emphasis"><i>knowledge level</i></span> (i.e. the metadata model)</p></li>
-<li><p>The <span class="emphasis"><i>operational level</i></span> (i.e. the concrete data model)</p></li>
-</ol></div>
-<p>
+libraries might define.</p><p>This last point cannot be over-stressed: <span class="strong"><em>the object model is not
+meant to be used for large scale application data storage</em></span>. It is
+meant to represent and store metadata, not application data.</p></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="object-system-design-datamodel"></a>Data Model</h3></div></div><p>Like most data models, the OpenACS Core data model has two levels:</p><div class="orderedlist"><ol type="1"><li><p>The <span class="emphasis"><em>knowledge level</em></span> (i.e. the metadata model)</p></li><li><p>The <span class="emphasis"><em>operational level</em></span> (i.e. the concrete data model)</p></li></ol></div><p>
You can browse the data models themselves from here:
-</p>
-<div class="itemizedlist"><ul>
-<li><p><a href="/doc/sql/display-sql?url=acs-metadata-create.sql&package_key=acs-kernel" target="_top">
-acs-metadata-create.sql</a></p></li>
-<li><p><a href="/doc/sql/display-sql?url=acs-objects-create.sql&package_key=acs-kernel" target="_top">
-acs-objects-create.sql</a></p></li>
-<li><p><a href="/doc/sql/display-sql?url=acs-relationships-create.sql&package_key=acs-kernel" target="_top">
-acs-relationships-create.sql</a></p></li>
-</ul></div>
-<p>(Note that we have subdivided the operational level into the latter two
-files.)</p>
-<p>The operational level depends on the knowledge level, so we discuss the
+</p><div class="itemizedlist"><ul type="disc"><li><p><a href="/doc/sql/display-sql?url=acs-metadata-create.sql%26amp;package_key=acs-kernel" target="_top">
+acs-metadata-create.sql</a></p></li><li><p><a href="/doc/sql/display-sql?url=acs-objects-create.sql%26amp;package_key=acs-kernel" target="_top">
+acs-objects-create.sql</a></p></li><li><p><a href="/doc/sql/display-sql?url=acs-relationships-create.sql%26amp;package_key=acs-kernel" target="_top">
+acs-relationships-create.sql</a></p></li></ul></div><p>(Note that we have subdivided the operational level into the latter two
+files.)</p><p>The operational level depends on the knowledge level, so we discuss the
knowledge level first. In the text below, we include abbreviated versions of
the SQL definitions of many tables. Generally, these match the actual
definitions in the existing data model but they are meant to reflect design
information, not implementation. Some less relevant columns may be left out,
-and things like constraint names are not included.</p>
-<div class="sect3">
-<div class="titlepage"><div><h4 class="title">
-<a name="objects-design-knowledge-level"></a>Knowledge-Level Model</h4></div></div>
-<p>The knowledge level data model for OpenACS objects centers around three tables
+and things like constraint names are not included.</p><div class="sect3"><div class="titlepage"><div><h4 class="title"><a name="objects-design-knowledge-level"></a>Knowledge-Level Model</h4></div></div><p>The knowledge level data model for OpenACS objects centers around three tables
that keep track of object types, attributes, and relation types. The first
table is <tt>acs_object_types</tt>, shown here in an abbreviated
-form:</p>
-<pre class="programlisting">
+form:</p><pre class="programlisting">
<tt>create table acs_object_types (
object_type varchar(100) not null primary key,
@@ -513,33 +276,22 @@
);
</tt>
-</pre>
-<p>This table contains one row for every object type in the system. The key
-things to note about this table are:</p>
-<div class="itemizedlist"><ul>
-<li><p>For every type, we store metadata for how to display this type in certain
-contexts (<tt>pretty_name</tt> and <tt>pretty_plural</tt>).</p></li>
-<li><p>If the type is a subtype, then its parent type is stored in the column
-<tt>supertype</tt>.</p></li>
-<li><p>We support a notion of "abstract" types that contain no
+</pre><p>This table contains one row for every object type in the system. The key
+things to note about this table are:</p><div class="itemizedlist"><ul type="disc"><li><p>For every type, we store metadata for how to display this type in certain
+contexts (<tt>pretty_name</tt> and <tt>pretty_plural</tt>).</p></li><li><p>If the type is a subtype, then its parent type is stored in the column
+<tt>supertype</tt>.</p></li><li><p>We support a notion of "abstract" types that contain no
instances (as of 9/2000 this is not actually used). These types exist only to
be subtyped. An example might be a type representing "shapes" that
contains common characteristics of all shapes, but which is only used to
create subtypes that represent real, concrete shapes like circles, squares,
-and so on.</p></li>
-<li><p>Every type defines a table in which one can find one row for every
-instance of this type (<tt>table_name</tt>, <tt>id_column</tt>).</p></li>
-<li><p>
-<tt>type_extension_table</tt> is for naming a table that stores extra
-generic attributes.</p></li>
-</ul></div>
-<p>The second table we use to describe types is <tt>acs_attributes</tt>.
+and so on.</p></li><li><p>Every type defines a table in which one can find one row for every
+instance of this type (<tt>table_name</tt>, <tt>id_column</tt>).</p></li><li><p><tt>type_extension_table</tt> is for naming a table that stores extra
+generic attributes.</p></li></ul></div><p>The second table we use to describe types is <tt>acs_attributes</tt>.
Each row in this table represents a single attribute on a specific object
type (e.g. the "password" attribute of the "user" type).
Again, here is an abbreviated version of what this table looks like. The
actual table used in the implementation is somewhat different and is
-discussed in a separate document.</p>
-<pre class="programlisting">
+discussed in a separate document.</p><pre class="programlisting">
<tt>create table acs_attributes (
attribute_id integer not null primary key
@@ -559,48 +311,34 @@
);
</tt>
-</pre>
-<p>The following points are important about this table:</p>
-<div class="itemizedlist"><ul>
-<li><p>Every attribute has a unique identifier.</p></li>
-<li><p>Every attribute is associated with an object type.</p></li>
-<li><p>We store various things about each attribute for presentation
-(<tt>pretty_name</tt>, <tt>sort_order</tt>).</p></li>
-<li><p>The <tt>data_type</tt> column stores type information on this
+</pre><p>The following points are important about this table:</p><div class="itemizedlist"><ul type="disc"><li><p>Every attribute has a unique identifier.</p></li><li><p>Every attribute is associated with an object type.</p></li><li><p>We store various things about each attribute for presentation
+(<tt>pretty_name</tt>, <tt>sort_order</tt>).</p></li><li><p>The <tt>data_type</tt> column stores type information on this
attribute. This is not the SQL type of the attribute; it is just a human
readable name for the type of data we think the attribute holds (e.g.
"String", or "Money"). This might be used later to
-generate a user interface.</p></li>
-<li><p>The <tt>sort_order</tt> column stores information about how to sort
-the attribute values.</p></li>
-<li><p>Attributes can either be stored explicitly in a table ("type
+generate a user interface.</p></li><li><p>The <tt>sort_order</tt> column stores information about how to sort
+the attribute values.</p></li><li><p>Attributes can either be stored explicitly in a table ("type
specific storage") or in a skinny table ("generic storage").
In most cases, an attribute maps directly to a column in the table identified
by the <tt>table_name</tt> of the corresponding object type, although, as
mentioned above, we sometimes store attribute values as key-value pairs in a
"skinny" table. However, when you ask the question "What are
the attributes of this type of object?", you don't really care about
how the values for each attribute are stored (in a column or as key-value
-pairs); you expect to receive the complete list of all attributes.</p></li>
-<li><p>The <tt>max_n_values</tt> and <tt>min_n_values</tt> columns
+pairs); you expect to receive the complete list of all attributes.</p></li><li><p>The <tt>max_n_values</tt> and <tt>min_n_values</tt> columns
encode information about the number of values an attribute may hold.
-Attributes can be defined to hold 0 or more total values.</p></li>
-<li><p>The <tt>static_p</tt> flag indicates whether this attribute value is
+Attributes can be defined to hold 0 or more total values.</p></li><li><p>The <tt>static_p</tt> flag indicates whether this attribute value is
shard by all instances of a type, as with static member fields in C++. Static
-attribute are like group level attributes in OpenACS 3.x.</p></li>
-</ul></div>
-<p>The final part of the knowledge level model keeps track of relationship
+attribute are like group level attributes in OpenACS 3.x.</p></li></ul></div><p>The final part of the knowledge level model keeps track of relationship
types. We said above that object relationships are used to generalize the 3.x
-notion of <span class="emphasis"><i>group member fields</i></span>. These were fields that a developer
+notion of <span class="emphasis"><em>group member fields</em></span>. These were fields that a developer
could store on each member of a group, but which were contextualized to the
membership relation. That is, they were really "attached" to the
fact that a user was a member of a particular group, and not really attached
to the user. This is a subtle but important distinction, because it allowed
the 3.x system to store multiple sets of attributes on a given user, one set
-for each group membership relation in which they participated.</p>
-<p>In OpenACS 4, this sort of data can be stored as a relationship type, in <a name="object-system-design-relsmodel"></a>
-<tt>acs_rel_types</tt>. The key parts of this table look like this:</p>
-<pre class="programlisting">
+for each group membership relation in which they participated.</p><p>In OpenACS 4, this sort of data can be stored as a relationship type, in <a name="object-system-design-relsmodel"></a>
+<tt>acs_rel_types</tt>. The key parts of this table look like this:</p><pre class="programlisting">
<tt>create table acs_rel_types (
rel_type varchar(100) not null
@@ -618,42 +356,27 @@
);
</tt>
-</pre>
-<p>Things to note about this table:</p>
-<div class="itemizedlist"><ul>
-<li><p>The main part of this table records the fact that the relation is between
+</pre><p>Things to note about this table:</p><div class="itemizedlist"><ul type="disc"><li><p>The main part of this table records the fact that the relation is between
instances of <tt>object_type_one</tt> and instances of
<tt>object_type_two</tt>. Therefore, each instance of this relation type
-will be a pair of objects of the appropriate types.</p></li>
-<li><p>The <tt>role</tt> columns store human readable names for the roles
+will be a pair of objects of the appropriate types.</p></li><li><p>The <tt>role</tt> columns store human readable names for the roles
played by each object in the relation (e.g. "employee" and
"employer"). Each role must appear in the
-<tt>acs_rel_roles</tt>.</p></li>
-<li><p>The <tt>min_n_rels_one</tt> column, and its three friends allow the
+<tt>acs_rel_roles</tt>.</p></li><li><p>The <tt>min_n_rels_one</tt> column, and its three friends allow the
programmer to specify constraints on how many objects any given object can be
-related to on either side of the relation.</p></li>
-</ul></div>
-<p>This table is easier to understand if you also know how the <a href="object-system-design.html#object-system-design-acs-rels"><tt>acs_rels</tt> table</a> works.</p>
-<p>To summarize, the <tt>acs_object_types</tt> and
+related to on either side of the relation.</p></li></ul></div><p>This table is easier to understand if you also know how the <a href="object-system-design.html#object-system-design-acs-rels"><tt>acs_rels</tt> table</a> works.</p><p>To summarize, the <tt>acs_object_types</tt> and
<tt>acs_attributes</tt> tables store metadata that describes every object
type and attribute in the system. These tables generalize the group types
data model in OpenACS 3.x. The <tt>acs_rel_types</tt> table stores
-information about relation types.</p>
-<p>This part of the data model is somewhat analogous to the data dictionary
+information about relation types.</p><p>This part of the data model is somewhat analogous to the data dictionary
in Oracle. The information stored here is primarily metadata that describes
the data stored in the <a href="object-system-design.html#objects-design-op-level" title="Operational-level Data Model">operational level</a> of the data
-model, which is discussed next.</p>
-</div>
-<div class="sect3">
-<div class="titlepage"><div><h4 class="title">
-<a name="objects-design-op-level"></a>Operational-level Data Model</h4></div></div>
-<p>The operational level data model centers around the
+model, which is discussed next.</p></div><div class="sect3"><div class="titlepage"><div><h4 class="title"><a name="objects-design-op-level"></a>Operational-level Data Model</h4></div></div><p>The operational level data model centers around the
<tt>acs_objects</tt> table. This table contains a single row for every
instance of the type <tt>acs_object</tt>. The table contains the
object's unique identifier, a reference to its type, security
information, and generic auditing information. Here is what the table looks
-like:</p>
-<pre class="programlisting">
+like:</p><pre class="programlisting">
<tt>create table acs_objects (
object_id integer not null,
@@ -671,18 +394,15 @@
);
</tt>
-</pre>
-<p>As we said in Section III, security contexts are hierarchical and also
+</pre><p>As we said in Section III, security contexts are hierarchical and also
modeled as objects. There is another table called
-<tt>acs_object_context_index</tt> that stores the context hierarchy.</p>
-<p>Other tables in the core data model store additional information related
+<tt>acs_object_context_index</tt> that stores the context hierarchy.</p><p>Other tables in the core data model store additional information related
to objects. The table <tt>acs_attribute_values</tt> and
<tt>acs_static_attr_values</tt> are used to store attribute values that
are not stored in a helper table associated with the object's type. The
former is used for instance attributes while the latter is used for
class-wide "static" values. These tables have the same basic form,
-so we'll only show the first:</p>
-<pre class="programlisting">
+so we'll only show the first:</p><pre class="programlisting">
<tt>create table acs_attribute_values (
object_id not null
@@ -694,10 +414,8 @@
);
</tt>
-</pre>
-<p>Finally, the table <tt>acs_rels</tt> <a name="object-system-design-acs-rels"></a>is used to store object pairs
-that are instances of a relation type.</p>
-<pre class="programlisting">
+</pre><p>Finally, the table <tt>acs_rels</tt> <a name="object-system-design-acs-rels"></a>is used to store object pairs
+that are instances of a relation type.</p><pre class="programlisting">
<tt>create table acs_rels (
rel_id not null
@@ -713,58 +431,29 @@
);
</tt>
-</pre>
-<p>This table is somewhat subtle:</p>
-<div class="itemizedlist"><ul>
-<li><p>
-<tt>rel_id</tt> is the ID of an <span class="emphasis"><i>instance</i></span> of some relation
+</pre><p>This table is somewhat subtle:</p><div class="itemizedlist"><ul type="disc"><li><p><tt>rel_id</tt> is the ID of an <span class="emphasis"><em>instance</em></span> of some relation
type. We do this so we can store all the mapping tables in this one
-table.</p></li>
-<li><p>
-<tt>rel_type</tt> is the ID of the relation type to which this object
-belongs.</p></li>
-<li><p>The next two object IDs are the IDs of the objects being mapped.</p></li>
-</ul></div>
-<p>All this table does is store one row for every pair of objects that
+table.</p></li><li><p><tt>rel_type</tt> is the ID of the relation type to which this object
+belongs.</p></li><li><p>The next two object IDs are the IDs of the objects being mapped.</p></li></ul></div><p>All this table does is store one row for every pair of objects that
we'd like to attach with a relation. Any additional attributes that
we'd like to attach to this pair of objects is specified in the
attributes of the relation type, and could be stored in any number of places.
As in the 3.x user/groups system, these places include helper tables or
-generic skinny tables.</p>
-<p>This table, along with <tt>acs_attributes</tt> and
+generic skinny tables.</p><p>This table, along with <tt>acs_attributes</tt> and
<tt>acs_attribute_values</tt> generalize the old user/group tables
<tt>user_group_map</tt>, <tt>user_group_member_fields_map</tt> and
-<tt>user_group_member_fields</tt>.</p>
-</div>
-<div class="sect3">
-<div class="titlepage"><div><h4 class="title">
-<a name="objects-design-discussion"></a>Summary and Discussion</h4></div></div>
-<p>The core tables in the OpenACS 4 data model store information about instances
+<tt>user_group_member_fields</tt>.</p></div><div class="sect3"><div class="titlepage"><div><h4 class="title"><a name="objects-design-discussion"></a>Summary and Discussion</h4></div></div><p>The core tables in the OpenACS 4 data model store information about instances
of object types and relation types. The <tt>acs_object</tt> table
provides the central location that contains a single row for every object in
the system. Services can use this table along with the metadata in stored in
the knowledge level data model to create, manage, query and manipulate
objects in a uniform manner. The <tt>acs_rels</tt> table has an analogous
-role in storing information on relations.</p>
-<p>These are all the tables that we'll discuss in this document. The rest
-of the Kernel data model is described in the documents for <a href="subsites-design.html" title="OpenACS 4 Subsites Design Document">subsites</a>, the <a href="permissions-design.html" title="OpenACS 4 Permissions Design">permissions</a> system and for the <a href="groups-design.html" title="OpenACS 4 Groups Design">groups</a> system.</p>
-<p>Some examples of how these tables are used in the system can be found in
-the discussion of the API, which comes next.</p>
-</div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="object-system-design-api"></a>API</h3></div></div>
-<p>Now we'll examine each piece of the API in detail. Bear in mind that
-the Object Model API is defined primarily through PL/SQL packages.</p>
-<div class="sect3">
-<div class="titlepage"><div><h4 class="title">
-<a name="objects-design-object-types"></a>Object Types and Attributes</h4></div></div>
-<p>The object system provides an API for creating new object types and then
+role in storing information on relations.</p><p>These are all the tables that we'll discuss in this document. The rest
+of the Kernel data model is described in the documents for <a href="subsites-design.html" title="OpenACS 4 Subsites Design Document">subsites</a>, the <a href="permissions-design.html" title="OpenACS 4 Permissions Design">permissions</a> system and for the <a href="groups-design.html" title="OpenACS 4 Groups Design">groups</a> system.</p><p>Some examples of how these tables are used in the system can be found in
+the discussion of the API, which comes next.</p></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="object-system-design-api"></a>API</h3></div></div><p>Now we'll examine each piece of the API in detail. Bear in mind that
+the Object Model API is defined primarily through PL/SQL packages.</p><div class="sect3"><div class="titlepage"><div><h4 class="title"><a name="objects-design-object-types"></a>Object Types and Attributes</h4></div></div><p>The object system provides an API for creating new object types and then
attaching attributes to them. The procedures <tt>create_type</tt> and
-<tt>drop_type</tt> are used to create and delete type definitions.</p>
-<p>The two calls show up in the package <tt>acs_object_type</tt>.</p>
-<pre class="programlisting">
+<tt>drop_type</tt> are used to create and delete type definitions.</p><p>The two calls show up in the package <tt>acs_object_type</tt>.</p><pre class="programlisting">
<tt> procedure create_type (
object_type in acs_object_types.object_type%TYPE,
@@ -787,12 +476,9 @@
);
</tt>
-</pre>
-<p>Here the <tt>cascade_p</tt> argument indicates whether dropping a type
-should also remove all its subtypes from the system.</p>
-<p>We define a similar interface for defining attributes in the package
-<tt>acs_attribute</tt>:</p>
-<pre class="programlisting">
+</pre><p>Here the <tt>cascade_p</tt> argument indicates whether dropping a type
+should also remove all its subtypes from the system.</p><p>We define a similar interface for defining attributes in the package
+<tt>acs_attribute</tt>:</p><pre class="programlisting">
<tt> function create_attribute (
object_type in acs_attributes.object_type%TYPE,
@@ -817,10 +503,8 @@
</tt>
-</pre>
-<p>In addition, the following two calls are available for attaching extra
-annotations onto attributes:</p>
-<pre class="programlisting">
+</pre><p>In addition, the following two calls are available for attaching extra
+annotations onto attributes:</p><pre class="programlisting">
<tt> procedure add_description (
object_type in acs_attribute_descriptions.object_type%TYPE,
@@ -836,24 +520,16 @@
);
</tt>
-</pre>
-<p>At this point, what you must do to hook into the object system from your
-own data model becomes clear:</p>
-<div class="itemizedlist"><ul>
-<li><p>Create a table that will store the instances of the new type.</p></li>
-<li><p>Call <tt>acs_object_type.create_type()</tt> to fill in the metadata
+</pre><p>At this point, what you must do to hook into the object system from your
+own data model becomes clear:</p><div class="itemizedlist"><ul type="disc"><li><p>Create a table that will store the instances of the new type.</p></li><li><p>Call <tt>acs_object_type.create_type()</tt> to fill in the metadata
table on this new type. If you want your objects to appear in the
<tt>acs_objects</tt> table, then your new type must be a subtype of
-<tt>acs_object</tt>.</p></li>
-<li><p>Call <tt>acs_attribute.create_attribute()</tt> to fill in information
-on the attributes that this type defines.</p></li>
-</ul></div>
-<p>So, suppose we are writing a new version of the ticket tracker for 4.0. We
+<tt>acs_object</tt>.</p></li><li><p>Call <tt>acs_attribute.create_attribute()</tt> to fill in information
+on the attributes that this type defines.</p></li></ul></div><p>So, suppose we are writing a new version of the ticket tracker for 4.0. We
probably define a table to store tickets in, and each ticket might have an ID
and a description. If we want each ticket to be an object, then
<tt>ticket_id</tt> must reference the <tt>object_id</tt> column in
-<tt>acs_objects</tt>:</p>
-<pre class="programlisting">
+<tt>acs_objects</tt>:</p><pre class="programlisting">
<tt>create table tickets (
ticket_id references acs_objects (object_id),
@@ -862,10 +538,8 @@
) ;
</tt>
-</pre>
-<p>In addition to defining the table, we need this extra PL/SQL code to hook
-into the object type tables:</p>
-<pre class="programlisting">
+</pre><p>In addition to defining the table, we need this extra PL/SQL code to hook
+into the object type tables:</p><pre class="programlisting">
<tt>declare
attr_id acs_attributes.attribute_id%TYPE;
@@ -894,29 +568,21 @@
end;
</tt>
-</pre>
-<p>Thus, with a small amount of extra code, the new ticket tracker will now
+</pre><p>Thus, with a small amount of extra code, the new ticket tracker will now
automatically be hooked into every generic object service that exists. Better
still, this code need not be changed as new services are added. As an aside,
the most important service that requires you to subtype
-<tt>acs_object</tt> is <a href="permissions-design.html" title="OpenACS 4 Permissions Design">permissions</a>.</p>
-</div>
-<div class="sect3">
-<div class="titlepage"><div><h4 class="title">
-<a name="objects-design-objects"></a>Objects</h4></div></div>
-<p>The next important piece of the API is defined in the
+<tt>acs_object</tt> is <a href="permissions-design.html" title="OpenACS 4 Permissions Design">permissions</a>.</p></div><div class="sect3"><div class="titlepage"><div><h4 class="title"><a name="objects-design-objects"></a>Objects</h4></div></div><p>The next important piece of the API is defined in the
<tt>acs_object</tt> package, and is concerned with creating and managing
objects. This part of the API is designed to take care of the mundane
bookkeeping needed to create objects and query their attributes.
Realistically however, limitations in PL/SQL and Oracle will make it hard to
build generic procedures for doing large scale queries in the object system,
so developers who need to do this will probably have to be fairly familiar
-with the data model at a lower level.</p>
-<p>The function <tt>acs_object.new()</tt> makes a new object for you. The
+with the data model at a lower level.</p><p>The function <tt>acs_object.new()</tt> makes a new object for you. The
function <tt>acs_object.delete()</tt> deletes an object. As before, this
is an abbreviated interface with all the long type specs removed. See the
-data model or developer's guide for the full interface.</p>
-<pre class="programlisting">
+data model or developer's guide for the full interface.</p><pre class="programlisting">
<tt> function new (
object_id in acs_objects.object_id%TYPE default null,
@@ -935,14 +601,11 @@
);
</tt>
-</pre>
-<p>Next, we define some generic functions to manipulate attributes. Again,
+</pre><p>Next, we define some generic functions to manipulate attributes. Again,
these interfaces are useful to an extent, but for large scale queries,
it's likely that developers would have to query the data model directly,
-and then encapsulate their queries in procedures.</p>
-<p>For names, the <tt>default_name</tt> function is used if you don't
-want to define your own name function.</p>
-<pre class="programlisting">
+and then encapsulate their queries in procedures.</p><p>For names, the <tt>default_name</tt> function is used if you don't
+want to define your own name function.</p><pre class="programlisting">
<tt> function name (
object_id in acs_objects.object_id%TYPE
@@ -954,10 +617,8 @@
</tt>
-</pre>
-<p>The following functions tell you where attributes are stored, and fetch
-single attributes for you.</p>
-<pre class="programlisting">
+</pre><p>The following functions tell you where attributes are stored, and fetch
+single attributes for you.</p><pre class="programlisting">
<tt> procedure get_attribute_storage (
object_id_in in acs_objects.object_id%TYPE,
@@ -979,16 +640,13 @@
);
</tt>
-</pre>
-<p>The main use of the <tt>acs_object</tt> package is to create
+</pre><p>The main use of the <tt>acs_object</tt> package is to create
application objects and make them available for services via the
<tt>acs_objects</tt> table. To do this, you just have to make sure you
call <tt>acs_object.new()</tt> on objects that you wish to appear in the
<tt>acs_objects</tt> table. In addition, all such objects must be
-instances of some subtype of <tt>acs_object</tt>.</p>
-<p>Continuing the ticket example, we might define the following sort of
-procedure for creating a new ticket:</p>
-<pre class="programlisting">
+instances of some subtype of <tt>acs_object</tt>.</p><p>Continuing the ticket example, we might define the following sort of
+procedure for creating a new ticket:</p><pre class="programlisting">
<tt> function new_ticket (
package_id in tickets.ticket_id%TYPE
@@ -1012,41 +670,26 @@
end new_ticket;
</tt>
-</pre>
-<p>This function will typically be defined in the context of a PL/SQL
-package, but we've left it stand-alone here for simplicity.</p>
-<p>To summarize: in order to take advantage of OpenACS 4 services, a new
-application need only do three things:</p>
-<div class="itemizedlist"><ul>
-<li><p>Define a data model to describe application objects. This can just be a
-normal SQL table.</p></li>
-<li><p>Create an object type, using code like in the example from the previous
-section.</p></li>
-<li><p>Make sure application objects are created using
+</pre><p>This function will typically be defined in the context of a PL/SQL
+package, but we've left it stand-alone here for simplicity.</p><p>To summarize: in order to take advantage of OpenACS 4 services, a new
+application need only do three things:</p><div class="itemizedlist"><ul type="disc"><li><p>Define a data model to describe application objects. This can just be a
+normal SQL table.</p></li><li><p>Create an object type, using code like in the example from the previous
+section.</p></li><li><p>Make sure application objects are created using
<tt>acs_object.new()</tt> in addition to whatever SQL code is needed to
-insert a new row into the application data model.</p></li>
-</ul></div>
-<p>One of the design goals of OpenACS 4 was to provide a straightforward and
+insert a new row into the application data model.</p></li></ul></div><p>One of the design goals of OpenACS 4 was to provide a straightforward and
consistent mechanism to provide applications with general services. What we
have seen here is that three simple steps and minimal changes in the
application data model are sufficient to make sure that application objects
are represented in the <tt>acs_objects</tt> table. Subsequently, all of
the general services in OpenACS 4 (i.e. permissions, general comments, and so on)
are written to work with any object that appears in <tt>acs_objects</tt>.
Therefore, in general these three steps are sufficient to make OpenACS 4 services
-available to your application.</p>
-</div>
-<div class="sect3">
-<div class="titlepage"><div><h4 class="title">
-<a name="objects-design-relat-types"></a>Relation Types</h4></div></div>
-<p>The relations system defines two packages: <tt>acs_rel_type</tt> for
+available to your application.</p></div><div class="sect3"><div class="titlepage"><div><h4 class="title"><a name="objects-design-relat-types"></a>Relation Types</h4></div></div><p>The relations system defines two packages: <tt>acs_rel_type</tt> for
creating and managing relation types, and <tt>acs_rel</tt> for relating
-objects.</p>
-<p>These two procedures just insert and remove roles from the
+objects.</p><p>These two procedures just insert and remove roles from the
<tt>acs_rel_roles</tt> table. This table stores the legal relationship
"roles" that can be used when creating relation types. Examples of
-roles are, say, "member", or "employer".</p>
-<pre class="programlisting">
+roles are, say, "member", or "employer".</p><pre class="programlisting">
<tt> procedure create_role (
role in acs_rel_roles.role%TYPE
@@ -1057,10 +700,8 @@
);
</tt>
-</pre>
-<p>The main functions in the <tt>acs_rel_type</tt> package are used to
-create and drop relation types.</p>
-<pre class="programlisting">
+</pre><p>The main functions in the <tt>acs_rel_type</tt> package are used to
+create and drop relation types.</p><pre class="programlisting">
<tt> procedure create_type (
rel_type in acs_rel_types.rel_type%TYPE,
@@ -1090,10 +731,8 @@
);
</tt>
-</pre>
-<p>Finally, the <tt>acs_rel</tt> package provides an API that you use to
-create and destroy instances of a relation type:</p>
-<pre class="programlisting">
+</pre><p>Finally, the <tt>acs_rel</tt> package provides an API that you use to
+create and destroy instances of a relation type:</p><pre class="programlisting">
<tt> function new (
rel_id in acs_rels.rel_id%TYPE default null,
@@ -1110,13 +749,11 @@
);
</tt>
-</pre>
-<p>A good example of how to use relation types appears in the OpenACS 4 data
-model for <span class="emphasis"><i>groups</i></span>. As in 3.x, group membership is modeled using a
+</pre><p>A good example of how to use relation types appears in the OpenACS 4 data
+model for <span class="emphasis"><em>groups</em></span>. As in 3.x, group membership is modeled using a
mapping table, but now we create this mapping using relation types instead of
explicitly creating a table. First, we create a helper table to store state
-on each membership fact:</p>
-<pre class="programlisting">
+on each membership fact:</p><pre class="programlisting">
<tt>create table membership_rels (
rel_id constraint membership_rel_rel_id_fk
@@ -1130,9 +767,7 @@
);
</tt>
-</pre>
-<p>Then, we create a new object type to describe groups.</p>
-<pre class="programlisting">
+</pre><p>Then, we create a new object type to describe groups.</p><pre class="programlisting">
<tt> acs_object_type.create_type (
object_type => 'group',
@@ -1145,17 +780,14 @@
);
</tt>
-</pre>
-<p>In this example, we've made groups a subtype of
+</pre><p>In this example, we've made groups a subtype of
<tt>acs_object</tt> to make the code simpler. The actual data model is
somewhat different. Also, we've assumed that there is a helper table
called <tt>groups</tt> to store information on groups, and that there is
a helper table called <tt>group_types</tt> that has been defined to store
-extra attributes on groups.</p>
-<p>Now, assuming we have another object type called <tt>person</tt> to
+extra attributes on groups.</p><p>Now, assuming we have another object type called <tt>person</tt> to
represent objects that can be group members, we define the following
-relationship type for group membership:</p>
-<pre class="programlisting">
+relationship type for group membership:</p><pre class="programlisting">
<tt> acs_rel_type.create_role ('member');
@@ -1172,14 +804,12 @@
);
</tt>
-</pre>
-<p>Now we can define the following procedure to add a new member to a group.
+</pre><p>Now we can define the following procedure to add a new member to a group.
All this function does is create a new instance of the membership relation
type and then insert the membership state into the helper table that we
define above. In the actual implementation, this function is implemented in
the <tt>membership_rel</tt> package. Here we just define an independent
-function:</p>
-<pre class="programlisting">
+function:</p><pre class="programlisting">
<tt>function member_add (
rel_id in membership_rels.rel_id%TYPE default null,
@@ -1210,10 +840,8 @@
end;
</tt>
-</pre>
-<p>Another simple function can be defined to remove a member from a
-group:</p>
-<pre class="programlisting">
+</pre><p>Another simple function can be defined to remove a member from a
+group:</p><pre class="programlisting">
<tt> procedure member_delete (
rel_id in membership_rels.rel_id%TYPE
@@ -1227,94 +855,13 @@
end;
</tt>
-</pre>
-</div>
-<div class="sect3">
-<div class="titlepage"><div><h4 class="title">
-<a name="objects-design-discuss"></a>Summary and Discussion</h4></div></div>
-<p>The Object Model's API and data model provides a small set of simple
+</pre></div><div class="sect3"><div class="titlepage"><div><h4 class="title"><a name="objects-design-discuss"></a>Summary and Discussion</h4></div></div><p>The Object Model's API and data model provides a small set of simple
procedures that allow applications to create object types, object instances,
and object relations. Most of the data model is straightforward; the relation
type mechanism is a bit more complex, but in return it provides functionality
-on par with the old user/groups system in a more general way.</p>
-</div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="object-system-design-future"></a>Future Improvements/Areas of Likely Change</h3></div></div>
-<p>Nothing here yet.</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="object-system-design-authors"></a>Authors</h3></div></div>
-<p>
-<a href="mailto:psu@arsdigita.com" target="_top">Pete Su</a> generated this document
+on par with the old user/groups system in a more general way.</p></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="object-system-design-future"></a>Future Improvements/Areas of Likely Change</h3></div></div><p>Nothing here yet.</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="object-system-design-authors"></a>Authors</h3></div></div><p><a href="mailto:psu@arsdigita.com" target="_top">Pete Su</a> generated this document
from material culled from other documents by <a href="mailto:mcyoon@arsdigita.com" target="_top">Michael Yoon</a>, <a href="mailto:richardl@arsdigita.com" target="_top">Richard Li</a> and <a href="mailto:rhs@arsdigita.com" target="_top">Rafael Schloming</a>. But, any remaining lies
-are his and his alone.</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="object-system-design-revision-hist"></a>Revision History</h3></div></div>
-<div class="informaltable"><table border="1">
-<colgroup>
-<col>
-<col>
-<col>
-<col>
-</colgroup>
-<tbody>
-<tr>
-<td><span class="strong"><i>Document Revision #</i></span></td>
-<td><span class="strong"><i>Action Taken, Notes</i></span></td>
-<td><span class="strong"><i>When?</i></span></td>
-<td><span class="strong"><i>By Whom?</i></span></td>
-</tr>
-<tr>
-<td>0.1</td>
-<td>Creation</td>
-<td>9/09/2000</td>
-<td>Pete Su</td>
-</tr>
-<tr>
-<td>0.2</td>
-<td>Edited for ACS 4 Beta</td>
-<td>9/30/2000</td>
-<td>Kai Wu</td>
-</tr>
-<tr>
-<td>0.3</td>
-<td>Edited for ACS 4.0.1, fixed some mistakes, removed use of term
-"OM"</td>
-<td>11/07/2000</td>
-<td>Pete Su</td>
-</tr>
-</tbody>
-</table></div>
-</div>
-</div>
-<div class="navfooter">
-<hr>
-<table width="100%" summary="Navigation footer">
-<tr>
-<td width="40%" align="left">
-<a accesskey="p" href="object-system-requirements.html">Prev</a> </td>
-<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
-<td width="40%" align="right"> <a accesskey="n" href="permissions-requirements.html">Next</a>
-</td>
-</tr>
-<tr>
-<td width="40%" align="left">OpenACS 4 Object Model Requirements </td>
-<td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td>
-<td width="40%" align="right"> OpenACS 4 Permissions Requirements</td>
-</tr>
-</table>
-<hr>
-<address>
- rmello at fslc.usu.edu
- </address>
-<address><a href="mailto:vinod@kurup.com">
+are his and his alone.</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="object-system-design-revision-hist"></a>Revision History</h3></div></div><div class="informaltable"><table border="1"><colgroup><col><col><col><col></colgroup><tbody><tr><td><span class="strong"><em>Document Revision #</em></span></td><td><span class="strong"><em>Action Taken, Notes</em></span></td><td><span class="strong"><em>When?</em></span></td><td><span class="strong"><em>By Whom?</em></span></td></tr><tr><td>0.1</td><td>Creation</td><td>9/09/2000</td><td>Pete Su</td></tr><tr><td>0.2</td><td>Edited for ACS 4 Beta</td><td>9/30/2000</td><td>Kai Wu</td></tr><tr><td>0.3</td><td>Edited for ACS 4.0.1, fixed some mistakes, removed use of term
+"OM"</td><td>11/07/2000</td><td>Pete Su</td></tr></tbody></table></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="object-system-requirements.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="permissions-requirements.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS 4 Object Model Requirements </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> OpenACS 4 Permissions Requirements</td></tr></table><hr><address>rmello at fslc.usu.edu</address><address><a href="mailto:vinod@kurup.com">
vinod@kurup.com
- </a></address>
-</div>
-</body>
-</html>
+ </a></address></div></body></html>
Index: openacs-4/packages/acs-core-docs/www/object-system-requirements.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/object-system-requirements.html,v
diff -u -r1.5 -r1.5.2.1
--- openacs-4/packages/acs-core-docs/www/object-system-requirements.html 7 Mar 2002 06:55:36 -0000 1.5
+++ openacs-4/packages/acs-core-docs/www/object-system-requirements.html 15 May 2002 23:26:18 -0000 1.5.2.1
@@ -1,89 +1,37 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type">
-<title>OpenACS 4 Object Model Requirements</title>
-<meta name="generator" content="DocBook XSL Stylesheets V1.45">
-<link rel="home" href="index.html" title="OpenACS Documentation">
-<link rel="up" href="kernel-doc.html" title="Chapter 7. Kernel Documentation">
-<link rel="previous" href="kernel-overview.html" title="Overview">
-<link rel="next" href="object-system-design.html" title="OpenACS 4 Object Model Design">
-<link rel="stylesheet" href="openacs.css" type="text/css">
-</head>
-<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-<div class="navheader">
-<a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr>
-<td width="20%" align="left">
-<a accesskey="p" href="kernel-overview.html">Prev</a> </td>
-<th width="60%" align="center">Chapter 7. Kernel Documentation</th>
-<td width="20%" align="right"> <a accesskey="n" href="object-system-design.html">Next</a>
-</td>
-</tr></table>
-<hr>
-</div>
-<div class="sect1">
-<div class="titlepage"><div><h2 class="title" style="clear: both">
-<a name="object-system-requirements"></a>OpenACS 4 Object Model Requirements</h2></div></div>
-<div class="authorblurb"><p>
-By <a href="mailto:psu@arsdigita.com" target="_top">Pete Su</a>
-</p></div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="object-system-requirements-"></a>I. Introduction</h3></div></div>
-<p>A major goal in OpenACS 4 is to unify and normalize many of the core services
+<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"><title>OpenACS 4 Object Model Requirements</title><meta name="generator" content="DocBook XSL Stylesheets V1.50.0"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="kernel-doc.html" title="Chapter 7. Kernel Documentation"><link rel="previous" href="kernel-overview.html" title="Overview"><link rel="next" href="object-system-design.html" title="OpenACS 4 Object Model Design"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="kernel-overview.html">Prev</a> </td><th width="60%" align="center">Chapter 7. Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="object-system-design.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="object-system-requirements"></a>OpenACS 4 Object Model Requirements</h2></div></div><div class="authorblurb"><p>
+By <a href="mailto:psu@arsdigita.com" target="_top">Pete Su</a><br>
+ OpenACS docs are written by the named authors, but may be edited
+ by OpenACS documentation staff.
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="object-system-requirements-"></a>I. Introduction</h3></div></div><p>A major goal in OpenACS 4 is to unify and normalize many of the core services
of the system into a coherent common data model and API. In the past, these
services were provided to applications in an ad-hoc and irregular fashion.
-Examples of such services include:</p>
-<div class="itemizedlist"><ul>
-<li><p>General Comments</p></li>
-<li><p>User/groups</p></li>
-<li><p>Attribute storage in user/groups</p></li>
-<li><p>General Permissions</p></li>
-<li><p>Site wide search</p></li>
-<li><p>General Auditing</p></li>
-</ul></div>
-<p>All of these services involve relating extra information and services to
-application data objects, examples of which include:</p>
-<div class="itemizedlist"><ul>
-<li><p>Bboard messages</p></li>
-<li><p>A user home page</p></li>
-<li><p>A ticket in the Ticket Tracker</p></li>
-<li><p>A photograph in the PhotoDB</p></li>
-</ul></div>
-<p>In the past, developers had to use ad-hoc and inconsistent schemes to
+Examples of such services include:</p><div class="itemizedlist"><ul type="disc"><li><p>General Comments</p></li><li><p>User/groups</p></li><li><p>Attribute storage in user/groups</p></li><li><p>General Permissions</p></li><li><p>Site wide search</p></li><li><p>General Auditing</p></li></ul></div><p>All of these services involve relating extra information and services to
+application data objects, examples of which include:</p><div class="itemizedlist"><ul type="disc"><li><p>Bboard messages</p></li><li><p>A user home page</p></li><li><p>A ticket in the Ticket Tracker</p></li><li><p>A photograph in the PhotoDB</p></li></ul></div><p>In the past, developers had to use ad-hoc and inconsistent schemes to
interface to the various "general" services mentioned above. Since
each service used its own scheme for storing its metadata and mapping this
data to application objects, we could not implement any kind of centralized
management system or consistent administrative pages for all the services.
Consequently, a large amount of duplicate code appeared throughout the system
-for dealing with these services.</p>
-<p>Unifying and "normalizing" these interfaces, to minimize the
+for dealing with these services.</p><p>Unifying and "normalizing" these interfaces, to minimize the
amount of code repetition in applications, is a primary goal of OpenACS 4. Thus
the Object Model (OM, also referred to later as the object system) is
-concerned primarily with the storage and management of <span class="emphasis"><i>metadata</i></span>, on
+concerned primarily with the storage and management of <span class="emphasis"><em>metadata</em></span>, on
any object within a given instance of OpenACS 4. The term "metadata"
refers to any extra data the OM stores on behalf of the application - outside
of the application's data model - in order to enable certain generic
services. The term "object" refers to any entity being represented
within the OpenACS, and typically corresponds to a single row within the
-relational database.</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="object-system-requirements-vision"></a>Vision Statement</h3></div></div>
-<p>The OpenACS 4 Object Model must address five high-level requirements that
+relational database.</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="object-system-requirements-vision"></a>Vision Statement</h3></div></div><p>The OpenACS 4 Object Model must address five high-level requirements that
repeatedly exhibit themselves in the context of existing services in OpenACS 3.x,
-as described below.</p>
-<p><span class="strong"><i>Object Identifiers for General Services</i></span></p>
-<p>Generic services require a single unambiguous way of identifying
+as described below.</p><p><span class="strong"><em>Object Identifiers for General Services</em></span></p><p>Generic services require a single unambiguous way of identifying
application objects that they manage or manipulate. In OpenACS 3.x, there are
several different idioms that construct object identifiers from other data.
Many modules use a <tt>(user_id, group_id, scope)</tt> triple combination
for the purpose of recording ownership information on objects for access
control. User/groups also uses <tt>(user_id, group_id)</tt> pairs in its
<tt>user_group_map</tt> table as a way to identify data associated with a
-single membership relation.</p>
-<p>Also in OpenACS 3.x, many utility modules exist that do nothing more than
+single membership relation.</p><p>Also in OpenACS 3.x, many utility modules exist that do nothing more than
attach some extra attributes to existing application data. For example,
general comments maintains a mapping table that maps application
"page" data (static or dynamic) to one or more user comments on the
@@ -93,79 +41,31 @@
as the "(on_which_table + on_what_id)" method for identifying
application data. General comments stores its map from pages to comments
using a "(on_which_table + on_what_id)" key, plus the id of the
-comment itself.</p>
-<p>All of these composite key constructions are implicit object identifiers:
+comment itself.</p><p>All of these composite key constructions are implicit object identifiers:
they build a unique ID out of other pieces of the data model. The problem is
that their definition and use is ad-hoc and inconsistent. This makes the
construction of generic application-independent services difficult.
Therefore, the OpenACS 4 Object Model should provide a centralized and uniform
-mechanism for tagging application objects with unique identifiers.</p>
-<p><span class="strong"><i>Support for Unified Access Control</i></span></p>
-<p>Access control should be as transparent as possible to the application
+mechanism for tagging application objects with unique identifiers.</p><p><span class="strong"><em>Support for Unified Access Control</em></span></p><p>Access control should be as transparent as possible to the application
developer. Until the implementation of the general permissions system, every
OpenACS application had to manage access control to its data separately. Later
on, a notion of "scoping" was introduced into the core data
-model.</p>
-<p>"Scope" is a term best explained by example. Consider some
-hypothetical rows in the <tt>address_book</tt> table:</p>
-<blockquote class="blockquote"><div class="informaltable"><table border="1">
-<colgroup>
-<col>
-<col>
-<col>
-<col>
-</colgroup>
-<tbody>
-<tr>
-<td><span class="strong"><i>...</i></span></td>
-<td><span class="strong"><i><tt>scope</tt></i></span></td>
-<td><span class="strong"><i><tt>user_id</tt></i></span></td>
-<td><span class="strong"><i><tt>group_id</tt></i></span></td>
-<td><span class="strong"><i>...</i></span></td>
-</tr>
-<tr>
-<td>...</td>
-<td><tt>user</tt></td>
-<td><tt>123</tt></td>
-<td>�</td>
-<td>...</td>
-</tr>
-<tr>
-<td>...</td>
-<td><tt>group</tt></td>
-<td>�</td>
-<td><tt>456</tt></td>
-<td>...</td>
-</tr>
-<tr>
-<td>...</td>
-<td><tt>public</tt></td>
-<td>�</td>
-<td>�</td>
-<td>...</td>
-</tr>
-</tbody>
-</table></div></blockquote>
-<p>The first row represents an entry in User 123's personal address book,
+model.</p><p>"Scope" is a term best explained by example. Consider some
+hypothetical rows in the <tt>address_book</tt> table:</p><blockquote class="blockquote"><div class="informaltable"><table border="1"><colgroup><col><col><col><col></colgroup><tbody><tr><td><span class="strong"><em>...</em></span></td><td><span class="strong"><em><tt>scope</tt></em></span></td><td><span class="strong"><em><tt>user_id</tt></em></span></td><td><span class="strong"><em><tt>group_id</tt></em></span></td><td><span class="strong"><em>...</em></span></td></tr><tr><td>...</td><td><tt>user</tt></td><td><tt>123</tt></td><td>�</td><td>...</td></tr><tr><td>...</td><td><tt>group</tt></td><td>�</td><td><tt>456</tt></td><td>...</td></tr><tr><td>...</td><td><tt>public</tt></td><td>�</td><td>�</td><td>...</td></tr></tbody></table></div></blockquote><p>The first row represents an entry in User 123's personal address book,
the second row represents an entry in User Group 456's shared address
book, and the third row represents an entry in the site's public address
-book.</p>
-<p>In this way, the scoping columns identify the security context in which a
-given object belongs, where each context is <span class="emphasis"><i>either</i></span> a person
-<span class="emphasis"><i>or</i></span> a group of people <span class="emphasis"><i>or</i></span> the general public (itself a group
-of people).</p>
-<p>The problem with this scheme is that we are limited to using only users
+book.</p><p>In this way, the scoping columns identify the security context in which a
+given object belongs, where each context is <span class="emphasis"><em>either</em></span> a person
+<span class="emphasis"><em>or</em></span> a group of people <span class="emphasis"><em>or</em></span> the general public (itself a group
+of people).</p><p>The problem with this scheme is that we are limited to using only users
and groups as scopes for access control, limiting applications to a single
level of hierarchy. Worse, the scoping system demanded that every page
needing access to a given application had to do an explicit scope check to
make sure access was allowed - if a developer was careless on just one site
-page, a security problem could result.</p>
-<p>Thus the OpenACS 4 Object Model must support a more general access control
+page, a security problem could result.</p><p>Thus the OpenACS 4 Object Model must support a more general access control
system that allows access control domains to be hierarchical, and specifiable
with a single piece of data, instead of the old composite keys described
-above.</p>
-<p><span class="strong"><i>Extensible Data Models</i></span></p>
-<p>Another problem with previous OpenACS data models is that many of the central
+above.</p><p><span class="strong"><em>Extensible Data Models</em></span></p><p>Another problem with previous OpenACS data models is that many of the central
tables in the system became bloated as they were extended to support an
increasing number of modules. The <tt>users</tt> table is the best case
in point: it became full of columns that exist for various special
@@ -176,49 +76,36 @@
would improve maintainability greatly. Furthermore, the ability to allow
applications or users to define new extensions to existing tables, and have
some central metadata facility for keeping track of what data belong to which
-tables, would be very useful.</p>
-<p>Thus the motivation for providing <span class="emphasis"><i>object types</i></span> and
-<span class="emphasis"><i>subtyping</i></span> in the OpenACS 4 Object Model. The OM should allow developers
-to define a hierarchy of metadata <span class="emphasis"><i>object types</i></span> with subtyping and
+tables, would be very useful.</p><p>Thus the motivation for providing <span class="emphasis"><em>object types</em></span> and
+<span class="emphasis"><em>subtyping</em></span> in the OpenACS 4 Object Model. The OM should allow developers
+to define a hierarchy of metadata <span class="emphasis"><em>object types</em></span> with subtyping and
inheritance. Developers can then use the framework to allow users to define
custom extensions to the existing data models, and the OM does the
bookkeeping necessary to make this easier, providing a generic API for object
creation that automatically keeps track of the location and relationships
-between data.</p>
-<p>
-<span class="strong"><i>Design Note:</i></span> While this doesn't really belong in a
+between data.</p><p><span class="strong"><em>Design Note:</em></span> While this doesn't really belong in a
requirements document, the fact that we are constrained to using relational
databases means that certain constraints on the overall design of the object
-data model exist, which you can read about in <a href="object-system-design.html#object-system-design-summary">Summary and Design Considerations</a>.</p>
-<p><span class="strong"><i>Modifiable Data Models</i></span></p>
-<p>Another recurring applications problem is how to store a modifiable data
+data model exist, which you can read about in <a href="object-system-design.html#object-system-design-summary">Summary and Design Considerations</a>.</p><p><span class="strong"><em>Modifiable Data Models</em></span></p><p>Another recurring applications problem is how to store a modifiable data
model, or how to store information that may change extensively between
releases or in different client installations. Furthermore, we want to avoid
changes to an application's database queries in the face of any custom
extensions, since such changes are difficult or dangerous to make at runtime,
and can make updating the system difficult. Some example applications in OpenACS
-3.x with modifiable data models include:</p>
-<div class="itemizedlist"><ul>
-<li><p>User/groups: developers and users can attach custom data to group types,
-groups, and members of groups.</p></li>
-<li><p>In the Ecommerce data model, the <tt>ec_custom_product_fields</tt>
+3.x with modifiable data models include:</p><div class="itemizedlist"><ul type="disc"><li><p>User/groups: developers and users can attach custom data to group types,
+groups, and members of groups.</p></li><li><p>In the Ecommerce data model, the <tt>ec_custom_product_fields</tt>
table defines attributes for catalog products, and the
<tt>ec_custom_product_field_values</tt> table stores values for those
-attributes.</p></li>
-<li><p>In the PhotoDB data model, the <tt>ph_custom_photo_fields</tt> table
+attributes.</p></li><li><p>In the PhotoDB data model, the <tt>ph_custom_photo_fields</tt> table
defines attributes for the photographs owned by a specific user, and tables
named according to the convention
"<tt>ph_user_<user_id>_custom_info</tt>" are used to
-store values for those attributes.</p></li>
-</ul></div>
-<p>Thus the Object Model must provide a general mechanism for applications
+store values for those attributes.</p></li></ul></div><p>Thus the Object Model must provide a general mechanism for applications
and developers to modify or extend data models, without requiring changes to
the SQL schema of the system. This ensures that all applications use the same
-base schema, resulting in a uniform and more maintainable system.</p>
-<p><span class="strong"><i>Generic Relations</i></span></p>
-<p>Many OpenACS applications define simple relationships between application
+base schema, resulting in a uniform and more maintainable system.</p><p><span class="strong"><em>Generic Relations</em></span></p><p>Many OpenACS applications define simple relationships between application
objects, and tag those relationships with extra data. In OpenACS 3.x, this was
-done using <span class="emphasis"><i>mapping tables</i></span>. The user/groups module has the most
+done using <span class="emphasis"><em>mapping tables</em></span>. The user/groups module has the most
highly developed data model for this purpose, using a single table called
<tt>user_group_map</tt> that mapped users to groups. In addition, it uses
the the <tt>user_group_member_fields</tt> and
@@ -229,440 +116,155 @@
historical note, in OpenACS 3.x, user/groups was the only part of the system that
provided this kind of data model in a reusable way. Therefore, applications
that needed this capability often hooked into user/groups for no other reason
-than to use this part of its data model.</p>
-<p>The OpenACS 4 data model must support generic relations by allowing developers
-to define a special kind of object type called a <span class="emphasis"><i>relation type</i></span>.
+than to use this part of its data model.</p><p>The OpenACS 4 data model must support generic relations by allowing developers
+to define a special kind of object type called a <span class="emphasis"><em>relation type</em></span>.
Relation types are themselves object types that do nothing but represent
relations. They can be used by applications that previously used user/groups
for the same purpose, but without the extraneous, artificial
-dependencies.</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="object-system-requirements-system-overview"></a>System Overview</h3></div></div>
-<p>The Object Model package is a combination of data model and a procedural
+dependencies.</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="object-system-requirements-system-overview"></a>System Overview</h3></div></div><p>The Object Model package is a combination of data model and a procedural
API for manipulating application objects within an OpenACS instance. The OM
-allows developers to describe a hierarchical system of <span class="emphasis"><i>object types</i></span>
+allows developers to describe a hierarchical system of <span class="emphasis"><em>object types</em></span>
that store metadata on application objects. The object type system supports
subtyping with inheritance, so new object types can be defined in terms of
-existing object types.</p>
-<p>The OM data model forms the main part of the OpenACS 4 Kernel data model. The
-other parts of the Kernel data model include:</p>
-<div class="itemizedlist"><ul>
-<li><p>Parties and Groups</p></li>
-<li><p>Permissions</p></li>
-</ul></div>
-<p>Each of these is documented elsewhere at length.</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="object-system-requirements-use-cases"></a>Use-cases and User-scenarios</h3></div></div>
-<p>(Pending as of 8/27/00)</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="object-system-requirements-links"></a>Related Links</h3></div></div>
-<div class="itemizedlist"><ul>
-<li><p><a href="object-system-design.html">OpenACS 4 Object Model Design</a></p></li>
-<li><p><a href="objects.html">OpenACS 4.5 Data Models and the Object System</a></p></li>
-</ul></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="object-system-requirements-data-model"></a>Requirements: Data Model</h3></div></div>
-<p>The data model for the object system provides support for the following
-kinds of schema patterns that are used by many existing OpenACS modules:</p>
-<div class="variablelist"><dl>
-<dt><span class="term"><span class="strong"><i>10.0 Object Identification and Storage</i></span></span></dt>
-<dd>
-<p>Object identification is a central mechanism in the new metadata system.
+existing object types.</p><p>The OM data model forms the main part of the OpenACS 4 Kernel data model. The
+other parts of the Kernel data model include:</p><div class="itemizedlist"><ul type="disc"><li><p>Parties and Groups</p></li><li><p>Permissions</p></li></ul></div><p>Each of these is documented elsewhere at length.</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="object-system-requirements-use-cases"></a>Use-cases and User-scenarios</h3></div></div><p>(Pending as of 8/27/00)</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="object-system-requirements-links"></a>Related Links</h3></div></div><div class="itemizedlist"><ul type="disc"><li><p><a href="object-system-design.html">OpenACS 4 Object Model Design</a></p></li><li><p><a href="objects.html">OpenACS 4.5 Data Models and the Object System</a></p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="object-system-requirements-data-model"></a>Requirements: Data Model</h3></div></div><p>The data model for the object system provides support for the following
+kinds of schema patterns that are used by many existing OpenACS modules:</p><div class="variablelist"><dl><dt><span class="term"><span class="strong"><em>10.0 Object Identification and Storage</em></span></span></dt><dd><p>Object identification is a central mechanism in the new metadata system.
The fact that every object has a known unique identifier means that the core
can deal with all objects in a generic way. Thus the only action required of
an application to obtain any general service is to "hook into" the
-object system.</p>
-<p>In OpenACS 3.x, modules use ad-hoc means to construct unique identifiers for
+object system.</p><p>In OpenACS 3.x, modules use ad-hoc means to construct unique identifiers for
objects that they manage. Generally, these unique IDs are built from other
IDs that happen to be in the data model. Because there is no consistency in
these implementations, every application must hook into every service
-separately.</p>
-<p>Examples of utilities that do this in OpenACS 3.x system are:</p>
-<div class="itemizedlist"><ul>
-<li><p>User/groups: Information is attached to group membership relations.</p></li>
-<li><p>General Comments: Comments are attached to objects representing some kind
-of document.</p></li>
-<li><p>General Permissions: Stores access control information on application
-data.</p></li>
-<li><p>User Profiling: Maps users to pieces of content that they have looked at;
-content identifiers must be managed in a uniform way.</p></li>
-<li><p>Site Wide Search: Stores all content in a single flat table, with object
+separately.</p><p>Examples of utilities that do this in OpenACS 3.x system are:</p><div class="itemizedlist"><ul type="disc"><li><p>User/groups: Information is attached to group membership relations.</p></li><li><p>General Comments: Comments are attached to objects representing some kind
+of document.</p></li><li><p>General Permissions: Stores access control information on application
+data.</p></li><li><p>User Profiling: Maps users to pieces of content that they have looked at;
+content identifiers must be managed in a uniform way.</p></li><li><p>Site Wide Search: Stores all content in a single flat table, with object
identifiers pointing to the object containing the content in the first place.
This way, we can search the contents of many different types of objects in a
-uniform way.</p></li>
-</ul></div>
-<p>The OM will support and unify this programming idiom by providing objects
+uniform way.</p></li></ul></div><p>The OM will support and unify this programming idiom by providing objects
with unique identifiers (unique within a given OpenACS instance) and with
information about where the application data associated with the object is
stored. The identifier can be used to refer to collections of heterogeneous
application data. More importantly, object identifiers will enable developers
to readily build and use generic services that work globally across a
-system.</p>
-<p>The object identifiers should be subject to the following
-requirements:</p>
-<p><span class="strong"><i>10.10 Uniqueness</i></span></p>
-<p>The object ID should be unique among all the IDs in the entire OpenACS system
-in which the object lives.</p>
-<p><span class="strong"><i>10.20 Useful as a Reference</i></span></p>
-<p>Applications should be able to use the unique object ID as a reference,
-with which they can fetch any or all of the object's attributes.</p>
-<p><span class="strong"><i>10.30 Storable</i></span></p>
-<p>Object IDs should be storable in tables. e.g. you should be able to use
+system.</p><p>The object identifiers should be subject to the following
+requirements:</p><p><span class="strong"><em>10.10 Uniqueness</em></span></p><p>The object ID should be unique among all the IDs in the entire OpenACS system
+in which the object lives.</p><p><span class="strong"><em>10.20 Useful as a Reference</em></span></p><p>Applications should be able to use the unique object ID as a reference,
+with which they can fetch any or all of the object's attributes.</p><p><span class="strong"><em>10.30 Storable</em></span></p><p>Object IDs should be storable in tables. e.g. you should be able to use
them to implement mapping tables between objects, to represent
-relationships.</p>
-<p><span class="strong"><i>10.40 Moveable</i></span></p>
-<p>Objects should be mobile between databases. That is, information will
+relationships.</p><p><span class="strong"><em>10.40 Moveable</em></span></p><p>Objects should be mobile between databases. That is, information will
often need to be moved between multiple servers (development, staging, and
production), so a mechanism for moving this data is necessary. In addition, a
mechanism for tagging these objects in a way similar to CVS would be useful
-in determining which objects need to be synchronized.</p>
-</dd>
-<dt><span class="term"><span class="strong"><i>20.0 Object Types</i></span></span></dt>
-<dd>
-<p>An <span class="emphasis"><i>object type</i></span> refers to a specification of one or more
-attributes to be managed along with a piece of application data.</p>
-<p>The object system should provide a data model for describing and
+in determining which objects need to be synchronized.</p></dd><dt><span class="term"><span class="strong"><em>20.0 Object Types</em></span></span></dt><dd><p>An <span class="emphasis"><em>object type</em></span> refers to a specification of one or more
+attributes to be managed along with a piece of application data.</p><p>The object system should provide a data model for describing and
representing object types. This data model is somewhat analogous to the
Oracle data dictionary, which stores information about all user defined
-tables in the system.</p>
-<p>The canonical example of this kind of data model occurs in the current OpenACS
-3.x user/groups module, which allows the developer to create new <span class="emphasis"><i>group
-types</i></span> that can contain not only generic system level attributes but also
+tables in the system.</p><p>The canonical example of this kind of data model occurs in the current OpenACS
+3.x user/groups module, which allows the developer to create new <span class="emphasis"><em>group
+types</em></span> that can contain not only generic system level attributes but also
extended, developer-defined attributes. In addition, these attributes can
either be attached to the group type itself, and shared by all instances, or
they can be different for each instance. At its core, the OpenACS 4 object system
is meant to be a generalization of this mechanism. The data model should
allow developers to at least do everything they used to with user/groups, but
-without its administrative hassles.</p>
-<p>Therefore, the data model must be able to represent object types that have
-the following characteristics:</p>
-<p><span class="strong"><i>20.10 Type Name</i></span></p>
-<p>A human readable name for the object type.</p>
-<p><span class="strong"><i>20.20 Type Attributes</i></span></p>
-<p>Attributes whose values are shared by all instances of the object
-type.</p>
-<p><span class="strong"><i>20.30 Object Attributes</i></span></p>
-<p>Attributes that are specific to each particular object belonging to a
-given type.</p>
-<p>The data model must also enforce certain constraints on object types:</p>
-<p><span class="strong"><i>20.40 Type Uniqueness</i></span></p>
-<p>Object type names must be unique.</p>
-<p><span class="strong"><i>20.50 Attribute Name Uniqueness</i></span></p>
-<p>Attribute names must be unique in the scope of a single object type and
-any of its parent types.</p>
-</dd>
-<dt><span class="term"><span class="strong"><i>30.0 Type Extension</i></span></span></dt>
-<dd>
-<p>The Object Model must support the definition of object types that are
+without its administrative hassles.</p><p>Therefore, the data model must be able to represent object types that have
+the following characteristics:</p><p><span class="strong"><em>20.10 Type Name</em></span></p><p>A human readable name for the object type.</p><p><span class="strong"><em>20.20 Type Attributes</em></span></p><p>Attributes whose values are shared by all instances of the object
+type.</p><p><span class="strong"><em>20.30 Object Attributes</em></span></p><p>Attributes that are specific to each particular object belonging to a
+given type.</p><p>The data model must also enforce certain constraints on object types:</p><p><span class="strong"><em>20.40 Type Uniqueness</em></span></p><p>Object type names must be unique.</p><p><span class="strong"><em>20.50 Attribute Name Uniqueness</em></span></p><p>Attribute names must be unique in the scope of a single object type and
+any of its parent types.</p></dd><dt><span class="term"><span class="strong"><em>30.0 Type Extension</em></span></span></dt><dd><p>The Object Model must support the definition of object types that are
subtypes of existing types. A subtype inherits all the attributes of its
parent type, and defines some attributes of its own. A critical aspect of the
OM is parent types may be altered, and any such change must propagate to
-child subtypes.</p>
-<p>The OM data model must enforce constraints on subtypes that are similar to
-the ones on general object types.</p>
-<p><span class="strong"><i>30.10 Subtype Uniqueness</i></span></p>
-<p>Subtype names must be unique (this parallels requirement 10.40).</p>
-<p><span class="strong"><i>30.20 Subtype Attribute Name Uniqueness</i></span></p>
-<p>Attribute names must be unique in the scope of a single object
-subtype.</p>
-<p><span class="strong"><i>30.30 Parent Type Prerequisite</i></span></p>
-<p>Subtypes must be defined in terms of parent types that, in fact, already
-exist.</p>
-<p><span class="strong"><i>30.40</i></span></p>
-<p>The extended attribute names in a subtype must not be the same as those in
-its parent type.</p>
-</dd>
-<dt><span class="term"><span class="strong"><i>35.0 Methods</i></span></span></dt>
-<dd>
-<p><span class="strong"><i>35.10 Method and Type Association</i></span></p>
-<p>The OM data model should define a mechanism for associating procedural
-code, called <span class="emphasis"><i>methods</i></span>, with objects of a given type. Methods are
-associated with the each object <span class="emphasis"><i>type</i></span> - not each object
-<span class="emphasis"><i>instance</i></span>.</p>
-<p><span class="strong"><i>35.20 Method Sharing</i></span></p>
-<p>All instances of a given object type should share the same set of defined
-methods for that type.</p>
-</dd>
-<dt><span class="term"><span class="strong"><i>40.0 Object Attribute Value Storage</i></span></span></dt>
-<dd>
-<p>In addition to information on types, the OM data model provides for the
+child subtypes.</p><p>The OM data model must enforce constraints on subtypes that are similar to
+the ones on general object types.</p><p><span class="strong"><em>30.10 Subtype Uniqueness</em></span></p><p>Subtype names must be unique (this parallels requirement 10.40).</p><p><span class="strong"><em>30.20 Subtype Attribute Name Uniqueness</em></span></p><p>Attribute names must be unique in the scope of a single object
+subtype.</p><p><span class="strong"><em>30.30 Parent Type Prerequisite</em></span></p><p>Subtypes must be defined in terms of parent types that, in fact, already
+exist.</p><p><span class="strong"><em>30.40</em></span></p><p>The extended attribute names in a subtype must not be the same as those in
+its parent type.</p></dd><dt><span class="term"><span class="strong"><em>35.0 Methods</em></span></span></dt><dd><p><span class="strong"><em>35.10 Method and Type Association</em></span></p><p>The OM data model should define a mechanism for associating procedural
+code, called <span class="emphasis"><em>methods</em></span>, with objects of a given type. Methods are
+associated with the each object <span class="emphasis"><em>type</em></span> - not each object
+<span class="emphasis"><em>instance</em></span>.</p><p><span class="strong"><em>35.20 Method Sharing</em></span></p><p>All instances of a given object type should share the same set of defined
+methods for that type.</p></dd><dt><span class="term"><span class="strong"><em>40.0 Object Attribute Value Storage</em></span></span></dt><dd><p>In addition to information on types, the OM data model provides for the
centralized storage of object attribute values. This facility unifies the
many ad-hoc attribute/value tables that exist in various OpenACS 3.x data models,
-such as:</p>
-<div class="itemizedlist"><ul>
-<li><p>User groups: Each instance of a group type can have custom data.</p></li>
-<li><p>Photo DB: Users can define their own custom metadata to attach to
-photograph objects.</p></li>
-<li><p>Ecommerce: Vendors can attach custom fields to the data model describing
-their products.</p></li>
-</ul></div>
-<p><span class="strong"><i>40.10 Generic Retrieval</i></span></p>
-<p>Attributes should be stored so that they are retrievable in a way that is
+such as:</p><div class="itemizedlist"><ul type="disc"><li><p>User groups: Each instance of a group type can have custom data.</p></li><li><p>Photo DB: Users can define their own custom metadata to attach to
+photograph objects.</p></li><li><p>Ecommerce: Vendors can attach custom fields to the data model describing
+their products.</p></li></ul></div><p><span class="strong"><em>40.10 Generic Retrieval</em></span></p><p>Attributes should be stored so that they are retrievable in a way that is
independent of the type of the object that they belong to. That is, the only
data needed to retrieve an attribute should be the system-wide ID of an
-object (see requirement 10.20 above) and the attribute name.</p>
-<p><span class="strong"><i>40.20 Inherited Attributes</i></span></p>
-<p>The system should allow for the automatic retrieval of inherited attribute
-values, for an object belonging to a subtype.</p>
-<p><span class="strong"><i>40.30. Constraints on Attributes</i></span></p>
-<p>The system should allow the developer to put down constraints on the
+object (see requirement 10.20 above) and the attribute name.</p><p><span class="strong"><em>40.20 Inherited Attributes</em></span></p><p>The system should allow for the automatic retrieval of inherited attribute
+values, for an object belonging to a subtype.</p><p><span class="strong"><em>40.30. Constraints on Attributes</em></span></p><p>The system should allow the developer to put down constraints on the
values that an attribute may hold, for the purposes of maintaining
-application specific integrity rules.</p>
-</dd>
-<dt><span class="term"><span class="strong"><i>50.0 Object Contexts</i></span></span></dt>
-<dd>
-<p>In OpenACS 3.x, there was a notion of "scope" for application
+application specific integrity rules.</p></dd><dt><span class="term"><span class="strong"><em>50.0 Object Contexts</em></span></span></dt><dd><p>In OpenACS 3.x, there was a notion of "scope" for application
objects. An object could be belong to one of three scopes: public, group or
user. This provided a crude way to associate objects with particular scopes
-in the system, but it was awkward to use and limited in flexibility.</p>
-<p>The OpenACS 4 Object Model provides a generalized notion of scope that allows
-developers to represent a hierarchy of object <span class="emphasis"><i>contexts</i></span>. These
+in the system, but it was awkward to use and limited in flexibility.</p><p>The OpenACS 4 Object Model provides a generalized notion of scope that allows
+developers to represent a hierarchy of object <span class="emphasis"><em>contexts</em></span>. These
contexts are used as the basis for the permissions system. In general, if an
object has no explicit permissions attached to it, then it inherits
-permissions from its context.</p>
-<p>The context data model also forms the basis of the <a href="subsites-requirements.html" title="OpenACS 4 Subsites Requirements">subsites system</a>, and is
+permissions from its context.</p><p>The context data model also forms the basis of the <a href="subsites-requirements.html" title="OpenACS 4 Subsites Requirements">subsites system</a>, and is
a basic part of the <a href="permissions-requirements.html" title="OpenACS 4 Permissions Requirements">permissions system</a>,
-described in separate documents.</p>
-<p>The context data model should provide the following facilities:</p>
-<p><span class="strong"><i>50.10 Unique ID</i></span></p>
-<p>Every context should have a unique ID in the system.</p>
-<p><span class="strong"><i>50.20 Tree Structure</i></span></p>
-<p>The data model should support a tree structured organization of contexts.
+described in separate documents.</p><p>The context data model should provide the following facilities:</p><p><span class="strong"><em>50.10 Unique ID</em></span></p><p>Every context should have a unique ID in the system.</p><p><span class="strong"><em>50.20 Tree Structure</em></span></p><p>The data model should support a tree structured organization of contexts.
That is, contexts can be logically "contained" within other
contexts (i.e. contexts have parents) and contexts can contain other contexts
-(i.e. contexts can have children).</p>
-<p><span class="strong"><i>50.30 Data Model Constraints</i></span></p>
-<p>All objects must have a context ID. This ID must refer to an existing
+(i.e. contexts can have children).</p><p><span class="strong"><em>50.30 Data Model Constraints</em></span></p><p>All objects must have a context ID. This ID must refer to an existing
context or be NULL. The meaning of a NULL context is determined by the
-implementation.</p>
-<p><span class="strong"><i>Note:</i></span></p>
-<p>The current system interprets the NULL context as meaning the default
+implementation.</p><p><span class="strong"><em>Note:</em></span></p><p>The current system interprets the NULL context as meaning the default
"site-wide" context in some sense. I wanted to note this fact for
others, but there is no need to make this a requirement of the system. I
think it would be reasonable to have a NULL context be an error (psu
-8/24/2000).</p>
-</dd>
-<dt><span class="term"><span class="strong"><i>55.0 Object Relations</i></span></span></dt>
-<dd><p>The data model should include a notion of pair-wise relations between
+8/24/2000).</p></dd><dt><span class="term"><span class="strong"><em>55.0 Object Relations</em></span></span></dt><dd><p>The data model should include a notion of pair-wise relations between
objects. Relations should be able to record simple facts of the form
"object X is related to object Y by relationship R," and also be
-able to attach attributes to these facts.</p></dd>
-</dl></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="object-system-requirements-api"></a>Requirements: API</h3></div></div>
-<p>The API should let programmers accomplish the following actions:</p>
-<div class="variablelist"><dl>
-<dt><span class="term"><span class="strong"><i>60.0 Object Type Creation</i></span></span></dt>
-<dd>
-<p><span class="strong"><i>60.10 Create a New Object Type</i></span></p>
-<p>The object system API should provide a procedure call that creates a new
+able to attach attributes to these facts.</p></dd></dl></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="object-system-requirements-api"></a>Requirements: API</h3></div></div><p>The API should let programmers accomplish the following actions:</p><div class="variablelist"><dl><dt><span class="term"><span class="strong"><em>60.0 Object Type Creation</em></span></span></dt><dd><p><span class="strong"><em>60.10 Create a New Object Type</em></span></p><p>The object system API should provide a procedure call that creates a new
object type by running the appropriate transactions on the object system data
model. This API call is subject to the constraints laid out in the data
-model. We call this operation "instantiating" an object.</p>
-<p><span class="strong"><i>60.20 Create a New Object Subtype</i></span></p>
-<p>The object system API should provide a procedure call for creating
+model. We call this operation "instantiating" an object.</p><p><span class="strong"><em>60.20 Create a New Object Subtype</em></span></p><p>The object system API should provide a procedure call for creating
subtypes of a given type. Operationally, this API is the same as requirement
60.10. Instances of subtypes automatically contain all attributes of the
parent type in addition to all attributes of the subtype. This API is subject
-to the constraints laid out in the data model.</p>
-<p><span class="strong"><i>60.30 Create a New Relation Type</i></span></p>
-<p>There should be an API call to create a new type of object relation.
+to the constraints laid out in the data model.</p><p><span class="strong"><em>60.30 Create a New Relation Type</em></span></p><p>There should be an API call to create a new type of object relation.
Relation types can be modeled as object types. The API below for manipulating
-attributes can then be used to add attributes to relation types.</p>
-</dd>
-<dt><span class="term"><span class="strong"><i>70.0 Update an Object Type</i></span></span></dt>
-<dd><p>The object system API must allow the programmer to modify, add, and delete
+attributes can then be used to add attributes to relation types.</p></dd><dt><span class="term"><span class="strong"><em>70.0 Update an Object Type</em></span></span></dt><dd><p>The object system API must allow the programmer to modify, add, and delete
attributes from any object type. Updates should be propagated to any child
subtypes. This API is subject to the constraints laid out in the data
-model.</p></dd>
-<dt><span class="term"><span class="strong"><i>80.0 Delete an Object Type</i></span></span></dt>
-<dd>
-<p>The system provides an API call for deleting an object type.</p>
-<p><span class="strong"><i>80.10</i></span></p>
-<p>Deleting an object type destroys all instances of the type. It should be
+model.</p></dd><dt><span class="term"><span class="strong"><em>80.0 Delete an Object Type</em></span></span></dt><dd><p>The system provides an API call for deleting an object type.</p><p><span class="strong"><em>80.10</em></span></p><p>Deleting an object type destroys all instances of the type. It should be
an error to delete types that have dependent subtypes. This API is subject to
-the constraints laid out in the data model.</p>
-<p><span class="strong"><i>80.10.10</i></span></p>
-<p>However, the programmer should also be able to specify that all the
+the constraints laid out in the data model.</p><p><span class="strong"><em>80.10.10</em></span></p><p>However, the programmer should also be able to specify that all the
subtypes and instances of those subtypes be destroyed before destroying the
object type. This is similar to a "delete cascade" constraint in
-SQL.</p>
-</dd>
-<dt><span class="term"><span class="strong"><i>90.0 Object Instance Creation and Destruction</i></span></span></dt>
-<dd>
-<p>The system must provide API calls to manage the creation and destruction
-of object instances.</p>
-<p><span class="strong"><i>90.10 Create an Instance of an Object Type</i></span></p>
-<p>The system should provide an API call for creating a new instance of a
+SQL.</p></dd><dt><span class="term"><span class="strong"><em>90.0 Object Instance Creation and Destruction</em></span></span></dt><dd><p>The system must provide API calls to manage the creation and destruction
+of object instances.</p><p><span class="strong"><em>90.10 Create an Instance of an Object Type</em></span></p><p>The system should provide an API call for creating a new instance of a
given object type. The new instance should be populated with values for each
of the attributes specified in the definition of the type. In addition, it
should be possible to create the new instance with an optional context ID
-that refers to the default context that the object will live in.</p>
-<p><span class="strong"><i>90.20 Delete an Object Instance</i></span></p>
-<p>The OM should provide an API call for object deletion. Objects can be
+that refers to the default context that the object will live in.</p><p><span class="strong"><em>90.20 Delete an Object Instance</em></span></p><p>The OM should provide an API call for object deletion. Objects can be
deleted only when no other objects in the system refer to them. Since it
might not be practical to provide a mechanism like "delete cascade"
here in a reliable way, providing such a facility in the system is
-optional.</p>
-</dd>
-<dt><span class="term"><span class="strong"><i>94.0 Object Relation Creation and Destruction</i></span></span></dt>
-<dd><p>The system must provide API calls to manage the creation and destruction
-of object relations.</p></dd>
-<dt><span class="term"><span class="strong"><i>94.10 Create an Object Relation</i></span></span></dt>
-<dd><p>The OM must provide an API call to declare that two objects are related to
+optional.</p></dd><dt><span class="term"><span class="strong"><em>94.0 Object Relation Creation and Destruction</em></span></span></dt><dd><p>The system must provide API calls to manage the creation and destruction
+of object relations.</p></dd><dt><span class="term"><span class="strong"><em>94.10 Create an Object Relation</em></span></span></dt><dd><p>The OM must provide an API call to declare that two objects are related to
each other by a given relation type. This API call should also allow
-programmers to attach attributes to this object relation.</p></dd>
-<dt><span class="term"><span class="strong"><i>94.20 Destroy an Object Relation</i></span></span></dt>
-<dd><p>There should be an API call for destroying object relations and their
-attributes.</p></dd>
-<dt><span class="term"><span class="strong"><i>95.10 Create and Destroy Contexts</i></span></span></dt>
-<dd><p>The system should provide an API to create and destroy object
-contexts.</p></dd>
-<dt><span class="term"><span class="strong"><i>100.10 Set Attribute Values for an Object</i></span></span></dt>
-<dd><p>The system should provide an API for updating the attribute values of a
-particular instance of an object type.</p></dd>
-<dt><span class="term"><span class="strong"><i>110.10 Get Attribute Values for an Object</i></span></span></dt>
-<dd><p>The system should provide an API for retrieving attribute values from a
-particular instance of an object type.</p></dd>
-<dt><span class="term"><span class="strong"><i>120.10 Efficiency</i></span></span></dt>
-<dd><p>The Object Model must support the efficient storage and retrieval of
+programmers to attach attributes to this object relation.</p></dd><dt><span class="term"><span class="strong"><em>94.20 Destroy an Object Relation</em></span></span></dt><dd><p>There should be an API call for destroying object relations and their
+attributes.</p></dd><dt><span class="term"><span class="strong"><em>95.10 Create and Destroy Contexts</em></span></span></dt><dd><p>The system should provide an API to create and destroy object
+contexts.</p></dd><dt><span class="term"><span class="strong"><em>100.10 Set Attribute Values for an Object</em></span></span></dt><dd><p>The system should provide an API for updating the attribute values of a
+particular instance of an object type.</p></dd><dt><span class="term"><span class="strong"><em>110.10 Get Attribute Values for an Object</em></span></span></dt><dd><p>The system should provide an API for retrieving attribute values from a
+particular instance of an object type.</p></dd><dt><span class="term"><span class="strong"><em>120.10 Efficiency</em></span></span></dt><dd><p>The Object Model must support the efficient storage and retrieval of
object attributes. Since the OM is intended to form the core of many general
services in the OpenACS, and these services will likely make extensive use of the
OM tables, queries on these tables must be fast. The major problem here seems
to be supporting subtyping and inheritance in a way that does not severely
-impact query performance.</p></dd>
-<dt><span class="term"><span class="strong"><i>130.10 Ease of Use</i></span></span></dt>
-<dd>
-<p>Most OpenACS packages will be expected to use the Object Model in one way or
+impact query performance.</p></dd><dt><span class="term"><span class="strong"><em>130.10 Ease of Use</em></span></span></dt><dd><p>Most OpenACS packages will be expected to use the Object Model in one way or
another. Since it is important that the largest audience of developers
possible adopts and uses the OM, it must be easy to incorporate into
applications, and it must not impose undue requirements on an
application's data model. In other words, it should be easy to "hook
into" the object model, and that ability should not have a major impact
-on the application data model.</p>
-<p>
-<span class="strong"><i>Note:</i></span> Is the API the only way to obtain values? How does
-this integrate with application level SQL queries?</p>
-</dd>
-</dl></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="object-system-requirements-history"></a>Revision History</h3></div></div>
-<div class="informaltable"><table border="1">
-<colgroup>
-<col>
-<col>
-<col>
-<col>
-</colgroup>
-<tbody>
-<tr>
-<td><span class="strong"><i>Document Revision #</i></span></td>
-<td><span class="strong"><i>Action Taken, Notes</i></span></td>
-<td><span class="strong"><i>When?</i></span></td>
-<td><span class="strong"><i>By Whom?</i></span></td>
-</tr>
-<tr>
-<td>0.1</td>
-<td>Creation</td>
-<td>08/10/2000</td>
-<td>Bryan Quinn</td>
-</tr>
-<tr>
-<td>0.2</td>
-<td>Major re-write</td>
-<td>08/11/2000</td>
-<td>Pete Su</td>
-</tr>
-<tr>
-<td>0.3</td>
-<td>Draft completed after initial reviews</td>
-<td>08/22/2000</td>
-<td>Pete Su</td>
-</tr>
-<tr>
-<td>0.4</td>
-<td>Edited, updated to conform to requirements template, pending freeze</td>
-<td>08/23/2000</td>
-<td>Kai Wu</td>
-</tr>
-<tr>
-<td>�</td>
-<td>Final edits before freeze</td>
-<td>08/24/2000</td>
-<td>Pete Su</td>
-</tr>
-<tr>
-<td>0.5</td>
-<td>Edited for consistency</td>
-<td>08/27/2000</td>
-<td>Kai Wu</td>
-</tr>
-<tr>
-<td>0.6</td>
-<td>Put Object ID stuff first, because it makes more sense</td>
-<td>08/28/2000</td>
-<td>Pete Su</td>
-</tr>
-<tr>
-<td>0.7</td>
-<td>Added requirement that knowledge-level objects must be moveable between
-databases.</td>
-<td>08/29/2000</td>
-<td>Richard Li</td>
-</tr>
-<tr>
-<td>0.8</td>
-<td>Rewrote intro to match language and concepts in the design document. Also
+on the application data model.</p><p><span class="strong"><em>Note:</em></span> Is the API the only way to obtain values? How does
+this integrate with application level SQL queries?</p></dd></dl></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="object-system-requirements-history"></a>Revision History</h3></div></div><div class="informaltable"><table border="1"><colgroup><col><col><col><col></colgroup><tbody><tr><td><span class="strong"><em>Document Revision #</em></span></td><td><span class="strong"><em>Action Taken, Notes</em></span></td><td><span class="strong"><em>When?</em></span></td><td><span class="strong"><em>By Whom?</em></span></td></tr><tr><td>0.1</td><td>Creation</td><td>08/10/2000</td><td>Bryan Quinn</td></tr><tr><td>0.2</td><td>Major re-write</td><td>08/11/2000</td><td>Pete Su</td></tr><tr><td>0.3</td><td>Draft completed after initial reviews</td><td>08/22/2000</td><td>Pete Su</td></tr><tr><td>0.4</td><td>Edited, updated to conform to requirements template, pending freeze</td><td>08/23/2000</td><td>Kai Wu</td></tr><tr><td>�</td><td>Final edits before freeze</td><td>08/24/2000</td><td>Pete Su</td></tr><tr><td>0.5</td><td>Edited for consistency</td><td>08/27/2000</td><td>Kai Wu</td></tr><tr><td>0.6</td><td>Put Object ID stuff first, because it makes more sense</td><td>08/28/2000</td><td>Pete Su</td></tr><tr><td>0.7</td><td>Added requirement that knowledge-level objects must be moveable between
+databases.</td><td>08/29/2000</td><td>Richard Li</td></tr><tr><td>0.8</td><td>Rewrote intro to match language and concepts in the design document. Also
cleaned up usage a bit in the requirements section. Added short vague
-requirements on relation types.</td>
-<td>09/06/2000</td>
-<td>Pete Su</td>
-</tr>
-<tr>
-<td>0.9</td>
-<td>Edited for ACS 4 Beta release.</td>
-<td>09/30/2000</td>
-<td>Kai Wu</td>
-</tr>
-</tbody>
-</table></div>
-</div>
-</div>
-<div class="navfooter">
-<hr>
-<table width="100%" summary="Navigation footer">
-<tr>
-<td width="40%" align="left">
-<a accesskey="p" href="kernel-overview.html">Prev</a> </td>
-<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
-<td width="40%" align="right"> <a accesskey="n" href="object-system-design.html">Next</a>
-</td>
-</tr>
-<tr>
-<td width="40%" align="left">Overview </td>
-<td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td>
-<td width="40%" align="right"> OpenACS 4 Object Model Design</td>
-</tr>
-</table>
-<hr>
-<address>
- rmello at fslc.usu.edu
- </address>
-<address><a href="mailto:vinod@kurup.com">
+requirements on relation types.</td><td>09/06/2000</td><td>Pete Su</td></tr><tr><td>0.9</td><td>Edited for ACS 4 Beta release.</td><td>09/30/2000</td><td>Kai Wu</td></tr></tbody></table></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="kernel-overview.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="object-system-design.html">Next</a></td></tr><tr><td width="40%" align="left">Overview </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> OpenACS 4 Object Model Design</td></tr></table><hr><address>rmello at fslc.usu.edu</address><address><a href="mailto:vinod@kurup.com">
vinod@kurup.com
- </a></address>
-</div>
-</body>
-</html>
+ </a></address></div></body></html>
Index: openacs-4/packages/acs-core-docs/www/objects.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/objects.html,v
diff -u -r1.7 -r1.7.2.1
--- openacs-4/packages/acs-core-docs/www/objects.html 7 Mar 2002 06:55:36 -0000 1.7
+++ openacs-4/packages/acs-core-docs/www/objects.html 15 May 2002 23:26:18 -0000 1.7.2.1
@@ -1,44 +1,16 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type">
-<title>OpenACS 4.5 Data Models and the Object System</title>
-<meta name="generator" content="DocBook XSL Stylesheets V1.45">
-<link rel="home" href="index.html" title="OpenACS Documentation">
-<link rel="up" href="dev-guide.html" title="Chapter 4. OpenACS Developer's Guide">
-<link rel="previous" href="developers-overview.html" title="Overview">
-<link rel="next" href="packages.html" title="OpenACS 4.5 Packages">
-<link rel="stylesheet" href="openacs.css" type="text/css">
-</head>
-<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-<div class="navheader">
-<a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr>
-<td width="20%" align="left">
-<a accesskey="p" href="developers-overview.html">Prev</a> </td>
-<th width="60%" align="center">Chapter 4. OpenACS Developer's Guide</th>
-<td width="20%" align="right"> <a accesskey="n" href="packages.html">Next</a>
-</td>
-</tr></table>
-<hr>
-</div>
-<div class="sect1">
-<div class="titlepage"><div><h2 class="title" style="clear: both">
-<a name="objects"></a>OpenACS 4.5 Data Models and the Object System</h2></div></div>
-<div class="authorblurb"><p>By <a href="mailto:psu@arsdigita.com" target="_top">Pete Su</a>
-</p></div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="objects-overview"></a>Overview</h3></div></div>
-<p>
+<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"><title>OpenACS 4.5 Data Models and the Object System</title><meta name="generator" content="DocBook XSL Stylesheets V1.50.0"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="dev-guide.html" title="Chapter 4. OpenACS Developer's Guide"><link rel="previous" href="developers-overview.html" title="Overview"><link rel="next" href="packages.html" title="OpenACS 4.5 Packages"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="developers-overview.html">Prev</a> </td><th width="60%" align="center">Chapter 4. OpenACS Developer's Guide</th><td width="20%" align="right"> <a accesskey="n" href="packages.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="objects"></a>OpenACS 4.5 Data Models and the Object System</h2></div></div><div class="authorblurb"><p><p>By <a href="mailto:psu@arsdigita.com" target="_top">Pete Su</a></p><br>
+ OpenACS docs are written by the named authors, but may be edited
+ by OpenACS documentation staff.
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="objects-overview"></a>Overview</h3></div></div><p>
Developing data models in OpenACS 4.5 is much like developing data models
for OpenACS 3, save for the implementation. As usual, you need to examine
how to model the information that the application must store and
manipulate, and define a suitable set of SQL tables. In our Notes
application, we have to be able to keep track of who entered a
particular note, when they did it, and the actual text of the notes
that users have entered. A simple data model might look like this:
-</p>
-<pre class="programlisting">
+</p><pre class="programlisting">
create table notes (
note_id integer primary key,
owner_id integer references users(user_id),
@@ -48,22 +20,12 @@
title varchar(255) not null,
body varchar(1024)
)
-</pre>
-<p>
+</pre><p>
We've omitted constraint names for the purpose of clarity.
-</p>
-<p>
+</p><p>
Thinking further ahead, we can imagine doing any of the following
things with Notes as well:
-</p>
-<div class="itemizedlist"><ul>
-<li style="list-style-type: opencircle"><p>Define access control policies on notes.</p></li>
-<li style="list-style-type: opencircle"><p>Attach user comments on notes.</p></li>
-<li style="list-style-type: opencircle"><p>Allows users to define custom fields to store on their notes.</p></li>
-<li style="list-style-type: opencircle"><p>Automatically generate input forms or output displays for notes.</p></li>
-<li style="list-style-type: opencircle"><p>Allow other applications to use notes in ways we don't know of yet.</p></li>
-</ul></div>
-<p>
+</p><div class="itemizedlist"><ul type="opencircle"><li style="list-style-type: opencircle"><p>Define access control policies on notes.</p></li><li style="list-style-type: opencircle"><p>Attach user comments on notes.</p></li><li style="list-style-type: opencircle"><p>Allows users to define custom fields to store on their notes.</p></li><li style="list-style-type: opencircle"><p>Automatically generate input forms or output displays for notes.</p></li><li style="list-style-type: opencircle"><p>Allow other applications to use notes in ways we don't know of yet.</p></li></ul></div><p>
In OpenACS 4.5, the key to enabling these types of services on your
application data is to take advantage of the Object System. The first
question anyone asks is usually "Just what are objects, and what do
@@ -75,46 +37,34 @@
table defines all the standard attributes that are stored on every
object, including its system-wide unique ID, object type, and some
generic auditing columns.
-</p>
-<p>
+</p><p>
To make use of the object system, you as the application developer
have to write your data model in a way that is slightly more complex
than before. What you get for this extra work includes:
-<div class="itemizedlist"><ul>
-<li><p>The <a href="permissions.html">Permissions System</a> lets you
+</p><div class="itemizedlist"><ul type="disc"><li><p>The <a href="permissions.html">Permissions System</a> lets you
track who is allowed to do what to the rows
in an application table, and gives you an easy way to enforce
- this from Tcl.</p></li>
-<li><p>Every object has an attribute called <tt>context_id</tt>
+ this from Tcl.</p></li><li><p>Every object has an attribute called <tt>context_id</tt>
that provides a way to trivially specify both the default
permissions for an object, and the intended "scope" of an
object. Just set the <tt>context_id</tt> to the controlling
- object and forget about it.</p></li>
-<li><p>And most importantly, any future object-level service - from
+ object and forget about it.</p></li><li><p>And most importantly, any future object-level service - from
a general-comments replacement to personalized ranking - will
- become available to your application "for free."</p></li>
-</ul></div>
-</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="objects-how-to-use"></a>How to Use Objects</h3></div></div>
-<p>
+ become available to your application "for free."</p></li></ul></div><p>
+</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="objects-how-to-use"></a>How to Use Objects</h3></div></div><p>
Using ACS objects is straightforward: all that's required are a few
extra steps in the design of your application data model.
-</p>
-<p>
+</p><p>
For our example Notes application, to hook into the object system we
make some calls to use our <tt>notes</tt> table as the basis for a
-new <span class="emphasis"><i>object type</i></span>. Object types are analogous to classes in
+new <span class="emphasis"><em>object type</em></span>. Object types are analogous to classes in
programming languages such as C++ and Java. For example, in Java a
class defines a set of attributes that store data and a set of methods
that run code. In OpenACS 4.5, we use one or more Oracle tables to store the
data attributes, and we define a PL/SQL package to hold procedures to
define the programming interface to the data model.
-</p>
-<p>
+</p><p>
The object type itself is described using data in the
<tt>acs_object_types</tt> and <tt>acs_attributes</tt> tables,
which plays a role similar to the data dictionary in Oracle. As in
@@ -124,19 +74,13 @@
bookkeeping code to keep everything consistent. Given all of this,
below you'll find the code needed to describe a new object type called
<tt>notes</tt> in your system.
-</p>
-<p>
+</p><p>
Fire up your text editor and open the
<tt>ROOT/packages/notes/sql/notes-create.sql</tt> file created
during the earlier <a href="packages.html" title="OpenACS 4.5 Packages">created the package</a>. Then, do the following:
-</p>
-<div class="sect3">
-<div class="titlepage"><div><h4 class="title">
-<a name="id5305750"></a>Describe the new type to the type system</h4></div></div>
-<p>
+</p><div class="sect3"><div class="titlepage"><div><h4 class="title"><a name="id5419938"></a>Describe the new type to the type system</h4></div></div><p>
First, add an entry to the <tt>acs_object_types</tt> table with the following PL/SQL call:
-</p>
-<pre class="programlisting">
+</p><pre class="programlisting">
begin
acs_object_type.create_type (
supertype => 'acs_object',
@@ -149,8 +93,7 @@
end;
/
show errors;
-</pre>
-<p>
+</pre><p>
This PL/SQL call tells the system that we would like to use the table
<tt>NOTES</tt> as the basis for a new object type called
<tt>note</tt>. This type is a subtype of the
@@ -159,15 +102,13 @@
some work on our part to make this happen, since Oracle can't do it
automatically. In general, most basic applications will define types
that are simple subtypes of <tt>acs_object</tt>.
-</p>
-<p>
+</p><p>
Now add entries to the <tt>acs_attributes</tt> table to describe
the data attributes of the new type. This data can eventually be used
to do things like automatically generate user interfaces to manipulate
the <tt>notes</tt> table, though that functionality isn't yet
available.
-</p>
-<pre class="programlisting">
+</p><pre class="programlisting">
declare
attr_id acs_attributes.attribute_id%TYPE;
begin
@@ -189,36 +130,28 @@
end;
/
show errors;
-</pre>
-<p>
+</pre><p>
We can stop here and not bother to register the usual OpenACS 3.x
attributes of <tt>creation_user</tt>, <tt>creation_date</tt>
and <tt>last_modified</tt>, since the object type
<tt>acs_object</tt> already defines these attributes. Again,
because the new type <tt>note</tt> is a subtype of
<tt>acs_object</tt>, it will inherit these attributes, so there is
no need for us to define them.
-</p>
-</div>
-<div class="sect3">
-<div class="titlepage"><div><h4 class="title">
-<a name="id5303162"></a>Define a table in which to store your objects</h4></div></div>
-<p>
+</p></div><div class="sect3"><div class="titlepage"><div><h4 class="title"><a name="id5420102"></a>Define a table in which to store your objects</h4></div></div><p>
The next thing we do is make a small modification to the data model to
reflect the fact that each row in the <tt>notes</tt> table
represents something that is not only an object of type
<tt>note</tt>, but also an <tt>acs_object</tt>. The new table
definition looks like this:
-</p>
-<pre class="programlisting">
+</p><pre class="programlisting">
create table notes (
note_id integer references acs_objects(object_id) primary key,
owner_id integer references users(user_id),
title varchar(255) not null,
body varchar(1024)
)
-</pre>
-<p>
+</pre><p>
Again, the usual <tt>creation_date</tt> and
<tt>modified_date</tt> columns are absent since they already exist
in <tt>acs_objects</tt>. Also, note the constraint we have added
@@ -230,17 +163,11 @@
use the <tt>acs_objects</tt> table to find objects will
transparently find any objects that are instances of any subtype of
<tt>acs_objects</tt>.
-</p>
-</div>
-<div class="sect3">
-<div class="titlepage"><div><h4 class="title">
-<a name="id5378251"></a>Define a package for type specific procedures</h4></div></div>
-<p>
+</p></div><div class="sect3"><div class="titlepage"><div><h4 class="title"><a name="id5420228"></a>Define a package for type specific procedures</h4></div></div><p>
The next step is to define a PL/SQL package for your new type, and
write some basic procedures to create and delete objects. Here is a
package definition for our new type:
-</p>
-<pre class="programlisting">
+</p><pre class="programlisting">
create or replace package note
as
function new (
@@ -263,8 +190,7 @@
end note;
/
show errors
-</pre>
-<p>
+</pre><p>
You might be wondering what all the extra parameters are to these
calls, since we haven't mentioned them before. These parameters are
needed to fill out information that will be stored about the object
@@ -275,8 +201,7 @@
self-explanatory and reflects attributes that existed in the earlier
OpenACS 3.x data models, with the exception of the <tt>context_id</tt>
attribute.
-</p>
-<p>
+</p><p>
The <tt>context_id</tt> attribute stores the ID of an object that
represents the default security domain to which the object belongs. It
is used by the <a href="permissions.html" title="Groups, Context, Permissions">permissions</a> system in
@@ -286,21 +211,15 @@
object OBJ was "read only", then any other object that used OBJ as its
context would also be "read only" by default. We'll talk about this more
later.
-</p>
-</div>
-<div class="sect3">
-<div class="titlepage"><div><h4 class="title">
-<a name="id5378356"></a>Define a package body for type specific procedures</h4></div></div>
-<p>
+</p></div><div class="sect3"><div class="titlepage"><div><h4 class="title"><a name="id5420333"></a>Define a package body for type specific procedures</h4></div></div><p>
The PL/SQL package body contains the implementations of the procedures
defined above. The only subtle thing going on here is that we must use
<tt>acs_object.new</tt> to insert a row into
<tt>acs_objects</tt>, before inserting a row into the
<tt>notes</tt>. Similarly, when we delete a row from
<tt>note</tt>, we have to be sure to delete the corresponding
<tt>acs_object</tt> row.
-</p>
-<pre class="programlisting">
+</p><pre class="programlisting">
create or replace package body note
as
@@ -351,20 +270,17 @@
end note;
/
show errors;
-</pre>
-<p>
+</pre><p>
That's pretty much it! As long as you use the <tt>note.new</tt>
function to create notes, and the <tt>note.delete</tt> function to
delete them, you'll be assured that the relationship each
<tt>note</tt> has with its corresponding <tt>acs_object</tt>
is preserved.
-</p>
-<p>
+</p><p>
The last thing to do is to make a file
<tt>ROOT/packages/notes/sql/notes-drop.sql</tt> so it's easy to
drop the data model when, say, you're testing:
-</p>
-<pre class="programlisting">
+</p><pre class="programlisting">
begin
acs_object_type.drop_type ('note');
end;
@@ -373,77 +289,57 @@
drop package note;
drop table notes;
-</pre>
-</div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="objects-when-to-use-objects"></a>When to Use Objects</h3></div></div>
-<p>
+</pre></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="objects-when-to-use-objects"></a>When to Use Objects</h3></div></div><p>
While it is generally hard to give general design advice without
knowing anything about a particular application, you should follow the
following rule of thumb when deciding when to hook part of your data
model to the object system:
-</p>
-<p>
+</p><p>
Anything in your data model that needs to be available to general OpenACS
services such as user comments, permissions, and so on should be a
subtype of <tt>acs_object</tt>. In addition, if you want your data
model to take advantage of attributes that exist in some object type
that is a subtype of <tt>acs_object</tt>, then you should use the
object system.
-</p>
-<p>
+</p><p>
For example, for most applications, you will want to use objects to
represent the data in your application that is user visible and thus
requires access control. But other internal tables, views, mapping
tables and so on probably don't need to be objects. As before, this
kind of design decision is mostly made on an
application-by-application basis, but this is a good baseline from
which to start.
-</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="objects-design-guidance"></a>Design Guidance</h3></div></div>
-<p>
+</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="objects-design-guidance"></a>Design Guidance</h3></div></div><p>
In this section we cover some overall guidelines for designing data
models that are meant to be integrated with the OpenACS object
system.
-</p>
-<p>
+</p><p>
There are two basic rules you should follow when designing OpenACS 4.5 data
models:
-<div class="orderedlist"><ol type="1">
-<li><p>
+</p><div class="orderedlist"><ol type="1"><li><p>
Never utilize fields in the <tt>acs_objects</tt> table in
application specific ways. That is, never assign any
application-specific semantics to this data. In the notes
application, we use the <tt>creation_date</tt> and
<tt>last_modified</tt> fields, but this is OK since we do not
assign any application-specific meaning to these fields.
-</p></li>
-<li>
-<p>
+</p></li><li><p>
In particular, never assign any application specific semantics to the
<tt>context_id</tt> attribute of an object. This field is used for
a very specific purpose by the permissions system, and using this
-field in <span class="emphasis"><i>any other way whatsoever</i></span> is guaranteed to make your
+field in <span class="emphasis"><em>any other way whatsoever</em></span> is guaranteed to make your
application act strangely.
-</p>
-<p>
+</p><p>
As we'll see later, the Notes example will point each note object's
<tt>context_id</tt> to the package instance in which the note was
created. The idea will be that in a real site, the administrator would
create one package instance for every separate set of Notes (say, one
per user). The instance would "own" all of the notes that it created,
and the administrator would be able to use the package instance as
the basis for access control, which is convenient.
-</p>
-</li>
-</ol></div>
+</p></li></ol></div><p>
The reason behind these two rules is pretty straightforward: First,
@@ -456,13 +352,11 @@
semantics of the data model are no longer independent of the
application. This would make it impossible to build the generic tools
that the data model is trying to support.
-</p>
-<p>
+</p><p>
Another less important reason for these two rules is to not introduce
any joins against the <tt>acs_objects</tt> table in SQL queries in
your application that you do not absolutely need.
-</p>
-<p>
+</p><p>
In the Notes example, the result of applying these rules is that we
are careful to define our own attribute for <tt>owner_id</tt>
rather than overloading <tt>creation_user</tt> from the objects
@@ -474,69 +368,31 @@
when to use inherited attributes is fairly straightforward, but
requires a good amount of thought at design time even for simple
applications.
-</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="objects-summary"></a>Summary</h3></div></div>
-<p>
+</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="objects-summary"></a>Summary</h3></div></div><p>
Hooking into the OpenACS 4.5 object system brings the application developer
numerous benefits, and doing it involves only four easy steps:
-<div class="itemizedlist"><ul>
-<li style="list-style-type: opencircle"><p>
+</p><div class="itemizedlist"><ul type="opencircle"><li style="list-style-type: opencircle"><p>
Describe the a new object type to the system. Most new application
types will be subtypes of the built-in type <tt>acs_object</tt>.
-</p></li>
-<li style="list-style-type: opencircle"><p>
+</p></li><li style="list-style-type: opencircle"><p>
Define a table to store application object data.
-</p></li>
-<li style="list-style-type: opencircle"><p>
+</p></li><li style="list-style-type: opencircle"><p>
Define a PL/SQL package to store procedures related to the new
type. You have to define at least a function called <tt>new</tt>
to create new application objects and a procedure called
<tt>delete</tt> to delete them.
-</p></li>
-<li style="list-style-type: opencircle"><p>
+</p></li><li style="list-style-type: opencircle"><p>
Define a package body that contains the implementations of the PL/SQL
procedures defined above.
-</p></li>
-<li style="list-style-type: opencircle"><p>
+</p></li><li style="list-style-type: opencircle"><p>
Try not to write queries in your application that join against
<tt>acs_objects</tt>. This means you should never use the fields
in <tt>acs_objects</tt> for application-specific purposes. This is
especially true for the <tt>context_id</tt> field.
-</p></li>
-</ul></div>
+</p></li></ul></div><p>
-</p>
-<p><div class="cvstag">($Id$)</div></p>
-</div>
-</div>
-<div class="navfooter">
-<hr>
-<table width="100%" summary="Navigation footer">
-<tr>
-<td width="40%" align="left">
-<a accesskey="p" href="developers-overview.html">Prev</a> </td>
-<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
-<td width="40%" align="right"> <a accesskey="n" href="packages.html">Next</a>
-</td>
-</tr>
-<tr>
-<td width="40%" align="left">Overview </td>
-<td width="20%" align="center"><a accesskey="u" href="dev-guide.html">Up</a></td>
-<td width="40%" align="right"> OpenACS 4.5 Packages</td>
-</tr>
-</table>
-<hr>
-<address>
- rmello at fslc.usu.edu
- </address>
-<address><a href="mailto:vinod@kurup.com">
+</p><p><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="developers-overview.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="packages.html">Next</a></td></tr><tr><td width="40%" align="left">Overview </td><td width="20%" align="center"><a accesskey="u" href="dev-guide.html">Up</a></td><td width="40%" align="right"> OpenACS 4.5 Packages</td></tr></table><hr><address>rmello at fslc.usu.edu</address><address><a href="mailto:vinod@kurup.com">
vinod@kurup.com
- </a></address>
-</div>
-</body>
-</html>
+ </a></address></div></body></html>
Index: openacs-4/packages/acs-core-docs/www/openacs-overview.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/openacs-overview.html,v
diff -u -r1.2 -r1.2.2.1
--- openacs-4/packages/acs-core-docs/www/openacs-overview.html 7 Mar 2002 06:55:36 -0000 1.2
+++ openacs-4/packages/acs-core-docs/www/openacs-overview.html 15 May 2002 23:26:18 -0000 1.2.2.1
@@ -1,54 +1,4 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type">
-<title>Overview</title>
-<meta name="generator" content="DocBook XSL Stylesheets V1.45">
-<link rel="home" href="index.html" title="OpenACS Documentation">
-<link rel="up" href="general-documents.html" title="Chapter 1. High level information: What is OpenACS?">
-<link rel="previous" href="general-documents.html" title="Chapter 1. High level information: What is OpenACS?">
-<link rel="next" href="release-notes.html" title="OpenACS 4.5 Release Notes">
-<link rel="stylesheet" href="openacs.css" type="text/css">
-</head>
-<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-<div class="navheader">
-<a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr>
-<td width="20%" align="left">
-<a accesskey="p" href="general-documents.html">Prev</a> </td>
-<th width="60%" align="center">Chapter 1. High level information: What is OpenACS?</th>
-<td width="20%" align="right"> <a accesskey="n" href="release-notes.html">Next</a>
-</td>
-</tr></table>
-<hr>
-</div>
-<div class="sect1">
-<div class="titlepage"><div><h2 class="title" style="clear: both">
-<a name="openacs-overview"></a>Overview</h2></div></div>
-<p>The place to start if you want a soft, high level introduction to OpenACS</p>
-</div>
-<div class="navfooter">
-<hr>
-<table width="100%" summary="Navigation footer">
-<tr>
-<td width="40%" align="left">
-<a accesskey="p" href="general-documents.html">Prev</a> </td>
-<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
-<td width="40%" align="right"> <a accesskey="n" href="release-notes.html">Next</a>
-</td>
-</tr>
-<tr>
-<td width="40%" align="left">Chapter 1. High level information: What is OpenACS? </td>
-<td width="20%" align="center"><a accesskey="u" href="general-documents.html">Up</a></td>
-<td width="40%" align="right"> OpenACS 4.5 Release Notes</td>
-</tr>
-</table>
-<hr>
-<address>
- rmello at fslc.usu.edu
- </address>
-<address><a href="mailto:vinod@kurup.com">
+<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"><title>Overview</title><meta name="generator" content="DocBook XSL Stylesheets V1.50.0"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="general-documents.html" title="Chapter 1. High level information: What is OpenACS?"><link rel="previous" href="general-documents.html" title="Chapter 1. High level information: What is OpenACS?"><link rel="next" href="release-notes.html" title="OpenACS 4.5 Release Notes"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="general-documents.html">Prev</a> </td><th width="60%" align="center">Chapter 1. High level information: What is OpenACS?</th><td width="20%" align="right"> <a accesskey="n" href="release-notes.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="openacs-overview"></a>Overview</h2></div></div><p>The place to start if you want a soft, high level introduction to OpenACS</p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="general-documents.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="release-notes.html">Next</a></td></tr><tr><td width="40%" align="left">Chapter 1. High level information: What is OpenACS? </td><td width="20%" align="center"><a accesskey="u" href="general-documents.html">Up</a></td><td width="40%" align="right"> OpenACS 4.5 Release Notes</td></tr></table><hr><address>rmello at fslc.usu.edu</address><address><a href="mailto:vinod@kurup.com">
vinod@kurup.com
- </a></address>
-</div>
-</body>
-</html>
+ </a></address></div></body></html>
Index: openacs-4/packages/acs-core-docs/www/openacs.css
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/openacs.css,v
diff -u -r1.1 -r1.1.2.1
--- openacs-4/packages/acs-core-docs/www/openacs.css 2 Feb 2002 03:53:31 -0000 1.1
+++ openacs-4/packages/acs-core-docs/www/openacs.css 15 May 2002 23:26:18 -0000 1.1.2.1
@@ -9,4 +9,5 @@
.codeblock{background-color:#ffffff;font-family:monospace}
.programlisting{background-color:#CCCCCC}
-.strong{font-weight:bold}
\ No newline at end of file
+.strong{font-weight:bold}
+.authorblurb{font-size:small}
Index: openacs-4/packages/acs-core-docs/www/openacs.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/openacs.html,v
diff -u -r1.5 -r1.5.2.1
--- openacs-4/packages/acs-core-docs/www/openacs.html 7 Mar 2002 06:55:36 -0000 1.5
+++ openacs-4/packages/acs-core-docs/www/openacs.html 15 May 2002 23:26:18 -0000 1.5.2.1
@@ -1,91 +1,49 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type">
-<title>Install OpenACS 4.5</title>
-<meta name="generator" content="DocBook XSL Stylesheets V1.45">
-<link rel="home" href="index.html" title="OpenACS Documentation">
-<link rel="up" href="unix-install.html" title="Chapter 2. Installing on Unix/Linux">
-<link rel="previous" href="aolserver.html" title="Install AOLserver 3.3+ad13">
-<link rel="next" href="nextsteps.html" title="Next Steps">
-<link rel="stylesheet" href="openacs.css" type="text/css">
-</head>
-<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-<div class="navheader">
-<a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr>
-<td width="20%" align="left">
-<a accesskey="p" href="aolserver.html">Prev</a> </td>
-<th width="60%" align="center">Chapter 2. Installing on Unix/Linux</th>
-<td width="20%" align="right"> <a accesskey="n" href="nextsteps.html">Next</a>
-</td>
-</tr></table>
-<hr>
-</div>
-<div class="sect1">
-<div class="titlepage"><div><h2 class="title" style="clear: both">
-<a name="openacs"></a>Install OpenACS 4.5</h2></div></div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="install-openacs-download"></a>Downloading OpenACS</h3></div></div>
-<div class="itemizedlist"><ul>
-<li><p> Download the <a href="http://www.openacs.org/software" target="_top">OpenACS 4.5 software</a>
+<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"><title>Install OpenACS 4.5</title><meta name="generator" content="DocBook XSL Stylesheets V1.50.0"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="unix-install.html" title="Chapter 2. Installing on Unix/Linux"><link rel="previous" href="aolserver.html" title="Install AOLserver 3.3+ad13"><link rel="next" href="nextsteps.html" title="Next Steps"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="aolserver.html">Prev</a> </td><th width="60%" align="center">Chapter 2. Installing on Unix/Linux</th><td width="20%" align="right"> <a accesskey="n" href="nextsteps.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="openacs"></a>Install OpenACS 4.5</h2></div></div><div class="authorblurb"><p>
+ by <a href="mailto:vinod@kurup.com" target="_top">Vinod Kurup</a><br>
+ OpenACS docs are written by the named authors, but may be edited
+ by OpenACS documentation staff.
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="install-openacs-download"></a>Downloading OpenACS</h3></div></div><div class="itemizedlist"><ul type="disc"><li><p> Download the <a href="http://www.openacs.org/software" target="_top">OpenACS 4.5 software</a>
to the <tt>/tmp</tt> directory:
- </p></li>
-<li>
-<p>
+ </p></li><li><p>
Login as <tt>nsadmin</tt> and untar the
downloaded components into <tt>/web</tt>
- directory. The alpha-2 tarball is currently named
- <tt>alpha2.tgz</tt>. Replace
- <tt>alpha2.tgz</tt> in the commands below
+ directory. The OpenACS 4.5 tarball is currently named
+ <tt>openacs-4-5.tgz</tt>. Replace
+ <tt>openacs-4-5.tgz</tt> in the commands below
with whatever the current tarball is named.
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
joeuser:~$ su - nsadmin
Password: ***********
nsadmin:~$ cd /web
-nsadmin:/web$ tar xzf /tmp/alpha2.tgz</pre>
-</li>
-<li>
-<p>
+nsadmin:/web$ tar xzf /tmp/openacs-4-5.tgz</pre></li><li><p>
You should now have an
<tt>openacs-4/</tt> directory tree in
<tt>/web</tt>. Rename this directory to
whatever you want your web service to be identified as. The name
of your web service is referred to as the
- <span class="emphasis"><i>service_name</i></span>. Since you can run multiple
+ <span class="emphasis"><em>service_name</em></span>. Since you can run multiple
separate web services under AOLserver, this identification is
used internally by AOLserver to differentiate your services from
one another. A service name should be a single word,
- <span class="emphasis"><i>letters and numbers only</i></span>. If the name of
+ <span class="emphasis"><em>letters and numbers only</em></span>. If the name of
your site is one word, that would be a good choice. For example
"birdnotes" might be the service name for the <a href="http://birdnotes.net/" target="_top">birdnotes.net</a>
- community. We'll use <span class="emphasis"><i>birdnotes</i></span> as an example
+ community. We'll use <span class="emphasis"><em>birdnotes</em></span> as an example
in these docs.
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
nsadmin:/web$ ls -l
total 4
drwxr-xr-x 8 nsadmin nsadmin 4096 Nov 27 09:32 openacs-4
-nsadmin:/web$ mv openacs-4 <span class="emphasis"><i>birdnotes</i></span>
+nsadmin:/web$ mv openacs-4 <span class="emphasis"><em>birdnotes</em></span>
nsadmin:/web$ ls -l
total 4
-drwxr-xr-x 8 nsadmin nsadmin 4096 Dec 20 14:37 birdnotes</pre>
-</li>
-</ul></div>
-</div>
-<p>
+drwxr-xr-x 8 nsadmin nsadmin 4096 Dec 20 14:37 birdnotes</pre></li></ul></div></div><p>
Skip ahead if you want to <a href="openacs.html#install-openacs-prepare-postgres">Prepare PostgreSQL for OpenACS</a>
- </p>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="install-openacs-prepare-oracle"></a>Prepare Oracle for OpenACS</h3></div></div>
-<p>You should be logged on as
+ </p><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="install-openacs-prepare-oracle"></a>Prepare Oracle for OpenACS</h3></div></div><p>You should be logged on as
<tt>nsadmin</tt> for this step and you should
make sure that <tt>nsadmin</tt> is in the
- <tt>dba</tt> group.</p>
-<div class="itemizedlist"><ul>
-<li><p>
+ <tt>dba</tt> group.</p><div class="itemizedlist"><ul type="disc"><li><p>
Verify nsadmin membership by typing
<tt>groups</tt> when you login:
@@ -111,8 +69,7 @@
Make sure to logout as <tt>root</tt> when
you are finished with this step and log back in as
<tt>nsadmin</tt>.
- </p></li>
-<li><p>
+ </p></li><li><p>
Connect to Oracle using
<tt>svrmgrl</tt> and login:
@@ -121,8 +78,7 @@
SVRMGR> connect internal
Connected.</pre>
- </p></li>
-<li><p>
+ </p></li><li><p>
Determine where the system tablespaces are stored:
<pre class="programlisting">
@@ -137,8 +93,7 @@
/ora8/m01/app/oracle/oradata/ora8/users01.dbf
/ora8/m01/app/oracle/oradata/ora8/indx01.dbf
/ora8/m01/app/oracle/oradata/ora8/drsys01.dbf</pre>
- </p></li>
-<li><p>
+ </p></li><li><p>
Using the above output, you should determine where
to store your tablespace. As a general rule, you'll want to
store your tablespace on a mount point under the
@@ -152,24 +107,18 @@
12</a> of <a href="http://www.arsdigita.com/books/panda/" target="_top">Philip's
book</a>. For this example, we'll use
<tt>/ora8/m02/oradata/ora8/</tt>.
- </p></li>
-<li>
-<p>
+ </p></li><li><p>
Create the directory for the datafile; to do this,
exit from <tt>svrmgrl</tt> and login as
- <tt>root</tt> for this step: </p>
-<pre class="programlisting">
+ <tt>root</tt> for this step: </p><pre class="programlisting">
SVRMGR> exit
nsadmin:~$ su -
Password: ************
root:~# mkdir -p /ora8/m02/oradata/ora8/
root:~# chown nsadmin.web /ora8/m02/oradata/ora8
root:~# chmod 775 /ora8/m02/oradata/ora8
root:~# exit
-nsadmin:~$</pre>
-</li>
-<li>
-<p>
+nsadmin:~$</pre></li><li><p>
As <tt>nsadmin</tt>, create a tablespace for
the service. It is important that the tablespace can
<tt>autoextend</tt>. This allows the
@@ -178,185 +127,125 @@
extents won't grow geometrically. We do not set it to 0 at
the tablespace level because this would affect Oracle's
ability to automatically coalesce free space in the
- tablespace. </p>
-<pre class="programlisting">
+ tablespace. </p><pre class="programlisting">
nsadmin:~$ svrmgrl
SVRMGR> connect internal;
-SVRMGR> create tablespace <span class="emphasis"><i>birdnotes</i></span> datafile '/ora8/m02/oradata/ora8/<span class="emphasis"><i>birdnotes</i></span>01.dbf' size 50m autoextend on default storage (pctincrease 1);</pre>
-</li>
-<li>
-<p>
+SVRMGR> create tablespace <span class="emphasis"><em>birdnotes</em></span> datafile '/ora8/m02/oradata/ora8/<span class="emphasis"><em>birdnotes</em></span>01.dbf' size 50m autoextend on default storage (pctincrease 1);</pre></li><li><p>
Create a database user for this service. Give the
user access to the tablespace and rights to connect. We'll use
- <tt>birdnotespassword</tt> as our password.</p>
-<p>
- Write down what you specify as <span class="emphasis"><i>service_name</i></span>
+ <tt>birdnotespassword</tt> as our password.</p><p>
+ Write down what you specify as <span class="emphasis"><em>service_name</em></span>
(i.e. <tt>birdnotes</tt>) and
- <span class="emphasis"><i>database_password</i></span>
+ <span class="emphasis"><em>database_password</em></span>
(i.e. <tt>birdnotespassword</tt>). You
will need this information for configuring exports and
AOLserver.
- </p>
-<pre class="programlisting">
-SVRMGR> create user <span class="emphasis"><i>birdnotes</i></span> identified by <span class="emphasis"><i>birdnotespassword</i></span> default tablespace <span class="emphasis"><i>birdnotes</i></span>
-temporary tablespace temp quota unlimited on <span class="emphasis"><i>birdnotes</i></span>;
-SVRMGR> grant connect, resource, ctxapp, javasyspriv, query rewrite to <span class="emphasis"><i>birdnotes</i></span>;
-SVRMGR> revoke unlimited tablespace from <span class="emphasis"><i>birdnotes</i></span>;
-SVRMGR> alter user <span class="emphasis"><i>birdnotes</i></span> quota unlimited on <span class="emphasis"><i>birdnotes</i></span>;
-SVRMGR> exit;</pre>
-<p>
+ </p><pre class="programlisting">
+SVRMGR> create user <span class="emphasis"><em>birdnotes</em></span> identified by <span class="emphasis"><em>birdnotespassword</em></span> default tablespace <span class="emphasis"><em>birdnotes</em></span>
+temporary tablespace temp quota unlimited on <span class="emphasis"><em>birdnotes</em></span>;
+SVRMGR> grant connect, resource, ctxapp, javasyspriv, query rewrite to <span class="emphasis"><em>birdnotes</em></span>;
+SVRMGR> revoke unlimited tablespace from <span class="emphasis"><em>birdnotes</em></span>;
+SVRMGR> alter user <span class="emphasis"><em>birdnotes</em></span> quota unlimited on <span class="emphasis"><em>birdnotes</em></span>;
+SVRMGR> exit;</pre><p>
Your table space is now ready. In case you are trying to delete a
previous OpenACS installation, consult these commands in <a href="openacs.html#install-openacs-delete-tablespace" title="Deleting a tablespace">the section called “Deleting a tablespace”</a> below.
- </p>
-</li>
-<li>
-<p>
+ </p></li><li><p>
Make sure that you can login to Oracle using your
- <span class="emphasis"><i>service_name</i></span> account: </p>
-<pre class="programlisting">
-nsadmin:~$ sqlplus <span class="emphasis"><i>birdnotes</i></span>/<span class="emphasis"><i>birdnotespassword</i></span>
+ <span class="emphasis"><em>service_name</em></span> account: </p><pre class="programlisting">
+nsadmin:~$ sqlplus <span class="emphasis"><em>birdnotes</em></span>/<span class="emphasis"><em>birdnotespassword</em></span>
SQL> select sysdate from dual;
SYSDATE
----------
2001-12-20
-SQL> exit</pre>
-<p>
+SQL> exit</pre><p>
You should see today's date in a format 'YYYY-MM-DD.'
If you can't login, try redoing step 1 again. If the date is
in the wrong format, make sure you followed the steps outlined in
<a href="oracle.html#install-oracle-troubleshooting" title="Troubleshooting Oracle Dates">the section called “Troubleshooting Oracle Dates”</a>
- </p>
-</li>
-<li>
-<p>
+ </p></li><li><p>
Next we'll set up AOLserver so that it has the proper environment
variables set before launching. Download this <a href="files/nsd-oracle.txt" target="_top">nsd-oracle script</a> into
<tt>/tmp/nsd-oracle.txt</tt> :
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
nsadmin:~$ cp /tmp/nsd-oracle.txt ./bin/nsd-oracle
-nsadmin:~$ chmod 700 ./bin/nsd-oracle</pre>
-</li>
-</ul></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="install-openacs-prepare-postgres"></a>Prepare PostgreSQL for OpenACS</h3></div></div>
-<p>
+nsadmin:~$ chmod 700 ./bin/nsd-oracle</pre></li></ul></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="install-openacs-prepare-postgres"></a>Prepare PostgreSQL for OpenACS</h3></div></div><p>
Preparing PostgreSQL is just a little bit simpler than preparing
Oracle. We simply need to create a database with the name of our
- <span class="emphasis"><i>service-name</i></span>
+ <span class="emphasis"><em>service-name</em></span>
(i.e. <tt>birdnotes</tt>)
- </p>
-<pre class="programlisting">
-nsadmin:/web$ createdb <span class="emphasis"><i>birdnotes</i></span>
-CREATE DATABASE</pre>
-<p>Next we'll set up AOLserver so that it has the proper environment
+ </p><pre class="programlisting">
+nsadmin:/web$ createdb <span class="emphasis"><em>birdnotes</em></span>
+CREATE DATABASE</pre><p>Next we'll set up AOLserver so that it has the proper environment
variables set before launching. Download this <a href="files/nsd-postgres.txt" target="_top">nsd-postgres script</a> into
- <tt>/tmp/nsd-postgres.txt</tt> :</p>
-<pre class="programlisting">
+ <tt>/tmp/nsd-postgres.txt</tt> :</p><pre class="programlisting">
nsadmin:/web$ cd
nsadmin:~$ cp /tmp/nsd-postgres.txt ./bin/nsd-postgres
-nsadmin:~$ chmod 700 ./bin/nsd-postgres</pre>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="install-openacs-configure-aol"></a>Configuring AOLserver</h3></div></div>
-<p>
+nsadmin:~$ chmod 700 ./bin/nsd-postgres</pre></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="install-openacs-configure-aol"></a>Configuring AOLserver</h3></div></div><p>
The AOLserver architecture lets you run an arbitrary number of
virtual servers. A virtual server is an HTTP service running on a
specific port, e.g. port 80. In order for the OpenACS to work, you
need to configure a virtual server. Because the process is involved,
we have prepared a sample virtual server configuration file.
- </p>
-<div class="orderedlist"><ol type="1">
-<li><p>
+ </p><div class="orderedlist"><ol type="1"><li><p>
Download <a href="files/openacs4.tcl.txt" target="_top"><tt>openacs4.tcl.txt</tt></a>
into <tt>/tmp</tt>.
- </p></li>
-<li><p>
+ </p></li><li><p>
Modify it for your needs and save it in
<tt>/usr/local/aolserver/birdnotes.tcl</tt>
(Of course change <tt>birdnotes</tt> to
- whatever you're using as your <span class="emphasis"><i>service-name</i></span>
- </p></li>
-</ol></div>
-<pre class="programlisting">
-nsadmin:~$ cp /tmp/openacs4.tcl.txt ./<span class="emphasis"><i>birdnotes</i></span>.tcl
-nsadmin:~$ chmod 660 <span class="emphasis"><i>birdnotes</i></span>.tcl
-nsadmin:~$ emacs <span class="emphasis"><i>birdnotes</i></span>.tcl</pre>
-<p>
+ whatever you're using as your <span class="emphasis"><em>service-name</em></span>
+ </p></li></ol></div><pre class="programlisting">
+nsadmin:~$ cp /tmp/openacs4.tcl.txt ./<span class="emphasis"><em>birdnotes</em></span>.tcl
+nsadmin:~$ chmod 660 <span class="emphasis"><em>birdnotes</em></span>.tcl
+nsadmin:~$ emacs <span class="emphasis"><em>birdnotes</em></span>.tcl</pre><p>
Specifically, you'll have set the following variables
- </p>
-<div class="itemizedlist"><ul>
-<li><p>
- <span class="emphasis"><i>server</i></span> - This is the name of
+ </p><div class="itemizedlist"><ul type="disc"><li><p>
+ <span class="emphasis"><em>server</em></span> - This is the name of
the directory where your code resides. In our example above, we
- used <span class="emphasis"><i>birdnotes</i></span>.
- </p></li>
-<li><p>
-<span class="emphasis"><i>db_name</i></span> - In almost all cases,
+ used <span class="emphasis"><em>birdnotes</em></span>.
+ </p></li><li><p><span class="emphasis"><em>db_name</em></span> - In almost all cases,
this can be kept as a reference to $server. If for some reason,
the tablespace you are using is different than your servername,
then you can set it here. You should have a good reason for doing
this.
- </p></li>
-<li><p>
- <span class="emphasis"><i>servername</i></span> - This is just a
+ </p></li><li><p>
+ <span class="emphasis"><em>servername</em></span> - This is just a
*pretty* name for your server. For example, we might call ours
"Birdnotes.net Community"
- </p></li>
-<li><p>
-<span class="emphasis"><i>httpport</i></span> - If you want your
- server on a different port, enter it here</p></li>
-</ul></div>
-<p>
+ </p></li><li><p><span class="emphasis"><em>httpport</em></span> - If you want your
+ server on a different port, enter it here</p></li></ul></div><p>
AOLServer is very configurable. These settings should get you
started, but for more options, read the <a href="http://aolserver.com/docs/admin/config.adp" target="_top">AOLServer
docs</a>.
- </p>
-<p>
+ </p><p>
Kill any current running AOLserver processes and start a new
one. (Note, if you are using Oracle, rather than PostgreSQL, replace
<tt>nsd-postgres</tt> with
- <tt>nsd-oracle</tt>): </p>
-<pre class="programlisting">
+ <tt>nsd-oracle</tt>): </p><pre class="programlisting">
nsadmin:~$ killall nsd
; Should probably see:
nsd: no process killed
-nsadmin:~$ /usr/local/aolserver/bin/nsd-postgres -t /usr/local/aolserver/<span class="emphasis"><i>birdnotes</i></span>.tcl</pre>
-<p>
+nsadmin:~$ /usr/local/aolserver/bin/nsd-postgres -t /usr/local/aolserver/<span class="emphasis"><em>birdnotes</em></span>.tcl</pre><p>
Attempt to connect to the service from a web browser as you did
in the <a href="aolserver.html#install-aolserver-test">Test AOLserver</a> section. You should
specify a URL like:
- </p>
-<pre class="programlisting">
-http://<span class="emphasis"><i>ip_name</i></span>:<span class="emphasis"><i>ip_port</i></span>/</pre>
-<p>
+ </p><pre class="programlisting">
+http://<span class="emphasis"><em>ip_name</em></span>:<span class="emphasis"><em>ip_port</em></span>/</pre><p>
You should see a page that looks like <a href="files/openacs-start.html" target="_top">this</a> - if so, go on to <a href="openacs.html#install-openacs-using-installer">Using the OpenACS Installer</a>.
- </p>
-<p>
+ </p><p>
If you don't see the login page, view your error log
- (<tt>/usr/local/aolserver/log/<span class="emphasis"><i>birdnotes</i></span>-error.log</tt>)
+ (<tt>/usr/local/aolserver/log/<span class="emphasis"><em>birdnotes</em></span>-error.log</tt>)
to make sure the service is starting without any problems. If you
need to make changes, don't forget to kill any running
servers.
- </p>
-<pre class="programlisting">
-nsadmin:~$ killall nsd</pre>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="install-openacs-using-installer"></a>Using the OpenACS Installer</h3></div></div>
-<p>
+ </p><pre class="programlisting">
+nsadmin:~$ killall nsd</pre></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="install-openacs-using-installer"></a>Using the OpenACS Installer</h3></div></div><p>
Now that you've got AOLserver up and running, let's install OpenACS
4.5.
- </p>
-<div class="itemizedlist"><ul>
-<li><p>
+ </p><div class="itemizedlist"><ul type="disc"><li><p>
You should see a page from the webserver titled
<tt>OpenACS Installation:
Welcome</tt>. You will be warned if your version of
@@ -366,118 +255,80 @@
side. But if everything is fine, you can click
<tt>Next</tt> to proceed to load the
OpenACS Kernel data model.
- </p></li>
-<li>
-<p>
+ </p></li><li><p>
The next page shows the results of loading the OpenACS Kernel
data model - be prepared to wait a few minutes as it works. You
should see a string of "No errors." as the tables are
created. You'll see the line:
- </p>
-<pre class="programlisting">
-Loading package .info files ... this will take a few minutes</pre>
-<p>
+ </p><pre class="programlisting">
+Loading package .info files ... this will take a few minutes</pre><p>
This will really take a few minutes. Have faith! Finally,
another <tt>Next</tt> button will appear at
the bottom - click it.
- </p>
-</li>
-<li><p>
+ </p></li><li><p>
The following page shows the results of loading the package data
models. You should see positive results for each of the
previously selected packages, but watch out for any
errors. Eventually, the page will display "Generating secret
tokens" and then "Done"- click
<tt>Next</tt>.
- </p></li>
-<li><p>
+ </p></li><li><p>
You should see a page, "OpenACS Installation: Create
Administrator" with form fields to define the OpenACS site
administrator. Fill out the fields as appropriate, and click
<tt>Create User</tt>.
- </p></li>
-<li><p>
+ </p></li><li><p>
You should see a page, "OpenACS Installation: Set System
Information" allowing you to name your service. Fill out the
fields as appropriate, and click <tt>Set System
Information</tt>
- </p></li>
-<li>
-<p>
+ </p></li><li><p>
You'll see the final Installer page, "OpenACS
Installation: Complete." It will tell you that the server is
being restarted; note that unless you already set up a way for
AOLServer to restart itself (ie. inittab or daemontools),
you'll need to manually restart your service.
- </p>
-<pre class="programlisting">
-nsadmin:~$ /usr/local/aolserver/bin/nsd-postgres -t /usr/local/aolserver/<span class="emphasis"><i>birdnotes</i></span>.tcl</pre>
-</li>
-<li><p>
+ </p><pre class="programlisting">
+nsadmin:~$ /usr/local/aolserver/bin/nsd-postgres -t /usr/local/aolserver/<span class="emphasis"><em>birdnotes</em></span>.tcl</pre></li><li><p>
Give the server a few minutes to start up. Then
reload the final page above. You should see the front page, with
an area to login near the upper right. Congratulations, OpenACS
4.5 is now up and running!
- </p></li>
-</ul></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="install-openacs-keepalive"></a>Keep AOLserver alive</h3></div></div>
-<p>
+ </p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="install-openacs-keepalive"></a>Keep AOLserver alive</h3></div></div><p>
Now, we'll describe how to start AOLserver automatically on boot,
or whenever else the service dies.
- </p>
-<p>
+ </p><p>
There are 2 ways of doing this - via inittab or via daemontools. The
second way is by far the better way. Using daemontools gives you much
finer control over your servers and avoids the hassle of messing with
<tt>/etc/inittab</tt>. But, we'll describe
the inittab way as this may be easier for some users. I encourage
everyone to follow the links provided which describe how to <a href="openacs.html#install-openacs-daemontools">Install daemontools</a>.
- </p>
-<p>
-<span class="emphasis"><i>Important:</i></span> You need to set up
- <span class="emphasis"><i>either</i></span> inittab or daemontools, not both!</p>
-<div class="sect3">
-<div class="titlepage"><div><h4 class="title">
-<a name="install-openacs-inittab"></a>Editing inittab</h4></div></div>
-<p>
+ </p><p><span class="emphasis"><em>Important:</em></span> You need to set up
+ <span class="emphasis"><em>either</em></span> inittab or daemontools, not both!</p><div class="sect3"><div class="titlepage"><div><h4 class="title"><a name="install-openacs-inittab"></a>Editing inittab</h4></div></div><p>
This step should be completed as root. This can break every service
on your machine, so proceed with caution.
- </p>
-<div class="itemizedlist"><ul>
-<li>
-<p>
+ </p><div class="itemizedlist"><ul type="disc"><li><p>
There are 2 general steps to getting this working.
- </p>
-<div class="orderedlist"><ol type="1">
-<li><p>
+ </p><div class="orderedlist"><ol type="1"><li><p>
Install a script called
<tt>restart-aolserver</tt>. This
script doesn't actually restart AOLserver - it just kills
it.
- </p></li>
-<li><p>
+ </p></li><li><p>
Ask the OS to restart our service whenever it's not
running. We do this by adding a line to
<tt>/etc/inittab</tt>.
- </p></li>
-</ol></div>
-<p>
+ </p></li></ol></div><p>
Calling <tt>restart-aolserver</tt>
kills our service. The OS notices that our service is not
running, so it automatically restarts it. Thus, calling
<tt>restart-aolserver</tt> effectively
restarts our service.
- </p>
-</li>
-<li><p>
+ </p></li><li><p>
Copy this <a href="files/restart-aolserver.txt" target="_top">file</a> into
<tt>/tmp/restart-aolserver.txt</tt>.
- </p></li>
-<li>
-<p>
+ </p></li><li><p>
This script needs to be SUID-root, which means
that the script will run as root. This is necessary to ensure
that the AOLserver processes are killed regardless of who owns
@@ -487,330 +338,208 @@
general system users cannot run the script. You also need to
have Perl installed and also a symbolic link to it in
<tt>/usr/local/bin</tt>.
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
nsadmin:~$ su -
Password: ***********
root:~# cp /tmp/restart-aolserver.txt /usr/local/bin/restart-aolserver
root:~# chown root.web /usr/local/bin/restart-aolserver
root:~# chmod 4750 /usr/local/bin/restart-aolserver
root:~# ln -s /usr/bin/perl /usr/local/bin/perl
-root:~# exit</pre>
-</li>
-<li>
-<p>
+root:~# exit</pre></li><li><p>
Test the <tt>restart-aolserver</tt>
script. We'll first kill all running servers to clean the
slate. Then, we'll start one server and use
<tt>restart-aolserver</tt> to kill
it. If it works, then there should be no more servers
- running. You should see the following lines. </p>
-<pre class="programlisting">
+ running. You should see the following lines. </p><pre class="programlisting">
nsadmin:~$ killall nsd
nsd: no process killed
-nsadmin:~$ /usr/local/aolserver/bin/nsd-postgres -it /usr/local/aolserver/<span class="emphasis"><i>birdnotes</i></span>.tcl
-nsadmin:~$ restart-aolserver <span class="emphasis"><i>birdnotes</i></span>
+nsadmin:~$ /usr/local/aolserver/bin/nsd-postgres -it /usr/local/aolserver/<span class="emphasis"><em>birdnotes</em></span>.tcl
+nsadmin:~$ restart-aolserver <span class="emphasis"><em>birdnotes</em></span>
Killing 23727
nsadmin:~$ killall nsd
-nsd: no process killed</pre>
-<p>
+nsd: no process killed</pre><p>
The number 23727 indicates the process id(s) (PIDs) of the
- processes being killed. It is important that <span class="strong"><i>no processes are killed</i></span> by the second
+ processes being killed. It is important that <span class="strong"><em>no processes are killed</em></span> by the second
call to <tt>killall</tt>. If there are
processes being killed, it means that the script is not
- working.</p>
-</li>
-<li>
-<p>
+ working.</p></li><li><p>
Assuming that the <tt>restart-aolserver</tt>
script worked, login as root and open
<tt>/etc/inittab</tt> for
- editing. </p>
-<pre class="programlisting">
+ editing. </p><pre class="programlisting">
nsadmin:~$ su -
Password: ************
-root:~# emacs -nw /etc/inittab</pre>
-</li>
-<li>
-<p>
+root:~# emacs -nw /etc/inittab</pre></li><li><p>
Copy this line into the bottom of the file as a template,
making sure that the first field
<tt>nss1</tt> is unique.
- </p>
-<pre class="programlisting">
-nss1:2345:respawn:/usr/local/aolserver/bin/nsd-postgres -i -u nsadmin -g web -t /usr/local/aolserver/<span class="emphasis"><i>birdnotes</i></span>.tcl</pre>
-</li>
-<li><p>
- <span class="strong"><i>Important:</i></span> Make sure there is a
+ </p><pre class="programlisting">
+nss1:2345:respawn:/usr/local/aolserver/bin/nsd-postgres -i -u nsadmin -g web -t /usr/local/aolserver/<span class="emphasis"><em>birdnotes</em></span>.tcl</pre></li><li><p>
+ <span class="strong"><em>Important:</em></span> Make sure there is a
newline at the end of the file. If there is not a newline at
the end of the file, the system may suffer catastrophic
failures.
- </p></li>
-<li>
-<p>
+ </p></li><li><p>
Still as root, enter the following command to re-initialize
- <tt>/etc/inittab</tt>. </p>
-<pre class="programlisting">
+ <tt>/etc/inittab</tt>. </p><pre class="programlisting">
root:~# killall nsd
nsd: no process killed
-root:~# /sbin/init q</pre>
-</li>
-<li>
-<p>
+root:~# /sbin/init q</pre></li><li><p>
See if it worked by running the
<tt>restart-aolserver</tt> script
- again. </p>
-<pre class="programlisting">
-root:~# restart-aolserver <span class="emphasis"><i>birdnotes</i></span>
-Killing 23750</pre>
-</li>
-</ul></div>
-<p>
+ again. </p><pre class="programlisting">
+root:~# restart-aolserver <span class="emphasis"><em>birdnotes</em></span>
+Killing 23750</pre></li></ul></div><p>
If processes were killed, congratulations, your server is now
automated for startup and shutdown.
- </p>
-</div>
-<div class="sect3">
-<div class="titlepage"><div><h4 class="title">
-<a name="install-openacs-daemontools"></a>Install daemontools</h4></div></div>
-<p>
+ </p></div><div class="sect3"><div class="titlepage"><div><h4 class="title"><a name="install-openacs-daemontools"></a>Install daemontools</h4></div></div><p>
Installation instructions:
- <div class="variablelist"><dl>
-<dt><span class="term">Debian</span></dt>
-<dd><p>
-<pre class="programlisting">
+ </p><div class="variablelist"><dl><dt><span class="term">Debian</span></dt><dd><p><pre class="programlisting">
root:~# apt-get install daemontools-installer
root:~# build-daemontools
root:~# # answer 'yes' when asked to create symlink from /service to /var/lib/svscan</pre>
- </p></dd>
-<dt><span class="term">Red Hat</span></dt>
-<dd><p>RPMs for RH 6.2 and RPM 7.1 are available
+ </p></dd><dt><span class="term">Red Hat</span></dt><dd><p>RPMs for RH 6.2 and RPM 7.1 are available
<a href="http://untroubled.org/rpms/daemontools/" target="_top">http://untroubled.org/rpms/daemontools</a>. I
have not tested these, so I have no idea whether they work
properly.
- </p></dd>
-<dt><span class="term">Other distributions</span></dt>
-<dd><p>
+ </p></dd><dt><span class="term">Other distributions</span></dt><dd><p>
You can download the source directly from the author's site
at <a href="http://cr.yp.to/daemontools/install.html" target="_top">http://cr.yp.to/daemontools/install.html</a>.
- </p></dd>
-</dl></div>
- </p>
-<p>
+ </p></dd></dl></div><p>
+ </p><p>
Create a file called <tt>run</tt> inside
- <tt>/web/<span class="emphasis"><i>birdnotes</i></span></tt>:
- </p>
-<pre class="programlisting">
+ <tt>/web/<span class="emphasis"><em>birdnotes</em></span></tt>:
+ </p><pre class="programlisting">
nsadmin:~$ cd /web/birdnotes
-nsadmin:/web/birdnotes$ emacs run</pre>
-<p>
+nsadmin:/web/birdnotes$ emacs run</pre><p>
Copy this text into that file:
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
#!/bin/sh
-exec /usr/local/aolserver/bin/nsd-postgres -it /usr/local/aolserver/birdnotes.tcl -u nsadmin -g web</pre>
-<p>
+exec /usr/local/aolserver/bin/nsd-postgres -it /usr/local/aolserver/birdnotes.tcl -u nsadmin -g web</pre><p>
As root, change the ownership of this file:
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
nsadmin:/web/birdnotes$ su -
Password: ***********
root:~# chown root.root /web/birdnotes/run
-root:~# chmod 700 /web/birdnotes/run</pre>
-<p>
+root:~# chmod 700 /web/birdnotes/run</pre><p>
Now, we'll link our web root to the
<tt>/service</tt> directory. This causes
daemontools to monitor this directory. It should find your
<tt>run</tt> script and run it as soon as
you hit return.
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
root:~# killall nsd
root:~# ln -s /web/birdnotes /service
root:~# ps -A | grep nsd
19359 pts/3 00:00:08 nsd
19361 pts/3 00:00:00 nsd
19362 pts/3 00:00:00 nsd
19363 pts/3 00:00:00 nsd
-19364 pts/3 00:00:00 nsd</pre>
-<p>
+19364 pts/3 00:00:00 nsd</pre><p>
At this point, you should be able to use the
<tt>restart-aolserver</tt> script described
in <a href="openacs.html#install-openacs-inittab">Editing inittab</a>. Daemontools, however,
allows you much more precision control.
- </p>
-<div class="itemizedlist"><ul>
-<li><p>
+ </p><div class="itemizedlist"><ul type="disc"><li><p>
<tt>svc -d /web/birdnotes</tt> - Bring
the server down
- </p></li>
-<li><p>
+ </p></li><li><p>
<tt>svc -u /web/birdnotes</tt> - Start
the server up. Also, restart it whenever it stops.
- </p></li>
-<li><p>
+ </p></li><li><p>
<tt>svc -o /web/birdnotes</tt> - Start
the server up once. Do not restart it if it stops.
- </p></li>
-<li><p>
+ </p></li><li><p>
<tt>svc -t /web/birdnotes</tt> - Stop
and immediately restart the server
- </p></li>
-<li><p>
+ </p></li><li><p>
<tt>svc -k /web/birdnotes</tt> - Sends
the server a KILL signal. This is like KILL -9. AOLserver exits
immediately. If svc -t fails to fully kill AOLserver, use this
option.
- </p></li>
-</ul></div>
-<p>
+ </p></li></ul></div><p>
At this point, these commands will work only for the
<tt>root</tt> user. We can give a group
permission to run these commands as well. Download this <a href="files/svgroup.txt" target="_top">script</a> to
<tt>/tmp</tt>.
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
root:~# cp /tmp/svgroup.txt /usr/local/bin/svgroup
root:~# chmod 755 /usr/local/bin/svgroup
-root:~# svgroup web /service/birdnotes</pre>
-<p>
+root:~# svgroup web /service/birdnotes</pre><p>
This command will give the <tt>web</tt>
group permission to use <tt>svc</tt> commands
- on the <span class="emphasis"><i>birdnotes</i></span> server.
- </p>
-<p>
+ on the <span class="emphasis"><em>birdnotes</em></span> server.
+ </p><p>
Try it out. You may want to <tt>tail -f
/usr/local/aolserver/log/birdnotes-error.log</tt> in
another window, so you can see what happens when you type these
commands.
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
root:~# exit
nsadmin:~$ # first, bring the server down
nsadmin:~$ svc -d /web/birdnotes
nsadmin:~$ # now, start the server up
nsadmin:~$ svc -u /web/birdnotes
nsadmin:~$ # wait for server to come up, then restart it
-nsadmin:~$ svc -t /web/birdnotes</pre>
-<p>
- Most of this information comes from Tom Jackson's <a href="http://zmbh.com/discussion/svc/aolserver+daemontools.html" target="_top">AOLServer+Daemontools
+nsadmin:~$ svc -t /web/birdnotes</pre><p>
+ Most of this information comes from Tom Jackson's <a href="http://zmbh.com/discussion/svc/aolserver%2Bdaemontools.html" target="_top">AOLServer+Daemontools
Mini-HOWTO</a>.
- </p>
-</div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="install-openacs-port80"></a>Running AOLserver on Port 80</h3></div></div>
-<p>
+ </p></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="install-openacs-port80"></a>Running AOLserver on Port 80</h3></div></div><p>
If you want to run the service on port 80 (the default HTTP port),
you need to set the port to 80 in your
<tt>service_name.tcl</tt> file in
<tt>/usr/local/aolserver</tt>.
- </p>
-<p>
+ </p><p>
Moreover, you will need to start the service as
<tt>root</tt>. If you follow the instructions
above for <a href="openacs.html#install-openacs-keepalive" title="Keep AOLserver alive">automating
startup</a>, this will be taken care of, but if you ever start the
server from the command line, be sure to <tt>su
-</tt> first.
- </p>
-<p>
- Port 80 is a <span class="emphasis"><i>privileged</i></span> port. Only certain users
+ </p><p>
+ Port 80 is a <span class="emphasis"><em>privileged</em></span> port. Only certain users
can claim it. When you start <tt>nsd</tt> as
root, it obtains the port, and then changes to run as whatever user
you specify in the server configuration file. This ensures a high
level of security, as the server, once started, is not running as
<tt>root</tt>. This mean that if someone was
able to exploit your web server to execute a command on your server,
they would not be able to gain <tt>root</tt>
- access.</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="install-openacs-delete-tablespace"></a>Deleting a tablespace</h3></div></div>
-<p>Skip down for instructions on <a href="openacs.html#install-openacs-delete-postgres-tablespace">Deleting a PostgreSQL tablespace</a>.
- </p>
-<div class="sect3">
-<div class="titlepage"><div><h4 class="title">
-<a name="install-openacs-delete-oracle-tablespace"></a>Deleting an Oracle tablespace</h4></div></div>
-<p>
+ access.</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="install-openacs-delete-tablespace"></a>Deleting a tablespace</h3></div></div><p>Skip down for instructions on <a href="openacs.html#install-openacs-delete-postgres-tablespace">Deleting a PostgreSQL tablespace</a>.
+ </p><div class="sect3"><div class="titlepage"><div><h4 class="title"><a name="install-openacs-delete-oracle-tablespace"></a>Deleting an Oracle tablespace</h4></div></div><p>
Should it become necessary to rebuild a tablespace from scratch,
you can use the <tt>drop user</tt> command
in SVRMGRL with the <tt>cascade</tt>
option. This command will drop the user and every database object
- the user owns.</p>
-<pre class="programlisting">
-SVRMGR> drop user <span class="emphasis"><i>birdnotes</i></span> cascade;</pre>
-<p>
+ the user owns.</p><pre class="programlisting">
+SVRMGR> drop user <span class="emphasis"><em>birdnotes</em></span> cascade;</pre><p>
If this does not work because svrmgrl "cannot drop a user that
is currently connected", make sure to kill the AOLserver using
- this user. If it still does not work, do:</p>
-<pre class="programlisting">
-SVRMGR> select username, sid, serial# from v$session where username='<span class="emphasis"><i>birdnotes</i></span>';</pre>
-<p>and then</p>
-<pre class="programlisting">
-SVRMGR> alter system kill session '<span class="emphasis"><i>sid</i></span>,<span class="emphasis"><i>serial#</i></span>';</pre>
-<p>
- where <span class="emphasis"><i>sid</i></span> and <span class="emphasis"><i>serial#</i></span> are
- replaced with the corresponding values for the open session.</p>
-<p><span class="strong"><i>Use with caution!</i></span></p>
-<p>
- If you feel the need to delete <span class="emphasis"><i>everything</i></span>
- related to the service, you can also issue the following:</p>
-<pre class="programlisting">
-SVRMGR> drop tablespace <span class="emphasis"><i>birdnotes</i></span> including contents cascade constraints;</pre>
-</div>
-<div class="sect3">
-<div class="titlepage"><div><h4 class="title">
-<a name="install-openacs-delete-postgres-tablespace"></a>Deleting a PostgreSQL tablespace</h4></div></div>
-<p>
+ this user. If it still does not work, do:</p><pre class="programlisting">
+SVRMGR> select username, sid, serial# from v$session where username='<span class="emphasis"><em>birdnotes</em></span>';</pre><p>and then</p><pre class="programlisting">
+SVRMGR> alter system kill session '<span class="emphasis"><em>sid</em></span>,<span class="emphasis"><em>serial#</em></span>';</pre><p>
+ where <span class="emphasis"><em>sid</em></span> and <span class="emphasis"><em>serial#</em></span> are
+ replaced with the corresponding values for the open session.</p><p><span class="strong"><em>Use with caution!</em></span></p><p>
+ If you feel the need to delete <span class="emphasis"><em>everything</em></span>
+ related to the service, you can also issue the following:</p><pre class="programlisting">
+SVRMGR> drop tablespace <span class="emphasis"><em>birdnotes</em></span> including contents cascade constraints;</pre></div><div class="sect3"><div class="titlepage"><div><h4 class="title"><a name="install-openacs-delete-postgres-tablespace"></a>Deleting a PostgreSQL tablespace</h4></div></div><p>
Dropping a PostgreSQL tablespace is easy. You have to stop any
AOLserver instances that are using the database that you wish to
drop. If you're using daemontools, this is simple, just use the
'down' flag (-d). If you're using inittab, you have to comment out
your server in <tt>/etc/inittab</tt>,
reread the inittab with <tt>/sbin/init
q</tt>, and then <tt>restart-aolserver
- <span class="emphasis"><i>birdnotes</i></span></tt>.</p>
-<p>Then, to drop the db, just do:</p>
-<pre class="programlisting">
-nsadmin:~$ dropdb <span class="emphasis"><i>birdnotes</i></span>
-DROP DATABASE</pre>
-</div>
-</div>
-<p><div class="cvstag">($Id$)</div></p>
-</div>
-<div class="navfooter">
-<hr>
-<table width="100%" summary="Navigation footer">
-<tr>
-<td width="40%" align="left">
-<a accesskey="p" href="aolserver.html">Prev</a> </td>
-<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
-<td width="40%" align="right"> <a accesskey="n" href="nextsteps.html">Next</a>
-</td>
-</tr>
-<tr>
-<td width="40%" align="left">Install AOLserver 3.3+ad13 </td>
-<td width="20%" align="center"><a accesskey="u" href="unix-install.html">Up</a></td>
-<td width="40%" align="right"> Next Steps</td>
-</tr>
-</table>
-<hr>
-<address>
- rmello at fslc.usu.edu
- </address>
-<address><a href="mailto:vinod@kurup.com">
+ <span class="emphasis"><em>birdnotes</em></span></tt>.</p><p>Then, to drop the db, just do:</p><pre class="programlisting">
+nsadmin:~$ dropdb <span class="emphasis"><em>birdnotes</em></span>
+DROP DATABASE</pre></div></div><p><div class="cvstag">($Id$)</div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="aolserver.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="nextsteps.html">Next</a></td></tr><tr><td width="40%" align="left">Install AOLserver 3.3+ad13 </td><td width="20%" align="center"><a accesskey="u" href="unix-install.html">Up</a></td><td width="40%" align="right"> Next Steps</td></tr></table><hr><address>rmello at fslc.usu.edu</address><address><a href="mailto:vinod@kurup.com">
vinod@kurup.com
- </a></address>
-</div>
-</body>
-</html>
+ </a></address></div></body></html>
Index: openacs-4/packages/acs-core-docs/www/operating-system.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/Attic/operating-system.html,v
diff -u -r1.7 -r1.7.2.1
--- openacs-4/packages/acs-core-docs/www/operating-system.html 7 Mar 2002 06:55:36 -0000 1.7
+++ openacs-4/packages/acs-core-docs/www/operating-system.html 15 May 2002 23:26:18 -0000 1.7.2.1
@@ -1,247 +1,109 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type">
-<title>Install an Operating System</title>
-<meta name="generator" content="DocBook XSL Stylesheets V1.45">
-<link rel="home" href="index.html" title="OpenACS Documentation">
-<link rel="up" href="unix-install.html" title="Chapter 2. Installing on Unix/Linux">
-<link rel="previous" href="install-overview.html" title="Overview">
-<link rel="next" href="oracle.html" title="Install Oracle 8.1.7">
-<link rel="stylesheet" href="openacs.css" type="text/css">
-</head>
-<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-<div class="navheader">
-<a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr>
-<td width="20%" align="left">
-<a accesskey="p" href="install-overview.html">Prev</a> </td>
-<th width="60%" align="center">Chapter 2. Installing on Unix/Linux</th>
-<td width="20%" align="right"> <a accesskey="n" href="oracle.html">Next</a>
-</td>
-</tr></table>
-<hr>
-</div>
-<div class="sect1">
-<div class="titlepage"><div><h2 class="title" style="clear: both">
-<a name="operating-system"></a>Install an Operating System</h2></div></div>
-<p>
+<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"><title>Install an Operating System</title><meta name="generator" content="DocBook XSL Stylesheets V1.50.0"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="unix-install.html" title="Chapter 2. Installing on Unix/Linux"><link rel="previous" href="install-overview.html" title="Overview"><link rel="next" href="oracle.html" title="Install Oracle 8.1.7"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="install-overview.html">Prev</a> </td><th width="60%" align="center">Chapter 2. Installing on Unix/Linux</th><td width="20%" align="right"> <a accesskey="n" href="oracle.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="operating-system"></a>Install an Operating System</h2></div></div><div class="authorblurb"><p>
+ by <a href="mailto:vinod@kurup.com" target="_top">Vinod Kurup</a><br>
+ OpenACS docs are written by the named authors, but may be edited
+ by OpenACS documentation staff.
+ </p></div><p>
We won't provide detailed instructions to install an operating system
since there are so many valid choices available and each OS has their
own installation procedures.
- </p>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="os-other"></a>Other OpenACS Guides</h3></div></div>
-<p>
+ </p><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="os-other"></a>Other OpenACS Guides</h3></div></div><p>
Members of the OpenACS community use a variety of UNIX, Linux, BSD
and even Windows systems. The remainder of this guide will
be specific to Linux. Users of other OS's may find some helpful
information here, but we recommend that you instead use one of these
OS specific guides to install OpenACS 4.5.
- </p>
-<div class="itemizedlist"><ul>
-<li><p>
+ </p><div class="itemizedlist"><ul type="disc"><li><p>
<a href="http://www.orchardlabs.com/freebsd/" target="_top">FreeBSD guide</a>
- </p></li>
-<li>
-<p>
+ </p></li><li><p>
<a href="http://openacs.org/new-file-storage/one-folder?file_id=209" target="_top">Mac OS X guide</a>
- </p>
-<p>
+ </p><p>
This guide is currently valid for Mac OS 10.04, but it's being
updated for OS 10.1 as we speak. In the meantime, eager 10.1
- users can see this <a href="http://openacs.org/bboard/q-and-a-fetch-msg.tcl?msg_id=0002mP&topic_id=11&topic=OpenACS" target="_top">bboard
+ users can see this <a href="http://openacs.org/bboard/q-and-a-fetch-msg.tcl?msg_id=0002mP%26amp;topic_id=11%26amp;topic=OpenACS" target="_top">bboard
thread</a> for some help.
- </p>
-</li>
-<li>
-<p>
+ </p></li><li><p>
<a href="win2k-installation.html">OpenACS Installation Guide for Windows 2000</a>
- </p>
-<p>
- This was written for ACS and has <span class="emphasis"><i>not</i></span> yet been updated for
- OpenACS. (Note: AOLServer is no longer supporting Windows
- - it may be possible to run AOLServer under
- <a href="http://www.cygwin.com" target="_top">Cygwin</a>, but I
- haven't seen any success reports yet).
- </p>
-</li>
-</ul></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="os-linux"></a>Linux Information</h3></div></div>
-<p>
+ </p><p>
+ This was written for ACS and has <span class="emphasis"><em>not</em></span> yet
+ been updated for OpenACS. (Note: AOLServer is no longer
+ supporting Windows - it may be possible to run AOLServer under
+ <a href="http://www.cygwin.com" target="_top">Cygwin</a>, but I haven't
+ seen any success reports yet). Another alternative is to use John
+ Sequeira's <a href="http://www.pobox.com/~johnseq/projects/oasisvm/" target="_top">Oasis
+ VM</a>, which is basically a fully working OpenACS 4.5
+ system that you load into <a href="http://vmware.com" target="_top">VMware</a>.
+ </p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="os-linux"></a>Linux Information</h3></div></div><p>
I'm currently using Debian GNU/Linux, so this guide may show that
bias. Installation on any Linux distribution should be similar and
we'll try to point out differences where they exist.
- </p>
-<p>
+ </p><p>
When you do install your system, be sure to set up enough swap space
- at least 400 MB for Oracle, less for PostgreSQL. A rule of thumb is
to set aside a swap partition which is twice your RAM size.
- </p>
-<p>
+ </p><p>
Some things that you will need:
- </p>
-<div class="informaltable"><table border="1">
-<colgroup>
-<col>
-<col>
-</colgroup>
-<thead><tr>
-<th>Requirement</th>
-<th>Reason</th>
-</tr></thead>
-<tbody>
-<tr>
-<td>recent kernel</td>
-<td>Currently version 2.2.19 or
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Requirement</th><th>Reason</th></tr></thead><tbody><tr><td>recent kernel</td><td>Currently version 2.2.19 or
greater is the standard requirement. Some people are using 2.4.x
- (2.4.16) kernels.</td>
-</tr>
-<tr>
-<td>bash </td>
-<td>Bash is the standard Linux shell.
+ (2.4.16) kernels.</td></tr><tr><td>bash </td><td>Bash is the standard Linux shell.
We assume you are using bash for these instructions. If you're
not using bash, then you will need to substitute your shell's
conventions for setting environment variables when appropriate.
- </td>
-</tr>
-<tr>
-<td>glib 2.1 (or greater)</td>
-<td>You need recent versions of
- these libraries for Oracle to work properly. </td>
-</tr>
-<tr>
-<td>perl (and perl-suid)</td>
-<td>
+ </td></tr><tr><td>glib 2.1 (or greater)</td><td>You need recent versions of
+ these libraries for Oracle to work properly. </td></tr><tr><td>perl (and perl-suid)</td><td>
A few parts of the ACS require <a href="http://www.perl.org/" target="_top">perl</a> to work correctly.
(Debian users: <tt>apt-get install
- perl-suid</tt>)</td>
-</tr>
-<tr>
-<td>GNU Make (3.76.1 or better)</td>
-<td>
+ perl-suid</tt>)</td></tr><tr><td>GNU Make (3.76.1 or better)</td><td>
PostgreSQL and AOLServer require gmake to compile. Note that
on some linux distributions, GNU Make is simply named
<tt>make</tt> and there is no
<tt>gmake</tt>, whereas on BSD
distributions, <tt>make</tt> and
<tt>gmake</tt> are different.
- </td>
-</tr>
-<tr>
-<td>Tcl 8.3 development package (headers, libraries)</td>
-<td>
+ </td></tr><tr><td>Tcl 8.3 development package (headers, libraries)</td><td>
The site-wide-search service, OpenFTS, requires these to
compile. (Debian users: <tt>apt-get install
tcl8.3-dev</tt>)
- </td>
-</tr>
-<tr>
-<td>libxml2</td>
-<td>
+ </td></tr><tr><td>libxml2</td><td>
OpenACS 4.5 stores queries in XML files, so libxml2 is used to
parse these files. (Debian users: <tt>apt-get
install libxml2-dev</tt>)
- </td>
-</tr>
-</tbody>
-</table></div>
-<p>
+ </td></tr></tbody></table></div><p>
Locations:
- </p>
-<div class="itemizedlist"><ul>
-<li><p>
+ </p><div class="itemizedlist"><ul type="disc"><li><p>
We'll compile stuff in
<tt>/usr/local/src</tt>
- </p></li>
-<li><p>
+ </p></li><li><p>
PostgreSQL will go into <tt>/usr/local/pgsql</tt>
- </p></li>
-<li><p>
+ </p></li><li><p>
AOLServer will go into <tt>/usr/local/aolserver</tt>
- </p></li>
-<li><p>
+ </p></li><li><p>
The web root will go into <tt>/web</tt>
- </p></li>
-</ul></div>
-<p>
+ </p></li></ul></div><p>
None of these locations are set in stone - they're simply the values
that we've chosen. You are free to install your software in other
locations, but you'll need to adjust the instructions in this
document to point to those locations.
- </p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="os-install"></a>Linux Install Guides</h3></div></div>
-<p>
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="os-install"></a>Linux Install Guides</h3></div></div><p>
Here's a list of some helpful documentation for various OS's
- </p>
-<div class="itemizedlist"><ul>
-<li><p>
+ </p><div class="itemizedlist"><ul type="disc"><li><p>
<a href="http://tinyplanet.ca/pubs/debian/" target="_top">Painless Debian
GNU/Linux</a> by Stephen van Egmond
- </p></li>
-<li><p> <a href="http://www.debian.org/releases/stable/installmanual" target="_top">Official
- Debian Guide</a> </p></li>
-<li><p><a href="http://www.redhat.com/docs/manuals/linux/" target="_top">RedHat</a></p></li>
-<li><p><a href="http://www.linux-mandrake.com/en/fdoc.php3" target="_top">Mandrake</a></p></li>
-<li><p><a href="http://sdb.suse.de/sdb/en/html/" target="_top">SuSE</a></p></li>
-</ul></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="os-security"></a>Security Information</h3></div></div>
-<p>
+ </p></li><li><p> <a href="http://www.debian.org/releases/stable/installmanual" target="_top">Official
+ Debian Guide</a> </p></li><li><p><a href="http://www.redhat.com/docs/manuals/linux/" target="_top">RedHat</a></p></li><li><p><a href="http://www.linux-mandrake.com/en/fdoc.php3" target="_top">Mandrake</a></p></li><li><p><a href="http://sdb.suse.de/sdb/en/html/" target="_top">SuSE</a></p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="os-security"></a>Security Information</h3></div></div><p>
Once you get your OS installed, it's imperative that you secure your
installation. As Jon Griffin repeatedly warns us, "No distribution is
secure out of the box." Again, this topic is too big to cover properly
here, so see these links.
- </p>
-<div class="itemizedlist"><ul>
-<li><p>
+ </p><div class="itemizedlist"><ul type="disc"><li><p>
<a href="http://jongriffin.com/static/linuxnotes" target="_top">Jon Griffin's notes</a>
- </p></li>
-<li><p>
+ </p></li><li><p>
<a href="http://www.seifried.org/lasg/" target="_top">Linux Administrators Security Guide</a>
- </p></li>
-<li><p>
+ </p></li><li><p>
<a href="http://www.suse.com/en/support/howto/secure_webserv/index.html" target="_top">Installation
of a Secure Webserver</a>
- </p></li>
-<li><p>
+ </p></li><li><p>
Others?
- </p></li>
-</ul></div>
-</div>
-<p><div class="cvstag">($Id$)</div></p>
-</div>
-<div class="navfooter">
-<hr>
-<table width="100%" summary="Navigation footer">
-<tr>
-<td width="40%" align="left">
-<a accesskey="p" href="install-overview.html">Prev</a> </td>
-<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
-<td width="40%" align="right"> <a accesskey="n" href="oracle.html">Next</a>
-</td>
-</tr>
-<tr>
-<td width="40%" align="left">Overview </td>
-<td width="20%" align="center"><a accesskey="u" href="unix-install.html">Up</a></td>
-<td width="40%" align="right"> Install Oracle 8.1.7</td>
-</tr>
-</table>
-<hr>
-<address>
- rmello at fslc.usu.edu
- </address>
-<address><a href="mailto:vinod@kurup.com">
+ </p></li></ul></div></div><p><div class="cvstag">($Id$)</div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="install-overview.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="oracle.html">Next</a></td></tr><tr><td width="40%" align="left">Overview </td><td width="20%" align="center"><a accesskey="u" href="unix-install.html">Up</a></td><td width="40%" align="right"> Install Oracle 8.1.7</td></tr></table><hr><address>rmello at fslc.usu.edu</address><address><a href="mailto:vinod@kurup.com">
vinod@kurup.com
- </a></address>
-</div>
-</body>
-</html>
+ </a></address></div></body></html>
Index: openacs-4/packages/acs-core-docs/www/oracle.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/oracle.html,v
diff -u -r1.7 -r1.7.2.1
--- openacs-4/packages/acs-core-docs/www/oracle.html 7 Mar 2002 06:55:36 -0000 1.7
+++ openacs-4/packages/acs-core-docs/www/oracle.html 15 May 2002 23:26:18 -0000 1.7.2.1
@@ -1,225 +1,131 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type">
-<title>Install Oracle 8.1.7</title>
-<meta name="generator" content="DocBook XSL Stylesheets V1.45">
-<link rel="home" href="index.html" title="OpenACS Documentation">
-<link rel="up" href="unix-install.html" title="Chapter 2. Installing on Unix/Linux">
-<link rel="previous" href="operating-system.html" title="Install an Operating System">
-<link rel="next" href="postgres.html" title="Install PostgreSQL 7.1.3">
-<link rel="stylesheet" href="openacs.css" type="text/css">
-</head>
-<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-<div class="navheader">
-<a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr>
-<td width="20%" align="left">
-<a accesskey="p" href="operating-system.html">Prev</a> </td>
-<th width="60%" align="center">Chapter 2. Installing on Unix/Linux</th>
-<td width="20%" align="right"> <a accesskey="n" href="postgres.html">Next</a>
-</td>
-</tr></table>
-<hr>
-</div>
-<div class="sect1">
-<div class="titlepage"><div><h2 class="title" style="clear: both">
-<a name="oracle"></a>Install Oracle 8.1.7</h2></div></div>
-<p>Skip this page if you're not interested in Oracle</p>
-<p>
-<span class="strong"><i>NOTE:</i></span><span class="emphasis"><i> This document
- was originally written based on Oracle, version 8.1.6. However, the
- same approach should lead to a successful installation of Oracle
- 8.1.7. If you encounter any incompatibilities, please <a href="mailto:vinod@kurup.com" target="_top">let us know</a></i></span>
- </p>
-<p>
-<span class="strong"><i>NOTE:</i></span> We've not yet tested
- OpenACS 4.5 under Oracle 9i</p>
-<p>
-<span class="strong"><i>NOTE:</i></span> This document assumes that
+<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"><title>Install Oracle 8.1.7</title><meta name="generator" content="DocBook XSL Stylesheets V1.50.0"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="unix-install.html" title="Chapter 2. Installing on Unix/Linux"><link rel="previous" href="operating-system.html" title="Install an Operating System"><link rel="next" href="postgres.html" title="Install PostgreSQL 7.1.3"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="operating-system.html">Prev</a> </td><th width="60%" align="center">Chapter 2. Installing on Unix/Linux</th><td width="20%" align="right"> <a accesskey="n" href="postgres.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="oracle"></a>Install Oracle 8.1.7</h2></div></div><div class="authorblurb"><p>
+ by <a href="mailto:vinod@kurup.com" target="_top">Vinod Kurup</a><br>
+ OpenACS docs are written by the named authors, but may be edited
+ by OpenACS documentation staff.
+ </p></div><p>Skip this page if you're not interested in Oracle</p><p><span class="strong"><em>NOTE:</em></span> We've not yet tested
+ OpenACS 4.5 under Oracle 9i</p><p><span class="strong"><em>NOTE:</em></span> This document assumes that
you'll be installing Oracle on the same box as AOLServer. For more
details on a remote Oracle installation, see Daryl Biberdorf's <a href="http://openacs.org/new-file-storage/one-file?file_id=273" target="_top">document</a>.
- </p>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="install-oracle-getit"></a>Acquire Oracle 8.1.7 Enterprise Edition</h3></div></div>
-<p>
+ </p><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="install-oracle-getit"></a>Acquire Oracle 8.1.7 Enterprise Edition</h3></div></div><p>
You can obtain the software through a variety of methods (You'll need
to become a member of <a href="http://technet.oracle.com" target="_top">technet.oracle.com</a>, which is
free):
- </p>
-<div class="orderedlist"><ol type="1">
-<li><p>
+ </p><div class="orderedlist"><ol type="1"><li><p>
Order a CD from the <a href="http://oraclestore.oracle.com" target="_top">Oracle
Store</a>. The cost is currently $39.95 for a 30-day
evaluation copy with delivery estimated between 3-4 business
days.
- </p></li>
-<li>
-<p>
+ </p></li><li><p>
Download the software from the <a href="http://otn.oracle.com/software/content.html" target="_top">
Oracle Downloads</a> page.
- </p>
-<div class="itemizedlist"><ul>
-<li><p>
+ </p><div class="itemizedlist"><ul type="disc"><li><p>
Oracle 8.1.7 now comes with a Java RunTime
Environment built-in to the distribution, so you no longer
have to download and install it separately.
- </p></li>
-<li>
-<p>
+ </p></li><li><p>
After the download is complete, untar the file
to a convenient location. To do this, you will need to login
and cd to the directory where the archive is.
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
$ cd /directory/where/oracle/is
-$ tar -xvf oracle81701.tar</pre>
-</li>
-</ul></div>
-</li>
-<li><p>
+$ tar xvf oracle81701.tar</pre></li></ul></div></li><li><p>
It used to be possible to get a free CD by mail, but
I can no longer find the link for that option.
- </p></li>
-</ol></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="install-oracle-keepinmind"></a>Things to Keep in Mind</h3></div></div>
-<p>
+ </p></li></ol></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="install-oracle-keepinmind"></a>Things to Keep in Mind</h3></div></div><p>
Throughout these instructions, we will refer to a number of
configurable settings and advise certain defaults. With the exception
of passwords, we advise you to follow these defaults unless you know
what you are doing. Subsequent documents will expect that you used
the defaults, so a change made here will necessitate further changes
later. For a guide to the defaults, please see <a href="oracle.html#install-oracle-defaults" title="Defaults">the section called “Defaults”</a>.
- </p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="install-oracle-preinstall"></a>Pre-Installation Tasks</h3></div></div>
-<p>
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="install-oracle-preinstall"></a>Pre-Installation Tasks</h3></div></div><p>
Though Oracle 8.1.7 has an automated installer, we still need to
perform several manual, administrative tasks before we can launch
it. You must perform all of these steps as the
<tt>root</tt> user. We recommend entering the
X window system as a normal user and then doing a <tt>su
-</tt>. This command gives you full root access.
- </p>
-<div class="itemizedlist"><ul>
-<li><p>
+ </p><div class="itemizedlist"><ul type="disc"><li><p>
Login as a non-root user and start X by typing
<tt>startx</tt>
<pre class="programlisting">
joeuser:~$ startx</pre>
- </p></li>
-<li><p>
+ </p></li><li><p>
Open a terminal window type and login as root
<pre class="programlisting">
joeuser:~$ su -
Password: ***********
root:~#</pre>
- </p></li>
-<li>
-<p>
+ </p></li><li><p>
Create and setup the <tt>oracle</tt>
group and <tt>oracle</tt> account
- </p>
-<p>
+ </p><p>
We need to create a user <tt>oracle</tt>,
which is used to install the product, as well as starting and
stopping the database.
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
root:~# groupadd dba
root:~# groupadd oinstall
root:~# groupadd oracle
root:~# useradd -g dba -G oinstall,oracle -m oracle
-root:~# passwd oracle</pre>
-<p>
+root:~# passwd oracle</pre><p>
You will be prompted for the New Password and Confirmation of
that password.
- </p>
-</li>
-<li>
-<p> Setup the installation location for Oracle. While
+ </p></li><li><p> Setup the installation location for Oracle. While
Oracle can reside in a variety of places in the file system,
OpenACS has adopted <tt>/ora8</tt> as the
base directory.
- </p>
-<p>
- <span class="strong"><i>Note:</i></span> the Oracle install needs
+ </p><p>
+ <span class="strong"><em>Note:</em></span> the Oracle install needs
about 1 GB free on <tt>/ora8</tt> to
install successfully.
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
root:~# mkdir /ora8
root:/ora8# cd /ora8
root:/ora8# mkdir -p m01 m02 m03/oradata/ora8
root:/ora8# chown -R oracle.dba /ora8
-root:/ora8# exit</pre>
-</li>
-<li>
-<p>
+root:/ora8# exit</pre></li><li><p>
Set up the <tt>oracle</tt> user's
environment
- </p>
-<div class="itemizedlist"><ul>
-<li>
-<p>
+ </p><div class="itemizedlist"><ul type="round"><li><p>
Log in as the user
<tt>oracle</tt> by typing the
following:
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
joeuser:~$ su - oracle
-Password: ********</pre>
-</li>
-<li>
-<p>
+Password: ********</pre></li><li><p>
Use a text editor to edit the
<tt>.bash_profile</tt> file in the
<tt>oracle</tt> account home
directory.
- </p>
-<pre class="programlisting">
-oracle:~$ emacs .bash_profile</pre>
-<p>
+ </p><pre class="programlisting">
+oracle:~$ emacs .bash_profile</pre><p>
You may get this error trying to start emacs:
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
Xlib: connection to ":0.0" refused by server
Xlib: Client is not authorized to connect to Server
emacs: Cannot connect to X server :0.
Check the DISPLAY environment variable or use `-d'.
Also use the `xhost' program to verify that it is set to permit
-connections from your machine.</pre>
-<p>
+connections from your machine.</pre><p>
If so, open a new terminal window and do the following:
- </p>
-<pre class="programlisting">
-joeuser:~$ xhost +localhost</pre>
-<p>
+ </p><pre class="programlisting">
+joeuser:~$ xhost +localhost</pre><p>
Now, back in the oracle terminal:
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
oracle:~$ export DISPLAY=localhost:0.0
-oracle:~$ emacs .bash_profile</pre>
-<p>
+oracle:~$ emacs .bash_profile</pre><p>
Try this procedure anytime you get an Xlib connection refused
error.
- </p>
-</li>
-<li>
-<p>
+ </p></li><li><p>
Add the following lines (substituting your
Oracle version number as needed) to
<tt>.bash_profile</tt>:
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
export ORACLE_BASE=/ora8/m01/app/oracle
export ORACLE_HOME=$ORACLE_BASE/product/8.1.7
export PATH=$PATH:$ORACLE_HOME/bin
@@ -228,58 +134,41 @@
export ORACLE_TERM=vt100
export ORA_NLS33=$ORACLE_HOME/ocommon/nls/admin/data
-umask 022</pre>
-<p>
+umask 022</pre><p>
Save the file by typing <tt>CTRL-X
CTRL-S</tt> and then exit by typing
<tt>CTRL-X
CTRL-C</tt>. Alternatively, use the
menus.
- </p>
-</li>
-</ul></div>
-<p>
- Make sure that you do <span class="strong"><i>not</i></span> add
+ </p></li></ul></div><p>
+ Make sure that you do <span class="strong"><em>not</em></span> add
any lines like the following
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
# NLS_LANG=american
-# export NLS_LANG</pre>
-<p>
+# export NLS_LANG</pre><p>
These lines will change the Oracle date settings and will break
OpenACS since OpenACS depends on the ANSI date format, YYYY-MM-DD
dates.
- </p>
-</li>
-<li>
-<p>
+ </p></li><li><p>
Log out as oracle
- </p>
-<pre class="programlisting">
-oracle:~$ exit</pre>
-</li>
-<li>
-<p>
+ </p><pre class="programlisting">
+oracle:~$ exit</pre></li><li><p>
Log back in as <tt>oracle</tt> and double
check that your environment variables are as intended. The
<tt>env</tt> command lists all of the
variables that are set in your environment, and
<tt>grep</tt> shows you just the lines
you want (those with ORA in it).
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
oracle:~$ su - oracle
-oracle:~$ env | grep ORA</pre>
-<p>
+oracle:~$ env | grep ORA</pre><p>
If it worked, you should see:
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
ORACLE_SID=ora8
ORACLE_BASE=/ora8/m01/app/oracle
ORACLE_TERM=vt100
ORACLE_HOME=/ora8/m01/app/oracle/product/8.1.7
-ORA_NLS33=/ora8/m01/app/oracle/product/8.1.7/ocommon/nls/admin/data</pre>
-<p>
+ORA_NLS33=/ora8/m01/app/oracle/product/8.1.7/ocommon/nls/admin/data</pre><p>
If not, try adding the files to
<tt>~/.bashrc</tt> instead of
<tt>.bash_profile</tt>. Then logout and
@@ -290,143 +179,88 @@
<tt>.bashrc</tt> and
<tt>.bash_profile</tt> will be
evaluated.
- </p>
-<p>
+ </p><p>
Make sure that <tt>/bin</tt>,
<tt>/usr/bin</tt>, and
<tt>/usr/local/bin</tt> are in your path
by typing:
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
oracle:~$ echo $PATH
-/bin:/usr/bin:/usr/local/bin:/usr/bin/X11:/usr/X11R6/bin:/home/oracle/bin:/ora8/m01/app/oracle/product/8.1.7/bin</pre>
-<p>
+/bin:/usr/bin:/usr/local/bin:/usr/bin/X11:/usr/X11R6/bin:/home/oracle/bin:/ora8/m01/app/oracle/product/8.1.7/bin</pre><p>
If they are not, then add them to the
<tt>.bash_profile</tt> by changing the
PATH statement above to
<tt>PATH=$PATH:/usr/local/bin:$ORACLE_HOME/bin</tt>
- </p>
-</li>
-</ul></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="install-oracle-install"></a>Installing Oracle 8.1.7 Server</h3></div></div>
-<div class="itemizedlist"><ul>
-<li>
-<p>
+ </p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="install-oracle-install"></a>Installing Oracle 8.1.7 Server</h3></div></div><div class="itemizedlist"><ul type="disc"><li><p>
Log in as <tt>oracle</tt> and
start X if not already running. Start a new terminal:
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
joeuser:~$ xhost +localhost
joeuser:~$ su - oracle
Password: **********
-oracle:~$ export DISPLAY=localhost:0.0</pre>
-</li>
-<li>
-<p>
+oracle:~$ export DISPLAY=localhost:0.0</pre></li><li><p>
Find the <tt>runInstaller</tt> script
- </p>
-<div class="itemizedlist"><ul>
-<li>
-<p>
+ </p><div class="itemizedlist"><ul type="round"><li><p>
If you are installing Oracle from a CD-ROM, it is located in
the <tt>install/linux</tt> path from
the cd-rom mount point
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
oracle:~$ su - root
root:~# mount -t iso9660 /dev/cdrom /mnt/cdrom
root:~# exit
-oracle:~$ cd /mnt/cdrom</pre>
-</li>
-<li>
-<p>
+oracle:~$ cd /mnt/cdrom</pre></li><li><p>
If you are installing from the tarball, the install script is
located in the <tt>Oracle8iR2</tt>
directory that was created when you expanded the archive.
- </p>
-<pre class="programlisting">
-oracle:~$ cd /where/oracle/Disk1</pre>
-</li>
-</ul></div>
-<p>
+ </p><pre class="programlisting">
+oracle:~$ cd /where/oracle/Disk1</pre></li></ul></div><p>
Check to make sure the file is there.
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
oracle:/where/oracle/Disk1$ ls
-doc index.htm install runInstaller stage starterdb</pre>
-<p>
+doc index.htm install runInstaller stage starterdb</pre><p>
If you don't see
<tt>runInstaller</tt>, you are in the
wrong directory.
- </p>
-</li>
-<li>
-<p>
+ </p></li><li><p>
Run the installer
- </p>
-<pre class="programlisting">
-oracle:/where/oracle/Disk1$ ./runInstaller</pre>
-<p>
+ </p><pre class="programlisting">
+oracle:/where/oracle/Disk1$ ./runInstaller</pre><p>
A window will open that welcomes you to the 'Oracle Universal
Installer' (OUI). Click on
"<tt>Next</tt>"
- </p>
-</li>
-<li>
-<p>
+ </p></li><li><p>
The "File Locations" screen in the OUI:
- </p>
-<div class="itemizedlist"><ul>
-<li><p>
+ </p><div class="itemizedlist"><ul type="round"><li><p>
"Source" path should have been
prefilled with "(wherever you mounted the
CDROM)<tt>/stage/products.jar</tt>"
- </p></li>
-<li>
-<p>
+ </p></li><li><p>
"destination" path says
"<tt>/ora8/m01/app/oracle/product/8.1.7</tt>"
- </p>
-<p>
+ </p><p>
If the destination is not correct it is because your
environment variables are not set properly. Make sure you
logged on as <tt>oracle</tt> using
<tt>su - oracle</tt>. If so, edit the
<tt>~/.bash_profile</tt> as you
did in <a href="oracle.html#install-oracle-preinstall" title="Pre-Installation Tasks">the section called “Pre-Installation Tasks”</a>
- </p>
-</li>
-<li><p>
+ </p></li><li><p>
Click "Next" (a pop up window will display Loading
Product information).
- </p></li>
-</ul></div>
-</li>
-<li>
-<p>
+ </p></li></ul></div></li><li><p>
The "Unix Group Name" screen in the OUI:
- </p>
-<div class="itemizedlist"><ul>
-<li><p>
+ </p><div class="itemizedlist"><ul type="round"><li><p>
The Unix Group name needs to be set to
'<tt>oinstall</tt>' ( we made
this Unix group earlier ).
- </p></li>
-<li><p>
+ </p></li><li><p>
Click "Next"
- </p></li>
-<li><p>
+ </p></li><li><p>
A popup window appears instantly, requesting you
to run a script as root:
- </p></li>
-<li>
-<p>
+ </p></li><li><p>
Open a new terminal window, then type:
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
joeuser:~$ su -
root:~# cd /ora8/m01/app/oracle/product/8.1.7
root:~# ./orainstRoot.sh
@@ -435,172 +269,93 @@
Changing groupname of /ora8/m01/app/oracle/oraInventory to oinstall.
root:~# mkdir -p /usr/local/java
root:~# exit
-joeuser:~$ exit</pre>
-</li>
-<li><p>
+joeuser:~$ exit</pre></li><li><p>
Click "Retry"
- </p></li>
-</ul></div>
-</li>
-<li>
-<p>
+ </p></li></ul></div></li><li><p>
The "Available Products" screen in the OUI:
- </p>
-<div class="itemizedlist"><ul>
-<li><p>
+ </p><div class="itemizedlist"><ul type="round"><li><p>
Select "Oracle 8i Enterprise Edition 8.1.7.1.0"
- </p></li>
-<li><p>Click "Next"</p></li>
-</ul></div>
-</li>
-<li>
-<p>
+ </p></li><li><p>Click "Next"</p></li></ul></div></li><li><p>
The "Installation Types" screen
- </p>
-<div class="itemizedlist"><ul>
-<li><p>
+ </p><div class="itemizedlist"><ul type="round"><li><p>
Select the "Custom" installation type.
- </p></li>
-<li><p>Click "Next"</p></li>
-</ul></div>
-</li>
-<li>
-<p>
+ </p></li><li><p>Click "Next"</p></li></ul></div></li><li><p>
The "Available Product Components" screen
- </p>
-<div class="itemizedlist"><ul>
-<li><p>
+ </p><div class="itemizedlist"><ul type="round"><li><p>
In addition to the defaults, make sure that "Oracle SQLJ
8.1.7.0," "Oracle Protocol Support 8.1.7.0.0," and
"Linux Documentation 8.1.7.0.0" are also checked.
- </p></li>
-<li><p>
+ </p></li><li><p>
Click "Next"
- </p></li>
-<li><p>
+ </p></li><li><p>
A progress bar will appear for about 1 minute.
- </p></li>
-</ul></div>
-</li>
-<li>
-<p>
+ </p></li></ul></div></li><li><p>
The "Component Locations" screen in the OUI
- </p>
-<div class="itemizedlist"><ul>
-<li><p>
+ </p><div class="itemizedlist"><ul type="round"><li><p>
Click on the "Java Runtime Environment 1.1.8" It
should have the path
"<tt>/ora8/m01/app/oracle/jre/1.1.8</tt>"
- </p></li>
-<li><p>
+ </p></li><li><p>
Click "Next"
- </p></li>
-<li><p>
+ </p></li><li><p>
A progress bar will appear for about 1 minute.
- </p></li>
-</ul></div>
-</li>
-<li>
-<p>
+ </p></li></ul></div></li><li><p>
The "Privileged Operation System Groups" screen in the
OUI
- </p>
-<div class="itemizedlist"><ul>
-<li><p>
+ </p><div class="itemizedlist"><ul type="round"><li><p>
Enter "dba" for "Database Administrator
(OSDBA) Group"
- </p></li>
-<li><p>
+ </p></li><li><p>
Enter "dba" for the "Database Operator
(OSOPER) Group"
- </p></li>
-<li><p>
+ </p></li><li><p>
Click "Next"
- </p></li>
-<li><p>
+ </p></li><li><p>
A progress bar will appear for about 1 minute.
- </p></li>
-</ul></div>
-</li>
-<li>
-<p>
+ </p></li></ul></div></li><li><p>
The "Authentication Methods" screen
- </p>
-<div class="itemizedlist"><ul><li><p>
+ </p><div class="itemizedlist"><ul type="round"><li><p>
Click "Next"
- </p></li></ul></div>
-</li>
-<li>
-<p>
+ </p></li></ul></div></li><li><p>
The next screen is "Choose JDK home directory"
- </p>
-<div class="itemizedlist"><ul>
-<li><p>
+ </p><div class="itemizedlist"><ul type="round"><li><p>
Keep the default path: <tt>/usr/local/java</tt>
- </p></li>
-<li><p>
+ </p></li><li><p>
Click "Next"
- </p></li>
-</ul></div>
-</li>
-<li>
-<p>
+ </p></li></ul></div></li><li><p>
The "Create a Database" screen in the OUI
- </p>
-<div class="itemizedlist"><ul>
-<li><p>
+ </p><div class="itemizedlist"><ul type="round"><li><p>
Select "No" as we will do this later, after some
important configuration changes.
- </p></li>
-<li><p>
+ </p></li><li><p>
Click "Next"
- </p></li>
-</ul></div>
-</li>
-<li>
-<p>
+ </p></li></ul></div></li><li><p>
The next screen is "Oracle Product Support"
- </p>
-<div class="itemizedlist"><ul>
-<li><p>
+ </p><div class="itemizedlist"><ul type="round"><li><p>
TCP should be checked with "Status" listed as
Required
- </p></li>
-<li><p>
+ </p></li><li><p>
Click "Next"
- </p></li>
-</ul></div>
-</li>
-<li>
-<p>
+ </p></li></ul></div></li><li><p>
The "Summary" screen in the OUI
- </p>
-<div class="itemizedlist"><ul>
-<li><p>
+ </p><div class="itemizedlist"><ul type="round"><li><p>
Check the "Space Requirements" section to verify
you have enough disk space for the install.
- </p></li>
-<li><p>
+ </p></li><li><p>
Check that "(144 products)" is in the "New
Installations" section title.
- </p></li>
-<li><p>
+ </p></li><li><p>
Click "Install"
- </p></li>
-<li><p>
+ </p></li><li><p>
A progress bar will appear for about 20 - 30 minutes. Now is a
good time to take a break.
- </p></li>
-<li><p>
+ </p></li><li><p>
A "Setup Privileges" window will popup towards the
end of the installation asking you to run a script as
<tt>root</tt>
- </p></li>
-<li>
-<p>
+ </p></li><li><p>
Run the script.
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
joeuser:~$ su -
Password: *********
root:~# /ora8/m01/app/oracle/product/8.1.7/root.sh
@@ -629,356 +384,219 @@
created by the Oracle Enterprise Manager Intelligent
Agent. These files may be found in the directories
you use for storing other Net8 log and trace files.
- If such files exist, the OEM IA may not restart.</pre>
-</li>
-<li><p>
+ If such files exist, the OEM IA may not restart.</pre></li><li><p>
Do not follow the instructions on deleting trace
and log files, it is not necessary.
- </p></li>
-</ul></div>
-<pre class="programlisting">
+ </p></li></ul></div><pre class="programlisting">
root:~# exit
-joeuser:~$ exit</pre>
-</li>
-<li><p>
+joeuser:~$ exit</pre></li><li><p>
Go back to the pop-up window and click "OK"
- </p></li>
-<li>
-<p>
+ </p></li><li><p>
The "Configuration Tools" screen in the OUI
- </p>
-<div class="itemizedlist"><ul><li><p>
+ </p><div class="itemizedlist"><ul type="round"><li><p>
This window displays the config tools that will automatically
be launched.
- </p></li></ul></div>
-</li>
-<li>
-<p>
+ </p></li></ul></div></li><li><p>
The "Welcome" screen in the "net 8 Configuration
Assistant"
- </p>
-<div class="itemizedlist"><ul>
-<li><p>
+ </p><div class="itemizedlist"><ul type="round"><li><p>
Make sure the "Perform Typical installation" is
- <span class="strong"><i>not</i></span> selected.
- </p></li>
-<li><p>
+ <span class="strong"><em>not</em></span> selected.
+ </p></li><li><p>
Click "Next"
- </p></li>
-<li><p>
+ </p></li><li><p>
The "Directory Service Access" screen in the
"Net 8 Configuration Assistant"
- </p></li>
-<li><p>
+ </p></li><li><p>
Select "No"
- </p></li>
-<li><p>
+ </p></li><li><p>
Click "Next"
- </p></li>
-</ul></div>
-</li>
-<li>
-<p>
+ </p></li></ul></div></li><li><p>
The "Listener Configuration, Listener Name" screen in
the "Net 8 Configuration Assistant"
- </p>
-<div class="itemizedlist"><ul>
-<li><p>
+ </p><div class="itemizedlist"><ul type="round"><li><p>
Accept the default listener name of "LISTENER"
- </p></li>
-<li><p>
+ </p></li><li><p>
Click "Next"
- </p></li>
-</ul></div>
-</li>
-<li>
-<p>
+ </p></li></ul></div></li><li><p>
The "Listener Configuration, Select
Protocols" screen in the "Net 8 Configuration
Assistant"
- </p>
-<div class="itemizedlist"><ul>
-<li><p>
+ </p><div class="itemizedlist"><ul type="round"><li><p>
The only choice in "Select protocols:" should be
"TCP/IP"
- </p></li>
-<li><p>
+ </p></li><li><p>
Click "Next"
- </p></li>
-</ul></div>
-</li>
-<li>
-<p>
+ </p></li></ul></div></li><li><p>
The "Listener Configuration TCP/IP Protocol" screen in
the "Net 8 Configuration Assistant"
- </p>
-<div class="itemizedlist"><ul>
-<li><p>
+ </p><div class="itemizedlist"><ul type="round"><li><p>
Default Port should be 1521 and selected.
- </p></li>
-<li><p>
+ </p></li><li><p>
Click "Next"
- </p></li>
-</ul></div>
-</li>
-<li>
-<p>
+ </p></li></ul></div></li><li><p>
The "Listener Configuration, More Listeners" screen in
the "Net 8 Configuration Assistant"
- </p>
-<div class="itemizedlist"><ul>
-<li><p>
+ </p><div class="itemizedlist"><ul type="round"><li><p>
Select "No"
- </p></li>
-<li><p>
+ </p></li><li><p>
Click "Next"
- </p></li>
-</ul></div>
-</li>
-<li>
-<p>
+ </p></li></ul></div></li><li><p>
The "Listener Configuration Done" screen in the
"Net 8 Configuration Assistant"
- </p>
-<div class="itemizedlist"><ul><li><p>
+ </p><div class="itemizedlist"><ul type="round"><li><p>
Click "Next"
- </p></li></ul></div>
-</li>
-<li>
-<p>
+ </p></li></ul></div></li><li><p>
The "Naming Methods Configuration" screen
in the "Net 8 Configuration Assistant"
- </p>
-<div class="itemizedlist"><ul>
-<li><p>
+ </p><div class="itemizedlist"><ul type="round"><li><p>
Select "No"
- </p></li>
-<li><p>
+ </p></li><li><p>
Click "Next"
- </p></li>
-</ul></div>
-</li>
-<li>
-<p>
+ </p></li></ul></div></li><li><p>
The "Done" screen in the "Net 8 Configuration
Assistant"
- </p>
-<div class="itemizedlist"><ul><li><p>
+ </p><div class="itemizedlist"><ul type="round"><li><p>
Click "Finish"
- </p></li></ul></div>
-</li>
-<li>
-<p>
+ </p></li></ul></div></li><li><p>
The "End of Installation" screen in the OUI
- </p>
-<div class="itemizedlist"><ul>
-<li><p>
+ </p><div class="itemizedlist"><ul type="round"><li><p>
Click "Exit"
- </p></li>
-<li><p>
+ </p></li><li><p>
Click "Yes" on the confirmation pop up window.
- </p></li>
-<li><p>
+ </p></li><li><p>
The Oracle Universal Installer window should have disappeared!
- </p></li>
-</ul></div>
-</li>
-</ul></div>
-<p>
+ </p></li></ul></div></li></ul></div><p>
Congratulations, you have just installed Oracle 8.1.7 Server!
However, you still need to create a database which can take about an
hour of non-interactive time, so don't quit yet.
- </p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="install-oracle-create"></a>Creating the First Database</h3></div></div>
-<p>
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="install-oracle-create"></a>Creating the First Database</h3></div></div><p>
This step will take you through the steps of creating a customized
database. Be warned that this process takes about an hour on a
Pentium II with 128 MB of RAM.
- </p>
-<div class="itemizedlist"><ul>
-<li>
-<p>
+ </p><div class="itemizedlist"><ul type="disc"><li><p>
Make sure you are running X. Open up a terminal and
<tt>su</tt> to oracle and then run the
<tt>dbassist</tt> program.
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
joeuser:~$ xhost +localhost
joeuser:~$ su - oracle
Password: *********
oracle:~$ export DISPLAY=localhost:0.0
-oracle:~$ dbassist</pre>
-</li>
-<li>
-<p>
+oracle:~$ dbassist</pre></li><li><p>
The "Welcome" screen in the Oracle Database
Configuration Agent (ODCA)
- </p>
-<div class="itemizedlist"><ul>
-<li><p>
+ </p><div class="itemizedlist"><ul type="round"><li><p>
Select "Create a database"
- </p></li>
-<li><p>
+ </p></li><li><p>
Click "Next"
- </p></li>
-</ul></div>
-</li>
-<li>
-<p>
+ </p></li></ul></div></li><li><p>
The "Select database type" screen in the ODCA
- </p>
-<div class="itemizedlist"><ul>
-<li><p>
+ </p><div class="itemizedlist"><ul type="round"><li><p>
Select "Custom"
- </p></li>
-<li><p>
+ </p></li><li><p>
Click "Next"
- </p></li>
-</ul></div>
-</li>
-<li>
-<p>
+ </p></li></ul></div></li><li><p>
The "Primary Database Type" window in ODCA
- </p>
-<div class="itemizedlist"><ul>
-<li><p>
+ </p><div class="itemizedlist"><ul type="round"><li><p>
Select "Multipurpose"
- </p></li>
-<li><p>
+ </p></li><li><p>
Click "Next"
- </p></li>
-</ul></div>
-</li>
-<li>
-<p>
+ </p></li></ul></div></li><li><p>
The "concurrent users" screen of the ODCA
- </p>
-<div class="itemizedlist"><ul>
-<li><p>
+ </p><div class="itemizedlist"><ul type="round"><li><p>
Select "60" concurrent users.
- </p></li>
-<li><p>
+ </p></li><li><p>
Click "Next"
- </p></li>
-</ul></div>
-</li>
-<li><p>
+ </p></li></ul></div></li><li><p>
Select "<tt>Dedicated Server
Mode</tt>", click
"<tt>Next</tt>"
- </p></li>
-<li><p>
+ </p></li><li><p>
Accept all of the options, and click
"<tt>Next</tt>" Oracle Visual
Information Retrieval may be grayed out. If so, you can ignore
it; just make sure that everything else is checked.
- </p></li>
-<li><p>
+ </p></li><li><p>
For "Global Database Name", enter
"<tt>ora8</tt>"; for
"SID", also enter
"<tt>ora8</tt>" (it should do
this automatically). Click
"<tt>Next</tt>".
- </p></li>
-<li><p>
+ </p></li><li><p>
Accept the defaults for the next screen (control file
location). Click
"<tt>Next</tt>"
- </p></li>
-<li><p>
+ </p></li><li><p>
Go to the "temporary" and
"rollback" tabs, and change the Size
(upper-right text box) to
<tt>150</tt>MB. Click
"<tt>Next</tt>"
- </p></li>
-<li><p>
+ </p></li><li><p>
Increase the redo log sizes to
<tt>10000K</tt> each. Click
"<tt>Next</tt>"
- </p></li>
-<li><p>
+ </p></li><li><p>
Use the default checkpoint interval & timeout. Click
"<tt>Next</tt>"
- </p></li>
-<li><p>
+ </p></li><li><p>
Increase "<tt>Processes</tt>"
to <tt>100</tt>;
"<tt>Block Size</tt>" to
<tt>4096</tt> (better for small Linux
boxes; use 8192 for a big Solaris machine).
- </p></li>
-<li><p>
+ </p></li><li><p>
Accept the defaults for the Trace File Directory. Click
"<tt>Next</tt>"
- </p></li>
-<li><p>
+ </p></li><li><p>
Finally, select "<tt>Save information to a shell
script</tt>" and click
"<tt>Finish</tt>" (We're
going to examine the contents of this file before creating our
database.)
- </p></li>
-<li><p>
+ </p></li><li><p>
Click the "<tt>Save</tt>"
button. Oracle will automatically save it to the correct
directory and with the correct file name. This will likely be
<tt>/ora8/m01/app/oracle/product/8.1.7/assistants/dbca/jlib/sqlora8.sh</tt>
- </p></li>
-<li><p>
+ </p></li><li><p>
It will alert you that the script has been saved
successfully.
- </p></li>
-<li>
-<p>
+ </p></li><li><p>
Now we need to customize the database configuration a bit. While
still logged on as <tt>oracle</tt>, edit
the database initialization script (run when the db loads). The
scripts are kept in
<tt>$ORACLE_HOME/dbs</tt> and the name of
the script is usually
- <tt>init</tt><span class="emphasis"><i>SID</i></span><tt>.ora</tt>
- where <span class="emphasis"><i>SID</i></span> is the SID of your
+ <tt>init</tt><span class="emphasis"><em>SID</em></span><tt>.ora</tt>
+ where <span class="emphasis"><em>SID</em></span> is the SID of your
database. Assuming your
<tt>$ORACLE_HOME</tt> matches our default
of
<tt>/ora8/m01/app/oracle/product/8.1.7</tt>,
the following will open the file for editing.
- </p>
-<pre class="programlisting">
-oracle:~$ emacs /ora8/m01/app/oracle/product/8.1.7/dbs/initora8.ora</pre>
-</li>
-<li>
-<p>
+ </p><pre class="programlisting">
+oracle:~$ emacs /ora8/m01/app/oracle/product/8.1.7/dbs/initora8.ora</pre></li><li><p>
Add the following line to the end:
- </p>
-<pre class="programlisting">
-nls_date_format = "YYYY-MM-DD"</pre>
-</li>
-<li>
-<p>
+ </p><pre class="programlisting">
+nls_date_format = "YYYY-MM-DD"</pre></li><li><p>
Now find the <tt>open_cursors</tt> line
in the file. If you're using
<tt>emacs</tt> scroll up to the top of
the buffer and do <tt>CTRL-S</tt> and
type <tt>open_cursors</tt> to find the
line. The default is <tt>100</tt>. Change
it to <tt>500</tt>.
- </p>
-<pre class="programlisting">
-open_cursors = 500</pre>
-</li>
-<li><p>
+ </p><pre class="programlisting">
+open_cursors = 500</pre></li><li><p>
Save the file. In emacs, do <tt>CTRL-X
CTRL-S</tt> to save followed by
<tt>CTRL-X CTRL-C</tt> to exit or use
the menu.
- </p></li>
-<li><p>
+ </p></li><li><p>
At this point, you are ready to initiate database creation. We
recommend shutting down X to free up some RAM unless you have 256
MB of RAM or more. You can do this quickly by doing a
@@ -988,103 +606,64 @@
login screen instead, switch to a virtual console by doing
<tt>CRTL-ALT-F1</tt>. Then login as
<tt>oracle</tt>.
- </p></li>
-<li>
-<p>
+ </p></li><li><p>
Change to the directory where the database creation script is and
run it:
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
oracle:~$ cd /ora8/m01/app/oracle/product/8.1.7/assistants/dbca/jlib
-oracle:/ora8/m01/app/oracle/product/8.1.7/assistants/dbca/jlib$ ./sqlora8.sh</pre>
-<p>
+oracle:/ora8/m01/app/oracle/product/8.1.7/assistants/dbca/jlib$ ./sqlora8.sh</pre><p>
In some instances, Oracle will save the file to
<tt>/ora8/m01/app/oracle/product/8.1.7/assistants/dbca</tt>
Try running the script there if your first attempt does not
succeed.
- </p>
-</li>
-<li>
-<p>
+ </p></li><li><p>
Your database will now be built. It will take > 1 hour - no
fooling. You will see lots of errors scroll by (like:
"ORA-01432: public synonym to be dropped does not
exist") Fear not, this is normal.
- </p>
-<p>
+ </p><p>
Eventually, you'll be returned to your shell prompt. In the
meantime, relax, you've earned it.
- </p>
-</li>
-</ul></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="istall-oracle-test"></a>Acceptance Test</h3></div></div>
-<p>
+ </p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="istall-oracle-test"></a>Acceptance Test</h3></div></div><p>
For this step, open up a terminal and
<tt>su</tt> to
<tt>oracle</tt> as usual. You should be
running X and Netscape (or other web browser) for this phase.
- </p>
-<div class="itemizedlist"><ul>
-<li><p>
+ </p><div class="itemizedlist"><ul type="disc"><li><p>
You need to download the "Oracle Acceptance Test" file.
It's available <a href="files/acceptance-sql.txt" target="_top">here</a> and at <a href="http://philip.greenspun.com/wtr/oracle/acceptance-sql.txt" target="_top">http://philip.greenspun.com/wtr/oracle/acceptance-sql.txt</a>.
Save the file to <tt>/tmp</tt>
- </p></li>
-<li>
-<p>
+ </p></li><li><p>
In the oracle shell, copy the file.
- </p>
-<pre class="programlisting">
-oracle:~$ cp /tmp/acceptance-sql.txt /tmp/acceptance.sql</pre>
-</li>
-<li>
-<p>
+ </p><pre class="programlisting">
+oracle:~$ cp /tmp/acceptance-sql.txt /tmp/acceptance.sql</pre></li><li><p>
Once you've got the acceptance test file all set, stay in
your term and type the following:
- </p>
-<pre class="programlisting">
-oracle:~$ sqlplus system/manager</pre>
-<p>
+ </p><pre class="programlisting">
+oracle:~$ sqlplus system/manager</pre><p>
SQL*Plus should startup. If you get an <tt>ORA-01034:
Oracle not Available</tt> error, it is because your
Oracle instance is not running. You can manually start it as
- the <tt>oracle</tt> user.</p>
-<pre class="programlisting">
+ the <tt>oracle</tt> user.</p><pre class="programlisting">
oracle:~$ svrmgrl
SVRMGR> connect internal
-SVRMGR> startup</pre>
-</li>
-<li>
-<p>
+SVRMGR> startup</pre></li><li><p>
Now that you're into SQL*Plus, change the default passwords
for system, sys, and ctxsys to "alexisahunk" (or to
something you'll remember):
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
SQL> alter user system identified by alexisahunk;
SQL> alter user sys identified by alexisahunk;
-SQL> alter user ctxsys identified by alexisahunk;</pre>
-</li>
-<li>
-<p>
+SQL> alter user ctxsys identified by alexisahunk;</pre></li><li><p>
Verify that your date settings are correct.
- </p>
-<pre class="programlisting">
-SQL> select sysdate from dual;</pre>
-<p>
+ </p><pre class="programlisting">
+SQL> select sysdate from dual;</pre><p>
If you don't see a date that fits the format
<tt>YYYY-MM-DD</tt>, please read <a href="oracle.html#install-oracle-troubleshooting" title="Troubleshooting Oracle Dates">the section called “Troubleshooting Oracle Dates”</a>.
- </p>
-</li>
-<li>
-<p>
+ </p></li><li><p>
At this point we are going to hammer your database with an
intense acceptance test. This usually takes around 30 minutes.
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
SQL> @ /tmp/acceptance.sql
; A bunch of lines will scroll by. You'll know if the test worked if
@@ -1094,15 +673,12 @@
----------
2000-06-10
-SQL></pre>
-<p>
+SQL></pre><p>
Many people encounter an error regarding <tt>maximum
key length</tt>:
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
ERROR at line 1:
-ORA-01450: maximum key length (758) exceeded</pre>
-<p>
+ORA-01450: maximum key length (758) exceeded</pre><p>
This error occurs if your database block size is wrong and is
usually suffered by people trying to load OpenACS into a
pre-existing database. Unfortunately, the only solution is to
@@ -1113,25 +689,14 @@
<tt>dbassist</tt> program or by setting
the <tt>DB_BLOCK_SIZE</tt> parameter in
your database's creation script.
- </p>
-<p>
+ </p><p>
If there were no errors, then consider yourself fortunate. Your
Oracle installation is working.
- </p>
-</li>
-</ul></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="install-oracle-automating"></a>Automating Startup & Shutdown</h3></div></div>
-<p>
+ </p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="install-oracle-automating"></a>Automating Startup & Shutdown</h3></div></div><p>
You will want to automate the database startup and shutdown process.
It's probably best to have Oracle spring to life when you boot up
your machine.
- </p>
-<div class="itemizedlist"><ul>
-<li>
-<p>
+ </p><div class="itemizedlist"><ul type="disc"><li><p>
Oracle includes a script called
<tt>dbstart</tt> that can be used to
automatically start the database. Unfortunately, the script
@@ -1140,71 +705,46 @@
it. First, save <a href="files/dbstart.txt" target="_top">dbstart</a> to
<tt>/tmp</tt>. Then, as
<tt>oracle</tt>, do the following:
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
oracle:~$ cp /tmp/dbstart.txt /ora8/m01/app/oracle/product/8.1.7/bin/dbstart
-oracle:~$ chmod 755 /ora8/m01/app/oracle/product/8.1.7/bin/dbstart</pre>
-</li>
-<li>
-<p>
+oracle:~$ chmod 755 /ora8/m01/app/oracle/product/8.1.7/bin/dbstart</pre></li><li><p>
While you're logged in as
<tt>oracle</tt>, you should configure the
<tt>oratab</tt> file to load your
database at start. Edit the file
<tt>/etc/oratab</tt>:
- </p>
-<div class="itemizedlist"><ul>
-<li>
-<p>You will see this line. </p>
-<pre class="programlisting">
-ora8:/ora8/m01/app/oracle/product/8.1.7:N</pre>
-<p>
+ </p><div class="itemizedlist"><ul type="round"><li><p>You will see this line. </p><pre class="programlisting">
+ora8:/ora8/m01/app/oracle/product/8.1.7:N</pre><p>
By the way, if you changed the service name or have multiple
databases, the format of this file is:
- </p>
-<p>
- <span class="emphasis"><i><tt>service_name:$ORACLE_HOME:Y || N
- (for autoload)</tt></i></span>
- </p>
-</li>
-<li>
-<p>
+ </p><p>
+ <span class="emphasis"><em><tt>service_name:$ORACLE_HOME:Y || N
+ (for autoload)</tt></em></span>
+ </p></li><li><p>
Change the last letter from "N" to
"Y". This tells Oracle that you want the database
to start when the machine boots. It should look like this.
- </p>
-<pre class="programlisting">
-ora8:/ora8/m01/app/oracle/product/8.1.7:Y</pre>
-</li>
-<li><p>
+ </p><pre class="programlisting">
+ora8:/ora8/m01/app/oracle/product/8.1.7:Y</pre></li><li><p>
Save the file & quit the terminal.
- </p></li>
-</ul></div>
-</li>
-<li>
-<p>
+ </p></li></ul></div></li><li><p>
You need a script to automate startup and shutdown. Save <a href="files/oracle8i.txt" target="_top">oracle8i.txt</a> in
<tt>/tmp</tt>. Then login as
<tt>root</tt> and install the
script. (Debian users: substitute
<tt>/etc/init.d</tt> for
<tt>/etc/rc.d/init.d</tt> throughout
this section)
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
oracle:~$ su -
root:~# cp /tmp/oracle8i.txt /etc/rc.d/init.d/oracle8i
root:~# chown root.root /etc/rc.d/init.d/oracle8i
-root:~# chmod 700 /etc/rc.d/init.d/oracle8i</pre>
-</li>
-<li>
-<p>
+root:~# chmod 700 /etc/rc.d/init.d/oracle8i</pre></li><li><p>
Test the script by typing the following commands and checking the
output. (Debian Users: as root, do <tt>mkdir
/var/lock/subsys</tt> first)
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
root:~# /etc/rc.d/init.d/oracle8i stop
Oracle 8i auto start/stop
Shutting Oracle8i:
@@ -1247,26 +787,15 @@
Database "ora8" warm started.
-Database "ora8" warm started.</pre>
-</li>
-<li>
-<p>
+Database "ora8" warm started.</pre></li><li><p>
If it worked, then run these commands to make the startup and
shutdown automatic.
- </p>
-<div class="itemizedlist"><ul>
-<li>
-<p>Red Hat users:</p>
-<pre class="programlisting">
+ </p><div class="itemizedlist"><ul type="round"><li><p>Red Hat users:</p><pre class="programlisting">
root:~# cd /etc/rc.d/init.d/
root:~# chkconfig --add oracle8i
root:~# chkconfig --list oracle8i
; You should see:
-oracle8i 0:off 1:off 2:off 3:on 4:on 5:on 6:off</pre>
-</li>
-<li>
-<p>Debian users:</p>
-<pre class="programlisting">
+oracle8i 0:off 1:off 2:off 3:on 4:on 5:on 6:off</pre></li><li><p>Debian users:</p><pre class="programlisting">
root:~# update-rc.d oracle8i defaults
Adding system startup for /etc/init.d/oracle8i ...
/etc/rc0.d/K20oracle8i -> ../init.d/oracle8i
@@ -1275,11 +804,7 @@
/etc/rc2.d/S20oracle8i -> ../init.d/oracle8i
/etc/rc3.d/S20oracle8i -> ../init.d/oracle8i
/etc/rc4.d/S20oracle8i -> ../init.d/oracle8i
- /etc/rc5.d/S20oracle8i -> ../init.d/oracle8i</pre>
-</li>
-<li>
-<p>SuSE users:</p>
-<pre class="programlisting">
+ /etc/rc5.d/S20oracle8i -> ../init.d/oracle8i</pre></li><li><p>SuSE users:</p><pre class="programlisting">
root:~# cd /etc/rc.d/init.d
root:/etc/rc.d/init.d# ln -s /etc/rc.d/init.d/oracle8i K20oracle8i
root:/etc/rc.d/init.d# ln -s /etc/rc.d/init.d/oracle8i S20oracle8i
@@ -1319,38 +844,25 @@
Executing /sbin/conf.d/SuSEconfig.tetex...
Executing /sbin/conf.d/SuSEconfig.ypclient...
Processing index files of all manpages...
-Finished.</pre>
-</li>
-</ul></div>
-</li>
-<li>
-<p>
+Finished.</pre></li></ul></div></li><li><p>
You also need some scripts to automate startup and shutdown of
the Oracle8i listener. The listener is a name server that allows
your Oracle programs to talk to local and remote databases using
a standard naming convention. It is required for Intermedia Text
and full site search.
- </p>
-<p>
+ </p><p>
Download these three scripts into
<tt>/tmp</tt>
- </p>
-<div class="itemizedlist"><ul>
-<li><p>
+ </p><div class="itemizedlist"><ul type="round"><li><p>
<a href="files/startlsnr.txt" target="_top">startlsnr.txt</a>
- </p></li>
-<li><p>
+ </p></li><li><p>
<a href="files/stoplsnr.txt" target="_top">stoplsnr.txt</a>
- </p></li>
-<li><p>
+ </p></li><li><p>
<a href="files/listener8i.txt" target="_top">listener8i.txt</a>
- </p></li>
-</ul></div>
-<p>
+ </p></li></ul></div><p>
Now issue the following commands (still as
<tt>root</tt>).
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
root:~# su - oracle
oracle:~$ cp /tmp/startlsnr.txt /ora8/m01/app/oracle/product/8.1.7/bin/startlsnr
oracle:~$ cp /tmp/stoplsnr.txt /ora8/m01/app/oracle/product/8.1.7/bin/stoplsnr
@@ -1359,12 +871,10 @@
oracle:~$ exit
root:~# cp /tmp/listener8i.txt /etc/rc.d/init.d/listener8i
root:~# cd /etc/rc.d/init.d
-root:/etc/rc.d/init.d# chmod 700 listener8i</pre>
-<p>
+root:/etc/rc.d/init.d# chmod 700 listener8i</pre><p>
Test the listener automation by running the following commands
and checking the output.
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
root:/etc/rc.d/init.d# ./listener8i stop
Oracle 8i listener start/stop
Shutting down Listener for 8i:
@@ -1406,17 +916,14 @@
Services Summary...
PLSExtProc has 1 service handler(s)
ora8 has 1 service handler(s)
-The command completed successfully</pre>
-<p>
+The command completed successfully</pre><p>
This test will verify that the listener is operating
normally. Login into the database using the listener naming
convention.
- </p>
-<p>
+ </p><p>
<tt>sqlplus</tt>
- <span class="emphasis"><i><tt>username/password/@SID</tt></i></span>
- </p>
-<pre class="programlisting">
+ <span class="emphasis"><em><tt>username/password/@SID</tt></em></span>
+ </p><pre class="programlisting">
root:~# su - oracle
oracle:~$ sqlplus system/alexisahunk@ora8
@@ -1428,27 +935,17 @@
SQL> exit
oracle:~$ exit
-root:~#</pre>
-<div class="itemizedlist"><ul>
-<li>
-<p>RedHat users:</p>
-<p>
+root:~#</pre><div class="itemizedlist"><ul type="round"><li><p>RedHat users:</p><p>
Now run <tt>chkconfig</tt> on the
<tt>listener8i</tt> script.
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
root:~# cd /etc/rc.d/init.d/
root:/etc/rc.d/init.d# chkconfig --add listener8i
root:/etc/rc.d/init.d# chkconfig --list listener8i
-listener8i 0:off 1:off 2:off 3:on 4:on 5:on 6:off</pre>
-</li>
-<li>
-<p>Debian users:</p>
-<p>
+listener8i 0:off 1:off 2:off 3:on 4:on 5:on 6:off</pre></li><li><p>Debian users:</p><p>
Now run <tt>update-rc.d</tt> on the
<tt>listener8i</tt> script.
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
root:~# update-rc.d listener8i defaults 21 19
Adding system startup for /etc/init.d/listener8i ...
/etc/rc0.d/K19listener8i -> ../init.d/listener8i
@@ -1457,213 +954,91 @@
/etc/rc2.d/S21listener8i -> ../init.d/listener8i
/etc/rc3.d/S21listener8i -> ../init.d/listener8i
/etc/rc4.d/S21listener8i -> ../init.d/listener8i
- /etc/rc5.d/S21listener8i -> ../init.d/listener8i</pre>
-</li>
-</ul></div>
-</li>
-<li>
-<p>
+ /etc/rc5.d/S21listener8i -> ../init.d/listener8i</pre></li></ul></div></li><li><p>
Test the automation
- </p>
-<p>
+ </p><p>
As a final test, reboot your computer and make sure Oracle comes
up. You can do this by typing
- </p>
-<pre class="programlisting">
-root:~# /sbin/shutdown -r -t 0 now</pre>
-<p>
+ </p><pre class="programlisting">
+root:~# /sbin/shutdown -r -t 0 now</pre><p>
Log back in and ensure that Oracle started automatically.
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
joeuser:~$ su - oracle
oracle:~$ sqlplus system/alexisahunk@ora8
-SQL> exit</pre>
-</li>
-</ul></div>
-<p>
+SQL> exit</pre></li></ul></div><p>
Congratulations, your installation of Oracle 8.1.7 is
complete.
- </p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="install-oracle-troubleshooting"></a>Troubleshooting Oracle Dates</h3></div></div>
-<p>
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="install-oracle-troubleshooting"></a>Troubleshooting Oracle Dates</h3></div></div><p>
Oracle has an internal representation for storing the data based on
the number of seconds elapsed since some date. However, for the
purposes of inputing dates into Oracle and getting them back out,
Oracle needs to be told to use a specific date format. By default, it
uses an Oracle-specific format which isn't copacetic. You want
Oracle to use the ANSI-compliant date format which is of form
<tt>'YYYY-MM-DD'</tt>.
- </p>
-<p>
+ </p><p>
To fix this, you should include the following line in
- <tt>$ORACLE_HOME/dbs/init</tt><span class="emphasis"><i>SID</i></span><tt>.ora</tt>
+ <tt>$ORACLE_HOME/dbs/init</tt><span class="emphasis"><em>SID</em></span><tt>.ora</tt>
or for the default case,
<tt>$ORACLE_HOME/dbs/initora8.ora</tt>
- </p>
-<pre class="programlisting">
-nls_date_format = "YYYY-MM-DD"</pre>
-<p>
+ </p><pre class="programlisting">
+nls_date_format = "YYYY-MM-DD"</pre><p>
You test whether this solved the problem by firing up
<tt>sqlplus</tt> and typing:
- </p>
-<pre class="programlisting">
-SQL> select sysdate from dual;</pre>
-<p>
+ </p><pre class="programlisting">
+SQL> select sysdate from dual;</pre><p>
You should see back a date like
<tt>2000-06-02</tt>. If some of the date is
chopped off, i.e. like <tt>2000-06-0</tt>,
everything is still fine. The problem here is that
<tt>sqlplus</tt> is simply truncating the
output. You can fix this by typing:
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
SQL> column sysdate format a15
-SQL> select sysdate from dual;</pre>
-<p>
+SQL> select sysdate from dual;</pre><p>
If the date does not conform to this format, double-check that you
included the necessary line in the init scripts. If it still
isn't working, make sure that you have restarted the database
since adding the line if you didn't do it prior to database
creation.
- </p>
-<p>
+ </p><p>
If you're sure that you have restarted the database since adding
the line, check your initialization scripts. Make sure that the
following line is not included:
- </p>
-<pre class="programlisting">
-export nls_lang = american</pre>
-<p>
+ </p><pre class="programlisting">
+export nls_lang = american</pre><p>
Setting this environment variable will override the date
setting. Either delete this line and login again or add the following
- entry to your login scripts <span class="emphasis"><i>after</i></span> the
+ entry to your login scripts <span class="emphasis"><em>after</em></span> the
<tt>nls_lang</tt> line:
- </p>
-<pre class="programlisting">
-export nls_date_format = 'YYYY-MM-DD'</pre>
-<p>
+ </p><pre class="programlisting">
+export nls_date_format = 'YYYY-MM-DD'</pre><p>
Log back in again. If adding the
<tt>nls_date_format</tt> line doesn't
help, you can ask for advice in our <a href="http://www.openacs.org/bboard/" target="_top">OpenACS forum</a>.
- </p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="install-oracle-procs"></a>Useful Procedures</h3></div></div>
-<div class="itemizedlist"><ul><li>
-<p>
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="install-oracle-procs"></a>Useful Procedures</h3></div></div><div class="itemizedlist"><ul type="disc"><li><p>
Dropping a tablespace
- </p>
-<div class="itemizedlist"><ul>
-<li>
-<p>
+ </p><div class="itemizedlist"><ul type="round"><li><p>
Run sqlplus as the dba:
- </p>
-<pre class="programlisting">
-oracle:~$ sqlplus system/changeme</pre>
-</li>
-<li>
-<p>
+ </p><pre class="programlisting">
+oracle:~$ sqlplus system/changeme</pre></li><li><p>
To drop a user and all of the tables and data owned by that
user:
- </p>
-<pre class="programlisting">
-SQL> drop user <span class="emphasis"><i>oracle_user_name</i></span> cascade;</pre>
-</li>
-<li>
-<p>
+ </p><pre class="programlisting">
+SQL> drop user <span class="emphasis"><em>oracle_user_name</em></span> cascade;</pre></li><li><p>
To drop the tablespace: This will delete everything in the
tablespace overriding any referential integrity
constraints. Run this command only if you want to clean out
your database entirely.
- </p>
-<pre class="programlisting">
-SQL> drop tablespace <span class="emphasis"><i>table_space_name</i></span> including contents cascade constraints;</pre>
-</li>
-</ul></div>
-</li></ul></div>
-<p>
+ </p><pre class="programlisting">
+SQL> drop tablespace <span class="emphasis"><em>table_space_name</em></span> including contents cascade constraints;</pre></li></ul></div></li></ul></div><p>
For more information on Oracle, please consult the <a href="http://oradoc.photo.net/" target="_top">documentation</a>.
- </p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="install-oracle-defaults"></a>Defaults</h3></div></div>
-<p>We used the following defaults while installing Oracle.</p>
-<div class="informaltable"><table border="1">
-<colgroup>
-<col>
-<col>
-<col>
-</colgroup>
-<thead><tr>
-<th>Variable</th>
-<th>Value</th>
-<th>Reason</th>
-</tr></thead>
-<tbody>
-<tr>
-<td>ORACLE_HOME</td>
-<td>/ora8/m01/app/oracle/product/8.1.7</td>
-<td>This is the default Oracle installation directory.</td>
-</tr>
-<tr>
-<td>ORACLE_SERVICE</td>
-<td>ora8</td>
-<td>The service name is a domain-qualified identifier for
- your Oracle server.</td>
-</tr>
-<tr>
-<td>ORACLE_SID</td>
-<td>ora8</td>
-<td>This is an identifier for your Oracle server.</td>
-</tr>
-<tr>
-<td>ORACLE_OWNER</td>
-<td>oracle</td>
-<td>The user who owns all of the oracle files.</td>
-</tr>
-<tr>
-<td>ORACLE_GROUP</td>
-<td>dba</td>
-<td>The special oracle group. Users in the dba group are
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="install-oracle-defaults"></a>Defaults</h3></div></div><p>We used the following defaults while installing Oracle.</p><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Variable</th><th>Value</th><th>Reason</th></tr></thead><tbody><tr><td>ORACLE_HOME</td><td>/ora8/m01/app/oracle/product/8.1.7</td><td>This is the default Oracle installation directory.</td></tr><tr><td>ORACLE_SERVICE</td><td>ora8</td><td>The service name is a domain-qualified identifier for
+ your Oracle server.</td></tr><tr><td>ORACLE_SID</td><td>ora8</td><td>This is an identifier for your Oracle server.</td></tr><tr><td>ORACLE_OWNER</td><td>oracle</td><td>The user who owns all of the oracle files.</td></tr><tr><td>ORACLE_GROUP</td><td>dba</td><td>The special oracle group. Users in the dba group are
authorized to do a <tt>connect
internal</tt> within
<tt>svrmgrl</tt> to gain full system
- access to the Oracle system.</td>
-</tr>
-</tbody>
-</table></div>
-</div>
-<p><div class="cvstag">($Id$)</div></p>
-</div>
-<div class="navfooter">
-<hr>
-<table width="100%" summary="Navigation footer">
-<tr>
-<td width="40%" align="left">
-<a accesskey="p" href="operating-system.html">Prev</a> </td>
-<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
-<td width="40%" align="right"> <a accesskey="n" href="postgres.html">Next</a>
-</td>
-</tr>
-<tr>
-<td width="40%" align="left">Install an Operating System </td>
-<td width="20%" align="center"><a accesskey="u" href="unix-install.html">Up</a></td>
-<td width="40%" align="right"> Install PostgreSQL 7.1.3</td>
-</tr>
-</table>
-<hr>
-<address>
- rmello at fslc.usu.edu
- </address>
-<address><a href="mailto:vinod@kurup.com">
+ access to the Oracle system.</td></tr></tbody></table></div></div><p><div class="cvstag">($Id$)</div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="operating-system.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="postgres.html">Next</a></td></tr><tr><td width="40%" align="left">Install an Operating System </td><td width="20%" align="center"><a accesskey="u" href="unix-install.html">Up</a></td><td width="40%" align="right"> Install PostgreSQL 7.1.3</td></tr></table><hr><address>rmello at fslc.usu.edu</address><address><a href="mailto:vinod@kurup.com">
vinod@kurup.com
- </a></address>
-</div>
-</body>
-</html>
+ </a></address></div></body></html>
Index: openacs-4/packages/acs-core-docs/www/other-developer-overview.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/Attic/other-developer-overview.html,v
diff -u -r1.2 -r1.2.2.1
--- openacs-4/packages/acs-core-docs/www/other-developer-overview.html 7 Mar 2002 06:55:36 -0000 1.2
+++ openacs-4/packages/acs-core-docs/www/other-developer-overview.html 15 May 2002 23:26:18 -0000 1.2.2.1
@@ -1,54 +1,4 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type">
-<title>Overview</title>
-<meta name="generator" content="DocBook XSL Stylesheets V1.45">
-<link rel="home" href="index.html" title="OpenACS Documentation">
-<link rel="up" href="more-developer-info.html" title="Chapter 5. Other Developer Resources">
-<link rel="previous" href="more-developer-info.html" title="Chapter 5. Other Developer Resources">
-<link rel="next" href="parties.html" title="Parties in OpenACS 4.5">
-<link rel="stylesheet" href="openacs.css" type="text/css">
-</head>
-<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-<div class="navheader">
-<a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr>
-<td width="20%" align="left">
-<a accesskey="p" href="more-developer-info.html">Prev</a> </td>
-<th width="60%" align="center">Chapter 5. Other Developer Resources</th>
-<td width="20%" align="right"> <a accesskey="n" href="parties.html">Next</a>
-</td>
-</tr></table>
-<hr>
-</div>
-<div class="sect1">
-<div class="titlepage"><div><h2 class="title" style="clear: both">
-<a name="other-developer-overview"></a>Overview</h2></div></div>
-<p>Developer information that doesn't really fit anywhere else.</p>
-</div>
-<div class="navfooter">
-<hr>
-<table width="100%" summary="Navigation footer">
-<tr>
-<td width="40%" align="left">
-<a accesskey="p" href="more-developer-info.html">Prev</a> </td>
-<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
-<td width="40%" align="right"> <a accesskey="n" href="parties.html">Next</a>
-</td>
-</tr>
-<tr>
-<td width="40%" align="left">Chapter 5. Other Developer Resources </td>
-<td width="20%" align="center"><a accesskey="u" href="more-developer-info.html">Up</a></td>
-<td width="40%" align="right"> Parties in OpenACS 4.5</td>
-</tr>
-</table>
-<hr>
-<address>
- rmello at fslc.usu.edu
- </address>
-<address><a href="mailto:vinod@kurup.com">
+<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"><title>Overview</title><meta name="generator" content="DocBook XSL Stylesheets V1.50.0"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="more-developer-info.html" title="Chapter 5. Other Developer Resources"><link rel="previous" href="more-developer-info.html" title="Chapter 5. Other Developer Resources"><link rel="next" href="parties.html" title="Parties in OpenACS 4.5"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="more-developer-info.html">Prev</a> </td><th width="60%" align="center">Chapter 5. Other Developer Resources</th><td width="20%" align="right"> <a accesskey="n" href="parties.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="other-developer-overview"></a>Overview</h2></div></div><p>Developer information that doesn't really fit anywhere else.</p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="more-developer-info.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="parties.html">Next</a></td></tr><tr><td width="40%" align="left">Chapter 5. Other Developer Resources </td><td width="20%" align="center"><a accesskey="u" href="more-developer-info.html">Up</a></td><td width="40%" align="right"> Parties in OpenACS 4.5</td></tr></table><hr><address>rmello at fslc.usu.edu</address><address><a href="mailto:vinod@kurup.com">
vinod@kurup.com
- </a></address>
-</div>
-</body>
-</html>
+ </a></address></div></body></html>
Index: openacs-4/packages/acs-core-docs/www/packages.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/packages.html,v
diff -u -r1.7 -r1.7.2.1
--- openacs-4/packages/acs-core-docs/www/packages.html 7 Mar 2002 06:55:36 -0000 1.7
+++ openacs-4/packages/acs-core-docs/www/packages.html 15 May 2002 23:26:18 -0000 1.7.2.1
@@ -1,56 +1,21 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type">
-<title>OpenACS 4.5 Packages</title>
-<meta name="generator" content="DocBook XSL Stylesheets V1.45">
-<link rel="home" href="index.html" title="OpenACS Documentation">
-<link rel="up" href="dev-guide.html" title="Chapter 4. OpenACS Developer's Guide">
-<link rel="previous" href="objects.html" title="OpenACS 4.5 Data Models and the Object System">
-<link rel="next" href="request-processor.html" title="The Request Processor">
-<link rel="stylesheet" href="openacs.css" type="text/css">
-</head>
-<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-<div class="navheader">
-<a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr>
-<td width="20%" align="left">
-<a accesskey="p" href="objects.html">Prev</a> </td>
-<th width="60%" align="center">Chapter 4. OpenACS Developer's Guide</th>
-<td width="20%" align="right"> <a accesskey="n" href="request-processor.html">Next</a>
-</td>
-</tr></table>
-<hr>
-</div>
-<div class="sect1">
-<div class="titlepage"><div><h2 class="title" style="clear: both">
-<a name="packages"></a>OpenACS 4.5 Packages</h2></div></div>
-<p>
+<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"><title>OpenACS 4.5 Packages</title><meta name="generator" content="DocBook XSL Stylesheets V1.50.0"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="dev-guide.html" title="Chapter 4. OpenACS Developer's Guide"><link rel="previous" href="objects.html" title="OpenACS 4.5 Data Models and the Object System"><link rel="next" href="request-processor.html" title="The Request Processor"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="objects.html">Prev</a> </td><th width="60%" align="center">Chapter 4. OpenACS Developer's Guide</th><td width="20%" align="right"> <a accesskey="n" href="request-processor.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="packages"></a>OpenACS 4.5 Packages</h2></div></div><p>
By <a href="mailto:psu@arsdigita.com" target="_top">Pete Su</a> and
<a href="mailto:bquinn@arsdigita.com" target="_top">Bryan Quinn</a>
- </p>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="packages-overview"></a>Overview</h3></div></div>
-<p>
+ </p><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="packages-overview"></a>Overview</h3></div></div><p>
This document is a guide on how to write a software package for
OpenACS. OpenACS packages are installed and maintained
with the OpenACS Package Manager (APM). This document presents reasons
for packaging software, conventions for the file system and naming
that must be followed, and step by step instructions for creating a
new package for the "Notes" example package.
- </p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="packages-why-package"></a>Why package your software?</h3></div></div>
-<p>
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="packages-why-package"></a>Why package your software?</h3></div></div><p>
To answer this question, we should examine how OpenACS servers were
organized in the past. We will assume throughout this document that
the page root for your server is called <tt>ROOT</tt>. In OpenACS
3.2.x and earlier, a typical server might have a file system behind it
that looked something like this:
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
ROOT/
bin/
@@ -82,29 +47,20 @@
... and so on for all modules ...
- </pre>
-<p>
+ </pre><p>
In previous versions of OpenACS, you wrote a new application like this:
- </p>
-<div class="orderedlist"><ol type="1">
-<li><p>Put all Tcl library procedures under
- <tt>server-root/tcl</tt>.</p></li>
-<li><p>Put all User viewable content under
- <tt>server-root/www</tt>.</p></li>
-<li><p>Put all Admin content under <tt>/admin/package-key/</tt>.
- </p></li>
-</ol></div>
-<p>
+ </p><div class="orderedlist"><ol type="1"><li><p>Put all Tcl library procedures under
+ <tt>server-root/tcl</tt>.</p></li><li><p>Put all User viewable content under
+ <tt>server-root/www</tt>.</p></li><li><p>Put all Admin content under <tt>/admin/package-key/</tt>.
+ </p></li></ol></div><p>
This structure is very simple, and worked well in a world where
OpenACS was basically a single monolithic entity. But, this organization
made it difficult to distribute modules as independent packages, because
the pieces of each module are strewn all over the tree in at least 3
or 4 different areas.
- </p>
-<p>
+ </p><p>
Here is how an OpenACS 4.5 server is laid out:
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
ROOT/
bin/
@@ -143,88 +99,62 @@
www/
misc pages
- </pre>
-<p>
+ </pre><p>
Note that a major reorganization has happened here. The diagram only
expands the structure of the <tt>bboard/</tt> package directory,
but all the others are basically the same. Each package encapsulates
all of its data model, library code, logic, adminstration pages and
user pages in a single part of the file tree. this organization has
two major advantages:
- </p>
-<div class="itemizedlist"><ul>
-<li><p>
+ </p><div class="itemizedlist"><ul type="disc"><li><p>
This structure makes it easy for developers to track down
- <span class="emphasis"><i>everything</i></span> that is related to a particular package without
+ <span class="emphasis"><em>everything</em></span> that is related to a particular package without
hunting all over the file system.
- </p></li>
-<li><p>
+ </p></li><li><p>
Encapsulating everything about a package in one place also makes it
much easier to distribute packages indepedently from the OpenACS itself.
- </p></li>
-</ul></div>
-<p>
+ </p></li></ul></div><p>
In order to make this work, we need a system that keeps track of the
packages that have been installed in the server, where those packages
have been installed, and a standard way to map URLs that a client
sends to our server to the right page in the appropriate
package. While we are at it, this tool may as well also automate
package installation, depedency checking, upgrades, and package
removal. In OpenACS 4.5, this tool is called APM.
- </p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="packages-apm"></a>The APM</h3></div></div>
-<p>
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="packages-apm"></a>The APM</h3></div></div><p>
The APM is used to create, maintain, and install packages. It takes
care of copying all of the files and registering the package in the
system. The APM is responsible for:
- </p>
-<div class="orderedlist"><ol type="1">
-<li><p>Package registration</p></li>
-<li><p>Automatic installation of packages: loading data models, code
- libraries, and so on.</p></li>
-<li><p>Checking what packages depend on what other packages.</p></li>
-<li><p>Storing information on the package including ownership and a file
- list.</p></li>
-</ol></div>
-<p>
+ </p><div class="orderedlist"><ol type="1"><li><p>Package registration</p></li><li><p>Automatic installation of packages: loading data models, code
+ libraries, and so on.</p></li><li><p>Checking what packages depend on what other packages.</p></li><li><p>Storing information on the package including ownership and a file
+ list.</p></li></ol></div><p>
In addition for packages that are applications, the APM is responsible
for keeping track of where in the site a user must go in order to use
the application. To do this, the APM defines a set of objects that we
- call <span class="emphasis"><i>package instances</i></span>. Once a package is loaded, the
+ call <span class="emphasis"><em>package instances</em></span>. Once a package is loaded, the
administrator can create as many instances of the package as she
likes, and map these instances to any URL in the site that she
wants. If packages are analogous to executable programs in an
operating system, then package instances are analgous to multiple
running copies of a single program. Each instance can be independently
administered and each instance maintains its own set of application
parameters and options.
- </p>
-<p>
+ </p><p>
The following sections will show you how to make a package for the
Notes application. In addition, they will discuss some new site
management features in OpenACS 4.5 that take advantage of the APM's package
- instance model. The two most important of these are <span class="emphasis"><i>subsites</i></span>,
- and the <span class="emphasis"><i>site map</i></span> tool, which can be used to map applications to
+ instance model. The two most important of these are <span class="emphasis"><em>subsites</em></span>,
+ and the <span class="emphasis"><em>site map</em></span> tool, which can be used to map applications to
one or more arbitrary URLs in a running site.
- </p>
-<p>
+ </p><p>
We will also discuss how to organize your files and queries so
they work with OpenACS' Query Dispatcher.
- </p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="packages-looks"></a>What a Package Looks Like</h3></div></div>
-<p>
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="packages-looks"></a>What a Package Looks Like</h3></div></div><p>
<a class="indexterm" name="baby"></a>
To illustrate the general structure of a package, let's see what the
package for the "notes" application should look like. This is shown in
the diagram below:
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
ROOT/
+-- packages/ APM Root
@@ -275,321 +205,178 @@
| +-- notes.info Package Specification File
+-- Other package directories.
- </pre>
-<p>
+ </pre><p>
All file locations are relative to the package root, which in this
case is <tt>ROOT/packages/notes</tt>. The following table
describes in detail what each of the files up in the diagram contain.
- </p>
-<div class="informaltable"><table border="1">
-<colgroup>
-<col>
-<col>
-<col>
-</colgroup>
-<thead><tr>
-<th>File Type</th>
-<th>Its Use</th>
-<th>Naming Convention</th>
-</tr></thead>
-<tbody>
-<tr>
-<td>Data Model Creation Script</td>
-<td>
+ </p><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>File Type</th><th>Its Use</th><th>Naming Convention</th></tr></thead><tbody><tr><td>Data Model Creation Script</td><td>
Contains the SQL that creates the necessary data model and
PL/SQL packages (or PL/pgSQL or whatever) to support the
package. The name must match the convention below or the
package will not be installed correctly. Notice that
the script must be under the appropriate directory for
the database you are developing your package for
(hopefully all OpenACS-supported databases :-))
- </td>
-<td><tt>sql/<database>/notes-create.sql</tt></td>
-</tr>
-<tr>
-<td>Data Model Drop Script</td>
-<td>Contains the SQL that removes the data model and PL/SQL
+ </td><td><tt>sql/<database>/notes-create.sql</tt></td></tr><tr><td>Data Model Drop Script</td><td>Contains the SQL that removes the data model and PL/SQL
packages generated by the creation script. The name must
match the convention below or the package will not be
installed correctly.
- </td>
-<td><tt>sql/<database>/notes-drop.sql</tt></td>
-</tr>
-<tr>
-<td>Data Model File</td>
-<td>Any .sql file that does not match the naming convention above
+ </td><td><tt>sql/<database>/notes-drop.sql</tt></td></tr><tr><td>Data Model File</td><td>Any .sql file that does not match the naming convention above
is recognized as a data model file. It is useful to separate
the SQL in the creation and drop scripts into several
files and then have the scripts source the other data model
files. In Oracle this can be done by including
- <span class="emphasis"><i>@@ filename</i></span> in the creation or drop
+ <span class="emphasis"><em>@@ filename</em></span> in the creation or drop
scripts. See the <a href="http://oradoc.photo.net/ora816/sqlplus.816/a75664/ch83.htm#1011677" target="_top">
Oracle SQL*Plus documentation</a> for examples. In
- PostgreSQL the same is acomplished by including <span class="emphasis"><i>\i</i></span>.
- </td>
-<td><tt>sql/<database>/*.sql</tt></td>
-</tr>
-<tr>
-<td>
+ PostgreSQL the same is acomplished by including <span class="emphasis"><em>\i</em></span>.
+ </td><td><tt>sql/<database>/*.sql</tt></td></tr><tr><td>
SQL92 Query Files
- </td>
-<td>
+ </td><td>
Files with queries that are supported by all
databases. These are usually SQL92 queries. Notice that
the .xql filename must match the name of the .tcl file
that uses those queries.
- </td>
-<td><tt>
+ </td><td><tt>
*.xql
- </tt></td>
-</tr>
-<tr>
-<td>
+ </tt></td></tr><tr><td>
Oracle-specific Query Files
- </td>
-<td>
+ </td><td>
Files with queries that are Oracle-specific. Notice that
the .xql filename must match the name of the .tcl file
that uses those queries.
- </td>
-<td><tt>
+ </td><td><tt>
*-oracle.xql
- </tt></td>
-</tr>
-<tr>
-<td>
+ </tt></td></tr><tr><td>
PostgreSQL-specific Query Files
- </td>
-<td>
+ </td><td>
Files with queries that are PostgreSQL-specific. Notice that
the .xql filename must match the name of the .tcl file
that uses those queries.
- </td>
-<td><tt>
+ </td><td><tt>
*-postgresql.xql
- </tt></td>
-</tr>
-<tr>
-<td>Tcl Library Files</td>
-<td>
+ </tt></td></tr><tr><td>Tcl Library Files</td><td>
The Tcl library files include a set of procedures that provide
an application programming interface (API) for the package to
utilize.
- </td>
-<td><tt>tcl/notes-procs.tcl</tt></td>
-</tr>
-<tr>
-<td>Tcl Initialization</td>
-<td>The initialization files are used to run Tcl procedures that
+ </td><td><tt>tcl/notes-procs.tcl</tt></td></tr><tr><td>Tcl Initialization</td><td>The initialization files are used to run Tcl procedures that
should only be sourced once on startup. Examples of
statements to put here are registered filters or procedures.
Tcl initialization files are sourced once on server startup
after all of the Tcl library files are sourced.
- </td>
-<td><tt>tcl/notes-init.tcl</tt></td>
-</tr>
-<tr>
-<td>Administration UI</td>
-<td>The administration UI is used to administer the instances of
+ </td><td><tt>tcl/notes-init.tcl</tt></td></tr><tr><td>Administration UI</td><td>The administration UI is used to administer the instances of
the package. For example, the bboard administration UI is
used to create new forums, moderate postings, and create new
- categories for bboard postings.</td>
-<td><tt>www/admin/*</tt></td>
-</tr>
-<tr>
-<td>Administration UI Index Page</td>
-<td>Every package administration UI must have an index page. In
+ categories for bboard postings.</td><td><tt>www/admin/*</tt></td></tr><tr><td>Administration UI Index Page</td><td>Every package administration UI must have an index page. In
most cases, this is <tt>index.tcl</tt> but it can be
any file with the name <tt>index</tt>, such as
- index.html or index.adp.</td>
-<td><tt>www/admin/index.tcl</tt></td>
-</tr>
-<tr>
-<td>Regression Tests</td>
-<td>Every package should have a set of regression tests that
+ index.html or index.adp.</td><td><tt>www/admin/index.tcl</tt></td></tr><tr><td>Regression Tests</td><td>Every package should have a set of regression tests that
verify that it is in working operation.
These tests should be able to be run at any time after the package has
been installed and report helpful error messages when there is
- a fault in the system.</td>
-<td><tt>www/admin/tests/</tt></td>
-</tr>
-<tr>
-<td>Regression Test Index Page</td>
-<td>The regression test directory must have an index page that
+ a fault in the system.</td><td><tt>www/admin/tests/</tt></td></tr><tr><td>Regression Test Index Page</td><td>The regression test directory must have an index page that
displays all of the tests available and provides information
on how to run them. This file can have any extension, as long
- as its name is <tt>index</tt>.</td>
-<td><tt>/www/admin/tests/index.html</tt></td>
-</tr>
-<tr>
-<td>Documentation</td>
-<td>Every package must include a full set of documentation that
+ as its name is <tt>index</tt>.</td><td><tt>/www/admin/tests/index.html</tt></td></tr><tr><td>Documentation</td><td>Every package must include a full set of documentation that
includes requirements and design documents, and user-level and
- developer-level documentation where appropriate.</td>
-<td><tt>/www/doc/</tt></td>
-</tr>
-<tr>
-<td>Documentation Index Page</td>
-<td>The documentation directory must include a static HTML file with the name
- of <tt>index.html</tt>.</td>
-<td><tt>/www/doc/index.html</tt></td>
-</tr>
-<tr>
-<td>UI Logic Scripts</td>
-<td>Packages provide a UI for users to access the system. The UI
+ developer-level documentation where appropriate.</td><td><tt>/www/doc/</tt></td></tr><tr><td>Documentation Index Page</td><td>The documentation directory must include a static HTML file with the name
+ of <tt>index.html</tt>.</td><td><tt>/www/doc/index.html</tt></td></tr><tr><td>UI Logic Scripts</td><td>Packages provide a UI for users to access the system. The UI
is split into Logic and Templates. The logic scripts
perform database queries and prepare variables for
- presentation by the associated templates.</td>
-<td><tt>/www/*.tcl</tt></td>
-</tr>
-<tr>
-<td>UI Templates</td>
-<td>Templates are used to control the presentation of the UI.
+ presentation by the associated templates.</td><td><tt>/www/*.tcl</tt></td></tr><tr><td>UI Templates</td><td>Templates are used to control the presentation of the UI.
Templates receive a set of data sources from the logic scripts
- and prepare them for display to the browser.</td>
-<td><tt>/www/*.adp</tt></td>
-</tr>
-<tr>
-<td>UI Index Page</td>
-<td>The UI must have an index page composed of a logic script
+ and prepare them for display to the browser.</td><td><tt>/www/*.adp</tt></td></tr><tr><td>UI Index Page</td><td>The UI must have an index page composed of a logic script
called <tt>index.tcl</tt> and a template called
- <tt>index.adp</tt>.</td>
-<td><tt>/www/index.tcl</tt></td>
-</tr>
-<tr>
-<td>Package Specification File</td>
-<td>The package specification file is an XML file generated and
+ <tt>index.adp</tt>.</td><td><tt>/www/index.tcl</tt></td></tr><tr><td>Package Specification File</td><td>The package specification file is an XML file generated and
maintained by the OpenACS Package Manager (APM). It specifies
information about the package including its parameters and its
- files.</td>
-<td><tt>notes.info</tt></td>
-</tr>
-</tbody>
-</table></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="packages-making-a-package"></a>Making a Package</h3></div></div>
-<p>
+ files.</td><td><tt>notes.info</tt></td></tr></tbody></table></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="packages-making-a-package"></a>Making a Package</h3></div></div><p>
Here is how you make a package.
- </p>
-<div class="orderedlist"><ol type="1">
-<li><p>Login as a site-wide administrator on your web service.
- </p></li>
-<li><p>Go to the package manager on your server. The URL is <a href="/acs-admin/apm" target="_top">/acs-admin/apm</a>.
- </p></li>
-<li><p>Click on the link <a href="/acs-admin/apm/package-add" target="_top">/acs-admin/apm/package-add</a>.
- </p></li>
-<li><p>Fill out the form for adding a new package. The form explains what
+ </p><div class="orderedlist"><ol type="1"><li><p>Login as a site-wide administrator on your web service.
+ </p></li><li><p>Go to the package manager on your server. The URL is <a href="/acs-admin/apm" target="_top">/acs-admin/apm</a>.
+ </p></li><li><p>Click on the link <a href="/acs-admin/apm/package-add" target="_top">/acs-admin/apm/package-add</a>.
+ </p></li><li><p>Fill out the form for adding a new package. The form explains what
everything means, but we'll repeat the important bits here for easy
reference:
- <div class="variablelist"><dl>
-<dt><span class="term">Package Key
- </span></dt>
-<dd><p>
+ </p><div class="variablelist"><dl><dt><span class="term">Package Key
+ </span></dt><dd><p>
This is a short text string that should uniquely name your package to
distinguish it from all the others. It is used as a database key to
keep track of the package and as the name of the directory in the file
system where all the files related to your package will live. Example
package keys in the current system include: <tt>bboard</tt>,
<tt>acs-kernel</tt> and so on. For the example application, we
will use the package key <tt>notes</tt>.
- </p></dd>
-<dt><span class="term">Package Name
- </span></dt>
-<dd><p>
+ </p></dd><dt><span class="term">Package Name
+ </span></dt><dd><p>
This is a short human readable name for your package. For our example,
we will use the name "Notes".
- </p></dd>
-<dt><span class="term">Package Plural
- </span></dt>
-<dd><p>
+ </p></dd><dt><span class="term">Package Plural
+ </span></dt><dd><p>
If your package name is a nice singular noun, this should be the
plural form of it. I assume the plural form is used when multiple
instances of the package are used by a single service. We'll talk more
about package instances later. Our example apllication doesn't really
have a good plural name. So just make it also be "Notes".
- </p></dd>
-<dt><span class="term">Package Type
- </span></dt>
-<dd><p>
- Generally we think of packages as either being <span class="emphasis"><i>applications</i></span>,
+ </p></dd><dt><span class="term">Package Type
+ </span></dt><dd><p>
+ Generally we think of packages as either being <span class="emphasis"><em>applications</em></span>,
meaning that the package is meant primarily for use by end-users, or
- <span class="emphasis"><i>services</i></span> meaning that the package is meant to be a reusable
+ <span class="emphasis"><em>services</em></span> meaning that the package is meant to be a reusable
library of code, to be used by other packages. <tt>bboard</tt> is
a good example of an application, while <tt>acs-templating</tt> is
a good example of a service. Our example is an application, so pick
that.
- </p></dd>
-<dt><span class="term">Package URL
- </span></dt>
-<dd><p>
+ </p></dd><dt><span class="term">Package URL
+ </span></dt><dd><p>
The URL from which people will download your package when it is
done. Just use the default for this, you can change it later.
- </p></dd>
-<dt><span class="term">Initial Version
- </span></dt>
-<dd><p>
+ </p></dd><dt><span class="term">Initial Version
+ </span></dt><dd><p>
Just use the default here, which by convention is 0.1d.
- </p></dd>
-<dt><span class="term">Version URL
- </span></dt>
-<dd><p>
+ </p></dd><dt><span class="term">Version URL
+ </span></dt><dd><p>
Just use the default here.
- </p></dd>
-<dt><span class="term">Summary and Description
- </span></dt>
-<dd><p>
+ </p></dd><dt><span class="term">Summary and Description
+ </span></dt><dd><p>
Enter a short summary and longer description of what the Notes
application will do. That is, something like "this application keeps
short textual notes in the database", and so on.
- </p></dd>
-</dl></div>
- </p></li>
-<li><p>Click the button "Create Package".
- </p></li>
-<li><p>At this point, APM will create a directory called
+ </p></dd></dl></div><p>
+ </p></li><li><p>Click the button "Create Package".
+ </p></li><li><p>At this point, APM will create a directory called
<tt>ROOT/packages/notes</tt>.
- </p></li>
-<li>
-<p>Since we didn't create any files for the package before, the
+ </p></li><li><p>Since we didn't create any files for the package before, the
directory that APM created will be empty except for the
<tt>notes.info</tt> file. At this point, create a file called
<tt>ROOT/packages/notes/sql/notes-create.sql</tt> and put the add
the <a href="objects.html" title="OpenACS 4.5 Data Models and the Object System">data model</a> that we created before to
this file. You should also create a file called
<tt>ROOT/packages/notes/sql/notes-drop.sql</tt> that drops the
- data model. </p>
-<p>After you do this, go back to the main APM page. From there, click
+ data model. </p><p>After you do this, go back to the main APM page. From there, click
the link called "notes" to go to the management page for the new
package. Now click the link called "Manage file information",
then the "Scan the <tt>packages/notes</tt> directory for
additional files in this package" link on that page to scan the
file system for new files. This will bring you do a page that lists
all the files you just added and lets you add them to the
<tt>notes</tt> package.
- </p>
-<p>
+ </p><p>
Note that while the <tt>.sql</tt> files have been added to the
- packge, they <span class="emphasis"><i>have not</i></span> been loaded into the database. For the
+ packge, they <span class="emphasis"><em>have not</em></span> been loaded into the database. For the
purposes of development, you have to load the data model by hand,
because while OpenACS has automatic mechanisms for loading and reloading
<tt>.tcl</tt> files for code, it does not do the same thing for
data model files.
- </p>
-</li>
-<li><p>Now go back to the main management page for the <tt>notes</tt>
+ </p></li><li><p>Now go back to the main management page for the <tt>notes</tt>
If your package has parameters, create them using the "Manage
- Parameter Information" link.</p></li>
-<li>
-<p>The new package has been created and installed in the server. At
+ Parameter Information" link.</p></li><li><p>The new package has been created and installed in the server. At
this point, you should add your package files to your CVS repository.
I'll assume that you have set up your development repository according
to the standards described in
<a href="http://acs40.arsdigita.com/acs40-project-central/client-build.html" target="_top">these instructions</a>. If so, then you just do this:
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
% cd ROOT/packages
% cvs add notes
@@ -601,44 +388,34 @@
% cd ROOT/packages/notes
% cvs commit -m "add new package for notes"
- </pre>
-</li>
-<li><p>
+ </pre></li><li><p>
Now you can start developing the package. In addition to writing code,
you should also consider the tasks outlined in the <a href="http://acs40.arsdigita.com/acs40-project-central/package-submission.html" target="_top">package submission guidelines</a>.
- </p></li>
-</ol></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="packages-subsites"></a>The Site Map and Package Instances</h3></div></div>
-<p>
+ </p></li></ol></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="packages-subsites"></a>The Site Map and Package Instances</h3></div></div><p>
At this point, you are probably excited to see your new package in
action. But, we haven't added any user visible pages yet. By
convention, user visible pages go in the
<tt>ROOT/packages/notes/www</tt> directory. So go there and add a
file called <tt>hello.html</tt> with some text in it. Now we have
to make the user pages visible in the site. Since we didn't put the
pages underneath <tt>ROOT/www</tt> they will not appear on their
- own. What we have to do is <span class="emphasis"><i>mount</i></span> the application into the site
+ own. What we have to do is <span class="emphasis"><em>mount</em></span> the application into the site
map. That is, we have to define the URL from which the application
will serve its pages. This process is slightly more complex than in
OpenACS 3.x, but also much more flexible.
- </p>
-<p>
+ </p><p>
In OpenACS 3.x, everything in the site was implicitly mounted underneath
<tt>ROOT/www</tt>. AOLserver automatically took any URL like
<tt>/foo/bar/moo/baz.html</tt> and mapped it to the file
<tt>ROOT/www/foo/bar/moo/baz.html</tt>. This was conveniently
simple, but lacked flexibility. In particular, it was difficult to
map content that lived outside the page root into the site, and it was
also hard to map mulitiple URLs to the same place in the file system.
- </p>
-<p>
+ </p><p>
In OpenACS 4.5, administrators can define an arbitrary mapping between the
URLs the user types and the actual file in the file system that is
- served. This mapping is called the <span class="emphasis"><i>site map</i></span> and entries in the
- site map are called <span class="emphasis"><i>site nodes</i></span>. Each site node maps a URL to an
+ served. This mapping is called the <span class="emphasis"><em>site map</em></span> and entries in the
+ site map are called <span class="emphasis"><em>site nodes</em></span>. Each site node maps a URL to an
OpenACS object. Since package instances are objects, the site map allows
us to easily map package instances to URLs As we said before, each
instance of an application has its own set of parameters settings and
@@ -652,8 +429,7 @@
you how OpenACS figures out which instance of your application was
requested by the user at any given time. The <a href="subsites.html" title="Writing OpenACS 4.5 Application Pages">page development</a> tutorial shows you how to use this
information in your user interface.
- </p>
-<p>
+ </p><p>
In order to make the new <tt>notes</tt> application visible to
users, we have to mount it in the site map. You do this by going to
the <a href="/admin/site-map" target="_top">Site Map</a> page, which is by
@@ -662,17 +438,14 @@
the root of the site, then click "new application" to mount a new
instance of the <tt>notes</tt> application to the site. Name the
new instance <tt>notes-1</tt>.
- </p>
-<p>
+ </p><p>
After you get done doing this, try typing this URL into your browser:
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
http://your-server.your-domain.com/notes/hello.html
- </pre>
-<p>
+ </pre><p>
Now you should see the contents of the page that you added. What has
happened is that all URLs that start with <tt>/notes</tt> have
been mapped in such a way as to serve content from the directory
@@ -682,68 +455,21 @@
later document, we'll see how to write your applicationn so that the
code can detect from where in the site it was invoked. This is the key
to supporting <a href="subsites.html" title="Writing OpenACS 4.5 Application Pages">subsites</a>.
- </p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="packages-summary"></a>Summary</h3></div></div>
-<p>
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="packages-summary"></a>Summary</h3></div></div><p>
The APM performs the following tasks in an OpenACS site:
- </p>
-<div class="itemizedlist"><ul>
-<li><p>
+ </p><div class="itemizedlist"><ul type="disc"><li><p>
Manages creation, installation, and removal of packages from the
server. Also keeps track of what files belong to which packages.
- </p></li>
-<li><p>
+ </p></li><li><p>
Manages package upgrades.
- </p></li>
-<li><p>
- Manages information on all package <span class="emphasis"><i>instances</i></span> in a site. For
+ </p></li><li><p>
+ Manages information on all package <span class="emphasis"><em>instances</em></span> in a site. For
correctly written application packages, this allows the site
administrator to map multiple instances of a package to URLs within a
site.
- </p></li>
-<li><p>
+ </p></li><li><p>
Writes out package distribution files for other people to download and
install. We'll cover this later.
- </p></li>
-</ul></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="packages-add-reading"></a>Additional Reading</h3></div></div>
-<div class="itemizedlist"><ul>
-<li><p><a href="apm-design.html">OpenACS 4.5 Package Manager Design</a></p></li>
-<li><p><a href="apm-requirements.html">OpenACS 4.5 Package Manager Requirements</a></p></li>
-<li><p><a href="http://acs40.arsdigita.com/acs40-project-central/package-submission.html" target="_top">Package submission guidelines</a></p></li>
-</ul></div>
-<p><div class="cvstag">($Id$)</div></p>
-</div>
-</div>
-<div class="navfooter">
-<hr>
-<table width="100%" summary="Navigation footer">
-<tr>
-<td width="40%" align="left">
-<a accesskey="p" href="objects.html">Prev</a> </td>
-<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
-<td width="40%" align="right"> <a accesskey="n" href="request-processor.html">Next</a>
-</td>
-</tr>
-<tr>
-<td width="40%" align="left">OpenACS 4.5 Data Models and the Object System </td>
-<td width="20%" align="center"><a accesskey="u" href="dev-guide.html">Up</a></td>
-<td width="40%" align="right"> The Request Processor</td>
-</tr>
-</table>
-<hr>
-<address>
- rmello at fslc.usu.edu
- </address>
-<address><a href="mailto:vinod@kurup.com">
+ </p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="packages-add-reading"></a>Additional Reading</h3></div></div><div class="itemizedlist"><ul type="disc"><li><p><a href="apm-design.html">OpenACS 4.5 Package Manager Design</a></p></li><li><p><a href="apm-requirements.html">OpenACS 4.5 Package Manager Requirements</a></p></li><li><p><a href="http://acs40.arsdigita.com/acs40-project-central/package-submission.html" target="_top">Package submission guidelines</a></p></li></ul></div><p><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="objects.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="request-processor.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS 4.5 Data Models and the Object System </td><td width="20%" align="center"><a accesskey="u" href="dev-guide.html">Up</a></td><td width="40%" align="right"> The Request Processor</td></tr></table><hr><address>rmello at fslc.usu.edu</address><address><a href="mailto:vinod@kurup.com">
vinod@kurup.com
- </a></address>
-</div>
-</body>
-</html>
+ </a></address></div></body></html>
Index: openacs-4/packages/acs-core-docs/www/parties.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/parties.html,v
diff -u -r1.7 -r1.7.2.1
--- openacs-4/packages/acs-core-docs/www/parties.html 7 Mar 2002 06:55:36 -0000 1.7
+++ openacs-4/packages/acs-core-docs/www/parties.html 15 May 2002 23:26:18 -0000 1.7.2.1
@@ -1,64 +1,28 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type">
-<title>Parties in OpenACS 4.5</title>
-<meta name="generator" content="DocBook XSL Stylesheets V1.45">
-<link rel="home" href="index.html" title="OpenACS Documentation">
-<link rel="up" href="more-developer-info.html" title="Chapter 5. Other Developer Resources">
-<link rel="previous" href="other-developer-overview.html" title="Overview">
-<link rel="next" href="object-identity.html" title="Object Identity">
-<link rel="stylesheet" href="openacs.css" type="text/css">
-</head>
-<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-<div class="navheader">
-<a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr>
-<td width="20%" align="left">
-<a accesskey="p" href="other-developer-overview.html">Prev</a> </td>
-<th width="60%" align="center">Chapter 5. Other Developer Resources</th>
-<td width="20%" align="right"> <a accesskey="n" href="object-identity.html">Next</a>
-</td>
-</tr></table>
-<hr>
-</div>
-<div class="sect1">
-<div class="titlepage"><div><h2 class="title" style="clear: both">
-<a name="parties"></a>Parties in OpenACS 4.5</h2></div></div>
-<div class="authorblurb"><p>
-by <a href="http://planitia.org" target="_top">Rafael H. Schloming</a>
-</p></div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="parties-intro"></a>Introduction</h3></div></div>
-<p>While many applications must deal with individuals and many applications
+<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"><title>Parties in OpenACS 4.5</title><meta name="generator" content="DocBook XSL Stylesheets V1.50.0"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="more-developer-info.html" title="Chapter 5. Other Developer Resources"><link rel="previous" href="other-developer-overview.html" title="Overview"><link rel="next" href="object-identity.html" title="Object Identity"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="other-developer-overview.html">Prev</a> </td><th width="60%" align="center">Chapter 5. Other Developer Resources</th><td width="20%" align="right"> <a accesskey="n" href="object-identity.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="parties"></a>Parties in OpenACS 4.5</h2></div></div><div class="authorblurb"><p>
+by <a href="http://planitia.org" target="_top">Rafael H. Schloming</a><br>
+ OpenACS docs are written by the named authors, but may be edited
+ by OpenACS documentation staff.
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="parties-intro"></a>Introduction</h3></div></div><p>While many applications must deal with individuals and many applications
must deal with groups, most applications must deal with individuals
-<span class="emphasis"><i>or</i></span> groups. It is often the case with such applications that in many
+<span class="emphasis"><em>or</em></span> groups. It is often the case with such applications that in many
respects both individuals and groups are treated in an identical manner. It
is this latter class of application that makes it extremely useful to model
individuals and groups as specializations of one supertype. This concept is
so commonly used throughout human language and thought that we don't even
need to invent for it some bizarre and specialized terminology. This
-supertype is called a "party".</p>
-<p>A classic example use of the "party" supertype is evident
+supertype is called a "party".</p><p>A classic example use of the "party" supertype is evident
in a common address book. A typical person's address book might contain
the address of his doctor, and his cable company. So what do we label the
first field in an entry in his address book? It isn't a person, and it
-isn't a company. It is a "party".</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="parties-data-model"></a>The Data Model</h3></div></div>
-<p>Most developers who do significant work with the OpenACS will become
+isn't a company. It is a "party".</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="parties-data-model"></a>The Data Model</h3></div></div><p>Most developers who do significant work with the OpenACS will become
intimately familiar with the parties data model, and probably extend it on
many occasions. For this reason the parties developer guide will begin with
-an introduction to the data model.</p>
-<p><span class="strong"><i>Parties</i></span></p>
-<p>The central table in the parties data model is the parties table itself.
+an introduction to the data model.</p><p><span class="strong"><em>Parties</em></span></p><p>The central table in the parties data model is the parties table itself.
Every party has exactly one row in this table. Every party has an optional
unique email address and an optional url. A party is an acs object, so
permissions may granted and revoked on parties and auditing information is
-stored in the acs objects table.</p>
-<pre class="programlisting">
+stored in the acs objects table.</p><pre class="programlisting">
<tt>create table parties (
party_id not null
@@ -71,21 +35,17 @@
);
</tt>
-</pre>
-<p>There are two tables that extend the parties table. One is the persons
+</pre><p>There are two tables that extend the parties table. One is the persons
table and one is the groups table. A row in the persons table represents the
most basic form of individual that is modeled by the parties data model. A
row in the groups table represents the most basic form of an aggregation of
-individuals that is represented.</p>
-<p><span class="strong"><i>Persons</i></span></p>
-<p>If a party is an individual then there will be a row in the persons table
+individuals that is represented.</p><p><span class="strong"><em>Persons</em></span></p><p>If a party is an individual then there will be a row in the persons table
containing first_names and last_name for that individual. Note that the
primary key of the persons table (person_id) references the primary key of
the parties table (party_id). This guarantees that if there is a row in the
persons table then there must be a corresponding row in the parties table.
Also note that an individual need not be known to the system as a user. A
-user is in fact a further specialized form of an individual.</p>
-<pre class="programlisting">
+user is in fact a further specialized form of an individual.</p><pre class="programlisting">
<tt>create table persons (
person_id not null
@@ -97,25 +57,21 @@
);
</tt>
-</pre>
-<p><span class="strong"><i>Users</i></span></p>
-<p>The users table is an even more specialized form of an individual. A row
+</pre><p><span class="strong"><em>Users</em></span></p><p>The users table is an even more specialized form of an individual. A row
in the users table represents an individual that has login access to the
system. Note that the primary key of the users table references the primary
key of the persons table. Once again this guarantees that if there is a row
in the users table then there must be a row in the persons table and a row in
-the parties table.</p>
-<p>One of the interesting benefits of decomposing all the information
+the parties table.</p><p>One of the interesting benefits of decomposing all the information
associated with a user into the four tables (acs_objects, parties, persons,
users) is that it is now possible to "nuke" a user from a live
system by removing his entry from the users table, but leaving the rest of
his information present (i.e. turning him from a user into a person). This is
because wherever possible the OpenACS 4.5 data model references the persons or
-parties table, <span class="strong"><i>not</i></span> the users table. If this feature is
+parties table, <span class="strong"><em>not</em></span> the users table. If this feature is
desired when extending the system, then the developers should be careful to
only references the users table in situations where it is clear that the
-references is to a user and not to an individual.</p>
-<pre class="programlisting">
+references is to a user and not to an individual.</p><pre class="programlisting">
<tt>create table users (
user_id not null
@@ -144,15 +100,12 @@
);
</tt>
-</pre>
-<p><span class="strong"><i>Groups</i></span></p>
-<p>The final piece of the parties data model is the groups data model. A
+</pre><p><span class="strong"><em>Groups</em></span></p><p>The final piece of the parties data model is the groups data model. A
group is a specialization of a party that represents an aggregation of other
parties. The only extra information directly associated with a group (beyond
that in the parties table) is the name of the group. As you might guess there
is another piece to the groups data model that records relations between
-parties and groups.</p>
-<pre class="programlisting">
+parties and groups.</p><pre class="programlisting">
<tt>create table groups (
group_id not null
@@ -163,35 +116,30 @@
);
</tt>
-</pre>
-<p><span class="strong"><i>Group Relations</i></span></p>
-<p>One surprise here is that there are actually two relations involved. One
+</pre><p><span class="strong"><em>Group Relations</em></span></p><p>One surprise here is that there are actually two relations involved. One
is the normal membership relation between parties and groups. A party may be
a "member" of a group. The other relation is a composition
relation between two groups. To fully understand why two relations are
necessary, and the situations in which each is appropriate, let's
consider an example. Greenpeace is an organization that can have as members
both individuals and organizations. Hence the membership relation between
-groups and <span class="emphasis"><i>parties</i></span>. But just because you are a member of an
+groups and <span class="emphasis"><em>parties</em></span>. But just because you are a member of an
organization that is a member of Greenpeace, that doesn't make you a
member of Greenpeace, i.e., membership is not transitive with respect to
itself. Now let's consider a multinational corporation. This corporation
might have a U.S. division and a European division. A member of either the
U.S. or European division is automatically a member of the company. In this
situation the U.S. and European divisions are "components" of
-the company, i.e., membership <span class="emphasis"><i>is</i></span> transitive with respect to
+the company, i.e., membership <span class="emphasis"><em>is</em></span> transitive with respect to
composition. Having a membership relation between groups and parties, and
having a composition relation between groups and groups allows us to easily
model the full range of sophisticated group structures that exist in the real
-world.</p>
-<p><span class="strong"><i>Group Membership</i></span></p>
-<p>Group memberships can be created and manipulated using the membership_rel
+world.</p><p><span class="strong"><em>Group Membership</em></span></p><p>Group memberships can be created and manipulated using the membership_rel
package. Note that you can only create one membership object for a given
group, party pair. Because of composition, it is possible in some
circumstances to make someone a member of a group of which they are already a
member. This is because there is a distinction between direct membership and
-indirect membership (membership via some component or sub component).</p>
-<pre class="programlisting">
+indirect membership (membership via some component or sub component).</p><pre class="programlisting">
<tt>create or replace package membership_rel
as
@@ -235,16 +183,13 @@
show errors
</tt>
-</pre>
-<p><span class="strong"><i>Group Composition</i></span></p>
-<p>Composition relations can be created or destroyed using the
+</pre><p><span class="strong"><em>Group Composition</em></span></p><p>Composition relations can be created or destroyed using the
composition_rel package. The only restriction on compositions is that there
cannot be a cycle, i.e., a group cannot be a component of itself either
directly or indirectly. This constraint is maintained for you by the API, but
if you don't want users seeing some random PL/SQL error message, it is a
good idea to not give them the option to create a composition relation that
-would result in a cycle.</p>
-<pre class="programlisting">
+would result in a cycle.</p><pre class="programlisting">
<tt>create or replace package composition_rel
as
@@ -267,12 +212,7 @@
show errors
</tt>
-</pre>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="parties-views"></a>Views</h3></div></div>
-<p>The data model described above does a reasonable job of representing many
+</pre></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="parties-views"></a>Views</h3></div></div><p>The data model described above does a reasonable job of representing many
of the situations one is likely to encounter when modeling organizational
structures, but we still need to be able to efficiently answer questions like
"what members are in this group and all of its components?", and
@@ -281,8 +221,7 @@
Directed Acyclic Graph (DAG) between a group and its components. For these
reasons the party system provides a bunch of views that take advantage of the
internal representation of group relations to answer questions like these
-very quickly.</p>
-<p>This view returns all the subcomponents of a group including components of
+very quickly.</p><p>This view returns all the subcomponents of a group including components of
sub components and so forth. The container_id column is the group_id of the
group in which component_id is directly contained. This allows you to easily
distinguish whether a component is a direct component or an indirect
@@ -291,84 +230,66 @@
group_id, component_id, and container_id. The rel_id column points to the row
in acs_rels that contains the relation object that relates component_id to
container_id. The rel_id might be useful for retrieving or updating standard
-auditing info for the relation.</p>
-<pre class="programlisting">
+auditing info for the relation.</p><pre class="programlisting">
<tt>create or replace view group_component_map
as select group_id, component_id, container_id, rel_id
...
</tt>
-</pre>
-<p>This is similar to group_component_map except for membership relations.
+</pre><p>This is similar to group_component_map except for membership relations.
Note that this view will return all membership relations regardless of
-membership state.</p>
-<pre class="programlisting">
+membership state.</p><pre class="programlisting">
<tt>create or replace view group_member_map
as select group_id, member_id, container_id, rel_id
...
</tt>
-</pre>
-<p>The group_approved_member_map is the same as the group_member_map except
-it only returns entries that relate to approved members.</p>
-<pre class="programlisting">
+</pre><p>The group_approved_member_map is the same as the group_member_map except
+it only returns entries that relate to approved members.</p><pre class="programlisting">
<tt>create or replace view group_approved_member_map
as select group_id, member_id, container_id, rel_id
...
</tt>
-</pre>
-<p>This view is useful if you don't care about the distinction between
+</pre><p>This view is useful if you don't care about the distinction between
direct membership and indirect membership. It simply returns all members of a
-group including members of components. (It is the transitive closure.)</p>
-<pre class="programlisting">
+group including members of components. (It is the transitive closure.)</p><pre class="programlisting">
<tt>create or replace view group_distinct_member_map
as select group_id, member_id
...
</tt>
-</pre>
-<p>This view is the same as group_distinct_member_map, except it includes the
+</pre><p>This view is the same as group_distinct_member_map, except it includes the
identity mapping. In other words it maps from a party to the fully expanded
list of parties represented by that party including the party itself. So if a
party is an individual this view will have exactly one mapping that is from
that party to itself. If a view is a group containing three individuals, this
view will have four rows for that party, one for each member, and one from
-the party to itself.</p>
-<pre class="programlisting">
+the party to itself.</p><pre class="programlisting">
<tt>create or replace view party_member_map
as select party_id, member_id
...
</tt>
-</pre>
-<p>This view is the same as above except that when it expands groups, it only
-pays attention to approved members.</p>
-<pre class="programlisting">
+</pre><p>This view is the same as above except that when it expands groups, it only
+pays attention to approved members.</p><pre class="programlisting">
<tt>create or replace view party_approved_member_map
as select party_id, member_id
...
</tt>
-</pre>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="parties-extending-data-model"></a>Extending The Parties Data Model</h3></div></div>
-<p>As is, the parties data model can represent some fairly sophisticated real
+</pre></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="parties-extending-data-model"></a>Extending The Parties Data Model</h3></div></div><p>As is, the parties data model can represent some fairly sophisticated real
world situations, and a lot of work has been put into making this efficient,
but it is foolish to assume that this data model is sufficient for every
application. It therefore seems likely that developers will want to extend
the parties data model in a number of ways. This section will describe some
-of the more common ways.</p>
-<p><span class="strong"><i>Specializing Users</i></span></p>
-<p>It is conceivable that some applications will want to collect more
+of the more common ways.</p><p><span class="strong"><em>Specializing Users</em></span></p><p>It is conceivable that some applications will want to collect more
detailed information for people using the system. If it is the case that
there can be only one such piece of information per user, then it might make
sense to create another type of individual that is a further specialization
@@ -378,16 +299,12 @@
have a primary key that references the users table, thereby guaranteeing that
each row in the mensa_users table has a corresponding row in each of the
users, persons, parties, and acs_objects tables. This child table could then
-store any extra information relevant to the MENSA community.</p>
-<p><span class="strong"><i>Specializing Groups</i></span></p>
-<p>If one were to build an intranet application on top of the 4.5 party
+store any extra information relevant to the MENSA community.</p><p><span class="strong"><em>Specializing Groups</em></span></p><p>If one were to build an intranet application on top of the 4.5 party
system, it is likely that one would want to take advantage of the systems
efficient representation of sophisticated organizational structures, but
there would be much more specialized information associated with each group.
In this case it would make sense to specialize the group party type into a
-company party type in the same manner as above.</p>
-<p><span class="strong"><i>Specializing Membership Relations</i></span></p>
-<p>The final portion of the parties data model that is designed to be
+company party type in the same manner as above.</p><p><span class="strong"><em>Specializing Membership Relations</em></span></p><p>The final portion of the parties data model that is designed to be
extended is the membership relationship. Consider the intranet example again.
It is likely that a membership in a company would have more information
associated with it than a membership in an ordinary group. An obvious example
@@ -396,33 +313,6 @@
single integer primary key in what could be thought of as a pure relation.
Because a membership relation is an ordinary acs object with <a href="object-identity.html" target="_top">object identity</a>, it is as easy to extend the
membership relation to store extra information as it is to extend the users
-table or the groups table.</p>
-<p><div class="cvstag">($Id$)</div></p>
-</div>
-</div>
-<div class="navfooter">
-<hr>
-<table width="100%" summary="Navigation footer">
-<tr>
-<td width="40%" align="left">
-<a accesskey="p" href="other-developer-overview.html">Prev</a> </td>
-<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
-<td width="40%" align="right"> <a accesskey="n" href="object-identity.html">Next</a>
-</td>
-</tr>
-<tr>
-<td width="40%" align="left">Overview </td>
-<td width="20%" align="center"><a accesskey="u" href="more-developer-info.html">Up</a></td>
-<td width="40%" align="right"> Object Identity</td>
-</tr>
-</table>
-<hr>
-<address>
- rmello at fslc.usu.edu
- </address>
-<address><a href="mailto:vinod@kurup.com">
+table or the groups table.</p><p><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="other-developer-overview.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="object-identity.html">Next</a></td></tr><tr><td width="40%" align="left">Overview </td><td width="20%" align="center"><a accesskey="u" href="more-developer-info.html">Up</a></td><td width="40%" align="right"> Object Identity</td></tr></table><hr><address>rmello at fslc.usu.edu</address><address><a href="mailto:vinod@kurup.com">
vinod@kurup.com
- </a></address>
-</div>
-</body>
-</html>
+ </a></address></div></body></html>
Index: openacs-4/packages/acs-core-docs/www/permissions-design.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/permissions-design.html,v
diff -u -r1.5 -r1.5.2.1
--- openacs-4/packages/acs-core-docs/www/permissions-design.html 7 Mar 2002 06:55:36 -0000 1.5
+++ openacs-4/packages/acs-core-docs/www/permissions-design.html 15 May 2002 23:26:18 -0000 1.5.2.1
@@ -1,51 +1,12 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type">
-<title>OpenACS 4 Permissions Design</title>
-<meta name="generator" content="DocBook XSL Stylesheets V1.45">
-<link rel="home" href="index.html" title="OpenACS Documentation">
-<link rel="up" href="kernel-doc.html" title="Chapter 7. Kernel Documentation">
-<link rel="previous" href="permissions-requirements.html" title="OpenACS 4 Permissions Requirements">
-<link rel="next" href="groups-requirements.html" title="OpenACS 4 Groups Requirements">
-<link rel="stylesheet" href="openacs.css" type="text/css">
-</head>
-<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-<div class="navheader">
-<a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr>
-<td width="20%" align="left">
-<a accesskey="p" href="permissions-requirements.html">Prev</a> </td>
-<th width="60%" align="center">Chapter 7. Kernel Documentation</th>
-<td width="20%" align="right"> <a accesskey="n" href="groups-requirements.html">Next</a>
-</td>
-</tr></table>
-<hr>
-</div>
-<div class="sect1">
-<div class="titlepage"><div><h2 class="title" style="clear: both">
-<a name="permissions-design"></a>OpenACS 4 Permissions Design</h2></div></div>
-<div class="authorblurb"><p>
-by <a href="mailto:jmp@arsdigita.com" target="_top">John Prevost</a> and <a href="http://planitia.org" target="_top">Rafael H. Schloming</a>
-</p></div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="permissions-design-essentials"></a>Essentials</h3></div></div>
-<div class="itemizedlist"><ul>
-<li><p>Tcl in <tt>packages/acs-kernel</tt>
-</p></li>
-<li><p><a href="permissions-requirements.html">OpenACS 4 Permissions Requirements</a></p></li>
-<li><p><a href="/doc/sql/display-sql?url=acs-permissions-create.sql&package_key=acs-kernel" target="_top">
-SQL file</a></p></li>
-<li><p>
-<a href="images/permissions-er.png" target="_top">ER diagram</a>
+<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"><title>OpenACS 4 Permissions Design</title><meta name="generator" content="DocBook XSL Stylesheets V1.50.0"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="kernel-doc.html" title="Chapter 7. Kernel Documentation"><link rel="previous" href="permissions-requirements.html" title="OpenACS 4 Permissions Requirements"><link rel="next" href="groups-requirements.html" title="OpenACS 4 Groups Requirements"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="permissions-requirements.html">Prev</a> </td><th width="60%" align="center">Chapter 7. Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="groups-requirements.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="permissions-design"></a>OpenACS 4 Permissions Design</h2></div></div><div class="authorblurb"><p>
+by <a href="mailto:jmp@arsdigita.com" target="_top">John Prevost</a> and <a href="http://planitia.org" target="_top">Rafael H. Schloming</a><br>
+ OpenACS docs are written by the named authors, but may be edited
+ by OpenACS documentation staff.
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="permissions-design-essentials"></a>Essentials</h3></div></div><div class="itemizedlist"><ul type="disc"><li><p>Tcl in <tt>packages/acs-kernel</tt></p></li><li><p><a href="permissions-requirements.html">OpenACS 4 Permissions Requirements</a></p></li><li><p><a href="/doc/sql/display-sql?url=acs-permissions-create.sql%26amp;package_key=acs-kernel" target="_top">
+SQL file</a></p></li><li><p><a href="images/permissions-er.png" target="_top">ER diagram</a>
-</p></li>
-</ul></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="permissions-design-intro"></a>Introduction</h3></div></div>
-<p>The goal of the Permissions system is to provide generic means to both
+</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="permissions-design-intro"></a>Introduction</h3></div></div><p>The goal of the Permissions system is to provide generic means to both
programmers and site administrators to designate operations (methods) as
requiring permissions, and then to check, grant, or revoke permissions via a
consistent interface. For example, we might decide that the transaction that
@@ -54,371 +15,175 @@
that viewing a certain set of pages within the application is an operation to
be individually granted or revoked from a user. It's expected that the
Permissions system will be seeing a lot of use - almost every page will make
-at least one permissions API call, and some will make several.</p>
-<p>For programmers, the Permissions API provides a means to work with access
+at least one permissions API call, and some will make several.</p><p>For programmers, the Permissions API provides a means to work with access
control in a consistent manner. If a programmer's OpenACS package defines new
methods for itself, the Permissions API must provide simple calls to
determine whether the current user is authorized to perform the given method.
In addition, using the Permissions API, queries should easily select only
-those package objects on which a user has certain permissions.</p>
-<p>For site administrators and other authorized users, the Permissions UI
+those package objects on which a user has certain permissions.</p><p>For site administrators and other authorized users, the Permissions UI
provides a means to aggregate the primitive operations (methods) made
available by the programmer into logical privileges (like read, write, and
-admin) that can be granted and revoked.</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="permissions-design-history"></a>Historical Considerations</h3></div></div>
-<p>In earlier versions of the OpenACS, permissions and access control was handled
+admin) that can be granted and revoked.</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="permissions-design-history"></a>Historical Considerations</h3></div></div><p>In earlier versions of the OpenACS, permissions and access control was handled
on a module-by-module basis, often even on a page-by-page basis. For example,
a typical module might allow any registered user to access its pages
read-only, but only allow members of a certain group to make changes. The way
this group was determined also varied greatly between modules. Some modules
used "roles", while others did not. Other modules did all access
control based simply on coded rules regarding who can act on a given database
-row based on the information in that row.</p>
-<p>Problems resulting from this piecemeal approach to permissions and access
+row based on the information in that row.</p><p>Problems resulting from this piecemeal approach to permissions and access
control were many, the two major ones being inconsistency, and
repeated/redundant code. Thus the drive in OpenACS 4 to provide a unified,
consistent permissions system that both programmers and administrators can
-readily use.</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="permissions-design-competitors"></a>Competitive Analysis</h3></div></div>
-<p><span class="emphasis"><i>None available as of 10/2000.</i></span></p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="permissions-design-design-tradeoffs"></a>Design Tradeoffs</h3></div></div>
-<p>The core of the permissions data model is quite simple. Unfortunately, the
+readily use.</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="permissions-design-competitors"></a>Competitive Analysis</h3></div></div><p><span class="emphasis"><em>None available as of 10/2000.</em></span></p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="permissions-design-design-tradeoffs"></a>Design Tradeoffs</h3></div></div><p>The core of the permissions data model is quite simple. Unfortunately, the
hierarchical nature of default permissions entails quite a number of tree
queries which could slow the system down. Since every page will have at least
one permissions check, a number of views and auxiliary tables
(de-normalizations of the data model) have been created to speed up access
queries. As a consequence, speed of updates are decreased and requirements
-for additional storage space increase.</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="permissions-design-data-model"></a>Data Model Discussion</h3></div></div>
-<p>As described in section V., the core of the permissions data model is
+for additional storage space increase.</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="permissions-design-data-model"></a>Data Model Discussion</h3></div></div><p>As described in section V., the core of the permissions data model is
simple, though a number of views and auxiliary tables exist to ensure
-adequate performance. The core model consists of five tables:</p>
-<div class="variablelist"><dl>
-<dt><span class="term"><tt>acs_methods</tt>
+adequate performance. The core model consists of five tables:</p><div class="variablelist"><dl><dt><span class="term"><tt>acs_methods</tt>
-</span></dt>
-<dd><p>The set of all defined methods.</p></dd>
-<dt><span class="term"><tt>acs_privileges</tt>
+</span></dt><dd><p>The set of all defined methods.</p></dd><dt><span class="term"><tt>acs_privileges</tt>
-</span></dt>
-<dd><p>The set of all defined privileges.</p></dd>
-<dt><span class="term"><tt>acs_privilege_method_rules</tt>
+</span></dt><dd><p>The set of all defined privileges.</p></dd><dt><span class="term"><tt>acs_privilege_method_rules</tt>
-</span></dt>
-<dd><p>A relation describing the set of methods <span class="strong"><i>directly</i></span>
-associated with each privilege.</p></dd>
-<dt><span class="term"><tt>acs_privilege_hierarchy</tt>
+</span></dt><dd><p>A relation describing the set of methods <span class="strong"><em>directly</em></span>
+associated with each privilege.</p></dd><dt><span class="term"><tt>acs_privilege_hierarchy</tt>
-</span></dt>
-<dd><p>A relation describing which privileges <span class="strong"><i>directly</i></span>
-"contain" other privileges.</p></dd>
-<dt><span class="term"><tt>acs_permissions</tt>
+</span></dt><dd><p>A relation describing which privileges <span class="strong"><em>directly</em></span>
+"contain" other privileges.</p></dd><dt><span class="term"><tt>acs_permissions</tt>
-</span></dt>
-<dd><p>A table with one (<span class="emphasis"><i>party</i></span>, <span class="emphasis"><i>object</i></span>, <span class="emphasis"><i>privilege</i></span>)
-row for every privilege <span class="strong"><i>directly</i></span> granted on any object in
+</span></dt><dd><p>A table with one (<span class="emphasis"><em>party</em></span>, <span class="emphasis"><em>object</em></span>, <span class="emphasis"><em>privilege</em></span>)
+row for every privilege <span class="strong"><em>directly</em></span> granted on any object in
the system - this is a denormalization of
<tt>acs_privilege_method_rules</tt> and
-<tt>acs_privilege_hierarchy</tt>
-</p></dd>
-</dl></div>
-<p>There are also a number of views to make it easier to ask specific
+<tt>acs_privilege_hierarchy</tt></p></dd></dl></div><p>There are also a number of views to make it easier to ask specific
questions about permissions. For example, a number of the above tables
describe "direct" or explicit permissions. Inheritance and default
values can, however, introduce permissions which are not directly specified.
(For example, read access on a bboard allows read access on all the messages
-in the bboard.)</p>
-<p>The following views provide flattened versions of inherited
-information:</p>
-<div class="variablelist"><dl>
-<dt><span class="term"><tt>acs_privilege_method_map</tt>
+in the bboard.)</p><p>The following views provide flattened versions of inherited
+information:</p><div class="variablelist"><dl><dt><span class="term"><tt>acs_privilege_method_map</tt>
-</span></dt>
-<dd><p>Map of privileges to the methods they contain either directly or because
-of another privilege which is included (at any depth).</p></dd>
-<dt><span class="term"><tt>acs_object_grantee_priv_map</tt>
+</span></dt><dd><p>Map of privileges to the methods they contain either directly or because
+of another privilege which is included (at any depth).</p></dd><dt><span class="term"><tt>acs_object_grantee_priv_map</tt>
-</span></dt>
-<dd><p>Relation on (<span class="emphasis"><i>object</i></span>, <span class="emphasis"><i>party</i></span>, <span class="emphasis"><i>privilege</i></span>) for
+</span></dt><dd><p>Relation on (<span class="emphasis"><em>object</em></span>, <span class="emphasis"><em>party</em></span>, <span class="emphasis"><em>privilege</em></span>) for
privileges from <tt>acs_privileges</tt>) granted directly on the object, or
-on the context of the object (at any depth).</p></dd>
-<dt><span class="term"><tt>acs_object_party_privilege_map</tt>
+on the context of the object (at any depth).</p></dd><dt><span class="term"><tt>acs_object_party_privilege_map</tt>
-</span></dt>
-<dd><p>Relation on (<span class="emphasis"><i>object</i></span>, <span class="emphasis"><i>party</i></span>, <span class="emphasis"><i>privilege</i></span>) for
+</span></dt><dd><p>Relation on (<span class="emphasis"><em>object</em></span>, <span class="emphasis"><em>party</em></span>, <span class="emphasis"><em>privilege</em></span>) for
privileges directly from <tt>acs_object_grantee_priv_map</tt> or also because
-a party is a member of a group (at any depth).</p></dd>
-<dt><span class="term"><tt>acs_object_party_method_map</tt>
+a party is a member of a group (at any depth).</p></dd><dt><span class="term"><tt>acs_object_party_method_map</tt>
-</span></dt>
-<dd><p>Relation with every (<span class="emphasis"><i>object</i></span>, <span class="emphasis"><i>party</i></span>, <span class="emphasis"><i>method</i></span>)
-tuple implied by the above trees.</p></dd>
-</dl></div>
-<p>In general, <span class="strong"><i>only <tt>acs_object_party_method_map</tt></i></span>
+</span></dt><dd><p>Relation with every (<span class="emphasis"><em>object</em></span>, <span class="emphasis"><em>party</em></span>, <span class="emphasis"><em>method</em></span>)
+tuple implied by the above trees.</p></dd></dl></div><p>In general, <span class="strong"><em>only <tt>acs_object_party_method_map</tt></em></span>
should be used for queries from other modules. The other views are
-intermediate steps in building that query.</p>
-<p>The data model also includes two simple PL/SQL procedures
+intermediate steps in building that query.</p><p>The data model also includes two simple PL/SQL procedures
(<tt>acs_permission.grant_permission</tt> and
<tt>acs_permission.revoke_permission</tt>) for granting and revoking a
-specific privilege for a specific user on a specific object.</p>
-<p>To sum up, the PL/SQL procedures are meant to be used to grant or revoke
+specific privilege for a specific user on a specific object.</p><p>To sum up, the PL/SQL procedures are meant to be used to grant or revoke
permissions. The five base tables represent the basic data model of the
system, with a set of views provided to convert them into a format suitable
for joining to answer specific questions. The exact means by which this
transformation takes place should not be depended on, since they may change
-for efficiency reasons.</p>
-<p>The transformations done create a set of default permissions, in
-which:</p>
-<div class="itemizedlist"><ul>
-<li><p>parties get the privileges of any groups they are directly or indirectly
-a member of</p></li>
-<li><p>privileges get associated with the methods of any other privileges they
+for efficiency reasons.</p><p>The transformations done create a set of default permissions, in
+which:</p><div class="itemizedlist"><ul type="disc"><li><p>parties get the privileges of any groups they are directly or indirectly
+a member of</p></li><li><p>privileges get associated with the methods of any other privileges they
have taken methods from (at any level) (see
-<tt>acs_privilege_hierarchy</tt>)</p></li>
-<li><p>objects get access control from direct grants, or inherit permissions
+<tt>acs_privilege_hierarchy</tt>)</p></li><li><p>objects get access control from direct grants, or inherit permissions
from their context (unless the "don't inherit" flag is
-set)</p></li>
-</ul></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="permissions-design-transactions"></a>Legal Transactions</h3></div></div>
-<p>There are three essential areas in which all transactions in the
-permissions system fall:</p>
-<div class="itemizedlist"><ul>
-<li><p>Modification of methods and privileges</p></li>
-<li><p>Modification of permissions</p></li>
-<li><p>Queries on permissions</p></li>
-</ul></div>
-<p>
-<span class="strong"><i>"Modification of methods and privileges."</i></span> This
+set)</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="permissions-design-transactions"></a>Legal Transactions</h3></div></div><p>There are three essential areas in which all transactions in the
+permissions system fall:</p><div class="itemizedlist"><ul type="disc"><li><p>Modification of methods and privileges</p></li><li><p>Modification of permissions</p></li><li><p>Queries on permissions</p></li></ul></div><p><span class="strong"><em>"Modification of methods and privileges."</em></span> This
refers to actions that happen mainly at package installation time - a package
will create a number of methods for its own use, then associate them with the
system's standard privileges, or new privileges which the package has
created. The association step might also happen later, if the site-wide
-administrator chooses to change permissions policy.</p>
-<p>These steps involve directly manipulating the <tt>acs_methods</tt>,
+administrator chooses to change permissions policy.</p><p>These steps involve directly manipulating the <tt>acs_methods</tt>,
<tt>acs_privileges</tt>, and <tt>acs_privilege_method_rules</tt> tables. A
web page for manipulating these features should be limited to site-wide
-administrators.</p>
-<p>
-<span class="strong"><i>"Modification of permissions"</i></span> - involves fairly
+administrators.</p><p><span class="strong"><em>"Modification of permissions"</em></span> - involves fairly
common operations. Users are typically able to administer permissions for
objects they themselves create. The two basic operations here are
"grant" and "revoke". Granting permissions is done via
<tt>acs_permissions.grant_permission</tt>, and revocation via
<tt>acs_permissions.revoke_permission</tt>. These directly manipulate the
-<tt>acs_permissions</tt> table.</p>
-<p>Web pages for making these changes are available to all users, so they
+<tt>acs_permissions</tt> table.</p><p>Web pages for making these changes are available to all users, so they
should not be in an admin area. In order to grant and revoke permissions on
an object, the user must have the <tt>administer_privileges</tt> method
-permission on that object.</p>
-<p>
-<span class="strong"><i>"Queries on permissions"</i></span> - by far the most
+permission on that object.</p><p><span class="strong"><em>"Queries on permissions"</em></span> - by far the most
common operation is querying the permissions database. Several kinds of
questions are commonly asked: First, and most commonly, "Can this party
perform this method on this object?" Two Tcl functions are provided to
answer this - one which returns a boolean, the other of which results in an
error page. These tcl functions directly access the
-<tt>acs_object_party_method_map</tt>.</p>
-<p>The second most commonly asked question occurs when a list of objects is
+<tt>acs_object_party_method_map</tt>.</p><p>The second most commonly asked question occurs when a list of objects is
being displayed, often in order to provide appropriate UI functionality:
"For this party, what methods are available on these objects?"
Here, the SQL query needs to filter based on whether the party/user can
perform some operation on the object. This is done via a join or sub-select
against <tt>acs_object_party_method_map</tt>, or by calling the Tcl functions
-for appropriate methods.</p>
-<p>Finally, when administering the permissions for an object, a web page
+for appropriate methods.</p><p>Finally, when administering the permissions for an object, a web page
needs to know all permissions directly granted on that object. This is done
-by querying against <tt>acs_permissions</tt>.</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="permissions-design-api"></a>API</h3></div></div>
-<p>The API to the permissions system consists of a few well-known tables,
-plus a pair of PL/SQL procedures and a pair of Tcl functions.</p>
-<p><span class="strong"><i>Tables</i></span></p>
-<p>
-<tt>acs_methods</tt>, <tt>acs_privileges</tt>, and
+by querying against <tt>acs_permissions</tt>.</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="permissions-design-api"></a>API</h3></div></div><p>The API to the permissions system consists of a few well-known tables,
+plus a pair of PL/SQL procedures and a pair of Tcl functions.</p><p><span class="strong"><em>Tables</em></span></p><p><tt>acs_methods</tt>, <tt>acs_privileges</tt>, and
<tt>acs_privilege_method_rules</tt> manage the set of permissions in the
system. At installation time, a package will add to these three tables to
-introduce new permissions into the system.</p>
-<p>The main table for queries is <tt>acs_object_party_method_map</tt>, which
-contains (<span class="emphasis"><i>object</i></span>, <span class="emphasis"><i>party</i></span>, <span class="emphasis"><i>method</i></span>) triples for all
-allowed operations in the system.</p>
-<p>Also of interest for queries is <tt>acs_permissions</tt>, which lists
+introduce new permissions into the system.</p><p>The main table for queries is <tt>acs_object_party_method_map</tt>, which
+contains (<span class="emphasis"><em>object</em></span>, <span class="emphasis"><em>party</em></span>, <span class="emphasis"><em>method</em></span>) triples for all
+allowed operations in the system.</p><p>Also of interest for queries is <tt>acs_permissions</tt>, which lists
directly granted privileges. Neither <tt>acs_object_party_method_map</tt>
(which is a view) nor <tt>acs_permissions</tt> should be updated
-directly.</p>
-<p><span class="strong"><i>PL/SQL Procedures</i></span></p>
-<p>
-<tt>acs_permissions.grant_permission</tt> introduces new permissions for
-an object. It should be given an (<span class="emphasis"><i>object</i></span>, <span class="emphasis"><i>party</i></span>,
-<span class="emphasis"><i>privilege</i></span>) triple, and will always succeed. If the permission is
+directly.</p><p><span class="strong"><em>PL/SQL Procedures</em></span></p><p><tt>acs_permissions.grant_permission</tt> introduces new permissions for
+an object. It should be given an (<span class="emphasis"><em>object</em></span>, <span class="emphasis"><em>party</em></span>,
+<span class="emphasis"><em>privilege</em></span>) triple, and will always succeed. If the permission is
already in the system, no change occurs. The interface for this procedure
-is:</p>
-<pre class="programlisting">
+is:</p><pre class="programlisting">
procedure grant_permission (
object_id acs_permissions.object_id%TYPE,
grantee_id acs_permissions.grantee_id%TYPE,
privilege acs_permissions.privilege%TYPE
);
-</pre>
-<p>
-<tt>acs_permissions.revoke_permission</tt> removes a permission entry
+</pre><p><tt>acs_permissions.revoke_permission</tt> removes a permission entry
given a triple. It always succeeds--if a permission does not exist, nothing
-changes. The interface for this procedure is:</p>
-<pre class="programlisting">
+changes. The interface for this procedure is:</p><pre class="programlisting">
procedure revoke_permission (
object_id acs_permissions.object_id%TYPE,
grantee_id acs_permissions.grantee_id%TYPE,
privilege acs_permissions.privilege%TYPE
);
-</pre>
-<p>These procedures are defined in <a href="http://acs40.arsdigita.com/doc/sql/display-sql?url=acs-permissions-create.sql&package_key=acs-kernel" target="_top">
-<tt>permissions-create.sql</tt></a>
-</p>
-<p><span class="strong"><i>Tcl Procedures</i></span></p>
-<p>Two tcl procedures provide a simple call for the query, "Can this
+</pre><p>These procedures are defined in <a href="http://acs40.arsdigita.com/doc/sql/display-sql?url=acs-permissions-create.sql%26amp;package_key=acs-kernel" target="_top">
+<tt>permissions-create.sql</tt></a></p><p><span class="strong"><em>Tcl Procedures</em></span></p><p>Two tcl procedures provide a simple call for the query, "Can this
user perform this method on this object?" One returns true or false, the
-other presents an error page.</p>
-<p>To receive a true or false value, Tcl code should call:</p>
-<pre class="programlisting">
+other presents an error page.</p><p>To receive a true or false value, Tcl code should call:</p><pre class="programlisting">
ad_permission_p $object_id $object_type $method -user_id $user_id
-</pre>
-<p>If the <tt>user_id</tt> argument is left out, then the currently logged in
-user is checked. To create an error page, Tcl code should call:</p>
-<pre class="programlisting">
+</pre><p>If the <tt>user_id</tt> argument is left out, then the currently logged in
+user is checked. To create an error page, Tcl code should call:</p><pre class="programlisting">
ad_require_permission $object_id $object_type $method
-</pre>
-<p>These procedures are defined in <tt>acs-permissions-procs.tcl</tt>.</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="permissions-design-ui"></a>User Interface</h3></div></div>
-<p>All users of the permissions system are the same at the user-interface
+</pre><p>These procedures are defined in <tt>acs-permissions-procs.tcl</tt>.</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="permissions-design-ui"></a>User Interface</h3></div></div><p>All users of the permissions system are the same at the user-interface
level. If you have the <tt>administer_privileges</tt> method permission on an
-object, then you may edit privileges for that object with the UI.</p>
-<p>The UI currently provides a list of all granted permissions on the object.
+object, then you may edit privileges for that object with the UI.</p><p>The UI currently provides a list of all granted permissions on the object.
If the user wishes to revoke privileges, she may select a set of grants,
choose revoke, confirm their deletion, and be returned to the same page after
-those privileges have been revoked.</p>
-<p>Granting permissions currently (as of 10/2000) works by providing a list
+those privileges have been revoked.</p><p>Granting permissions currently (as of 10/2000) works by providing a list
of all possible permissions and a list of all parties in the system. (For
large sites, some future search mechanism will be necessary.) After choosing
privileges to grant, the user is returned to the "edit privileges for
-one object" screen.</p>
-<p>If it makes sense, the system will also display a checkbox which the user
+one object" screen.</p><p>If it makes sense, the system will also display a checkbox which the user
may select to toggle whether permissions are inherited from the object's
-context.</p>
-<p>There are a number of potential future enhancements for the permissions
-UI, outlined below.</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="permissions-design-configure"></a>Configuration/Parameters</h3></div></div>
-<p>There are no configuration options for the permissions system.</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="permissions-design-future"></a>Future Improvements/Areas of Likely Change</h3></div></div>
-<p>The most important future changes to the Permissions system are likely to
-be in the UI:</p>
-<div class="itemizedlist"><ul>
-<li><p>There should be a page displaying a list of all objects for which the
-current user is allowed to administer privileges.</p></li>
-<li><p>Users should be able to view the permissions on any object, or perhaps on
+context.</p><p>There are a number of potential future enhancements for the permissions
+UI, outlined below.</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="permissions-design-configure"></a>Configuration/Parameters</h3></div></div><p>There are no configuration options for the permissions system.</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="permissions-design-future"></a>Future Improvements/Areas of Likely Change</h3></div></div><p>The most important future changes to the Permissions system are likely to
+be in the UI:</p><div class="itemizedlist"><ul type="disc"><li><p>There should be a page displaying a list of all objects for which the
+current user is allowed to administer privileges.</p></li><li><p>Users should be able to view the permissions on any object, or perhaps on
objects which they have the "read_permissions" method. This would
allow them to see what grants are affecting their objects through
-inheritance.</p></li>
-</ul></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="permissions-design-authors"></a>Authors</h3></div></div>
-<div class="variablelist"><dl>
-<dt><span class="term">System creator
+inheritance.</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="permissions-design-authors"></a>Authors</h3></div></div><div class="variablelist"><dl><dt><span class="term">System creator
-</span></dt>
-<dd><p><a href="mailto:rhs@mit.edu" target="_top">Rafael H. Schloming</a></p></dd>
-<dt><span class="term">System owner
+</span></dt><dd><p><a href="mailto:rhs@mit.edu" target="_top">Rafael H. Schloming</a></p></dd><dt><span class="term">System owner
-</span></dt>
-<dd><p><a href="mailto:rhs@mit.edu" target="_top">Rafael H. Schloming</a></p></dd>
-<dt><span class="term">Documentation author
+</span></dt><dd><p><a href="mailto:rhs@mit.edu" target="_top">Rafael H. Schloming</a></p></dd><dt><span class="term">Documentation author
-</span></dt>
-<dd><p><a href="mailto:jmp@arsdigita.com" target="_top">John Prevost</a></p></dd>
-</dl></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="permissions-design-rev-history"></a>Revision History</h3></div></div>
-<div class="informaltable"><table border="1">
-<colgroup>
-<col>
-<col>
-<col>
-<col>
-</colgroup>
-<tbody>
-<tr>
-<td><span class="strong"><i>Document Revision #</i></span></td>
-<td><span class="strong"><i>Action Taken, Notes</i></span></td>
-<td><span class="strong"><i>When?</i></span></td>
-<td><span class="strong"><i>By Whom?</i></span></td>
-</tr>
-<tr>
-<td>0.1</td>
-<td>Creation</td>
-<td>9/11/2000</td>
-<td>John Prevost</td>
-</tr>
-<tr>
-<td>0.2</td>
-<td>Edited for ACS 4 Beta release</td>
-<td>10/04/2000</td>
-<td>Kai Wu</td>
-</tr>
-</tbody>
-</table></div>
-</div>
-</div>
-<div class="navfooter">
-<hr>
-<table width="100%" summary="Navigation footer">
-<tr>
-<td width="40%" align="left">
-<a accesskey="p" href="permissions-requirements.html">Prev</a> </td>
-<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
-<td width="40%" align="right"> <a accesskey="n" href="groups-requirements.html">Next</a>
-</td>
-</tr>
-<tr>
-<td width="40%" align="left">OpenACS 4 Permissions Requirements </td>
-<td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td>
-<td width="40%" align="right"> OpenACS 4 Groups Requirements</td>
-</tr>
-</table>
-<hr>
-<address>
- rmello at fslc.usu.edu
- </address>
-<address><a href="mailto:vinod@kurup.com">
+</span></dt><dd><p><a href="mailto:jmp@arsdigita.com" target="_top">John Prevost</a></p></dd></dl></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="permissions-design-rev-history"></a>Revision History</h3></div></div><div class="informaltable"><table border="1"><colgroup><col><col><col><col></colgroup><tbody><tr><td><span class="strong"><em>Document Revision #</em></span></td><td><span class="strong"><em>Action Taken, Notes</em></span></td><td><span class="strong"><em>When?</em></span></td><td><span class="strong"><em>By Whom?</em></span></td></tr><tr><td>0.1</td><td>Creation</td><td>9/11/2000</td><td>John Prevost</td></tr><tr><td>0.2</td><td>Edited for ACS 4 Beta release</td><td>10/04/2000</td><td>Kai Wu</td></tr></tbody></table></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="permissions-requirements.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="groups-requirements.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS 4 Permissions Requirements </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> OpenACS 4 Groups Requirements</td></tr></table><hr><address>rmello at fslc.usu.edu</address><address><a href="mailto:vinod@kurup.com">
vinod@kurup.com
- </a></address>
-</div>
-</body>
-</html>
+ </a></address></div></body></html>
Index: openacs-4/packages/acs-core-docs/www/permissions-requirements.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/permissions-requirements.html,v
diff -u -r1.5 -r1.5.2.1
--- openacs-4/packages/acs-core-docs/www/permissions-requirements.html 7 Mar 2002 06:55:36 -0000 1.5
+++ openacs-4/packages/acs-core-docs/www/permissions-requirements.html 15 May 2002 23:26:18 -0000 1.5.2.1
@@ -1,43 +1,11 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type">
-<title>OpenACS 4 Permissions Requirements</title>
-<meta name="generator" content="DocBook XSL Stylesheets V1.45">
-<link rel="home" href="index.html" title="OpenACS Documentation">
-<link rel="up" href="kernel-doc.html" title="Chapter 7. Kernel Documentation">
-<link rel="previous" href="object-system-design.html" title="OpenACS 4 Object Model Design">
-<link rel="next" href="permissions-design.html" title="OpenACS 4 Permissions Design">
-<link rel="stylesheet" href="openacs.css" type="text/css">
-</head>
-<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-<div class="navheader">
-<a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr>
-<td width="20%" align="left">
-<a accesskey="p" href="object-system-design.html">Prev</a> </td>
-<th width="60%" align="center">Chapter 7. Kernel Documentation</th>
-<td width="20%" align="right"> <a accesskey="n" href="permissions-design.html">Next</a>
-</td>
-</tr></table>
-<hr>
-</div>
-<div class="sect1">
-<div class="titlepage"><div><h2 class="title" style="clear: both">
-<a name="permissions-requirements"></a>OpenACS 4 Permissions Requirements</h2></div></div>
-<div class="authorblurb"><p>
-by <a href="mailto:jmp@arsdigita.com" target="_top">John McClary Prevost</a>
-</p></div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="permissions-requirements-intro"></a>Introduction</h3></div></div>
-<p>This document records requirements for the OpenACS 4 Permissions system, a
+<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"><title>OpenACS 4 Permissions Requirements</title><meta name="generator" content="DocBook XSL Stylesheets V1.50.0"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="kernel-doc.html" title="Chapter 7. Kernel Documentation"><link rel="previous" href="object-system-design.html" title="OpenACS 4 Object Model Design"><link rel="next" href="permissions-design.html" title="OpenACS 4 Permissions Design"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="object-system-design.html">Prev</a> </td><th width="60%" align="center">Chapter 7. Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="permissions-design.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="permissions-requirements"></a>OpenACS 4 Permissions Requirements</h2></div></div><div class="authorblurb"><p>
+by <a href="mailto:jmp@arsdigita.com" target="_top">John McClary Prevost</a><br>
+ OpenACS docs are written by the named authors, but may be edited
+ by OpenACS documentation staff.
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="permissions-requirements-intro"></a>Introduction</h3></div></div><p>This document records requirements for the OpenACS 4 Permissions system, a
component of the OpenACS 4 Kernel. The Permissions system is meant to unify and
-centralize the handling of access and control on a given OpenACS 4 system.</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="permissions-requirements-vision"></a>Vision Statement</h3></div></div>
-<p>Any multi-user software system must address the general problem of
+centralize the handling of access and control on a given OpenACS 4 system.</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="permissions-requirements-vision"></a>Vision Statement</h3></div></div><p>Any multi-user software system must address the general problem of
permissions, or "who can do what, on what." On web services, which
typically involve large numbers of users belonging to different groups,
permissions handling is a critical need: access to content, services, and
@@ -47,231 +15,80 @@
manner reduces both cost and risk: cost, in that less code has to be written
and maintained for dealing with recurring permissions situations; risk, in
that we need not rely on any single programmer's diligence to ensure
-access control is implemented and enforced correctly.</p>
-<p><span class="strong"><i>Historical Motivations</i></span></p>
-<p>In earlier versions of the OpenACS, permissions and access control was handled
+access control is implemented and enforced correctly.</p><p><span class="strong"><em>Historical Motivations</em></span></p><p>In earlier versions of the OpenACS, permissions and access control was handled
on a module-by-module basis, often even on a page-by-page basis. For example,
a typical module might allow any registered user to access its pages
read-only, but only allow members of a certain group to make changes. The way
this group was determined also varied greatly between modules. Some modules
used "roles", while others did not. Other modules did all access
control based simply on coded rules regarding who can act on a given database
-row based on the information in that row.</p>
-<p>Problems resulting from this piecemeal approach to permissions and access
+row based on the information in that row.</p><p>Problems resulting from this piecemeal approach to permissions and access
control were many, the two major ones being inconsistency, and
repeated/redundant code. Thus the drive in OpenACS 4 to provide a unified,
consistent permissions system that both programmers and administrators can
-readily use.</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="permissions-requirements-system-overview"></a>System Overview</h3></div></div>
-<p>The OpenACS 4 Permissions system has two main pieces: first, an API for
+readily use.</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="permissions-requirements-system-overview"></a>System Overview</h3></div></div><p>The OpenACS 4 Permissions system has two main pieces: first, an API for
developers to readily handle access control in their applications. The second
piece of the system is a UI meant primarily for (subsite) administrators to
-grant and revoke permissions to system entities under their control.</p>
-<p>Consistency is a key characteristic of the Permissions system - both for a
+grant and revoke permissions to system entities under their control.</p><p>Consistency is a key characteristic of the Permissions system - both for a
common administrative interface, and easily deployed and maintained access
control. The system must be flexible enough to support every access model
required in OpenACS applications, but not so flexible that pieces will go unused
-or fall outside the common administrative interfaces.</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="permissions-requirements-"></a>Use Cases and User Scenarios</h3></div></div>
-<p><span class="strong"><i>Terminology</i></span></p>
-<p>The primary question an access control system must answer is a three-way
+or fall outside the common administrative interfaces.</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="permissions-requirements-"></a>Use Cases and User Scenarios</h3></div></div><p><span class="strong"><em>Terminology</em></span></p><p>The primary question an access control system must answer is a three-way
relation, like that between the parts of most simple sentences. A simple
sentence generally has three parts, a subject, an object, and a verb - in the
context of OpenACS Permissions, our simple sentence is, "Can this party
-perform this operation on this target?" Definitions:</p>
-<p>The subject of the sentence is "<span class="strong"><i>party</i></span>" - a
+perform this operation on this target?" Definitions:</p><p>The subject of the sentence is "<span class="strong"><em>party</em></span>" - a
distinguishable actor whose access may be controlled, this special word is
used because one person may be represented by several parties, and one party
-may represent many users (or no users at all).</p>
-<p>The object of the sentence is "<span class="strong"><i>target</i></span>" - this
+may represent many users (or no users at all).</p><p>The object of the sentence is "<span class="strong"><em>target</em></span>" - this
is an entity, or object, that the party wishes to perform some action on. An
-entity/object here is anything that can be put under access control.</p>
-<p>The verb of the sentence is "operation" - a behavior on the OpenACS
+entity/object here is anything that can be put under access control.</p><p>The verb of the sentence is "operation" - a behavior on the OpenACS
system subject to control, this word is used to represent the fact that a
single operation may be part of many larger actions the system wants to
perform. If "foo" is an operation, than we sometimes refer to the
foo "privilege" to mean that a user has the privilege to perform
-that operation.</p>
-<p>Examples of the essential question addressed by the Permissions system:
+that operation.</p><p>Examples of the essential question addressed by the Permissions system:
Can jane@attacker.com delete the web security bboard? Can the Boston office
(a party) within the VirtuaCorp intranet/website create its own news
-instance?</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="permissions-requirements-links"></a>Related Links</h3></div></div>
-<div class="itemizedlist"><ul><li><p><a href="permissions-design.html">OpenACS 4 Permissions Design</a></p></li></ul></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="permissions-requirements-func-req"></a>Functional Requirements</h3></div></div>
-<p><span class="strong"><i>10.0 Granularity</i></span></p>
-<p>The system must support access control down to the level of a single
+instance?</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="permissions-requirements-links"></a>Related Links</h3></div></div><div class="itemizedlist"><ul type="disc"><li><p><a href="permissions-design.html">OpenACS 4 Permissions Design</a></p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="permissions-requirements-func-req"></a>Functional Requirements</h3></div></div><p><span class="strong"><em>10.0 Granularity</em></span></p><p>The system must support access control down to the level of a single
entity (this would imply down to the level of a row in the OpenACS Objects data
-model).</p>
-<p><span class="strong"><i>20.0 Operations</i></span></p>
-<p>The system itself must be able to answer the essential permissions
-question as well as several derived questions.</p>
-<blockquote class="blockquote">
-<p><span class="strong"><i>20.10 Basic Access Check</i></span></p>
-<p>The system must be able to answer the question, "May party P perform
-operation O on target T?"</p>
-</blockquote>
-<blockquote class="blockquote">
-<p><span class="strong"><i>20.20 Allowed Parties Check</i></span></p>
-<p>The system must be able to answer the question, "Which parties may
-perform operation O on target T?"</p>
-</blockquote>
-<blockquote class="blockquote">
-<p><span class="strong"><i>20.30 Allowed Operations Check</i></span></p>
-<p>The system must be able to answer the question, "Which operations may
-party P perform on target T?"</p>
-</blockquote>
-<blockquote class="blockquote">
-<p><span class="strong"><i>20.40 Allowed Targets Check</i></span></p>
-<p>The system must be able to answer the question, "Upon which targets
-may party P perform operation O?"</p>
-</blockquote>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="permissions-requirements-behave-req"></a>Behavioral Requirements</h3></div></div>
-<p><span class="strong"><i>40.0 Scale of Privileges</i></span></p>
-<p>Privileges must be designed with appropriate scope for a given OpenACS
+model).</p><p><span class="strong"><em>20.0 Operations</em></span></p><p>The system itself must be able to answer the essential permissions
+question as well as several derived questions.</p><blockquote class="blockquote"><p><span class="strong"><em>20.10 Basic Access Check</em></span></p><p>The system must be able to answer the question, "May party P perform
+operation O on target T?"</p></blockquote><blockquote class="blockquote"><p><span class="strong"><em>20.20 Allowed Parties Check</em></span></p><p>The system must be able to answer the question, "Which parties may
+perform operation O on target T?"</p></blockquote><blockquote class="blockquote"><p><span class="strong"><em>20.30 Allowed Operations Check</em></span></p><p>The system must be able to answer the question, "Which operations may
+party P perform on target T?"</p></blockquote><blockquote class="blockquote"><p><span class="strong"><em>20.40 Allowed Targets Check</em></span></p><p>The system must be able to answer the question, "Upon which targets
+may party P perform operation O?"</p></blockquote></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="permissions-requirements-behave-req"></a>Behavioral Requirements</h3></div></div><p><span class="strong"><em>40.0 Scale of Privileges</em></span></p><p>Privileges must be designed with appropriate scope for a given OpenACS
package. Some privileges are of general utility (e.g. "read" and
"write"). Others are of more limited use (e.g. "moderate"
- applies mainly to a package like bboard, where many users are contributing
content simultaneously). A package defining its own privileges should do so
with moderation, being careful not to overload a privilege like
-"read" to mean too many things.</p>
-<p><span class="strong"><i>50.0 Aggregation of Operations (Privileges)</i></span></p>
-<p>For user interface purposes, it can be appropriate to group certain
+"read" to mean too many things.</p><p><span class="strong"><em>50.0 Aggregation of Operations (Privileges)</em></span></p><p>For user interface purposes, it can be appropriate to group certain
privileges under others. For example, anyone with the "admin"
privilege may also automatically receive "read", "write",
-"delete", etc. privileges.</p>
-<p><span class="strong"><i>60.0 Aggregation of Parties (Groups)</i></span></p>
-<p>The system must allow aggregation of parties. The exact method used for
+"delete", etc. privileges.</p><p><span class="strong"><em>60.0 Aggregation of Parties (Groups)</em></span></p><p>The system must allow aggregation of parties. The exact method used for
aggregation will probably be addressed by the OpenACS 4 "Groups"
system. Regardless of the exact behavior of aggregate parties, if an
aggregate party exists, then access which is granted to the aggregate party
-should be available to all members of that aggregate.</p>
-<p><span class="strong"><i>70.0 Scope of Access Control</i></span></p>
-<blockquote class="blockquote">
-<p><span class="strong"><i>70.10 Context</i></span></p>
-<p>There must be a method for objects to receive default access control from
+should be available to all members of that aggregate.</p><p><span class="strong"><em>70.0 Scope of Access Control</em></span></p><blockquote class="blockquote"><p><span class="strong"><em>70.10 Context</em></span></p><p>There must be a method for objects to receive default access control from
some context. For example, if you do not have read access to a bboard, you
-should not have read access to a message in that bboard.</p>
-</blockquote>
-<blockquote class="blockquote">
-<p><span class="strong"><i>70.20 Overriding</i></span></p>
-<p>It must be possible to override defaults provided by the context of an
-object (as in 70.10), in both a positive and negative manner.</p>
-</blockquote>
-<blockquote class="blockquote">
-<p><span class="strong"><i>70.20.10 Positive Overriding</i></span></p>
-<p>It must be possible to allow a party more access to some target than they
+should not have read access to a message in that bboard.</p></blockquote><blockquote class="blockquote"><p><span class="strong"><em>70.20 Overriding</em></span></p><p>It must be possible to override defaults provided by the context of an
+object (as in 70.10), in both a positive and negative manner.</p></blockquote><blockquote class="blockquote"><p><span class="strong"><em>70.20.10 Positive Overriding</em></span></p><p>It must be possible to allow a party more access to some target than they
would get by default. (For example, a user does not have the right to edit
any message on a bboard. But a user does possibly have the right to edit
-their own messages.)</p>
-</blockquote>
-<blockquote class="blockquote">
-<p><span class="strong"><i>70.20.20 Negative Overriding</i></span></p>
-<p>It must be possible to deny a party access to some target that their
+their own messages.)</p></blockquote><blockquote class="blockquote"><p><span class="strong"><em>70.20.20 Negative Overriding</em></span></p><p>It must be possible to deny a party access to some target that their
inherited privileges would have allowed. (For example, a subdirectory in the
file-storage might normally have its parent directory as context. It should
-be possible, however, to make a subdirectory private to some group.)</p>
-</blockquote>
-<p><span class="strong"><i>100.0 Efficiency</i></span></p>
-<p>At least the basic access check (20.10) and the allowed targets check
+be possible, however, to make a subdirectory private to some group.)</p></blockquote><p><span class="strong"><em>100.0 Efficiency</em></span></p><p>At least the basic access check (20.10) and the allowed targets check
(20.40) must be efficient enough for general use, i.e. scalable under fairly
heavy website traffic. It can be expected that almost every page will contain
at least one basic access check, and most pages will contain an allowed
-targets check (20.40).</p>
-<p>In particular, constraining a <tt>SELECT</tt> to return only rows the
+targets check (20.40).</p><p>In particular, constraining a <tt>SELECT</tt> to return only rows the
current user has access to should not be much slower than the <tt>SELECT</tt>
-on its own.</p>
-<p><span class="strong"><i>120.0 Ease of Use</i></span></p>
-<p>Since most SQL queries will contain an allowed target check in the where
+on its own.</p><p><span class="strong"><em>120.0 Ease of Use</em></span></p><p>Since most SQL queries will contain an allowed target check in the where
clause, whatever mechanism is used to make checks in SQL should be fairly
-small and simple.</p>
-<p>In particular, constraining a <tt>SELECT</tt> to return only rows the
-current user has access to should not add more than one line to a query.</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="permissions-requirements-history"></a>Revision History</h3></div></div>
-<div class="informaltable"><table border="1">
-<colgroup>
-<col>
-<col>
-<col>
-<col>
-</colgroup>
-<tbody>
-<tr>
-<td><span class="strong"><i>Document Revision #</i></span></td>
-<td><span class="strong"><i>Action Taken, Notes</i></span></td>
-<td><span class="strong"><i>When?</i></span></td>
-<td><span class="strong"><i>By Whom?</i></span></td>
-</tr>
-<tr>
-<td>0.1</td>
-<td>Creation</td>
-<td>8/17/2000</td>
-<td>John Prevost</td>
-</tr>
-<tr>
-<td>0.2</td>
-<td>Revised, updated with new terminology</td>
-<td>8/25/2000</td>
-<td>John Prevost</td>
-</tr>
-<tr>
-<td>0.3</td>
-<td>Edited, reformatted to conform to requirements template, pending
-freeze.</td>
-<td>8/26/2000</td>
-<td>Kai Wu</td>
-</tr>
-<tr>
-<td>0.4</td>
-<td>Edited for ACS 4 Beta release.</td>
-<td>10/03/2000</td>
-<td>Kai Wu</td>
-</tr>
-</tbody>
-</table></div>
-</div>
-</div>
-<div class="navfooter">
-<hr>
-<table width="100%" summary="Navigation footer">
-<tr>
-<td width="40%" align="left">
-<a accesskey="p" href="object-system-design.html">Prev</a> </td>
-<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
-<td width="40%" align="right"> <a accesskey="n" href="permissions-design.html">Next</a>
-</td>
-</tr>
-<tr>
-<td width="40%" align="left">OpenACS 4 Object Model Design </td>
-<td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td>
-<td width="40%" align="right"> OpenACS 4 Permissions Design</td>
-</tr>
-</table>
-<hr>
-<address>
- rmello at fslc.usu.edu
- </address>
-<address><a href="mailto:vinod@kurup.com">
+small and simple.</p><p>In particular, constraining a <tt>SELECT</tt> to return only rows the
+current user has access to should not add more than one line to a query.</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="permissions-requirements-history"></a>Revision History</h3></div></div><div class="informaltable"><table border="1"><colgroup><col><col><col><col></colgroup><tbody><tr><td><span class="strong"><em>Document Revision #</em></span></td><td><span class="strong"><em>Action Taken, Notes</em></span></td><td><span class="strong"><em>When?</em></span></td><td><span class="strong"><em>By Whom?</em></span></td></tr><tr><td>0.1</td><td>Creation</td><td>8/17/2000</td><td>John Prevost</td></tr><tr><td>0.2</td><td>Revised, updated with new terminology</td><td>8/25/2000</td><td>John Prevost</td></tr><tr><td>0.3</td><td>Edited, reformatted to conform to requirements template, pending
+freeze.</td><td>8/26/2000</td><td>Kai Wu</td></tr><tr><td>0.4</td><td>Edited for ACS 4 Beta release.</td><td>10/03/2000</td><td>Kai Wu</td></tr></tbody></table></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="object-system-design.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="permissions-design.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS 4 Object Model Design </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> OpenACS 4 Permissions Design</td></tr></table><hr><address>rmello at fslc.usu.edu</address><address><a href="mailto:vinod@kurup.com">
vinod@kurup.com
- </a></address>
-</div>
-</body>
-</html>
+ </a></address></div></body></html>
Index: openacs-4/packages/acs-core-docs/www/permissions.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/permissions.html,v
diff -u -r1.7 -r1.7.2.1
--- openacs-4/packages/acs-core-docs/www/permissions.html 7 Mar 2002 06:55:36 -0000 1.7
+++ openacs-4/packages/acs-core-docs/www/permissions.html 15 May 2002 23:26:18 -0000 1.7.2.1
@@ -1,68 +1,34 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type">
-<title>Groups, Context, Permissions</title>
-<meta name="generator" content="DocBook XSL Stylesheets V1.45">
-<link rel="home" href="index.html" title="OpenACS Documentation">
-<link rel="up" href="dev-guide.html" title="Chapter 4. OpenACS Developer's Guide">
-<link rel="previous" href="templates.html" title="Using Templates in OpenACS 4.5">
-<link rel="next" href="subsites.html" title="Writing OpenACS 4.5 Application Pages">
-<link rel="stylesheet" href="openacs.css" type="text/css">
-</head>
-<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-<div class="navheader">
-<a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr>
-<td width="20%" align="left">
-<a accesskey="p" href="templates.html">Prev</a> </td>
-<th width="60%" align="center">Chapter 4. OpenACS Developer's Guide</th>
-<td width="20%" align="right"> <a accesskey="n" href="subsites.html">Next</a>
-</td>
-</tr></table>
-<hr>
-</div>
-<div class="sect1">
-<div class="titlepage"><div><h2 class="title" style="clear: both">
-<a name="permissions"></a>Groups, Context, Permissions</h2></div></div>
-<div class="authorblurb"><p>By <a href="mailto:psu@arsdigita.com" target="_top">Pete Su</a>
-</p></div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="permissions-overview"></a>Overview</h3></div></div>
-<p>
+<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"><title>Groups, Context, Permissions</title><meta name="generator" content="DocBook XSL Stylesheets V1.50.0"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="dev-guide.html" title="Chapter 4. OpenACS Developer's Guide"><link rel="previous" href="templates.html" title="Using Templates in OpenACS 4.5"><link rel="next" href="subsites.html" title="Writing OpenACS 4.5 Application Pages"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="templates.html">Prev</a> </td><th width="60%" align="center">Chapter 4. OpenACS Developer's Guide</th><td width="20%" align="right"> <a accesskey="n" href="subsites.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="permissions"></a>Groups, Context, Permissions</h2></div></div><div class="authorblurb"><p><p>By <a href="mailto:psu@arsdigita.com" target="_top">Pete Su</a></p><br>
+ OpenACS docs are written by the named authors, but may be edited
+ by OpenACS documentation staff.
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="permissions-overview"></a>Overview</h3></div></div><p>
The OpenACS 4.5 Permissions system allows developers and administrators to
set access control policies at the object level, that is, any
application or system object represented by a row in the
<tt>acs_objects</tt> table can be access-controlled via a simple
PL/SQL or Tcl interface. The permissions system manages a data model
that then allows scripts to check permissions using another simple
API call.
-</p>
-<p>
+</p><p>
Although this may all sound easy and wonderful, no developer or
-administrator would want to <span class="emphasis"><i>explicitly</i></span> set access control
-rights for <span class="emphasis"><i>every user</i></span> and <span class="emphasis"><i>every object</i></span> on a
+administrator would want to <span class="emphasis"><em>explicitly</em></span> set access control
+rights for <span class="emphasis"><em>every user</em></span> and <span class="emphasis"><em>every object</em></span> on a
site. Therefore, OpenACS 4.5 has two auxiliary mechanisms for making this
easier: First, the Groups system allows users to be grouped together
in flexible ways. Second, the object model defines a notion of
-<span class="emphasis"><i>object context</i></span>, which allows applications to group objects
+<span class="emphasis"><em>object context</em></span>, which allows applications to group objects
together into larger security domains. The rest of this document will
talk about each of these parts, and how they fit together with the
permissions system.
-</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="permissions-groups"></a>Groups</h3></div></div>
-<p>
+</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="permissions-groups"></a>Groups</h3></div></div><p>
In OpenACS 3.x, the groups system allowed developers and administrators to
define simple groupings of users. Each group had a human readable name
and unique ID, and there was a single mapping table that mapped users
to groups. (The actual data model was more complicated because it
contained a meta-data system much like the OpenACS 4.5 object type system,
but that's not relevant right now.)
-</p>
-<p>
+</p><p>
The 3.x groups system, while very useful, was limited in few ways. The
main limitation: groups could not either contain or include other
groups. You could not express the fact that all the members of group A
@@ -72,8 +38,7 @@
employees. Obviously, you'd want every member of an office employee
group to automatically be a member of the whole company employee
group.
-</p>
-<p>
+</p><p>
In OpenACS 3.x, you also could not express the fact that group A should
itself be a member of group B, without also implying that all of its
members are also members of B. This type of relationship also comes up
@@ -82,29 +47,25 @@
and organizations: although the Sierra Club may be an organization
member of Greenpeace, its members are not necessarily members of
Greenpeace.
-</p>
-<p>
+</p><p>
OpenACS 4.5 solves both of these modeling problems by introducing a new
-abstraction called a <span class="emphasis"><i>party</i></span>. Parties have a recursive
+abstraction called a <span class="emphasis"><em>party</em></span>. Parties have a recursive
definition, and we can illustrate how it works with the following
simplified data model. First, we define the <tt>parties</tt>
table, where each party has an email address and a URL for contact
information.
-</p>
-<pre class="programlisting">
+</p><pre class="programlisting">
create table parties (
party_id integer not null references acs_objects(object_id),
email varchar(100),
url varchar(100)
)
-</pre>
-<p>
+</pre><p>
Now we define two subtypes of party, one for persons, and one for
groups:
-</p>
-<pre class="programlisting">
+</p><pre class="programlisting">
create table groups (
group_id not null references parties(party_id),
@@ -117,49 +78,38 @@
last_name varchar(100) not null
)
-</pre>
-<p>
+</pre><p>
The <tt>users</tt> table is also defined in this data model as a
subtype of <tt>person</tt>. It contains many of the basic columns
that the old OpenACS 3.x <tt>users</tt> table contained.
-</p>
-<p>
-Finally, we define two relations, one for group <span class="emphasis"><i>membership</i></span> and
-one for group <span class="emphasis"><i>composition</i></span>. The composition relation allows us
+</p><p>
+Finally, we define two relations, one for group <span class="emphasis"><em>membership</em></span> and
+one for group <span class="emphasis"><em>composition</em></span>. The composition relation allows us
to express the fact that every member of group A should also be a
member of group B. This relation allows us to define a hierarchy of
groups instead of the simple flat groups that 3.x allowed.
-</p>
-<p>
+</p><p>
The membership relation is much like the mapping we had in 3.x, except
-that it maps groups to <span class="emphasis"><i>parties</i></span> instead of groups to users. What
+that it maps groups to <span class="emphasis"><em>parties</em></span> instead of groups to users. What
this means is that each member of a group is a party rather than just
a user. That is, groups consist of members that are either a person or
an entire group. This allows us to say that group A should be a
member of another group B.
-</p>
-<p>
+</p><p>
The groups data model is pleasantly recursive. The fact that parties
are modeled as being either a person or a group has a lot of power,
allowing us to model complex hierarchical groupings of persons and
groups that were hard or impossible to model in 3.x.
-</p>
-<p>
+</p><p>
The full details of the groups data model is beyond the scope of this
tutorial - I've just given you what you need to understand how
permissions work. For further detail, you can look at <a href="parties.html">Parties in OpenACS 4</a> or <a href="groups-design.html">OpenACS 4 Groups Design</a>.
-</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="permissions-permissions"></a>Permissions</h3></div></div>
-<p>
+</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="permissions-permissions"></a>Permissions</h3></div></div><p>
The permissions data model is actually pretty simple. The data model
-is a mapping between <span class="emphasis"><i>privileges</i></span>, parties and objects. We
+is a mapping between <span class="emphasis"><em>privileges</em></span>, parties and objects. We
already know what parties and objects are, but we don't know what
privileges are.
-</p>
-<p>
+</p><p>
In OpenACS 4.5, a privilege models the right to perform some operation on
some object. They are the basic units out of which we build access
control policies. For example, in the Unix filesystem we typically
@@ -173,8 +123,7 @@
automatically granted all the child privileges that the privilege
contains. The OpenACS 4.5 kernel data model actually defines these
privileges as follows:
-</p>
-<pre class="programlisting">
+</p><pre class="programlisting">
begin
acs_privilege.create_privilege('read');
@@ -191,94 +140,44 @@
commit;
end;
-</pre>
-<p>
+</pre><p>
To give a user permission to perform a particular operation on a
particular object you call
<tt>acs_permission.grant_permission</tt> like this:
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
acs_permission.grant_permission (
object_id => some_object_id,
grantee_id => some_party_id,
privilege => 'some_privilege_name'
);
-</pre>
-<p>
+</pre><p>
Using just these mechanisms is enough for developers and
administrators to effectively define access control for every object
in a system. But it would be tedious to explicitly attach permissions
to every object individually: in many cases, we'd prefer controlling
permissions to large groups of objects in the site, all at once. We
use contexts to achieve this goal.
-</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="permissions-object-context"></a>Object Context</h3></div></div>
-<p>
+</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="permissions-object-context"></a>Object Context</h3></div></div><p>
In OpenACS 4.5, an object context is a generalization of the scoping
mechanism introduced in OpenACS 3.x. "Scoping" and "scope" are terms best
explained by example: consider some hypothetical rows in the
<tt>address_book</tt> table:
-</p>
-<blockquote class="blockquote"><div class="informaltable"><table border="1">
-<colgroup>
-<col>
-<col>
-<col>
-<col>
-<col>
-</colgroup>
-<thead><tr>
-<th>...</th>
-<th><tt>scope</tt></th>
-<th><tt>user_id</tt></th>
-<th><tt>group_id</tt></th>
-<th>...</th>
-</tr></thead>
-<tbody>
-<tr>
-<td>...</td>
-<td><tt>user</tt></td>
-<td><tt>123</tt></td>
-<td>�</td>
-<td>...</td>
-</tr>
-<tr>
-<td>...</td>
-<td><tt>group</tt></td>
-<td>�</td>
-<td><tt>456</tt></td>
-<td>...</td>
-</tr>
-<tr>
-<td>...</td>
-<td><tt>public</tt></td>
-<td>�</td>
-<td>�</td>
-<td>...</td>
-</tr>
-</tbody>
-</table></div></blockquote>
-<p>
+</p><blockquote class="blockquote"><div class="informaltable"><table border="1"><colgroup><col><col><col><col><col></colgroup><thead><tr><th>...</th><th><tt>scope</tt></th><th><tt>user_id</tt></th><th><tt>group_id</tt></th><th>...</th></tr></thead><tbody><tr><td>...</td><td><tt>user</tt></td><td><tt>123</tt></td><td>�</td><td>...</td></tr><tr><td>...</td><td><tt>group</tt></td><td>�</td><td><tt>456</tt></td><td>...</td></tr><tr><td>...</td><td><tt>public</tt></td><td>�</td><td>�</td><td>...</td></tr></tbody></table></div></blockquote><p>
The first row represents an entry in User 123's personal address book,
the second row represents an entry in User Group 456's shared address
book, and the third row represents an entry in the site's public
address book.
-</p>
-<p>
+</p><p>
In this way, the scoping columns identify the security context in
-which a given object belongs, where each context is <span class="emphasis"><i>either</i></span> a
-person <span class="emphasis"><i>or</i></span> a group of people <span class="emphasis"><i>or</i></span> the general public
+which a given object belongs, where each context is <span class="emphasis"><em>either</em></span> a
+person <span class="emphasis"><em>or</em></span> a group of people <span class="emphasis"><em>or</em></span> the general public
(itself a group of people).
-</p>
-<p>
+</p><p>
In OpenACS 4.5, rather than breaking the world into a limited set of scopes,
-every object lives in a single <span class="emphasis"><i>context</i></span>. A context is just an
+every object lives in a single <span class="emphasis"><em>context</em></span>. A context is just an
another object that represents the security domain to which the object
belongs. By convention, if an object A doesn't have any permissions
explicitly attached to it, then the system will look at the
@@ -290,8 +189,7 @@
through the context happens, otherwise it does not. You might set this
field to <tt>'f'</tt> if you want to override the default
permissions in a subtree of some context.
-</p>
-<p> A good example of how to use this hierarchy is in the bboard
+</p><p> A good example of how to use this hierarchy is in the bboard
application. With only row-level permissions it is not obvious how to
reasonably initialize the access control list when creating a
message. At best, we have to explicitly grant various read and write
@@ -304,15 +202,12 @@
checks permissions on the message's context. To allow the creator of
the message to change the message after it has been posted we grant
the user write-access on the message, and we are done.
-</p>
-<p>
+</p><p>
This mechanism allows developers and administrators to define a
hierarchy that matches the structure they need for access control in
their application. The following picture shows a typical context
hierarchy for a hypothetical site:
-</p>
-<blockquote class="blockquote"><p><img src="images/context-hierarchy.jpg"></p></blockquote>
-<p>
+</p><blockquote class="blockquote"><p><img src="images/context-hierarchy.jpg"></p></blockquote><p>
A few things to note here. First, the top two contexts in the picture
are "magic" in some sense because they are created by default by OpenACS
for a specific purpose. The object <tt>default_context</tt>
@@ -325,33 +220,25 @@
some object has no permissions attached to it, and its value for
<tt>security_inherit_p</tt> is <tt>'f'</tt>, or
<tt>context_id</tt> is null, then we use this context by default.
-</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="permissions-example"></a>Example</h3></div></div>
-<p>
+</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="permissions-example"></a>Example</h3></div></div><p>
At this point, you should either go and download the Notes example
code from the package repository, or check it out of the ArsDigita CVS
repository and add it to your server. The package is called
"notes". To check it out from CVS, read the <a href="http://acs40.arsdigita.com/acs40-project-central/client-build.html" target="_top">these instructions</a> on how to use anonymous checkouts and then
checkout the module <tt>acs-packages/notes</tt>:
-</p>
-<pre class="programlisting">
+</p><pre class="programlisting">
% export CVSROOT=:pserver:anonymous@cvs.arsdigita.com:/usr/local/cvsroot
% cvs login # the password is acsrules
% cvs checkout acs-packages/notes
-</pre>
-<p>
+</pre><p>
After you have downloaded the package, look at the
<tt>index.tcl</tt> page in the <tt>www</tt> directory. You can also
-look at the code <a href="http://cvs.arsdigita.com/cgi-bin/cvsweb.pl/acs-packages/notes/www/index.tcl?rev=1.3&content-type=text/x-cvsweb-markup" target="_top">in your browser</a>. The code should look something like this:
-</p>
-<pre class="programlisting">
+look at the code <a href="http://cvs.arsdigita.com/cgi-bin/cvsweb.pl/acs-packages/notes/www/index.tcl?rev=1.3%26amp;content-type=text/x-cvsweb-markup" target="_top">in your browser</a>. The code should look something like this:
+</p><pre class="programlisting">
# main index page for notes.
@@ -396,46 +283,39 @@
ad_return_template
-</pre>
-<p>
+</pre><p>
This example shows both the Tcl and PL/SQL APIs for checking
permissions. The Tcl proc <tt>ad_permission_p</tt> and the PL/SQL
function <tt>acs_permission.permission_p</tt> both return a flag
indicating whether the current user has permission to perform the
given action. By default, the Tcl procedure extracts the user_id out
of the request environment, while the SQL procedure takes it as an
argument.
-</p>
-<p>
+</p><p>
It also shows how we display more complicated items using the template
-system. The code here creates a <span class="emphasis"><i>multirow</i></span> data source, i.e. a
+system. The code here creates a <span class="emphasis"><em>multirow</em></span> data source, i.e. a
data source that represents a query returning multiple rows from the
database. For each row, we return the ID of the note, the ID of the
owner of the note, the title, the body and then three flags that
indicate whether the user has write, admin, and delete
privileges. Also, the WHERE clause of the query ensures that we only
see notes that we are allowed to see.
-</p>
-<p>
-Next, look at the <a href="http://cvs.arsdigita.com/cgi-bin/cvsweb.pl/acs-packages/notes/www/index.adp?rev=1.1&content-type=text/x-cvsweb-markup" target="_top">index.adp</a>. It is pretty complicated.
+</p><p>
+Next, look at the <a href="http://cvs.arsdigita.com/cgi-bin/cvsweb.pl/acs-packages/notes/www/index.adp?rev=1.1%26amp;content-type=text/x-cvsweb-markup" target="_top">index.adp</a>. It is pretty complicated.
The main part of this page uses a <tt>multiple</tt> template
tag. If you want to experiment, you can replace the main body of the
<tt>multiple</tt> tag with this:
-</p>
-<pre class="programlisting">
+</p><pre class="programlisting">
<multiple name=notes>
<td>@notes.title@</td><td>@notes.body</td>
</multiple>
-</pre>
-<p>
+</pre><p>
This will just make a table with one note per row.
-</p>
-<p>
+</p><p>
Now put the more complex code back. You'll notice a lot of stuff like this:
-</p>
-<pre class="programlisting">
+</p><pre class="programlisting">
<if @notes.write_p@ eq 1>
<a href=add-edit?note_id=@notes.note_id@>@notes.title@</a>
@@ -444,14 +324,12 @@
@notes.title@
</else>
-</pre>
-<p>
+</pre><p>
This displays the title of the note as either a link or plain text
depending on whether or not we have write privileges on the object.
The <tt>if</tt> tag is something that the OpenACS 4.5 template system
defines for you to support conditional presentation. The <a href="/doc/acs-templating/developer-guide.html" target="_top">templates developer guide</a> provides more information about this.
-</p>
-<p>
+</p><p>
If you study the rest of the system, you will also notice that the
notes application doesn't explicitly attach privileges to the objects
it creates. All privileges are inherited from the context of the object
@@ -462,50 +340,17 @@
implement a user interface that allowed the user to explicitly attach
permissions to notes that she wanted to make public or whatever. But
that's beyond the scope of this example.
-</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="permissions-summary"></a>Summary</h3></div></div>
-<p>
+</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="permissions-summary"></a>Summary</h3></div></div><p>
OpenACS 4.5 defines three separate mechanisms for specifying access control
in applications. The Groups data model allows you to define
hierarchical organizations of users and groups of users. The Permissions
data model allows you to define a hierarchy of user rights. Finally,
the Context hierarchy allows you to define organize default
permissions in a hierarchical fashion. A simple PL/SQL or Tcl API is
then used to do access control checks in application pages.
-</p>
-<p>
+</p><p>
In the next section, we'll look at a more complex page for adding and
editing notes, and discuss these issues further.
-</p>
-<p><div class="cvstag">($Id$)</div></p>
-</div>
-</div>
-<div class="navfooter">
-<hr>
-<table width="100%" summary="Navigation footer">
-<tr>
-<td width="40%" align="left">
-<a accesskey="p" href="templates.html">Prev</a> </td>
-<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
-<td width="40%" align="right"> <a accesskey="n" href="subsites.html">Next</a>
-</td>
-</tr>
-<tr>
-<td width="40%" align="left">Using Templates in OpenACS 4.5 </td>
-<td width="20%" align="center"><a accesskey="u" href="dev-guide.html">Up</a></td>
-<td width="40%" align="right"> Writing OpenACS 4.5 Application Pages</td>
-</tr>
-</table>
-<hr>
-<address>
- rmello at fslc.usu.edu
- </address>
-<address><a href="mailto:vinod@kurup.com">
+</p><p><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="templates.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="subsites.html">Next</a></td></tr><tr><td width="40%" align="left">Using Templates in OpenACS 4.5 </td><td width="20%" align="center"><a accesskey="u" href="dev-guide.html">Up</a></td><td width="40%" align="right"> Writing OpenACS 4.5 Application Pages</td></tr></table><hr><address>rmello at fslc.usu.edu</address><address><a href="mailto:vinod@kurup.com">
vinod@kurup.com
- </a></address>
-</div>
-</body>
-</html>
+ </a></address></div></body></html>
Index: openacs-4/packages/acs-core-docs/www/postgres.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/postgres.html,v
diff -u -r1.5 -r1.5.2.1
--- openacs-4/packages/acs-core-docs/www/postgres.html 7 Mar 2002 06:55:36 -0000 1.5
+++ openacs-4/packages/acs-core-docs/www/postgres.html 15 May 2002 23:26:18 -0000 1.5.2.1
@@ -1,61 +1,28 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type">
-<title>Install PostgreSQL 7.1.3</title>
-<meta name="generator" content="DocBook XSL Stylesheets V1.45">
-<link rel="home" href="index.html" title="OpenACS Documentation">
-<link rel="up" href="unix-install.html" title="Chapter 2. Installing on Unix/Linux">
-<link rel="previous" href="oracle.html" title="Install Oracle 8.1.7">
-<link rel="next" href="aolserver.html" title="Install AOLserver 3.3+ad13">
-<link rel="stylesheet" href="openacs.css" type="text/css">
-</head>
-<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-<div class="navheader">
-<a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr>
-<td width="20%" align="left">
-<a accesskey="p" href="oracle.html">Prev</a> </td>
-<th width="60%" align="center">Chapter 2. Installing on Unix/Linux</th>
-<td width="20%" align="right"> <a accesskey="n" href="aolserver.html">Next</a>
-</td>
-</tr></table>
-<hr>
-</div>
-<div class="sect1">
-<div class="titlepage"><div><h2 class="title" style="clear: both">
-<a name="postgres"></a>Install PostgreSQL 7.1.3</h2></div></div>
-<p>
+<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"><title>Install PostgreSQL 7.1.3</title><meta name="generator" content="DocBook XSL Stylesheets V1.50.0"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="unix-install.html" title="Chapter 2. Installing on Unix/Linux"><link rel="previous" href="oracle.html" title="Install Oracle 8.1.7"><link rel="next" href="aolserver.html" title="Install AOLserver 3.3+ad13"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="oracle.html">Prev</a> </td><th width="60%" align="center">Chapter 2. Installing on Unix/Linux</th><td width="20%" align="right"> <a accesskey="n" href="aolserver.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="postgres"></a>Install PostgreSQL 7.1.3</h2></div></div><div class="authorblurb"><p>
+ by <a href="mailto:vinod@kurup.com" target="_top">Vinod Kurup</a><br>
+ OpenACS docs are written by the named authors, but may be edited
+ by OpenACS documentation staff.
+ </p></div><p>
Skip this page if you're not interested in PostgreSQL.
- </p>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="install-postgres-download"></a>Download the PostgreSQL source</h3></div></div>
-<p>
+ </p><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="install-postgres-download"></a>Download the PostgreSQL source</h3></div></div><p>
Download PostgreSQL 7.1.3 from the mirror closest to you. The list of
mirrors is at <a href="http://www.postgresql.org/" target="_top">http://www.postgresql.org</a>. Download
it to <tt>/tmp</tt>.
- </p>
-<p>
+ </p><p>
As <tt>root</tt>, unpack it into
<tt>/usr/local/src</tt>
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
joeuser:~$ su -
Password: ***********
root:~# cd /usr/local/src
-root:/usr/local/src# tar xzf /tmp/postgresql-7.1.3.tar.gz</pre>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="install-postgres-user"></a>Create the Postgres user</h3></div></div>
-<p>
+root:/usr/local/src# tar xzf /tmp/postgresql-7.1.3.tar.gz</pre></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="install-postgres-user"></a>Create the Postgres user</h3></div></div><p>
Still as <tt>root</tt>, create a user and
group (if you haven't done so before) for PostgreSQL. This is the
account that PostgreSQL will run as since it will not run as
root. Also give the <tt>postgres</tt> user a
password:
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
root:~# groupadd web
root:~# useradd -g web -d /usr/local/pgsql postgres
root:~# passwd postgres
@@ -66,38 +33,25 @@
root:~# exit
logout
joeuser:~$ su - postgres
-Password: ***********</pre>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="install-postgres-env"></a>Set up postgres's environment variables</h3></div></div>
-<p>
+Password: ***********</pre></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="install-postgres-env"></a>Set up postgres's environment variables</h3></div></div><p>
Edit <tt>/usr/local/pgsql/.bash_profile</tt>
so it looks like this:
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/pgsql/lib
PATH=$PATH:/usr/local/pgsql/bin
-export PATH LD_LIBRARY_PATH</pre>
-<p>
+export PATH LD_LIBRARY_PATH</pre><p>
Logout and login again as <tt>postgres</tt>. Use the
<tt>echo</tt> command to make sure that
<tt>/usr/local/pgsql/bin</tt> is now in your
PATH
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
postgres:~$ exit
logout
joeuser:~$ su - postgres
Password: ************
postgres:~$ echo $PATH
-/usr/local/bin:/usr/bin:/bin: ... :/usr/local/pgsql/bin</pre>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="install-postgres-compile"></a>Compile and install PostgreSQL</h3></div></div>
-<p>
+/usr/local/bin:/usr/bin:/bin: ... :/usr/local/pgsql/bin</pre></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="install-postgres-compile"></a>Compile and install PostgreSQL</h3></div></div><p>
First, we run <tt>./configure</tt> to set the
compilation options automatically. This is the point at which you can
configure PostgreSQL in various ways. For example, if you want to
@@ -106,70 +60,46 @@
<tt>--enable-multibyte</tt>. If you want to
see what the other possibilities are, run <tt>./configure
--help</tt>.
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
postgres:~$ cd /usr/local/src/postgresql-7.1.3
postgres:/usr/local/src/postgresql-7.1.3$ ./configure
-postgres:/usr/local/src/postgresql-7.1.3$ make all</pre>
-<p>
+postgres:/usr/local/src/postgresql-7.1.3$ make all</pre><p>
Compilation will take a while (about 10 minutes). Once it's done, you
will see the following message:
- </p>
-<pre class="programlisting">
-All of PostgreSQL is successfully made. Ready to install.</pre>
-<p>
+ </p><pre class="programlisting">
+All of PostgreSQL is successfully made. Ready to install.</pre><p>
Next, we'll install PostgreSQL. If all is successful, you'll see the
following “Thank You” message.
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
postgres:/usr/local/src/postgresql-7.1.3$ make install
...
-Thank you for choosing PostgreSQL, the most advanced open source database engine.</pre>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="install-postgres-openfts"></a>Prepare PostgreSQL for OpenFTS</h3></div></div>
-<p>
+Thank you for choosing PostgreSQL, the most advanced open source database engine.</pre></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="install-postgres-openfts"></a>Prepare PostgreSQL for OpenFTS</h3></div></div><p>
OpenFTS is the module that provides full text search to OpenACS 4.5. We
won't be installing it until later, but we'll set up a couple things
that are best done right now.
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
postgres:/usr/local/src/postgresql-7.1.3$ make install-all-headers
postgres:/usr/local/src/postgresql-7.1.3$ cd contrib/intarray
postgres:/usr/local/src/postgresql-7.1.3/contrib/intarray$ make
-postgres:/usr/local/src/postgresql-7.1.3/contrib/intarray$ make install</pre>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="install-postgres-startup"></a>Start PostgreSQL</h3></div></div>
-<p>The <tt>initdb</tt> command initializes
+postgres:/usr/local/src/postgresql-7.1.3/contrib/intarray$ make install</pre></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="install-postgres-startup"></a>Start PostgreSQL</h3></div></div><p>The <tt>initdb</tt> command initializes
the database. <tt>pg_ctl</tt> is used to
start up PostgreSQL.
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
postgres:/usr/local/src/postgresql-7.1.3/contrib/intarray$ cd
postgres:~$ /usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
postgres:~$ /usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data -l /usr/local/pgsql/data/server.log start
-postmaster successfully started</pre>
-<p>
+postmaster successfully started</pre><p>
PostgreSQL errors will be logged in
<tt>/usr/local/pgsql/data/server.log</tt>
- </p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="install-postgres-plpgsql"></a>Set up plpgsql and allow nsadmin access</h3></div></div>
-<p>
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="install-postgres-plpgsql"></a>Set up plpgsql and allow nsadmin access</h3></div></div><p>
We have to install plpgsql into our PostgreSQL installation so that
we can use stored procedures. Fortunately, it's pretty easy. We'll
also create a database user named
<tt>nsadmin</tt>, so that aolserver can
access the database. (Don't worry that you don't have a
<tt>nsadmin</tt> user yet - we'll create that
in the next chapter.)
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
postgres:~$ createlang plpgsql template1
postgres:~$ # Test if we succeeded
postgres:~$ createlang -l template1
@@ -181,16 +111,10 @@
postgres:~$ createuser nsadmin
Shall the new user be allowed to create databases? (y/n) y
Shall the new user be allowed to create more new users? (y/n) y
-CREATE USER</pre>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="install-postgres-test"></a>Test PostgreSQL</h3></div></div>
-<p>
+CREATE USER</pre></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="install-postgres-test"></a>Test PostgreSQL</h3></div></div><p>
Create a database and try some simple commands. The output should be
as shown.
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
postgres:~$ createdb mytestdb
CREATE DATABASE
postgres:~$ psql mytestdb
@@ -218,35 +142,22 @@
mytestdb=# \q
postgres:~$ dropdb mytestdb
-DROP DATABASE</pre>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="install-postgres-startonboot"></a>Getting PostgreSQL to start on boot</h3></div></div>
-<p>
+DROP DATABASE</pre></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="install-postgres-startonboot"></a>Getting PostgreSQL to start on boot</h3></div></div><p>
Download <a href="files/postgresql.txt" target="_top">postgresql.txt</a> to
<tt>/tmp</tt>. Then follow the instructions
specific to your distribution:
- </p>
-<div class="itemizedlist"><ul>
-<li>
-<p>Debian:</p>
-<pre class="programlisting">
+ </p><div class="itemizedlist"><ul type="disc"><li><p>Debian:</p><pre class="programlisting">
postgres:~$ su -
Password: ***********
root:~# cp /tmp/postgresql.txt /etc/init.d/postgresql
root:~# chown root.root /etc/init.d/postgresql
-root:~# chmod 700 /etc/init.d/postgresql</pre>
-<p>Test the script</p>
-<pre class="programlisting">
+root:~# chmod 700 /etc/init.d/postgresql</pre><p>Test the script</p><pre class="programlisting">
root:~# /etc/init.d/postgresql stop
-Stopping PostgreSQL: ok</pre>
-<p>
+Stopping PostgreSQL: ok</pre><p>
If PostgreSQL successfully stopped, then use the following
command to make sure that the script is run appropriately at boot
and shutdown.
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
root:~# update-rc.d postgresql defaults
Adding system startup for /etc/init.d/postgresql ...
/etc/rc0.d/K20postgresql -> ../init.d/postgresql
@@ -259,52 +170,36 @@
root:~# /etc/init.d/postgresql start
Starting PostgreSQL: ok
root:~# exit
-postgres:~$ exit</pre>
-</li>
-<li>
-<p>Red Hat:</p>
-<pre class="programlisting">
+postgres:~$ exit</pre></li><li><p>Red Hat:</p><pre class="programlisting">
postgres:~$ su -
Password: ***********
root:~# cp /tmp/postgresql.txt /etc/rc.d/init.d/postgresql
root:~# chown root.root /etc/rc.d/init.d/postgresql
-root:~# chmod 700 /etc/rc.d/init.d/postgresql</pre>
-<p>Test the script</p>
-<pre class="programlisting">
+root:~# chmod 700 /etc/rc.d/init.d/postgresql</pre><p>Test the script</p><pre class="programlisting">
root:~# /etc/rc.d/init.d/postgresql stop
-Stopping PostgreSQL: ok</pre>
-<p>If PostgreSQL successfully stopped, then use the following
+Stopping PostgreSQL: ok</pre><p>If PostgreSQL successfully stopped, then use the following
command to make sure that the script is run appropriately at boot
and shutdown.
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
root:~# chkconfig --add postgresql
root:~# chkconfig --list postgresql
; You should see:
-postgresql 0:off 1:off 2:off 3:on 4:on 5:on 6:off
+postgresql 0:off 1:off 2:on 3:on 4:on 5:on 6:off
root:~# /etc/rc.d/init.d/postgresql start
Starting PostgreSQL: ok
root:~# exit
-postgres:~$ exit</pre>
-</li>
-<li>
-<p>SuSE:</p>
-<pre class="programlisting">
+postgres:~$ exit</pre></li><li><p>SuSE:</p><pre class="programlisting">
postgres:~$ su -
Password: ***********
root:~# cp /tmp/postgresql.txt /etc/rc.d/init.d/postgresql
root:~# chown root.root /etc/rc.d/init.d/postgresql
-root:~# chmod 700 /etc/rc.d/init.d/postgresql</pre>
-<p>Test the script</p>
-<pre class="programlisting">
+root:~# chmod 700 /etc/rc.d/init.d/postgresql</pre><p>Test the script</p><pre class="programlisting">
root:~# /etc/rc.d/init.d/postgresql stop
-Stopping PostgreSQL: ok</pre>
-<p>
+Stopping PostgreSQL: ok</pre><p>
If PostgreSQL successfully stopped, then use the following
command to make sure that the script is run appropriately at boot
and shutdown.
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
root:~# cd /etc/rc.d/init.d
root:/etc/rc.d/init.d# ln -s /etc/rc.d/init.d/postgresql K20postgresql
root:/etc/rc.d/init.d# ln -s /etc/rc.d/init.d/postgresql S20postgresql
@@ -317,73 +212,30 @@
root:/etc/rc.d/init.d# cp K20postgresql rc5.d
root:/etc/rc.d/init.d# cp S20postgresql rc5.d
root:/etc/rc.d/init.d# rm K20postgresql
-root:/etc/rc.d/init.d# rm S20postgresql</pre>
-<p>
+root:/etc/rc.d/init.d# rm S20postgresql</pre><p>
Test configuration
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
root:/etc/rc.d/init.d # cd
root:~ # /etc/rc.d/init.d/rc2.d/S20postgresql start
Starting PostgreSQL: ok
-root:~ # exit</pre>
-</li>
-</ul></div>
-<p>
+root:~ # exit</pre></li></ul></div><p>
From now on, PostgreSQL should start automatically each time you boot
up and it should shutdown gracefully each time you shut down. (Note:
Debian defaults to starting all services on runlevels 2-5. Red Hat
defaults to starting services on 3-5. So, on Red Hat, PostgreSQL won't
start on runlevel 2 unless you alter the above commands a
little. This usually isn't a problem as Red Hat defaults to runlevel 3)
- </p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="install-postgres-moreinfo"></a>Learn more about PostgreSQL</h3></div></div>
-<p>
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="install-postgres-moreinfo"></a>Learn more about PostgreSQL</h3></div></div><p>
Here are some links:
- </p>
-<div class="itemizedlist"><ul>
-<li><p>
+ </p><div class="itemizedlist"><ul type="disc"><li><p>
<a href="http://www.postgresql.org/idocs/" target="_top">Official PostgreSQL Docs</a>
- </p></li>
-<li><p>
+ </p></li><li><p>
<a href="http://pascal.scheffers.net/openacs/pgupdate/" target="_top">Migrating from 7.0 to 7.1</a>
- </p></li>
-<li><p>
+ </p></li><li><p>
<a href="http://techdocs.postgresql.org" target="_top">techdocs.postgresql.org</a>
- </p></li>
-<li><p>
+ </p></li><li><p>
<a href="http://www.linuxjournal.com/article.php?sid=4791" target="_top">PostgreSQL
Performance Tuning</a>
- </p></li>
-</ul></div>
-</div>
-<p><div class="cvstag">($Id$)</div></p>
-</div>
-<div class="navfooter">
-<hr>
-<table width="100%" summary="Navigation footer">
-<tr>
-<td width="40%" align="left">
-<a accesskey="p" href="oracle.html">Prev</a> </td>
-<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
-<td width="40%" align="right"> <a accesskey="n" href="aolserver.html">Next</a>
-</td>
-</tr>
-<tr>
-<td width="40%" align="left">Install Oracle 8.1.7 </td>
-<td width="20%" align="center"><a accesskey="u" href="unix-install.html">Up</a></td>
-<td width="40%" align="right"> Install AOLserver 3.3+ad13</td>
-</tr>
-</table>
-<hr>
-<address>
- rmello at fslc.usu.edu
- </address>
-<address><a href="mailto:vinod@kurup.com">
+ </p></li></ul></div></div><p><div class="cvstag">($Id$)</div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="oracle.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="aolserver.html">Next</a></td></tr><tr><td width="40%" align="left">Install Oracle 8.1.7 </td><td width="20%" align="center"><a accesskey="u" href="unix-install.html">Up</a></td><td width="40%" align="right"> Install AOLserver 3.3+ad13</td></tr></table><hr><address>rmello at fslc.usu.edu</address><address><a href="mailto:vinod@kurup.com">
vinod@kurup.com
- </a></address>
-</div>
-</body>
-</html>
+ </a></address></div></body></html>
Index: openacs-4/packages/acs-core-docs/www/programming-with-aolserver.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/programming-with-aolserver.html,v
diff -u -r1.7 -r1.7.2.1
--- openacs-4/packages/acs-core-docs/www/programming-with-aolserver.html 7 Mar 2002 06:55:36 -0000 1.7
+++ openacs-4/packages/acs-core-docs/www/programming-with-aolserver.html 15 May 2002 23:26:18 -0000 1.7.2.1
@@ -1,97 +1,50 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type">
-<title>Programming with AOLserver</title>
-<meta name="generator" content="DocBook XSL Stylesheets V1.45">
-<link rel="home" href="index.html" title="OpenACS Documentation">
-<link rel="up" href="more-developer-info.html" title="Chapter 5. Other Developer Resources">
-<link rel="previous" href="object-identity.html" title="Object Identity">
-<link rel="next" href="eng-standards.html" title="Chapter 6. Engineering Standards">
-<link rel="stylesheet" href="openacs.css" type="text/css">
-</head>
-<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-<div class="navheader">
-<a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr>
-<td width="20%" align="left">
-<a accesskey="p" href="object-identity.html">Prev</a> </td>
-<th width="60%" align="center">Chapter 5. Other Developer Resources</th>
-<td width="20%" align="right"> <a accesskey="n" href="eng-standards.html">Next</a>
-</td>
-</tr></table>
-<hr>
-</div>
-<div class="sect1">
-<div class="titlepage"><div><h2 class="title" style="clear: both">
-<a name="programming-with-aolserver"></a>Programming with AOLserver</h2></div></div>
-<div class="authorblurb"><p>
+<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"><title>Programming with AOLserver</title><meta name="generator" content="DocBook XSL Stylesheets V1.50.0"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="more-developer-info.html" title="Chapter 5. Other Developer Resources"><link rel="previous" href="object-identity.html" title="Object Identity"><link rel="next" href="eng-standards.html" title="Chapter 6. Engineering Standards"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="object-identity.html">Prev</a> </td><th width="60%" align="center">Chapter 5. Other Developer Resources</th><td width="20%" align="right"> <a accesskey="n" href="eng-standards.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="programming-with-aolserver"></a>Programming with AOLserver</h2></div></div><div class="authorblurb"><p>
by <a href="mailto:michael@arsdigita.com" target="_top">Michael Yoon</a>, <a href="mailto:jsalz@mit.edu" target="_top">Jon Salz</a> and <a href="http://www.pinds.com/lars" target="_top">Lars Pind</a>.
-</p></div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="programming-aolserver-global"></a>The <tt>global</tt> command</h3></div></div>
-<p>
-When using AOLserver, remember that there are effectively <span class="emphasis"><i>two</i></span> types
+<br>
+ OpenACS docs are written by the named authors, but may be edited
+ by OpenACS documentation staff.
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="programming-aolserver-global"></a>The <tt>global</tt> command</h3></div></div><p>
+When using AOLserver, remember that there are effectively <span class="emphasis"><em>two</em></span> types
of global namespace, not one:
-</p>
-<div class="orderedlist"><ol type="1">
-<li><p>
-<span class="emphasis"><i>Server</i></span>-global: As you'd expect, there is
+</p><div class="orderedlist"><ol type="1"><li><p><span class="emphasis"><em>Server</em></span>-global: As you'd expect, there is
only one server-global namespace per server, and variables set within it can
be accessed by any Tcl code running subsequently, in any of the server's
threads. To set/get server-global variables, use AOLserver 3's <a href="http://www.aolserver.com/docs/nsv.adp" target="_top"><tt>nsv</tt> API</a>
(which supersedes <tt>ns_share</tt> from the pre-3.0 API).
-</p></li>
-<li><p>
-<span class="emphasis"><i>Script</i></span>-global: Each Tcl script (ADP, Tcl page,
+</p></li><li><p><span class="emphasis"><em>Script</em></span>-global: Each Tcl script (ADP, Tcl page,
registered proc, filter, etc.) executing within an AOLserver thread has its
own global namespace. Any variable set in the top level of a script is, by
definition, script-global, meaning that it is accessible only by subsequent
code in the same script and only for the duration of the current script
-execution.</p></li>
-</ol></div>
-<p>
+execution.</p></li></ol></div><p>
The Tcl built-in command <a href="http://aolserver.com/docs/tcl/tcl8.3/TclCmd/global.htm" target="_top"><tt>global</tt></a>
-accesses script-global, <span class="emphasis"><i>not</i></span> server-global, variables from within a
+accesses script-global, <span class="emphasis"><em>not</em></span> server-global, variables from within a
procedure. This distinction is important to understand in order to use
<tt>global</tt> correctly when programming AOLserver.
-</p>
-<p>Also, AOLserver purges all script-global variables in a thread (i.e., Tcl
+</p><p>Also, AOLserver purges all script-global variables in a thread (i.e., Tcl
interpreter) between HTTP requests. If it didn't, that would affect (and
complicate) our use of script-global variables dramatically, which would then
-be better described as <span class="emphasis"><i>thread</i></span>-global variables. Given
+be better described as <span class="emphasis"><em>thread</em></span>-global variables. Given
AOLserver's behaviour, however, "script-global" is a more
-appropriate term.</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="programming-aolserver-sched-procs"></a>Threads and Scheduled Procedures</h3></div></div>
-<p>
+appropriate term.</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="programming-aolserver-sched-procs"></a>Threads and Scheduled Procedures</h3></div></div><p>
<tt>ns_schedule_proc</tt> and <tt>ad_schedule_proc</tt> each take a
<tt>-thread</tt> flag to cause a scheduled procedure to run
asychronously, in its own thread. It almost always seems like a good idea to
specify this switch, but there's a problem.
-</p>
-<p>It turns out that whenever a task scheduled with <tt>ns_schedule_proc
+</p><p>It turns out that whenever a task scheduled with <tt>ns_schedule_proc
-thread</tt> or <tt>ad_schedule_proc -thread t</tt> is run, AOLserver
creates a brand new thread and a brand new interpreter, and reinitializes the
procedure table (essentially, loads all procedures that were created during
-server initialization into the new interpreter). This happens <span class="emphasis"><i>every
-time</i></span> the task is executed - and it is a very expensive process that
-should not be taken lightly!</p>
-<p>The moral: if you have a lightweight scheduled procedure
+server initialization into the new interpreter). This happens <span class="emphasis"><em>every
+time</em></span> the task is executed - and it is a very expensive process that
+should not be taken lightly!</p><p>The moral: if you have a lightweight scheduled procedure
which runs frequently, don't use the <tt>-thread</tt>
-switch.</p>
-<blockquote class="blockquote"><p><span class="emphasis"><i>Note also that thread is initialized with a copy of what was
+switch.</p><blockquote class="blockquote"><p><span class="emphasis"><em>Note also that thread is initialized with a copy of what was
installed during server startup, so if the procedure table have changed since
startup (e.g. using the <a href="apm-design.html" title="OpenACS 4.5 Package Manager Design">APM</a> watch
facility), that will not be reflected in the scheduled
-thread.</i></span></p></blockquote>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="programming-aolserver-return"></a>Using <tt>return</tt></h3></div></div>
-<p>
+thread.</em></span></p></blockquote></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="programming-aolserver-return"></a>Using <tt>return</tt></h3></div></div><p>
The <tt>return</tt> command in Tcl returns control to the caller procedure.
This definition allows nested procedures to work properly. However, this
definition also means that nested procedures cannot use <tt>return</tt> to
@@ -108,12 +61,7 @@
executed because the thread was not stopped. Note that <tt>return -code
return</tt> can be used in circumstances where the procedure will only be
called from two levels deep.
-</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="programming-aolserver-more-values"></a>Returning More Than One Value From a Function</h3></div></div>
-<p>
+</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="programming-aolserver-more-values"></a>Returning More Than One Value From a Function</h3></div></div><p>
Many functions have a single return value. For instance, <a href="/api-doc/proc-view?proc=empty%5fstring%5fp" target="_top"><tt>empty_string_p</tt></a>
returns a number: 1 or 0. Other functions need to return a composite value.
For instance, consider a function that looks up a user's name and email
@@ -122,22 +70,17 @@
contains the email address. The problem with this technique is that, because
Tcl does not support constants, calling procedures that returns lists in this
way necessitates the use of magic numbers, e.g.:
-</p>
-<pre class="programlisting">
+</p><pre class="programlisting">
set user_info [ad_get_user_info $user_id]
set first_name [lindex $user_info 0]
set email [lindex $user_info 1]
-</pre>
-<p>AOLserver/Tcl generally has three mechanisms that we like, for returning
+</pre><p>AOLserver/Tcl generally has three mechanisms that we like, for returning
more than one value from a function. When to use which depends on the
-circumstances.</p>
-<p>Using Arrays and Pass-By-Value</p>
-<p>
+circumstances.</p><p>Using Arrays and Pass-By-Value</p><p>
The one we generally prefer is returning an <a href="http://aolserver.com/docs/tcl/tcl8.3/TclCmd/array.htm#M8" target="_top"><tt>array
get</tt></a>-formatted list. It has all the nice properties of
pass-by-value, and it uses Tcl arrays, which have good native support.
-</p>
-<pre class="programlisting">
+</p><pre class="programlisting">
ad_proc ad_get_user_info { user_id } {
db_1row user_info { select first_names, last_name, email from users where user_id = :user_id }
return [list \
@@ -150,12 +93,10 @@
array set user_info [ad_get_user_info $user_id]
doc_body_append "$user_info(namelink) ($user_info(emaillink))"
-</pre>
-<p>
+</pre><p>
You could also have done this by using an array internally and using
<tt>array get</tt>:
-</p>
-<pre class="programlisting">
+</p><pre class="programlisting">
ad_proc ad_get_user_info { user_id } {
db_1row user_info { select first_names, last_name, email from users where user_id = :user_id }
@@ -166,25 +107,20 @@
return [array get user_info]
}
-</pre>
-<p>Using Arrays and Pass-By-Reference</p>
-<p>
+</pre><p>Using Arrays and Pass-By-Reference</p><p>
Sometimes pass-by-value incurs too much overhead, and you'd rather
pass-by-reference. Specifically, if you're writing a proc that uses
arrays internally to build up some value, there are many entries in the
array, and you're planning on iterating over the proc many times. In this
case, pass-by-value is expensive, and you'd use pass-by-reference.
-</p>
-<blockquote class="blockquote"><p><span class="emphasis"><i>The transformation of the array into a list and back to an
+</p><blockquote class="blockquote"><p><span class="emphasis"><em>The transformation of the array into a list and back to an
array takes, in our test environment, approximately 10 microseconds per entry
of 100 character's length. Thus you can process about 100 entries per
milisecond. The time depends almost completely on the number of entries, and
-almost not at all on the size of the entries.</i></span></p></blockquote>
-<p>
+almost not at all on the size of the entries.</em></span></p></blockquote><p>
You implement pass-by-reference in Tcl by taking the name of an array
as an argument and <tt>upvar</tt> it.
-</p>
-<pre class="programlisting">
+</p><pre class="programlisting">
ad_proc ad_get_user_info {
-array:required
@@ -202,28 +138,22 @@
doc_body_append "$user_info(namelink) ($user_info(emaillink))"
-</pre>
-<p>We prefer pass-by-value over pass-by-reference. Pass-by-reference makes
+</pre><p>We prefer pass-by-value over pass-by-reference. Pass-by-reference makes
the code harder to read and debug, because changing a value in one place has
side effects in other places. Especially if have a chain of
<tt>upvar</tt>s through several layers of the call stack, you'll have
-a hard time debugging.</p>
-<p>Multisets: Using <tt>ns_set</tt>s and Pass-By-Reference</p>
-<p>
-An array is a type of <span class="emphasis"><i>set</i></span>, which means you can't have multiple
+a hard time debugging.</p><p>Multisets: Using <tt>ns_set</tt>s and Pass-By-Reference</p><p>
+An array is a type of <span class="emphasis"><em>set</em></span>, which means you can't have multiple
entries with the same key. Data structures that can have multiple entries for
-the same key are known as a <span class="emphasis"><i>multiset</i></span> or <span class="emphasis"><i>bag</i></span>.
-</p>
-<p>If your data can have multiple entries with the same key,
+the same key are known as a <span class="emphasis"><em>multiset</em></span> or <span class="emphasis"><em>bag</em></span>.
+</p><p>If your data can have multiple entries with the same key,
you should use the AOLserver built-in <a href="http://www.aolserver.com/docs/tcldev/tapi-120.htm#197598" target="_top"><tt>
ns_set</tt></a>. You can also do a case-insensitive lookup on an
<tt>ns_set</tt>, something you can't easily do on an array. This is
especially useful for things like HTTP headers, which happen to have these
-exact properties.</p>
-<p>You always use pass-by-reference with <tt>ns_set</tt>s, since they
+exact properties.</p><p>You always use pass-by-reference with <tt>ns_set</tt>s, since they
don't have any built-in way of generating and reconstructing themselves
-from a string representation. Instead, you pass the handle to the set.</p>
-<pre class="programlisting">
+from a string representation. Instead, you pass the handle to the set.</p><pre class="programlisting">
ad_proc ad_get_user_info {
-set:required
@@ -241,16 +171,13 @@
doc_body_append "[ns_set get $user_info namelink] ([ns_set get $user_info emaillink])"
-</pre>
-<p>
+</pre><p>
We don't recommend <tt>ns_set</tt> as a general mechanism for passing
sets (as opposed to multisets) of data. Not only do they inherently use
pass-by-reference, which we dis-like, they're also somewhat clumsy to
use, since Tcl doesn't have built-in syntactic support for them.
-</p>
-<p>Consider for example a loop over the entries in a <tt>ns_set</tt> as
-compared to an array:</p>
-<pre class="programlisting">
+</p><p>Consider for example a loop over the entries in a <tt>ns_set</tt> as
+compared to an array:</p><pre class="programlisting">
# ns_set variant
set size [ns_set size $myset]
@@ -263,11 +190,9 @@
puts "$myarray($name) = $myarray($name)"
}
-</pre>
-<p>
+</pre><p>
And this example of constructing a value:
-</p>
-<pre class="programlisting">
+</p><pre class="programlisting">
# ns_set variant
set myset [ns_set create]
@@ -281,40 +206,12 @@
baz $baz
]
-</pre>
-<p>
+</pre><p>
<tt>ns_set</tt>s are designed to be lightweight, so memory consumption
should not be a problem. However, when using <tt>ns_set get</tt> to
perform lookup by name, they perform a linear lookup, whereas arrays use a
hash table, so <tt>ns_set</tt>s are slower than arrays when the number of
entries is large.
-</p>
-<p><div class="cvstag">($Id$)</div></p>
-</div>
-</div>
-<div class="navfooter">
-<hr>
-<table width="100%" summary="Navigation footer">
-<tr>
-<td width="40%" align="left">
-<a accesskey="p" href="object-identity.html">Prev</a> </td>
-<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
-<td width="40%" align="right"> <a accesskey="n" href="eng-standards.html">Next</a>
-</td>
-</tr>
-<tr>
-<td width="40%" align="left">Object Identity </td>
-<td width="20%" align="center"><a accesskey="u" href="more-developer-info.html">Up</a></td>
-<td width="40%" align="right"> Chapter 6. Engineering Standards</td>
-</tr>
-</table>
-<hr>
-<address>
- rmello at fslc.usu.edu
- </address>
-<address><a href="mailto:vinod@kurup.com">
+</p><p><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="object-identity.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="eng-standards.html">Next</a></td></tr><tr><td width="40%" align="left">Object Identity </td><td width="20%" align="center"><a accesskey="u" href="more-developer-info.html">Up</a></td><td width="40%" align="right"> Chapter 6. Engineering Standards</td></tr></table><hr><address>rmello at fslc.usu.edu</address><address><a href="mailto:vinod@kurup.com">
vinod@kurup.com
- </a></address>
-</div>
-</body>
-</html>
+ </a></address></div></body></html>
Index: openacs-4/packages/acs-core-docs/www/psgml-mode.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/psgml-mode.html,v
diff -u -r1.7 -r1.7.2.1
--- openacs-4/packages/acs-core-docs/www/psgml-mode.html 7 Mar 2002 06:55:36 -0000 1.7
+++ openacs-4/packages/acs-core-docs/www/psgml-mode.html 15 May 2002 23:26:18 -0000 1.7.2.1
@@ -1,109 +1,43 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type">
-<title>Using PSGML mode in Emacs</title>
-<meta name="generator" content="DocBook XSL Stylesheets V1.45">
-<link rel="home" href="index.html" title="OpenACS Documentation">
-<link rel="up" href="eng-standards.html" title="Chapter 6. Engineering Standards">
-<link rel="previous" href="docbook-primer.html" title="OpenACS Documentation Guide">
-<link rel="next" href="filename.html" title="Detailed Design Documentation Template">
-<link rel="stylesheet" href="openacs.css" type="text/css">
-</head>
-<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-<div class="navheader">
-<a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr>
-<td width="20%" align="left">
-<a accesskey="p" href="docbook-primer.html">Prev</a> </td>
-<th width="60%" align="center">Chapter 6. Engineering Standards</th>
-<td width="20%" align="right"> <a accesskey="n" href="filename.html">Next</a>
-</td>
-</tr></table>
-<hr>
-</div>
-<div class="sect1">
-<div class="titlepage"><div><h2 class="title" style="clear: both">
-<a name="psgml-mode"></a>Using PSGML mode in Emacs</h2></div></div>
-<div class="authorblurb"><p>
-By <a href="mailto:lutter@arsdigita.com" target="_top">David Lutterkort</a>
-</p></div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="psgml-mode-whatisit"></a>What it is</h3></div></div>
-<p>PSGML Mode is a mode for editing, umm, SGML and XML documents in emacs. It
+<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"><title>Using PSGML mode in Emacs</title><meta name="generator" content="DocBook XSL Stylesheets V1.50.0"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="eng-standards.html" title="Chapter 6. Engineering Standards"><link rel="previous" href="docbook-primer.html" title="OpenACS Documentation Guide"><link rel="next" href="filename.html" title="Detailed Design Documentation Template"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="docbook-primer.html">Prev</a> </td><th width="60%" align="center">Chapter 6. Engineering Standards</th><td width="20%" align="right"> <a accesskey="n" href="filename.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="psgml-mode"></a>Using PSGML mode in Emacs</h2></div></div><div class="authorblurb"><p>
+By <a href="mailto:lutter@arsdigita.com" target="_top">David Lutterkort</a><br>
+ OpenACS docs are written by the named authors, but may be edited
+ by OpenACS documentation staff.
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="psgml-mode-whatisit"></a>What it is</h3></div></div><p>PSGML Mode is a mode for editing, umm, SGML and XML documents in emacs. It
can parse a DTD and help you insert the right tags in the right place, knows
about tags' attributes and can tell you in which contexts a tag can be
-used. <span class="emphasis"><i>If</i></span> you give it the right DTD, that is. But even without a DTD,
+used. <span class="emphasis"><em>If</em></span> you give it the right DTD, that is. But even without a DTD,
it can save you some typing since pressing <tt>C-c/</tt> will close an open
-tag automatically.</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="psgml-mode-getit"></a>Where to get it</h3></div></div>
-<p>Most newer emacsen come with PSGML mode preinstalled. You can find out
+tag automatically.</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="psgml-mode-getit"></a>Where to get it</h3></div></div><p>Most newer emacsen come with PSGML mode preinstalled. You can find out
whether your emacs has it with the <tt>locate-library</tt> command. In Emacs,
type <tt>M-x locate-library</tt> and enter <tt>psgml</tt>. Emacs will tell
-you if it found it or not.</p>
-<p>If you don't have PSGML preinstalled in your Emacs, there are two
-things you can do:</p>
-<div class="orderedlist"><ol type="1">
-<li><p>On Linux: Get the <a href="ftp://sourceware.cygnus.com:/pub/docbook-tools/docware/RPMS/noarch/psgml-1.2.1-1.noarch.rpm" target="_top">
+you if it found it or not.</p><p>If you don't have PSGML preinstalled in your Emacs, there are two
+things you can do:</p><div class="orderedlist"><ol type="1"><li><p>On Linux: Get the <a href="ftp://sourceware.cygnus.com:/pub/docbook-tools/docware/RPMS/noarch/psgml-1.2.1-1.noarch.rpm" target="_top">
psgml rpm</a> from <a href="http://sources.redhat.com/docbook-tools/" target="_top">RedHat's
-docbook-tools</a> and install it as usual.</p></li>
-<li><p>On other systems: Get the tarball from the <a href="http://www.lysator.liu.se/~lenst/about_psgml/" target="_top">PSGML Website.</a>
-Unpack it and follow the install instructions.</p></li>
-</ol></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="psgml-mode-catalogs"></a>Using <tt>CATALOG</tt> files</h3></div></div>
-<p>The easiest way to teach PSGML mode about a DTD is by adding it to your
+docbook-tools</a> and install it as usual.</p></li><li><p>On other systems: Get the tarball from the <a href="http://www.lysator.liu.se/~lenst/about_psgml/" target="_top">PSGML Website.</a>
+Unpack it and follow the install instructions.</p></li></ol></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="psgml-mode-catalogs"></a>Using <tt>CATALOG</tt> files</h3></div></div><p>The easiest way to teach PSGML mode about a DTD is by adding it to your
own <tt>CATALOG</tt>. Here is an example of how you can set that up for the
-Docbook XML DTD.</p>
-<div class="orderedlist"><ol type="1">
-<li><p>Get the <a href="http://docbook.org/xml/index.html" target="_top">Docbook XML DTD</a>
-zip archive from <a href="http://docbook.org/" target="_top">docbook.org</a>
-</p></li>
-<li>
-<p>Go somewhere in your working directory and do </p>
-<pre class="programlisting">
+Docbook XML DTD.</p><div class="orderedlist"><ol type="1"><li><p>Get the <a href="http://docbook.org/xml/index.html" target="_top">Docbook XML DTD</a>
+zip archive from <a href="http://docbook.org/" target="_top">docbook.org</a></p></li><li><p>Go somewhere in your working directory and do </p><pre class="programlisting">
mkdir -p dtd/docbook-xml
cd dtd/docbook-xml
unzip -a <docbook XML DTD zip archive>
-</pre>
-</li>
-<li>
-<p>Create a file with the name <tt>CATALOG</tt> in the <tt>dtd</tt>
-directory and put the line </p>
-<pre class="programlisting">
+</pre></li><li><p>Create a file with the name <tt>CATALOG</tt> in the <tt>dtd</tt>
+directory and put the line </p><pre class="programlisting">
CATALOG "docbook-xml/docbook.cat"
-</pre>
-<p>
+</pre><p>
in it. By maintaining your own <tt>CATALOG</tt>, it is easy to add more
-DTD's without changing your emacs settings. (<span class="emphasis"><i>How about that HTML 4.01 DTD you
+DTD's without changing your emacs settings. (<span class="emphasis"><em>How about that HTML 4.01 DTD you
always wanted to get from <a href="http://www.w3.org/TR/html4/" target="_top">W3C</a> ? The
-DTD is in the zip archives and tarballs available on the site.</i></span>
-</p>
-</li>
-</ol></div>
-<p>That's it. Now you are ready to tell emacs all about PSGML mode and
-that funky <tt>CATALOG</tt>
-</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="psgml-mode-tell-emacs"></a>What to tell emacs</h3></div></div>
-<p>If you installed PSGML mode in a non-standard location, e.g., somewhere in
+DTD is in the zip archives and tarballs available on the site.</em></span></p></li></ol></div><p>That's it. Now you are ready to tell emacs all about PSGML mode and
+that funky <tt>CATALOG</tt></p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="psgml-mode-tell-emacs"></a>What to tell emacs</h3></div></div><p>If you installed PSGML mode in a non-standard location, e.g., somewhere in
your home directory, you need to add this to the <tt>load-path</tt> by adding
-this line to your <tt>.emacs</tt> file:</p>
-<pre class="programlisting">
+this line to your <tt>.emacs</tt> file:</p><pre class="programlisting">
(add-to-list 'load-path "/some/dir/that/contains/psgml.elc")
-</pre>
-<p>To let PSGML mode find your <tt>CATALOG</tt> and to enable PSGML mode for
-all your editing, add these lines to your <tt>.emacs</tt>:</p>
-<pre class="programlisting">
+</pre><p>To let PSGML mode find your <tt>CATALOG</tt> and to enable PSGML mode for
+all your editing, add these lines to your <tt>.emacs</tt>:</p><pre class="programlisting">
(require 'psgml)
(add-to-list 'auto-mode-alist '("\\.html" . sgml-mode))
@@ -113,10 +47,8 @@
(add-to-list 'sgml-catalog-files "/path/to/your/dtd/CATALOG")
-</pre>
-<p>If you want font-locking and indentation, you can also add these lines
-into the <tt>.emacs</tt> file:</p>
-<pre class="programlisting">
+</pre><p>If you want font-locking and indentation, you can also add these lines
+into the <tt>.emacs</tt> file:</p><pre class="programlisting">
(setq sgml-markup-faces '((start-tag . font-lock-function-name-face)
(end-tag . font-lock-function-name-face)
(comment . font-lock-comment-face)
@@ -132,101 +64,26 @@
(define-key sgml-mode-map "\C-c\C-x\C-i" 'sgml-general-dtd-info)
(define-key sgml-mode-map "\C-c\C-x\C-t" 'sgml-describe-entity))))
-</pre>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="psgml-mode-doctype"></a>What is a <tt>DOCTYPE</tt> ?</h3></div></div>
-<p>All SGML and XML documents that should conform to a DTD have to declare a
+</pre></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="psgml-mode-doctype"></a>What is a <tt>DOCTYPE</tt> ?</h3></div></div><p>All SGML and XML documents that should conform to a DTD have to declare a
doctype. For the docbook XML, all your <tt>.xml</tt> files whould start with
-the line</p>
-<pre class="programlisting">
+the line</p><pre class="programlisting">
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "docbookx.dtd">
-</pre>
-<p>If your document is only part of a larger XML document, you can tell PSGML
-mode about it by <span class="emphasis"><i>appending</i></span> the following lines to your file. In this
-case, do <span class="emphasis"><i>not</i></span> include a DOCTYPE declaration in your file.</p>
-<pre class="programlisting">
+</pre><p>If your document is only part of a larger XML document, you can tell PSGML
+mode about it by <span class="emphasis"><em>appending</em></span> the following lines to your file. In this
+case, do <span class="emphasis"><em>not</em></span> include a DOCTYPE declaration in your file.</p><pre class="programlisting">
<!--
Local Variables:
sgml-parent-document: ("top.xml" "book" "sect1")
End:
-->
-</pre>
-<p>Which says that the parent of this document can be found in the file
+</pre><p>Which says that the parent of this document can be found in the file
<tt>top.xml</tt>, that the element in the parent that will enclose the
current document is a <tt>book</tt> and that the current file's topmost
-element is a <tt>sect1</tt>.</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="psgml-mode-usage"></a>How to use it</h3></div></div>
-<p>Of course, you should read the emacs texinfo pages that come with PSGML
-mode from start to finish. Barring that, here are some handy commands:</p>
-<div class="informaltable"><table border="0">
-<colgroup>
-<col>
-<col>
-</colgroup>
-<thead><tr>
-<th>Key</th>
-<th>Command</th>
-</tr></thead>
-<tbody>
-<tr>
-<td><tt>C-c C-e</tt></td>
-<td>Insert an element. Uses completion and only lets you insert elements that
-are valid</td>
-</tr>
-<tr>
-<td><tt>C-c C-a</tt></td>
-<td>Edit attributes of enclosing element.</td>
-</tr>
-<tr>
-<td><tt>C-c C-x C-i</tt></td>
-<td>Show information about the document's DTD.</td>
-</tr>
-<tr>
-<td><tt>C-c C-x C-e</tt></td>
-<td>Describe element. Shows for one element which elements can be parents,
-what its contents can be and lists its attributes.</td>
-</tr>
-</tbody>
-</table></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="psgml-mode-reading"></a>Further reading</h3></div></div>
-<p>Start with the <a href="docbook-primer.html">OpenACS Documentation Guide</a>
-</p>
-<p><div class="cvstag">($Id$)</div></p>
-</div>
-</div>
-<div class="navfooter">
-<hr>
-<table width="100%" summary="Navigation footer">
-<tr>
-<td width="40%" align="left">
-<a accesskey="p" href="docbook-primer.html">Prev</a> </td>
-<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
-<td width="40%" align="right"> <a accesskey="n" href="filename.html">Next</a>
-</td>
-</tr>
-<tr>
-<td width="40%" align="left">OpenACS Documentation Guide </td>
-<td width="20%" align="center"><a accesskey="u" href="eng-standards.html">Up</a></td>
-<td width="40%" align="right"> Detailed Design Documentation Template</td>
-</tr>
-</table>
-<hr>
-<address>
- rmello at fslc.usu.edu
- </address>
-<address><a href="mailto:vinod@kurup.com">
+element is a <tt>sect1</tt>.</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="psgml-mode-usage"></a>How to use it</h3></div></div><p>Of course, you should read the emacs texinfo pages that come with PSGML
+mode from start to finish. Barring that, here are some handy commands:</p><div class="informaltable"><table border="0"><colgroup><col><col></colgroup><thead><tr><th>Key</th><th>Command</th></tr></thead><tbody><tr><td><tt>C-c C-e</tt></td><td>Insert an element. Uses completion and only lets you insert elements that
+are valid</td></tr><tr><td><tt>C-c C-a</tt></td><td>Edit attributes of enclosing element.</td></tr><tr><td><tt>C-c C-x C-i</tt></td><td>Show information about the document's DTD.</td></tr><tr><td><tt>C-c C-x C-e</tt></td><td>Describe element. Shows for one element which elements can be parents,
+what its contents can be and lists its attributes.</td></tr></tbody></table></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="psgml-mode-reading"></a>Further reading</h3></div></div><p>Start with the <a href="docbook-primer.html">OpenACS Documentation Guide</a></p><p><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="docbook-primer.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="filename.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS Documentation Guide </td><td width="20%" align="center"><a accesskey="u" href="eng-standards.html">Up</a></td><td width="40%" align="right"> Detailed Design Documentation Template</td></tr></table><hr><address>rmello at fslc.usu.edu</address><address><a href="mailto:vinod@kurup.com">
vinod@kurup.com
- </a></address>
-</div>
-</body>
-</html>
+ </a></address></div></body></html>
Index: openacs-4/packages/acs-core-docs/www/release-notes.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/release-notes.html,v
diff -u -r1.8 -r1.8.2.1
--- openacs-4/packages/acs-core-docs/www/release-notes.html 7 Mar 2002 06:55:36 -0000 1.8
+++ openacs-4/packages/acs-core-docs/www/release-notes.html 15 May 2002 23:26:18 -0000 1.8.2.1
@@ -1,89 +1,53 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type">
-<title>OpenACS 4.5 Release Notes</title>
-<meta name="generator" content="DocBook XSL Stylesheets V1.45">
-<link rel="home" href="index.html" title="OpenACS Documentation">
-<link rel="up" href="general-documents.html" title="Chapter 1. High level information: What is OpenACS?">
-<link rel="previous" href="openacs-overview.html" title="Overview">
-<link rel="next" href="acs-admin.html" title="Part Part II. For OpenACS Admins">
-<link rel="stylesheet" href="openacs.css" type="text/css">
-</head>
-<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-<div class="navheader">
-<a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr>
-<td width="20%" align="left">
-<a accesskey="p" href="openacs-overview.html">Prev</a> </td>
-<th width="60%" align="center">Chapter 1. High level information: What is OpenACS?</th>
-<td width="20%" align="right"> <a accesskey="n" href="acs-admin.html">Next</a>
-</td>
-</tr></table>
-<hr>
-</div>
-<div class="sect1">
-<div class="titlepage"><div><h2 class="title" style="clear: both">
-<a name="release-notes"></a>OpenACS 4.5 Release Notes</h2></div></div>
-<div class="authorblurb"><p>
+<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"><title>OpenACS 4.5 Release Notes</title><meta name="generator" content="DocBook XSL Stylesheets V1.50.0"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="general-documents.html" title="Chapter 1. High level information: What is OpenACS?"><link rel="previous" href="openacs-overview.html" title="Overview"><link rel="next" href="acs-admin.html" title="Part Part II. For OpenACS Admins"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="openacs-overview.html">Prev</a> </td><th width="60%" align="center">Chapter 1. High level information: What is OpenACS?</th><td width="20%" align="right"> <a accesskey="n" href="acs-admin.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="release-notes"></a>OpenACS 4.5 Release Notes</h2></div></div><div class="authorblurb"><p>
by <a href="mailto:dhogaza@pacifier.com" target="_top">Don Baccus</a> and
- <a href="mailto:vinod@kurup.com" target="_top">Vinod Kurup</a>
- </p></div>
-<p>
+ <a href="mailto:vinod@kurup.com" target="_top">Vinod Kurup</a><br>
+ OpenACS docs are written by the named authors, but may be edited
+ by OpenACS documentation staff.
+ </p></div><p>
This is a beta release of OpenACS 4.5. This release has been subjected
to an organized test effort, but please bear in mind that we are still
in the process of developing testing tools, methodology, and scripts.
- </p>
-<p>
+ </p><p>
Please report bugs using our
- <a href="http://openacs.org/sdm/one-package.tcl&package_id=9" target="_top">
+ <a href="http://openacs.org/sdm/one-package.tcl%26amp;package_id=9" target="_top">
Software Development Manager</a> at the <a href="http://openacs.org/" target="_top">OpenACS website</a>. The latest
- information on installating this alpha release under Oracle 8.1.6/7
+ information on installing this alpha release under Oracle 8.1.6/7
or PostgreSQL 7.1.* can be found there as well. Currently the
toolkit will not install under Oracle 9i due to Oracle having made
"delete" an illegal name for PL/SQL procedures and functions.
- </p>
-<p>
- You may want to begin by reading our installation documentation for <a href="unix-install.html">Installing on Unix/Linux</a> or <a href="win-install.html" title="Chapter 3. Installing on Windows">Chapter 3</a>. Note that the Windows
- documentation is not current for OpenACS 4.5.
- </p>
-<p>
+ </p><p>
+ You may want to begin by reading our installation documentation for
+ <a href="unix-install.html">Installing on Unix/Linux</a> or <a href="win-install.html">Installing on Windows</a>. Note
+ that the Windows documentation is not current for OpenACS 4.5,
+ but an alternative is to use John Sequeira's <a href="http://www.pobox.com/~johnseq/projects/oasisvm/" target="_top">Oasis VM
+ project</a>.
+ </p><p>
After installation, the full documentation set can be found by visiting
http://[your-host]/doc. Not all pieces are updated for OpenACS 4.5 at
this moment.
- </p>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="release-notes-sws"></a>Site Wide Searching</h3></div></div>
-<p>
+ </p><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="release-notes-sws"></a>Site Wide Searching</h3></div></div><p>
If you're using Oracle 8.1.6 or 8.1.7 Enterprise Edition you may want
to uncomment the SQL that causes InterMedia to keep online searching
- online while indexing. The feature doesn't exist in Standard Editionx
+ online while indexing. The feature doesn't exist in Standard Edition
and OpenACS 4.5 now defaults to being loadable in SE. Just grep for
'sync' to find the code.
- </p>
-<p>
+ </p><p>
Also be sure to read the documentation in the Site Wide Search
package's sql/oracle directory. The APM doesn't execute the SQL for
this package, in part due to the fact that some steps need to be run
as the Oracle user 'ctxsys'.
- </p>
-<p>
+ </p><p>
If you're using PostgreSQL be sure to read the documentation on
installing the Open FTS driver for OpenACS. It's included in the
package as a text file and is also summarized at the end of the
installation documentation in the section, <a href="nextsteps.html#install-next-openfts">Set Up OpenFTS</a>. As with the Oracle version, there
are steps you must take manually in order to get this feature
working.
- </p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="release-notes-testing"></a>Testing Notes</h3></div></div>
-<p>
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="release-notes-testing"></a>Testing Notes</h3></div></div><p>
Here are some notes from our testing group. While not quite up to
date it should give you some ideas of where things stand.
- </p>
-<pre class="programlisting">
+ </p><pre class="programlisting">
Summarised Testing Status
Skin
@@ -240,33 +204,6 @@
Test Coverage: Minimal
Suggested Status: Alpha
Comments: Don tested personally
- </pre>
-</div>
-<p><div class="cvstag">($Id$)</div></p>
-</div>
-<div class="navfooter">
-<hr>
-<table width="100%" summary="Navigation footer">
-<tr>
-<td width="40%" align="left">
-<a accesskey="p" href="openacs-overview.html">Prev</a> </td>
-<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
-<td width="40%" align="right"> <a accesskey="n" href="acs-admin.html">Next</a>
-</td>
-</tr>
-<tr>
-<td width="40%" align="left">Overview </td>
-<td width="20%" align="center"><a accesskey="u" href="general-documents.html">Up</a></td>
-<td width="40%" align="right"> Part Part II. For OpenACS Admins</td>
-</tr>
-</table>
-<hr>
-<address>
- rmello at fslc.usu.edu
- </address>
-<address><a href="mailto:vinod@kurup.com">
+ </pre></div><p><div class="cvstag">($Id$)</div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="openacs-overview.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="acs-admin.html">Next</a></td></tr><tr><td width="40%" align="left">Overview </td><td width="20%" align="center"><a accesskey="u" href="general-documents.html">Up</a></td><td width="40%" align="right"> Part Part II. For OpenACS Admins</td></tr></table><hr><address>rmello at fslc.usu.edu</address><address><a href="mailto:vinod@kurup.com">
vinod@kurup.com
- </a></address>
-</div>
-</body>
-</html>
+ </a></address></div></body></html>
Index: openacs-4/packages/acs-core-docs/www/request-processor.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/request-processor.html,v
diff -u -r1.7 -r1.7.2.1
--- openacs-4/packages/acs-core-docs/www/request-processor.html 7 Mar 2002 06:55:36 -0000 1.7
+++ openacs-4/packages/acs-core-docs/www/request-processor.html 15 May 2002 23:26:18 -0000 1.7.2.1
@@ -1,44 +1,12 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type">
-<title>The Request Processor</title>
-<meta name="generator" content="DocBook XSL Stylesheets V1.45">
-<link rel="home" href="index.html" title="OpenACS Documentation">
-<link rel="up" href="dev-guide.html" title="Chapter 4. OpenACS Developer's Guide">
-<link rel="previous" href="packages.html" title="OpenACS 4.5 Packages">
-<link rel="next" href="db-api.html" title="The OpenACS Database Access API">
-<link rel="stylesheet" href="openacs.css" type="text/css">
-</head>
-<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-<div class="navheader">
-<a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr>
-<td width="20%" align="left">
-<a accesskey="p" href="packages.html">Prev</a> </td>
-<th width="60%" align="center">Chapter 4. OpenACS Developer's Guide</th>
-<td width="20%" align="right"> <a accesskey="n" href="db-api.html">Next</a>
-</td>
-</tr></table>
-<hr>
-</div>
-<div class="sect1">
-<div class="titlepage"><div><h2 class="title" style="clear: both">
-<a name="request-processor"></a>The Request Processor</h2></div></div>
-<div class="authorblurb"><p>By <a href="mailto:psu@arsdigita.com" target="_top">Pete Su</a>
-</p></div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="rp-overview"></a>Overview</h3></div></div>
-<p>
+<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"><title>The Request Processor</title><meta name="generator" content="DocBook XSL Stylesheets V1.50.0"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="dev-guide.html" title="Chapter 4. OpenACS Developer's Guide"><link rel="previous" href="packages.html" title="OpenACS 4.5 Packages"><link rel="next" href="db-api.html" title="The OpenACS Database Access API"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="packages.html">Prev</a> </td><th width="60%" align="center">Chapter 4. OpenACS Developer's Guide</th><td width="20%" align="right"> <a accesskey="n" href="db-api.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="request-processor"></a>The Request Processor</h2></div></div><div class="authorblurb"><p><p>By <a href="mailto:psu@arsdigita.com" target="_top">Pete Su</a></p><br>
+ OpenACS docs are written by the named authors, but may be edited
+ by OpenACS documentation staff.
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="rp-overview"></a>Overview</h3></div></div><p>
This document is a brief introduction to the OpenACS 4.5 Request Processor;
more details can be found in the <a href="rp-design.html">OpenACS 4 Request Processor Design</a>. Here we cover the high level concepts behind the
system, and implications and usage for the application developer.
-</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="rp-theoldway"></a>The Old Way</h3></div></div>
-<p>
+</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="rp-theoldway"></a>The Old Way</h3></div></div><p>
In older versions of the OpenACS, the mapping between URLs and pages was
simple. AOLserver (the usual webserver for the OpenACS) would find the
appropriate file by appending the server's page-root to the path in
@@ -50,14 +18,10 @@
mechanism for the following requirements of larger web services:
-<div class="itemizedlist"><ul>
-<li style="list-style-type: opencircle"><p>Support for more flexible mappings from URLs to content
- </p></li>
-<li style="list-style-type: opencircle"><p>Robust user authentication
- </p></li>
-<li style="list-style-type: opencircle"><p>Page level access control
- </p></li>
-</ul></div>
+</p><div class="itemizedlist"><ul type="opencircle"><li style="list-style-type: opencircle"><p>Support for more flexible mappings from URLs to content
+ </p></li><li style="list-style-type: opencircle"><p>Robust user authentication
+ </p></li><li style="list-style-type: opencircle"><p>Page level access control
+ </p></li></ul></div><p>
To achieve this functionality above in OpenACS 3.x, developers used an ad
@@ -66,50 +30,35 @@
Request Processor, along with the OpenACS Package Manager, centralizes and
unifies this functionality, making it more transparent and readily
available to developers.
-</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="rp-thenewway"></a>The New Way</h3></div></div>
-<p>
+</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="rp-thenewway"></a>The New Way</h3></div></div><p>
The 4.5 Request Processor is a global filter and set of Tcl procs that
respond to every incoming URL reaching the server. The following
diagram summarizes the stages of the request processor assuming a URL
request like <tt>http://someserver.com/notes/somepage.adp</tt>.
-<div class="mediaobject"><img src="images/rp-flow.gif" align="center"></div>
+</p><div class="mediaobject"><img src="images/rp-flow.gif" align="center" longdesc="ld-id5421151.html"><div class="longdesc-link" align="right"><br clear="all"><span style="font-size: 8pt;">[<a href="ld-id5421151.html" target="longdesc">D</a>]</span></div></div><p>
-</p>
-<div class="variablelist"><dl>
-<dt><span class="term">Stage 1: Search Site Map</span></dt>
-<dd>
-<p>
+</p><div class="variablelist"><dl><dt><span class="term">Stage 1: Search Site Map</span></dt><dd><p>
The first thing the RP does is to map the given URL to the appropriate
physical directory in the filesystem, from which to serve content. We
do this by searching the site map data model (touched on in the <a href="packages.html">Packages</a>, and further
discussed in <a href="subsites.html" title="Writing OpenACS 4.5 Application Pages">the section called “Writing OpenACS 4.5 Application Pages”</a>). This data model maps URLs to objects representing
content, and these objects are typically package instances.
-</p>
-<p>
+</p><p>
After looking up the appropriate object, the RP stores the URL, the ID
of the object it found, and the package and package instance the
object belongs to into the environment of the connection. This
environment can be queried using the <tt>ad_conn</tt> procedure,
which is described in detail in <a href="rp-design.html">OpenACS 4 Request Processor Design</a>. The <a href="subsites.html" title="Writing OpenACS 4.5 Application Pages">page
development</a> tutorial shows you how to use this interface to make
your pages aware of which instance was requested.
-</p>
-</dd>
-<dt><span class="term">Stage 2: Authentication</span></dt>
-<dd><p>
+</p></dd><dt><span class="term">Stage 2: Authentication</span></dt><dd><p>
Next, the Request Processor examines the request for session
information. Session information is generally sent from the client
(the user's browser) to the server via cookies. The <a href="security-notes.html" title="OpenACS 4 Security Notes">security/session handler</a> is described in
detail in its own document. It examines the client request and either
extracts or sets up new session tokens for the user.
-</p></dd>
-<dt><span class="term">Stage 3: Authorization</span></dt>
-<dd><p>
+</p></dd><dt><span class="term">Stage 3: Authorization</span></dt><dd><p>
Next, the Request Processor checks if the user has appropriate access
privileges to the requested part of the site. In OpenACS 4.5, access control
is dictated by the <a href="permissions" target="_top">permissions system</a>. In
@@ -119,17 +68,13 @@
such as whehter the user can view a particular piece of content within
a package instance. This automatic check makes it easy to set up
sites with areas that are only accessible to specific groups of users.
-</p></dd>
-<dt><span class="term">Stage 4: URL Processing, File Search</span></dt>
-<dd>
-<p>
+</p></dd><dt><span class="term">Stage 4: URL Processing, File Search</span></dt><dd><p>
Finally, the Request Processor finds the file we intend to serve,
searching the filesystem to locate the actual file that corresponds to
an abstract URL. It searches for files with predefined "magic"
extensions, i.e. files that end with: <tt>.html</tt>,
<tt>.tcl</tt> and <tt>.adp</tt>.
-</p>
-<p>
+</p><p>
If the RP can't find any matching files with the expected extensions,
it will look for virtual-url-handler files, or <tt>.vuh</tt>
files. A <tt>.vuh</tt> file will be executed as if it were a Tcl
@@ -140,126 +85,67 @@
except that they integrate cleanly and correctly with the RP's URL
mapping mechanisms. The details of how to use these files are
described in <a href="rp-design.html">OpenACS 4 Request Processor Design</a>.
-</p>
-<p>
+</p><p>
Once the appropriate file is found, it is either served directly if
it's static content, or sent to the template system or the standard
Tcl interpreter if it's a dynamic page.
-</p>
-</dd>
-</dl></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="rp-basicapi"></a>Basic API</h3></div></div>
-<p>
+</p></dd></dl></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="rp-basicapi"></a>Basic API</h3></div></div><p>
Once the flow of control reaches a dynamic page, the Request Processor
has populated the environment of the request with several pieces of
useful information. The RP's environment is accessible through the
<tt>ad_conn</tt> interface, and the following calls should be
useful to you when developing dynamic pages:
-</p>
-<div class="variablelist"><dl>
-<dt><span class="term"><tt>[ad_conn user_id]</tt>
+</p><div class="variablelist"><dl><dt><span class="term"><tt>[ad_conn user_id]</tt>
-</span></dt>
-<dd><p>
+</span></dt><dd><p>
The ID of the user associated with this request. By convention this is
zero if there is no user.
-</p></dd>
-<dt><span class="term"><tt>[ad_conn session_id]</tt>
+</p></dd><dt><span class="term"><tt>[ad_conn session_id]</tt>
-</span></dt>
-<dd><p>
+</span></dt><dd><p>
The ID of the session associated with this request.
-</p></dd>
-<dt><span class="term"><tt>[ad_conn url]</tt>
+</p></dd><dt><span class="term"><tt>[ad_conn url]</tt>
-</span></dt>
-<dd><p>
+</span></dt><dd><p>
The URL associated with the request.
-</p></dd>
-<dt><span class="term"><tt>[ad_conn urlv]</tt>
+</p></dd><dt><span class="term"><tt>[ad_conn urlv]</tt>
-</span></dt>
-<dd><p>
+</span></dt><dd><p>
The URL associated with the request, represented as a list instead of
a single string.
-</p></dd>
-<dt><span class="term"><tt>[ad_conn file]</tt>
+</p></dd><dt><span class="term"><tt>[ad_conn file]</tt>
-</span></dt>
-<dd><p>
+</span></dt><dd><p>
The actual local filesystem path of the file that is being served.
-</p></dd>
-<dt><span class="term"><tt>[ad_conn object_url]</tt>
+</p></dd><dt><span class="term"><tt>[ad_conn object_url]</tt>
-</span></dt>
-<dd><p>
+</span></dt><dd><p>
If the URL refers to a site map object, this is the URL to the root
of the tree where the object is mounted.
-</p></dd>
-<dt><span class="term"><tt>[ad_conn package_url]</tt>
+</p></dd><dt><span class="term"><tt>[ad_conn package_url]</tt>
-</span></dt>
-<dd><p>
+</span></dt><dd><p>
If the URL refers to a package instance, this is the URL to the root
of the tree where the package is mounted.
-</p></dd>
-<dt><span class="term"><tt>[ad_conn extra_url]</tt>
+</p></dd><dt><span class="term"><tt>[ad_conn extra_url]</tt>
-</span></dt>
-<dd><p>
+</span></dt><dd><p>
If we found the URL in the site map, this is the tail of the URL
following the part that matched a site map entry.
-</p></dd>
-<dt><span class="term"><tt>[ad_conn object_id]</tt>
+</p></dd><dt><span class="term"><tt>[ad_conn object_id]</tt>
-</span></dt>
-<dd><p>
+</span></dt><dd><p>
If the URL refers to a site map object, this is the ID of that object.
-</p></dd>
-<dt><span class="term"><tt>[ad_conn package_id]</tt>
+</p></dd><dt><span class="term"><tt>[ad_conn package_id]</tt>
-</span></dt>
-<dd><p>
+</span></dt><dd><p>
If the URL refers to a package instance, this is the ID of that
package instance.
-</p></dd>
-<dt><span class="term"><tt>[ad_conn package_key]</tt>
+</p></dd><dt><span class="term"><tt>[ad_conn package_key]</tt>
-</span></dt>
-<dd><p>
+</span></dt><dd><p>
If the URL refers to a package instance, this is the unique key name
of the package.
-</p></dd>
-</dl></div>
-<p><div class="cvstag">($Id$)</div></p>
-</div>
-</div>
-<div class="navfooter">
-<hr>
-<table width="100%" summary="Navigation footer">
-<tr>
-<td width="40%" align="left">
-<a accesskey="p" href="packages.html">Prev</a> </td>
-<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
-<td width="40%" align="right"> <a accesskey="n" href="db-api.html">Next</a>
-</td>
-</tr>
-<tr>
-<td width="40%" align="left">OpenACS 4.5 Packages </td>
-<td width="20%" align="center"><a accesskey="u" href="dev-guide.html">Up</a></td>
-<td width="40%" align="right"> The OpenACS Database Access API</td>
-</tr>
-</table>
-<hr>
-<address>
- rmello at fslc.usu.edu
- </address>
-<address><a href="mailto:vinod@kurup.com">
+</p></dd></dl></div><p><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="packages.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="db-api.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS 4.5 Packages </td><td width="20%" align="center"><a accesskey="u" href="dev-guide.html">Up</a></td><td width="40%" align="right"> The OpenACS Database Access API</td></tr></table><hr><address>rmello at fslc.usu.edu</address><address><a href="mailto:vinod@kurup.com">
vinod@kurup.com
- </a></address>
-</div>
-</body>
-</html>
+ </a></address></div></body></html>
Index: openacs-4/packages/acs-core-docs/www/requirements-template.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/requirements-template.html,v
diff -u -r1.7 -r1.7.2.1
--- openacs-4/packages/acs-core-docs/www/requirements-template.html 7 Mar 2002 06:55:36 -0000 1.7
+++ openacs-4/packages/acs-core-docs/www/requirements-template.html 15 May 2002 23:26:18 -0000 1.7.2.1
@@ -1,242 +1,86 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type">
-<title>System/Application Requirements Template</title>
-<meta name="generator" content="DocBook XSL Stylesheets V1.45">
-<link rel="home" href="index.html" title="OpenACS Documentation">
-<link rel="up" href="eng-standards.html" title="Chapter 6. Engineering Standards">
-<link rel="previous" href="filename.html" title="Detailed Design Documentation Template">
-<link rel="next" href="eng-standards-versioning.html" title="Release Version Numbering">
-<link rel="stylesheet" href="openacs.css" type="text/css">
-</head>
-<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-<div class="navheader">
-<a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr>
-<td width="20%" align="left">
-<a accesskey="p" href="filename.html">Prev</a> </td>
-<th width="60%" align="center">Chapter 6. Engineering Standards</th>
-<td width="20%" align="right"> <a accesskey="n" href="eng-standards-versioning.html">Next</a>
-</td>
-</tr></table>
-<hr>
-</div>
-<div class="sect1">
-<div class="titlepage"><div><h2 class="title" style="clear: both">
-<a name="requirements-template"></a>System/Application Requirements Template</h2></div></div>
-<div class="authorblurb"><p>By <a href="mailto:youremail@arsdigita.com" target="_top">You</a>
-</p></div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="yourpackage-requirements-introduction"></a>Introduction</h3></div></div>
-<p>
- <span class="emphasis"><i>Briefly explain to the reader what this document is for, whether
+<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"><title>System/Application Requirements Template</title><meta name="generator" content="DocBook XSL Stylesheets V1.50.0"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="eng-standards.html" title="Chapter 6. Engineering Standards"><link rel="previous" href="filename.html" title="Detailed Design Documentation Template"><link rel="next" href="eng-standards-versioning.html" title="Release Version Numbering"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="filename.html">Prev</a> </td><th width="60%" align="center">Chapter 6. Engineering Standards</th><td width="20%" align="right"> <a accesskey="n" href="eng-standards-versioning.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="requirements-template"></a>System/Application Requirements Template</h2></div></div><div class="authorblurb"><p><p>By <a href="mailto:youremail@arsdigita.com" target="_top">You</a></p><br>
+ OpenACS docs are written by the named authors, but may be edited
+ by OpenACS documentation staff.
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="yourpackage-requirements-introduction"></a>Introduction</h3></div></div><p>
+ <span class="emphasis"><em>Briefly explain to the reader what this document is for, whether
it records the requirements for a new system, a client application, a
toolkit subsystem, etc. Remember your audience: fellow programmers,
AND interested non-technical parties such as potential clients, who
may all want to see how rigorous our engineering process is. Here and
everywhere, write clearly and precisely; for requirements
documentation, write at a level that any intelligent layperson can
- understand.</i></span>
- </p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="yourpackage-requirements-vision"></a>Vision Statement</h3></div></div>
-<p>
+ understand.</em></span>
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="yourpackage-requirements-vision"></a>Vision Statement</h3></div></div><p>
- <span class="emphasis"><i>Very broadly, describe how the system meets a need of a business,
+ <span class="emphasis"><em>Very broadly, describe how the system meets a need of a business,
group, the OpenACS as a whole, etc. Make sure that technical and
non-technical readers alike would understand what the system would do
and why it's useful. Whenever applicable, you should explicitly state
- what the business value of the system is. </i></span>
- </p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="yourpackage-requirements-system-app-overview"></a>System/Application Overview</h3></div></div>
-<p>
- <span class="emphasis"><i>Discuss the high-level breakdown of the components that make up
+ what the business value of the system is. </em></span>
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="yourpackage-requirements-system-app-overview"></a>System/Application Overview</h3></div></div><p>
+ <span class="emphasis"><em>Discuss the high-level breakdown of the components that make up
the system. You can go by functional areas, by the main transactions
- the system allows, etc. </i></span>
- </p>
-<p>
- <span class="emphasis"><i>You should also state the context and dependencies of the system
+ the system allows, etc. </em></span>
+ </p><p>
+ <span class="emphasis"><em>You should also state the context and dependencies of the system
here, e.g. if it's an application-level package for OpenACS 4, briefly
- describe how it uses kernel services, like permissions or subsites. </i></span>
- </p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="yourpackage-requirements-cases"></a>Use-cases and User-scenarios</h3></div></div>
-<p>
- <span class="emphasis"><i>Determine the types or classes of users who would use the
+ describe how it uses kernel services, like permissions or subsites. </em></span>
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="yourpackage-requirements-cases"></a>Use-cases and User-scenarios</h3></div></div><p>
+ <span class="emphasis"><em>Determine the types or classes of users who would use the
system, and what their experience would be like at a high-level.
Sketch what their experience would be like and what actions they would
- take, and how the system would support them.</i></span>
- </p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="yourpackage-requirements-competitive-analysis"></a>Optional: Competitive Analysis</h3></div></div>
-<p>
- <span class="emphasis"><i>Describe other systems or services that are comparable to what
+ take, and how the system would support them.</em></span>
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="yourpackage-requirements-competitive-analysis"></a>Optional: Competitive Analysis</h3></div></div><p>
+ <span class="emphasis"><em>Describe other systems or services that are comparable to what
you're building. If applicable, say why your implementation will be
superior, where it will match the competition, and where/why it will
lack existing best-of-breed capabilities. This section is also in the
- Design doc, so write about it where you deem most appropriate.</i></span>
- </p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="yourpackage-requirements-links"></a>Related Links</h3></div></div>
-<p>Include all pertinent links to supporting and related material,
- such as: </p>
-<div class="itemizedlist"><ul>
-<li><p> System/Package "coversheet" - where all documentation for this software is linked off of</p></li>
-<li><p> Design document</p></li>
-<li><p> Developer's guide</p></li>
-<li><p> User's guide</p></li>
-<li><p> Other-cool-system-related-to-this-one document</p></li>
-<li><p> Test plan </p></li>
-<li><p> Competitive system(s)</p></li>
-</ul></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="yourpackage-requirements-requirements"></a>Requirements</h3></div></div>
-<p>
- <span class="emphasis"><i>The main course of the document, requirements. Break up the
+ Design doc, so write about it where you deem most appropriate.</em></span>
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="yourpackage-requirements-links"></a>Related Links</h3></div></div><p>Include all pertinent links to supporting and related material,
+ such as: </p><div class="itemizedlist"><ul type="disc"><li><p> System/Package "coversheet" - where all documentation for this software is linked off of</p></li><li><p> Design document</p></li><li><p> Developer's guide</p></li><li><p> User's guide</p></li><li><p> Other-cool-system-related-to-this-one document</p></li><li><p> Test plan </p></li><li><p> Competitive system(s)</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="yourpackage-requirements-requirements"></a>Requirements</h3></div></div><p>
+ <span class="emphasis"><em>The main course of the document, requirements. Break up the
requirements sections (A, B, C, etc.) as needed. Within each section,
create a list denominated with unique identifiers that reflect any
functional hierarchy present, e.g. 20.5.13. - for the first number,
leave generous gaps on the first writing of requirements (e.g. 1, 10,
20, 30, 40, etc.) because you'll want to leave room for any missing
- key requirements that may arise. </i></span>
- </p>
-<div class="itemizedlist"><ul><li>
-<p><span class="strong"><i>10.0 A Common Solution</i></span></p>
-<p>
+ key requirements that may arise. </em></span>
+ </p><div class="itemizedlist"><ul type="disc"><li><p><span class="strong"><em>10.0 A Common Solution</em></span></p><p>
Programmers and designers should only have to learn a single
system that serves as a UI substrate for all the functionally
specific modules in the toolkit.
- </p>
-<blockquote class="blockquote">
-<p><span class="strong"><i>10.0.1</i></span></p>
-<p>
+ </p><blockquote class="blockquote"><p><span class="strong"><em>10.0.1</em></span></p><p>
The system should not make any assumptions about how pages should
look or function.
- </p>
-<p><span class="strong"><i>10.0.5</i></span></p>
-<p>
+ </p><p><span class="strong"><em>10.0.5</em></span></p><p>
Publishers should be able to change the default presentation of
any module using a single methodology with minimal exposure to
code.
- </p>
-</blockquote>
-</li></ul></div>
-<p>
+ </p></blockquote></li></ul></div><p>
For guidelines writing requirements, take a
<a href="http://www.arsdigita.com/ad-sepg/process/requirements-quality.html" target="_top">look
at the quality standards</a>, along with a good example, such as <a href="apm-requirements.html">OpenACS 4.5 Package Manager Requirements</a>.
- </p>
-<p>
+ </p><p>
Besides writing requirements in natural language, consider using the
following techniques as needed:
- </p>
-<div class="itemizedlist"><ul>
-<li><p> Pseudocode - a quasi programming language, combining the
+ </p><div class="itemizedlist"><ul type="disc"><li><p> Pseudocode - a quasi programming language, combining the
informality of natural language with the strict syntax and control
- structures of a programming language. </p></li>
-<li><p> Finite State Machines - a hypothetical machine that can be in
+ structures of a programming language. </p></li><li><p> Finite State Machines - a hypothetical machine that can be in
only one of a given number of states at any specific time. Useful to
model situations that are rigidly deterministic, that is, any set of
- inputs mathematically determines the system outputs. </p></li>
-<li><p> Decision Trees and Decision Tables - similar to FSMs, but better
- suited to handle combinations of inputs. </p></li>
-<li><p> Flowcharts - easy to draw and understand, suited for event and
- decision driven systems. UML is the industry standard here.</p></li>
-<li><p> Entity-Relationship diagrams - a necessary part of Design
+ inputs mathematically determines the system outputs. </p></li><li><p> Decision Trees and Decision Tables - similar to FSMs, but better
+ suited to handle combinations of inputs. </p></li><li><p> Flowcharts - easy to draw and understand, suited for event and
+ decision driven systems. UML is the industry standard here.</p></li><li><p> Entity-Relationship diagrams - a necessary part of Design
documents, sometimes a high-level ER diagram is useful for
- requirements as well.</p></li>
-</ul></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="yourpackage-requirements-implementation"></a>Optional: Implementation Notes</h3></div></div>
-<p>
- <span class="emphasis"><i>Although in theory coding comes after design, which comes after
+ requirements as well.</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="yourpackage-requirements-implementation"></a>Optional: Implementation Notes</h3></div></div><p>
+ <span class="emphasis"><em>Although in theory coding comes after design, which comes after
requirements, we do not, and perhaps should not, always follow such a
rigid process (a.k.a. the waterfall lifecyle). Often, there is a
pre-existing system or prototype first, and thus you may want to write
some thoughts on implementation, for aiding and guiding yourself or
- other programmers. </i></span>
- </p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="yourpackage-revision-history"></a>Revision History</h3></div></div>
-<div class="informaltable"><table border="1">
-<colgroup>
-<col>
-<col>
-<col>
-<col>
-</colgroup>
-<thead><tr>
-<th>Document Revision #</th>
-<th>Action Taken, Notes</th>
-<th>When?</th>
-<th>By Whom?</th>
-</tr></thead>
-<tbody>
-<tr>
-<td>0.3</td>
-<td>Edited further, incorporated feedback from Michael Yoon</td>
-<td>9/05/2000</td>
-<td>Kai Wu</td>
-</tr>
-<tr>
-<td>0.2</td>
-<td>Edited</td>
-<td>8/22/2000</td>
-<td>Kai Wu</td>
-</tr>
-<tr>
-<td>0.1</td>
-<td>Created</td>
-<td>8/21/2000</td>
-<td>Josh Finkler, Audrey McLoghlin</td>
-</tr>
-</tbody>
-</table></div>
-<p><div class="cvstag">($Id$)</div></p>
-</div>
-</div>
-<div class="navfooter">
-<hr>
-<table width="100%" summary="Navigation footer">
-<tr>
-<td width="40%" align="left">
-<a accesskey="p" href="filename.html">Prev</a> </td>
-<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
-<td width="40%" align="right"> <a accesskey="n" href="eng-standards-versioning.html">Next</a>
-</td>
-</tr>
-<tr>
-<td width="40%" align="left">Detailed Design Documentation Template </td>
-<td width="20%" align="center"><a accesskey="u" href="eng-standards.html">Up</a></td>
-<td width="40%" align="right"> Release Version Numbering</td>
-</tr>
-</table>
-<hr>
-<address>
- rmello at fslc.usu.edu
- </address>
-<address><a href="mailto:vinod@kurup.com">
+ other programmers. </em></span>
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="yourpackage-revision-history"></a>Revision History</h3></div></div><div class="informaltable"><table border="1"><colgroup><col><col><col><col></colgroup><thead><tr><th>Document Revision #</th><th>Action Taken, Notes</th><th>When?</th><th>By Whom?</th></tr></thead><tbody><tr><td>0.3</td><td>Edited further, incorporated feedback from Michael Yoon</td><td>9/05/2000</td><td>Kai Wu</td></tr><tr><td>0.2</td><td>Edited</td><td>8/22/2000</td><td>Kai Wu</td></tr><tr><td>0.1</td><td>Created</td><td>8/21/2000</td><td>Josh Finkler, Audrey McLoghlin</td></tr></tbody></table></div><p><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="filename.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="eng-standards-versioning.html">Next</a></td></tr><tr><td width="40%" align="left">Detailed Design Documentation Template </td><td width="20%" align="center"><a accesskey="u" href="eng-standards.html">Up</a></td><td width="40%" align="right"> Release Version Numbering</td></tr></table><hr><address>rmello at fslc.usu.edu</address><address><a href="mailto:vinod@kurup.com">
vinod@kurup.com
- </a></address>
-</div>
-</body>
-</html>
+ </a></address></div></body></html>
Index: openacs-4/packages/acs-core-docs/www/rp-design.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/rp-design.html,v
diff -u -r1.5 -r1.5.2.1
--- openacs-4/packages/acs-core-docs/www/rp-design.html 7 Mar 2002 06:55:36 -0000 1.5
+++ openacs-4/packages/acs-core-docs/www/rp-design.html 15 May 2002 23:26:18 -0000 1.5.2.1
@@ -1,130 +1,55 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type">
-<title>OpenACS 4 Request Processor Design</title>
-<meta name="generator" content="DocBook XSL Stylesheets V1.45">
-<link rel="home" href="index.html" title="OpenACS Documentation">
-<link rel="up" href="kernel-doc.html" title="Chapter 7. Kernel Documentation">
-<link rel="previous" href="rp-requirements.html" title="OpenACS 4 Request Processor Requirements">
-<link rel="next" href="db-api-detailed.html" title="Database Access API">
-<link rel="stylesheet" href="openacs.css" type="text/css">
-</head>
-<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-<div class="navheader">
-<a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr>
-<td width="20%" align="left">
-<a accesskey="p" href="rp-requirements.html">Prev</a> </td>
-<th width="60%" align="center">Chapter 7. Kernel Documentation</th>
-<td width="20%" align="right"> <a accesskey="n" href="db-api-detailed.html">Next</a>
-</td>
-</tr></table>
-<hr>
-</div>
-<div class="sect1">
-<div class="titlepage"><div><h2 class="title" style="clear: both">
-<a name="rp-design"></a>OpenACS 4 Request Processor Design</h2></div></div>
-<div class="authorblurb"><p>
-by <a href="http://planitia.org" target="_top">Rafael H. Schloming</a>
-</p></div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="rp-design-essentials"></a>Essentials</h3></div></div>
-<div class="itemizedlist"><ul>
-<li><p><a href="rp-requirements.html">OpenACS 4 Request Processor Requirements</a></p></li>
-<li><p><a href="/api-doc/procs-file-view?path=packages/acs-kernel/tcl/request-processor-procs.tcl" target="_top">
-/packages/acs-kernel/tcl/request-processor-procs.tcl</a></p></li>
-<li><p><a href="/api-doc/procs-file-view?path=packages/acs-kernel/tcl/request-processor-init.tcl" target="_top">
-/packages/acs-kernel/tcl/request-processor-init.tcl</a></p></li>
-<li><p><a href="/api-doc/procs-file-view?path=packages/acs-kernel/tcl/site-nodes-procs.tcl" target="_top">
-/packages/acs-kernel/tcl/site-nodes-procs.tcl</a></p></li>
-<li><p><a href="/api-doc/procs-file-view?path=packages/acs-kernel/tcl/site-nodes-init.tcl" target="_top">
-/packages/acs-kernel/tcl/site-nodes-init.tcl</a></p></li>
-<li><p><a href="/doc/sql/display-sql?package_key=acs-kernel&url=site-nodes-create.sql" target="_top">
-/packages/acs-kernel/sql/site-nodes-create.sql</a></p></li>
-</ul></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="rp-design-intro"></a>Introduction</h3></div></div>
-<p>The request processor is the set of procs that responds to every HTTP
+<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"><title>OpenACS 4 Request Processor Design</title><meta name="generator" content="DocBook XSL Stylesheets V1.50.0"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="kernel-doc.html" title="Chapter 7. Kernel Documentation"><link rel="previous" href="rp-requirements.html" title="OpenACS 4 Request Processor Requirements"><link rel="next" href="db-api-detailed.html" title="Database Access API"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="rp-requirements.html">Prev</a> </td><th width="60%" align="center">Chapter 7. Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="db-api-detailed.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="rp-design"></a>OpenACS 4 Request Processor Design</h2></div></div><div class="authorblurb"><p>
+by <a href="http://planitia.org" target="_top">Rafael H. Schloming</a><br>
+ OpenACS docs are written by the named authors, but may be edited
+ by OpenACS documentation staff.
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="rp-design-essentials"></a>Essentials</h3></div></div><div class="itemizedlist"><ul type="disc"><li><p><a href="rp-requirements.html">OpenACS 4 Request Processor Requirements</a></p></li><li><p><a href="/api-doc/procs-file-view?path=packages/acs-kernel/tcl/request-processor-procs.tcl" target="_top">
+/packages/acs-kernel/tcl/request-processor-procs.tcl</a></p></li><li><p><a href="/api-doc/procs-file-view?path=packages/acs-kernel/tcl/request-processor-init.tcl" target="_top">
+/packages/acs-kernel/tcl/request-processor-init.tcl</a></p></li><li><p><a href="/api-doc/procs-file-view?path=packages/acs-kernel/tcl/site-nodes-procs.tcl" target="_top">
+/packages/acs-kernel/tcl/site-nodes-procs.tcl</a></p></li><li><p><a href="/api-doc/procs-file-view?path=packages/acs-kernel/tcl/site-nodes-init.tcl" target="_top">
+/packages/acs-kernel/tcl/site-nodes-init.tcl</a></p></li><li><p><a href="/doc/sql/display-sql?package_key=acs-kernel%26amp;url=site-nodes-create.sql" target="_top">
+/packages/acs-kernel/sql/site-nodes-create.sql</a></p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="rp-design-intro"></a>Introduction</h3></div></div><p>The request processor is the set of procs that responds to every HTTP
request made to the OpenACS. The request processor must authenticate the
connecting user, and make sure that he is authorized to perform the given
request. If these steps succeed, then the request processor must locate the
file that is associated with the specified URL, and serve the content it
-provides to the browser.</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="rp-design-related-systems"></a>Related Systems</h3></div></div>
-<div class="itemizedlist"><ul><li><p><a href="apm-design.html">OpenACS 4.5 Package Manager Design</a></p></li></ul></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="rp-design-terminology"></a>Terminology</h3></div></div>
-<div class="itemizedlist"><ul>
-<li><p>
-<span class="strong"><i>pageroot</i></span> -- Any directory that contains scripts and/or
+provides to the browser.</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="rp-design-related-systems"></a>Related Systems</h3></div></div><div class="itemizedlist"><ul type="disc"><li><p><a href="apm-design.html">OpenACS 4.5 Package Manager Design</a></p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="rp-design-terminology"></a>Terminology</h3></div></div><div class="itemizedlist"><ul type="disc"><li><p>
+<span class="strong"><em>pageroot</em></span> -- Any directory that contains scripts and/or
static files intended to be served in response to HTTP requests. A typical
-OpenACS installation is required to serve files from multiple pageroots.</p></li>
-<li><p>
-<span class="strong"><i>global pageroot</i></span>
-(<span class="strong"><i>/web/<span class="emphasis"><i>servicename</i></span>/www</i></span>) -- Files appearing under
+OpenACS installation is required to serve files from multiple pageroots.</p></li><li><p><span class="strong"><em>global pageroot</em></span>
+(<span class="strong"><em>/web/<span class="emphasis"><em>servicename</em></span>/www</em></span>) -- Files appearing under
this pageroot will be served directly off the base url
-http://www.<span class="emphasis"><i>servicename</i></span>.com/</p></li>
-<li><p>
-<span class="strong"><i>package root</i></span>
-(<span class="strong"><i>/web/<span class="emphasis"><i>servicename</i></span>/packages</i></span>) -- Each subdirectory of
+http://www.<span class="emphasis"><em>servicename</em></span>.com/</p></li><li><p><span class="strong"><em>package root</em></span>
+(<span class="strong"><em>/web/<span class="emphasis"><em>servicename</em></span>/packages</em></span>) -- Each subdirectory of
the package root is a package. A typical OpenACS installation will have several
-packages.</p></li>
-<li><p>
-<span class="strong"><i>package pageroot</i></span>
-(<span class="strong"><i>/web/<span class="emphasis"><i>servicename</i></span>/packages/<span class="emphasis"><i>package_key</i></span>/www</i></span>)
--- This is the pageroot for the <span class="emphasis"><i>package_key</i></span> package.</p></li>
-<li><p>
-<span class="strong"><i>request environment</i></span> (<span class="strong"><i>ad_conn</i></span>) -- This is
+packages.</p></li><li><p><span class="strong"><em>package pageroot</em></span>
+(<span class="strong"><em>/web/<span class="emphasis"><em>servicename</em></span>/packages/<span class="emphasis"><em>package_key</em></span>/www</em></span>)
+-- This is the pageroot for the <span class="emphasis"><em>package_key</em></span> package.</p></li><li><p><span class="strong"><em>request environment</em></span> (<span class="strong"><em>ad_conn</em></span>) -- This is
a global namespace containing variables associated with the current
-request.</p></li>
-<li><p>
-<span class="strong"><i>abstract URL</i></span> -- A URL with no extension that doesn't
-directly correspond to a file in the filesystem.</p></li>
-<li><p>
-<span class="strong"><i>abstract file</i></span> or <span class="strong"><i>abstract path</i></span> -- A URL
+request.</p></li><li><p><span class="strong"><em>abstract URL</em></span> -- A URL with no extension that doesn't
+directly correspond to a file in the filesystem.</p></li><li><p><span class="strong"><em>abstract file</em></span> or <span class="strong"><em>abstract path</em></span> -- A URL
that has been translated into a file system path (probably by prepending the
appropriate pageroot), but still doesn't have any extension and so does
-not directly correspond to a file in the filesystem.</p></li>
-<li><p>
-<span class="strong"><i>concrete file</i></span> or <span class="strong"><i>concrete path</i></span> -- A file
-or path that actually references something in the filesystem.</p></li>
-</ul></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="rp-design-system-overview"></a>System Overview</h3></div></div>
-<p><span class="strong"><i>Package Lookup</i></span></p>
-<p>One of the first things the request processor must do is to determine
+not directly correspond to a file in the filesystem.</p></li><li><p><span class="strong"><em>concrete file</em></span> or <span class="strong"><em>concrete path</em></span> -- A file
+or path that actually references something in the filesystem.</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="rp-design-system-overview"></a>System Overview</h3></div></div><p><span class="strong"><em>Package Lookup</em></span></p><p>One of the first things the request processor must do is to determine
which package instance a given request references, and based on this
information, which pageroot to use when searching for a file to serve. During
this process the request processor divides the URL into two pieces. The first
portion identifies the package instance. The rest identifies the path into
the package pageroot. For example if the news package is mounted on
/offices/boston/announcements/, then a request for
/offices/boston/announcements/index would be split into the
-<span class="strong"><i>package_url</i></span> (/offices/boston/announcements/), and the
+<span class="strong"><em>package_url</em></span> (/offices/boston/announcements/), and the
abstract (no extension info) file path (index). The request processor must be
-able to figure out which <span class="strong"><i>package_id</i></span> is associated with a
+able to figure out which <span class="strong"><em>package_id</em></span> is associated with a
given package_url, and package mountings must be persistent across server
restarts and users must be able to manipulate the mountings on a live site,
-therefore this mapping is stored in the database.</p>
-<p><span class="strong"><i>Authentication and Authorization</i></span></p>
-<p>Once the request processor has located both the package_id and concrete
+therefore this mapping is stored in the database.</p><p><span class="strong"><em>Authentication and Authorization</em></span></p><p>Once the request processor has located both the package_id and concrete
file associated with the request, authentication is performed by the <a href="../sessions.html" target="_top">session</a> security system. After authentication has
been performed the user is authorized to have read access for the given
package by the <a href="permissions-design.html">OpenACS 4 Permissions Design</a>.
If authorization succeeds then the request is served, otherwise it is
-aborted.</p>
-<p><span class="strong"><i>Concrete File Search</i></span></p>
-<p>To actually serve a file, the request processor generates an ordered list
+aborted.</p><p><span class="strong"><em>Concrete File Search</em></span></p><p>To actually serve a file, the request processor generates an ordered list
of abstract paths and searches each path for a concrete file. The first path
searched is composed of the package pageroot with the extra portion of the
URL appended. The second abstract path consists of the global pageroot with
@@ -135,179 +60,45 @@
directory. Files take precedence over directory listings, so an index file in
the global pageroot will be served instead of a directory listing in the
package pageroot, even though the global pageroot is searched later. If a
-file is found at any of the searched locations then it is served.</p>
-<p><span class="strong"><i>Virtual URL Handlers</i></span></p>
-<p>If no file is found during the concrete file search, then the request
-processor searches the filesystem for a <span class="strong"><i>virtual url handler</i></span>
-(<span class="strong"><i>.vuh</i></span>) file. This file contains normal tcl code, and is in
+file is found at any of the searched locations then it is served.</p><p><span class="strong"><em>Virtual URL Handlers</em></span></p><p>If no file is found during the concrete file search, then the request
+processor searches the filesystem for a <span class="strong"><em>virtual url handler</em></span>
+(<span class="strong"><em>.vuh</em></span>) file. This file contains normal tcl code, and is in
fact handled by the same extension handling procedure that handles .tcl
files. The only way this file is treated differently is in how the request
processor searches for it. When a lookup fails, the request processor
generates each valid prefix of all the abstract paths considered in the
concrete file search, and searches these prefixes in order from most specific
to least specific for a matching .vuh file. If a file is found then the
-ad_conn variable <span class="strong"><i>path_info</i></span> is set to the portion of the url
-<span class="emphasis"><i>not</i></span> matched by the .vuh script, and the script is sourced. This
+ad_conn variable <span class="strong"><em>path_info</em></span> is set to the portion of the url
+<span class="emphasis"><em>not</em></span> matched by the .vuh script, and the script is sourced. This
facility is intended to replace the concept of registered procs, since no
special distinction is required between sitewide procs and package specific
procs when using this facility. It is also much less prone to overlap and
confusion than the use of registered procs, especially in an environment with
-many packages installed.</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="rp-design-site-nodes"></a>Site Nodes</h3></div></div>
-<p>The request processor manages the mappings from URL patterns to package
+many packages installed.</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="rp-design-site-nodes"></a>Site Nodes</h3></div></div><p>The request processor manages the mappings from URL patterns to package
instances with the site_nodes data model. Every row in the site_nodes table
represents a fully qualified URL. A package can be mounted on any node in
this data model. When the request processor performs a URL lookup, it
determines which node matches the longest possible prefix of the request URI.
In order to make this lookup operation as fast as possible, the rows in the
site_nodes table are pulled out of the database at server startup, and stored
-in memory.</p>
-<p>The memory structure used to store the site_nodes mapping is a hash table
+in memory.</p><p>The memory structure used to store the site_nodes mapping is a hash table
that maps from the fully qualified URL of the node, to the package_id and
package_key of the package instance mounted on the node. A lookup is
performed by starting with the full request URI and successively stripping
off the rightmost path components until a match is reached. This way the time
required to lookup a URL is proportional to the length of the URL, not to the
-number of entries in the mapping.</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="rp-design-req-env"></a>Request Environment</h3></div></div>
-<p>The request environment is managed by the procedure
-<span class="strong"><i>ad_conn</i></span>. Variables can be set and retrieved through use of
+number of entries in the mapping.</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="rp-design-req-env"></a>Request Environment</h3></div></div><p>The request environment is managed by the procedure
+<span class="strong"><em>ad_conn</em></span>. Variables can be set and retrieved through use of
the ad_conn procedure. The following variables are available for public use.
If the ad_conn procedure doesn't recognize a variable being passed to it
for a lookup, it tries to get a value using ns_conn. This guarantees that
-ad_conn subsumes the functionality of ns_conn.</p>
-<div class="informaltable"><table border="0">
-<colgroup>
-<col>
-<col>
-</colgroup>
-<tbody>
-<tr><td><span class="strong"><i>Request processor</i></span></td></tr>
-<tr>
-<td valign="top"><tt>[ad_conn urlv]</tt></td>
-<td valign="top">A list containing each element of the URL</td>
-</tr>
-<tr>
-<td valign="top"><tt>[ad_conn url]</tt></td>
-<td valign="top">The URL associated with the request.</td>
-</tr>
-<tr>
-<td valign="top"><tt>[ad_conn file]</tt></td>
-<td valign="top">The filepath including filename of the file being served</td>
-</tr>
-<tr>
-<td valign="top"><tt>[ad_conn request]</tt></td>
-<td valign="top">The number of requests since the server was last started</td>
-</tr>
-<tr>
-<td valign="top"><tt>[ad_conn start_clicks]</tt></td>
-<td valign="top">The system time when the RP starts handling the request</td>
-</tr>
-<tr><td>�</td></tr>
-<tr><td>
-<span class="strong"><i>Session System Variables</i></span>: set in
-sec_handler, check security with ad_validate_security_info</td></tr>
-<tr>
-<td valign="top"><tt>[ad_conn session_id]</tt></td>
-<td valign="top">The unique session_id coming from the sequence
-<tt>sec_id_seq</tt>
-</td>
-</tr>
-<tr>
-<td valign="top"><tt>[ad_conn user_id]</tt></td>
-<td valign="top">User_id of a person if the person is logged in. Otherwise, it is
-blank</td>
-</tr>
-<tr>
-<td valign="top"><tt>[ad_conn sec_validated]</tt></td>
-<td valign="top">This becomes "secure" when the connection uses SSL</td>
-</tr>
-<tr><td>�</td></tr>
-<tr><td><span class="strong"><i>Database API</i></span></td></tr>
-<tr>
-<td valign="top"><tt>[ad_conn db,handles]</tt></td>
-<td valign="top">What are the list of handles available to AOL?</td>
-</tr>
-<tr>
-<td valign="top"><tt>[ad_conn db,n_handles_used]</tt></td>
-<td valign="top">How many database handles are currently used?</td>
-</tr>
-<tr>
-<td valign="top"><tt>[ad_conn db,last_used]</tt></td>
-<td valign="top">Which database handle did we use last?</td>
-</tr>
-<tr>
-<td valign="top"><tt>[ad_conn db,transaction_level,$db]</tt></td>
-<td valign="top">Specifies what transaction level we are in</td>
-</tr>
-<tr>
-<td valign="top"><tt>[ad_conn db,db_abort_p,$dbh]</tt></td>
-<td valign="top">Whether the transaction is aborted</td>
-</tr>
-<tr><td>�</td></tr>
-<tr><td><span class="strong"><i>APM</i></span></td></tr>
-<tr>
-<td valign="top"><tt>[ad_conn xml_loaded_p]</tt></td>
-<td valign="top">Checks whether the XML parser is loaded so that it only gets loaded once.
-Set in apm_load_xml_packages</td>
-</tr>
-<tr><td>�</td></tr>
-<tr><td><span class="strong"><i>Packages</i></span></td></tr>
-<tr>
-<td valign="top"><tt>[ad_conn package_id]</tt></td>
-<td valign="top">The package_id of the package associated with the URL.</td>
-</tr>
-<tr>
-<td valign="top"><tt>[ad_conn package_url]</tt></td>
-<td valign="top">The URL on which the package is mounted.</td>
-</tr>
-<tr><td>�</td></tr>
-<tr><td><span class="strong"><i>Miscellaneous</i></span></td></tr>
-<tr>
-<td valign="top"><tt>[ad_conn system_p]</tt></td>
-<td valign="top">If true then the request has been made to one of the special directories
+ad_conn subsumes the functionality of ns_conn.</p><div class="informaltable"><table border="0"><colgroup><col><col></colgroup><tbody><tr><td colspan="2"><span class="strong"><em>Request processor</em></span></td></tr><tr><td valign="top"><tt>[ad_conn urlv]</tt></td><td valign="top">A list containing each element of the URL</td></tr><tr><td valign="top"><tt>[ad_conn url]</tt></td><td valign="top">The URL associated with the request.</td></tr><tr><td valign="top"><tt>[ad_conn file]</tt></td><td valign="top">The filepath including filename of the file being served</td></tr><tr><td valign="top"><tt>[ad_conn request]</tt></td><td valign="top">The number of requests since the server was last started</td></tr><tr><td valign="top"><tt>[ad_conn start_clicks]</tt></td><td valign="top">The system time when the RP starts handling the request</td></tr><tr><td colspan="2">�</td></tr><tr><td colspan="2"><span class="strong"><em>Session System Variables</em></span>: set in
+sec_handler, check security with ad_validate_security_info</td></tr><tr><td valign="top"><tt>[ad_conn session_id]</tt></td><td valign="top">The unique session_id coming from the sequence
+<tt>sec_id_seq</tt></td></tr><tr><td valign="top"><tt>[ad_conn user_id]</tt></td><td valign="top">User_id of a person if the person is logged in. Otherwise, it is
+blank</td></tr><tr><td valign="top"><tt>[ad_conn sec_validated]</tt></td><td valign="top">This becomes "secure" when the connection uses SSL</td></tr><tr><td colspan="2">�</td></tr><tr><td colspan="2"><span class="strong"><em>Database API</em></span></td></tr><tr><td valign="top"><tt>[ad_conn db,handles]</tt></td><td valign="top">What are the list of handles available to AOL?</td></tr><tr><td valign="top"><tt>[ad_conn db,n_handles_used]</tt></td><td valign="top">How many database handles are currently used?</td></tr><tr><td valign="top"><tt>[ad_conn db,last_used]</tt></td><td valign="top">Which database handle did we use last?</td></tr><tr><td valign="top"><tt>[ad_conn db,transaction_level,$db]</tt></td><td valign="top">Specifies what transaction level we are in</td></tr><tr><td valign="top"><tt>[ad_conn db,db_abort_p,$dbh]</tt></td><td valign="top">Whether the transaction is aborted</td></tr><tr><td colspan="2">�</td></tr><tr><td colspan="2"><span class="strong"><em>APM</em></span></td></tr><tr><td valign="top"><tt>[ad_conn xml_loaded_p]</tt></td><td valign="top">Checks whether the XML parser is loaded so that it only gets loaded once.
+Set in apm_load_xml_packages</td></tr><tr><td colspan="2">�</td></tr><tr><td colspan="2"><span class="strong"><em>Packages</em></span></td></tr><tr><td valign="top"><tt>[ad_conn package_id]</tt></td><td valign="top">The package_id of the package associated with the URL.</td></tr><tr><td valign="top"><tt>[ad_conn package_url]</tt></td><td valign="top">The URL on which the package is mounted.</td></tr><tr><td colspan="2">�</td></tr><tr><td colspan="2"><span class="strong"><em>Miscellaneous</em></span></td></tr><tr><td valign="top"><tt>[ad_conn system_p]</tt></td><td valign="top">If true then the request has been made to one of the special directories
specified in the config file (somewhere), and no authentication or
-authorization has been performed.</td>
-</tr>
-<tr><td>�</td></tr>
-<tr><td><span class="strong"><i>Documentation</i></span></td></tr>
-<tr>
-<td valign="top"><tt>[ad_conn api_page_documentation_mode_p]</tt></td>
-<td valign="top">�</td>
-</tr>
-</tbody>
-</table></div>
-</div>
-</div>
-<div class="navfooter">
-<hr>
-<table width="100%" summary="Navigation footer">
-<tr>
-<td width="40%" align="left">
-<a accesskey="p" href="rp-requirements.html">Prev</a> </td>
-<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
-<td width="40%" align="right"> <a accesskey="n" href="db-api-detailed.html">Next</a>
-</td>
-</tr>
-<tr>
-<td width="40%" align="left">OpenACS 4 Request Processor Requirements </td>
-<td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td>
-<td width="40%" align="right"> Database Access API</td>
-</tr>
-</table>
-<hr>
-<address>
- rmello at fslc.usu.edu
- </address>
-<address><a href="mailto:vinod@kurup.com">
+authorization has been performed.</td></tr><tr><td colspan="2">�</td></tr><tr><td colspan="2"><span class="strong"><em>Documentation</em></span></td></tr><tr><td valign="top"><tt>[ad_conn api_page_documentation_mode_p]</tt></td><td valign="top">�</td></tr></tbody></table></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="rp-requirements.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="db-api-detailed.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS 4 Request Processor Requirements </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> Database Access API</td></tr></table><hr><address>rmello at fslc.usu.edu</address><address><a href="mailto:vinod@kurup.com">
vinod@kurup.com
- </a></address>
-</div>
-</body>
-</html>
+ </a></address></div></body></html>
Index: openacs-4/packages/acs-core-docs/www/rp-requirements.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/rp-requirements.html,v
diff -u -r1.5 -r1.5.2.1
--- openacs-4/packages/acs-core-docs/www/rp-requirements.html 7 Mar 2002 06:55:36 -0000 1.5
+++ openacs-4/packages/acs-core-docs/www/rp-requirements.html 15 May 2002 23:26:18 -0000 1.5.2.1
@@ -1,131 +1,29 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type">
-<title>OpenACS 4 Request Processor Requirements</title>
-<meta name="generator" content="DocBook XSL Stylesheets V1.45">
-<link rel="home" href="index.html" title="OpenACS Documentation">
-<link rel="up" href="kernel-doc.html" title="Chapter 7. Kernel Documentation">
-<link rel="previous" href="security-notes.html" title="OpenACS 4 Security Notes">
-<link rel="next" href="rp-design.html" title="OpenACS 4 Request Processor Design">
-<link rel="stylesheet" href="openacs.css" type="text/css">
-</head>
-<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-<div class="navheader">
-<a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr>
-<td width="20%" align="left">
-<a accesskey="p" href="security-notes.html">Prev</a> </td>
-<th width="60%" align="center">Chapter 7. Kernel Documentation</th>
-<td width="20%" align="right"> <a accesskey="n" href="rp-design.html">Next</a>
-</td>
-</tr></table>
-<hr>
-</div>
-<div class="sect1">
-<div class="titlepage"><div><h2 class="title" style="clear: both">
-<a name="rp-requirements"></a>OpenACS 4 Request Processor Requirements</h2></div></div>
-<div class="authorblurb"><p>
-by <a href="http://planitia.org" target="_top">Rafael H. Schloming</a>
-</p></div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="rp-requirements-intro"></a>Introduction</h3></div></div>
-<p>The following is a requirements document for the OpenACS 4.0 request
+<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"><title>OpenACS 4 Request Processor Requirements</title><meta name="generator" content="DocBook XSL Stylesheets V1.50.0"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="kernel-doc.html" title="Chapter 7. Kernel Documentation"><link rel="previous" href="security-notes.html" title="OpenACS 4 Security Notes"><link rel="next" href="rp-design.html" title="OpenACS 4 Request Processor Design"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="security-notes.html">Prev</a> </td><th width="60%" align="center">Chapter 7. Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="rp-design.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="rp-requirements"></a>OpenACS 4 Request Processor Requirements</h2></div></div><div class="authorblurb"><p>
+by <a href="http://planitia.org" target="_top">Rafael H. Schloming</a><br>
+ OpenACS docs are written by the named authors, but may be edited
+ by OpenACS documentation staff.
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="rp-requirements-intro"></a>Introduction</h3></div></div><p>The following is a requirements document for the OpenACS 4.0 request
processor. The major enhancements in the 4.0 version include a more
sophisticated directory mapping system that allows package pageroots to be
mounted at arbitrary urls, and tighter integration with the database to allow
-for flexible user controlled url structures, and subsites.</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="rp-requirements-vision"></a>Vision Statement</h3></div></div>
-<p>Most web servers are designed to serve pages from exactly one static
+for flexible user controlled url structures, and subsites.</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="rp-requirements-vision"></a>Vision Statement</h3></div></div><p>Most web servers are designed to serve pages from exactly one static
pageroot. This restriction can become cumbersome when trying to build a web
-toolkit full of reusable and reconfigurable components.</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="rp-requirements-system-overview"></a>System Overview</h3></div></div>
-<p>The request processor's functionality can be split into two main
-pieces.</p>
-<div class="orderedlist"><ol type="1">
-<li>
-<p>Set up the environment in which a server side script expects to run. This
-includes things like:</p>
-<div class="itemizedlist"><ul>
-<li><p>Initialize common variables associated with a request.</p></li>
-<li><p>Authenticate the connecting party.</p></li>
-<li><p>Check that the connecting party is authorized to proceed with the
-request.</p></li>
-<li><p>Invoke any filters associated with the request URI.</p></li>
-</ul></div>
-</li>
-<li><p>Determine to which entity the request URI maps, and deliver the content
+toolkit full of reusable and reconfigurable components.</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="rp-requirements-system-overview"></a>System Overview</h3></div></div><p>The request processor's functionality can be split into two main
+pieces.</p><div class="orderedlist"><ol type="1"><li><p>Set up the environment in which a server side script expects to run. This
+includes things like:</p><div class="itemizedlist"><ul type="disc"><li><p>Initialize common variables associated with a request.</p></li><li><p>Authenticate the connecting party.</p></li><li><p>Check that the connecting party is authorized to proceed with the
+request.</p></li><li><p>Invoke any filters associated with the request URI.</p></li></ul></div></li><li><p>Determine to which entity the request URI maps, and deliver the content
provided by this entity. If this entity is a proc, then it is invoked. If
this entitty is a file then this step involves determining the file type, and
the manner in which the file must be processed to produce content appropriate
for the connecting party. Eventually this may also require determining the
capabilities of the connecting browser and choosing the most appropriate form
-for the delivered content.</p></li>
-</ol></div>
-<p>It is essential that any errors that occur during the above steps be
-reported to developers in an easily decipherable manner.</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="rp-requirements-links"></a>Related Links</h3></div></div>
-<p><a href="rp-design.html">OpenACS 4 Request Processor Design</a></p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="rp-requirements-req"></a>Requirements</h3></div></div>
-<p><span class="strong"><i>10.0 Multiple Pageroots</i></span></p>
-<blockquote class="blockquote">
-<p>
-<span class="strong"><i>10.10</i></span> Pageroots may be combined into one URL space.</p>
-<p>
-<span class="strong"><i>10.20</i></span> Pageroots may be mounted at more than one location in the URL
-space.</p>
-</blockquote>
-<p><span class="strong"><i>20.0 Application Context</i></span></p>
-<blockquote class="blockquote"><p>
-<span class="strong"><i>20.10</i></span> The request processor must be able to determine a primary context
+for the delivered content.</p></li></ol></div><p>It is essential that any errors that occur during the above steps be
+reported to developers in an easily decipherable manner.</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="rp-requirements-links"></a>Related Links</h3></div></div><p><a href="rp-design.html">OpenACS 4 Request Processor Design</a></p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="rp-requirements-req"></a>Requirements</h3></div></div><p><span class="strong"><em>10.0 Multiple Pageroots</em></span></p><blockquote class="blockquote"><p><span class="strong"><em>10.10</em></span> Pageroots may be combined into one URL space.</p><p><span class="strong"><em>10.20</em></span> Pageroots may be mounted at more than one location in the URL
+space.</p></blockquote><p><span class="strong"><em>20.0 Application Context</em></span></p><blockquote class="blockquote"><p><span class="strong"><em>20.10</em></span> The request processor must be able to determine a primary context
or state associated with a pageroot based on it's location within the URL
-space.</p></blockquote>
-<p><span class="strong"><i>30.0 Authentication</i></span></p>
-<blockquote class="blockquote"><p>
-<span class="strong"><i>30.10</i></span> The request processor must be able to verify that the connecting
-browser actually represents the party it claims to represent.</p></blockquote>
-<p><span class="strong"><i>40.0 Authorization</i></span></p>
-<blockquote class="blockquote"><p>
-<span class="strong"><i>40.10</i></span> The request processor must be able to verify that the party the
-connecting browser represents is allowed to make the request.</p></blockquote>
-<p><span class="strong"><i>50.0 Scalability</i></span></p>
-</div>
-</div>
-<div class="navfooter">
-<hr>
-<table width="100%" summary="Navigation footer">
-<tr>
-<td width="40%" align="left">
-<a accesskey="p" href="security-notes.html">Prev</a> </td>
-<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
-<td width="40%" align="right"> <a accesskey="n" href="rp-design.html">Next</a>
-</td>
-</tr>
-<tr>
-<td width="40%" align="left">OpenACS 4 Security Notes </td>
-<td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td>
-<td width="40%" align="right"> OpenACS 4 Request Processor Design</td>
-</tr>
-</table>
-<hr>
-<address>
- rmello at fslc.usu.edu
- </address>
-<address><a href="mailto:vinod@kurup.com">
+space.</p></blockquote><p><span class="strong"><em>30.0 Authentication</em></span></p><blockquote class="blockquote"><p><span class="strong"><em>30.10</em></span> The request processor must be able to verify that the connecting
+browser actually represents the party it claims to represent.</p></blockquote><p><span class="strong"><em>40.0 Authorization</em></span></p><blockquote class="blockquote"><p><span class="strong"><em>40.10</em></span> The request processor must be able to verify that the party the
+connecting browser represents is allowed to make the request.</p></blockquote><p><span class="strong"><em>50.0 Scalability</em></span></p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="security-notes.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="rp-design.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS 4 Security Notes </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> OpenACS 4 Request Processor Design</td></tr></table><hr><address>rmello at fslc.usu.edu</address><address><a href="mailto:vinod@kurup.com">
vinod@kurup.com
- </a></address>
-</div>
-</body>
-</html>
+ </a></address></div></body></html>
Index: openacs-4/packages/acs-core-docs/www/security-design.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/security-design.html,v
diff -u -r1.6 -r1.6.2.1
--- openacs-4/packages/acs-core-docs/www/security-design.html 7 Mar 2002 06:55:36 -0000 1.6
+++ openacs-4/packages/acs-core-docs/www/security-design.html 15 May 2002 23:26:18 -0000 1.6.2.1
@@ -1,196 +1,53 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type">
-<title>OpenACS 4 Security Design</title>
-<meta name="generator" content="DocBook XSL Stylesheets V1.45">
-<link rel="home" href="index.html" title="OpenACS Documentation">
-<link rel="up" href="kernel-doc.html" title="Chapter 7. Kernel Documentation">
-<link rel="previous" href="security-requirements.html" title="OpenACS 4 Security Requirements">
-<link rel="next" href="security-notes.html" title="OpenACS 4 Security Notes">
-<link rel="stylesheet" href="openacs.css" type="text/css">
-</head>
-<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-<div class="navheader">
-<a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr>
-<td width="20%" align="left">
-<a accesskey="p" href="security-requirements.html">Prev</a> </td>
-<th width="60%" align="center">Chapter 7. Kernel Documentation</th>
-<td width="20%" align="right"> <a accesskey="n" href="security-notes.html">Next</a>
-</td>
-</tr></table>
-<hr>
-</div>
-<div class="sect1">
-<div class="titlepage"><div><h2 class="title" style="clear: both">
-<a name="security-design"></a>OpenACS 4 Security Design</h2></div></div>
-<div class="authorblurb"><p>
+<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"><title>OpenACS 4 Security Design</title><meta name="generator" content="DocBook XSL Stylesheets V1.50.0"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="kernel-doc.html" title="Chapter 7. Kernel Documentation"><link rel="previous" href="security-requirements.html" title="OpenACS 4 Security Requirements"><link rel="next" href="security-notes.html" title="OpenACS 4 Security Notes"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="security-requirements.html">Prev</a> </td><th width="60%" align="center">Chapter 7. Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="security-notes.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="security-design"></a>OpenACS 4 Security Design</h2></div></div><div class="authorblurb"><p>
-by <a href="mailto:richardl@arsdigita.com" target="_top">Richard Li</a>, <a href="mailto:ashah@arsdigita.com" target="_top">Archit Shah</a>
-
-</p></div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="security-design-essentials"></a>Essentials</h3></div></div>
-<div class="itemizedlist"><ul><li><p><a href="security-requirements.html">OpenACS 4 Security Requirements</a></p></li></ul></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="security-design-intro"></a>Introduction</h3></div></div>
-<p>
+by <a href="mailto:richardl@arsdigita.com" target="_top">Richard Li</a>, <a href="mailto:ashah@arsdigita.com" target="_top">Archit Shah</a><br>
+ OpenACS docs are written by the named authors, but may be edited
+ by OpenACS documentation staff.
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="security-design-essentials"></a>Essentials</h3></div></div><div class="itemizedlist"><ul type="disc"><li><p><a href="security-requirements.html">OpenACS 4 Security Requirements</a></p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="security-design-intro"></a>Introduction</h3></div></div><p>
This document explains security model design for OpenACS 4. The security system
with the OpenACS core must authenticate users in both secure and insecure
environments. In addition, this subsystem provides sessions on top of the
stateless HTTP protocol. This system also provides session level properties
as a generic service to the rest of the OpenACS.
-</p>
-<p>The atoms used in the implementation:</p>
-<div class="itemizedlist"><ul>
-<li>
-<p>Cookies: <a href="http://web.mit.edu/rfc/rfc2109.txt" target="_top">RFC 2109, HTTP
-State Management Mechanism</a> </p>
-<p>Cookies provide client side state. They are used to identify the
+</p><p>The atoms used in the implementation:</p><div class="itemizedlist"><ul type="disc"><li><p>Cookies: <a href="http://web.mit.edu/rfc/rfc2109.txt" target="_top">RFC 2109, HTTP
+State Management Mechanism</a> </p><p>Cookies provide client side state. They are used to identify the
user. Expiration of cookies is used to demark the end of a
session.
-</p>
-</li>
-<li>
-<p>SHA: <a href="http://csrc.nist.gov/fips/fip180-1.txt" target="_top">SHA-1</a> </p>
-<p>This secure hash algorithm enables us to digitally sign cookies
+</p></li><li><p>SHA: <a href="http://csrc.nist.gov/fips/fip180-1.txt" target="_top">SHA-1</a> </p><p>This secure hash algorithm enables us to digitally sign cookies
which guarantee that they have not been tampered with. It is also used to
hash passwords.
-</p>
-</li>
-<li>
-<p>SSL with server authentication: <a href="http://home.netscape.com/eng/ssl3/ssl-toc.html" target="_top">SSL v3</a> </p>
-<p>SSL provides the client with a guarantee that the server is
+</p></li><li><p>SSL with server authentication: <a href="http://home.netscape.com/eng/ssl3/ssl-toc.html" target="_top">SSL v3</a> </p><p>SSL provides the client with a guarantee that the server is
actually the server it is advertised as being. It also provides a secure
transport.
-</p>
-</li>
-</ul></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="security-design-design"></a>Design</h3></div></div>
-<div class="sect3">
-<div class="titlepage"><div><h4 class="title">
-<a name="sessions"></a>Sessions</h4></div></div>
-<p>
+</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="security-design-design"></a>Design</h3></div></div><div class="sect3"><div class="titlepage"><div><h4 class="title"><a name="sessions"></a>Sessions</h4></div></div><p>
A session is defined as a series of clicks in which no two clicks are
separated by more than some constant. This constant is the parameter
SessionTimeout. Using the expiration time on the signatures of the signed
cookies, we can verify when the cookie was issued and determine if two
requests are part of the same session. It is important to note that the
expiration time set in the cookie protocol is not trusted. Only the time
inserted by the signed cookie mechanism is trusted.
-</p>
-</div>
-<div class="sect3">
-<div class="titlepage"><div><h4 class="title">
-<a name="authentication"></a>Authentication</h4></div></div>
-<p>
+</p></div><div class="sect3"><div class="titlepage"><div><h4 class="title"><a name="authentication"></a>Authentication</h4></div></div><p>
Two levels of access can be granted: insecure and secure. This grant lasts
for the remainder of the particular session. Secure authentication tokens are
only issued over secured connections.
-</p>
-<p>One consequence of this security design is that secure tokens are not
+</p><p>One consequence of this security design is that secure tokens are not
automatically issued to users who authenticate themselves over insecure
connections. This means that users will need to reauthenticate themselves
-over SSL when performing some action that requires secure authentication.</p>
-<p>Although this makes the site less user friendly, this design significantly
+over SSL when performing some action that requires secure authentication.</p><p>Although this makes the site less user friendly, this design significantly
increases the security of the system because this insures that the
authentication tokens presented to a secure section of the web site were not
sniffed. The system is not entirely secure, since the actual authentication
password can be sniffed from the system, after which the sniffer can apply
for a secure authentication token. However, the basic architecture here lays
the foundation for a secure system and can be easily adapted to a more secure
-authentication system by forcing all logins to occur over HTTPS.</p>
-</div>
-<div class="sect3">
-<div class="titlepage"><div><h4 class="title">
-<a name="authentication-details"></a>Details</h4></div></div>
-<p>The authentication system issues up to four signed cookies (see below),
-with each cookie serving a different purpose. These cookies are:</p>
-<blockquote class="blockquote"><div class="informaltable"><table border="1">
-<colgroup>
-<col>
-<col>
-<col>
-<col>
-</colgroup>
-<tbody>
-<tr>
-<td><span class="strong"><i>name</i></span></td>
-<td><span class="strong"><i>value</i></span></td>
-<td><span class="strong"><i>max-age</i></span></td>
-<td><span class="strong"><i>secure?</i></span></td>
-</tr>
-<tr>
-<td>ad_session_id</td>
-<td>session_id,user_id</td>
-<td>SessionTimeout</td>
-<td>no</td>
-</tr>
-<tr>
-<td>ad_user_login</td>
-<td>user_id</td>
-<td>Infinity</td>
-<td>no</td>
-</tr>
-<tr>
-<td>ad_user_login_secure</td>
-<td>user_id,random</td>
-<td>Infinity</td>
-<td>yes</td>
-</tr>
-<tr>
-<td>ad_secure_token</td>
-<td>session_id,user_id,random</td>
-<td>SessionLifetime</td>
-<td>yes</td>
-</tr>
-</tbody>
-</table></div></blockquote>
-<div class="itemizedlist"><ul>
-<li>
-<p>ad_session_id</p>
-<div class="itemizedlist"><ul>
-<li><p>reissued on any hit separated by more than SessionRenew seconds from the
-previous hit that received a cookie</p></li>
-<li><p>is valid only for SessionTimeout seconds</p></li>
-<li><p>is the canonical source for the session ID in ad_conn</p></li>
-</ul></div>
-</li>
-<li>
-<p>ad_user_login</p>
-<div class="itemizedlist"><ul><li><p>is used for permanent logins</p></li></ul></div>
-</li>
-<li>
-<p>ad_user_login_secure</p>
-<div class="itemizedlist"><ul>
-<li><p>is used for permanent secure logins</p></li>
-<li><p>contains random garbage (ns_time) to prevent attack against the secure
-hash</p></li>
-</ul></div>
-</li>
-<li>
-<p>ad_secure_token
-</p>
-<div class="itemizedlist"><ul>
-<li><p>is a session-level cookie from the browser's standpoint</p></li>
-<li><p>its signature expires in SessionLifetime seconds</p></li>
-<li><p>contains random garbage (ns_time) to prevent attack against the secure
-hash</p></li>
-<li><p>user_id is extraneous</p></li>
-</ul></div>
-</li>
-</ul></div>
-</div>
-<div class="sect3">
-<div class="titlepage"><div><h4 class="title">
-<a name="authentication-process"></a>Authentication Process</h4></div></div>
-<p>The Tcl function (<tt>sec_handler</tt>) is called by the request
+authentication system by forcing all logins to occur over HTTPS.</p></div><div class="sect3"><div class="titlepage"><div><h4 class="title"><a name="authentication-details"></a>Details</h4></div></div><p>The authentication system issues up to four signed cookies (see below),
+with each cookie serving a different purpose. These cookies are:</p><blockquote class="blockquote"><div class="informaltable"><table border="1"><colgroup><col><col><col><col></colgroup><tbody><tr><td><span class="strong"><em>name</em></span></td><td><span class="strong"><em>value</em></span></td><td><span class="strong"><em>max-age</em></span></td><td><span class="strong"><em>secure?</em></span></td></tr><tr><td>ad_session_id</td><td>session_id,user_id</td><td>SessionTimeout</td><td>no</td></tr><tr><td>ad_user_login</td><td>user_id</td><td>Infinity</td><td>no</td></tr><tr><td>ad_user_login_secure</td><td>user_id,random</td><td>Infinity</td><td>yes</td></tr><tr><td>ad_secure_token</td><td>session_id,user_id,random</td><td>SessionLifetime</td><td>yes</td></tr></tbody></table></div></blockquote><div class="itemizedlist"><ul type="disc"><li><p>ad_session_id</p><div class="itemizedlist"><ul type="round"><li><p>reissued on any hit separated by more than SessionRenew seconds from the
+previous hit that received a cookie</p></li><li><p>is valid only for SessionTimeout seconds</p></li><li><p>is the canonical source for the session ID in ad_conn</p></li></ul></div></li><li><p>ad_user_login</p><div class="itemizedlist"><ul type="round"><li><p>is used for permanent logins</p></li></ul></div></li><li><p>ad_user_login_secure</p><div class="itemizedlist"><ul type="round"><li><p>is used for permanent secure logins</p></li><li><p>contains random garbage (ns_time) to prevent attack against the secure
+hash</p></li></ul></div></li><li><p>ad_secure_token
+</p><div class="itemizedlist"><ul type="round"><li><p>is a session-level cookie from the browser's standpoint</p></li><li><p>its signature expires in SessionLifetime seconds</p></li><li><p>contains random garbage (ns_time) to prevent attack against the secure
+hash</p></li><li><p>user_id is extraneous</p></li></ul></div></li></ul></div></div><div class="sect3"><div class="titlepage"><div><h4 class="title"><a name="authentication-process"></a>Authentication Process</h4></div></div><p>The Tcl function (<tt>sec_handler</tt>) is called by the request
processor to authenticate the user. It first checks the
<tt>ad_session_id</tt> cookie. If there is no valid session in progress,
a new session is created with <tt>sec_setup_session</tt>. If the user
@@ -200,17 +57,11 @@
determined by whether or not the request is on a secure connection. If
neither cookie is present, then a session is created without any
authentication. If the <tt>ad_session_id</tt> cookie is valid, the
-user_id and session_id are pulled from it and put into ad_conn.</p>
-</div>
-<div class="sect3">
-<div class="titlepage"><div><h4 class="title">
-<a name="secure-connections"></a>Authenticating Secure Connections</h4></div></div>
-<p>Secure connections are authenticated slightly differently. The function
+user_id and session_id are pulled from it and put into ad_conn.</p></div><div class="sect3"><div class="titlepage"><div><h4 class="title"><a name="secure-connections"></a>Authenticating Secure Connections</h4></div></div><p>Secure connections are authenticated slightly differently. The function
<tt>ad_secure_conn_p</tt> is used to determine whether or not the URL
being accessed is requires a secure login. The function simply checks if the
location begins with "https". (This is safe because the location is
-set during the server initialization.)</p>
-<p>If secure authentication is required, the <tt>ad_secure_token</tt>
+set during the server initialization.)</p><p>If secure authentication is required, the <tt>ad_secure_token</tt>
cookie is checked to make sure its data matches the data stored in
<tt>ad_session_id</tt>. This is true for all pages except those that are
part of the login process. On these pages, the user can not yet have received
@@ -221,115 +72,21 @@
browser when the browser exits. Since an attacker could conceivably store the
secure cookie in a replay attack (since expiration date is not validated),
the data in the secure cookie is never used to set any data in ad_conn;
-user_id and session_id is set from the ad_session_id cookie.</p>
-<p>It is important to note that the integrity of secure authentication rests
+user_id and session_id is set from the ad_session_id cookie.</p><p>It is important to note that the integrity of secure authentication rests
on the two Tcl function <tt>ad_secure_conn_p</tt> and
<tt>ad_login_page</tt>. If <tt>ad_secure_conn_p</tt> is false, secure
authentication is not required. If <tt>ad_login_page</tt> is false,
-secure authentication is not required.</p>
-</div>
-<div class="sect3">
-<div class="titlepage"><div><h4 class="title">
-<a name="login-process"></a>Login Process</h4></div></div>
-<p>The Tcl function <tt>ad_user_login</tt> does two things. First it
+secure authentication is not required.</p></div><div class="sect3"><div class="titlepage"><div><h4 class="title"><a name="login-process"></a>Login Process</h4></div></div><p>The Tcl function <tt>ad_user_login</tt> does two things. First it
performs the appropriate manipulation of the permanent login cookies, and
then it updates the current session to reflect the new user_id. The
-manipulation of the permanent login cookies is based on 3 factors:</p>
-<div class="itemizedlist"><ul>
-<li><p>previous login: other user, same user</p></li>
-<li><p>permanent: was a permanent login requested?</p></li>
-<li><p>secure: is this a secure connection?</p></li>
-</ul></div>
-<p>
+manipulation of the permanent login cookies is based on 3 factors:</p><div class="itemizedlist"><ul type="disc"><li><p>previous login: other user, same user</p></li><li><p>permanent: was a permanent login requested?</p></li><li><p>secure: is this a secure connection?</p></li></ul></div><p>
Both the secure and insecure permanent login cookie can have one of three
actions taken on it:
-</p>
-<div class="itemizedlist"><ul>
-<li><p>set: cookie with no expiration is set</p></li>
-<li><p>delete: set to "" with max age of 0, so it is expired
-immediately</p></li>
-<li><p>nothing: if the cookie is present, it remains</p></li>
-</ul></div>
-<p>
+</p><div class="itemizedlist"><ul type="disc"><li><p>set: cookie with no expiration is set</p></li><li><p>delete: set to "" with max age of 0, so it is expired
+immediately</p></li><li><p>nothing: if the cookie is present, it remains</p></li></ul></div><p>
The current state of the permanent login cookies is not taken into account
when determining the appropriate action.
-</p>
-<blockquote class="blockquote"><div class="informaltable"><table border="1">
-<colgroup>
-<col>
-<col>
-<col>
-<col>
-<col>
-</colgroup>
-<tbody>
-<tr>
-<td><span class="strong"><i>previous login state</i></span></td>
-<td><span class="strong"><i>permanent login requested</i></span></td>
-<td><span class="strong"><i>secure connection</i></span></td>
-<td><span class="strong"><i>action on insecure</i></span></td>
-<td><span class="strong"><i>action on secure</i></span></td>
-</tr>
-<tr>
-<td>other</td>
-<td>y</td>
-<td>y</td>
-<td>set</td>
-<td>set</td>
-</tr>
-<tr>
-<td>same</td>
-<td>y</td>
-<td>y</td>
-<td>set</td>
-<td>set</td>
-</tr>
-<tr>
-<td>other</td>
-<td>y</td>
-<td>n</td>
-<td>set</td>
-<td>delete</td>
-</tr>
-<tr>
-<td>same</td>
-<td>y</td>
-<td>n</td>
-<td>set</td>
-<td>nothing</td>
-</tr>
-<tr>
-<td>same</td>
-<td>n</td>
-<td>y</td>
-<td>nothing</td>
-<td>delete</td>
-</tr>
-<tr>
-<td>other</td>
-<td>n</td>
-<td>y</td>
-<td>delete</td>
-<td>delete</td>
-</tr>
-<tr>
-<td>other</td>
-<td>n</td>
-<td>n</td>
-<td>delete</td>
-<td>delete</td>
-</tr>
-<tr>
-<td>same</td>
-<td>n</td>
-<td>n</td>
-<td>delete</td>
-<td>delete</td>
-</tr>
-</tbody>
-</table></div></blockquote>
-<p>
-<tt>ad_user_login</tt>
+</p><blockquote class="blockquote"><div class="informaltable"><table border="1"><colgroup><col><col><col><col><col></colgroup><tbody><tr><td><span class="strong"><em>previous login state</em></span></td><td><span class="strong"><em>permanent login requested</em></span></td><td><span class="strong"><em>secure connection</em></span></td><td><span class="strong"><em>action on insecure</em></span></td><td><span class="strong"><em>action on secure</em></span></td></tr><tr><td>other</td><td>y</td><td>y</td><td>set</td><td>set</td></tr><tr><td>same</td><td>y</td><td>y</td><td>set</td><td>set</td></tr><tr><td>other</td><td>y</td><td>n</td><td>set</td><td>delete</td></tr><tr><td>same</td><td>y</td><td>n</td><td>set</td><td>nothing</td></tr><tr><td>same</td><td>n</td><td>y</td><td>nothing</td><td>delete</td></tr><tr><td>other</td><td>n</td><td>y</td><td>delete</td><td>delete</td></tr><tr><td>other</td><td>n</td><td>n</td><td>delete</td><td>delete</td></tr><tr><td>same</td><td>n</td><td>n</td><td>delete</td><td>delete</td></tr></tbody></table></div></blockquote><p><tt>ad_user_login</tt>
calls<tt>sec_setup_session</tt> which actually calls
<tt>sec_generate_session_id_cookie</tt> to generate the
new cookie with refer to the appropriate user_id. If the connection is secure
@@ -341,50 +98,30 @@
<tt>sec_setup_session</tt> call
<tt>sec_generate_session_id_cookie</tt>.
-</p>
-<p>
-<tt>ad_user_logout</tt> logs the user out by deleting all 4 cookies
-that are used by the authentication system.</p>
-</div>
-<div class="sect3">
-<div class="titlepage"><div><h4 class="title">
-<a name="session-creation"></a>Session Creation</h4></div></div>
-<p>The creation and setup of sessions is handled in
+</p><p><tt>ad_user_logout</tt> logs the user out by deleting all 4 cookies
+that are used by the authentication system.</p></div><div class="sect3"><div class="titlepage"><div><h4 class="title"><a name="session-creation"></a>Session Creation</h4></div></div><p>The creation and setup of sessions is handled in
<tt>sec_setup_session</tt>, which is called either to
create a new session from <tt>sec_handler</tt> or from
<tt>ad_user_login</tt> when there is a change in
authorization level. The session management code must do two things: insure that
session-level data does not float between users, and update the users table
which has columns for <tt>n_sessions</tt>,
<tt>last_visit</tt>, and
-<tt>second_to_last_visit</tt>.</p>
-<p>If there is no session already setup on this hit, a new session is
+<tt>second_to_last_visit</tt>.</p><p>If there is no session already setup on this hit, a new session is
created. This happens when <tt>sec_setup_session</tt> is
called from <tt>sec_handler</tt>. If the login is from a
user to another user, a new session is created, otherwise, the current session
is continued, simply with a higher authorization state. This allows for data
-associated with a session to be carried over when a user logs in.</p>
-<p>The users table is updated by
+associated with a session to be carried over when a user logs in.</p><p>The users table is updated by
<tt>sec_update_user_session_info</tt> which is called
when an existing session is assigned a non-zero user_id, or when a session is
-created with a non-zero user_id.</p>
-</div>
-<div class="sect3">
-<div class="titlepage"><div><h4 class="title">
-<a name="passwords"></a>Passwords</h4></div></div>
-<p>
-<tt>ad_user_login</tt> assumes a password check has already been
+created with a non-zero user_id.</p></div><div class="sect3"><div class="titlepage"><div><h4 class="title"><a name="passwords"></a>Passwords</h4></div></div><p><tt>ad_user_login</tt> assumes a password check has already been
performed (this will change in the future). The actual check is done by
<tt>ad_check_password</tt>. The database stores a salt and a hash of the
password concatenated with the salt. Updating the password
(<tt>ad_change_password</tt>) simply requires getting a new salt
(ns_time) concatenating and rehashing. Both the salt and the hashed password
-field are updated.</p>
-</div>
-<div class="sect3">
-<div class="titlepage"><div><h4 class="title">
-<a name="performance-enhancements"></a>Performance Enhancements</h4></div></div>
-<p>A session is labeled by a session_id sequence. Creating a session merely
+field are updated.</p></div><div class="sect3"><div class="titlepage"><div><h4 class="title"><a name="performance-enhancements"></a>Performance Enhancements</h4></div></div><p>A session is labeled by a session_id sequence. Creating a session merely
requires incrementing the session_id sequence. We do two things to improve the
performance of this process. First, sequence values are precomputed and cached
in the Oracle SGA. In addition, sequence values are incremented by 100 with each
@@ -400,20 +137,14 @@
db and <tt>tcl_max_value</tt> is incremented by
100. This is done on a per-thread basis so that no locking is required.
-</p>
-<p>In addition, two procedures are dynamically generated at startup in
+</p><p>In addition, two procedures are dynamically generated at startup in
<tt>security-init.tcl</tt>. These two procedures use
<tt>ad_parameter</tt> to obtain the constant value of a given parameter;
these values are used to dynamically generate a procedure that returns a
constant. This approach avoids (relatively) expensive calls to
<tt>ad_parameter</tt> in <tt>sec_handler</tt>. The impact of this
approach is that these parameters cannot be dynamically changed at runtime
-and require a server restart.</p>
-</div>
-<div class="sect3">
-<div class="titlepage"><div><h4 class="title">
-<a name="session-properties"></a>Session Properties</h4></div></div>
-<p>
+and require a server restart.</p></div><div class="sect3"><div class="titlepage"><div><h4 class="title"><a name="session-properties"></a>Session Properties</h4></div></div><p>
Session properties are stored in a single table that maps session IDs to
named session properties and values. This table is periodically purged. For
maximum performance, the table is created with nologging turned on and new
@@ -422,33 +153,21 @@
sessions whose first hit was more than SessionLifetime seconds (1 week by
default) ago. Session properties are removed through that same process with
cascading delete.
-</p>
-</div>
-<div class="sect4">
-<div class="titlepage"><div><h5 class="title">
-<a name="secure-session-properties"></a>Secure Session Properties</h5></div></div>
-<p>Session properties can be set as secure. In this case,
+</p></div><div class="sect4"><div class="titlepage"><div><h5 class="title"><a name="secure-session-properties"></a>Secure Session Properties</h5></div></div><p>Session properties can be set as secure. In this case,
<tt>ad_set_client_property</tt> will fail if the connection is not
secure. <tt>ad_get_client_property</tt> will behave as if the property
-had not been set if the property was not set securely.</p>
-</div>
-<div class="sect3">
-<div class="titlepage"><div><h4 class="title">
-<a name="digital-signatures"></a>Digital Signatures & Signed Cookies</h4></div></div>
-<p>
+had not been set if the property was not set securely.</p></div><div class="sect3"><div class="titlepage"><div><h4 class="title"><a name="digital-signatures"></a>Digital Signatures & Signed Cookies</h4></div></div><p>
Signed cookies are implemented using the generic secure digital signature
mechanism. This mechanism guarantees that the user can not tamper with (or
construct a value of his choice) without detection. In addition, it provides
the optional facility of timing out the signature so it is valid for only a
certain period of time. This works by simply including an expiration time as
part of the value that is signed.
-</p>
-<p>The signature produced by <tt>ad_sign</tt> is the Tcl list of
+</p><p>The signature produced by <tt>ad_sign</tt> is the Tcl list of
<tt>token_id,expire_time,hash</tt>, where hash =
SHA1(value,token_id,expire_time,secret_token). The secret_token is a forty
character randomly generated string that is never sent to any user agent. The
-scheme consists of one table:</p>
-<pre class="programlisting">
+scheme consists of one table:</p><pre class="programlisting">
create table secret_tokens (
token_id integer
@@ -457,17 +176,14 @@
token_timestamp sysdate
);
-</pre>
-<p>
-<tt>ad_verify_signature</tt> takes a value and a signature and
+</pre><p><tt>ad_verify_signature</tt> takes a value and a signature and
verifies that the signature was generated using that value. It works simply
by taking the token_id and expire_time from the signature, and regenerating
the hash using the supplied value and the secret_token corresponding to the
token_id. This regenerated hash is compared to the hash extracted from the
supplied signature. The expire_time is also verified to be greater than the
current time. An expire_time of 0 is also allowed, as it indicates no time
-out on the signature.</p>
-<p>Signed cookies include in their RFC2109 VALUE field a Tcl list of the
+out on the signature.</p><p>Signed cookies include in their RFC2109 VALUE field a Tcl list of the
value and the signature. In addition to the expiration of the digital
signature, RFC 2109 specifies an optional max age that is returned to the
client. For most cookies, this max age matches the expiration date of the
@@ -476,16 +192,11 @@
exits." Because we can not trust the client to do this, we must specify
a timeout for the signature. The SessionLifetime parameter is used for this
purpose, as it represents the maximum possible lifetime of a single
-session.</p>
-<p>RFC 2109 specifies this optional "secure" parameter which
+session.</p><p>RFC 2109 specifies this optional "secure" parameter which
mandates that the user-agent use "secure means" to contact the
server when transmitting the cookie. If a secure cookie is returned to the
client over https, then the cookie will never be transmitted over insecure
-means.</p>
-<div class="sect4">
-<div class="titlepage"><div><h5 class="title">
-<a name="signature-performance"></a>Performance</h5></div></div>
-<p>Performance is a key goal of this implementation of signed cookies. To
+means.</p><div class="sect4"><div class="titlepage"><div><h5 class="title"><a name="signature-performance"></a>Performance</h5></div></div><p>Performance is a key goal of this implementation of signed cookies. To
maximize performance, we will use the following architecture. At the lowest
level, we will use the <tt>secret_tokens</tt> table as the canonical set
of secret tokens. This table is necessary for multiple servers to maintain
@@ -494,190 +205,94 @@
<tt>secret_tokens</tt>. When a new signed cookie is requested, a random
token_id is returned out of the entire set of cached token_ids. In addition,
a thread-persistent cache called tcl_secret_tokens is maintained on a
-per-thread basis.</p>
-<p>Thus, the L2 ns_cache functions as a server-wide LRU cache that has a
-minimum of 100 tokens in it. The cache has a dual purpose:</p>
-<div class="itemizedlist"><ul>
-<li><p>
-<span class="strong"><i>LRU cache</i></span> Note that cache misses will only occur in the
+per-thread basis.</p><p>Thus, the L2 ns_cache functions as a server-wide LRU cache that has a
+minimum of 100 tokens in it. The cache has a dual purpose:</p><div class="itemizedlist"><ul type="disc"><li><p><span class="strong"><em>LRU cache</em></span> Note that cache misses will only occur in the
multiple server case, where a user agent may have a signature guaranteed by a
-secret token issued by another server in the cluster.</p></li>
-<li><p>
-<span class="strong"><i>signature cache</i></span> Since the cache always maintains a
+secret token issued by another server in the cluster.</p></li><li><p><span class="strong"><em>signature cache</em></span> Since the cache always maintains a
minimum of 100 (set by a parameter) tokens populated at startup, it can be
-used to provide a random token for signature purposes.</p></li>
-</ul></div>
-<p>
+used to provide a random token for signature purposes.</p></li></ul></div><p>
The per-thread cache functions as an L1 cache that indiscriminately caches
-all secret tokens. Note that this is <span class="strong"><i>not</i></span> an LRU cache
+all secret tokens. Note that this is <span class="strong"><em>not</em></span> an LRU cache
because there is no cache eviction policy per se -- the cache is cleared when
the thread is destroyed by AOLserver.
-</p>
-</div>
-<div class="sect4">
-<div class="titlepage"><div><h5 class="title">
-<a name="signature-security"></a>Security</h5></div></div>
-<p>Storing information on a client always presents an additional security
-risk.</p>
-<p>Since we are only validating the information and not trying to protect it
+</p></div><div class="sect4"><div class="titlepage"><div><h5 class="title"><a name="signature-security"></a>Security</h5></div></div><p>Storing information on a client always presents an additional security
+risk.</p><p>Since we are only validating the information and not trying to protect it
as a secret, we don't use salt. Cryptographic salt is useful if you are
-trying to protect information from being read (e.g., hashing passwords).</p>
-</div>
-</div>
-<div class="sect3">
-<div class="titlepage"><div><h4 class="title">
-<a name="external-ssl"></a>External SSL</h4></div></div>
-<p>
+trying to protect information from being read (e.g., hashing passwords).</p></div></div><div class="sect3"><div class="titlepage"><div><h4 class="title"><a name="external-ssl"></a>External SSL</h4></div></div><p>
External SSL mechanisms (firewall, dedicated hardware, etc.) can be used by
creating two pools of AOLservers. In one pool the servers should be
configured with the location parameter of nssock module set to
"https://yourservername". The servers in the other pool are
configured as normal. The external SSL agent should direct SSL queries to the
pool of secure servers, and it should direct non-SSL queries to the insecure
servers.
-</p>
-</div>
-<div class="sect3">
-<div class="titlepage"><div><h4 class="title">
-<a name="PRNG"></a>PRNG</h4></div></div>
-<p>
+</p></div><div class="sect3"><div class="titlepage"><div><h4 class="title"><a name="PRNG"></a>PRNG</h4></div></div><p>
The pseudorandom number generator depends primarily on ns_rand, but is also
seeded with ns_time and the number of page requests served since the server
was started. The PRNG takes the SHA1(seed,ns_rand,ns_time,requests,clicks),
and saves the first 40 bits as the seed for the next call to the PRNG in a
thread-persistent global variable. The remaining 120 bits are rehashed to
produce 160 bits of output.
-</p>
-</div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="security-design-api"></a>API</h3></div></div>
-<div class="sect3">
-<div class="titlepage"><div><h4 class="title">
-<a name="login-password-api"></a>Login/Password</h4></div></div>
-<p>
-<span class="strong"><i>ad_user_login <span class="emphasis"><i>user_id</i></span></i></span> Logs the user in as user
-<span class="emphasis"><i>user_id</i></span>. Optional forever flag determines whether or not permanent
+</p></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="security-design-api"></a>API</h3></div></div><div class="sect3"><div class="titlepage"><div><h4 class="title"><a name="login-password-api"></a>Login/Password</h4></div></div><p>
+<span class="strong"><em>ad_user_login <span class="emphasis"><em>user_id</em></span></em></span> Logs the user in as user
+<span class="emphasis"><em>user_id</em></span>. Optional forever flag determines whether or not permanent
cookies are issued.
-</p>
-<p>
-<span class="strong"><i>ad_user_logout</i></span> Logs the user out.</p>
-<p>
-<span class="strong"><i>ad_check_password <span class="emphasis"><i>user_id</i></span> <span class="emphasis"><i>password</i></span></i></span>
-returns 0 or 1.</p>
-<p><span class="strong"><i>ad_change_password <span class="emphasis"><i>user_id</i></span> <span class="emphasis"><i>new
-password</i></span></i></span></p>
-</div>
-<div class="sect3">
-<div class="titlepage"><div><h4 class="title">
-<a name="signature-api"></a>Digital Signatures and Signed Cookies</h4></div></div>
-<p>
-<span class="strong"><i>ad_sign <span class="emphasis"><i>value</i></span></i></span> Returns the digital signature of this
-value. Optional parameters allow for the specification of the <span class="emphasis"><i>secret</i></span>
-used, the <span class="emphasis"><i>token_id</i></span> used and the <span class="emphasis"><i>max_age</i></span> for the signature.
-<span class="strong"><i>ad_verify_signature <span class="emphasis"><i>value</i></span> <span class="emphasis"><i>signature</i></span></i></span>Returns
+</p><p><span class="strong"><em>ad_user_logout</em></span> Logs the user out.</p><p><span class="strong"><em>ad_check_password <span class="emphasis"><em>user_id</em></span> <span class="emphasis"><em>password</em></span></em></span>
+returns 0 or 1.</p><p><span class="strong"><em>ad_change_password <span class="emphasis"><em>user_id</em></span> <span class="emphasis"><em>new
+password</em></span></em></span></p></div><div class="sect3"><div class="titlepage"><div><h4 class="title"><a name="signature-api"></a>Digital Signatures and Signed Cookies</h4></div></div><p>
+<span class="strong"><em>ad_sign <span class="emphasis"><em>value</em></span></em></span> Returns the digital signature of this
+value. Optional parameters allow for the specification of the <span class="emphasis"><em>secret</em></span>
+used, the <span class="emphasis"><em>token_id</em></span> used and the <span class="emphasis"><em>max_age</em></span> for the signature.
+<span class="strong"><em>ad_verify_signature <span class="emphasis"><em>value</em></span> <span class="emphasis"><em>signature</em></span></em></span>Returns
1 or 0 indicating whether or not the signature matches the value specified.
-The <span class="emphasis"><i>secret</i></span> parameter allows for specification of a different secret
-token to be used. </p>
-<p>
-<span class="strong"><i>ad_set_signed_cookie <span class="emphasis"><i>name</i></span> <span class="emphasis"><i>data</i></span></i></span> Sets a
-signed cookie <span class="emphasis"><i>name</i></span> with value <span class="emphasis"><i>data</i></span>. </p>
-<p>
-<span class="strong"><i>ad_get_signed_cookie <span class="emphasis"><i>name</i></span></i></span> Gets the signed cookie
-<span class="emphasis"><i>name</i></span>. It raises an error if the cookie has been tampered with, or if
-its expiration time has passed.</p>
-</div>
-<div class="sect3">
-<div class="titlepage"><div><h4 class="title">
-<a name="session-property-api"></a>Session Properties</h4></div></div>
-<p>
-<span class="strong"><i>ad_set_client_property <span class="emphasis"><i>module</i></span> <span class="emphasis"><i>name</i></span>
-<span class="emphasis"><i>data</i></span></i></span> Sets a session property with <span class="emphasis"><i>name</i></span> to value
-<span class="emphasis"><i>data</i></span> for the module <span class="emphasis"><i>module</i></span>. The optional secure flag
+The <span class="emphasis"><em>secret</em></span> parameter allows for specification of a different secret
+token to be used. </p><p>
+<span class="strong"><em>ad_set_signed_cookie <span class="emphasis"><em>name</em></span> <span class="emphasis"><em>data</em></span></em></span> Sets a
+signed cookie <span class="emphasis"><em>name</em></span> with value <span class="emphasis"><em>data</em></span>. </p><p><span class="strong"><em>ad_get_signed_cookie <span class="emphasis"><em>name</em></span></em></span> Gets the signed cookie
+<span class="emphasis"><em>name</em></span>. It raises an error if the cookie has been tampered with, or if
+its expiration time has passed.</p></div><div class="sect3"><div class="titlepage"><div><h4 class="title"><a name="session-property-api"></a>Session Properties</h4></div></div><p><span class="strong"><em>ad_set_client_property <span class="emphasis"><em>module</em></span> <span class="emphasis"><em>name</em></span>
+<span class="emphasis"><em>data</em></span></em></span> Sets a session property with <span class="emphasis"><em>name</em></span> to value
+<span class="emphasis"><em>data</em></span> for the module <span class="emphasis"><em>module</em></span>. The optional secure flag
specifies the property should only be set if the client is authorized for
secure access (<tt>ad_secure_conn_p</tt> is true). There is also an optional
-<span class="emphasis"><i>session_id</i></span> flag to access data from sessions other than the current one.</p>
-<p>
-<span class="strong"><i>ad_get_client_property <span class="emphasis"><i>module</i></span> <span class="emphasis"><i>name</i></span>
-<span class="emphasis"><i>data</i></span></i></span> Gets a session property with <span class="emphasis"><i>name</i></span> to for the
-module <span class="emphasis"><i>module</i></span>. The optional secure flag specifies the property
+<span class="emphasis"><em>session_id</em></span> flag to access data from sessions other than the current one.</p><p><span class="strong"><em>ad_get_client_property <span class="emphasis"><em>module</em></span> <span class="emphasis"><em>name</em></span>
+<span class="emphasis"><em>data</em></span></em></span> Gets a session property with <span class="emphasis"><em>name</em></span> to for the
+module <span class="emphasis"><em>module</em></span>. The optional secure flag specifies the property
should only be retrieved if the client is authorized for secure access
(<tt>ad_secure_conn_p</tt> is true). There is also an optional
-<span class="emphasis"><i>session_id</i></span> flag to access data from sessions other than the current one.</p>
-</div>
-<div class="sect3">
-<div class="titlepage"><div><h4 class="title">
-<a name="parameters"></a>Parameters</h4></div></div>
-<p>
-<span class="strong"><i>SessionTimeout</i></span> the maximum time in seconds (default 1200)
-between requests that are part of the same session </p>
-<p>
-<span class="strong"><i>SessionRenew</i></span> the time in seconds (default 300) between
+<span class="emphasis"><em>session_id</em></span> flag to access data from sessions other than the current one.</p></div><div class="sect3"><div class="titlepage"><div><h4 class="title"><a name="parameters"></a>Parameters</h4></div></div><p>
+<span class="strong"><em>SessionTimeout</em></span> the maximum time in seconds (default 1200)
+between requests that are part of the same session </p><p><span class="strong"><em>SessionRenew</em></span> the time in seconds (default 300) between
reissue of the session cookie. The minimum time that can pass after a session
cookie is issued and before it is rejected is (SessionTimeout -
SessionRenew). This parameter is used so that only one session_id cookie is
set on a single page even if there are multiple images that are being
-downloaded.</p>
-<p>
-<span class="strong"><i>SessionLifetime</i></span> the maximum possible lifetime of a
-session in seconds (default 604800 = 7 days)</p>
-<p>
-<span class="strong"><i>NumberOfCachedSecretTokens</i></span> the number of secret tokens to
-cache. (default 100)</p>
-</div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="security-design-future"></a>Future Improvements</h3></div></div>
-<div class="sect3">
-<div class="titlepage"><div><h4 class="title">
-<a name="PRNG-impl"></a>PRNG implementation</h4></div></div>
-<p>
+downloaded.</p><p><span class="strong"><em>SessionLifetime</em></span> the maximum possible lifetime of a
+session in seconds (default 604800 = 7 days)</p><p><span class="strong"><em>NumberOfCachedSecretTokens</em></span> the number of secret tokens to
+cache. (default 100)</p></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="security-design-future"></a>Future Improvements</h3></div></div><div class="sect3"><div class="titlepage"><div><h4 class="title"><a name="PRNG-impl"></a>PRNG implementation</h4></div></div><p>
The pseudorandom number generator used in the OpenACS is cryptographically weak,
and depends primarily on the randomness of the <tt>ns_rand</tt> function
for its randomness. The implementation of the PRNG could be substantially
improved.
-</p>
-</div>
-<div class="sect3">
-<div class="titlepage"><div><h4 class="title">
-<a name="ad_user_login"></a><tt>ad_user_login</tt></h4></div></div>
-<p>
+</p></div><div class="sect3"><div class="titlepage"><div><h4 class="title"><a name="ad_user_login"></a><tt>ad_user_login</tt></h4></div></div><p>
Add a password argument. It is non-optimal to make the default behavior to
assume that the password was provided.
-</p>
-</div>
-<div class="sect3">
-<div class="titlepage"><div><h4 class="title">
-<a name="secret-tokens"></a>Secret Tokens</h4></div></div>
-<p>
+</p></div><div class="sect3"><div class="titlepage"><div><h4 class="title"><a name="secret-tokens"></a>Secret Tokens</h4></div></div><p>
The secret tokens pool is currently static. Ideally, this pool should be
changed on a random but regular basis, and the number of secret_tokens
increased as the number of users come to the web site.
-</p>
-<p>Since the security of the entire system depends on the secret tokens pool,
+</p><p>Since the security of the entire system depends on the secret tokens pool,
access to the secret tokens table should be restricted and accessible via a
strict PL/SQL API. This can be done by revoking standard SQL permissions on
the table for the AOLserver user and giving those permissions to a PL/SQL
-package.</p>
-</div>
-<div class="sect3">
-<div class="titlepage"><div><h4 class="title">
-<a name="robots"></a>Robots</h4></div></div>
-<p>
+package.</p></div><div class="sect3"><div class="titlepage"><div><h4 class="title"><a name="robots"></a>Robots</h4></div></div><p>
Deferring session to creation until the second hit from a browser seems to be
a good way of preventing a lot of overhead processing for robots. If we do
this, send cookie on first hit to test if cookies are accepted, then actually
allocate on second hit. To preserve a record of the first hit of the session,
just include any info about that first hit in the probe cookie sent. Look at
how usca_p (user session cookie attempted) is used in OpenACS 3.x ecommerce.
-</p>
-</div>
-<div class="sect3">
-<div class="titlepage"><div><h4 class="title">
-<a name="client-property-future"></a>Client properties</h4></div></div>
-<p>
+</p></div><div class="sect3"><div class="titlepage"><div><h4 class="title"><a name="client-property-future"></a>Client properties</h4></div></div><p>
Currently there are only session properties. Because sessions have a maximum
life, properties have a maximum life. It would be nice to expand the
interface to allow for more persistent properties. In the past, there was a
@@ -690,12 +305,7 @@
can be shared between concurrent sessions). The applications should have
control over the deletion patterns, but should not be able to ignore the
amount of data stored.
-</p>
-</div>
-<div class="sect3">
-<div class="titlepage"><div><h4 class="title">
-<a name="session-information"></a>Session information</h4></div></div>
-<p>
+</p></div><div class="sect3"><div class="titlepage"><div><h4 class="title"><a name="session-information"></a>Session information</h4></div></div><p>
It would be nice to keep some info about sessions: first hit, last hit, and
URLs visited come to mind. Both logging and API for accessing this info would
be nice. WimpyPoint is an application that already wants to use this
@@ -704,93 +314,42 @@
analyzers (leaving it in server memory for applications to access). Putting
it into the database at all is probably too big a hammer. Certainly putting
it into the database on every hit is too big a hammer.
-</p>
-</div>
-<div class="sect3">
-<div class="titlepage"><div><h4 class="title">
-<a name="cookieless-sessions"></a>Cookieless Sessions</h4></div></div>
-<p>Two trends drive the requirement for removing cookie dependence. WAP
+</p></div><div class="sect3"><div class="titlepage"><div><h4 class="title"><a name="cookieless-sessions"></a>Cookieless Sessions</h4></div></div><p>Two trends drive the requirement for removing cookie dependence. WAP
browsers that do not have cookies, and publc perceptions of cookies as an
invasion of privacy. The rely on the cookies mechanism in HTTP to distinguish
one request from the next, and we trust it to force requests from the same
client to carry the same cookie headers. The same thing can be accomplished by
personalizing the URLs sent back to each browser. If we can store an identifier
in the URL and get it back on the next hit, the sessions system would continue
-to work.</p>
-<p>Problems that arise:
+to work.</p><p>Problems that arise:
-<div class="itemizedlist"><ul>
-<li>URL sharing could be dangerous. If I happen to be browsing Amazon
+</p><div class="itemizedlist"><ul type="disc"><li>URL sharing could be dangerous. If I happen to be browsing Amazon
while logged in and I email a friend, he could conceivably receive it and follow
it before my session has expired, gaining all of the privileges I
-had.</li>
-<li>User-entered URLs are harder to handler. If a user is in the middle of
+had.</li><li>User-entered URLs are harder to handler. If a user is in the middle of
a session and then types in the URL of some page, he could be kicked out of his
-session.</li>
-</ul></div>
+session.</li></ul></div><p>
Both of these problems can be mitigated by doing detection of cookie support
(see the section on robot detection). To help deal with the first problem, One
could also make the restriction that secure sessions are only allowed over
-cookied HTTP.</p>
-</div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="security-design-vulnerability"></a>Vulnerability Analysis</h3></div></div>
-<p>
+cookied HTTP.</p></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="security-design-vulnerability"></a>Vulnerability Analysis</h3></div></div><p>
This section is not meant to be a comprehensive analysis of the
vulnerabilities of the security system. Listed below are possible attack
points for the system; these vulnerabilities are currently theoretical in
nature. The major cryptographic vulnerability of the system stems from the
pseudorandom nature of the random number generators used in the system.
-</p>
-<div class="itemizedlist"><ul>
-<li><p>
-<span class="strong"><i>Cryptographically weak PRNG</i></span> see
-above.</p></li>
-<li><p>
-<span class="strong"><i>Dependence on <tt>sample</tt>
-SQL command</i></span> The list of random token that are placed in the secret
+</p><div class="itemizedlist"><ul type="disc"><li><p><span class="strong"><em>Cryptographically weak PRNG</em></span> see
+above.</p></li><li><p><span class="strong"><em>Dependence on <tt>sample</tt>
+SQL command</em></span> The list of random token that are placed in the secret
tokens cache is randomly chosen by the Oracle
<tt>sample</tt> command. This command may not be
entirely random, so predicting the contents of the secret tokens cache may not
-be as difficult as someone may anticipate.</p></li>
-<li><p>
-<span class="strong"><i>Dependence on
-<tt>ns_rand</tt></i></span> The actual token that is
+be as difficult as someone may anticipate.</p></li><li><p><span class="strong"><em>Dependence on
+<tt>ns_rand</tt></em></span> The actual token that is
chosen from the cache to be used is chosen by a call to
-<tt>ns_rand</tt>.</p></li>
-<li><p>
-<span class="strong"><i><tt>ad_secure_conn_p</tt></i></span>
+<tt>ns_rand</tt>.</p></li><li><p><span class="strong"><em><tt>ad_secure_conn_p</tt></em></span>
As discussed above, the security of the secure sessions authentication system is
-dependent upon this function.</p></li>
-</ul></div>
-</div>
-</div>
-<div class="navfooter">
-<hr>
-<table width="100%" summary="Navigation footer">
-<tr>
-<td width="40%" align="left">
-<a accesskey="p" href="security-requirements.html">Prev</a> </td>
-<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
-<td width="40%" align="right"> <a accesskey="n" href="security-notes.html">Next</a>
-</td>
-</tr>
-<tr>
-<td width="40%" align="left">OpenACS 4 Security Requirements </td>
-<td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td>
-<td width="40%" align="right"> OpenACS 4 Security Notes</td>
-</tr>
-</table>
-<hr>
-<address>
- rmello at fslc.usu.edu
- </address>
-<address><a href="mailto:vinod@kurup.com">
+dependent upon this function.</p></li></ul></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="security-requirements.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="security-notes.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS 4 Security Requirements </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> OpenACS 4 Security Notes</td></tr></table><hr><address>rmello at fslc.usu.edu</address><address><a href="mailto:vinod@kurup.com">
vinod@kurup.com
- </a></address>
-</div>
-</body>
-</html>
+ </a></address></div></body></html>
Index: openacs-4/packages/acs-core-docs/www/security-notes.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/security-notes.html,v
diff -u -r1.7 -r1.7.2.1
--- openacs-4/packages/acs-core-docs/www/security-notes.html 7 Mar 2002 06:55:36 -0000 1.7
+++ openacs-4/packages/acs-core-docs/www/security-notes.html 15 May 2002 23:26:18 -0000 1.7.2.1
@@ -1,60 +1,29 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type">
-<title>OpenACS 4 Security Notes</title>
-<meta name="generator" content="DocBook XSL Stylesheets V1.45">
-<link rel="home" href="index.html" title="OpenACS Documentation">
-<link rel="up" href="kernel-doc.html" title="Chapter 7. Kernel Documentation">
-<link rel="previous" href="security-design.html" title="OpenACS 4 Security Design">
-<link rel="next" href="rp-requirements.html" title="OpenACS 4 Request Processor Requirements">
-<link rel="stylesheet" href="openacs.css" type="text/css">
-</head>
-<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-<div class="navheader">
-<a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr>
-<td width="20%" align="left">
-<a accesskey="p" href="security-design.html">Prev</a> </td>
-<th width="60%" align="center">Chapter 7. Kernel Documentation</th>
-<td width="20%" align="right"> <a accesskey="n" href="rp-requirements.html">Next</a>
-</td>
-</tr></table>
-<hr>
-</div>
-<div class="sect1">
-<div class="titlepage"><div><h2 class="title" style="clear: both">
-<a name="security-notes"></a>OpenACS 4 Security Notes</h2></div></div>
-<div class="authorblurb"><p>
-by <a href="mailto:richardl@arsdigita.com" target="_top">Richard Li</a>
-</p></div>
-<p>
+<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"><title>OpenACS 4 Security Notes</title><meta name="generator" content="DocBook XSL Stylesheets V1.50.0"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="kernel-doc.html" title="Chapter 7. Kernel Documentation"><link rel="previous" href="security-design.html" title="OpenACS 4 Security Design"><link rel="next" href="rp-requirements.html" title="OpenACS 4 Request Processor Requirements"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="security-design.html">Prev</a> </td><th width="60%" align="center">Chapter 7. Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="rp-requirements.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="security-notes"></a>OpenACS 4 Security Notes</h2></div></div><div class="authorblurb"><p>
+by <a href="mailto:richardl@arsdigita.com" target="_top">Richard Li</a><br>
+ OpenACS docs are written by the named authors, but may be edited
+ by OpenACS documentation staff.
+ </p></div><p>
The security system was designed for security. Thus, decisions requiring
trade-offs between ease-of-use and security tend to result in a system that
may not be as easy to use but is more secure.
-</p>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="security-notes-https-sessions"></a>HTTPS and the sessions system</h3></div></div>
-<p>
+</p><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="security-notes-https-sessions"></a>HTTPS and the sessions system</h3></div></div><p>
If a user switches to HTTPS after logging into the system via HTTP, the user
-must obtain a secure token. To insure security, the <span class="emphasis"><i>only way</i></span> to
+must obtain a secure token. To insure security, the <span class="emphasis"><em>only way</em></span> to
obtain a secure token in the security system is to authenticate yourself via
password over an HTTPS connection. Thus, users may need to log on again to a
system when switching from HTTP to HTTPS. Note that logging on to a system
via HTTPS gives the user both insecure and secure authentication tokens, so
switching from HTTPS to HTTP does not require reauthentication.
-</p>
-<p>This method of authentication is important in order to establish, in as
+</p><p>This method of authentication is important in order to establish, in as
strong a manner as possible, the identity of the owner of the secure token.
In order for the security system to offer stronger guarantees of someone who
issues a secure token, the method of authentication must be as strong as the
-method of transmission.</p>
-<p>If a developer truly does not want such a level of protection, this system
+method of transmission.</p><p>If a developer truly does not want such a level of protection, this system
can be disabled via source code modification only. This can be accomplished
by commenting out the following lines in the <tt>sec_handler</tt>
-procedure defined in <tt>security-procs.tcl</tt>:</p>
-<pre class="programlisting">
+procedure defined in <tt>security-procs.tcl</tt>:</p><pre class="programlisting">
if { [ad_secure_conn_p] && ![ad_login_page] } {
set s_token_cookie [ns_urldecode [ad_get_cookie "ad_secure_token"]]
@@ -65,11 +34,9 @@
}
}
-</pre>
-<p>The source code must also be edited if the user login pages have been
+</pre><p>The source code must also be edited if the user login pages have been
moved out of an OpenACS system. This information is contained by the
-<tt>ad_login_page</tt> procedure in <tt>security-procs.tcl</tt>:</p>
-<pre class="programlisting">
+<tt>ad_login_page</tt> procedure in <tt>security-procs.tcl</tt>:</p><pre class="programlisting">
ad_proc -private ad_login_page {} {
@@ -85,38 +52,10 @@
return 0
}
-</pre>
-<p>
+</pre><p>
The set of string match expressions in the procedure above should be extended
appropriately for other registration pages. This procedure does not use
<tt>ad_parameter</tt> or regular expressions for performance reasons, as
-it is called by the request processor. </p>
-<p><div class="cvstag">($Id$)</div></p>
-</div>
-</div>
-<div class="navfooter">
-<hr>
-<table width="100%" summary="Navigation footer">
-<tr>
-<td width="40%" align="left">
-<a accesskey="p" href="security-design.html">Prev</a> </td>
-<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
-<td width="40%" align="right"> <a accesskey="n" href="rp-requirements.html">Next</a>
-</td>
-</tr>
-<tr>
-<td width="40%" align="left">OpenACS 4 Security Design </td>
-<td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td>
-<td width="40%" align="right"> OpenACS 4 Request Processor Requirements</td>
-</tr>
-</table>
-<hr>
-<address>
- rmello at fslc.usu.edu
- </address>
-<address><a href="mailto:vinod@kurup.com">
+it is called by the request processor. </p><p><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="security-design.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="rp-requirements.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS 4 Security Design </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> OpenACS 4 Request Processor Requirements</td></tr></table><hr><address>rmello at fslc.usu.edu</address><address><a href="mailto:vinod@kurup.com">
vinod@kurup.com
- </a></address>
-</div>
-</body>
-</html>
+ </a></address></div></body></html>
Index: openacs-4/packages/acs-core-docs/www/security-requirements.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/security-requirements.html,v
diff -u -r1.5 -r1.5.2.1
--- openacs-4/packages/acs-core-docs/www/security-requirements.html 7 Mar 2002 06:55:36 -0000 1.5
+++ openacs-4/packages/acs-core-docs/www/security-requirements.html 15 May 2002 23:26:18 -0000 1.5.2.1
@@ -1,145 +1,50 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type">
-<title>OpenACS 4 Security Requirements</title>
-<meta name="generator" content="DocBook XSL Stylesheets V1.45">
-<link rel="home" href="index.html" title="OpenACS Documentation">
-<link rel="up" href="kernel-doc.html" title="Chapter 7. Kernel Documentation">
-<link rel="previous" href="apm-design.html" title="OpenACS 4.5 Package Manager Design">
-<link rel="next" href="security-design.html" title="OpenACS 4 Security Design">
-<link rel="stylesheet" href="openacs.css" type="text/css">
-</head>
-<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-<div class="navheader">
-<a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr>
-<td width="20%" align="left">
-<a accesskey="p" href="apm-design.html">Prev</a> </td>
-<th width="60%" align="center">Chapter 7. Kernel Documentation</th>
-<td width="20%" align="right"> <a accesskey="n" href="security-design.html">Next</a>
-</td>
-</tr></table>
-<hr>
-</div>
-<div class="sect1">
-<div class="titlepage"><div><h2 class="title" style="clear: both">
-<a name="security-requirements"></a>OpenACS 4 Security Requirements</h2></div></div>
-<div class="authorblurb"><p>
-by <a href="mailto:richardl@arsdigita.com" target="_top">Richard Li</a>
-</p></div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="security-requirements-intro"></a>Introduction</h3></div></div>
-<p>
+<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"><title>OpenACS 4 Security Requirements</title><meta name="generator" content="DocBook XSL Stylesheets V1.50.0"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="kernel-doc.html" title="Chapter 7. Kernel Documentation"><link rel="previous" href="apm-design.html" title="OpenACS 4.5 Package Manager Design"><link rel="next" href="security-design.html" title="OpenACS 4 Security Design"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="apm-design.html">Prev</a> </td><th width="60%" align="center">Chapter 7. Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="security-design.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="security-requirements"></a>OpenACS 4 Security Requirements</h2></div></div><div class="authorblurb"><p>
+by <a href="mailto:richardl@arsdigita.com" target="_top">Richard Li</a><br>
+ OpenACS docs are written by the named authors, but may be edited
+ by OpenACS documentation staff.
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="security-requirements-intro"></a>Introduction</h3></div></div><p>
This document lists the requirements for the security system for the OpenACS.
-</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="security-requirements-vision"></a>Vision Statement</h3></div></div>
-<p>
+</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="security-requirements-vision"></a>Vision Statement</h3></div></div><p>
Virtually all web sites support personalized content based on user identity.
The level of personalization may be as simple as displaying the name of the
user on certain pages or can be as sophisticated as dynamically recommending
sections of site that the user may be interested in based on prior browsing
history. In any case, the user's identity must be validated and made
available to the rest of the system. In addition, sites such as ecommerce
vendors require that the user identity be securely validated.
-</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="security-requirements-system-overview"></a>Security System Overview</h3></div></div>
-<p>
+</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="security-requirements-system-overview"></a>Security System Overview</h3></div></div><p>
The security system consists of a number of subsystems.
-</p>
-<p><span class="strong"><i>Signed Cookies</i></span></p>
-<p>
+</p><p><span class="strong"><em>Signed Cookies</em></span></p><p>
Cookies play a key role in storing user information. However, since they are
stored in plaintext on a user's system, the validity of cookies is an
important issue in trusting cookie information. Thus, we want to be able to
validate a cookie, but we also want to validate the cookie without a database
hit.
-</p>
-<div class="itemizedlist"><ul>
-<li><p>
-<span class="strong"><i>10.0 Guaranteed Tamper Detection</i></span> Any tampering of cookie
-data should be easily detectable by the web server.</p></li>
-<li><p>
-<span class="strong"><i>10.1 Performance and Scalability</i></span> Validation and
+</p><div class="itemizedlist"><ul type="disc"><li><p><span class="strong"><em>10.0 Guaranteed Tamper Detection</em></span> Any tampering of cookie
+data should be easily detectable by the web server.</p></li><li><p><span class="strong"><em>10.1 Performance and Scalability</em></span> Validation and
verification of the cookie should be easily scalable and should not require a
-database query on every hit.</p></li>
-</ul></div>
-<p><span class="strong"><i>Session Properties</i></span></p>
-<p>
+database query on every hit.</p></li></ul></div><p><span class="strong"><em>Session Properties</em></span></p><p>
Applications should be able to store session-level properties in a database
table.
-</p>
-<div class="itemizedlist"><ul>
-<li><p>
-<span class="strong"><i>11.0 Storage API</i></span> Session-level data should be accessible
-via an API.</p></li>
-<li><p>
-<span class="strong"><i>11.1 Purge Mechanism</i></span> An efficient pruning mechanism
+</p><div class="itemizedlist"><ul type="disc"><li><p><span class="strong"><em>11.0 Storage API</em></span> Session-level data should be accessible
+via an API.</p></li><li><p><span class="strong"><em>11.1 Purge Mechanism</em></span> An efficient pruning mechanism
should be used to prevent old session level properties from filling up the
-table.</p></li>
-</ul></div>
-<p><span class="strong"><i>Login</i></span></p>
-<p>
+table.</p></li></ul></div><p><span class="strong"><em>Login</em></span></p><p>
The security system should support the concept of persistent user logins.
This persistence takes several forms.
-</p>
-<div class="itemizedlist"><ul>
-<li><p>
-<span class="strong"><i>12.0 Permanent Login</i></span> Users should be able to maintain a
-permanent user login so that they never need to type their password.</p></li>
-<li><p>
-<span class="strong"><i>12.1 Session Login</i></span> The security system should support
+</p><div class="itemizedlist"><ul type="disc"><li><p><span class="strong"><em>12.0 Permanent Login</em></span> Users should be able to maintain a
+permanent user login so that they never need to type their password.</p></li><li><p><span class="strong"><em>12.1 Session Login</em></span> The security system should support
the concept of a session, with authentication tokens that become invalid
-after a certain period of time.</p></li>
-<li><p>
-<span class="strong"><i>12.2 Session Definition</i></span> A session is a sequence of
+after a certain period of time.</p></li><li><p><span class="strong"><em>12.2 Session Definition</em></span> A session is a sequence of
clicks by one user from one browser in which no two clicks are separated by
-more than some constant (the session timeout).</p></li>
-<li><p>
-<span class="strong"><i>12.3 Stateless</i></span> The security system should not require
+more than some constant (the session timeout).</p></li><li><p><span class="strong"><em>12.3 Stateless</em></span> The security system should not require
state that is stored in the server. Required state may reside only in the
user request (including cookies), and in the database. A single user should
be able to log in to the system even if the user is sent to a different
-AOLserver for each step of the login process (e.g., by a load balancer).</p></li>
-<li><p>
-<span class="strong"><i>12.4 Secure</i></span> The security system should not store
-passwords in clear text in the database.</p></li>
-</ul></div>
-<div class="itemizedlist"><ul><li><p>
-<span class="strong"><i>13.0 SSL Hardware</i></span> The system must work when the SSL
+AOLserver for each step of the login process (e.g., by a load balancer).</p></li><li><p><span class="strong"><em>12.4 Secure</em></span> The security system should not store
+passwords in clear text in the database.</p></li></ul></div><div class="itemizedlist"><ul type="disc"><li><p><span class="strong"><em>13.0 SSL Hardware</em></span> The system must work when the SSL
processing occurs outside of the web server (in specialized hardware, in a
-firewall, etc.).</p></li></ul></div>
-</div>
-</div>
-<div class="navfooter">
-<hr>
-<table width="100%" summary="Navigation footer">
-<tr>
-<td width="40%" align="left">
-<a accesskey="p" href="apm-design.html">Prev</a> </td>
-<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
-<td width="40%" align="right"> <a accesskey="n" href="security-design.html">Next</a>
-</td>
-</tr>
-<tr>
-<td width="40%" align="left">OpenACS 4.5 Package Manager Design </td>
-<td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td>
-<td width="40%" align="right"> OpenACS 4 Security Design</td>
-</tr>
-</table>
-<hr>
-<address>
- rmello at fslc.usu.edu
- </address>
-<address><a href="mailto:vinod@kurup.com">
+firewall, etc.).</p></li></ul></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="apm-design.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="security-design.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS 4.5 Package Manager Design </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> OpenACS 4 Security Design</td></tr></table><hr><address>rmello at fslc.usu.edu</address><address><a href="mailto:vinod@kurup.com">
vinod@kurup.com
- </a></address>
-</div>
-</body>
-</html>
+ </a></address></div></body></html>
Index: openacs-4/packages/acs-core-docs/www/subsites-design.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/subsites-design.html,v
diff -u -r1.5 -r1.5.2.1
--- openacs-4/packages/acs-core-docs/www/subsites-design.html 7 Mar 2002 06:55:36 -0000 1.5
+++ openacs-4/packages/acs-core-docs/www/subsites-design.html 15 May 2002 23:26:18 -0000 1.5.2.1
@@ -1,109 +1,50 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type">
-<title>OpenACS 4 Subsites Design Document</title>
-<meta name="generator" content="DocBook XSL Stylesheets V1.45">
-<link rel="home" href="index.html" title="OpenACS Documentation">
-<link rel="up" href="kernel-doc.html" title="Chapter 7. Kernel Documentation">
-<link rel="previous" href="subsites-requirements.html" title="OpenACS 4 Subsites Requirements">
-<link rel="next" href="apm-requirements.html" title="OpenACS 4.5 Package Manager Requirements">
-<link rel="stylesheet" href="openacs.css" type="text/css">
-</head>
-<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-<div class="navheader">
-<a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr>
-<td width="20%" align="left">
-<a accesskey="p" href="subsites-requirements.html">Prev</a> </td>
-<th width="60%" align="center">Chapter 7. Kernel Documentation</th>
-<td width="20%" align="right"> <a accesskey="n" href="apm-requirements.html">Next</a>
-</td>
-</tr></table>
-<hr>
-</div>
-<div class="sect1">
-<div class="titlepage"><div><h2 class="title" style="clear: both">
-<a name="subsites-design"></a>OpenACS 4 Subsites Design Document</h2></div></div>
-<div class="authorblurb"><p>
-by <a href="http://planitia.org" target="_top">Rafael H. Schloming</a>
-</p></div>
-<p><span class="emphasis"><i>*Note* This document has not gone through the any of the
+<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"><title>OpenACS 4 Subsites Design Document</title><meta name="generator" content="DocBook XSL Stylesheets V1.50.0"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="kernel-doc.html" title="Chapter 7. Kernel Documentation"><link rel="previous" href="subsites-requirements.html" title="OpenACS 4 Subsites Requirements"><link rel="next" href="apm-requirements.html" title="OpenACS 4.5 Package Manager Requirements"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="subsites-requirements.html">Prev</a> </td><th width="60%" align="center">Chapter 7. Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="apm-requirements.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="subsites-design"></a>OpenACS 4 Subsites Design Document</h2></div></div><div class="authorblurb"><p>
+by <a href="http://planitia.org" target="_top">Rafael H. Schloming</a><br>
+ OpenACS docs are written by the named authors, but may be edited
+ by OpenACS documentation staff.
+ </p></div><p><span class="emphasis"><em>*Note* This document has not gone through the any of the
required QA process yet. It is being tagged as stable due to high
-demand.</i></span></p>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="subsites-design-essentials"></a>Essentials</h3></div></div>
-<div class="itemizedlist"><ul><li><p><a href="subsites-requirements.html">OpenACS 4 Subsites Requirements</a></p></li></ul></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="subsites-design-intro"></a>Introduction</h3></div></div>
-<p>An OpenACS 4 subsite is a managed suite of applications that work together for
+demand.</em></span></p><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="subsites-design-essentials"></a>Essentials</h3></div></div><div class="itemizedlist"><ul type="disc"><li><p><a href="subsites-requirements.html">OpenACS 4 Subsites Requirements</a></p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="subsites-design-intro"></a>Introduction</h3></div></div><p>An OpenACS 4 subsite is a managed suite of applications that work together for
a particular user community. This definition covers a very broad range of
requirements: from a Geocities style homepage where a user can install
whatever available application he wants (e.g. a single user could have their
own news and bboard), to a highly structured project subsite with multiple
interdependent applications. Thus, flexibility in application deployment is
-the overarching philosophy of subsites.</p>
-<p>Meeting such broad requirements of flexibility demands architecture-level
+the overarching philosophy of subsites.</p><p>Meeting such broad requirements of flexibility demands architecture-level
support, i.e. very low level support from the core OpenACS 4 data model. For
example, the subsites concept demands that any package can have multiple
instances installed at different URLs - entailing support from the APM and
the Request Processor. Since the design and implementation directly
associated with subsites is actually minimal, a discussion of subsites design
is, in fact, a discussion of how core OpenACS 4 components implicitly support
-subsites as a whole.</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="subsites-design-hist-considerations"></a>Historical Considerations</h3></div></div>
-<p>The subsites problem actually has several quite diverse origins. It was
+subsites as a whole.</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="subsites-design-hist-considerations"></a>Historical Considerations</h3></div></div><p>The subsites problem actually has several quite diverse origins. It was
originally recognized as a toolkit feature in the form of
"scoping". The basic concept behind scoping was to allow one scoped
OpenACS installation to behave as multiple unscoped OpenACS installations so that one
OpenACS install could serve multiple communities. Each piece of application data
was tagged with a "scope" consisting of the (user_id, group_id,
scope) triple. In practice the highly denormalized data models that this
method uses produced large amounts of very redundant code and in general made
-it an extremely cumbersome process to "scopify" a module.</p>
-<p>Before the advent of scoping there were several cases of client projects
+it an extremely cumbersome process to "scopify" a module.</p><p>Before the advent of scoping there were several cases of client projects
implementing their own version of scoping in special cases. One example being
the wineaccess multi-retailer ecommerce. (Remember the other examples and get
-details. Archnet?, iluvcamp?)</p>
-<p>The requirements of all these different projects vary greatly, but the one
+details. Archnet?, iluvcamp?)</p><p>The requirements of all these different projects vary greatly, but the one
consistent theme among all of them is the concept that various areas of the
web site have their own private version of a module. Because this theme is so
dominant, this is the primary problem that the OpenACS4 implementation of
-subsites addresses.</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="subsites-design-competitors"></a>Competitive Analysis</h3></div></div>
-<p>...</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="subsites-design-design-tradeoffs"></a>Design Tradeoffs</h3></div></div>
-<p>The current implementation of package instances and subsites allows
+subsites addresses.</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="subsites-design-competitors"></a>Competitive Analysis</h3></div></div><p>...</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="subsites-design-design-tradeoffs"></a>Design Tradeoffs</h3></div></div><p>The current implementation of package instances and subsites allows
extremely flexible URL configurations. This has the benefit of allowing
multiple instances of the same package to be installed in one subsite, but
can potentially complicate the process of integrating packages with each
other since it is likely people will want packages that live at non standard
URLs to operate together. This requirement would cause some packages to have
more configuration options than normal since hard-coding the URLs would not
-be feasible anymore.</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="subsites-design-api"></a>API</h3></div></div>
-<p>This section will cover all the APIs relevant to subsites, and so will
-consist of portions of the APIs of several systems.</p>
-<p><span class="strong"><i>Packages</i></span></p>
-<p>The following package is provided for instantiation of packages. The
+be feasible anymore.</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="subsites-design-api"></a>API</h3></div></div><p>This section will cover all the APIs relevant to subsites, and so will
+consist of portions of the APIs of several systems.</p><p><span class="strong"><em>Packages</em></span></p><p>The following package is provided for instantiation of packages. The
apm_package.new function can be used to create a package of any type known to
the system. The apm_package_types table can be queried for a list of
-installed packages. (See APM docs for more detail XXX: insert link here)</p>
-<pre class="programlisting">
+installed packages. (See APM docs for more detail XXX: insert link here)</p><pre class="programlisting">
<tt>create or replace package apm_package
as
@@ -160,18 +101,15 @@
show errors
</tt>
-</pre>
-<p><span class="strong"><i>Site Nodes</i></span></p>
-<p>This data model keeps track of what packages are being served from what
+</pre><p><span class="strong"><em>Site Nodes</em></span></p><p>This data model keeps track of what packages are being served from what
URLs. You can think of this as a kind of rp_register_directory_map on drugs.
This table represents a fully hierarchical site map. The directory_p column
indicates whether or not the node is a leaf node. The pattern_p column
indicates whether an exact match between the request URL and the URL of the
node is required. If pattern_p is true then a match between a request URL and
a site node occurs if any valid prefix of the request URL matches the site
node URL. The object_id column contains the object mounted on the URL
-represented by the node. In most cases this will be a package instance.</p>
-<pre class="programlisting">
+represented by the node. In most cases this will be a package instance.</p><pre class="programlisting">
<tt>create table site_nodes (
node_id constraint site_nodes_node_id_fk
@@ -199,9 +137,7 @@
);
</tt>
-</pre>
-<p>The following package is provided for creating nodes.</p>
-<pre class="programlisting">
+</pre><p>The following package is provided for creating nodes.</p><pre class="programlisting">
<tt>create or replace package site_node
as
@@ -246,47 +182,24 @@
show errors
</tt>
-</pre>
-<p><span class="strong"><i>Request Processor</i></span></p>
-<p>Once the above APIs are used to create packages and mount them on a
+</pre><p><span class="strong"><em>Request Processor</em></span></p><p>Once the above APIs are used to create packages and mount them on a
specific site node, the following request processor APIs can be used to allow
-the package to serve content appropriate to the package instance.</p>
-<pre class="programlisting">
+the package to serve content appropriate to the package instance.</p><pre class="programlisting">
<tt>[ad_conn node_id]
[ad_conn package_id]
[ad_conn package_url]
</tt>
-</pre>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="subsites-design-data-model"></a>Data Model Discussion</h3></div></div>
-<p>The subsites implementation doesn't really have it's own data
+</pre></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="subsites-design-data-model"></a>Data Model Discussion</h3></div></div><p>The subsites implementation doesn't really have it's own data
model, although it depends heavily on the site-nodes data model, and the APM
-data model.</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="subsites-design-ui"></a>User Interface</h3></div></div>
-<p>The primary elements of the subsite user interface consist of the subsite
+data model.</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="subsites-design-ui"></a>User Interface</h3></div></div><p>The primary elements of the subsite user interface consist of the subsite
admin pages. These pages are divided up into two areas: Group administration,
and the site map. The group administration pages allow a subsite
administrator to create and modify groups. The site map pages allow a subsite
administrator to install, remove, configure, and control access to packages.
The site map interface is the primary point of entry for most of the things a
-subsite administrator would want to do.</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="subsites-design-config"></a>Configuration/Parameters</h3></div></div>
-<p>...</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="subsites-design-future"></a>Future Improvements/Areas of Likely Change</h3></div></div>
-<p>The current subsites implementation addresses the most basic functionality
+subsite administrator would want to do.</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="subsites-design-config"></a>Configuration/Parameters</h3></div></div><p>...</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="subsites-design-future"></a>Future Improvements/Areas of Likely Change</h3></div></div><p>The current subsites implementation addresses the most basic functionality
required for subsites. It is likely that as developers begin to use the
subsites system for more sophisticated projects, it will become necessary to
develop tools to help build tightly integrated packages. The general area
@@ -297,37 +210,6 @@
a particular configuration of site nodes/packages. As we build more
fundamental applications that can be applied in more general areas, this
feature will become more and more in demand since more problems will be
-solvable by configuration instead of coding.</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="subsites-design-authors"></a>Authors</h3></div></div>
-<p><a href="mailto:rhs@mit.edu" target="_top">rhs@mit.edu</a></p>
-</div>
-</div>
-<div class="navfooter">
-<hr>
-<table width="100%" summary="Navigation footer">
-<tr>
-<td width="40%" align="left">
-<a accesskey="p" href="subsites-requirements.html">Prev</a> </td>
-<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
-<td width="40%" align="right"> <a accesskey="n" href="apm-requirements.html">Next</a>
-</td>
-</tr>
-<tr>
-<td width="40%" align="left">OpenACS 4 Subsites Requirements </td>
-<td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td>
-<td width="40%" align="right"> OpenACS 4.5 Package Manager Requirements</td>
-</tr>
-</table>
-<hr>
-<address>
- rmello at fslc.usu.edu
- </address>
-<address><a href="mailto:vinod@kurup.com">
+solvable by configuration instead of coding.</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="subsites-design-authors"></a>Authors</h3></div></div><p><a href="mailto:rhs@mit.edu" target="_top">rhs@mit.edu</a></p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="subsites-requirements.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="apm-requirements.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS 4 Subsites Requirements </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> OpenACS 4.5 Package Manager Requirements</td></tr></table><hr><address>rmello at fslc.usu.edu</address><address><a href="mailto:vinod@kurup.com">
vinod@kurup.com
- </a></address>
-</div>
-</body>
-</html>
+ </a></address></div></body></html>
Index: openacs-4/packages/acs-core-docs/www/subsites-requirements.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/subsites-requirements.html,v
diff -u -r1.5 -r1.5.2.1
--- openacs-4/packages/acs-core-docs/www/subsites-requirements.html 7 Mar 2002 06:55:36 -0000 1.5
+++ openacs-4/packages/acs-core-docs/www/subsites-requirements.html 15 May 2002 23:26:18 -0000 1.5.2.1
@@ -1,214 +1,60 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type">
-<title>OpenACS 4 Subsites Requirements</title>
-<meta name="generator" content="DocBook XSL Stylesheets V1.45">
-<link rel="home" href="index.html" title="OpenACS Documentation">
-<link rel="up" href="kernel-doc.html" title="Chapter 7. Kernel Documentation">
-<link rel="previous" href="groups-design.html" title="OpenACS 4 Groups Design">
-<link rel="next" href="subsites-design.html" title="OpenACS 4 Subsites Design Document">
-<link rel="stylesheet" href="openacs.css" type="text/css">
-</head>
-<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-<div class="navheader">
-<a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr>
-<td width="20%" align="left">
-<a accesskey="p" href="groups-design.html">Prev</a> </td>
-<th width="60%" align="center">Chapter 7. Kernel Documentation</th>
-<td width="20%" align="right"> <a accesskey="n" href="subsites-design.html">Next</a>
-</td>
-</tr></table>
-<hr>
-</div>
-<div class="sect1">
-<div class="titlepage"><div><h2 class="title" style="clear: both">
-<a name="subsites-requirements"></a>OpenACS 4 Subsites Requirements</h2></div></div>
-<div class="authorblurb"><p>
-by <a href="http://planitia.org" target="_top">Rafael H. Schloming</a> and <a href="mailto:dennis@arsdigita.com" target="_top">Dennis Gregorovic</a>
-</p></div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="subsites-requirements-intro"></a>Introduction</h3></div></div>
-<p>The following is a requirements document for OpenACS 4 Subsites, part of the
+<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"><title>OpenACS 4 Subsites Requirements</title><meta name="generator" content="DocBook XSL Stylesheets V1.50.0"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="kernel-doc.html" title="Chapter 7. Kernel Documentation"><link rel="previous" href="groups-design.html" title="OpenACS 4 Groups Design"><link rel="next" href="subsites-design.html" title="OpenACS 4 Subsites Design Document"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="groups-design.html">Prev</a> </td><th width="60%" align="center">Chapter 7. Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="subsites-design.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="subsites-requirements"></a>OpenACS 4 Subsites Requirements</h2></div></div><div class="authorblurb"><p>
+by <a href="http://planitia.org" target="_top">Rafael H. Schloming</a> and <a href="mailto:dennis@arsdigita.com" target="_top">Dennis Gregorovic</a><br>
+ OpenACS docs are written by the named authors, but may be edited
+ by OpenACS documentation staff.
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="subsites-requirements-intro"></a>Introduction</h3></div></div><p>The following is a requirements document for OpenACS 4 Subsites, part of the
OpenACS 4 Kernel. The Subsites system allows one OpenACS server instance to serve
multiple user communities, by enabling the suite of available OpenACS
-applications to be customized for defined user communities.</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="subsites-requirements-vision"></a>Vision Statement</h3></div></div>
-<p>Many online communities are also collections of discrete subcommunities,
+applications to be customized for defined user communities.</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="subsites-requirements-vision"></a>Vision Statement</h3></div></div><p>Many online communities are also collections of discrete subcommunities,
reflecting real-world relationships. For example, a corporate
intranet/extranet website serves both units within the company (e.g.,
offices, departments, teams, projects) and external parties (e.g., customers,
partners, vendors). Subsites enable a single OpenACS instance to provide each
subcommunity with its own "virtual website," by assembling OpenACS
packages that together deliver a feature set tailored to the needs of the
-subcommunity.</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="subsites-requirements-system-overview"></a>System Overview</h3></div></div>
-<p>The OpenACS subsite system allows a single OpenACS installation to serve multiple
+subcommunity.</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="subsites-requirements-system-overview"></a>System Overview</h3></div></div><p>The OpenACS subsite system allows a single OpenACS installation to serve multiple
communities. At an implementation level this is primarily accomplished by
having an application "scope" its content to a particular package
instance. The <a href="rp-design.html" title="OpenACS 4 Request Processor Design">request
processor</a> then figures out which package_id a particular URL references
and then provides this information through the <tt>ad_conn</tt> api (<tt>[ad_conn
-package_id]</tt>, <tt>[ad_conn package_url]</tt>).</p>
-<p>The other piece of the subsite system is a subsite package that provides
+package_id]</tt>, <tt>[ad_conn package_url]</tt>).</p><p>The other piece of the subsite system is a subsite package that provides
subsite admins a "control panel" for administering their subsite.
This is the same package used to provide all the community core functionality
available at the "main" site which is in fact simply another
-subsite.</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="subsites-requirements-use-cases"></a>Use-cases and User-scenarios</h3></div></div>
-<p>The Subsites functionality is intended for use by two different classes of
-users:</p>
-<div class="orderedlist"><ol type="1">
-<li><p>Package programmers (referred to as 'the programmer') must
-develop subcommunity-aware applications.</p></li>
-<li><p>Site administrators (referred to as 'the administrator') use
+subsite.</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="subsites-requirements-use-cases"></a>Use-cases and User-scenarios</h3></div></div><p>The Subsites functionality is intended for use by two different classes of
+users:</p><div class="orderedlist"><ol type="1"><li><p>Package programmers (referred to as 'the programmer') must
+develop subcommunity-aware applications.</p></li><li><p>Site administrators (referred to as 'the administrator') use
subsites to provide tailored "virtual websites" to different
-subcommunities.</p></li>
-</ol></div>
-<p>Joe Programmer is working on the bboard package and wants to make it
+subcommunities.</p></li></ol></div><p>Joe Programmer is working on the bboard package and wants to make it
subsite-aware. Using [ad_conn package_id], Joe adds code that only displays
bboard messages associated with the current package instance. Joe is happy to
realize that ad_parameter is already smart enough to return configuration
parameters for the current package instance, and so he has to do no extra
-work to tailor configuration parameters to the current subsite.</p>
-<p>Jane Admin maintains www.company.com. She learns of Joe's work and
+work to tailor configuration parameters to the current subsite.</p><p>Jane Admin maintains www.company.com. She learns of Joe's work and
would like to set up individual bboards for the Boston and Austin offices of
her company. The first thing she does is use the APM to install the new
-bboard package.</p>
-<p>Next, Jane uses the Subsite UI to create subsites for the Boston and
+bboard package.</p><p>Next, Jane uses the Subsite UI to create subsites for the Boston and
Austin offices. Then Jane uses the Subsite UI to create bboards for each
-office.</p>
-<p>Now, the Boston office employees have their own bboard at
+office.</p><p>Now, the Boston office employees have their own bboard at
http://www.company.com/offices/boston/bboard, and similarly for the Austin
office. At this point, the Boston and Austin office admins can customize the
configurations for each of their bboards, or they can just use the
-defaults.</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="subsites-requirements-links"></a>Related Links</h3></div></div>
-<div class="itemizedlist"><ul>
-<li><p><a href="subsites-design.html">OpenACS 4 Subsites Design Document</a></p></li>
-<li><p>Test plan (Not available yet)</p></li>
-</ul></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="subsites-requirements-api"></a>Requirements: Programmer's API</h3></div></div>
-<p>A subsite API is required for programmers to ensure their packages are
-subsite-aware. The following functions should be sufficient for this:</p>
-<p><span class="strong"><i>10.10.0 Package creation</i></span></p>
-<p>The system must provide an API call to create a package, and it must be
-possible for the context (to which the package belongs) to be specified.</p>
-<p><span class="strong"><i>10.20.0 Package deletion</i></span></p>
-<p>The system must provide an API call to delete a package and all related
-objects in the subsite's context.</p>
-<p><span class="strong"><i>10.30.0 Object's package information</i></span></p>
-<p>Given an object ID, the system must provide an API call to determine the
-package (ID) to which the object belongs.</p>
-<p><span class="strong"><i>10.40.0 URL from package</i></span></p>
-<p>Given a package (ID), the system must provide an API call to return the
-canonical URL for that package.</p>
-<p><span class="strong"><i>10.50.0 Main subsite's package_id</i></span></p>
-<p>The system must provide an API call to return a package ID corresponding
-to the main subsite's package ID (the degenerate subsite).</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="subsites-requirements-ui"></a>Requirements: The User Interface</h3></div></div>
-<p><span class="strong"><i>The Programmer's User Interface</i></span></p>
-<p>There is no programmer's UI, other than the API described above.</p>
-<p><span class="strong"><i>The Administrator's User Interface</i></span></p>
-<p>The UI for administrators is a set of HTML pages that are used to drive
+defaults.</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="subsites-requirements-links"></a>Related Links</h3></div></div><div class="itemizedlist"><ul type="disc"><li><p><a href="subsites-design.html">OpenACS 4 Subsites Design Document</a></p></li><li><p>Test plan (Not available yet)</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="subsites-requirements-api"></a>Requirements: Programmer's API</h3></div></div><p>A subsite API is required for programmers to ensure their packages are
+subsite-aware. The following functions should be sufficient for this:</p><p><span class="strong"><em>10.10.0 Package creation</em></span></p><p>The system must provide an API call to create a package, and it must be
+possible for the context (to which the package belongs) to be specified.</p><p><span class="strong"><em>10.20.0 Package deletion</em></span></p><p>The system must provide an API call to delete a package and all related
+objects in the subsite's context.</p><p><span class="strong"><em>10.30.0 Object's package information</em></span></p><p>Given an object ID, the system must provide an API call to determine the
+package (ID) to which the object belongs.</p><p><span class="strong"><em>10.40.0 URL from package</em></span></p><p>Given a package (ID), the system must provide an API call to return the
+canonical URL for that package.</p><p><span class="strong"><em>10.50.0 Main subsite's package_id</em></span></p><p>The system must provide an API call to return a package ID corresponding
+to the main subsite's package ID (the degenerate subsite).</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="subsites-requirements-ui"></a>Requirements: The User Interface</h3></div></div><p><span class="strong"><em>The Programmer's User Interface</em></span></p><p>There is no programmer's UI, other than the API described above.</p><p><span class="strong"><em>The Administrator's User Interface</em></span></p><p>The UI for administrators is a set of HTML pages that are used to drive
the underlying API for package instance management (i.e. adding, removing, or
altering packages). It is restricted to administrators of the current subsite
such that administrators can only manage their own subsites. Of course,
-Site-Wide Administrators can manage all subsites.</p>
-<div class="itemizedlist"><ul>
-<li>
-<p><span class="strong"><i>20.10.0 Package creation</i></span></p>
-<p>
-<span class="strong"><i>20.10.1</i></span> The administrator should be able to create a
-package and make it available at a URL underneath the subsite.</p>
-</li>
-<li>
-<p><span class="strong"><i>20.20.0 Package deactivation</i></span></p>
-<p>
-<span class="strong"><i>20.20.1</i></span> The administrator should be able to deactivate
-any package, causing it to be inaccessible to users.</p>
-<p>
-<span class="strong"><i>20.20.5</i></span> Deactivating a package makes the package no
+Site-Wide Administrators can manage all subsites.</p><div class="itemizedlist"><ul type="disc"><li><p><span class="strong"><em>20.10.0 Package creation</em></span></p><p><span class="strong"><em>20.10.1</em></span> The administrator should be able to create a
+package and make it available at a URL underneath the subsite.</p></li><li><p><span class="strong"><em>20.20.0 Package deactivation</em></span></p><p><span class="strong"><em>20.20.1</em></span> The administrator should be able to deactivate
+any package, causing it to be inaccessible to users.</p><p><span class="strong"><em>20.20.5</em></span> Deactivating a package makes the package no
longer accessible, but it does not remove data created within the context of
-that package.</p>
-</li>
-</ul></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="subsites-requirements-rev-history"></a>Revision History</h3></div></div>
-<div class="informaltable"><table border="1">
-<colgroup>
-<col>
-<col>
-<col>
-<col>
-</colgroup>
-<tbody>
-<tr>
-<td><span class="strong"><i>Document Revision #</i></span></td>
-<td><span class="strong"><i>Action Taken, Notes</i></span></td>
-<td><span class="strong"><i>When?</i></span></td>
-<td><span class="strong"><i>By Whom?</i></span></td>
-</tr>
-<tr>
-<td>0.1</td>
-<td>Creation</td>
-<td>08/18/2000</td>
-<td>Dennis Gregorovic</td>
-</tr>
-<tr>
-<td>0.2</td>
-<td>Edited, reviewed</td>
-<td>08/29/2000</td>
-<td>Kai Wu</td>
-</tr>
-</tbody>
-</table></div>
-</div>
-</div>
-<div class="navfooter">
-<hr>
-<table width="100%" summary="Navigation footer">
-<tr>
-<td width="40%" align="left">
-<a accesskey="p" href="groups-design.html">Prev</a> </td>
-<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
-<td width="40%" align="right"> <a accesskey="n" href="subsites-design.html">Next</a>
-</td>
-</tr>
-<tr>
-<td width="40%" align="left">OpenACS 4 Groups Design </td>
-<td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td>
-<td width="40%" align="right"> OpenACS 4 Subsites Design Document</td>
-</tr>
-</table>
-<hr>
-<address>
- rmello at fslc.usu.edu
- </address>
-<address><a href="mailto:vinod@kurup.com">
+that package.</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="subsites-requirements-rev-history"></a>Revision History</h3></div></div><div class="informaltable"><table border="1"><colgroup><col><col><col><col></colgroup><tbody><tr><td><span class="strong"><em>Document Revision #</em></span></td><td><span class="strong"><em>Action Taken, Notes</em></span></td><td><span class="strong"><em>When?</em></span></td><td><span class="strong"><em>By Whom?</em></span></td></tr><tr><td>0.1</td><td>Creation</td><td>08/18/2000</td><td>Dennis Gregorovic</td></tr><tr><td>0.2</td><td>Edited, reviewed</td><td>08/29/2000</td><td>Kai Wu</td></tr></tbody></table></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="groups-design.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="subsites-design.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS 4 Groups Design </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> OpenACS 4 Subsites Design Document</td></tr></table><hr><address>rmello at fslc.usu.edu</address><address><a href="mailto:vinod@kurup.com">
vinod@kurup.com
- </a></address>
-</div>
-</body>
-</html>
+ </a></address></div></body></html>
Index: openacs-4/packages/acs-core-docs/www/subsites.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/subsites.html,v
diff -u -r1.7 -r1.7.2.1
--- openacs-4/packages/acs-core-docs/www/subsites.html 7 Mar 2002 06:55:36 -0000 1.7
+++ openacs-4/packages/acs-core-docs/www/subsites.html 15 May 2002 23:26:18 -0000 1.7.2.1
@@ -1,37 +1,11 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type">
-<title>Writing OpenACS 4.5 Application Pages</title>
-<meta name="generator" content="DocBook XSL Stylesheets V1.45">
-<link rel="home" href="index.html" title="OpenACS Documentation">
-<link rel="up" href="dev-guide.html" title="Chapter 4. OpenACS Developer's Guide">
-<link rel="previous" href="permissions.html" title="Groups, Context, Permissions">
-<link rel="next" href="more-developer-info.html" title="Chapter 5. Other Developer Resources">
-<link rel="stylesheet" href="openacs.css" type="text/css">
-</head>
-<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-<div class="navheader">
-<a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr>
-<td width="20%" align="left">
-<a accesskey="p" href="permissions.html">Prev</a> </td>
-<th width="60%" align="center">Chapter 4. OpenACS Developer's Guide</th>
-<td width="20%" align="right"> <a accesskey="n" href="more-developer-info.html">Next</a>
-</td>
-</tr></table>
-<hr>
-</div>
-<div class="sect1">
-<div class="titlepage"><div><h2 class="title" style="clear: both">
-<a name="subsites"></a>Writing OpenACS 4.5 Application Pages</h2></div></div>
-<div class="authorblurb"><p>
+<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"><title>Writing OpenACS 4.5 Application Pages</title><meta name="generator" content="DocBook XSL Stylesheets V1.50.0"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="dev-guide.html" title="Chapter 4. OpenACS Developer's Guide"><link rel="previous" href="permissions.html" title="Groups, Context, Permissions"><link rel="next" href="more-developer-info.html" title="Chapter 5. Other Developer Resources"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="permissions.html">Prev</a> </td><th width="60%" align="center">Chapter 4. OpenACS Developer's Guide</th><td width="20%" align="right"> <a accesskey="n" href="more-developer-info.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="subsites"></a>Writing OpenACS 4.5 Application Pages</h2></div></div><div class="authorblurb"><p><p>
By <a href="http://planitia.org/" target="_top">Rafael H. Schloming</a>
and <a href="mailto:psu@arsdigita.com" target="_top">Pete Su</a>
-</p></div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="subsites-overview"></a>Overview</h3></div></div>
-<p>
+</p><br>
+ OpenACS docs are written by the named authors, but may be edited
+ by OpenACS documentation staff.
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="subsites-overview"></a>Overview</h3></div></div><p>
In this document, we'll examine the user interface pages of the Notes
application in more detail, covering two separate aspects of page
development in OpenACS 4.5. First, we'll talk about the code needed to make
@@ -40,84 +14,60 @@
form-based user interfaces in OpenACS 4.5. While these seem like unrelated
topics, they both come up in the example page that we are going to
look at, so it makes sense to address them at the same time.
-</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="subsites-instances"></a>Application Instances and Subsites</h3></div></div>
-<p>
+</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="subsites-instances"></a>Application Instances and Subsites</h3></div></div><p>
As you will recall from the <a href="packages.html" title="OpenACS 4.5 Packages">packages</a> tutorial, the Request
Processor (RP) and Package Manager (APM) in OpenACS 4.5 allow site
administrators to define an arbitrary mapping from URLs in the site to
objects representing content. These objects may represent single
files, or entire applications. The APM uses the site map to map
application instances to particular URLs within a site. We call
-creating such a mapping <span class="emphasis"><i>mounting</i></span> the application instance at a
+creating such a mapping <span class="emphasis"><em>mounting</em></span> the application instance at a
particular URL. The tutorial also showed how a given URL is
translated into a physical file to serve using the site map. We'll
repeat this description here, assuming that you have mounted an
instance of Notes at the URL <tt>/notes</tt> as we did in the <a href="packages.html#packages-looks" title="What a Package Looks Like">packages-example</a>:
-</p>
-<div class="itemizedlist"><ul>
-<li><p>
+</p><div class="itemizedlist"><ul type="disc"><li><p>
AOLserver receives your request for the URL <tt>/notes/somepage</tt>.
-</p></li>
-<li><p>
+</p></li><li><p>
This URL is passed to the request processor.
-</p></li>
-<li><p>
+</p></li><li><p>
The RP looks up the URL in the site map, and sees that the object
mounted at that location is an instance of the <tt>notes</tt>
application.
-</p></li>
-<li><p>
+</p></li><li><p>
The RP asks the package manager where in the file system the Notes
package lives. In the standard case, this would be
<tt>ROOT/packages/notes</tt>.
-</p></li>
-<li><p>
+</p></li><li><p>
The RP translates the URL to serve a page relative to the page root of
the application, which is
<tt>ROOT/packages/notes/www/</tt>. Therefore, the page that is
finally served is <tt>ROOT/packages/notes/www/hello.html</tt>,
which is what we wanted.
-</p></li>
-</ul></div>
-<p>
+</p></li></ul></div><p>
What is missing from this description is a critical fact for
application developers: In addition to working out what file to serve,
the RP also stores information about which package instance the file
belongs to into the AOLserver connection environment. The following
<tt>ad_conn</tt> interfaces can be used to extract this
information:
-</p>
-<div class="variablelist"><dl>
-<dt><span class="term"><tt>[ad_conn package_url]</tt></span></dt>
-<dd><p>
+</p><div class="variablelist"><dl><dt><span class="term"><tt>[ad_conn package_url]</tt></span></dt><dd><p>
If the URL refers to a package instance, this is the URL to the root
of the tree where the package is mounted.
-</p></dd>
-<dt><span class="term"><tt>[ad_conn package_id]</tt></span></dt>
-<dd><p>
+</p></dd><dt><span class="term"><tt>[ad_conn package_id]</tt></span></dt><dd><p>
If the URL refers to a package instance, this is the ID of that
package instance.
-</p></dd>
-<dt><span class="term"><tt>[ad_conn package_key]</tt>
+</p></dd><dt><span class="term"><tt>[ad_conn package_key]</tt>
-</span></dt>
-<dd><p>
+</span></dt><dd><p>
If the URL refers to a package instance, this is the unique key name
of the package.
-</p></dd>
-<dt><span class="term"><tt>[ad_conn extra_url]</tt>
+</p></dd><dt><span class="term"><tt>[ad_conn extra_url]</tt>
-</span></dt>
-<dd><p>
+</span></dt><dd><p>
If we found the URL in the site map, this is the tail of the URL
following the part that matched a site map entry.
-</p></dd>
-</dl></div>
-<p>
+</p></dd></dl></div><p>
In the Notes example, we are particularly interested in the
<tt>package_id</tt> field. If you study the data model and code,
you'll see why. As we said before in the <a href="objects.html" title="OpenACS 4.5 Data Models and the Object System">data modeling</a> tutorial, the Notes application points the
@@ -128,14 +78,12 @@
owner of the package to easily define access control policies for all
the notes in a particular instance just my setting permissions on the
package instance itself.
-</p>
-<p>
+</p><p>
The code for adding and editing notes, in
<tt>notes/www/add-edit.tcl</tt>, shows how this works. At the top
of the page, we extract the <tt>package_id</tt> and use it to do
permission checks:
-</p>
-<pre class="programlisting">
+</p><pre class="programlisting">
set package_id [ad_conn package_id]
@@ -149,17 +97,14 @@
set context_bar [ad_context_bar "New Note"]
}
-</pre>
-<p>
+</pre><p>
This code figures out whether we are editing an existing note or
creating a new one. It then ensures that we have the right privileges
for each action.
-</p>
-<p>
+</p><p>
Later, when we actually create a note, the SQL that we run ensures
that the <tt>context_id</tt> is set the right way:
-</p>
-<pre class="programlisting">
+</p><pre class="programlisting">
db_dml new_note {
declare
@@ -176,43 +121,33 @@
end;
}
-</pre>
-<p>
+</pre><p>
The rest of this page makes calls to the form builder part of the
template system. This API allows you to write forms-based pages
without generating a lot of duplicated HTML in your pages. It also
encapsulates most of the common logic that we use in dealing with
forms, which we'll discuss next.
-</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="subsites-using-forms"></a>Using Forms</h3></div></div>
-<p>
+</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="subsites-using-forms"></a>Using Forms</h3></div></div><p>
The forms API is pretty simple: You use calls in the
<tt>template::form</tt> namespace in your Tcl script to create
form elements. The final template page then picks this stuff up and
lays the form out for the user. The form is set up to route submit
buttons and whatnot back to the same Tcl script that set up the
form, so your Tcl script will also contain the logic needed to process
these requests.
-</p>
-<p>
+</p><p>
So, given this outline, here is a breakdown of how the forms code
works in the <tt>add-edit.tcl</tt> page. First, we create a form object
called <tt>new_note</tt>:
-</p>
-<pre class="programlisting">
+</p><pre class="programlisting">
template::form create new_note
-</pre>
-<p>
+</pre><p>
All the forms related code in this page will refer back to this
object. In addition, the <tt>adp</tt> part of this page does
nothing but display the form object:
-</p>
-<pre class="programlisting">
+</p><pre class="programlisting">
<master>
@@ -224,12 +159,10 @@
<formtemplate id="new_note"></formtemplate>
</center>
-</pre>
-<p>
+</pre><p>
The next thing that the Tcl page does is populate the form with form
elements. This code comes first:
-</p>
-<pre class="programlisting">
+</p><pre class="programlisting">
if {[template::form is_request new_note] && [info exists note_id]} {
@@ -245,46 +178,36 @@
}
}
-</pre>
-<p>
+</pre><p>
The <tt>if_request</tt> call returns true if we are asking the
page to render the form for the first time. That is, we are rendering
the form to ask the user for input. The <tt>tcl</tt> part of a
form page can be called in 3 different states: the initial request,
the initial submission, and the validated submission. These states
reflect the typical logic of a forms based page in OpenACS:
-</p>
-<div class="itemizedlist"><ul>
-<li><p>
+</p><div class="itemizedlist"><ul type="disc"><li><p>
First render the input form.
-</p></li>
-<li><p>
+</p></li><li><p>
Next, control passes to a validation page that checks and confirms the
inputs.
-</p></li>
-<li><p>
+</p></li><li><p>
Finally, control passes to the page that performs the update in the
database.
-</p></li>
-</ul></div>
-<p>
+</p></li></ul></div><p>
The rest of the <tt>if</tt> condition figures out if we are
creating a new note or editing an existing note. If
<tt>note_id</tt> is passed to us from the calling page, we assume
that we are editing an existing note. In this case, we do a database
query to grab the data for the note so we can populate the form with
it.
-</p>
-<p>
+</p><p>
The next two calls create form elements where the user can insert or
edit the title and body of the Note. The interface to
<tt>template::element</tt> is pretty straightforward.
-</p>
-<p>
+</p><p>
Finally, the code at the bottom of the page performs the actual
database updates when the form is submitted and validated:
-</p>
-<pre class="programlisting">
+</p><pre class="programlisting">
if [template::form is_valid new_note] {
set user_id [ad_conn user_id]
@@ -317,19 +240,13 @@
ad_returnredirect "."
}
-</pre>
-<p>
+</pre><p>
In this simple example, we don't do any custom validation. The nice
thing about using this API is that the forms library handles all of
the HTML rendering, input validation and database transaction logic on
your behalf. This means that you can write pages without duplicating
all of that code in every set of pages that uses forms.
-</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="subsites-how-it-all-fits"></a>How it All Fits</h3></div></div>
-<p>
+</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="subsites-how-it-all-fits"></a>How it All Fits</h3></div></div><p>
To watch all of this work, use the installer to update the Notes
package with the new code that you grabbed out of CVS or the package
repository, mount an instance of Notes somewhere in your server and
@@ -339,62 +256,27 @@
home page, and set up the permissions so that the instance is only
visible to that user. The end result is a site where users can come
and write notes to themselves.
-</p>
-<p>
+</p><p>
This is a good example of the leverage available in the OpenACS 4.5
system. The code that we have written for Notes is not at all more
complex than a similar application without access control or site map
awareness. By adding a small amount of code, we have taken a small,
simple, and special purpose application to something that has the
potential to be a very useful, general-purpose tool, complete with
multi-user features, access control, and centralized administration.
-</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="subsites-summary"></a>Summary</h3></div></div>
-<p>
+</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="subsites-summary"></a>Summary</h3></div></div><p>
In OpenACS 4.5, application pages and scripts can be aware of the package
instance, or subsite in which they are executing. This is a powerful
general purpose mechanism that can be used to structure web services
in very flexible ways.
-</p>
-<p>
+</p><p>
We saw how to use this mechanism in the Notes application and how it
makes it possible to easily turn Notes into an application that
appears to provide each user in a system with their own private notes
database.
-</p>
-<p>
+</p><p>
We also saw how to use the templating system's forms API in a simple
way, to create forms based pages with minimal duplication of code.
-</p>
-<p><div class="cvstag">($Id$)</div></p>
-</div>
-</div>
-<div class="navfooter">
-<hr>
-<table width="100%" summary="Navigation footer">
-<tr>
-<td width="40%" align="left">
-<a accesskey="p" href="permissions.html">Prev</a> </td>
-<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
-<td width="40%" align="right"> <a accesskey="n" href="more-developer-info.html">Next</a>
-</td>
-</tr>
-<tr>
-<td width="40%" align="left">Groups, Context, Permissions </td>
-<td width="20%" align="center"><a accesskey="u" href="dev-guide.html">Up</a></td>
-<td width="40%" align="right"> Chapter 5. Other Developer Resources</td>
-</tr>
-</table>
-<hr>
-<address>
- rmello at fslc.usu.edu
- </address>
-<address><a href="mailto:vinod@kurup.com">
+</p><p><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="permissions.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="more-developer-info.html">Next</a></td></tr><tr><td width="40%" align="left">Groups, Context, Permissions </td><td width="20%" align="center"><a accesskey="u" href="dev-guide.html">Up</a></td><td width="40%" align="right"> Chapter 5. Other Developer Resources</td></tr></table><hr><address>rmello at fslc.usu.edu</address><address><a href="mailto:vinod@kurup.com">
vinod@kurup.com
- </a></address>
-</div>
-</body>
-</html>
+ </a></address></div></body></html>
Index: openacs-4/packages/acs-core-docs/www/tcl-doc.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tcl-doc.html,v
diff -u -r1.7 -r1.7.2.1
--- openacs-4/packages/acs-core-docs/www/tcl-doc.html 7 Mar 2002 06:55:36 -0000 1.7
+++ openacs-4/packages/acs-core-docs/www/tcl-doc.html 15 May 2002 23:26:18 -0000 1.7.2.1
@@ -1,93 +1,45 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type">
-<title>Documenting Tcl Files: Page Contracts and Libraries</title>
-<meta name="generator" content="DocBook XSL Stylesheets V1.45">
-<link rel="home" href="index.html" title="OpenACS Documentation">
-<link rel="up" href="kernel-doc.html" title="Chapter 7. Kernel Documentation">
-<link rel="previous" href="db-api-detailed.html" title="Database Access API">
-<link rel="next" href="bootstrap-acs.html" title="Bootstrapping OpenACS">
-<link rel="stylesheet" href="openacs.css" type="text/css">
-</head>
-<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-<div class="navheader">
-<a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr>
-<td width="20%" align="left">
-<a accesskey="p" href="db-api-detailed.html">Prev</a> </td>
-<th width="60%" align="center">Chapter 7. Kernel Documentation</th>
-<td width="20%" align="right"> <a accesskey="n" href="bootstrap-acs.html">Next</a>
-</td>
-</tr></table>
-<hr>
-</div>
-<div class="sect1">
-<div class="titlepage"><div><h2 class="title" style="clear: both">
-<a name="tcl-doc"></a>Documenting Tcl Files: Page Contracts and Libraries</h2></div></div>
-<div class="authorblurb"><p>
+<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"><title>Documenting Tcl Files: Page Contracts and Libraries</title><meta name="generator" content="DocBook XSL Stylesheets V1.50.0"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="kernel-doc.html" title="Chapter 7. Kernel Documentation"><link rel="previous" href="db-api-detailed.html" title="Database Access API"><link rel="next" href="bootstrap-acs.html" title="Bootstrapping OpenACS"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="db-api-detailed.html">Prev</a> </td><th width="60%" align="center">Chapter 7. Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="bootstrap-acs.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="tcl-doc"></a>Documenting Tcl Files: Page Contracts and Libraries</h2></div></div><div class="authorblurb"><p>
by <a href="mailto:jsalz@mit.edu" target="_top">Jon Salz</a> on 3 July 2000
-</p></div>
-<div class="itemizedlist"><ul><li><p>Tcl procedures: /packages/acs-kernel/tcl-documentation-procs.tcl</p></li></ul></div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="tcl-doc-bigpicture"></a>The Big Picture</h3></div></div>
-<p>In versions of the OpenACS prior to 3.4, <a href="/doc/standards" target="_top">the standard
+<br>
+ OpenACS docs are written by the named authors, but may be edited
+ by OpenACS documentation staff.
+ </p></div><div class="itemizedlist"><ul type="disc"><li><p>Tcl procedures: /packages/acs-kernel/tcl-documentation-procs.tcl</p></li></ul></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="tcl-doc-bigpicture"></a>The Big Picture</h3></div></div><p>In versions of the OpenACS prior to 3.4, <a href="/doc/standards" target="_top">the standard
place</a> to document Tcl files (both Tcl pages and Tcl library files) was in
-a comment at the top of the file:</p>
-<pre class="programlisting">
+a comment at the top of the file:</p><pre class="programlisting">
#
-# <span class="emphasis"><i>path from server home</i></span>/<span class="emphasis"><i>filename</i></span>
+# <span class="emphasis"><em>path from server home</em></span>/<span class="emphasis"><em>filename</em></span>
#
-# <span class="emphasis"><i>Brief description of the file's purpose</i></span>
+# <span class="emphasis"><em>Brief description of the file's purpose</em></span>
#
-# <span class="emphasis"><i>author's email address</i></span>, <span class="emphasis"><i>file creation date</i></span>
+# <span class="emphasis"><em>author's email address</em></span>, <span class="emphasis"><em>file creation date</em></span>
#
# <a href="http://www.loria.fr/~molli/cvs/doc/cvs_12.html#SEC93" target="_top">$Id$</a>
#
-</pre>
-<p>
+</pre><p>
In addition, the inputs expected by a Tcl page (i.e., form variables) would
be enumerated in a call to <tt>ad_page_variables</tt>, in effect,
documenting the page's argument list.
-</p>
-<p>The problem with these practices is that the documentation is only
+</p><p>The problem with these practices is that the documentation is only
accessible by reading the source file itself. For this reason, ACS 3.4
introduces a new API for documenting Tcl files and, on top of that, a
-web-based user interface for browsing the documentation:</p>
-<div class="itemizedlist"><ul>
-<li><p>
-<span class="strong"><i><tt><a href="tcl-doc.html#tcl-doc-ad-page-contract" title="ad_page_contract">ad_page_contract</a></tt></i></span>: Every Tcl page
-has a <span class="strong"><i>contract</i></span> that explicitly defines what inputs the page
+web-based user interface for browsing the documentation:</p><div class="itemizedlist"><ul type="disc"><li><p><span class="strong"><em><tt><a href="tcl-doc.html#tcl-doc-ad-page-contract" title="ad_page_contract">ad_page_contract</a></tt></em></span>: Every Tcl page
+has a <span class="strong"><em>contract</em></span> that explicitly defines what inputs the page
expects (with more precision than <tt>ad_page_variables</tt>) and
incorporates metadata about the page (what used to live in the top-of-page
comment). Like <tt>ad_page_variables</tt>, <tt>ad_page_contract</tt>
-also sets the specified variables in the context of the Tcl page.</p></li>
-<li><p>
-<span class="strong"><i><tt><a href="tcl-doc.html#tcl-doc-ad-library" title="ad_library">ad_library</a></tt></i></span>: To be
+also sets the specified variables in the context of the Tcl page.</p></li><li><p><span class="strong"><em><tt><a href="tcl-doc.html#tcl-doc-ad-library" title="ad_library">ad_library</a></tt></em></span>: To be
called at the top of every library file (i.e., all files in the
<tt>/tcl/</tt> directory under the server root and
-<tt>*-procs.tcl</tt> files under <tt>/packages/</tt>).</p></li>
-</ul></div>
-<p>
+<tt>*-procs.tcl</tt> files under <tt>/packages/</tt>).</p></li></ul></div><p>
This has the following benefits:
-</p>
-<div class="itemizedlist"><ul>
-<li><p>Facilitates automatic generation of human-readable documentation.</p></li>
-<li><p>Promotes security, by introducing a standard and automated way to check
-inputs to scripts for correctness.</p></li>
-<li><p>Allows graphical designers to determine easily how to customize
-sites' UIs, e.g., what properties are available in templates.</p></li>
-<li><p>Allows the request processor to be intelligent: a script can specify in
+</p><div class="itemizedlist"><ul type="disc"><li><p>Facilitates automatic generation of human-readable documentation.</p></li><li><p>Promotes security, by introducing a standard and automated way to check
+inputs to scripts for correctness.</p></li><li><p>Allows graphical designers to determine easily how to customize
+sites' UIs, e.g., what properties are available in templates.</p></li><li><p>Allows the request processor to be intelligent: a script can specify in
its contract which type of abstract document it
returns, and the request processor can transform it automatically into
something useful to a particular user agent. (Don't worry about this for
-now - it's not complete for ACS 3.4.)</p></li>
-</ul></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="tcl-doc-ad-page-contract"></a>ad_page_contract</h3></div></div>
-<p>
+now - it's not complete for ACS 3.4.)</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="tcl-doc-ad-page-contract"></a>ad_page_contract</h3></div></div><p>
Currently <tt>ad_page_contract</tt> serves mostly as a replacement for
<tt>ad_page_variables</tt>. Eventually, it will be integrated closely
with the documents API so that each script's contract will document
@@ -96,9 +48,7 @@
decsribe it here yet; for now, you can just consider
<tt>ad_page_contract</tt> a newer, better, documented
<tt>ad_page_variables</tt>.)
-</p>
-<p>Let's look at an example usage of <tt>ad_page_contract</tt>:</p>
-<pre class="programlisting">
+</p><p>Let's look at an example usage of <tt>ad_page_contract</tt>:</p><pre class="programlisting">
# /packages/acs-kernel/api-doc/www/package-view.tcl
ad_page_contract {
@@ -121,145 +71,87 @@
@cvs-id $Id$
}
-</pre>
-<p>
+</pre><p>
Note that:
-</p>
-<div class="itemizedlist"><ul>
-<li><p>
-<span class="strong"><i>By convention, <tt>ad_page_contract</tt> should be preceded
-by a comment line containing the file's path</i></span>. The comment is on
+</p><div class="itemizedlist"><ul type="disc"><li><p><span class="strong"><em>By convention, <tt>ad_page_contract</tt> should be preceded
+by a comment line containing the file's path</em></span>. The comment is on
line 1, and the contract starts on line 2.
-</p></li>
-<li><p>
-<span class="strong"><i><tt>ad_page_contract</tt></i></span>'s first argument is
+</p></li><li><p><span class="strong"><em><tt>ad_page_contract</tt></em></span>'s first argument is
the list of expected arguments from the HTTP query (<tt>version_id</tt>,
<tt>public_p</tt>, <tt>kind</tt>, and <tt>format</tt>). Like
<tt>ad_page_variables</tt>, <tt>ad_page_contract</tt> sets the
corresponding Tcl variables when the page is executed.
-</p></li>
-<li><p>
-<span class="strong"><i>Arguments can have defaults</i></span>, specified using the same
+</p></li><li><p><span class="strong"><em>Arguments can have defaults</em></span>, specified using the same
syntax as in the Tcl <tt>proc</tt> (a two-element list where the first
element is the parameter name and the second argument is the default value).
-</p></li>
-<li>
-<p>
-<span class="strong"><i>Arguments can have flags</i></span>, specified by following the
+</p></li><li><p><span class="strong"><em>Arguments can have flags</em></span>, specified by following the
name of the query argument with a colon and one or more of the following
-strings (separated by commas): </p>
-<div class="itemizedlist"><ul>
-<li><p>
-<span class="strong"><i><tt>optional</tt></i></span>: the query argument doesn't
+strings (separated by commas): </p><div class="itemizedlist"><ul type="round"><li><p><span class="strong"><em><tt>optional</tt></em></span>: the query argument doesn't
need to be provided; if it's not, the variable for that argument simply
won't be set. For instance, if I call the script above without a
<tt>public_p</tt> in the query, then in the page body <tt>[info exists
public_p]</tt> will return 0.
-</p></li>
-<li><p>
-<span class="strong"><i><tt>integer</tt></i></span>: the argument must be an integer
+</p></li><li><p><span class="strong"><em><tt>integer</tt></em></span>: the argument must be an integer
(<tt>ad_page_contract</tt> will fail and display and error if not). This
flag, like the next, is intended to prevent clients from fudging query
arguments to trick scripts into executing arbitrary SQL.
-</p></li>
-<li><p>
-<span class="strong"><i><tt>sql_identifier</tt></i></span>: the argument must be a SQL
+</p></li><li><p><span class="strong"><em><tt>sql_identifier</tt></em></span>: the argument must be a SQL
identifier (i.e., <tt>[string is wordchar $the_query_var]</tt> must
return true).
-</p></li>
-<li><p>
-<span class="strong"><i><tt>trim</tt></i></span>: the argument will be [string
+</p></li><li><p><span class="strong"><em><tt>trim</tt></em></span>: the argument will be [string
trim]'ed.
-</p></li>
-<li>
-<p>
-<span class="strong"><i><tt>multiple</tt></i></span>: the argument may be specified
+</p></li><li><p><span class="strong"><em><tt>multiple</tt></em></span>: the argument may be specified
arbitrarily many times in the query string, and the variable will be set to a
list of all those values (or an empty list if it's unspecified). This is
analogous to the <tt>-multiple-list</tt> flag to
<tt>ad_page_variables</tt>, and is useful for handling form input
-generated by <tt><SELECT MULTIPLE></tt> tags and checkboxes. </p>
-<p>For instance, if <tt>dest_user_id:multiple</tt> is specified in the
-contract, and the query string is</p>
-<pre class="programlisting">
+generated by <tt><SELECT MULTIPLE></tt> tags and checkboxes. </p><p>For instance, if <tt>dest_user_id:multiple</tt> is specified in the
+contract, and the query string is</p><pre class="programlisting">
?dest_user_id=913&dest_user_id=891&dest_user_id=9
-</pre>
-<p>
+</pre><p>
then <tt>$dest_user_id</tt> is set to <tt>[list 913 891 9]</tt>.
-</p>
-</li>
-<li>
-<p>
-<span class="strong"><i><tt>array</tt></i></span>: the argument may be specified
+</p></li><li><p><span class="strong"><em><tt>array</tt></em></span>: the argument may be specified
arbitrarily many times in the query string, with parameter names with
suffixes like <tt>_1</tt>, <tt>_2</tt>, <tt>_3</tt>, etc. The
variable is set to a list of all those values (or an empty list if none are
-specified). </p>
-<p>For instance, if <tt>dest_user_id:array</tt> is specified in the
-contract, and the query string is</p>
-<pre class="programlisting">
+specified). </p><p>For instance, if <tt>dest_user_id:array</tt> is specified in the
+contract, and the query string is</p><pre class="programlisting">
?dest_user_id_0=913&dest_user_id_1=891&dest_user_id_2=9
-</pre>
-<p>
-then <tt>$dest_user_id</tt> is set to <tt>[list 913 891 9]</tt>.</p>
-</li>
-</ul></div>
-</li>
-<li>
-<p>
-<span class="strong"><i>You can provide structured, HTML-formatted documentation for your
-contract</i></span>. Note that format is derived heavily from Javadoc: a
+</pre><p>
+then <tt>$dest_user_id</tt> is set to <tt>[list 913 891 9]</tt>.</p></li></ul></div></li><li><p><span class="strong"><em>You can provide structured, HTML-formatted documentation for your
+contract</em></span>. Note that format is derived heavily from Javadoc: a
general description of the script's functionality, followed optionally by
a series of named attributes tagged by at symbols (<tt>@</tt>). You are
encouraged to provide:
-</p>
-<div class="itemizedlist"><ul>
-<li><p>A description of the functionality of the page. If the description
+</p><div class="itemizedlist"><ul type="round"><li><p>A description of the functionality of the page. If the description
contains more than one sentence, the first sentence should be a brief
summary.
-</p></li>
-<li>
-<p>A <span class="strong"><i><tt>@param</tt></i></span> tag for each allowable query
-argument. The format is </p>
-<pre class="programlisting">
+</p></li><li><p>A <span class="strong"><em><tt>@param</tt></em></span> tag for each allowable query
+argument. The format is </p><pre class="programlisting">
-@param <span class="emphasis"><i>parameter-name</i></span> <span class="emphasis"><i>description...</i></span>
+@param <span class="emphasis"><em>parameter-name</em></span> <span class="emphasis"><em>description...</em></span>
-</pre>
-</li>
-<li><p>An <span class="strong"><i><tt>@author</tt></i></span> tag for each author. Specify the
-author's name, followed his or her email address in parentheses.</p></li>
-<li><p>A <span class="strong"><i><tt>@creation-date</tt></i></span> tag indicating when the
-script was first created.</p></li>
-<li><p>A <span class="strong"><i><tt>@cvs-id</tt></i></span> tag containing the page's CVS
+</pre></li><li><p>An <span class="strong"><em><tt>@author</tt></em></span> tag for each author. Specify the
+author's name, followed his or her email address in parentheses.</p></li><li><p>A <span class="strong"><em><tt>@creation-date</tt></em></span> tag indicating when the
+script was first created.</p></li><li><p>A <span class="strong"><em><tt>@cvs-id</tt></em></span> tag containing the page's CVS
identification string. Just use <tt>$Id: tcl-documentation.html,v 1.2
2000/09/19 07:22:35 ron Exp $</tt> when creating the file, and CVS will
-substitute an appropriate string when you check the file in.</p></li>
-</ul></div>
-<p>
- These <tt>@</tt> tags are optional, but highly recommended!</p>
-</li>
-</ul></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="tcl-doc-ad-library"></a>ad_library</h3></div></div>
-<p>
+substitute an appropriate string when you check the file in.</p></li></ul></div><p>
+ These <tt>@</tt> tags are optional, but highly recommended!</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="tcl-doc-ad-library"></a>ad_library</h3></div></div><p>
<tt>ad_library</tt> provides a replacement for the informal documentation
(described above) found at the beginning of every Tcl page. Instead of:
-</p>
-<pre class="programlisting">
+</p><pre class="programlisting">
# /packages/acs-kernel/00-proc-procs.tcl
#
@@ -269,11 +161,9 @@
#
# $Id$
-</pre>
-<p>
+</pre><p>
you'll now write:
-</p>
-<pre class="programlisting">
+</p><pre class="programlisting">
# /packages/acs-kernel/00-proc-procs.tcl
ad_library {
@@ -287,49 +177,16 @@
}
-</pre>
-<p>
+</pre><p>
Note that format is derived heavily from Javadoc: a general description of
the script's functionality, followed optionally by a series of named
attributes tagged by at symbols (<tt>@</tt>). HTML formatting is allowed.
You are encouraged to provide:
-</p>
-<div class="itemizedlist"><ul>
-<li><p>An <span class="strong"><i><tt>@author</tt></i></span> tag for each author. Specify the
-author's name, followed his or her email address in parentheses.</p></li>
-<li><p>A <span class="strong"><i><tt>@creation-date</tt></i></span> tag indicating when the
-script was first created.</p></li>
-<li><p>A <span class="strong"><i><tt>@cvs-id</tt></i></span> tag containing the page's CVS
+</p><div class="itemizedlist"><ul type="disc"><li><p>An <span class="strong"><em><tt>@author</tt></em></span> tag for each author. Specify the
+author's name, followed his or her email address in parentheses.</p></li><li><p>A <span class="strong"><em><tt>@creation-date</tt></em></span> tag indicating when the
+script was first created.</p></li><li><p>A <span class="strong"><em><tt>@cvs-id</tt></em></span> tag containing the page's CVS
identification string. Just use <tt>$Id: tcl-documentation.html,v 1.2
2000/09/19 07:22:35 ron Exp $</tt> when creating the file, and CVS will
-substitute an appropriate string when you check the file in.</p></li>
-</ul></div>
-<p><div class="cvstag">($Id$)</div></p>
-</div>
-</div>
-<div class="navfooter">
-<hr>
-<table width="100%" summary="Navigation footer">
-<tr>
-<td width="40%" align="left">
-<a accesskey="p" href="db-api-detailed.html">Prev</a> </td>
-<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
-<td width="40%" align="right"> <a accesskey="n" href="bootstrap-acs.html">Next</a>
-</td>
-</tr>
-<tr>
-<td width="40%" align="left">Database Access API </td>
-<td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td>
-<td width="40%" align="right"> Bootstrapping OpenACS</td>
-</tr>
-</table>
-<hr>
-<address>
- rmello at fslc.usu.edu
- </address>
-<address><a href="mailto:vinod@kurup.com">
+substitute an appropriate string when you check the file in.</p></li></ul></div><p><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="db-api-detailed.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="bootstrap-acs.html">Next</a></td></tr><tr><td width="40%" align="left">Database Access API </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> Bootstrapping OpenACS</td></tr></table><hr><address>rmello at fslc.usu.edu</address><address><a href="mailto:vinod@kurup.com">
vinod@kurup.com
- </a></address>
-</div>
-</body>
-</html>
+ </a></address></div></body></html>
Index: openacs-4/packages/acs-core-docs/www/templates.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/templates.html,v
diff -u -r1.7 -r1.7.2.1
--- openacs-4/packages/acs-core-docs/www/templates.html 7 Mar 2002 06:55:37 -0000 1.7
+++ openacs-4/packages/acs-core-docs/www/templates.html 15 May 2002 23:26:18 -0000 1.7.2.1
@@ -1,69 +1,35 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type">
-<title>Using Templates in OpenACS 4.5</title>
-<meta name="generator" content="DocBook XSL Stylesheets V1.45">
-<link rel="home" href="index.html" title="OpenACS Documentation">
-<link rel="up" href="dev-guide.html" title="Chapter 4. OpenACS Developer's Guide">
-<link rel="previous" href="db-api.html" title="The OpenACS Database Access API">
-<link rel="next" href="permissions.html" title="Groups, Context, Permissions">
-<link rel="stylesheet" href="openacs.css" type="text/css">
-</head>
-<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-<div class="navheader">
-<a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr>
-<td width="20%" align="left">
-<a accesskey="p" href="db-api.html">Prev</a> </td>
-<th width="60%" align="center">Chapter 4. OpenACS Developer's Guide</th>
-<td width="20%" align="right"> <a accesskey="n" href="permissions.html">Next</a>
-</td>
-</tr></table>
-<hr>
-</div>
-<div class="sect1">
-<div class="titlepage"><div><h2 class="title" style="clear: both">
-<a name="templates"></a>Using Templates in OpenACS 4.5</h2></div></div>
-<div class="authorblurb"><p>By <a href="mailto:psu@arsdigita.com" target="_top">Pete Su</a>
-</p></div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="templates-overview"></a>Overview</h3></div></div>
-<p>
+<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"><title>Using Templates in OpenACS 4.5</title><meta name="generator" content="DocBook XSL Stylesheets V1.50.0"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="dev-guide.html" title="Chapter 4. OpenACS Developer's Guide"><link rel="previous" href="db-api.html" title="The OpenACS Database Access API"><link rel="next" href="permissions.html" title="Groups, Context, Permissions"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="db-api.html">Prev</a> </td><th width="60%" align="center">Chapter 4. OpenACS Developer's Guide</th><td width="20%" align="right"> <a accesskey="n" href="permissions.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="templates"></a>Using Templates in OpenACS 4.5</h2></div></div><div class="authorblurb"><p><p>By <a href="mailto:psu@arsdigita.com" target="_top">Pete Su</a></p><br>
+ OpenACS docs are written by the named authors, but may be edited
+ by OpenACS documentation staff.
+ </p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="templates-overview"></a>Overview</h3></div></div><p>
The OpenACS 4.5 Template System (ATS) is designed to allow developers to
-cleanly separate <span class="emphasis"><i>application logic</i></span> from <span class="emphasis"><i>display
-logic</i></span>. The intent is to have all of the logic related to
+cleanly separate <span class="emphasis"><em>application logic</em></span> from <span class="emphasis"><em>display
+logic</em></span>. The intent is to have all of the logic related to
manipulating the database and other application state data in one
place, and all the logic related to displaying the state of the
application in another place. This gives developer's quicker
customization and easier upgrades, and also allows developers and
graphic designers to work more independently.
-</p>
-<p>
+</p><p>
In ATS, you write two files for every user-visible page in the
system. One is a plain <tt>.tcl</tt> file and the other is a
special <tt>.adp</tt> file. The <tt>.tcl</tt> file runs a
-script that sets up a set of name/value bindings that we call <span class="emphasis"><i>data
-sources</i></span>. These <a href="/docs/acs-templating/guide/data.html" target="_top">data sources</a> are generally the results of Tcl and/or database queries
+script that sets up a set of name/value bindings that we call <span class="emphasis"><em>data
+sources</em></span>. These <a href="/docs/acs-templating/guide/data.html" target="_top">data sources</a> are generally the results of Tcl and/or database queries
or some combination thereof. The template system automatically makes
them available to the <tt>.adp</tt> file, or the display part of
the template, which is written in a combination of HTML, special
template related tags, and data source substitutions.
-</p>
-<p>
+</p><p>
In the overall context of our example OpenACS Notes application, this
document will show you how to set up a simple templated page that
displays a form to the user for entering new notes into the system. In
later sections of the DG, we'll discuss how to develop the pages that
actually add notes to the database, how to provide a separate instance
of the Notes application to every user and how to design appropriate
access control policies for the system.
-</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="templates-entering-notes"></a>Entering Notes</h3></div></div>
-<p>
+</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="templates-entering-notes"></a>Entering Notes</h3></div></div><p>
In order for the Notes application to be useful, we have to allow
users to enter data into the database. Typically, this takes two
pages: one that displays a form for data entry, and another page that
@@ -72,15 +38,13 @@
build the first of these pages. This isn't a very interesting use of
the system since we won't be displaying much data, but we'll cover
more on that end later.
-</p>
-<p>
+</p><p>
The <tt>.tcl</tt> file for the form entry template is pretty
simple. Here, the only thing we need from the database is a new ID for
the note object to be inserted. Open up a file called
<tt>note-add.tcl</tt> in the <tt>ROOT/packages/notes/www</tt>
directory, and put the following code in it:
-</p>
-<pre class="programlisting">
+</p><pre class="programlisting">
ad_page_contract {
@@ -112,12 +76,9 @@
ad_return_template "note-add"
-</pre>
-<p>
+</pre><p>
Some things to note about this code:
-</p>
-<div class="itemizedlist"><ul>
-<li><p>
+</p><div class="itemizedlist"><ul type="disc"><li><p>
The procedure <a href="tcl-doc.html#tcl-doc-ad-page-contract" title="ad_page_contract">ad_page_contract</a> is
always the first thing a <tt>.tcl</tt> file calls, if it's under
the www/ directory (i.e. not a Tcl library file). It does validation
@@ -131,29 +92,24 @@
also include overall documentation for the page in the contract, and
OpenACS has automatic tools that extract this documentation and make it
browsable.
-</p></li>
-<li><p>
+</p></li><li><p>
After being declared in the <tt>ad_page_contract</tt>, each
property is just a simple Tcl variable. The template system passes the
final value of the variable to the <tt>.adp</tt> template when the
<tt>.tcl</tt> file is processed.
-</p></li>
-<li><p>
+</p></li><li><p>
The call <tt>ad_return_template</tt> tells the template system
what <tt>.adp</tt> template page to fetch to display the
properties that have been processed. By default, the template system
will look for a file by the same name as the <tt>.tcl</tt> file
that just ran, but with an <tt>.adp</tt> extension.
-</p></li>
-</ul></div>
-<p>
+</p></li></ul></div><p>
Next we write the corresponding <tt>.adp</tt> page. This page
outputs HTML for the form, and also contains placeholders whose values
are substituted in from the properties set up by the <tt>.tcl</tt>
file. Create a file called <tt>note-add.adp</tt> in your editor,
and insert this text:
-</p>
-<pre class="programlisting">
+</p><pre class="programlisting">
<master src="master">
<property name="title">@page_title@</property>
@@ -173,8 +129,7 @@
</p>
</form>
-</pre>
-<p>
+</pre><p>
The main point to note here is: when you want to substitute a value
into a page, you put the name of the data source between two "@"
characters. Another point to note is the use of a master template:
@@ -183,8 +138,7 @@
have a master template that does the standard page headers and footers
for us - create the <tt>master.adp</tt> file, which looks like
this:
-</p>
-<pre class="programlisting">
+</p><pre class="programlisting">
<%= [ad_header $title] %>
<h2>@title@</h2>
@@ -194,60 +148,26 @@
<br clear="all">
<%= [ad_footer] %>
-</pre>
-<p>
+</pre><p>
The main subtlety in this code is the inline Tcl code for running
procs to build the header, footer, context bar, etc. Also, note the
property substitutions that happen here, the values of which are set
up in the <tt><property></tt> tags in the slave page.
-</p>
-<p>
+</p><p>
After putting all these files into
<tt>ROOT/packages/notes/www</tt>, you should be able to go to
<tt>/notes/</tt> URL for your server and see the input form.
-</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="templates-summary"></a>Summary</h3></div></div>
-<p>
+</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="templates-summary"></a>Summary</h3></div></div><p>
Templates separate application logic from display logic by requiring
the developer to write pages in two stages, one file for database
queries and application logic, and another for display. In OpenACS 4.5, the
logic part of the page is just a <tt>.tcl</tt> that sets up
-<span class="emphasis"><i>data sources</i></span> that are used by the display part of the page. The
+<span class="emphasis"><em>data sources</em></span> that are used by the display part of the page. The
display part of the page is an <tt>.adp</tt> file with some
special tags and notations for dealing with display logic and
inserting properties into the text of the page. Later on we'll get
into templates more deeply, and show how to use database queries as
data sources.
-</p>
-<p><div class="cvstag">($Id$)</div></p>
-</div>
-</div>
-<div class="navfooter">
-<hr>
-<table width="100%" summary="Navigation footer">
-<tr>
-<td width="40%" align="left">
-<a accesskey="p" href="db-api.html">Prev</a> </td>
-<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
-<td width="40%" align="right"> <a accesskey="n" href="permissions.html">Next</a>
-</td>
-</tr>
-<tr>
-<td width="40%" align="left">The OpenACS Database Access API </td>
-<td width="20%" align="center"><a accesskey="u" href="dev-guide.html">Up</a></td>
-<td width="40%" align="right"> Groups, Context, Permissions</td>
-</tr>
-</table>
-<hr>
-<address>
- rmello at fslc.usu.edu
- </address>
-<address><a href="mailto:vinod@kurup.com">
+</p><p><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="db-api.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="permissions.html">Next</a></td></tr><tr><td width="40%" align="left">The OpenACS Database Access API </td><td width="20%" align="center"><a accesskey="u" href="dev-guide.html">Up</a></td><td width="40%" align="right"> Groups, Context, Permissions</td></tr></table><hr><address>rmello at fslc.usu.edu</address><address><a href="mailto:vinod@kurup.com">
vinod@kurup.com
- </a></address>
-</div>
-</body>
-</html>
+ </a></address></div></body></html>
Index: openacs-4/packages/acs-core-docs/www/unix-install.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/Attic/unix-install.html,v
diff -u -r1.5 -r1.5.2.1
--- openacs-4/packages/acs-core-docs/www/unix-install.html 7 Mar 2002 06:55:37 -0000 1.5
+++ openacs-4/packages/acs-core-docs/www/unix-install.html 15 May 2002 23:26:18 -0000 1.5.2.1
@@ -1,66 +1,4 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type">
-<title>Chapter 2. Installing on Unix/Linux</title>
-<meta name="generator" content="DocBook XSL Stylesheets V1.45">
-<link rel="home" href="index.html" title="OpenACS Documentation">
-<link rel="up" href="acs-admin.html" title="Part Part II. For OpenACS Admins">
-<link rel="previous" href="acs-admin.html" title="Part Part II. For OpenACS Admins">
-<link rel="next" href="install-overview.html" title="Overview">
-<link rel="stylesheet" href="openacs.css" type="text/css">
-</head>
-<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-<div class="navheader">
-<a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr>
-<td width="20%" align="left">
-<a accesskey="p" href="acs-admin.html">Prev</a> </td>
-<th width="60%" align="center">Part Part II. For OpenACS Admins</th>
-<td width="20%" align="right"> <a accesskey="n" href="install-overview.html">Next</a>
-</td>
-</tr></table>
-<hr>
-</div>
-<div class="chapter">
-<div class="titlepage"><div><h2 class="title">
-<a name="unix-install"></a>Chapter 2. Installing on Unix/Linux</h2></div></div>
-<div class="toc">
-<p><b>Table of Contents</b></p>
-<dl>
-<dt><a href="install-overview.html">Overview</a></dt>
-<dt><a href="operating-system.html">Install an Operating System</a></dt>
-<dt><a href="oracle.html">Install Oracle 8.1.7</a></dt>
-<dt><a href="postgres.html">Install PostgreSQL 7.1.3</a></dt>
-<dt><a href="aolserver.html">Install AOLserver 3.3+ad13</a></dt>
-<dt><a href="openacs.html">Install OpenACS 4.5</a></dt>
-<dt><a href="nextsteps.html">Next Steps</a></dt>
-<dt><a href="credits.html">Credits</a></dt>
-</dl>
-</div>
-</div>
-<div class="navfooter">
-<hr>
-<table width="100%" summary="Navigation footer">
-<tr>
-<td width="40%" align="left">
-<a accesskey="p" href="acs-admin.html">Prev</a> </td>
-<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
-<td width="40%" align="right"> <a accesskey="n" href="install-overview.html">Next</a>
-</td>
-</tr>
-<tr>
-<td width="40%" align="left">Part Part II. For OpenACS Admins </td>
-<td width="20%" align="center"><a accesskey="u" href="acs-admin.html">Up</a></td>
-<td width="40%" align="right"> Overview</td>
-</tr>
-</table>
-<hr>
-<address>
- rmello at fslc.usu.edu
- </address>
-<address><a href="mailto:vinod@kurup.com">
+<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"><title>Chapter 2. Installing on Unix/Linux</title><meta name="generator" content="DocBook XSL Stylesheets V1.50.0"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="acs-admin.html" title="Part Part II. For OpenACS Admins"><link rel="previous" href="acs-admin.html" title="Part Part II. For OpenACS Admins"><link rel="next" href="install-overview.html" title="Overview"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="acs-admin.html">Prev</a> </td><th width="60%" align="center">Part Part II. For OpenACS Admins</th><td width="20%" align="right"> <a accesskey="n" href="install-overview.html">Next</a></td></tr></table><hr></div><div class="chapter"><div class="titlepage"><div><h2 class="title"><a name="unix-install"></a>Chapter 2. Installing on Unix/Linux</h2></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a href="install-overview.html">Overview</a></dt><dt><a href="operating-system.html">Install an Operating System</a></dt><dt><a href="oracle.html">Install Oracle 8.1.7</a></dt><dt><a href="postgres.html">Install PostgreSQL 7.1.3</a></dt><dt><a href="aolserver.html">Install AOLserver 3.3+ad13</a></dt><dt><a href="openacs.html">Install OpenACS 4.5</a></dt><dt><a href="nextsteps.html">Next Steps</a></dt><dt><a href="credits.html">Credits</a></dt></dl></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="acs-admin.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="install-overview.html">Next</a></td></tr><tr><td width="40%" align="left">Part Part II. For OpenACS Admins </td><td width="20%" align="center"><a accesskey="u" href="acs-admin.html">Up</a></td><td width="40%" align="right"> Overview</td></tr></table><hr><address>rmello at fslc.usu.edu</address><address><a href="mailto:vinod@kurup.com">
vinod@kurup.com
- </a></address>
-</div>
-</body>
-</html>
+ </a></address></div></body></html>
Index: openacs-4/packages/acs-core-docs/www/win-install.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/Attic/win-install.html,v
diff -u -r1.7 -r1.7.2.1
--- openacs-4/packages/acs-core-docs/www/win-install.html 7 Mar 2002 06:55:37 -0000 1.7
+++ openacs-4/packages/acs-core-docs/www/win-install.html 15 May 2002 23:26:19 -0000 1.7.2.1
@@ -1,60 +1,4 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type">
-<title>Chapter 3. Installing on Windows</title>
-<meta name="generator" content="DocBook XSL Stylesheets V1.45">
-<link rel="home" href="index.html" title="OpenACS Documentation">
-<link rel="up" href="acs-admin.html" title="Part Part II. For OpenACS Admins">
-<link rel="previous" href="credits.html" title="Credits">
-<link rel="next" href="win-overview.html" title="Overview">
-<link rel="stylesheet" href="openacs.css" type="text/css">
-</head>
-<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-<div class="navheader">
-<a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr>
-<td width="20%" align="left">
-<a accesskey="p" href="credits.html">Prev</a> </td>
-<th width="60%" align="center">Part Part II. For OpenACS Admins</th>
-<td width="20%" align="right"> <a accesskey="n" href="win-overview.html">Next</a>
-</td>
-</tr></table>
-<hr>
-</div>
-<div class="chapter">
-<div class="titlepage"><div><h2 class="title">
-<a name="win-install"></a>Chapter 3. Installing on Windows</h2></div></div>
-<div class="toc">
-<p><b>Table of Contents</b></p>
-<dl>
-<dt><a href="win-overview.html">Overview</a></dt>
-<dt><a href="win2k-installation.html">OpenACS Installation Guide for Windows2000</a></dt>
-</dl>
-</div>
-</div>
-<div class="navfooter">
-<hr>
-<table width="100%" summary="Navigation footer">
-<tr>
-<td width="40%" align="left">
-<a accesskey="p" href="credits.html">Prev</a> </td>
-<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
-<td width="40%" align="right"> <a accesskey="n" href="win-overview.html">Next</a>
-</td>
-</tr>
-<tr>
-<td width="40%" align="left">Credits </td>
-<td width="20%" align="center"><a accesskey="u" href="acs-admin.html">Up</a></td>
-<td width="40%" align="right"> Overview</td>
-</tr>
-</table>
-<hr>
-<address>
- rmello at fslc.usu.edu
- </address>
-<address><a href="mailto:vinod@kurup.com">
+<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"><title>Chapter 3. Installing on Windows</title><meta name="generator" content="DocBook XSL Stylesheets V1.50.0"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="acs-admin.html" title="Part Part II. For OpenACS Admins"><link rel="previous" href="credits.html" title="Credits"><link rel="next" href="win-overview.html" title="Overview"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="credits.html">Prev</a> </td><th width="60%" align="center">Part Part II. For OpenACS Admins</th><td width="20%" align="right"> <a accesskey="n" href="win-overview.html">Next</a></td></tr></table><hr></div><div class="chapter"><div class="titlepage"><div><h2 class="title"><a name="win-install"></a>Chapter 3. Installing on Windows</h2></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a href="win-overview.html">Overview</a></dt><dt><a href="win2k-installation.html">OpenACS Installation Guide for Windows2000</a></dt></dl></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="credits.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="win-overview.html">Next</a></td></tr><tr><td width="40%" align="left">Credits </td><td width="20%" align="center"><a accesskey="u" href="acs-admin.html">Up</a></td><td width="40%" align="right"> Overview</td></tr></table><hr><address>rmello at fslc.usu.edu</address><address><a href="mailto:vinod@kurup.com">
vinod@kurup.com
- </a></address>
-</div>
-</body>
-</html>
+ </a></address></div></body></html>
Index: openacs-4/packages/acs-core-docs/www/win-overview.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/Attic/win-overview.html,v
diff -u -r1.3 -r1.3.2.1
--- openacs-4/packages/acs-core-docs/www/win-overview.html 7 Mar 2002 06:55:37 -0000 1.3
+++ openacs-4/packages/acs-core-docs/www/win-overview.html 15 May 2002 23:26:19 -0000 1.3.2.1
@@ -1,54 +1,4 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type">
-<title>Overview</title>
-<meta name="generator" content="DocBook XSL Stylesheets V1.45">
-<link rel="home" href="index.html" title="OpenACS Documentation">
-<link rel="up" href="win-install.html" title="Chapter 3. Installing on Windows">
-<link rel="previous" href="win-install.html" title="Chapter 3. Installing on Windows">
-<link rel="next" href="win2k-installation.html" title="OpenACS Installation Guide for Windows2000">
-<link rel="stylesheet" href="openacs.css" type="text/css">
-</head>
-<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-<div class="navheader">
-<a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr>
-<td width="20%" align="left">
-<a accesskey="p" href="win-install.html">Prev</a> </td>
-<th width="60%" align="center">Chapter 3. Installing on Windows</th>
-<td width="20%" align="right"> <a accesskey="n" href="win2k-installation.html">Next</a>
-</td>
-</tr></table>
-<hr>
-</div>
-<div class="sect1">
-<div class="titlepage"><div><h2 class="title" style="clear: both">
-<a name="win-overview"></a>Overview</h2></div></div>
-<p>This walks you through an OpenACS installation under Windows.</p>
-</div>
-<div class="navfooter">
-<hr>
-<table width="100%" summary="Navigation footer">
-<tr>
-<td width="40%" align="left">
-<a accesskey="p" href="win-install.html">Prev</a> </td>
-<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
-<td width="40%" align="right"> <a accesskey="n" href="win2k-installation.html">Next</a>
-</td>
-</tr>
-<tr>
-<td width="40%" align="left">Chapter 3. Installing on Windows </td>
-<td width="20%" align="center"><a accesskey="u" href="win-install.html">Up</a></td>
-<td width="40%" align="right"> OpenACS Installation Guide for Windows2000</td>
-</tr>
-</table>
-<hr>
-<address>
- rmello at fslc.usu.edu
- </address>
-<address><a href="mailto:vinod@kurup.com">
+<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"><title>Overview</title><meta name="generator" content="DocBook XSL Stylesheets V1.50.0"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="win-install.html" title="Chapter 3. Installing on Windows"><link rel="previous" href="win-install.html" title="Chapter 3. Installing on Windows"><link rel="next" href="win2k-installation.html" title="OpenACS Installation Guide for Windows2000"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="win-install.html">Prev</a> </td><th width="60%" align="center">Chapter 3. Installing on Windows</th><td width="20%" align="right"> <a accesskey="n" href="win2k-installation.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="win-overview"></a>Overview</h2></div></div><p>This walks you through an OpenACS installation under Windows.</p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="win-install.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="win2k-installation.html">Next</a></td></tr><tr><td width="40%" align="left">Chapter 3. Installing on Windows </td><td width="20%" align="center"><a accesskey="u" href="win-install.html">Up</a></td><td width="40%" align="right"> OpenACS Installation Guide for Windows2000</td></tr></table><hr><address>rmello at fslc.usu.edu</address><address><a href="mailto:vinod@kurup.com">
vinod@kurup.com
- </a></address>
-</div>
-</body>
-</html>
+ </a></address></div></body></html>
Index: openacs-4/packages/acs-core-docs/www/win2k-installation.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/win2k-installation.html,v
diff -u -r1.7 -r1.7.2.1
--- openacs-4/packages/acs-core-docs/www/win2k-installation.html 7 Mar 2002 06:55:37 -0000 1.7
+++ openacs-4/packages/acs-core-docs/www/win2k-installation.html 15 May 2002 23:26:19 -0000 1.7.2.1
@@ -1,149 +1,76 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type">
-<title>OpenACS Installation Guide for Windows2000</title>
-<meta name="generator" content="DocBook XSL Stylesheets V1.45">
-<link rel="home" href="index.html" title="OpenACS Documentation">
-<link rel="up" href="win-install.html" title="Chapter 3. Installing on Windows">
-<link rel="previous" href="win-overview.html" title="Overview">
-<link rel="next" href="acs-dev.html" title="Part Part III. For OpenACS Developers">
-<link rel="stylesheet" href="openacs.css" type="text/css">
-</head>
-<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-<div class="navheader">
-<a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr>
-<td width="20%" align="left">
-<a accesskey="p" href="win-overview.html">Prev</a> </td>
-<th width="60%" align="center">Chapter 3. Installing on Windows</th>
-<td width="20%" align="right"> <a accesskey="n" href="acs-dev.html">Next</a>
-</td>
-</tr></table>
-<hr>
-</div>
-<div class="sect1">
-<div class="titlepage"><div><h2 class="title" style="clear: both">
-<a name="win2k-installation"></a>OpenACS Installation Guide for Windows2000</h2></div></div>
-<div class="authorblurb"><p>By <a href="mailto:mburke@arsdigita.com" target="_top">Matthew Burke</a> and <a href="mailto:curtisg@arsdigita.com" target="_top">Curtis Galloway</a>
-</p></div>
-<div class="itemizedlist"><ul>
-<li><p>Source: <a href="http://software.arsdigita.com/dist" target="_top">http://software.arsdigita.com/dist</a>
-</p></li>
-<li><p>Bug reports: <a href="mailto:acs-bugs@arsdigita.com" target="_top">acs-bugs@arsdigita.com</a>
-</p></li>
-<li><p>Philosophy: <a href="http://photo.net/wtr/thebook/community" target="_top">http://photo.net/wtr/thebook/community</a>
- (the community chapter of <span class="emphasis"><i>Philip and Alex's Guide to Web
- Publishing</i></span>)</p></li>
-<li><p>Technical background: <a href="http://photo.net/wtr/thebook/" target="_top">http://photo.net/wtr/thebook/</a>
-</p></li>
-</ul></div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="win2kinstall-overview"></a>Overview</h3></div></div>
-<p>
+<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"><title>OpenACS Installation Guide for Windows2000</title><meta name="generator" content="DocBook XSL Stylesheets V1.50.0"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="win-install.html" title="Chapter 3. Installing on Windows"><link rel="previous" href="win-overview.html" title="Overview"><link rel="next" href="acs-dev.html" title="Part Part III. For OpenACS Developers"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="win-overview.html">Prev</a> </td><th width="60%" align="center">Chapter 3. Installing on Windows</th><td width="20%" align="right"> <a accesskey="n" href="acs-dev.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="win2k-installation"></a>OpenACS Installation Guide for Windows2000</h2></div></div><div class="authorblurb"><p><p>By <a href="mailto:mburke@arsdigita.com" target="_top">Matthew Burke</a> and <a href="mailto:curtisg@arsdigita.com" target="_top">Curtis Galloway</a></p><br>
+ OpenACS docs are written by the named authors, but may be edited
+ by OpenACS documentation staff.
+ </p></div><p><span class="strong"><em>NOTE:</em></span> These instructions were
+ valid for ACS v4, but have not been tested with OpenACS. Currently
+ (5/2002), the best option to get OpenACS 4.5 running on Windows
+ is to use <a href="http://vmware.com" target="_top">VMware</a> and John
+ Sequeira's <a href="http://www.pobox.com/~johnseq/projects/oasisvm/" target="_top">Oasis VM
+ distribution</a>
+ </p><div class="itemizedlist"><ul type="disc"><li><p>Source: <a href="http://software.arsdigita.com/dist" target="_top">http://software.arsdigita.com/dist</a></p></li><li><p>Bug reports: <a href="mailto:acs-bugs@arsdigita.com" target="_top">acs-bugs@arsdigita.com</a></p></li><li><p>Philosophy: <a href="http://photo.net/wtr/thebook/community" target="_top">http://photo.net/wtr/thebook/community</a>
+ (the community chapter of <span class="emphasis"><em>Philip and Alex's Guide to Web
+ Publishing</em></span>)</p></li><li><p>Technical background: <a href="http://photo.net/wtr/thebook/" target="_top">http://photo.net/wtr/thebook/</a></p></li></ul></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="win2kinstall-overview"></a>Overview</h3></div></div><p>
With the recent release of a win32 version of AOLserver, it is now
possible to run the OpenACS on Windows2000 and Windows98. This document
explains the steps necessary to get the OpenACS installed and running on your
- machine. <div>Note:</div> We do not recommend running a production
+ machine. </p><div>Note:</div><p> We do not recommend running a production
server on Windows98. But the platform is more than sufficient for working
the <a href="http://photo.net/teaching/one-term-web" target="_top">problem sets</a> and
for getting a feel for the OpenACS.
-</p>
-<p>You'll need to use the ArsDigita binary distribution of AOLserver
+</p><p>You'll need to use the ArsDigita binary distribution of AOLserver
for the Win32 platform, which contains patches for several problems we
have come across in the default AOLserver binary distribution. See <a href="/aol3" target="_top">the ArsDigita AOLserver 3 distribution page</a> for
- details.</p>
-<p>You can download the binary distribution from <a href="http://arsdigita.com/download" target="_top">the ArsDigita download page</a>
+ details.</p><p>You can download the binary distribution from <a href="http://arsdigita.com/download" target="_top">the ArsDigita download page</a>
under "ArsDigita AOLserver 3 Binary Distribution for Win32."
Please read the release notes in the distribution for configuration notes
- specific to the version you are downloading.</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="win2kinstall-prerequisites"></a>Prerequisites</h3></div></div>
-<div class="itemizedlist"><ul>
-<li><p>Windows 2000 or Windows 98</p></li>
-<li><p>
-<a href="http://www.winzip.com" target="_top">WinZip</a> or any tool that can
- extract gzipped/tarred archives.</p></li>
-<li><p>
-<a href="ftp://ftp.blarg.net/users/amol/zsh" target="_top">zsh</a> (free;
- included in the binary distribution). If this link is broken try <a href="http://www.zsh.org" target="_top">http://www.zsh.org</a>.</p></li>
-<li><p>
-<a href="http://www.oracle.com" target="_top">Oracle 8</a> relational database
- management system</p></li>
-<li><p>
-<a href="http://www.aolserver.com" target="_top">AOLserver</a> (free)</p></li>
-<li><p>
-<a href="http://arsdigita.com/free-tools/oracle-driver" target="_top">ArsDigita
- Oracle driver for AOLserver</a> (free)</p></li>
-</ul></div>
-<p> It is helpful if you have Oracle interMedia Text for full-text searches.
+ specific to the version you are downloading.</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="win2kinstall-prerequisites"></a>Prerequisites</h3></div></div><div class="itemizedlist"><ul type="disc"><li><p>Windows 2000 or Windows 98</p></li><li><p><a href="http://www.winzip.com" target="_top">WinZip</a> or any tool that can
+ extract gzipped/tarred archives.</p></li><li><p><a href="ftp://ftp.blarg.net/users/amol/zsh" target="_top">zsh</a> (free;
+ included in the binary distribution). If this link is broken try <a href="http://www.zsh.org" target="_top">http://www.zsh.org</a>.</p></li><li><p><a href="http://www.oracle.com" target="_top">Oracle 8</a> relational database
+ management system</p></li><li><p><a href="http://www.aolserver.com" target="_top">AOLserver</a> (free)</p></li><li><p><a href="http://arsdigita.com/free-tools/oracle-driver" target="_top">ArsDigita
+ Oracle driver for AOLserver</a> (free)</p></li></ul></div><p> It is helpful if you have Oracle interMedia Text for full-text searches.
We're also trying to make our system work with the PLS System,
available free from <a href="http://www.pls.com" target="_top">http://www.pls.com</a>.
-</p>
-<p>Although the <tt>zsh</tt> shell is the only command-line tool
+</p><p>Although the <tt>zsh</tt> shell is the only command-line tool
required to install the OpenACS, if you are a UNIX person used to typing
<tt>ls</tt> instead of <tt>dir</tt> you'll get along much
better with the Cygwin toolkit from RedHat (available at <a href="http://sourceware.cygnus.com/cygwin" target="_top">http://sourceware.cygnus.com/cygwin</a>).
This is a development library and set of tools that gives you a very
UNIX-like environment under Windows. In particular, it includes
<tt>bash</tt>, <tt>gzip</tt> and <tt>tar</tt>, which you can
- use to perform the OpenACS installation instead of WinZip and zsh.</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="win2kinstall-oracle"></a>Your Oracle installation</h3></div></div>
-<p>
+ use to perform the OpenACS installation instead of WinZip and zsh.</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="win2kinstall-oracle"></a>Your Oracle installation</h3></div></div><p>
When you install Oracle, a good rule of thumb is "every default
setting is wrong." We will not discuss Oracle configuration here
except to mention that the OpenACS requires Oracle's NLS_DATE_FORMAT
parameter be set to 'YYYY-MM-DD'. Fixing this depends on whether
- Oracle Administration Assistant for Windows NT (<span class="emphasis"><i>yes,
- that's Windows <div>NT</div>)</i></span> will run on your
+ Oracle Administration Assistant for Windows NT (<span class="emphasis"><em>yes,
+ that's Windows <div>NT</div>)</em></span> will run on your
machine or not (in some cases, it will complain about Microsoft Managment
- Console not being installed). </p>
-<p>If it runs on your machine, proceed as follows:</p>
-<div class="orderedlist"><ol type="1">
-<li><p>Run Oracle Administration Assistant for Windows NT</p></li>
-<li><p>Navigate using the Explorer-style control in the left panel and
- select the Oracle Home for the database you wish to use.</p></li>
-<li><p>Bring up its properties dialog and add a parameter NLS_DATE_FORMAT
- with value 'YYYY-MM-DD' (<span class="emphasis"><i>without the
- quotes</i></span>)</p></li>
-<li><p>Verify the date format by logging into the database using SQL Plus
+ Console not being installed). </p><p>If it runs on your machine, proceed as follows:</p><div class="orderedlist"><ol type="1"><li><p>Run Oracle Administration Assistant for Windows NT</p></li><li><p>Navigate using the Explorer-style control in the left panel and
+ select the Oracle Home for the database you wish to use.</p></li><li><p>Bring up its properties dialog and add a parameter NLS_DATE_FORMAT
+ with value 'YYYY-MM-DD' (<span class="emphasis"><em>without the
+ quotes</em></span>)</p></li><li><p>Verify the date format by logging into the database using SQL Plus
and run the following query: <tt>select sysdate from
- dual;</tt>
-</p></li>
-</ol></div>
-<p>Otherwise you will need to perform a little registry surgery as
- follows:</p>
-<div class="orderedlist"><ol type="1">
-<li><p>Run <tt>regedit</tt> and navigate down the registry keys to
- <tt>HKEY_LOCAL_MACHINE\Software\ORACLE</tt>.</p></li>
-<li><p>
+ dual;</tt></p></li></ol></div><p>Otherwise you will need to perform a little registry surgery as
+ follows:</p><div class="orderedlist"><ol type="1"><li><p>Run <tt>regedit</tt> and navigate down the registry keys to
+ <tt>HKEY_LOCAL_MACHINE\Software\ORACLE</tt>.</p></li><li><p>
Choose the appropriate subtree; this will be <tt>HOME0</tt> if
you only have on einstallation of Oracle.
- <blockquote class="blockquote"><p>
+ </p><blockquote class="blockquote"><p>
If you are an Oracle achiever and have more than one Oracle
installation on your machine, you will see <tt>HOME0, HOME1,
HOME2</tt>, etc. Choose the subtree that corresponds to the
Oracle installtion you wish to use with the OpenACS.
- </p></blockquote>
- </p></li>
-<li><p>If the <tt>NLS_DATE_FORMAT</tt> key is already present,
+ </p></blockquote><p>
+ </p></li><li><p>If the <tt>NLS_DATE_FORMAT</tt> key is already present,
double-click on its value and change it to 'YYYY-MM-DD'
- (<span class="emphasis"><i>without the quotes</i></span>). If the key does not
+ (<span class="emphasis"><em>without the quotes</em></span>). If the key does not
exist, choose <tt>Edit->New->String Value</tt> from the menu
and type <tt>NLS_DATE_FORMAT</tt> for the name of the new value to
- create it. Then double-click on the empty value to change it.</p></li>
-<li><p>Verify the date format by logging into the database using SQL Plus
+ create it. Then double-click on the empty value to change it.</p></li><li><p>Verify the date format by logging into the database using SQL Plus
and run the following query: <tt>select sysdate from
- dual;</tt>
-</p></li>
-</ol></div>
-<p>For more information on Oracle configuration look at <a href="http://photo.net/wtr/oracle-tips" target="_top">http://photo.net/wtr/oracle-tips</a>
+ dual;</tt></p></li></ol></div><p>For more information on Oracle configuration look at <a href="http://photo.net/wtr/oracle-tips" target="_top">http://photo.net/wtr/oracle-tips</a>
or search the <a href="http://photo.net/bboard/q-and-a?topic=web/db" target="_top">Web/db Q&A
Forum</a>. One other note: the "nuke a user" admin page and
Intermedia won't run unless you set <tt>open_cursors = 500</tt>
@@ -152,210 +79,123 @@
or search the <a href="http://photo.net/bboard/q-and-a.tcl?topic=web/db" target="_top">Web/db Q&A
Forum</a>. One other note: the "nuke a user" admin page and
Intermedia won't run unless you set <tt>open_cursors = 500</tt>
- for your database.</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="win2kinstall-acs-binary"></a>The ArsDigita binary installation</h3></div></div>
-<p>
+ for your database.</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="win2kinstall-acs-binary"></a>The ArsDigita binary installation</h3></div></div><p>
Extract the ArsDigita AOLserver distribution onto the <tt>C:</tt>
drive into the default <tt>aol30</tt> directory. You can install it
on any drive, but it will make your life easier if you keep the AOLserver
binary and your OpenACS instance on the same drive. For the rest of these
instructions, we'll assume that you used drive <tt>C:</tt>.
-</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="win2kinstall-untar-acs"></a>Untar the OpenACS</h3></div></div>
-<p>
+</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="win2kinstall-untar-acs"></a>Untar the OpenACS</h3></div></div><p>
We recommend rooting webserver content in <tt>c:\web</tt>. Since most
servers these days are expected to run multiple services from multiple IP
addresses, each server gets a subdirectory from <tt>c:\web</tt>. For
example, <tt>http://scorecard.org</tt> would be rooted at
<tt>c:\web\scorecard</tt> on one of our machines and if
<tt>http://jobdirect.com</tt> were on the same box then it would be
at <tt>c:\web\jobdirect</tt>.
-</p>
-<p>For the sake of argument, we're going to assume that your service
+</p><p>For the sake of argument, we're going to assume that your service
is called "yourdomain", is going to be at
<tt>http://yourdomain.com</tt> and is rooted at
<tt>c:\web\yourdomain</tt> in the Windows 2000 file system. Note that
you'll find our definitions files starting out with
- "yourdomain.com".</p>
-<div class="itemizedlist"><ul>
-<li><p>download the OpenACS (see <a href="#source" target="_top">above</a>) into
- <tt>c:\temp\acs.tar.gz</tt>
-</p></li>
-<li><p>use WinZip (or equivalent) to extract the files to
- <tt>c:\web\yourdomain</tt>
-</p></li>
-</ul></div>
-<p>
+ "yourdomain.com".</p><div class="itemizedlist"><ul type="disc"><li><p>download the OpenACS (see <a href="#source" target="_top">above</a>) into
+ <tt>c:\temp\acs.tar.gz</tt></p></li><li><p>use WinZip (or equivalent) to extract the files to
+ <tt>c:\web\yourdomain</tt></p></li></ul></div><p>
You'll now find that <tt>c:\web\yourdomain\www</tt> contains the
document root and <tt>c:\web\yourdomain\tcl</tt> contains Tcl scripts
that are loaded when the AOLserver starts up.
-</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="win2kinstall-data-model"></a>Feeding Oracle the Data Model</h3></div></div>
-<p>
+</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="win2kinstall-data-model"></a>Feeding Oracle the Data Model</h3></div></div><p>
The entire server will behave in an unhappy manner if it connects to
Oracle and finds that, for example, the users table does not exist. Thus
you need to connect to Oracle as whatever user the AOLserver will connect
as, and feed Oracle the table definitions.
-</p>
-<div class="itemizedlist"><ul>
-<li>
-<p>
+</p><div class="itemizedlist"><ul type="disc"><li><p>
load the <tt>states</tt>, <tt>country_codes</tt> and
<tt>counties</tt> tables using the <tt>load-geo-tables</tt>
shell script in the <tt>c:\web\yourdomain\www\install</tt>
- directory. You will need to open a console window and run </p>
-<pre class="programlisting">
+ directory. You will need to open a console window and run </p><pre class="programlisting">
zsh load-geo-tables foo/foopassword
-</pre>
-<p>
+</pre><p>
You most likely will see a slew of "Commit point reached . . .
" messages. This does not indicate a problem.
- </p>
-</li>
-<li>
-<p>
+ </p></li><li><p>
cd to <tt>c:\web\yourdomain\www\doc\sql</tt> and feed Oracle the
.sql files that you find there. There is a meta-loader file,
load-data-model.sql, that includes the other files in the proper
order. To use it, open a console window and run
-</p>
-<pre class="programlisting">
+</p><pre class="programlisting">
sqlplus foo/foopassword < load-data-model.sql
-</pre>
-</li>
-<li>
-<p>
+</pre></li><li><p>
If you have interMedia installed, while still in
<tt>c:\web\yourdomain\www\doc\sql</tt>, run
-</p>
-<pre class="programlisting">
+</p><pre class="programlisting">
zsh load-site-wide-search foo foopassword ctxsys-password
-</pre>
-<p>
+</pre><p>
Note that there's no slash between <tt>foo</tt> and
<tt>foopassword</tt> here. The third argument,
<tt>ctxsys-password</tt>, is the password for interMedia
Text's special ctxsys user.
- </p>
-</li>
-</ul></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="win2kinstall-aolserver"></a>Configuring AOLServer</h3></div></div>
-<p>You will need two configuration files. The first is a Tcl file with
+ </p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="win2kinstall-aolserver"></a>Configuring AOLServer</h3></div></div><p>You will need two configuration files. The first is a Tcl file with
configuration information for AOLserver. This should be called
<tt>yourdomain</tt> and should be located in
<tt>c:\aolserve3_0</tt>. The second is an .ini file that configures
the OpenACS and is discussed <a href="#ini" target="_top">below</a>. Note that pathnames in
<tt>yourdomain</tt> must use forward slashes rather than the Windows
- back slashes. This is also true for the .ini file.</p>
-<p>The following items must be defined in <tt>yourdomain</tt>:</p>
-<div class="itemizedlist"><ul>
-<li><p>three database pools: main, subquery, and log. They must be named
- as such. The default pool will be "main".</p></li>
-<li><p>the auxconfig directory which contains the .ini file:
- <tt>c:\web\yourdomain\parameters</tt>
-</p></li>
-<li><p>the pageroot: <tt>c:\web\yourdomain\www</tt>
-</p></li>
-<li><p>the directory containing the TclLibrary:
- <tt>c:\web\yourdomain\tcl</tt>
-</p></li>
-</ul></div>
-<p>
+ back slashes. This is also true for the .ini file.</p><p>The following items must be defined in <tt>yourdomain</tt>:</p><div class="itemizedlist"><ul type="disc"><li><p>three database pools: main, subquery, and log. They must be named
+ as such. The default pool will be "main".</p></li><li><p>the auxconfig directory which contains the .ini file:
+ <tt>c:\web\yourdomain\parameters</tt></p></li><li><p>the pageroot: <tt>c:\web\yourdomain\www</tt></p></li><li><p>the directory containing the TclLibrary:
+ <tt>c:\web\yourdomain\tcl</tt></p></li></ul></div><p>
You can use <a href="/doc/files/winnsd.txt" target="_top">our template file</a> as a starting
- point (<span class="emphasis"><i>you'll need to save this file with a rather than .txt
- extension</i></span>).
-</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="wint2install-configure-acs"></a>Configuring OpenACS itself</h3></div></div>
-<p>
+ point (<span class="emphasis"><em>you'll need to save this file with a rather than .txt
+ extension</em></span>).
+</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="wint2install-configure-acs"></a>Configuring OpenACS itself</h3></div></div><p>
If you want a system that works, go to
<tt>c:\web\yourdomain\parameters</tt> and copy <tt>ad.ini</tt> to
- <tt>yourdomain.ini</tt> (<span class="emphasis"><i>or any other name different from
- <tt>ad.ini</tt></i></span>). You don't actually have to delete
+ <tt>yourdomain.ini</tt> (<span class="emphasis"><em>or any other name different from
+ <tt>ad.ini</tt></em></span>). You don't actually have to delete
<tt>ad.ini</tt>.
-</p>
-<p>Each section of <tt>yourdomain.ini</tt> has a hardcoded
+</p><p>Each section of <tt>yourdomain.ini</tt> has a hardcoded
"yourservername" in the name (e.g.
<tt>[ns/server/yourservername/acs]</tt>). This means that the OpenACS
will ignore your configuration settings unless your AOLserver name
happens to be "yourservername". Therefore you must go through
<tt>yourdomain.ini</tt> and change "yourservername" to
- whatever you're calling this particular AOLserver (<span class="emphasis"><i>look at the
- server name in the <tt>nsd</tt> file for a reference</i></span>).</p>
-<p>Unless you want pages that advertise a community called
+ whatever you're calling this particular AOLserver (<span class="emphasis"><em>look at the
+ server name in the <tt>nsd</tt> file for a reference</em></span>).</p><p>Unless you want pages that advertise a community called
"Yourdomain Network" owned by
"webmaster@yourdomain.com", you'll probably want to edit
the text of <tt>yourdomain.ini</tt> to change system-wide parameters.
If you want to see how some of these are used, a good place to look is
<tt>c:\web\yourdomain\tcl\ad-defs</tt>. The Tcl function,
<tt>ad_parameter</tt>, is used to grab parameter values from the .ini
- file.</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="wi2kinstall-starting-service"></a>Starting the Service</h3></div></div>
-<p>
+ file.</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="wi2kinstall-starting-service"></a>Starting the Service</h3></div></div><p>
Now you're ready to start things up. Before installing as a Windows
service, you might want to test the setup for configuration errors. Open
up a console window and go to <tt>c:\aol30</tt>. Then run
-</p>
-<pre class="programlisting">
+</p><pre class="programlisting">
bin\nsd -ft yourdomain.tcl
-</pre>
-<p> This will print all the AOLserver messages to the console so you can see
+</pre><p> This will print all the AOLserver messages to the console so you can see
them.
-</p>
-<p>Try to connect to your new server with a web browser. If you see the
+</p><p>Try to connect to your new server with a web browser. If you see the
message "Error in serving group pages", you probably forgot to
copy the ad.ini file in <tt>c:\web\yourdomain\parameters</tt> If
everything seems ok, you can kill the server with Control-c and then
- issue the following command to install as a Windows service:</p>
-<pre class="programlisting">
+ issue the following command to install as a Windows service:</p><pre class="programlisting">
bin\nsd -I -s yourdomain -t yourdomain.tcl
-</pre>
-<p> You can now configure error recovery and other Windows aspects of the
+</pre><p> You can now configure error recovery and other Windows aspects of the
service from the Services control panel. If you make further changes to
<tt>yourdomain</tt> or <tt>yourdomain.ini</tt> you should stop
and start the service from the Services control panel.
-</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="win2kinstall-configure-permissions"></a>Configuring Permissions</h3></div></div>
-<p>
+</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="win2kinstall-configure-permissions"></a>Configuring Permissions</h3></div></div><p>
Now, you need to protect the proper administration directories of the
OpenACS. You decide the policy although we recommend requiring the admin
directories be accessible only via an SSL connection. Here are the
directories to consider protecting:
-</p>
-<div class="itemizedlist"><ul>
-<li><p>/doc (or at least /doc/sql/ since some AOLserver configurations
- will allow a user to execute SQL files)</p></li>
-<li><p>/admin</p></li>
-<li><p>any private admin dirs for a module you might have written that are
- not underneath the /admin directory</p></li>
-</ul></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="win2kinstall-add-yourself"></a>Adding Yourself as a User and Making Yourself a Sysadmin</h3></div></div>
-<p>
+</p><div class="itemizedlist"><ul type="disc"><li><p>/doc (or at least /doc/sql/ since some AOLserver configurations
+ will allow a user to execute SQL files)</p></li><li><p>/admin</p></li><li><p>any private admin dirs for a module you might have written that are
+ not underneath the /admin directory</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="win2kinstall-add-yourself"></a>Adding Yourself as a User and Making Yourself a Sysadmin</h3></div></div><p>
The ArsDigita Community System will define two users: system and
anonymous. It will also define a user group of system administrators.
You'll want to add yourself as a user (at /register/ ) and then add
@@ -364,17 +204,10 @@
"system"). Change the system user's password. Visit the
<tt>https://yourservername.com/admin/ug/</tt> directory and add your
personal user as a site-wide administrator. Now you're bootstrapped!
-</p>
-<p>If you do not know what the system user's password is connect to
- Oracle using SQL Plus and run the following query:</p>
-<pre class="programlisting">
+</p><p>If you do not know what the system user's password is connect to
+ Oracle using SQL Plus and run the following query:</p><pre class="programlisting">
select password from users where last_name = 'system';
-</pre>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="win2kinstall-closing-down-access"></a>Closing Down Access</h3></div></div>
-<p>
+</pre></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="win2kinstall-closing-down-access"></a>Closing Down Access</h3></div></div><p>
The OpenACS ships with a user named "anonymous" (email
"anonymous") to serve as a content owner. If you're
operating a restricted-access site, make sure to change the anonymous
@@ -385,58 +218,26 @@
documentation for <a href="user-registration" target="_top">user registration and
access control</a> and decide what the appropriate user state is for
anonymous on your site.
-</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="win2kinstall-where-is-what"></a>Where to Find What</h3></div></div>
-<p>
+</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="win2kinstall-where-is-what"></a>Where to Find What</h3></div></div><p>
A few pointers:
-</p>
-<div class="itemizedlist"><ul>
-<li><p>the /register directory contains the login and registration
+</p><div class="itemizedlist"><ul type="disc"><li><p>the /register directory contains the login and registration
scripts. You can easily redirect someone to /register/index to have
- them login or register.</p></li>
-<li><p>the /pvt directory is for user-specific pages. They can only be
- accessed by people who have logged in.</p></li>
-</ul></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="win2kinstall-make-sure-it-works"></a>Making sure that it works</h3></div></div>
-<p>
+ them login or register.</p></li><li><p>the /pvt directory is for user-specific pages. They can only be
+ accessed by people who have logged in.</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="win2kinstall-make-sure-it-works"></a>Making sure that it works</h3></div></div><p>
Run the acceptance tests in <a href="/doc/acceptance-test" target="_top">/doc/acceptance-test</a>
-</p>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><h3 class="title">
-<a name="win2kinstall-multiple-acs"></a>Running Multiple Instances of the OpenACS</h3></div></div>
-<p>
+</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="win2kinstall-multiple-acs"></a>Running Multiple Instances of the OpenACS</h3></div></div><p>
You can run multiple instances of the OpenACS on a physical machine but they
must each be set up as a separate Windows service. Each instance of the
OpenACS must have its own:
-</p>
-<div class="itemizedlist"><ul>
-<li><p>Oracle tablespace and a user account with the appropriate
+</p><div class="itemizedlist"><ul type="disc"><li><p>Oracle tablespace and a user account with the appropriate
permissions on that tablespace. Each of these tablespaces must have the
- OpenACS data model loaded.</p></li>
-<li><p>file with the appropriate settings including server name,
- auxconfig, ipaddress, and port.</p></li>
-<li><p>Copy of the acs files in an appropriate directory under
- <tt>c:\web</tt>.</p></li>
-</ul></div>
-<p> Suppose you wish to run two services: <tt>lintcollectors.com</tt> and
+ OpenACS data model loaded.</p></li><li><p>file with the appropriate settings including server name,
+ auxconfig, ipaddress, and port.</p></li><li><p>Copy of the acs files in an appropriate directory under
+ <tt>c:\web</tt>.</p></li></ul></div><p> Suppose you wish to run two services: <tt>lintcollectors.com</tt> and
<tt>iguanasdirect.com</tt>. You would need the following:
-</p>
-<div class="itemizedlist"><ul>
-<li><p>an Oracle tablespace, <tt>lintcollectors</tt> with a user
- <tt>lintcollectors</tt> and password <tt>secretlint</tt>
-</p></li>
-<li><p>an Oracle tablespace, <tt>iguanasdirect</tt> with a user
- <tt>iguanasdirect</tt> and password <tt>secretiguanas</tt>
-</p></li>
-</ul></div>
-<p> For each of these tablespaces/users you would load the OpenACS data model as
+</p><div class="itemizedlist"><ul type="disc"><li><p>an Oracle tablespace, <tt>lintcollectors</tt> with a user
+ <tt>lintcollectors</tt> and password <tt>secretlint</tt></p></li><li><p>an Oracle tablespace, <tt>iguanasdirect</tt> with a user
+ <tt>iguanasdirect</tt> and password <tt>secretiguanas</tt></p></li></ul></div><p> For each of these tablespaces/users you would load the OpenACS data model as
described <a href="#data" target="_top">above</a>. Then in <tt>c:\aolserver3_0</tt>
create files for each service, i.e. <tt>lintcollectors</tt> and
<tt>iguanasdirect</tt>. These files would point to their respective
@@ -446,43 +247,13 @@
<tt>c:\web\iguanasdirect\parameters</tt>; etc. In the respective
auxconfigdirs would be the files <tt>lintcollectors.ini</tt> and
<tt>iguanasdirect.ini</tt>.
-</p>
-<p>Now open a console window and go to <tt>c:\aol30</tt>. You'll
- start up the two services as follows:</p>
-<pre class="programlisting">
+</p><p>Now open a console window and go to <tt>c:\aol30</tt>. You'll
+ start up the two services as follows:</p><pre class="programlisting">
bin\nsd -I -s lintcollectors -t lintcollectors.tcl
bin\nsd -I -s iguanasdirect -t iguanasdirect.tcl
-</pre>
-<p> In the services control panel you should see two services:
+</pre><p> In the services control panel you should see two services:
<tt>AOLserver-lintcollectors</tt> and
<tt>AOLserver-iguanasdirect</tt>.
- </p>
-<p><div class="cvstag">($Id$)</div></p>
-</div>
-</div>
-<div class="navfooter">
-<hr>
-<table width="100%" summary="Navigation footer">
-<tr>
-<td width="40%" align="left">
-<a accesskey="p" href="win-overview.html">Prev</a> </td>
-<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
-<td width="40%" align="right"> <a accesskey="n" href="acs-dev.html">Next</a>
-</td>
-</tr>
-<tr>
-<td width="40%" align="left">Overview </td>
-<td width="20%" align="center"><a accesskey="u" href="win-install.html">Up</a></td>
-<td width="40%" align="right"> Part Part III. For OpenACS Developers</td>
-</tr>
-</table>
-<hr>
-<address>
- rmello at fslc.usu.edu
- </address>
-<address><a href="mailto:vinod@kurup.com">
+ </p><p><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="win-overview.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="acs-dev.html">Next</a></td></tr><tr><td width="40%" align="left">Overview </td><td width="20%" align="center"><a accesskey="u" href="win-install.html">Up</a></td><td width="40%" align="right"> Part Part III. For OpenACS Developers</td></tr></table><hr><address>rmello at fslc.usu.edu</address><address><a href="mailto:vinod@kurup.com">
vinod@kurup.com
- </a></address>
-</div>
-</body>
-</html>
+ </a></address></div></body></html>
Index: openacs-4/packages/acs-core-docs/www/files/export-oracle.txt
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/files/export-oracle.txt,v
diff -u -r1.1.1.1 -r1.1.1.1.2.1
--- openacs-4/packages/acs-core-docs/www/files/export-oracle.txt 13 Mar 2001 22:59:26 -0000 1.1.1.1
+++ openacs-4/packages/acs-core-docs/www/files/export-oracle.txt 15 May 2002 23:26:19 -0000 1.1.1.1.2.1
@@ -3,7 +3,7 @@
HZ=
LOGNAME=oracle
ORACLE_BASE=/ora8/m01/app/oracle
-ORACLE_HOME=$ORACLE_BASE/product/8.1.6
+ORACLE_HOME=$ORACLE_BASE/product/8.1.7
PATH=$PATH:$ORACLE_HOME/bin
LD_LIBRARY_PATH=$ORACLE_HOME/lib:/lib:/usr/lib
ORA_OWNER=oracle
Index: openacs-4/packages/acs-core-docs/www/files/nsd-oracle.txt
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/files/nsd-oracle.txt,v
diff -u -r1.2 -r1.2.2.1
--- openacs-4/packages/acs-core-docs/www/files/nsd-oracle.txt 1 Feb 2002 17:09:12 -0000 1.2
+++ openacs-4/packages/acs-core-docs/www/files/nsd-oracle.txt 15 May 2002 23:26:19 -0000 1.2.2.1
@@ -1,6 +1,6 @@
-#!/bin/sh
+#!/bin/bash
-export ORACLE_HOME="/ora8/m01/app/oracle/product/8.1.6"
+export ORACLE_HOME="/ora8/m01/app/oracle/product/8.1.7"
export ORACLE_BASE="/ora8/m01/app/oracle"
export LD_LIBRARY_PATH=$ORACLE_HOME/lib:$ORACLE_HOME/ctx/lib:/usr/lib:/lib:/usr/X11R6/lib
export PATH=$ORACLE_HOME/bin:$ORACLE_HOME/ctx/lib:$PATH
Index: openacs-4/packages/acs-core-docs/www/files/nsd-postgres.txt
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/files/nsd-postgres.txt,v
diff -u -r1.1 -r1.1.2.1
--- openacs-4/packages/acs-core-docs/www/files/nsd-postgres.txt 1 Feb 2002 17:12:18 -0000 1.1
+++ openacs-4/packages/acs-core-docs/www/files/nsd-postgres.txt 15 May 2002 23:26:19 -0000 1.1.2.1
@@ -1,4 +1,4 @@
-#!/bin/sh
+#!/bin/bash
export PATH=$PATH:/usr/local/pgsql/bin
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/pgsql/lib
Index: openacs-4/packages/acs-core-docs/www/files/openacs4.tcl.txt
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/files/openacs4.tcl.txt,v
diff -u -r1.3 -r1.3.2.1
--- openacs-4/packages/acs-core-docs/www/files/openacs4.tcl.txt 7 Mar 2002 06:55:37 -0000 1.3
+++ openacs-4/packages/acs-core-docs/www/files/openacs4.tcl.txt 15 May 2002 23:26:19 -0000 1.3.2.1
@@ -63,7 +63,7 @@
#
ns_section ns/threads
ns_param mutexmeter true ;# measure lock contention
-ns_param stacksize [expr 128*1024]
+ns_param stacksize 500000
#
# MIME types.
@@ -129,7 +129,7 @@
ns_param defaultparser fancy
ns_section ns/server/${server}/adp/parsers
-ns_param fancy ".adp"
+ns_param fancy ".adp"
#
# Socket driver module (HTTP) -- nssock
@@ -159,9 +159,9 @@
#
ns_section "ns/db/drivers"
if { $database == "oracle" } {
- ns_param ora8 ${bindir}/ora8.so
+ ns_param ora8 ${bindir}/ora8.so
} else {
- ns_param postgres ${bindir}/postgres.so ;# Load PostgreSQL driver
+ ns_param postgres ${bindir}/postgres.so ;# Load PostgreSQL driver
}
#
@@ -174,9 +174,9 @@
# and even different different database servers.
#
ns_section ns/db/pools
-ns_param pool1 "Pool 1"
-ns_param pool2 "Pool 2"
-ns_param pool3 "Pool 3"
+ns_param pool1 "Pool 1"
+ns_param pool2 "Pool 2"
+ns_param pool3 "Pool 3"
ns_section ns/db/pool/pool1
ns_param maxidle 1000000000
Index: openacs-4/packages/acs-core-docs/www/xml/index.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/index.xml,v
diff -u -r1.6 -r1.6.2.1
--- openacs-4/packages/acs-core-docs/www/xml/index.xml 3 Mar 2002 06:29:41 -0000 1.6
+++ openacs-4/packages/acs-core-docs/www/xml/index.xml 15 May 2002 23:26:19 -0000 1.6.2.1
@@ -2,13 +2,13 @@
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+<!ENTITY version "4.5">
+<!ENTITY majorversion "4">
<!--
OpenACS Version.
Update this to propagate current version numbers to documents.
In documents, use &version;
-->
-<!ENTITY version "4.5">
-<!ENTITY majorversion "4">
<!-- For Developers -->
<!ENTITY api SYSTEM "developers-guide/db-api.xml">
@@ -115,7 +115,7 @@
</chapter>
- <chapter id="win-install">
+ <chapter id="win-install" xreflabel="Installing on Windows">
<title>Installing on Windows</title>
<sect1 id="win-overview" xreflabel="Windows Installation Overview">
Index: openacs-4/packages/acs-core-docs/www/xml/openacs.xsl
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/openacs.xsl,v
diff -u -r1.3 -r1.3.2.1
--- openacs-4/packages/acs-core-docs/www/xml/openacs.xsl 7 Mar 2002 06:55:37 -0000 1.3
+++ openacs-4/packages/acs-core-docs/www/xml/openacs.xsl 15 May 2002 23:26:19 -0000 1.3.2.1
@@ -3,19 +3,21 @@
version="1.1"
exclude-result-prefixes="doc">
-<!-- vinodk: This stylesheet simply imports chunk.xsl -->
-<!-- I'll add customization later -->
+<!-- vinodk: Imports chunk.xsl -->
<xsl:import href="/usr/share/sgml/docbook/stylesheet/xsl/nwalsh/html/chunk.xsl"/>
+
+<!-- vinodk: Not sure if this is needed -->
<xsl:output media-type="text/html" encoding="iso-8859-1"/>
-
+<!-- vinodk: narrower TOC's, use chunker (?), pretty file names -->
<xsl:variable name="toc.section.depth">1</xsl:variable>
<xsl:variable name="using.chunker">1</xsl:variable>
<xsl:variable name="use.id.as.filename">1</xsl:variable>
<xsl:variable name="chunk.first.sections">1</xsl:variable>
+<!-- vinodk: Add our logo to header -->
<xsl:template name="header.navigation">
<xsl:param name="prev" select="/foo"/>
<xsl:param name="next" select="/foo"/>
@@ -69,6 +71,7 @@
</xsl:template>
+<!-- vinodk: Add our emails to footer -->
<xsl:template name="footer.navigation">
<xsl:param name="prev" select="/foo"/>
<xsl:param name="next" select="/foo"/>
@@ -151,7 +154,7 @@
</table>
<hr/>
<address>
- rmello at fslc.usu.edu
+ <xsl:text>rmello at fslc.usu.edu</xsl:text>
</address>
<address>
<a>
@@ -165,9 +168,18 @@
</xsl:if>
</xsl:template>
+<!-- vinodk: for some reason, chunk.xsl doesn't have a template
+ for authorblurb. Also add doc disclaimer. -->
<xsl:template match="authorblurb">
<div class="{name(.)}">
- <xsl:apply-templates/>
+ <p>
+ <xsl:apply-templates/>
+ <br />
+ <xsl:text>
+ OpenACS docs are written by the named authors, but may be edited
+ by OpenACS documentation staff.
+ </xsl:text>
+ </p>
</div>
</xsl:template>
@@ -241,7 +253,7 @@
</head>
</xsl:template>
-<!-- make phrase a "div" tag instead of "span" -->
+<!-- vinodk: make phrase a "div" tag instead of "span" -->
<xsl:template match="phrase">
<div>
<xsl:if test="@role and $phrase.propagates.style != 0">
Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/db-api.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/db-api.xml,v
diff -u -r1.4 -r1.4.2.1
--- openacs-4/packages/acs-core-docs/www/xml/developers-guide/db-api.xml 3 Mar 2002 01:27:08 -0000 1.4
+++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/db-api.xml 15 May 2002 23:26:19 -0000 1.4.2.1
@@ -1095,3 +1095,8 @@
</sect2>
</sect1>
+<!--
+ Local Variables:
+ sgml-parent-document: ("../index.xml" "chapter" "sect1")
+ End:
+-->
Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/object-identity.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/object-identity.xml,v
diff -u -r1.3 -r1.3.2.1
--- openacs-4/packages/acs-core-docs/www/xml/developers-guide/object-identity.xml 3 Mar 2002 01:27:08 -0000 1.3
+++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/object-identity.xml 15 May 2002 23:26:19 -0000 1.3.2.1
@@ -2,9 +2,9 @@
<title>Object Identity</title>
-<authorblurb><para>
+<authorblurb>
by <ulink url="http://planitia.org">Rafael H. Schloming</ulink>
-</para></authorblurb>
+</authorblurb>
<para>One of the major design features of OpenACS &version; is the explicit representation
@@ -51,3 +51,8 @@
</sect1>
+<!--
+ Local Variables:
+ sgml-parent-document: ("../index.xml" "chapter" "sect1")
+ End:
+-->
Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/objects.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/objects.xml,v
diff -u -r1.3 -r1.3.2.1
--- openacs-4/packages/acs-core-docs/www/xml/developers-guide/objects.xml 3 Mar 2002 01:27:08 -0000 1.3
+++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/objects.xml 15 May 2002 23:26:19 -0000 1.3.2.1
@@ -555,3 +555,8 @@
</sect1>
+<!--
+ Local Variables:
+ sgml-parent-document: ("../index.xml" "chapter" "sect1")
+ End:
+-->
Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/packages.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/packages.xml,v
diff -u -r1.4 -r1.4.2.1
--- openacs-4/packages/acs-core-docs/www/xml/developers-guide/packages.xml 3 Mar 2002 01:27:08 -0000 1.4
+++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/packages.xml 15 May 2002 23:26:19 -0000 1.4.2.1
@@ -815,5 +815,8 @@
</sect1>
-
-
+<!--
+ Local Variables:
+ sgml-parent-document: ("../index.xml" "chapter" "sect1")
+ End:
+-->
Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/parties.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/parties.xml,v
diff -u -r1.3 -r1.3.2.1
--- openacs-4/packages/acs-core-docs/www/xml/developers-guide/parties.xml 3 Mar 2002 01:27:08 -0000 1.3
+++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/parties.xml 15 May 2002 23:26:19 -0000 1.3.2.1
@@ -1,9 +1,9 @@
<sect1 id="parties" xreflabel="Parties in OpenACS 4">
<title>Parties in OpenACS &version;</title>
-<authorblurb><para>
+<authorblurb>
by <ulink url="http://planitia.org">Rafael H. Schloming</ulink>
-</para></authorblurb>
+</authorblurb>
<sect2 id="parties-intro">
<title>Introduction</title>
@@ -476,3 +476,8 @@
</sect1>
+<!--
+ Local Variables:
+ sgml-parent-document: ("../index.xml" "chapter" "sect1")
+ End:
+-->
Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/permissions.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/permissions.xml,v
diff -u -r1.4 -r1.4.2.1
--- openacs-4/packages/acs-core-docs/www/xml/developers-guide/permissions.xml 3 Mar 2002 01:27:08 -0000 1.4
+++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/permissions.xml 15 May 2002 23:26:19 -0000 1.4.2.1
@@ -549,3 +549,8 @@
</sect1>
+<!--
+ Local Variables:
+ sgml-parent-document: ("../index.xml" "chapter" "sect1")
+ End:
+-->
Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/programming-with-aolserver.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/programming-with-aolserver.xml,v
diff -u -r1.2 -r1.2.2.1
--- openacs-4/packages/acs-core-docs/www/xml/developers-guide/programming-with-aolserver.xml 2 Feb 2002 03:47:32 -0000 1.2
+++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/programming-with-aolserver.xml 15 May 2002 23:26:19 -0000 1.2.2.1
@@ -2,9 +2,9 @@
<title>Programming with AOLserver</title>
-<authorblurb><para>
+<authorblurb>
by <ulink url="mailto:michael@arsdigita.com">Michael Yoon</ulink>, <ulink url="mailto:jsalz@mit.edu">Jon Salz</ulink> and <ulink url="http://www.pinds.com/lars">Lars Pind</ulink>.
-</para></authorblurb>
+</authorblurb>
<sect2 id="programming-aolserver-global">
<title>The <computeroutput>global</computeroutput> command</title>
@@ -324,3 +324,8 @@
</sect1>
+<!--
+ Local Variables:
+ sgml-parent-document: ("../index.xml" "chapter" "sect1")
+ End:
+-->
Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/rp.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/rp.xml,v
diff -u -r1.3 -r1.3.2.1
--- openacs-4/packages/acs-core-docs/www/xml/developers-guide/rp.xml 3 Mar 2002 01:27:08 -0000 1.3
+++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/rp.xml 15 May 2002 23:26:19 -0000 1.3.2.1
@@ -257,4 +257,10 @@
</sect2>
-</sect1>
\ No newline at end of file
+</sect1>
+
+<!--
+ Local Variables:
+ sgml-parent-document: ("../index.xml" "chapter" "sect1")
+ End:
+-->
Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/subsites.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/subsites.xml,v
diff -u -r1.3 -r1.3.2.1
--- openacs-4/packages/acs-core-docs/www/xml/developers-guide/subsites.xml 3 Mar 2002 01:27:08 -0000 1.3
+++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/subsites.xml 15 May 2002 23:26:19 -0000 1.3.2.1
@@ -434,3 +434,9 @@
</sect2>
</sect1>
+
+<!--
+ Local Variables:
+ sgml-parent-document: ("../index.xml" "chapter" "sect1")
+ End:
+-->
Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/templates.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/templates.xml,v
diff -u -r1.3 -r1.3.2.1
--- openacs-4/packages/acs-core-docs/www/xml/developers-guide/templates.xml 3 Mar 2002 01:27:08 -0000 1.3
+++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/templates.xml 15 May 2002 23:26:19 -0000 1.3.2.1
@@ -238,3 +238,9 @@
</sect2>
</sect1>
+
+<!--
+ Local Variables:
+ sgml-parent-document: ("../index.xml" "chapter" "sect1")
+ End:
+-->
Index: openacs-4/packages/acs-core-docs/www/xml/engineering-standards/constraint-naming.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/engineering-standards/constraint-naming.xml,v
diff -u -r1.2 -r1.2.2.1
--- openacs-4/packages/acs-core-docs/www/xml/engineering-standards/constraint-naming.xml 2 Feb 2002 03:47:32 -0000 1.2
+++ openacs-4/packages/acs-core-docs/www/xml/engineering-standards/constraint-naming.xml 15 May 2002 23:26:19 -0000 1.2.2.1
@@ -193,4 +193,10 @@
</sect2>
-</sect1>
\ No newline at end of file
+</sect1>
+
+<!--
+ Local Variables:
+ sgml-parent-document: ("../index.xml" "chapter" "sect1")
+ End:
+-->
Index: openacs-4/packages/acs-core-docs/www/xml/engineering-standards/design-template.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/engineering-standards/design-template.xml,v
diff -u -r1.3 -r1.3.2.1
--- openacs-4/packages/acs-core-docs/www/xml/engineering-standards/design-template.xml 3 Mar 2002 01:27:08 -0000 1.3
+++ openacs-4/packages/acs-core-docs/www/xml/engineering-standards/design-template.xml 15 May 2002 23:26:19 -0000 1.3.2.1
@@ -407,3 +407,9 @@
</sect2>
</sect1>
+
+<!--
+ Local Variables:
+ sgml-parent-document: ("../index.xml" "chapter" "sect1")
+ End:
+-->
Index: openacs-4/packages/acs-core-docs/www/xml/engineering-standards/docbook-primer.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/engineering-standards/docbook-primer.xml,v
diff -u -r1.4 -r1.4.2.1
--- openacs-4/packages/acs-core-docs/www/xml/engineering-standards/docbook-primer.xml 3 Mar 2002 01:27:08 -0000 1.4
+++ openacs-4/packages/acs-core-docs/www/xml/engineering-standards/docbook-primer.xml 15 May 2002 23:26:19 -0000 1.4.2.1
@@ -795,6 +795,6 @@
<!--
Local Variables:
- sgml-parent-document: ("../index.xml" "book" "sect1")
+ sgml-parent-document: ("../index.xml" "chapter" "sect1")
End:
-->
Index: openacs-4/packages/acs-core-docs/www/xml/engineering-standards/eng-standards-versioning.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/engineering-standards/eng-standards-versioning.xml,v
diff -u -r1.2 -r1.2.2.1
--- openacs-4/packages/acs-core-docs/www/xml/engineering-standards/eng-standards-versioning.xml 2 Feb 2002 03:47:32 -0000 1.2
+++ openacs-4/packages/acs-core-docs/www/xml/engineering-standards/eng-standards-versioning.xml 15 May 2002 23:26:19 -0000 1.2.2.1
@@ -166,5 +166,8 @@
</sect1>
-
-
+<!--
+ Local Variables:
+ sgml-parent-document: ("../index.xml" "chapter" "sect1")
+ End:
+-->
Index: openacs-4/packages/acs-core-docs/www/xml/engineering-standards/filenaming.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/engineering-standards/filenaming.xml,v
diff -u -r1.2 -r1.2.2.1
--- openacs-4/packages/acs-core-docs/www/xml/engineering-standards/filenaming.xml 2 Feb 2002 03:47:32 -0000 1.2
+++ openacs-4/packages/acs-core-docs/www/xml/engineering-standards/filenaming.xml 15 May 2002 23:26:19 -0000 1.2.2.1
@@ -451,7 +451,8 @@
</sect1>
-
-
-
-
+<!--
+ Local Variables:
+ sgml-parent-document: ("../index.xml" "chapter" "sect1")
+ End:
+-->
Index: openacs-4/packages/acs-core-docs/www/xml/engineering-standards/plsql.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/engineering-standards/plsql.xml,v
diff -u -r1.2 -r1.2.2.1
--- openacs-4/packages/acs-core-docs/www/xml/engineering-standards/plsql.xml 2 Feb 2002 03:47:32 -0000 1.2
+++ openacs-4/packages/acs-core-docs/www/xml/engineering-standards/plsql.xml 15 May 2002 23:26:19 -0000 1.2.2.1
@@ -234,6 +234,8 @@
</sect1>
-
-
-
+<!--
+ Local Variables:
+ sgml-parent-document: ("../index.xml" "chapter" "sect1")
+ End:
+-->
Index: openacs-4/packages/acs-core-docs/www/xml/engineering-standards/psgml-mode.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/engineering-standards/psgml-mode.xml,v
diff -u -r1.3 -r1.3.2.1
--- openacs-4/packages/acs-core-docs/www/xml/engineering-standards/psgml-mode.xml 2 Feb 2002 03:47:32 -0000 1.3
+++ openacs-4/packages/acs-core-docs/www/xml/engineering-standards/psgml-mode.xml 15 May 2002 23:26:19 -0000 1.3.2.1
@@ -1,9 +1,9 @@
<sect1 id="psgml-mode" xreflabel="Using PSGML mode in Emacs">
<title>Using PSGML mode in Emacs</title>
-<authorblurb><para>
+<authorblurb>
By <ulink url="mailto:lutter@arsdigita.com">David Lutterkort</ulink>
-</para></authorblurb>
+</authorblurb>
<sect2 id="psgml-mode-whatisit">
<title>What it is</title>
@@ -221,6 +221,8 @@
</sect1>
-
-
-
+<!--
+ Local Variables:
+ sgml-parent-document: ("../index.xml" "chapter" "sect1")
+ End:
+-->
Index: openacs-4/packages/acs-core-docs/www/xml/engineering-standards/requirements-template.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/engineering-standards/requirements-template.xml,v
diff -u -r1.2 -r1.2.2.1
--- openacs-4/packages/acs-core-docs/www/xml/engineering-standards/requirements-template.xml 30 Dec 2001 01:29:07 -0000 1.2
+++ openacs-4/packages/acs-core-docs/www/xml/engineering-standards/requirements-template.xml 15 May 2002 23:26:19 -0000 1.2.2.1
@@ -245,3 +245,9 @@
</sect2>
</sect1>
+
+<!--
+ Local Variables:
+ sgml-parent-document: ("../index.xml" "chapter" "sect1")
+ End:
+-->
Index: openacs-4/packages/acs-core-docs/www/xml/for-everyone/acs-faq.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/for-everyone/acs-faq.xml,v
diff -u -r1.2 -r1.2.2.1
--- openacs-4/packages/acs-core-docs/www/xml/for-everyone/acs-faq.xml 3 Mar 2002 01:27:08 -0000 1.2
+++ openacs-4/packages/acs-core-docs/www/xml/for-everyone/acs-faq.xml 15 May 2002 23:26:19 -0000 1.2.2.1
@@ -333,3 +333,8 @@
</sect1>
+<!--
+ Local Variables:
+ sgml-parent-document: ("../index.xml" "chapter" "sect1")
+ End:
+-->
Index: openacs-4/packages/acs-core-docs/www/xml/for-everyone/release-notes.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/for-everyone/release-notes.xml,v
diff -u -r1.3 -r1.3.2.1
--- openacs-4/packages/acs-core-docs/www/xml/for-everyone/release-notes.xml 3 Mar 2002 01:27:08 -0000 1.3
+++ openacs-4/packages/acs-core-docs/www/xml/for-everyone/release-notes.xml 15 May 2002 23:26:19 -0000 1.3.2.1
@@ -1,10 +1,10 @@
<sect1 id="release-notes" xreflabel="OpenACS &version; Release Notes">
<title>OpenACS &version; Release Notes</title>
- <authorblurb><para>
+ <authorblurb>
by <ulink url="mailto:dhogaza@pacifier.com">Don Baccus</ulink> and
<ulink url="mailto:vinod@kurup.com">Vinod Kurup</ulink>
- </para></authorblurb>
+ </authorblurb>
<para>
This is a beta release of OpenACS &version;. This release has been subjected
@@ -17,17 +17,19 @@
<ulink url="http://openacs.org/sdm/one-package.tcl&package_id=9">
Software Development Manager</ulink> at the <ulink
url="http://openacs.org/">OpenACS website</ulink>. The latest
- information on installating this alpha release under Oracle 8.1.6/7
+ information on installing this alpha release under Oracle 8.1.6/7
or PostgreSQL 7.1.* can be found there as well. Currently the
toolkit will not install under Oracle 9i due to Oracle having made
"delete" an illegal name for PL/SQL procedures and functions.
</para>
<para>
- You may want to begin by reading our installation documentation for <xref
- linkend="unix-install"/> or <xref
- linkend="win-install"/>. Note that the Windows
- documentation is not current for OpenACS &version;.
+ You may want to begin by reading our installation documentation for
+ <xref linkend="unix-install"/> or <xref linkend="win-install"/>. Note
+ that the Windows documentation is not current for OpenACS &version;,
+ but an alternative is to use John Sequeira's <ulink
+ url="http://www.pobox.com/~johnseq/projects/oasisvm/">Oasis VM
+ project</ulink>.
</para>
<para>
@@ -42,7 +44,7 @@
<para>
If you're using Oracle 8.1.6 or 8.1.7 Enterprise Edition you may want
to uncomment the SQL that causes InterMedia to keep online searching
- online while indexing. The feature doesn't exist in Standard Editionx
+ online while indexing. The feature doesn't exist in Standard Edition
and OpenACS &version; now defaults to being loadable in SE. Just grep for
'sync' to find the code.
</para>
@@ -236,3 +238,9 @@
<para><phrase role="cvstag">($Id$)</phrase></para>
</sect1>
+
+<!--
+ Local Variables:
+ sgml-parent-document: ("../index.xml" "chapter" "sect1")
+ End:
+-->
Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/aolserver.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/aolserver.xml,v
diff -u -r1.5 -r1.5.2.1
--- openacs-4/packages/acs-core-docs/www/xml/install-guide/aolserver.xml 7 Mar 2002 06:55:37 -0000 1.5
+++ openacs-4/packages/acs-core-docs/www/xml/install-guide/aolserver.xml 15 May 2002 23:26:19 -0000 1.5.2.1
@@ -1,6 +1,10 @@
<sect1 id="aolserver" xreflabel="Install AOLserver 3.3+ad13">
<title>Install AOLserver 3.3+ad13</title>
+ <authorblurb>
+ by <ulink url="mailto:vinod@kurup.com">Vinod Kurup</ulink>
+ </authorblurb>
+
<sect2 id="install-aolserver-download" xreflabel="Download AOLServer">
<title>Download the Distribution</title>
@@ -409,3 +413,9 @@
<para><phrase role="cvstag">($Id$)</phrase></para>
</sect1>
+
+<!--
+ Local Variables:
+ sgml-parent-document: ("../index.xml" "chapter" "sect1")
+ End:
+-->
Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/credits.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/credits.xml,v
diff -u -r1.5 -r1.5.2.1
--- openacs-4/packages/acs-core-docs/www/xml/install-guide/credits.xml 3 Mar 2002 06:29:41 -0000 1.5
+++ openacs-4/packages/acs-core-docs/www/xml/install-guide/credits.xml 15 May 2002 23:26:19 -0000 1.5.2.1
@@ -1,6 +1,10 @@
<sect1 id="credits" xreflabel="Credits">
<title>Credits</title>
+ <authorblurb>
+ by <ulink url="mailto:vinod@kurup.com">Vinod Kurup</ulink>
+ </authorblurb>
+
<para><ulink url="mailto:vinod@kurup.com">Vinod Kurup</ulink> put
together the January 2002 version of this guide from many sources of
information.</para>
@@ -47,12 +51,16 @@
<para>
<emphasis role="strong">All questions and comments</emphasis> regarding
- this guide should be sent to <ulink
- url="mailto:vinod@kurup.com">vinod@kurup.com</ulink> or on the <ulink
+ this guide should be posted on the <ulink
url="http://openacs.org/bboard">OpenACS bboards</ulink>.
</para>
<para><phrase role="cvstag">($Id$)</phrase></para>
</sect1>
+<!--
+ Local Variables:
+ sgml-parent-document: ("../index.xml" "chapter" "sect1")
+ End:
+-->
Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/next-steps.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/Attic/next-steps.xml,v
diff -u -r1.2 -r1.2.2.1
--- openacs-4/packages/acs-core-docs/www/xml/install-guide/next-steps.xml 2 Feb 2002 03:47:32 -0000 1.2
+++ openacs-4/packages/acs-core-docs/www/xml/install-guide/next-steps.xml 15 May 2002 23:26:19 -0000 1.2.2.1
@@ -1,6 +1,10 @@
<sect1 id="nextsteps" xreflabel="Next Steps">
<title>Next Steps</title>
+ <authorblurb>
+ by <ulink url="mailto:vinod@kurup.com">Vinod Kurup</ulink>
+ </authorblurb>
+
<sect2 id="install-next-backups">
<title>Backup Strategy</title>
@@ -467,6 +471,12 @@
being meant to be mounted)
</para></listitem>
+ <listitem><para>Click on "Set parameters" for the OpenFTS instance
+ and make sure that openfts_tcl_src_path properly points to your
+ local copy of the Search package source code. If you've followed
+ these directions strictly, you shouldn't need to change it.
+ </para></listitem>
+
<listitem><para>
Create another folder under "Main Site" at the url
"search". Create a "new application". Call the application
@@ -512,3 +522,9 @@
<para><phrase role="cvstag">($Id$)</phrase></para>
</sect1>
+
+<!--
+ Local Variables:
+ sgml-parent-document: ("../index.xml" "chapter" "sect1")
+ End:
+-->
Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/openacs.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/openacs.xml,v
diff -u -r1.4 -r1.4.2.1
--- openacs-4/packages/acs-core-docs/www/xml/install-guide/openacs.xml 7 Mar 2002 06:55:37 -0000 1.4
+++ openacs-4/packages/acs-core-docs/www/xml/install-guide/openacs.xml 15 May 2002 23:26:19 -0000 1.4.2.1
@@ -1,6 +1,10 @@
<sect1 id="openacs" xreflabel="Install OpenACS &version;">
<title>Install OpenACS &version;</title>
+ <authorblurb>
+ by <ulink url="mailto:vinod@kurup.com">Vinod Kurup</ulink>
+ </authorblurb>
+
<sect2 id="install-openacs-download">
<title>Downloading OpenACS</title>
@@ -13,17 +17,17 @@
<listitem><para>
Login as <computeroutput>nsadmin</computeroutput> and untar the
downloaded components into <computeroutput>/web</computeroutput>
- directory. The alpha-2 tarball is currently named
- <computeroutput>alpha2.tgz</computeroutput>. Replace
- <computeroutput>alpha2.tgz</computeroutput> in the commands below
+ directory. The OpenACS &version; tarball is currently named
+ <computeroutput>openacs-4-5.tgz</computeroutput>. Replace
+ <computeroutput>openacs-4-5.tgz</computeroutput> in the commands below
with whatever the current tarball is named.
</para>
<programlisting>
joeuser:~$ su - nsadmin
Password: ***********
nsadmin:~$ cd /web
-nsadmin:/web$ tar xzf /tmp/alpha2.tgz</programlisting>
+nsadmin:/web$ tar xzf /tmp/openacs-4-5.tgz</programlisting>
</listitem>
<listitem><para>
@@ -879,3 +883,8 @@
<para><phrase role="cvstag">($Id$)</phrase></para>
</sect1>
+<!--
+ Local Variables:
+ sgml-parent-document: ("../index.xml" "chapter" "sect1")
+ End:
+-->
Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/oracle.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/oracle.xml,v
diff -u -r1.5 -r1.5.2.1
--- openacs-4/packages/acs-core-docs/www/xml/install-guide/oracle.xml 7 Mar 2002 06:55:37 -0000 1.5
+++ openacs-4/packages/acs-core-docs/www/xml/install-guide/oracle.xml 15 May 2002 23:26:19 -0000 1.5.2.1
@@ -1,15 +1,12 @@
<sect1 id="oracle" xreflabel="Install Oracle">
<title>Install Oracle 8.1.7</title>
+ <authorblurb>
+ by <ulink url="mailto:vinod@kurup.com">Vinod Kurup</ulink>
+ </authorblurb>
+
<para>Skip this page if you're not interested in Oracle</para>
- <para><emphasis role="strong">NOTE:</emphasis><emphasis> This document
- was originally written based on Oracle, version 8.1.6. However, the
- same approach should lead to a successful installation of Oracle
- 8.1.7. If you encounter any incompatibilities, please <ulink
- url="mailto:vinod@kurup.com">let us know</ulink></emphasis>
- </para>
-
<para><emphasis role="strong">NOTE:</emphasis> We've not yet tested
OpenACS &version; under Oracle 9i</para>
@@ -58,7 +55,7 @@
</para>
<programlisting>
$ cd /directory/where/oracle/is
-$ tar -xvf oracle81701.tar</programlisting>
+$ tar xvf oracle81701.tar</programlisting>
</listitem>
</itemizedlist>
</listitem>
@@ -1854,3 +1851,9 @@
<para><phrase role="cvstag">($Id$)</phrase></para>
</sect1>
+
+<!--
+ Local Variables:
+ sgml-parent-document: ("../index.xml" "chapter" "sect1")
+ End:
+-->
Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/os.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/os.xml,v
diff -u -r1.5 -r1.5.2.1
--- openacs-4/packages/acs-core-docs/www/xml/install-guide/os.xml 3 Mar 2002 06:29:41 -0000 1.5
+++ openacs-4/packages/acs-core-docs/www/xml/install-guide/os.xml 15 May 2002 23:26:19 -0000 1.5.2.1
@@ -1,6 +1,10 @@
<sect1 id="operating-system" xreflabel="Install an Operating System">
<title>Install an Operating System</title>
+ <authorblurb>
+ by <ulink url="mailto:vinod@kurup.com">Vinod Kurup</ulink>
+ </authorblurb>
+
<para>
We won't provide detailed instructions to install an operating system
since there are so many valid choices available and each OS has their
@@ -38,11 +42,16 @@
<xref linkend="win2k-installation" />
</para>
<para>
- This was written for ACS and has <emphasis>not</emphasis> yet been updated for
- OpenACS. (Note: AOLServer is no longer supporting Windows
- - it may be possible to run AOLServer under
- <ulink url="http://www.cygwin.com">Cygwin</ulink>, but I
- haven't seen any success reports yet).
+ This was written for ACS and has <emphasis>not</emphasis> yet
+ been updated for OpenACS. (Note: AOLServer is no longer
+ supporting Windows - it may be possible to run AOLServer under
+ <ulink url="http://www.cygwin.com">Cygwin</ulink>, but I haven't
+ seen any success reports yet). Another alternative is to use John
+ Sequeira's <ulink
+ url="http://www.pobox.com/~johnseq/projects/oasisvm/">Oasis
+ VM</ulink>, which is basically a fully working OpenACS &version;
+ system that you load into <ulink
+ url="http://vmware.com">VMware</ulink>.
</para>
</listitem>
@@ -234,3 +243,8 @@
<para><phrase role="cvstag">($Id$)</phrase></para>
</sect1>
+<!--
+ Local Variables:
+ sgml-parent-document: ("../index.xml" "chapter" "sect1")
+ End:
+-->
Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/overview.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/overview.xml,v
diff -u -r1.4 -r1.4.2.1
--- openacs-4/packages/acs-core-docs/www/xml/install-guide/overview.xml 3 Mar 2002 01:27:08 -0000 1.4
+++ openacs-4/packages/acs-core-docs/www/xml/install-guide/overview.xml 15 May 2002 23:26:19 -0000 1.4.2.1
@@ -1,6 +1,10 @@
<sect1 id="install-overview" xreflabel="Installation Overview">
<title>Overview</title>
+ <authorblurb>
+ by <ulink url="mailto:vinod@kurup.com">Vinod Kurup</ulink>
+ </authorblurb>
+
<sect2 id="install-description" xreflabel="What is OpenACS?">
<title>What is OpenACS?</title>
<para>
@@ -147,16 +151,16 @@
<para>
We'll do our best to assure that following our instructions will get
you to the promised land. If something goes wrong, don't
- panic. There's plenty of ways to get help. Here are some tips:
+ panic. There are plenty of ways to get help. Here are some tips:
</para>
<itemizedlist>
<listitem>
<para>
- Make sure that you keep track of what commands you are running
- and their output. I like to do my installations in a shell inside
- of emacs (M-x shell) so that I can save the output if needed. An
- alternative would be to use the
+ Keep track of the commands you are run and record their output. I
+ like to do my installations in a shell inside of emacs
+ (<computeroutput>M-x shell</computeroutput>) so that I can save
+ the output if needed. An alternative would be to use the
<computeroutput>script</computeroutput> command.
</para>
</listitem>
@@ -360,3 +364,8 @@
<para><phrase role="cvstag">($Id$)</phrase></para>
</sect1>
+<!--
+ Local Variables:
+ sgml-parent-document: ("../index.xml" "chapter" "sect1")
+ End:
+-->
Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/postgres.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/postgres.xml,v
diff -u -r1.4 -r1.4.2.1
--- openacs-4/packages/acs-core-docs/www/xml/install-guide/postgres.xml 7 Mar 2002 06:55:37 -0000 1.4
+++ openacs-4/packages/acs-core-docs/www/xml/install-guide/postgres.xml 15 May 2002 23:26:19 -0000 1.4.2.1
@@ -1,6 +1,10 @@
<sect1 id="postgres" xreflabel="Installing PostgreSQL">
<title>Install PostgreSQL 7.1.3</title>
+ <authorblurb>
+ by <ulink url="mailto:vinod@kurup.com">Vinod Kurup</ulink>
+ </authorblurb>
+
<para>
Skip this page if you're not interested in PostgreSQL.
</para>
@@ -289,7 +293,7 @@
root:~# chkconfig --add postgresql
root:~# chkconfig --list postgresql
; You should see:
-postgresql 0:off 1:off 2:off 3:on 4:on 5:on 6:off
+postgresql 0:off 1:off 2:on 3:on 4:on 5:on 6:off
root:~# /etc/rc.d/init.d/postgresql start
Starting PostgreSQL: ok
root:~# exit
@@ -385,3 +389,8 @@
<para><phrase role="cvstag">($Id$)</phrase></para>
</sect1>
+<!--
+ Local Variables:
+ sgml-parent-document: ("../index.xml" "chapter" "sect1")
+ End:
+-->
Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/win2kinstall.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/win2kinstall.xml,v
diff -u -r1.4 -r1.4.2.1
--- openacs-4/packages/acs-core-docs/www/xml/install-guide/win2kinstall.xml 3 Mar 2002 06:33:09 -0000 1.4
+++ openacs-4/packages/acs-core-docs/www/xml/install-guide/win2kinstall.xml 15 May 2002 23:26:19 -0000 1.4.2.1
@@ -5,7 +5,16 @@
<para>By <ulink url="mailto:mburke@arsdigita.com">Matthew Burke</ulink> and <ulink url="mailto:curtisg@arsdigita.com">Curtis Galloway</ulink></para>
</authorblurb>
+ <para><emphasis role="strong">NOTE:</emphasis> These instructions were
+ valid for ACS v4, but have not been tested with OpenACS. Currently
+ (5/2002), the best option to get OpenACS &version; running on Windows
+ is to use <ulink url="http://vmware.com">VMware</ulink> and John
+ Sequeira's <ulink
+ url="http://www.pobox.com/~johnseq/projects/oasisvm/">Oasis VM
+ distribution</ulink>
+ </para>
+
<itemizedlist>
<listitem><para>Source: <ulink url="http://software.arsdigita.com/dist">http://software.arsdigita.com/dist</ulink></para></listitem>
@@ -485,3 +494,8 @@
</sect2>
</sect1>
+<!--
+ Local Variables:
+ sgml-parent-document: ("../index.xml" "chapter" "sect1")
+ End:
+-->
Index: openacs-4/packages/acs-core-docs/www/xml/kernel/apm-design.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/kernel/apm-design.xml,v
diff -u -r1.3 -r1.3.2.1
--- openacs-4/packages/acs-core-docs/www/xml/kernel/apm-design.xml 3 Mar 2002 01:27:08 -0000 1.3
+++ openacs-4/packages/acs-core-docs/www/xml/kernel/apm-design.xml 15 May 2002 23:26:19 -0000 1.3.2.1
@@ -2,9 +2,9 @@
<title>OpenACS &version; Package Manager Design</title>
-<authorblurb><para>
+<authorblurb>
by <ulink url="mailto:bquinn@arsdigita.com">Bryan Quinn</ulink>
-</para></authorblurb>
+</authorblurb>
<sect2 id="apm-design-essentials">
@@ -1083,3 +1083,8 @@
</sect1>
+<!--
+ Local Variables:
+ sgml-parent-document: ("../index.xml" "chapter" "sect1")
+ End:
+-->
Index: openacs-4/packages/acs-core-docs/www/xml/kernel/apm-requirements.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/kernel/apm-requirements.xml,v
diff -u -r1.4 -r1.4.2.1
--- openacs-4/packages/acs-core-docs/www/xml/kernel/apm-requirements.xml 3 Mar 2002 01:27:08 -0000 1.4
+++ openacs-4/packages/acs-core-docs/www/xml/kernel/apm-requirements.xml 15 May 2002 23:26:19 -0000 1.4.2.1
@@ -1,9 +1,9 @@
<sect1 id="apm-requirements" xreflabel="OpenACS &version; Package Manager Requirements">
<title>OpenACS &version; Package Manager Requirements</title>
-<authorblurb><para>
+<authorblurb>
by <ulink url="mailto:bquinn@arsdigita.com">Bryan Quinn</ulink> and <ulink url="mailto:tnight@arsdigita.com">Todd Nightingale</ulink>
-</para></authorblurb>
+</authorblurb>
<sect2 id="apm-requirements-intro">
<title>Introduction</title>
@@ -1014,3 +1014,8 @@
</sect1>
+<!--
+ Local Variables:
+ sgml-parent-document: ("../index.xml" "chapter" "sect1")
+ End:
+-->
Index: openacs-4/packages/acs-core-docs/www/xml/kernel/bootstrap-acs.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/kernel/bootstrap-acs.xml,v
diff -u -r1.2 -r1.2.2.1
--- openacs-4/packages/acs-core-docs/www/xml/kernel/bootstrap-acs.xml 2 Feb 2002 03:47:32 -0000 1.2
+++ openacs-4/packages/acs-core-docs/www/xml/kernel/bootstrap-acs.xml 15 May 2002 23:26:19 -0000 1.2.2.1
@@ -1,9 +1,9 @@
<sect1 id="bootstrap-acs" xreflabel="Bootstrapping OpenACS">
<title>Bootstrapping OpenACS</title>
-<authorblurb><para>
+<authorblurb>
by <ulink url="mailto:jsalz@mit.edu">Jon Salz</ulink>
-</para></authorblurb>
+</authorblurb>
<itemizedlist>
<listitem><para>Tcl code: /tcl/0-acs-init.tcl and /packages/acs-kernel/bootstrap.tcl</para></listitem>
@@ -150,3 +150,8 @@
</sect2>
</sect1>
+<!--
+ Local Variables:
+ sgml-parent-document: ("../index.xml" "chapter" "sect1")
+ End:
+-->
Index: openacs-4/packages/acs-core-docs/www/xml/kernel/db-api.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/kernel/db-api.xml,v
diff -u -r1.4 -r1.4.2.1
--- openacs-4/packages/acs-core-docs/www/xml/kernel/db-api.xml 3 Mar 2002 01:27:08 -0000 1.4
+++ openacs-4/packages/acs-core-docs/www/xml/kernel/db-api.xml 15 May 2002 23:26:19 -0000 1.4.2.1
@@ -1,9 +1,9 @@
<sect1 id="db-api-detailed" xreflabel="Database Access API">
<title>Database Access API</title>
-<authorblurb><para>
+<authorblurb>
by <ulink url="mailto:jsalz@mit.edu">Jon Salz</ulink>
-</para></authorblurb>
+</authorblurb>
<itemizedlist>
<listitem><para>Tcl procedures: /packages/acs-kernel/10-database-procs.tcl</para></listitem>
@@ -1114,3 +1114,8 @@
</sect2>
</sect1>
+<!--
+ Local Variables:
+ sgml-parent-document: ("../index.xml" "chapter" "sect1")
+ End:
+-->
Index: openacs-4/packages/acs-core-docs/www/xml/kernel/groups-design.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/kernel/groups-design.xml,v
diff -u -r1.2 -r1.2.2.1
--- openacs-4/packages/acs-core-docs/www/xml/kernel/groups-design.xml 2 Feb 2002 03:47:32 -0000 1.2
+++ openacs-4/packages/acs-core-docs/www/xml/kernel/groups-design.xml 15 May 2002 23:26:19 -0000 1.2.2.1
@@ -1,9 +1,9 @@
<sect1 id="groups-design" xreflabel="OpenACS 4 Groups Design">
<title>OpenACS 4 Groups Design</title>
-<authorblurb><para>
+<authorblurb>
by <ulink url="http://planitia.org">Rafael H. Schloming</ulink> and <ulink url="mailto:mthomas@arsdigita.com">Mark Thomas</ulink>
-</para></authorblurb>
+</authorblurb>
<sect2 id="groups-design-essentials">
@@ -734,3 +734,8 @@
</sect1>
+<!--
+ Local Variables:
+ sgml-parent-document: ("../index.xml" "chapter" "sect1")
+ End:
+-->
Index: openacs-4/packages/acs-core-docs/www/xml/kernel/groups-requirements.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/kernel/groups-requirements.xml,v
diff -u -r1.2 -r1.2.2.1
--- openacs-4/packages/acs-core-docs/www/xml/kernel/groups-requirements.xml 2 Feb 2002 03:47:32 -0000 1.2
+++ openacs-4/packages/acs-core-docs/www/xml/kernel/groups-requirements.xml 15 May 2002 23:26:19 -0000 1.2.2.1
@@ -1,9 +1,9 @@
<sect1 id="groups-requirements" xreflabel="OpenACS 4 Groups Requirements">
<title>OpenACS 4 Groups Requirements</title>
-<authorblurb><para>
+<authorblurb>
by <ulink url="http://planitia.org">Rafael H. Schloming</ulink>, <ulink url="mailto:mthomas@arsdigita.com">Mark Thomas</ulink>
-</para></authorblurb>
+</authorblurb>
<sect2 id="groups-requirements-intro">
@@ -702,3 +702,8 @@
</sect1>
+<!--
+ Local Variables:
+ sgml-parent-document: ("../index.xml" "chapter" "sect1")
+ End:
+-->
Index: openacs-4/packages/acs-core-docs/www/xml/kernel/object-system-design.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/kernel/object-system-design.xml,v
diff -u -r1.3 -r1.3.2.1
--- openacs-4/packages/acs-core-docs/www/xml/kernel/object-system-design.xml 2 Feb 2002 03:47:32 -0000 1.3
+++ openacs-4/packages/acs-core-docs/www/xml/kernel/object-system-design.xml 15 May 2002 23:26:19 -0000 1.3.2.1
@@ -1,12 +1,12 @@
<sect1 id="object-system-design" xreflabel="OpenACS 4 Object Model Design">
<title>OpenACS 4 Object Model Design</title>
-<authorblurb><para>
+<authorblurb>
by <ulink url="mailto:psu@arsdigita.com">Pete Su</ulink>,
<ulink url="mailto:mcyoon@arsdigita.com">Michael Yoon</ulink>,
<ulink url="mailto:richardl@arsdigita.com">Richard Li</ulink>
and <ulink url="mailto:rhs@arsdigita.com">Rafael Schloming</ulink>
-</para></authorblurb>
+</authorblurb>
<sect2 id="object-system-design-essentials">
<title>Essentials</title>
@@ -1516,3 +1516,8 @@
</sect1>
+<!--
+ Local Variables:
+ sgml-parent-document: ("../index.xml" "chapter" "sect1")
+ End:
+-->
Index: openacs-4/packages/acs-core-docs/www/xml/kernel/object-system-req.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/kernel/object-system-req.xml,v
diff -u -r1.3 -r1.3.2.1
--- openacs-4/packages/acs-core-docs/www/xml/kernel/object-system-req.xml 2 Feb 2002 03:47:32 -0000 1.3
+++ openacs-4/packages/acs-core-docs/www/xml/kernel/object-system-req.xml 15 May 2002 23:26:19 -0000 1.3.2.1
@@ -1,9 +1,9 @@
<sect1 id="object-system-requirements" xreflabel="OpenACS 4 Object Model Requirements">
<title>OpenACS 4 Object Model Requirements</title>
-<authorblurb><para>
+<authorblurb>
By <ulink url="mailto:psu@arsdigita.com">Pete Su</ulink>
-</para></authorblurb>
+</authorblurb>
@@ -808,3 +808,8 @@
</sect1>
+<!--
+ Local Variables:
+ sgml-parent-document: ("../index.xml" "chapter" "sect1")
+ End:
+-->
Index: openacs-4/packages/acs-core-docs/www/xml/kernel/permissions-design.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/kernel/permissions-design.xml,v
diff -u -r1.2 -r1.2.2.1
--- openacs-4/packages/acs-core-docs/www/xml/kernel/permissions-design.xml 2 Feb 2002 03:47:32 -0000 1.2
+++ openacs-4/packages/acs-core-docs/www/xml/kernel/permissions-design.xml 15 May 2002 23:26:19 -0000 1.2.2.1
@@ -1,9 +1,9 @@
<sect1 id="permissions-design" xreflabel="OpenACS 4 Permissions Design">
<title>OpenACS 4 Permissions Design</title>
-<authorblurb><para>
+<authorblurb>
by <ulink url="mailto:jmp@arsdigita.com">John Prevost</ulink> and <ulink url="http://planitia.org">Rafael H. Schloming</ulink>
-</para></authorblurb>
+</authorblurb>
<sect2 id="permissions-design-essentials">
<title>Essentials</title>
@@ -497,3 +497,8 @@
</sect1>
+<!--
+ Local Variables:
+ sgml-parent-document: ("../index.xml" "chapter" "sect1")
+ End:
+-->
Index: openacs-4/packages/acs-core-docs/www/xml/kernel/permissions-requirements.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/kernel/permissions-requirements.xml,v
diff -u -r1.2 -r1.2.2.1
--- openacs-4/packages/acs-core-docs/www/xml/kernel/permissions-requirements.xml 2 Feb 2002 03:47:32 -0000 1.2
+++ openacs-4/packages/acs-core-docs/www/xml/kernel/permissions-requirements.xml 15 May 2002 23:26:19 -0000 1.2.2.1
@@ -1,9 +1,9 @@
<sect1 id="permissions-requirements" xreflabel="OpenACS 4 Permissions Requirements">
<title>OpenACS 4 Permissions Requirements</title>
-<authorblurb><para>
+<authorblurb>
by <ulink url="mailto:jmp@arsdigita.com">John McClary Prevost</ulink>
-</para></authorblurb>
+</authorblurb>
<sect2 id="permissions-requirements-intro">
<title>Introduction</title>
@@ -285,3 +285,8 @@
</sect1>
+<!--
+ Local Variables:
+ sgml-parent-document: ("../index.xml" "chapter" "sect1")
+ End:
+-->
Index: openacs-4/packages/acs-core-docs/www/xml/kernel/rp-design.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/kernel/rp-design.xml,v
diff -u -r1.3 -r1.3.2.1
--- openacs-4/packages/acs-core-docs/www/xml/kernel/rp-design.xml 2 Feb 2002 03:47:32 -0000 1.3
+++ openacs-4/packages/acs-core-docs/www/xml/kernel/rp-design.xml 15 May 2002 23:26:19 -0000 1.3.2.1
@@ -2,9 +2,9 @@
<title>OpenACS 4 Request Processor Design</title>
-<authorblurb><para>
+<authorblurb>
by <ulink url="http://planitia.org">Rafael H. Schloming</ulink>
-</para></authorblurb>
+</authorblurb>
<sect2 id="rp-design-essentials">
@@ -375,14 +375,8 @@
</sect1>
-
-
-
-
-
-
-
-
-
-
-
+<!--
+ Local Variables:
+ sgml-parent-document: ("../index.xml" "chapter" "sect1")
+ End:
+-->
Index: openacs-4/packages/acs-core-docs/www/xml/kernel/rp-requirements.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/kernel/rp-requirements.xml,v
diff -u -r1.2 -r1.2.2.1
--- openacs-4/packages/acs-core-docs/www/xml/kernel/rp-requirements.xml 2 Feb 2002 03:47:32 -0000 1.2
+++ openacs-4/packages/acs-core-docs/www/xml/kernel/rp-requirements.xml 15 May 2002 23:26:19 -0000 1.2.2.1
@@ -2,9 +2,9 @@
<title>OpenACS 4 Request Processor Requirements</title>
-<authorblurb><para>
+<authorblurb>
by <ulink url="http://planitia.org">Rafael H. Schloming</ulink>
-</para></authorblurb>
+</authorblurb>
<sect2 id="rp-requirements-intro">
@@ -128,3 +128,8 @@
</sect1>
+<!--
+ Local Variables:
+ sgml-parent-document: ("../index.xml" "chapter" "sect1")
+ End:
+-->
Index: openacs-4/packages/acs-core-docs/www/xml/kernel/security-design.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/kernel/security-design.xml,v
diff -u -r1.3 -r1.3.2.1
--- openacs-4/packages/acs-core-docs/www/xml/kernel/security-design.xml 2 Feb 2002 03:47:32 -0000 1.3
+++ openacs-4/packages/acs-core-docs/www/xml/kernel/security-design.xml 15 May 2002 23:26:19 -0000 1.3.2.1
@@ -1,11 +1,11 @@
<sect1 id="security-design" xreflabel="OpenACS 4 Security Design">
<title>OpenACS 4 Security Design</title>
-<authorblurb><para>
+<authorblurb>
by <ulink url="mailto:richardl@arsdigita.com">Richard Li</ulink>, <ulink url="mailto:ashah@arsdigita.com">Archit Shah</ulink>
-</para></authorblurb>
+</authorblurb>
<sect2 id="security-design-essentials">
@@ -879,3 +879,8 @@
</sect1>
+<!--
+ Local Variables:
+ sgml-parent-document: ("../index.xml" "chapter" "sect1")
+ End:
+-->
Index: openacs-4/packages/acs-core-docs/www/xml/kernel/security-notes.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/kernel/security-notes.xml,v
diff -u -r1.2 -r1.2.2.1
--- openacs-4/packages/acs-core-docs/www/xml/kernel/security-notes.xml 2 Feb 2002 03:47:32 -0000 1.2
+++ openacs-4/packages/acs-core-docs/www/xml/kernel/security-notes.xml 15 May 2002 23:26:19 -0000 1.2.2.1
@@ -2,9 +2,9 @@
<title>OpenACS 4 Security Notes</title>
-<authorblurb><para>
+<authorblurb>
by <ulink url="mailto:richardl@arsdigita.com">Richard Li</ulink>
-</para></authorblurb>
+</authorblurb>
<para>
The security system was designed for security. Thus, decisions requiring
@@ -90,3 +90,8 @@
</sect2>
</sect1>
+<!--
+ Local Variables:
+ sgml-parent-document: ("../index.xml" "chapter" "sect1")
+ End:
+-->
Index: openacs-4/packages/acs-core-docs/www/xml/kernel/security-requirements.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/kernel/security-requirements.xml,v
diff -u -r1.2 -r1.2.2.1
--- openacs-4/packages/acs-core-docs/www/xml/kernel/security-requirements.xml 2 Feb 2002 03:47:32 -0000 1.2
+++ openacs-4/packages/acs-core-docs/www/xml/kernel/security-requirements.xml 15 May 2002 23:26:19 -0000 1.2.2.1
@@ -1,9 +1,9 @@
<sect1 id="security-requirements" xreflabel="OpenACS 4 Security Requirements">
<title>OpenACS 4 Security Requirements</title>
-<authorblurb><para>
+<authorblurb>
by <ulink url="mailto:richardl@arsdigita.com">Richard Li</ulink>
-</para></authorblurb>
+</authorblurb>
<sect2 id="security-requirements-intro">
@@ -113,3 +113,8 @@
</sect1>
+<!--
+ Local Variables:
+ sgml-parent-document: ("../index.xml" "chapter" "sect1")
+ End:
+-->
Index: openacs-4/packages/acs-core-docs/www/xml/kernel/subsites-design.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/kernel/subsites-design.xml,v
diff -u -r1.2 -r1.2.2.1
--- openacs-4/packages/acs-core-docs/www/xml/kernel/subsites-design.xml 2 Feb 2002 03:47:32 -0000 1.2
+++ openacs-4/packages/acs-core-docs/www/xml/kernel/subsites-design.xml 15 May 2002 23:26:19 -0000 1.2.2.1
@@ -1,9 +1,9 @@
<sect1 id="subsites-design" xreflabel="OpenACS 4 Subsites Design Document">
<title>OpenACS 4 Subsites Design Document</title>
-<authorblurb><para>
+<authorblurb>
by <ulink url="http://planitia.org">Rafael H. Schloming</ulink>
-</para></authorblurb>
+</authorblurb>
<para><emphasis>*Note* This document has not gone through the any of the
required QA process yet. It is being tagged as stable due to high
@@ -368,3 +368,8 @@
</sect1>
+<!--
+ Local Variables:
+ sgml-parent-document: ("../index.xml" "chapter" "sect1")
+ End:
+-->
Index: openacs-4/packages/acs-core-docs/www/xml/kernel/subsites-requirements.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/kernel/subsites-requirements.xml,v
diff -u -r1.2 -r1.2.2.1
--- openacs-4/packages/acs-core-docs/www/xml/kernel/subsites-requirements.xml 2 Feb 2002 03:47:32 -0000 1.2
+++ openacs-4/packages/acs-core-docs/www/xml/kernel/subsites-requirements.xml 15 May 2002 23:26:19 -0000 1.2.2.1
@@ -1,9 +1,9 @@
<sect1 id="subsites-requirements" xreflabel="OpenACS 4 Subsites Requirements">
<title>OpenACS 4 Subsites Requirements</title>
-<authorblurb><para>
+<authorblurb>
by <ulink url="http://planitia.org">Rafael H. Schloming</ulink> and <ulink url="mailto:dennis@arsdigita.com">Dennis Gregorovic</ulink>
-</para></authorblurb>
+</authorblurb>
<sect2 id="subsites-requirements-intro">
@@ -226,3 +226,8 @@
</sect1>
+<!--
+ Local Variables:
+ sgml-parent-document: ("../index.xml" "chapter" "sect1")
+ End:
+-->
Index: openacs-4/packages/acs-core-docs/www/xml/kernel/tcl-doc.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/kernel/tcl-doc.xml,v
diff -u -r1.2 -r1.2.2.1
--- openacs-4/packages/acs-core-docs/www/xml/kernel/tcl-doc.xml 2 Feb 2002 03:47:32 -0000 1.2
+++ openacs-4/packages/acs-core-docs/www/xml/kernel/tcl-doc.xml 15 May 2002 23:26:19 -0000 1.2.2.1
@@ -2,9 +2,9 @@
<title>Documenting Tcl Files: Page Contracts and Libraries</title>
-<authorblurb><para>
+<authorblurb>
by <ulink url="mailto:jsalz@mit.edu">Jon Salz</ulink> on 3 July 2000
-</para></authorblurb>
+</authorblurb>
<itemizedlist>
<listitem><para>Tcl procedures: /packages/acs-kernel/tcl-documentation-procs.tcl</para></listitem>
@@ -345,3 +345,8 @@
</sect2>
</sect1>
+<!--
+ Local Variables:
+ sgml-parent-document: ("../index.xml" "chapter" "sect1")
+ End:
+-->