- For OpenACS Admins

Prev	Home	Next
Install PostgreSQL 7.1.3	Up	Install OpenACS 4.5

- - +

-OpenACS 4.5 Package Manager Design

-by Bryan Quinn -

-Essentials

OpenACS Administrator directory
OpenACS 4.5 Package Manager Requirements
Packages
ER diagram
-
Tcl API
-
- -apm-procs.tcl
- - -apm-install-procs.tcl (Supports installation of packages)
- - -20-apm-load-procs.tcl (Bootstraps APM for server startup)
- - -apm-admin-procs.tcl (Supports APM UI)
-
-
PL/SQL file
-
- apm-create.sql
-

-Introduction

-In general terms, a package is a unit of software that +OpenACS 4.5 Package Manager Design

Prev	Chapter 7. Kernel Documentation	Next

OpenACS 4.5 Package Manager Design

+by Bryan Quinn
+ OpenACS docs are written by the named authors, but may be edited + by OpenACS documentation staff. +

Essentials

OpenACS Administrator directory
OpenACS 4.5 Package Manager Requirements
Packages
ER diagram
Tcl API
- +apm-procs.tcl
- +apm-install-procs.tcl (Supports installation of packages)
- +20-apm-load-procs.tcl (Bootstraps APM for server startup)
- +apm-admin-procs.tcl (Supports APM UI)
PL/SQL file
- apm-create.sql

Introduction

+In general terms, a package 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: -

-OpenACS Applications: a "program or group of programs +
- OpenACS Applications: a "program or group of programs designed for end users" (the Webopedia -definition); also known as modules, for historical reasons. +definition); also known as modules, for historical reasons. Examples of applications include Bboard and News. -
- -OpenACS Services: the aforementioned building blocks. +
- OpenACS Services: the aforementioned building blocks. Examples of services include the OpenACS Content Repository, the OpenACS Templating System, and the OpenACS Kernel, which includes -APM.
-
An installation of the OpenACS includes the OpenACS Kernel, some services that +APM.

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 subsites. A subsite can contain multiple application and service instances that provide the end-user with capabilities -and content customized to the particular subsite.

This architecture supports the growth of collaborative commerce. For +and content customized to the particular subsite.

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.

The APM provides an architecture for packaging software, making instances +become part of Jane's View Camera subsite.

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.

-Historical Considerations

+for each instance, and managing the creation and release of new packages.

Historical Considerations

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: -

the data model
the Tcl procedures
the user-accessible pages
the administration pages

Experience has shown us that this lack of explicit boundaries causes a -number of maintainability problems for pre-3.3 installations:

-
Package interfaces were not guaranteed to be stable in any formal way, so +
- the data model
- the Tcl procedures
- the user-accessible pages
- the administration pages
Experience has shown us that this lack of explicit boundaries causes a +number of maintainability problems for pre-3.3 installations:
1. 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: -
  -
  - renaming a file or directory that appears in a URL
  - changing what form variables are expected as input by a page
  - changing a procedural abstraction, e.g., a PL/SQL or Java stored -procedure or a Tcl procedure
  - changing a functional abstraction, e.g., a database view or a PL/SQL or -Java stored function
  - changing the data model
  -
  This last point is especially important. In most cases, changing the data -model should not affect dependent packages. Rather, the package +
  - renaming a file or directory that appears in a URL
  - changing what form variables are expected as input by a page
  - changing a procedural abstraction, e.g., a PL/SQL or Java stored +procedure or a Tcl procedure
  - changing a functional abstraction, e.g., a database view or a PL/SQL or +Java stored function
  - changing the data model
  This last point is especially important. In most cases, changing the data +model should not 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.
  -
2. A typical ACS-backed site only uses a few of the modules included in the +break.
3. 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. -
4. Releasing a new version of the ACS was complicated, owing again to the +
5. 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. -
6. There was no standard way for developers outside of ArsDigita to extend +
7. 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.
-
Consistent use of the APM format and tools will go a long way toward +ACS was an error-prone and time-consuming process.

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.

For a simple illustration of the difference between ACS without APM +packages for other ACS users to download and install.

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):

APM itself is part of a package, the OpenACS Kernel, an OpenACS -service that is the only mandatory component of an OpenACS installation.

-Competitive Analysis

The OpenACS is a platform for web-based application software, and any software +3.2 (say, bboard and e-commerce):

[D]

APM itself is part of a package, the OpenACS Kernel, an OpenACS +service that is the only mandatory component of an OpenACS installation.

Competitive Analysis

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:

-Debian GNU/Linux and the Debian -Packaging manual -
-FreeBSD has the Ports -collection -
-Red Hat Linux has the Red Hat Package Manager (RPM) -

Borrowing from all of the above, OpenACS 3.3 introduces its own package -management system, the OpenACS Package Manager (APM), which consists of:

-
-a standard format for APM packages (also called -"OpenACS packages"), including:
-
- version numbering, independent of any other package and the OpenACS as a -whole
- specification of the package interface
- specification of dependencies on other packages (if any)
- attribution (who wrote it) and ownership (who maintains it)
-
-
-web-based tools for package management:
-
- obtaining packages from a remote distribution point
- -
  installing packages, if and only if:
  -
  1. all prerequisite packages are installed
  2. no conflicts will be created by the installation
  -
- configuring packages (obsoleting the monolithic OpenACS configuration -file)
- upgrading packages, without clobbering local modifications
- uninstalling unwanted packages
-
-a registry of installed packages, database-backed and +including:
- Debian GNU/Linux and the Debian +Packaging manual
- FreeBSD has the Ports +collection
- Red Hat Linux has the Red Hat Package Manager (RPM)
Borrowing from all of the above, OpenACS 3.3 introduces its own package +management system, the OpenACS Package Manager (APM), which consists of:
- a standard format for APM packages (also called +"OpenACS packages"), including:
  - version numbering, independent of any other package and the OpenACS as a +whole
  - specification of the package interface
  - specification of dependencies on other packages (if any)
  - attribution (who wrote it) and ownership (who maintains it)
- web-based tools for package management:
  - obtaining packages from a remote distribution point
  - installing packages, if and only if:
    all prerequisite packages are installed
    no conflicts will be created by the installation
  - configuring packages (obsoleting the monolithic OpenACS configuration +file)
  - upgrading packages, without clobbering local modifications
  - uninstalling unwanted packages
- a registry of installed packages, database-backed and integrated with filesystem-based version control -
- -
  -web-based tools for package development:
  -
  - creating new packages locally
  - releasing new versions of locally-created packages
  -
-

-Design Tradeoffs

web-based tools for package development:

creating new packages locally
releasing new versions of locally-created packages

Design Tradeoffs

The design chosen for APM was meant to satisfy the following constraints: -

The process of authoring a package must be as simple as possible.
Strict conventions must be established that provide a set of canonical +
- The process of authoring a package must be as simple as possible.
- Strict conventions must be established that provide a set of canonical locations and names for files and patterns, for OpenACS application -development.
- The processes of installing, upgrading, and using packages must be -straightforward and accessible through a web-based UI.
- Package instances must be able to have subsite-specific content available -at an easily configurable URL.
-
All of these requirements were met, but at the cost of development +development.
The processes of installing, upgrading, and using packages must be +straightforward and accessible through a web-based UI.
Package instances must be able to have subsite-specific content available +at an easily configurable URL.

All of these requirements were met, but at the cost of development simplicity. As Packages 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.

For example, to make a new application available to the system, a -developer must:

Create the necessary files to support the data model, Tcl API, and UI -pages.
Put the files in the correct locations for APM to be aware of them.
Use APM to create a new package and enable it.
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.

While this is complex, especially to a new OpenACS developer, the +capabilities.

For example, to make a new application available to the system, a +developer must:

Create the necessary files to support the data model, Tcl API, and UI +pages.
Put the files in the correct locations for APM to be aware of them.
Use APM to create a new package and enable it.
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.

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.

-API

The APM is composed of systems for accomplishing a set of package-related +installations without doing a monolithic upgrade or reinstall.

API

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:

Authoring a Package
Maintaining Multiple Versions of a Package
Creating Instances of the Package
Specifying Configuration Parameters for each Instance

Authoring a Package

Full instructions on how to prepare an OpenACS package are available in Packages. The API here can be invoked manually by a package's data model +model, and a UI:

Authoring a Package
Maintaining Multiple Versions of a Package
Creating Instances of the Package
Specifying Configuration Parameters for each Instance

Authoring a Package

Full instructions on how to prepare an OpenACS package are available in Packages. 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 APM PL/SQL -package.

+package.
 
 -- Informs the APM that this application is available for use.
 procedure register_application (
@@ -326,15 +142,12 @@
                                 default null
 );
 
-
-The procedure above registers an OpenACS application in the APM. It creates a
+

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 -apm.register_service.

To remove an application from the system, there are the calls +apm.register_service.

To remove an application from the system, there are the calls apm.unregister_application and -apm.unregister_service.

+apm.unregister_service.
 
 -- Remove the application from the system.  
 procedure unregister_application (
@@ -343,29 +156,22 @@
     cascade_p       in char default 'f'  
 );
 
-
-Use the cascade_p only if you want to completely remove the
-package from the OpenACS.
-In order to determine if a particular package exists in the system, use
+

Use the cascade_p only if you want to completely remove the +package from the OpenACS.

In order to determine if a particular package exists in the system, use the register_p predicate. It returns 1 if the specified -package_key exists in the system, 0 otherwise.

+package_key exists in the system, 0 otherwise.
 
 function register_p (
     package_key     in apm_package_types.package_key%TYPE
 ) return integer;
 
-
-Maintaining Multiple Versions of a Package
-While the package authoring API provides a means for registering a
+

Maintaining Multiple Versions of a Package

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 -apm_package_version PL/SQL package.

To create a new package version, use the -apm_package_version.new constructor function.

+apm_package_version PL/SQL package.
To create a new package version, use the
+apm_package_version.new constructor function.
 
 function new (
     version_id          in apm_package_versions.version_id%TYPE
@@ -386,49 +192,26 @@
                         default 'f'
 ) return apm_package_versions.version_id%TYPE;
 
-
-In order to use this function, an existing package_key must
+

In order to use this function, an existing package_key must be specified. The version_name parameter must follow a strict -convention:

A major version number
at least one minor version number. Although any number of minor version +convention:
1. A major version number
2. 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.
3. -
  One of the following:
  -
  - The letter d, indicating a development-only version
  - The letter a, indicating an alpha release
  - The letter b, indicating a beta release
  - No letter at all, indicating a final production release
  -
-
In addition, the letters d, a, and +convention of software developers.
One of the following:
- The letter d, indicating a development-only version
- The letter a, indicating an alpha release
- The letter b, indicating a beta release
- No letter at all, indicating a final production release

In addition, the letters d, a, and b may be followed by another integer, indicating a version -within the release.

For those who like regular expressions:

+within the release.
For those who like regular expressions:
 
 version_number := ^[0-9]+((\.[0-9]+)+((d|a|b|)[0-9]?)?)$
 
-
-So the following is a valid progression for version numbers:
-0.9d, 0.9d1, 0.9a1, 0.9b1, 0.9b2, 0.9, 1.0, 1.0.1, 1.1b1,
-1.1
-To delete a given version of a package, use the
-apm_package_version.delete procedure:
-+
So the following is a valid progression for version numbers:
0.9d, 0.9d1, 0.9a1, 0.9b1, 0.9b2, 0.9, 1.0, 1.0.1, 1.1b1,
+1.1
To delete a given version of a package, use the
+apm_package_version.delete procedure:
 
 procedure delete (
     package_id      in apm_packages.package_id%TYPE  
 );
 
-
-After creating a version, it is possible to edit the information
-associated with it using apm_package_version.edit.
-+
After creating a version, it is possible to edit the information
+associated with it using apm_package_version.edit.
 
 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;
 
-
-Versions can be enabled or disabled. Enabling a version instructs APM to
+

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.

+available to the OpenACS.
 
 procedure enable (
     version_id          in apm_package_versions.version_id%TYPE
@@ -463,11 +244,9 @@
     version_id          in apm_package_versions.version_id%TYPE  
 );
 
-
-Files associated with a version can be added and removed. The path is
-relative to the package-root which is
-acs-server-root/packages/package-key.
-+
Files associated with a version can be added and removed. The path is
+relative to the package-root which is
+acs-server-root/packages/package-key.
 -- 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 
 );
-
-Package versions need to indicate that they provide interfaces for other
+

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.

+specification of a version name for package URIs.
 
 -- Add an interface provided by this version.
 function add_interface(
@@ -509,11 +286,9 @@
     version_id          in apm_package_versions.version_id%TYPE
 );
 
-
-The primary use of interfaces is for other packages to specify required
+

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.

+unless all of its dependencies have been satisfied.
 
 -- 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
 );
 
-
-As new versions of packages are created, it is necessary to compare their
-version names. These two functions assist in that task.
-+
As new versions of packages are created, it is necessary to compare their
+version names. These two functions assist in that task.
 
 -- 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;
 
-
-Creating Instances of a Package
-Once a package is registered in the system, it is possible to create
+

Creating Instances of a Package

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.

+parameters.
 
 create or replace package apm_application
 as
@@ -582,12 +352,10 @@
 );
 end apm_application;
 
-
-Just creating a package instance is not sufficient for it to be served
+

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 OpenACS API Documentation service -makes itself available on the OpenACS main site:

+makes itself available on the OpenACS main site:
 
 declare
     api_doc_id integer;
@@ -614,20 +382,16 @@
 show errors
 
 
-
-Specifying Configuration Parameters for each Instance
-A parameter is a setting that can be changed on a package instance basis.
+

Specifying Configuration Parameters for each Instance

A parameter is a setting that can be changed on a package instance basis. Parameters are registered on each package_key, 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.

All of the functions below are in the APM PL/SQL -package.

+set when instances are created, but can be changed for each instance.
All of the functions below are in the APM PL/SQL
+package.
 
 -- Indicate to APM that a parameter is available to the system.
 function register_parameter (
@@ -673,10 +437,8 @@
                 default null
 );
 
-
-The following functions are used to associate values with parameters and
-instances:
-+
The following functions are used to associate values with parameters and
+instances:
 
 -- 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
 );  
 
-
-

-Data Model Discussion

The central piece of the data model is the apm_package_types +

Data Model Discussion

The central piece of the data model is the apm_package_types 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 bboard package is installed on your OpenACS server, a row in apm_package_types will be created, noting that it's an -application package type.

The apm_packages table is used to contain information about -the instances of packages currently created in the system. The +application package type.

The apm_packages table is used to contain information about +the instances of packages currently created in the system. The package_key column references the apm_package_types table to ensure that no package instance can be created for a type that does -not exist.

The apm_package_versions table contains information specific +not exist.

The apm_package_versions table contains information specific to a particular version of a package. Several tables reference this one to -provide further information about the particular version:

-apm_package_owners +provide further information about the particular version:
- apm_package_owners Stores information about the owners of a particular version of a package. -
- -apm_package_files +
- apm_package_files Stores information about the files that are part of a version. -
- -apm_package_dependencies +
- apm_package_dependencies Stores information about what interfaces the package provides and -requires.
-
Parameter information is maintained through two tables:
-
- -apm_parameters +requires.
Parameter information is maintained through two tables:
- apm_parameters This table contains the definition of each of the parameters for a package. -
- -apm_parameter_values +
- apm_parameter_values This table holds all of the values of parameters for specific package instances. -
-
A number of views are available for obtaining information about packages -registered in the APM.
-
- -apm_package_version_info +
A number of views are available for obtaining information about packages +registered in the APM.
- apm_package_version_info Provides information about all of the versions in the system with information available from the apm_package_types table. -
- -apm_enabled_package_versions +
- apm_enabled_package_versions A view (subset) of the above table with only enabled versions. -
- -apm_file_info - Provides a public interface for querying file information.
-

-User Interface

The APM's user interface is part of the +

apm_file_info + Provides a public interface for querying file information.

User Interface

The APM's user interface is part of the OpenACS Administration Service. 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.

-Configuration/Parameters

APM has two parameters for configuring how it interacts with the UNIX +site-wide administration.

Configuration/Parameters

APM has two parameters for configuring how it interacts with the UNIX filesystem, accessible via the Site Map admin page. These parameters need not be changed under most circumstances, but may -need to be tweaked for Windows compatibility.

-GzipExecutableDirectory +need to be tweaked for Windows compatibility.
- GzipExecutableDirectory This directory points to where the gunzip program can be found for uncompressing gzip archives. This is needed for the installation of .apm files which are simply gziped tarballs. Default is /usr/local/bin -
- -InfoFilePermissionsMode +
- InfoFilePermissionsMode This sets the default UNIX permissions used when creating files using the -APM. Default is 775.
-

-Future Improvements/Areas of Likely Change

APM has been in production since OpenACS 3.3, and as of version 4.0 offers a +APM. Default is 775.

Future Improvements/Areas of Likely Change

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.

Architecturally, minor improvements to the data model and the +end users by facilitating the extension of their OpenACS systems.

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.

APM packages currently lack provisions to verify security information. +architecture over time.

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.

Another anticipated change is to split the APM UI into separate systems +repositories worldwide.

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.

-Authors

System creator: Bryan Quinn, Jon Salz, Michael Yoon, Lars Pind, Todd -Nightingale.
System owner: Bryan Quinn
Documentation author: Bryan Quinn, building from earlier versions by Jon -Salz, Michael Yoon, and Lars Pind.

-Revision History

------ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Document Revision #	Action Taken, Notes	When?	By Whom?
0.1	Creation	9/25/2000	Bryan Quinn
0.8	Ready for QA	9/29/2000	Bryan Quinn
0.9	Edited for ACS 4 Beta release	10/02/2000	Kai Wu
1.0	Edited for OpenACS 4.5 Beta release	03/02/2002	Roberto Mello

- - - - - - - - - - - -

-Prev	Home	Next -
OpenACS 4.5 Package Manager Requirements	Up	OpenACS 4 Security Requirements

- rmello at fslc.usu.edu -

+usability perspective.

Authors

System creator: Bryan Quinn, Jon Salz, Michael Yoon, Lars Pind, Todd +Nightingale.
System owner: Bryan Quinn
Documentation author: Bryan Quinn, building from earlier versions by Jon +Salz, Michael Yoon, and Lars Pind.

Revision History

Document Revision #	Action Taken, Notes	When?	By Whom?
0.1	Creation	9/25/2000	Bryan Quinn
0.8	Ready for QA	9/29/2000	Bryan Quinn
0.9	Edited for ACS 4 Beta release	10/02/2000	Kai Wu
1.0	Edited for OpenACS 4.5 Beta release	03/02/2002	Roberto Mello

Prev	Home	Next
OpenACS 4.5 Package Manager Requirements	Up	OpenACS 4 Security Requirements

rmello at fslc.usu.edu

+these features should be quite straightforward.

- - +

-OpenACS 4.5 Package Manager Requirements

-by Bryan Quinn and Todd Nightingale -

-Introduction

The following is a requirements document for the OpenACS Package Manager +OpenACS 4.5 Package Manager Requirements

Prev	Chapter 7. Kernel Documentation	Next

OpenACS 4.5 Package Manager Requirements

+by Bryan Quinn and Todd Nightingale
+ OpenACS docs are written by the named authors, but may be edited + by OpenACS documentation staff. +

Introduction

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:

A public procedural API. (v 3.3 only has web-based UI)
Support for dependency checking.
Support for compound packages (to support installation chaining).
Support for on-line parameter setting.
Support for sub-site level configuration (requires revised ad_parameter +with the following specific enhancements:
- A public procedural API. (v 3.3 only has web-based UI)
- Support for dependency checking.
- Support for compound packages (to support installation chaining).
- Support for on-line parameter setting.
- Support for sub-site level configuration (requires revised ad_parameter and /admin pages at sub-site level; deprecation of site-wide parameter -file).
-
To differentiate these new requirements from the requirements of version +file).

To differentiate these new requirements from the requirements of version 3.3, all requirements new in v4 are prefaced with the number -4.

We gratefully acknowledge the authors of APM 3 for their original design +4.

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.

-Vision Statement

A typical website will tend to offer its users a number of web-based +behind this document.

Vision Statement

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.

In general terms, a package is a unit of software that serves a single +OpenACS sites.

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.

-System Overview

+user-friendly, and subsite-aware manner.

System Overview

The OpenACS Package Manager (APM) consists of: -

-
-A standard format for APM packages including:
-
- Version numbering, independent of any other package and the OpenACS as a -whole
- Specification of the package interface
- Specification of dependencies on other packages (if any)
- Attribution (who wrote it) and ownership (who maintains it)
-
-
-Web-based tools for package management:
-
- Obtaining packages from a remote distribution point
- -
  Installing packages, if and only if:
  -
  1. All prerequisite packages are installed
  2. No conflicts will be created by the installation
  -
- Configuring packages (obsoleting the monolithic OpenACS configuration -file)
- Upgrading packages, without clobbering local modifications
- Uninstalling unwanted packages
-
-A registry of installed packages, database-backed and +
- A standard format for APM packages including:
  - Version numbering, independent of any other package and the OpenACS as a +whole
  - Specification of the package interface
  - Specification of dependencies on other packages (if any)
  - Attribution (who wrote it) and ownership (who maintains it)
- Web-based tools for package management:
  - Obtaining packages from a remote distribution point
  - Installing packages, if and only if:
    All prerequisite packages are installed
    No conflicts will be created by the installation
  - Configuring packages (obsoleting the monolithic OpenACS configuration +file)
  - Upgrading packages, without clobbering local modifications
  - Uninstalling unwanted packages
- A registry of installed packages, database-backed and integrated with file system-based version control -
- -
  -Web-based tools for package development:
  -
  - Creating new packages locally
  - Releasing new versions of locally-created packages
  - Uploading packages to a global package repository on the web
  - Use of these tools should be safe, i.e. installing or removing a package -should never break an OpenACS installation
  -
- -
  -Web-based tools for package configuration:
  -
  - The ability to change package parameter values on-line through a simple -web interface.
  - A new ad_parameter which does not require a monolithic site-wide -parameter's file or server restarts for changes to take effect.
  - The ability to manage multiple package instances at the sub-site -level.
  -
-

-Use-cases and User-scenarios

Web-based tools for package development:

Creating new packages locally
Releasing new versions of locally-created packages
Uploading packages to a global package repository on the web
Use of these tools should be safe, i.e. installing or removing a package +should never break an OpenACS installation

Web-based tools for package configuration:

The ability to change package parameter values on-line through a simple +web interface.
A new ad_parameter which does not require a monolithic site-wide +parameter's file or server restarts for changes to take effect.
The ability to manage multiple package instances at the sub-site +level.

Use-cases and User-scenarios

The APM is intended for the following classes of users, which may or may not -overlap:

-Developers (referred to as 'the developer') use +overlap:
1. Developers (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.
2. -Site-wide administrators (referred to as 'the +API for direct control of the APM system.
3. Site-wide administrators (referred to as 'the administrator') use the APM to install packages for their OpenACS instance, -and optionally make them available to sub-sites.
4. -Sub-site administrators (referred to as 'the +and optionally make them available to sub-sites.
5. Sub-site administrators (referred to as 'the sub-admin') use an administration interface to configure and enable -packages for their sub-site.
-
Initial Package Development
-
-David Developer writes a piece of software used to do +packages for their sub-site.

Initial Package Development

David Developer 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 Patricia -Programmer's Super Widget toolkit, he specifies that as a +UI. Noting that his software was built with Patricia +Programmer'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.

Initial Package Installation

-Annie Admin learns of David's KM system by browsing +available for download at the OpenACS package repository.

Initial Package Installation

Annie Admin 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.

Since the package is available for use, its initialization routines are +installation was successful, the package is available for use.

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.

Initial Subsite Use of Package

Annie Admin decides to make the KM module available only to a particular +be ready for use. Annie restarts the server.

Initial Subsite Use of Package

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).

Annie Admin notifies Sally SubAdmin by e-mail that a new +using the Sub-site type UI (not part of APM).

Annie Admin notifies Sally SubAdmin 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.

Upgrade Process

Sally SubAdmin finds a bug in the KM system and sends a report to David +These changes take effect immediately, without any server restarts.

Upgrade Process

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.

Sally SubAdmin asks Annie Administrator to upgrade the package using the +repository.

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.

Procedural API

-Danielle Developer wants her software to perform +in Sally's sub-site.

Procedural API

Danielle Developer 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.

-Related Links

-Requirements: Data Model

-
-4.500.0 Package Identification -(All of these items are entered by the developer using the developer UI.)
-
-4.500.1 A human readable package key that is guaranteed +exhibits different behavior.

Requirements: Data Model

4.500.0 Package Identification +(All of these items are entered by the developer using the developer UI.)
4.500.1 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."
-
-4.500.5 A package id (primary key) that is guaranteed to +example, "apm."
4.500.5 A package id (primary key) that is guaranteed to be unique to the local site must be maintained by the APM. For example, -"25."
-
-4.500.10 A package URL that is guaranteed to be unique +"25."
4.500.10 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." -
-
-
-4.505.0 Version Identification - (All of these items are entered by the developer using the developer UI.)
-
-4.505.1 A version id (primary key) that is guaranteed to -be unique to the local site must be maintained by the APM.
-
-4.505.5 A version URL that is guaranteed to be unique +
4.505.0 Version Identification + (All of these items are entered by the developer using the developer UI.)
4.505.1 A version id (primary key) that is guaranteed to +be unique to the local site must be maintained by the APM.
4.505.5 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. -
-

-Requirements: API

The API for APM v3 is explicitly a private API. However, it would be +

Requirements: API

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.

-
-4.400.0 Packages Status Predicates
-
-4.400.1 Given defining information such as a package URL, +that already do all of the below in raw SQL.
- 4.400.0 Packages Status Predicates
  4.400.1 Given defining information such as a package URL, the APM API can return the status of the package on the local OpenACS -instance.
  -
- -
  -4.405.0 Package Information Procedures
  -
  -4.405.1 The APM API can return information for any +instance.
- 4.405.0 Package Information Procedures
  4.405.1 The APM API can return information for any locally installed packages, including the version number, paths and files, -and package key.
  -
- -
  -4.410.0 Sub-site Procedures
  -
  -4.410.1 After a package has been installed at the +and package key.
- 4.410.0 Sub-site Procedures
  4.410.1 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.
  -
- -
  -4.415.0 Parameter Values (replaces ad_parameter)
  -
  -4.415.1 The system API shall allow subsite parameters for +presence, creation, enabling, disabling, and destruction on a subsite.
- 4.415.0 Parameter Values (replaces ad_parameter)
  4.415.1 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).
  -
  -4.415.5 Parameters for a given subsite and package can be -returned by the system API.
  -
-

-Requirements: Security

+take effect after a server restart (default is immediate).

4.415.5 Parameters for a given subsite and package can be +returned by the system API.

Requirements: Security

Provisions will be made to assure that packages are securely -identified.

-4.600.1 Each package will have a PGP signature and there +identified.
- 4.600.1 Each package will have a PGP signature and there will be MD5 time stamps for each file within the package. -
- -4.600.5 The APM will provide a facility to validate both -the PGP signature and MD5 stamps information before a package install.
-

-Requirements: The User Interface

The user interface is a set of HTML pages that are used to drive the +

4.600.5 The APM will provide a facility to validate both +the PGP signature and MD5 stamps information before a package install.

Requirements: The User Interface

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.

-Requirements: The Developer's Interface

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.

Requirements: The Developer's Interface

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.

-
10.0 Define a package.
-
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.
- 10.0 Define a package.
  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.
  -
  -10.1 The APM must maintain the state of all locally -generated packages.
  -
  -10.50 If the developer fails to provide the required -information, the package cannot be created.
  -
  -10.55 All of the package information should be editable -after creation, except for the package key.
  -
  -4.10.60 The package creator must specify whether the +package key, version information, owner information, and a canonical URL.
  10.1 The APM must maintain the state of all locally +generated packages.
  10.50 If the developer fails to provide the required +information, the package cannot be created.
  10.55 All of the package information should be editable +after creation, except for the package key.
  4.10.60 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.
  -
  -4.10.65 If the developer fails to provide unique +instance of the package is permitted.
  4.10.65 If the developer fails to provide unique information for unique fields specified in the data model requirements, the -package cannot be created.
  -
- -
  -20.0 Add files to a package
  -
  -20.1 The developer must be able to add files to the +package cannot be created.
- 20.0 Add files to a package
  20.1 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.
  -
  -20.3 Once a package has been versioned and distributed, +creation.
  20.3 Once a package has been versioned and distributed, no new files should be added to the package without incrementing the version -number.
  -
  -20.5 The APM's UI should facilitate the process of +number.
  20.5 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.
  -
  -20.10 The developer cannot add files to a given package -via the UI that do not exist in the file system already.
  -
  -20.15 Package file structure must follow a specified +and allowing the developer to confirm adding them.
  20.10 The developer cannot add files to a given package +via the UI that do not exist in the file system already.
  20.15 Package file structure must follow a specified convention. Please see the design -document for what we do currently.
  -
- -
  30.0 Remove files from a package
  -
  The developer must be able to remove files from a package. This can be -done in two ways.
  -
  - -
    -30.1 Access the APM UI, browse the file list, and remove -files.
    -
    -30.1.1If a file is removed from the package list, but not -from the file system, an error should be generated at package load time.
    -
  - -
    -30.5 Remove the file from file system.
    -
    -30.5.1 The APM UI should take note of the fact that the +document for what we do currently.
  - 30.0 Remove files from a package
    The developer must be able to remove files from a package. This can be +done in two ways.
    30.1 Access the APM UI, browse the file list, and remove +files.
    30.1.1If a file is removed from the package list, but not +from the file system, an error should be generated at package load time.
    30.5 Remove the file from file system.
    30.5.1 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. -
    -
    -
    -
  - -
    -40.0 Modify files in a package.
    -
    -40.1 The developer should be able to modify files in the -file system. The APM UI should not interfere with this.
    -
    -40.5 However, if the developer modifies files containing -procedural definitions, APM UI should allow a means to watch +
- 40.0 Modify files in a package.
  40.1 The developer should be able to modify files in the +file system. The APM UI should not interfere with this.
  40.5 However, if the developer modifies files containing +procedural definitions, APM UI should allow a means to watch those files and automatically reload them if changed. See requirement 50.0 -for more detail.
  -
  -40.10 Also, although a change in files implies that the +for more detail.
  40.10 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.
  -
- -
  -4.45.0 Manage Package Dependency Information.
  -
  -4.45.1 The developer should be able to specify which -interfaces the package requires.
  -
  -4.45.5 The developer should be able to specify which -interfaces the package provides.
  -
  -4.45.10 Circular dependencies are not allowed.
  -
- -
  -50.0 Watch a file
  -
  -4.50.1 The developer should be able to assign a watch to -any Tcl procedure file, whether in /packages or /tcl.
  -
  -50.5 If a watched file is locally modified, then it will +responsibility to update it.
- 4.45.0 Manage Package Dependency Information.
  4.45.1 The developer should be able to specify which +interfaces the package requires.
  4.45.5 The developer should be able to specify which +interfaces the package provides.
  4.45.10 Circular dependencies are not allowed.
- 50.0 Watch a file
  4.50.1 The developer should be able to assign a watch to +any Tcl procedure file, whether in /packages or /tcl.
  50.5 If a watched file is locally modified, then it will be automatically reloaded, thus allowing for any changes made to take affect -immediately.
  -
  -4.50.10 The setting of a watch should be persistent +immediately.
  4.50.10 The setting of a watch should be persistent across server restarts. -
  -
- -
  -60.0 Display an XML package specification
  -
  -60.1 The developer should be able to view the XML package +
- 60.0 Display an XML package specification
  60.1 The developer should be able to view the XML package specification that encodes all package information. -
  -
- -
  -70.0 Write an XML package specification to the file -system
  -
  -70.1 The developer should be able to write an up-to-date -XML specification to disk.
  -
  -70.5 The developer should be able to request the current -XML specification for all installed, locally generated packages.
  -
- -
  -130.0 Distribution file generation
  -
  -130.1 The developer should be able to generate a .APM -distribution file for the package with just one click.
  -
  -130.5 Generating a distribution file implies doing an +
- 70.0 Write an XML package specification to the file +system
  70.1 The developer should be able to write an up-to-date +XML specification to disk.
  70.5 The developer should be able to request the current +XML specification for all installed, locally generated packages.
- 130.0 Distribution file generation
  130.1 The developer should be able to generate a .APM +distribution file for the package with just one click.
  130.5 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. -
  -
- -
  -140.0 Access CVS information
  -
  -140.1 The developer should be able to determine the CVS +
- 140.0 Access CVS information
  140.1 The developer should be able to determine the CVS status of a package, or all packages, with a single click. -
  -
- -
  -4.200.0 Compound Package Construction
  -
  -4.200.1 The developer can include .APM packages +
- 4.200.0 Compound Package Construction
  4.200.1 The developer can include .APM packages (sub-packages) within a package (the compound package) like any other -file.
  -
  -4.200.5 The recommended usage for this feature is to +file.
  4.200.5 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 community-core-doc.apm. 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.
  -
  -4.200.10 If a sub-package is required for the +separate package that is required by the compound package.
  4.200.10 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.
  -
-

-Requirements: The Site-Wide Administrator's Interface

The requirement of the administrator's interface is to enable the +registered dependency on the sub-package.

Requirements: The Site-Wide Administrator's Interface

The requirement of the administrator's interface is to enable the administrator to install, enable, upgrade, disable, deinstall, and delete -packages.

-
-80.0 Package Enable/Disable
-
-4.80.1 The administrator should be able mark an installed +packages.
- 80.0 Package Enable/Disable
  4.80.1 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.
  -
  -4.80.5 Moreover, the administrator must be able to +is done through the sub-site system.
  4.80.5 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. -
  -
- -
  -90.0 Package Install
  -
  -90.1 The administrator must be able to install new -packages either from locally maintained .APM files or from URLs.
  -
  -90.5 In the case of an URL, the APM transparently +
- 90.0 Package Install
  90.1 The administrator must be able to install new +packages either from locally maintained .APM files or from URLs.
  90.5 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.
  -
  -90.10.1 If .APM files are present in a package, then it -is considered a compound package (use 4.210.0).
  -
  -90.15.0 Installation requires these steps:
  -
  1. -90.15.1The package dependencies are scanned. If some +and then optionally removes the .APM file just downloaded.
    90.10.1 If .APM files are present in a package, then it +is considered a compound package (use 4.210.0).
    90.15.0 Installation requires these steps:
    90.15.1The package dependencies are scanned. If some dependencies are not present, the system warns the administrator that -installation cannot proceed until those packages are installed.
    -
    -90.15.2 Assuming all dependencies are present, APM -extracts the contents of the APM file into the /packages directory.
    -
    -90.15.3 The administrator is offered the option of -importing directly into CVS.
    -
    -90.15.4 The administrator is given a list of data model -scripts found in the package and can select which ones to be executed.
    -
    -90.15.5 If no errors are recorded during this process, -the package is enabled.
    -
    -
  2. -
    -4.210.0 Compound package Install
    -
    -4.210.1 If .APM files are present in a package, then it -is considered a compound package.
    -
    -4.210.5.0 Installation of a compound package proceeds -according to the following sequence:
    -
    -
    -4.210.5.1 Identify the set of all sub-packages within -the compound package by scanning for all files with .APM.
    -
    -4.210.5.2 Identify which sub-packages are required by +installation cannot proceed until those packages are installed.
    90.15.2 Assuming all dependencies are present, APM +extracts the contents of the APM file into the /packages directory.
    90.15.3 The administrator is offered the option of +importing directly into CVS.
    90.15.4 The administrator is given a list of data model +scripts found in the package and can select which ones to be executed.
    90.15.5 If no errors are recorded during this process, +the package is enabled.
  3. 4.210.0 Compound package Install
    4.210.1 If .APM files are present in a package, then it +is considered a compound package.
    4.210.5.0 Installation of a compound package proceeds +according to the following sequence:
    4.210.5.1 Identify the set of all sub-packages within +the compound package by scanning for all files with .APM.
    4.210.5.2 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.
    -
    -4.210.5.3 Present Administrator with the ability to +first.
    4.210.5.3 Present Administrator with the ability to choose which sub-packages to install. Required sub-packages must be -installed.
    -
    -4.210.5.4 Proceed with the installation of each +installed.
    4.210.5.4 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 90.15.0, otherwise if it is a compound -package, proceed according to 4.210.5.0.
    -
    -4.210.5.5 If all required sub-packages are installed, +proceed according to 90.15.0, otherwise if it is a compound +package, proceed according to 4.210.5.0.
    4.210.5.5 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.
    -
    -4.210.5.6 Any attempt to install a compound package in +compound package is also a failure.
    4.210.5.6 Any attempt to install a compound package in the future involves a choice presented to the admin of installing any -uninstalled sub-packages.
    -
    -
  4. -
    4.220.0 Recovering from failed package installation
    -
    -4.220.1 If any error is generated during package +uninstalled sub-packages.
- 4.220.0 Recovering from failed package installation
  4.220.1 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.
  -
- -
  -100.0 Version Upgrade
  -
  -100.1 The administrator can upgrade to a new version of a -package. This entails
  -
  1. -100.1.1 Running any necessary and included upgrade -scripts.
  2. -100.1.5 Replacing any old files with new versions.
  3. -100.1.10 Marking the old version of the package as -'superseded' and disabling it.
  4. -100.1.15 Assuming no errors from above, the new package -is enabled.
  -
- -
  -110.0 Package Deinstall
  -
  -110.1 The administrator must be able to deinstall a -package that has already been installed. Deinstallation entails:
  -
  1. -110.1.1 Running any data model scripts necessary to drop -the package.
  2. -110.1.5 Moving all of the files into a separate location -in the file system from the installed packages.
  3. -4.110.1.10 If the package is a compound package, then +failure, the package should be selected for installation again.
  4. 100.0 Version Upgrade
    100.1 The administrator can upgrade to a new version of a +package. This entails
    100.1.1 Running any necessary and included upgrade +scripts.
    100.1.5 Replacing any old files with new versions.
    100.1.10 Marking the old version of the package as +'superseded' and disabling it.
    100.1.15 Assuming no errors from above, the new package +is enabled.
  5. 110.0 Package Deinstall
    110.1 The administrator must be able to deinstall a +package that has already been installed. Deinstallation entails:
    110.1.1 Running any data model scripts necessary to drop +the package.
    110.1.5 Moving all of the files into a separate location +in the file system from the installed packages.
    4.110.1.10 If the package is a compound package, then the administrator must confirm removing all sub-packages. Optionally, some -sub-packages can be kept.
    -
    -
    -110.5 Deinstalled packages can be re-installed at a later -date.
    -
    -4.110.10 If deinstalling a package or any of its +sub-packages can be kept.
  110.5 Deinstalled packages can be re-installed at a later +date.
  4.110.10 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.
  -
- -
  -120.0 Package Deletion
  -
  -120.1 The administrator should be able to completely +the package registering the dependency is removed.
- 120.0 Package Deletion
  120.1 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.
  -
  -120.5 This option can only be used if all package +package, all related database tables and content.
  120.5 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.
  -
- -
  -150.0 Scan for new or modified packages
  -
  -150.1 The administrator should be able to scan the file -system for any changes made in any of the installed package files.
  -
  -150.5 The administrator should be able to scan the file +consequences throughout a site and should almost never be done.
- 150.0 Scan for new or modified packages
  150.1 The administrator should be able to scan the file +system for any changes made in any of the installed package files.
  150.5 The administrator should be able to scan the file system for any newly installed packages. -
  -
-

-Requirements: The Sub-Site Administrator's Interface

Requirements: The Sub-Site Administrator's Interface

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. -

-
-4.300 Creating a package instance.
-
-4.300.1 From the sub-site /admin interface, there should +
- 4.300 Creating a package instance.
  4.300.1 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.
  -
  -4.300.5 From the "add" option, the sub-admin +option to add a package to the subsite.
  4.300.5 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.
  -
  -4.300.19 Once a package instance is added, it is -available on the list of the subsite's available packages.
  -
- -
  -4.305 Configuring a package instance.
  -
  -4.305.1 An automatic web interface that lists all -parameters with current values must be available.
  -
  -4.305.5 Changing the values for the parameters is -accomplished simply by submitting an HTML form.
  -
- -
  -4.310 Enabling a package instance.
  -
  -4.310.1 The sub-admin should be able to enable a package +type to which the sub-site belongs.
  4.300.19 Once a package instance is added, it is +available on the list of the subsite's available packages.
- 4.305 Configuring a package instance.
  4.305.1 An automatic web interface that lists all +parameters with current values must be available.
  4.305.5 Changing the values for the parameters is +accomplished simply by submitting an HTML form.
- 4.310 Enabling a package instance.
  4.310.1 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. -
  -
- -
  -4.315 Disabling a package instance.
  -
  -4.315.1 The sub-admin should be able to disable a package +
- 4.315 Disabling a package instance.
  4.315.1 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.
  -
- -
  -4.320 Deleting a package instance.
  -
  -4.320.1 Deleting a package instance involves deleting not +serve those URLs.
- 4.320 Deleting a package instance.
  4.320.1 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. -
  -
-

-Implementation notes

Despite the fact that requirements are meant to be design/implementation +

Implementation notes

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.

When a package is installed system-wide, a corresponding acs_object_type +comprehensible.

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.

When a package instance is created, it is an acs_object. Its parameters +for that acs_object_type.

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.

-Revision History

------ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Document Revision #	Action Taken, Notes	When?	By Whom?
0.1	Creation	8/10/2000	Bryan Quinn, Todd Nightingale
�	Reviewed	8/11/2000	John Prevost, Mark Thomas, and Pete Su
0.2	Revised and updated	8/12/2000	Bryan Quinn
0.3	Reviewed, revised, and updated - conforms to requirements template.	8/18/2000	Kai Wu
0.4	Minor edits before ACS 4 Beta.	9/30/2000	Kai Wu

- - - - - - - - - - - -

-Prev	Home	Next -
OpenACS 4 Subsites Design Document	Up	OpenACS 4.5 Package Manager Design

- rmello at fslc.usu.edu -

Revision History

Document Revision #	Action Taken, Notes	When?	By Whom?
0.1	Creation	8/10/2000	Bryan Quinn, Todd Nightingale
�	Reviewed	8/11/2000	John Prevost, Mark Thomas, and Pete Su
0.2	Revised and updated	8/12/2000	Bryan Quinn
0.3	Reviewed, revised, and updated - conforms to requirements template.	8/18/2000	Kai Wu
0.4	Minor edits before ACS 4 Beta.	9/30/2000	Kai Wu

Prev	Home	Next
OpenACS 4 Subsites Design Document	Up	OpenACS 4.5 Package Manager Design

rmello at fslc.usu.edu

- - +

-Prev	Chapter 7. Kernel Documentation

-Bootstrapping OpenACS

-by Jon Salz -

Tcl code: /tcl/0-acs-init.tcl and /packages/acs-kernel/bootstrap.tcl

This document describes the startup (bootstrapping) process for an AOLserver +Bootstrapping OpenACS

Prev	Chapter 7. Kernel Documentation

Bootstrapping OpenACS

+by Jon Salz
+ OpenACS docs are written by the named authors, but may be edited + by OpenACS documentation staff. +

Tcl code: /tcl/0-acs-init.tcl and /packages/acs-kernel/bootstrap.tcl

This document describes the startup (bootstrapping) process for an AOLserver running OpenACS. -

-The Big Picture

The Big Picture

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 /web/yourservername/tcl), +library directory (generally /web/yourservername/tcl), sourcing each file in sequence. -

While this overall structure for initialization is still intact, package +

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:

Examine the OpenACS file tree for files that should not be present in OpenACS +to do during initialization, most notably:
- 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).
- Scan the /packages directory for new packages.
- Initialize enabled packages by sourcing their *-procs.tcl -and *-init.tcl files.
-
+removed).
Scan the /packages directory for new packages.
Initialize enabled packages by sourcing their *-procs.tcl +and *-init.tcl files.

This document examines in detail each of the steps involved in AOLserver/OpenACS startup. -

-The Startup Process

The Startup Process

As soon as the nsd daemon is executed by the init process (or otherwise), AOLserver reads its configuration file and chroots itself if necessary. It then loads shared libraries indicated in the .ini file (e.g., the Oracle driver and nssock), and sources Tcl module files (generally in /home/aol30/modules/tcl). This step is, and has always been, the same for all AOLservers, regardless of whether they are running OpenACS. -

Next AOLserver sources, in lexicographical order, each file in the +

Next AOLserver sources, in lexicographical order, each file in the /tcl directory. The first such file is 0-acs-init.tcl, which doesn't do much directly except to -determine the OpenACS path root (e.g., /web/yourservername) +determine the OpenACS path root (e.g., /web/yourservername) by trimming the final component from the path to the Tcl library directory -(/web/yourservername/tcl). But +(/web/yourservername/tcl). But 0-acs-init.tcl's has an important function, namely sourcing -/packages/acs-core/bootstrap.tcl, which does the following:

-Initialize some NSVs used by the core. These NSVs are +/packages/acs-core/bootstrap.tcl, which does the following:
1. Initialize some NSVs used by the core. These NSVs are documented in /packages/acs-core/apm-procs.tcl - no need to worry about them unless you're an OpenACS core hacker. -
2. -Verify the deletion of obsolete OpenACS files. The +
3. Verify the deletion of obsolete OpenACS files. The /tcl directory has evolved quite a bit over the months and years, and a few files have come and gone. The /www/doc/removed-files.txt file contains a list of files which -must be deleted from the AOLserver installation, at the risk of +must be deleted from the AOLserver installation, at the risk of causing weird conflicts, e.g., having several security filters registered. bootstrap.tcl scans through this list, logging error messages to the log if any of these files exist. -
4. -Source *-procs.tcl files in the OpenACS core. +
5. Source *-procs.tcl files in the OpenACS core. We source each file matching the *-procs.tcl glob in the /packages/acs-kernel directory, in lexicographical order. These procedure are needed to perform any of the following steps. -
6. -Ensure that the database is available by grabbing and +
7. Ensure that the database is available 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). -
8. -Register any new packages in the /packages -directory. In each directory inside /packages, we look +
9. Register any new packages in the /packages +directory. In each directory inside /packages, we look for a .info 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, no packages will have been registered in the database +OpenACS starts up, no packages will have been registered in the database yet, so this step will registers every single package in the /packages directory.) Note that packages discovered here are initially disabled; they must be manually enabled in the package manager before they can be used. -
10. -Ensure that the acs-kernel package is -enabled. If the OpenACS core isn't initialized, the server +
11. Ensure that the acs-kernel package is +enabled. 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. -
12. -Load *-procs.tcl files for enabled -packages, activating their APIs. +
13. Load *-procs.tcl files for enabled +packages, activating their APIs. -
14. -Load *-init.tcl files for enabled packages, +
15. Load *-init.tcl files for enabled packages, giving packages a chance to register filters and procedures, initialize data structures, etc. -
16. -Verify that the core has been properly initialized by +
17. Verify that the core has been properly initialized 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.
-
+operational, so we log an error.

At this point, bootstrap.tcl is done executing. AOLserver proceeds to source the remaining files in the /tcl directory (i.e., unpackaged libraries) and begins listening for connections. -

($Id$)

- - - - - - - - - - - -

-Prev	Home
Documenting Tcl Files: Page Contracts and Libraries	Up

- rmello at fslc.usu.edu -

Prev	Home
Documenting Tcl Files: Page Contracts and Libraries	Up

+ Lynch, Jon Griffin, Daryl Biberdorf, Bjorn Thor Jonsson, Jade Rubick, + Fred Yankowski, Dan Chak, Sebastiano Pilla, Reuven Lerner and Malte + Sussdorff. +

- - +

-Credits

-Vinod Kurup put +Credits

Prev	Chapter 2. Installing on Unix/Linux	Next

Credits

+ by Vinod Kurup
+ OpenACS docs are written by the named authors, but may be edited + by OpenACS documentation staff. +

Vinod Kurup put together the January 2002 version of this guide from many sources of - information.

+ information.
- Install an Operating System -
- +
- OpenACS 3.x Installation Guide -
- +
- Gilbert Wong's FreeBSD installation guide -
- +
- My own Brief OpenACS4 installation guide -
-
+

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,15 @@ 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.

+ Tom Jackson and Karl Lehenbauer.

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. -

- All questions and comments regarding - this guide should be sent to vinod@kurup.com or on the OpenACS bboards. -

($Id$)

- - - - - - - - - - - -

-Prev	Home	Next -
Next Steps	Up	Chapter 3. Installing on Windows

- rmello at fslc.usu.edu -

+ All questions and comments regarding + this guide should be posted on the OpenACS bboards. +

($Id$)

Prev	Home	Next
Next Steps	Up	Chapter 3. Installing on Windows

rmello at fslc.usu.edu

- - +

-Database Access API

-by Jon Salz -

Tcl procedures: /packages/acs-kernel/10-database-procs.tcl
Tcl initialization: /packages/acs-kernel/database-init.tcl

-The Big Picture

+Database Access API

Prev	Chapter 7. Kernel Documentation	Next

Database Access API

+by Jon Salz. Revised and expanded by +Roberto Mello (rmello at fslc dot usu dot edu), July 2002. +
+ OpenACS docs are written by the named authors, but may be edited + by OpenACS documentation staff. +

Tcl procedures: /packages/acs-kernel/10-database-procs.tcl
Tcl initialization: /packages/acs-kernel/database-init.tcl

The Big Picture

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. -

There were four significant problems with the way OpenACS previously used the -database (i.e., directly through the ns_db interface):

-Handle management. We required code to pass database +
There were four significant problems with the way OpenACS previously used the +database (i.e., directly through the ns_db interface):
1. Handle management. 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. -
2. -
  -Nested transactions. In our Oracle driver, begin +
3. Nested transactions. In our Oracle driver, begin transaction really means "turn auto-commit mode off" and end transaction 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:
  -+non-obvious. Consider: proc foo { db args } { db_transaction { @@ -74,8 +37,7 @@ db_dml unused "insert into greeble(bork) values(50)" } - - + This would insert greeble #33 and do all the stuff in foo transactionally, but the end transaction in foo would actually cause a commit, and greeble #50 would later be inserted in @@ -84,82 +46,55 @@ already have been committed!. This is not a good thing. - -
- +Postgres).

The Database Access API addresses the first three problems by: -

- -making use of database handles transparent -wrapping common database operations (including transaction management) in -Tcl control structures (this is, after all, what Tcl is good at!) - - + making use of database handles transparent wrapping common database operations (including transaction management) in +Tcl control structures (this is, after all, what Tcl is good at!) 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.) - -To be clear, SQL abstraction is not fully implemented in OpenACS + To be clear, SQL abstraction is not 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: - -how to add WHERE clause criteria dynamically -how to build a dynamic ORDER BY clause (Ben Adida has a -proposed solution for this) -how to define a statement's formal interface (i.e., what bind +unresolved issues include: how to add WHERE clause criteria dynamically how to build a dynamic ORDER BY clause (Ben Adida has a +proposed solution for this) how to define a statement's formal interface (i.e., what bind variables it expects, what columns its SELECT clause must contain if it's a query) without actually implementing the statement in a -specific SQL dialect - - +specific SQL dialect 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. - -

- - -The Bell Tolls for set_variables_after_query - + The Bell Tolls for set_variables_after_query set_variables_after_query 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: - -+ 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!" - - + Like ns_db 1row, 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: - -+ 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 +103,34 @@ doc_body_append "There's no such user!" } - - + Selecting a bunch of rows is a lot prettier now: - -+ db_foreach select_names "select first_names, last_name from users" { doc_body_append "Say hi to $first_names $last_name for me!<br>" } - - + That's right, db_foreach is now like ns_db select plus a while loop plus set_variables_after_query plus an if statement (containing code to be executed if no rows are returned). - -+ 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!" } - - - - -Handle Management - + Handle Management 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: - -+ doc_body_append "<ul>" db_foreach select_names "select first_names, last_name, user_id from users" { @@ -224,101 +149,79 @@ doc_body_append "</ul>" db_release_unused_handles - - + 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 db_release_unused_handles is invoked (or the script terminates). - -Note that there is no analogue to ns_db gethandle - the -handle is always automatically allocated the first time it's needed. - - - -Bind Variables -Introduction - + Note that there is no analogue to ns_db gethandle - the +handle is always automatically allocated the first time it's needed. Bind Variables Introduction 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 - -+ -delete from wp_presentations where presentation_id = some_presentation_id +delete from wp_presentations where presentation_id = some_presentation_id - - -where some_presentation_id is a number which is a valid + +where some_presentation_id 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 -bind variables, which represent placeholders for actual +bind variables, 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: - -+ db_dml presentation_delete { delete from wp_presentations where presentation_id = :some_presentation_id } - - + When this SQL statement is invoked, the value for the bind variable :some_presentation_id is pulled from the Tcl variable $some_presentation_id (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 ns_set -providing bind variables' values; see Usage.) - -The value of a bind variable is taken literally by the database driver, so +providing bind variables' values; see Usage.) + 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 db_quote to escape single-quotes contained -in the value. The following works fine, despite the apostrophe: -+in the value. The following works fine, despite the apostrophe: set exclamation "That's all, folks!" db_dml exclamation_insert { insert into exclamations(exclamation) values(:exclamation) } - -Note that you can use a bind variable in a SQL statement only where you + 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 $table_name is set -properly: -+properly: select * from :table_name - -Why Bind Variables Are Useful - + Why Bind Variables Are Useful Why bother with bind variables at all - why not just write the Tcl statement above like this: - -+ db_dml presentation_delete " delete from wp_presentations where presentation_id = $some_presentation_id " - - + (Note the use of double-quotes to allow the variable reference to $some_presentation_id to be interpolated in.) This will work, but consider the case where some devious user causes some_presentation_id to be set to something like '3 or 1 = 1', which would result in the following statement being executed: - -+ delete from wp_presentations where presentation_id = 3 or 1 = 1 - - + 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 +231,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. - -Usage -Every db_* command accepting a SQL command as an argument -supports bind variables. You can either - -specify the -bind switch to provide a set with bind variable -values, or -specify the -bind switch to explicitly provide a list of -bind variable names and values, or -not specify a bind variable list at all, in which case Tcl variables are -used as bind variables. - - + Usage Every db_* command accepting a SQL command as an argument +supports bind variables. You can either specify the -bind switch to provide a set with bind variable +values, or specify the -bind switch to explicitly provide a list of +bind variable names and values, or not specify a bind variable list at all, in which case Tcl variables are +used as bind variables. The default behavior (i.e., if the -bind switch is omitted) is that these procedures expect to find local variables that correspond in name to the referenced bind variables, e.g.: - -+ set user_id 123456 set role "administrator" @@ -361,14 +255,11 @@ # of "administrator" } - - + The value of the local Tcl variable user_id (123456) is bound to the user_id bind variable. - -The -bind switch can takes the name of an ns_set -containing keys for each bind variable named in the query, e.g.: -+ The -bind switch can takes the name of an ns_set +containing keys for each bind variable named in the query, e.g.: set bind_vars [ns_set create] ns_set put $bind_vars user_id 123456 @@ -385,12 +276,10 @@ # of "administrator" } - - + Alternatively, as an argument to -bind you can specify a list of alternating name/value pairs for bind variables: - -+ db_foreach user_group_memberships_by_role { select g.group_id, g.group_name @@ -403,23 +292,18 @@ # of "administrator" } - -Nulls and Bind Variables - + Nulls and Bind Variables When processing a DML statement, Oracle coerces empty strings into -null. (This coercion does not occur in the +null. (This coercion does not occur in the WHERE clause of a query, i.e. col = '' and col is null are not equivalent.) - -As a result, when using bind variables, the only way to make Oracle set a + As a result, when using bind variables, the only way to make Oracle set a column value to null 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". -These Oracle quirks complicate the process of writing clear and abstract -DML difficult. Here is an example that illustrates why: -+"null". These Oracle quirks complicate the process of writing clear and abstract +DML difficult. Here is an example that illustrates why: # # Given the table: @@ -439,19 +323,15 @@ # null, because Oracle has coerced the empty string (even for the # numeric column "bar") into null in both cases - - + Since databases other than Oracle do not coerce empty strings into null, 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. - -Therefore, the Database Access API provides a database-independent way to + Therefore, the Database Access API provides a database-independent way to represent null (instead of the Oracle-specific idiom of the -empty string): db_null. -Use it instead of the empty string whenever you want to set a column value -explicitly to null, e.g.: -+empty string): db_null. Use it instead of the empty string whenever you want to set a column value +explicitly to null, e.g.: set bar [db_null] set baz [db_null] @@ -460,35 +340,23 @@ # # sets the values for both the "bar" and "baz" columns to null - - - - -SQL Abstraction - + SQL Abstraction 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. - - - - -Placing Column Values in Arrays and Sets - + Placing Column Values in Arrays and Sets Normally, db_foreach, db_0or1row, and db_1row places the results of queries in Tcl variables, so you can say: - -+ db_foreach users_select "select first_names, last_name from users" { doc_body_append "<li>$first_names $last_name\n" } - - + 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 +365,7 @@ instruct the database routines to place the results in a Tcl array or ns_set, respectively, where the keys are the column names and the values are the column values. For example: - -+ db_foreach users_select "select first_names, last_name from users" -column_set columns { # Now $columns is an ns_set. @@ -508,282 +375,143 @@ } } - - + will write something like: - - -first_names is Jon. last_name is Salz. -first_names is Lars. last_name is Pind. -first_names is Michael. last_name is Yoon. - - - - -Sequence Pooling - -The database library can transparently maintain pools of sequence values, so -that each request for a new sequence value (using db_nextval) -does not incur a roundtrip to the server. For instance, this functionality is -very useful in the security/sessions library, which very frequently allocates -values from the sec_id_seq sequence. To utilize this -functionality for a particular sequence, register the sequence to be pooled, -either using the db_register_pooled_sequence procedure at server -startup time, or by including a configuration parameter of the form - -- -PoolSequence.sequence_name_seq=count - - - -in any configuration section in the yourservername.ini -file, e.g., e.g., - -- -[ns/server/yourservername/acs/security] -PoolSequence.sec_id_seq=20 - - - -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 -PooledSequenceUpdateInterval parameter in the -[ns/server/yourservername/acs/database] configuration -section.) - - - - -API - + first_names is Jon. last_name is Salz. first_names is Lars. last_name is Pind. first_names is Michael. last_name is Yoon. API Note that you never have to use ns_db anymore (including ns_db gethandle)! Just start doing stuff, and (if you want) call db_release_unused_handles when you're done as a hint to release the database handle. - - -db_abort_transaction - - --db_abort_transaction - -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 -db_dml "abort" "abort transaction". + db_null - - - -db_null - - - --db_null - -Returns a value which can be used in a bind variable to represent the SQL + +db_null + Returns a value which can be used in a bind variable to represent the SQL value null. See Nulls and Bind Variables -above. - - -db_foreach - - --db_foreach statement-name sql [ -bind bind_set_id | -bind bind_value_list ] \ - [ -column_array array_name | -column_set set_name ] \ - code_block [ if_no_rows if_no_rows_block ] - -Performs the SQL query sql, executing -code_block once for each row with variables set to +above. +db_foreach + +db_foreach statement-name sql [ -bind bind_set_id | -bind bind_value_list ] \ + [ -column_array array_name | -column_set set_name ] \ + code_block [ if_no_rows if_no_rows_block ] + Performs the SQL query sql, executing +code_block once for each row with variables set to column values (or a set or array populated if -column_array or column_set is specified). If the query returns no rows, executes -if_no_rows_block (if provided). -Example: -+if_no_rows_block (if provided). Example: 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" } - - + The code block may contain break statements (which terminate the loop and flush the database handle) and continue statements -(which continue to the next row of the loop). - -db_1row - --db_1row statement-name sql [ -bind bind_set_id | -bind bind_value_list ] \ - [ -column_array array_name | -column_set set_name ] - -Performs the SQL query sql, setting variables to -column values. Raises an error if the query does not return exactly 1 row. -Example: -+(which continue to the next row of the loop). db_1row +db_1row statement-name sql [ -bind bind_set_id | -bind bind_value_list ] \ + [ -column_array array_name | -column_set set_name ] + Performs the SQL query sql, setting variables to +column values. Raises an error if the query does not return exactly 1 row. Example: 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. - - -db_0or1row - --db_0or1row statement-name sql [ -bind bind_set_id | -bind bind_value_list ] \ - [ -column_array array_name | -column_set set_name ] - -Performs the SQL query sql. If a row is returned, + db_0or1row +db_0or1row statement-name sql [ -bind bind_set_id | -bind bind_value_list ] \ + [ -column_array array_name | -column_set set_name ] + Performs the SQL query sql. 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. - -db_nextval - --db_nextval sequence-name - -Returns the next value for the sequence sequence-name (using a -SQL statement like SELECT sequence-name.nextval FROM -DUAL). 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 Sequence Pooling). - - - -db_register_pooled_sequence - --db_register_pooled_sequence sequence-name pool-size - -Registers the sequence sequence-name to be pooled, with a pool -size of pool-size sequence values (see Sequence Pooling). - - - -db_string - --db_string statement-name sql [ -default default ] [ -bind bind_set_id | -bind bind_value_list ] - -Returns the first column of the result of SQL query -sql. If sql doesn't return a -row, returns default (or throws an error if -default is unspecified). Analogous to +returns 0. If more than one row is returned, throws an error. db_string +db_string statement-name sql [ -default default ] [ -bind bind_set_id | -bind bind_value_list ] + Returns the first column of the result of SQL query +sql. If sql doesn't return a +row, returns default (or throws an error if +default is unspecified). Analogous to database_to_tcl_string and database_to_tcl_string_or_null. - - -db_list - --db_list statement-name sql [ -bind bind_set_id | -bind bind_value_list ] - -Returns a Tcl list of the values in the first column of the result of SQL -query sql. If sql doesn't + db_nextval +db_nextval sequence-name + Returns the next value for the sequence sequence-name (using a +SQL statement like SELECT sequence-name.nextval FROM +DUAL). 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. + + db_list +db_list statement-name sql [ -bind bind_set_id | -bind bind_value_list ] + Returns a Tcl list of the values in the first column of the result of SQL +query sql. If sql doesn't return any rows, returns an empty list. Analogous to database_to_tcl_list. - - -db_list_of_lists - --db_list_of_lists statement-name sql [ -bind bind_set_id | -bind bind_value_list ] - -Returns a Tcl list, each element of which is a list of all column values -in a row of the result of SQL query sql. If -sql doesn't return any rows, returns an empty list. + db_list_of_lists +db_list_of_lists statement-name sql [ -bind bind_set_id | -bind bind_value_list ] + Returns a Tcl list, each element of which is a list of all column values +in a row of the result of SQL query sql. If +sql doesn't return any rows, returns an empty list. (Analogous to database_to_tcl_list_list.) - - -db_dml - --db_dml statement-name sql \ - [ -bind bind_set_id | -bind bind_value_list ] \ - [ -blobs blob_list | -clobs clob_list | - -blob_files blob_file_list | -clob_files clob_file_list ] - -Performs the DML or DDL statement sql. -If a length-n list of blobs or clobs is provided, then the SQL -should return n blobs or clobs into the bind variables -:1, :2, ... :n. -blobs or clobs, if specified, + db_list_of_ns_sets +db_list_of_ns_sets statement-name sql [ -bind bind_set_id | -bind bind_value_list ] + + Returns a list of ns_sets with the values of each column of each row + returned by the sql query specified. + db_dml +db_dml statement-name sql \ + [ -bind bind_set_id | -bind bind_value_list ] \ + [ -blobs blob_list | -clobs clob_list | + -blob_files blob_file_list | -clob_files clob_file_list ] + Performs the DML or DDL statement sql. If a length-n list of blobs or clobs is provided, then the SQL +should return n blobs or clobs into the bind variables +:1, :2, ... :n. +blobs or clobs, if specified, should be a list of individual BLOBs or CLOBs to insert; -blob_files or clob_files, if -specified, should be a list of paths to files containing the data to +blob_files or clob_files, if +specified, should be a list of paths to files containing the data to insert. Only one of -blobs, -clobs, --blob_files, and -clob_files may be provided. -Example: -+-blob_files, and -clob_files may be provided. Example: 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"] - - + This inserts a new row into the photos table, with the contents of the files /var/tmp/the_photo and /var/tmp/the_thumbnail in the image and thumbnail columns, respectively. - - - -db_write_clob, -db_write_blob, -db_blob_get_file - - --db_write_clob statement-name sql [ -bind bind_set_id | -bind bind_value_list ] + +db_write_clob, +db_write_blob, +db_blob_get_file + +db_write_clob statement-name sql [ -bind bind_set_id | -bind bind_value_list ] -db_write_blob statement-name sql [ -bind bind_set_id | -bind bind_value_list ] +db_write_blob statement-name sql [ -bind bind_set_id | -bind bind_value_list ] -db_blob_get_file statement-name sql [ -bind bind_set_id | -bind bind_value_list ] - -Analagous to ns_ora write_clob/write_blob/blob_get_file. +db_blob_get_file statement-name sql [ -bind bind_set_id | -bind bind_value_list ] + Analagous to ns_ora write_clob/write_blob/blob_get_file. - - -db_release_unused_handles - --db_release_unused_handles - -Releases any allocated, unused database handles. - -db_transaction - --db_transaction code_block [ on_error { code_block } ] - -Executes code_block transactionally. Nested + db_release_unused_handles +db_release_unused_handles + Releases any allocated, unused database handles. db_transaction +db_transaction code_block [ on_error { code_block } ] + Executes code_block transactionally. Nested transactions are supported (end transaction is transparently ns_db dml'ed when the outermost transaction completes). The db_abort_transaction command can be used to abort all levels of transactions. It is possible to specify an optional on_error -code block that will be executed if some code in code_block throws +code block that will be executed if some code in code_block throws an exception. The variable errmsg will be bound in that scope. -If there is no on_error code, any errors will be propagated. -Example: -+If there is no on_error code, any errors will be propagated. Example: proc replace_the_foo { col } { db_transaction { @@ -812,30 +540,84 @@ print_the_foo ; # Writes out "foo is 8" - - -db_resultrows - --db_resultrows - -Returns the number of rows affected or returned by the previous + db_abort_transaction + +db_abort_transaction + 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 +db_dml "abort" "abort transaction". + + + db_multirow +db_multirow [ -local ] [ -append ] [ -extend column_list ] \ + var-name statement-name sql \ + [ -bind bind_set_id | -bind bind_value_list ] \ + code_block [ if_no_rows if_no_rows_block ] + + Performs the SQL query sql, saving results in variables + of the form + var_name:1, var_name:2, etc, + setting var_name:rowcount to the total number + of rows, and setting var_name:columns to a + list of column names. + + Each row also has a column, rownum, automatically + added and set to the row number, starting with 1. Note that this will + override any column in the SQL statement named 'rownum', also if you're + using the Oracle rownum pseudo-column. + + If the -local is passed, the variables defined + by db_multirow will be set locally (useful if you're compiling dynamic templates + in a function or similar situations). + + You may supply a code block, which will be executed for each row in + the loop. This is very useful if you need to make computations that + are better done in Tcl than in SQL, for example using ns_urlencode + or ad_quotehtml, etc. When the Tcl code is executed, all the columns + from the SQL query will be set as local variables in that code. Any + changes made to these local variables will be copied back into the + multirow. + + You may also add additional, computed columns to the multirow, using the + -extend { col_1 col_2 ... } switch. This is + useful for things like constructing a URL for the object retrieved by + the query. + + If you're constructing your multirow through multiple queries with the + same set of columns, but with different rows, you can use the + -append switch. This causes the rows returned by this query + to be appended to the rows already in the multirow, instead of starting + a clean multirow, as is the normal behavior. The columns must match the + columns in the original multirow, or an error will be thrown. + + Your code block may call continue in order to skip a row + and not include it in the multirow. Or you can call break + to skip this row and quit looping. + + + Notice the nonstandard numbering (everything + else in Tcl starts at 0); the reason is that the graphics designer, a non + programmer, may wish to work with row numbers. + + Example: + +db_multirow -extend { user_url } users users_query { + select user_id first_names, last_name, email from cc_users +} { + set user_url [acs_community_member_url -user_id $user_id] +} + db_resultrows +db_resultrows + Returns the number of rows affected or returned by the previous statement. - - -db_with_handle - --db_with_handle var code_block - -Places a database handle into the variable var and -executes code_block. This is useful when you don't + db_with_handle +db_with_handle var code_block + Places a database handle into the variable var and +executes code_block. This is useful when you don't want to have to use the new API (db_foreach, -db_1row, etc.), but need to use database handles explicitly. -Example: -+db_1row, etc.), but need to use database handles explicitly. Example: proc lookup_the_foo { foo } { db_with_handle db { @@ -853,71 +635,102 @@ } } - - -db_nullify_empty_string - --db_nullify_empty_string string - -For true SQL purists, we provide the convenience function -db_nullify_empty_string, which returns -[db_null] if its string argument is the empty string -and can be used to encapsulate another Oracle quirk: -- -set baz "" - -# Clean out the foo table -# -db_dml unused "delete from foo" - -db_dml unused "insert into foo(baz) values('$baz')" - -set n_rows [db_string unused "select count(*) from foo where baz is null"] -# -# $n_rows is 1; in effect, the "baz is null" criterion is matching -# the empty string we just inserted (because of Oracle's coercion -# quirk) - - - -To balance out this asymmetry, you can explicitly set baz to -null by writing: - -- -db_dml foo_insert "insert into foo(baz) values(:1)" {[db_nullify_empty_string $baz]} - - - - - ($Id$) - -

- - - - - - - - - - - - - - -Prev Home Next - OpenACS 4 Request Processor Design Up Documenting Tcl Files: Page Contracts and Libraries - - - rmello at fslc.usu.edu - - + + + + db_name + + + + + db_name + + + Returns the name of the database, as returned by the driver. + + + + db_type + + + + + db_type + + + Returns the RDBMS type (i.e. oracle, postgresql) this OpenACS installation is + using. The nsv ad_database_type is set up during the bootstrap process. + + + + db_compatible_rdbms_p + + + + db_compatible_rdbms_p db_type + + Returns 1 if the given db_type is compatible with the current RDBMS. + + + + db_package_supports_rdbms_p + + + + db_package_supports_rdbms_p db_type_list + + Returns 1 if db_type_list contains the current RDMBS type. A package + intended to run with a given RDBMS must note this in it's package info + file regardless of whether or not it actually uses the database. + + + + db_legacy_package_p + + + + db_legacy_package_p db_type_list + + Returns 1 if the package is a legacy package. We can only tell for certain if + it explicitly supports Oracle 8.1.6 rather than the OpenACS more general oracle. + + + + db_version + + + + db_version + + Returns the RDBMS version (i.e. 8.1.6 is a recent Oracle version; 7.1 a + recent PostgreSQL version. + + + + db_current_rdbms + + + + db_current_rdbms + + Returns the current rdbms type and version. + + + + db_known_database_types + + + + db_known_database_types + + Returns a list of three-element lists describing the database engines known + to OpenACS. Each sublist contains the internal database name (used in file + paths, etc), the driver name, and a "pretty name" to be used in selection + forms displayed to the user. + + The nsv containing the list is initialized by the bootstrap script and should + never be referenced directly by user code. + Returns the current rdbms type and version. + ($Id$)

-The OpenACS Database Access API

+The OpenACS Database Access API

Prev	Chapter 4. OpenACS Developer's Guide	Next

The OpenACS Database Access API

By Pete Su and Jon Salz. Modified by Roberto Mello. -

-Overview

Overview

-The Old Way

+ More detailed information about the DB api is available at + Database Access API. +

The Old Way

Here's a typical block of code from an OpenACS 3.x dynamic page: -

+    
 set tcl_var "foo"
 
 set db [ns_db gethandle]
@@ -74,47 +42,33 @@
 }
 
 ns_db releasehandle $db
-    
-
+

Writing code like this had the following annoyances: -

+
- It was repetitive, tedious and error prone to write the same type of loops over and over again. -
- +
- 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. -
- +
- Magic like set_variables_after_query made code confusing. -
- +
- The scope of transactions is not clear from reading the code. -
- +
- 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. -
+

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. -

-The New Way

The New Way

Here is how you would code up the example above using the new API. -

+    
 set count 0 
 
 set tcl_var "foo"
@@ -136,82 +90,62 @@
             	incr count
         }
 }
-    
-
+

There are several things to note here: -

+
1. No explicit code for grabbing and releasing handles. Usage of the Database API implicitly deals with all handle management issues. -
2. +
3. The new command db_transaction makes the scope of a transaction clear. db_transaction takes the code block argument and automatically runs it in the context of a transaction. -
4. +
5. The new command db_foreach writes our old while loop for us. -
6. +
7. Every SQL query has a name, meant to be unique within the server instance (though this is not enforced). -
8. +
9. Finally and most importantly, there is a new scheme for passing data from a Tcl variable to the database, which we'll cover next. -
+

-Bind Variables

Bind Variables

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: -

 select 
     foo, 
     bar, 
     baz 
 from some_table, some_other_table
 where some_table.id=some_other_table.id  
 and some_table.condition_p = 'foo'
-

There are a few problems with this: -

+
1. If the literal value is a huge string, then we waste a lot of time in the database server doing useless parsing. -
2. +
3. 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. -
4. -
  +
5. 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. -
  -
  +
  This type of attack, - called SQL smuggling, can be very + called SQL smuggling, 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 +156,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. -
  -
-
+

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: -

 select 
     foo, 
     bar, 
     baz 
 from some_table, some_other_table
 where some_table.id = some_other_table.id
 and some_table.condition_p = ?
-

The '?' character means "This will be filled in later with literal data". In use, you might write code that looks like this: -

+    
 set statement [prepare_query "
     		select 
         		foo, 
@@ -255,93 +183,73 @@
 	       "]
 
 [bind_param $statement 1 $tcl_var]
-    
-
+

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 bind values to the + to the server for parsing, then later we bind values to the placeholders, and send those values along seperately. This seperate - binding step is where the term bind variable comes from. -

+ binding step is where the term bind variable comes from. +

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. -

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: -

 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
-

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. -

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: -

 set table "baz"
 set condition "where foo = bar"
 
 db_foreach my_query { select :table from some_table where :condition }
-

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 not the same thing at all. -

+ interpolation in Tcl, it is not the same thing at all. +

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. -

-Usage

Every db_* command accepting a SQL command as an argument - supports bind variables. You can either

+
Usage
Every db_* command accepting a SQL command as an argument + supports bind variables. You can either
- Specify the -bind switch to provide a set with bind variable values, or -
- +
- Specify the -bind switch to explicitly provide a list of bind variable names and values, or -
- +
- Not specify a bind variable list at all, in which case Tcl variables are used as bind variables. -
-
+

The default behavior (i.e., if the -bind switch is omitted) is that these procedures expect to find local variables that correspond in name to the referenced bind variables, e.g.: -

+      
 
 set user_id 123456
 set role "administrator"
@@ -357,14 +265,11 @@
     # of "administrator"
 }
 
-      
-
+

The value of the local Tcl variable user_id (123456) is bound to the user_id bind variable. -

The -bind switch can takes the name of an ns_set - containing keys for each bind variable named in the query, e.g.:

+      
The -bind switch can takes the name of an ns_set
+	containing keys for each bind variable named in the query, e.g.:
 
 set bind_vars [ns_set create]
 ns_set put $bind_vars user_id 123456
@@ -381,12 +286,10 @@
     # of "administrator"
 }
 
-      
-
+

Alternatively, as an argument to -bind you can specify a list of alternating name/value pairs for bind variables: -

+      
 	
 db_foreach user_group_memberships_by_role {
     select g.group_id, g.group_name
@@ -399,26 +302,18 @@
     # of "administrator"
 }
 
-      
-

-Nulls and Bind Variables

Nulls and Bind Variables

When processing a DML statement, Oracle coerces empty strings into - null. (This coercion does not occur in the + null. (This coercion does not occur in the WHERE clause of a query, i.e. col = '' and col is null are not equivalent.) -

As a result, when using bind variables, the only way to make Oracle set a +

As a result, when using bind variables, the only way to make Oracle set a column value to null 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".

These Oracle quirks complicate the process of writing clear and abstract - DML difficult. Here is an example that illustrates why:

+	"null".
These Oracle quirks complicate the process of writing clear and abstract
+	DML difficult. Here is an example that illustrates why:
 
 #
 # Given the table:
@@ -438,19 +333,15 @@
 # null, because Oracle has coerced the empty string (even for the
 # numeric column "bar") into null in both cases
 
-      
-
+

Since databases other than Oracle do not coerce empty strings into null, 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. -

Therefore, the Database Access API provides a database-independent way to +

Therefore, the Database Access API provides a database-independent way to represent null (instead of the Oracle-specific idiom of the - empty string): db_null.

Use it instead of the empty string whenever you want to set a column value - explicitly to null, e.g.:

+	empty string): db_null.
Use it instead of the empty string whenever you want to set a column value
+	explicitly to null, e.g.:
 
 set bar [db_null]
 set baz [db_null]
@@ -459,13 +350,7 @@
 #
 # sets the values for both the "bar" and "baz" columns to null
 
-      
-

-Sequence Pooling

Sequence Pooling

The database library can transparently maintain pools of sequence values, so that each request for a new sequence value (using db_nextval) does not incur a roundtrip to the server. For instance, this functionality is @@ -474,324 +359,291 @@ functionality for a particular sequence, register the sequence to be pooled, either using the db_register_pooled_sequence procedure at server startup time, or by including a configuration parameter of the form -

 
-PoolSequence.sequence_name_seq=count
+PoolSequence.sequence_name_seq=count
 
-

- in any configuration section in the yourservername.ini +

+ in any configuration section in the yourservername.ini file, e.g., e.g., -

+    
 
-[ns/server/yourservername/acs/security]
+[ns/server/yourservername/acs/security]
 PoolSequence.sec_id_seq=20
 
-    
-
+

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 PooledSequenceUpdateInterval parameter in the [ns/server/ - yourservername + yourservername /acs/database] configuration section.) -

-Basic API

Basic API

The Database API has several functions that wrap familiar parts of the AOLserver database API. -

Note that you never have to use ns_db anymore (including ns_db gethandle)! Just start doing stuff, and (if you want) call db_release_unused_handles when you're done as a hint to release the database handle. -

+ db_abort_transaction - - - +

 db_abort_transaction
-

Aborts all levels of a transaction. That is if this is called within +

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 db_dml "abort" "abort transaction". -

+

db_multirow

+db_multirow [ -local ] [ -append ] [ -extend column_list ] \
+    var-name statement-name sql \
+    [ -bind bind_set_id | -bind bind_value_list ] \
+    code_block [ if_no_rows if_no_rows_block ]
+

+ Performs the SQL query sql, saving results in variables + of the form + var_name:1, var_name:2, etc, + setting var_name:rowcount to the total number + of rows, and setting var_name:columns to a + list of column names. +

+ Each row also has a column, rownum, automatically + added and set to the row number, starting with 1. Note that this will + override any column in the SQL statement named 'rownum', also if you're + using the Oracle rownum pseudo-column. +

+ If the -local is passed, the variables defined + by db_multirow will be set locally (useful if you're compiling dynamic templates + in a function or similar situations). +

+ You may supply a code block, which will be executed for each row in + the loop. This is very useful if you need to make computations that + are better done in Tcl than in SQL, for example using ns_urlencode + or ad_quotehtml, etc. When the Tcl code is executed, all the columns + from the SQL query will be set as local variables in that code. Any + changes made to these local variables will be copied back into the + multirow. +

+ You may also add additional, computed columns to the multirow, using the + -extend { col_1 col_2 ... } switch. This is + useful for things like constructing a URL for the object retrieved by + the query. +

+ If you're constructing your multirow through multiple queries with the + same set of columns, but with different rows, you can use the + -append switch. This causes the rows returned by this query + to be appended to the rows already in the multirow, instead of starting + a clean multirow, as is the normal behavior. The columns must match the + columns in the original multirow, or an error will be thrown. +

+ Your code block may call continue in order to skip a row + and not include it in the multirow. Or you can call break + to skip this row and quit looping. +

+ + Notice the nonstandard numbering (everything + else in Tcl starts at 0); the reason is that the graphics designer, a non + programmer, may wish to work with row numbers. +

+ Example: +

+db_multirow -extend { user_url } users users_query {
+    select user_id first_names, last_name, email from cc_users
+} {
+    set user_url [acs_community_member_url -user_id $user_id]
+}
+

db_null -

+	 db_null
-	  
-
+

Returns a value which can be used in a bind variable to represent the SQL value null. See Nulls and Bind Variables above. -

+

db_foreach -

-db_foreach statement-name sql [ -bind bind_set_id | -bind bind_value_list ] \
-    [ -column_array array_name | -column_set set_name ] \
-    code_block [ if_no_rows if_no_rows_block ]
-

- Performs the SQL query +

+db_foreach statement-name sql [ -bind bind_set_id | -bind bind_value_list ] \
+    [ -column_array array_name | -column_set set_name ] \
+    code_block [ if_no_rows if_no_rows_block ]
+

+ Performs the SQL query sql - , executing - code_block - once for each row + , executing + code_block + once for each row with variables set to column values (or a set or array populated if -column_array or column_set is specified). If the query returns no rows, executes - if_no_rows_block - (if provided). -

Example:

+	    if_no_rows_block
+	       (if provided).
+	  
Example:
 
 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"
 }
 
-	  
-
+

The code block may contain break statements (which terminate the loop and flush the database handle) and continue statements - (which continue to the next row of the loop).

+ (which continue to the next row of the loop).

db_1row -

-db_1row statement-name sql [ -bind bind_set_id | -bind bind_value_list ] \
-    [ -column_array array_name | -column_set set_name ]
-

- Performs the SQL query - sql, +

+db_1row statement-name sql [ -bind bind_set_id | -bind bind_value_list ] \
+    [ -column_array array_name | -column_set set_name ]
+

+ Performs the SQL query + sql, setting variables to column values. Raises an error if the query does not return exactly 1 row. -

Example:

 
 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.
 
-

+

db_0or1row -

-db_0or1row statement-name sql [ -bind bind_set_id | -bind bind_value_list ] \
-    [ -column_array array_name | -column_set set_name ]
-

+db_0or1row statement-name sql [ -bind bind_set_id | -bind bind_value_list ] \
+    [ -column_array array_name | -column_set set_name ]
+

Performs the SQL query - sql. + sql. 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. -

db_nextval

-db_nextval sequence-name
-

- Returns the next value for the sequence sequence-name (using a +

db_nextval

+db_nextval sequence-name
+

+ Returns the next value for the sequence sequence-name (using a SQL statement like SELECT - sequence-name.nextval FROM + sequence-name.nextval FROM DUAL). 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 Sequence Pooling). -

-

- + (see Sequence Pooling). + db_register_pooled_sequence - - --db_register_pooled_sequence sequence-name pool-size - -Registers the sequence sequence-name to be pooled, with a pool - size of pool-size sequence values - (see Sequence Pooling). + +db_register_pooled_sequence sequence-name pool-size + Registers the sequence sequence-name to be pooled, with a pool + size of pool-size sequence values + (see Sequence Pooling). - - -db_string - --db_string statement-name sql [ -default default ] [ -bind bind_set_id | -bind bind_value_list ] - -Returns the first column of the result of SQL query - sql. - If sql doesn't return a + db_string +db_string statement-name sql [ -default default ] [ -bind bind_set_id | -bind bind_value_list ] + Returns the first column of the result of SQL query + sql. + If sql doesn't return a row, returns - default + default (or throws an error if - default is unspecified). Analogous to + default is unspecified). Analogous to database_to_tcl_string and database_to_tcl_string_or_null. - - -db_list - --db_list statement-name sql [ -bind bind_set_id | -bind bind_value_list ] - -Returns a Tcl list of the values in the first column of the result of SQL + db_list +db_list statement-name sql [ -bind bind_set_id | -bind bind_value_list ] + Returns a Tcl list of the values in the first column of the result of SQL query - sql. - If sql doesn't + sql. + If sql doesn't return any rows, returns an empty list. Analogous to database_to_tcl_list. - - -db_list_of_lists - --db_list_of_lists statement-name sql [ -bind bind_set_id | -bind bind_value_list ] - -Returns a Tcl list, each element of which is a list of all column values - in a row of the result of SQL query sql. If - sql doesn't return any rows, returns an empty list. + db_list_of_lists +db_list_of_lists statement-name sql [ -bind bind_set_id | -bind bind_value_list ] + Returns a Tcl list, each element of which is a list of all column values + in a row of the result of SQL query sql. If + sql doesn't return any rows, returns an empty list. (Analogous to database_to_tcl_list_list.) - - -db_dml - --db_dml statement-name sql \ - [ -bind bind_set_id | -bind bind_value_list ] \ - [ -blobs blob_list | -clobs clob_list | - -blob_files blob_file_list | -clob_files clob_file_list ] - -Performs the DML or DDL statement sql. -If a length-n list of blobs or clobs is provided, then the SQL - should return n blobs or clobs into the bind variables - :1, :2, ... :n. - blobs or clobs, if specified, + db_dml +db_dml statement-name sql \ + [ -bind bind_set_id | -bind bind_value_list ] \ + [ -blobs blob_list | -clobs clob_list | + -blob_files blob_file_list | -clob_files clob_file_list ] + Performs the DML or DDL statement sql. If a length-n list of blobs or clobs is provided, then the SQL + should return n blobs or clobs into the bind variables + :1, :2, ... :n. + blobs or clobs, if specified, should be a list of individual BLOBs or CLOBs to insert; - blob_files or clob_files, if - specified, should be a list of paths to files containing the data to + blob_files or clob_files, if + specified, should be a list of paths to files containing the data to insert. Only one of -blobs, -clobs, - -blob_files, and -clob_files may be provided. -Example: -+ -blob_files, and -clob_files may be provided. Example: 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"] - - + This inserts a new row into the photos table, with the contents of the files /var/tmp/the_photo and /var/tmp/the_thumbnail in the image and thumbnail columns, respectively. - - - + db_write_clob, db_write_blob, db_blob_get_file - - --db_write_clob statement-name sql [ -bind bind_set_id | -bind bind_value_list ] + +db_write_clob statement-name sql [ -bind bind_set_id | -bind bind_value_list ] -db_write_blob statement-name sql [ -bind bind_set_id | -bind bind_value_list ] +db_write_blob statement-name sql [ -bind bind_set_id | -bind bind_value_list ] -db_blob_get_file statement-name sql [ -bind bind_set_id | -bind bind_value_list ] - -Analagous to ns_ora write_clob/write_blob/blob_get_file. +db_blob_get_file statement-name sql [ -bind bind_set_id | -bind bind_value_list ] + Analagous to ns_ora write_clob/write_blob/blob_get_file. - - -db_release_unused_handles - -+ db_release_unused_handles db_release_unused_handles - -Releases any allocated, unused database handles. - -db_transaction - --db_transaction code_block [ on_error { code_block } ] - -Executes code_block transactionally. Nested + Releases any allocated, unused database handles. db_transaction +db_transaction code_block [ on_error { code_block } ] + Executes code_block transactionally. Nested transactions are supported (end transaction is transparently ns_db dml'ed when the outermost transaction completes). The db_abort_transaction command can be used to abort all levels of transactions. It is possible to specify an optional on_error - code block that will be executed if some code in code_block throws + code block that will be executed if some code in code_block throws an exception. The variable errmsg will be bound in that scope. - If there is no on_error code, any errors will be propagated. -Example: -+ If there is no on_error code, any errors will be propagated. Example: proc replace_the_foo { col } { db_transaction { @@ -820,30 +672,18 @@ print_the_foo ; # Writes out "foo is 8" - - -db_resultrows - -+ db_resultrows db_resultrows - -Returns the number of rows affected or returned by the previous + Returns the number of rows affected or returned by the previous statement. - - -db_with_handle - --db_with_handle var code_block - -Places a database handle into the variable var and - executes code_block. This is useful when you don't + db_with_handle +db_with_handle var code_block + Places a database handle into the variable var and + executes code_block. This is useful when you don't want to have to use the new API (db_foreach, - db_1row, etc.), but need to use database handles explicitly. -Example: -+ db_1row, etc.), but need to use database handles explicitly. Example: proc lookup_the_foo { foo } { db_with_handle db { @@ -861,24 +701,18 @@ } } - - - + db_nullify_empty_string - - --db_nullify_empty_string string - -For true SQL purists, we provide the convenience function + +db_nullify_empty_string string + For true SQL purists, we provide the convenience function db_nullify_empty_string, which returns - [db_null] if its string argument is the empty string - and can be used to encapsulate another Oracle quirk: -+ [db_null] if its string argument is the empty string + and can be used to encapsulate another Oracle quirk: set baz "" @@ -894,46 +728,15 @@ # the empty string we just inserted (because of Oracle's coercion # quirk) - - + To balance out this asymmetry, you can explicitly set baz to null by writing: - -+ db_dml foo_insert "insert into foo(baz) values(:1)" {[db_nullify_empty_string $baz]} - - -

- - ($Id$) - -

-

- - - - - - - - - - - - - - -Prev Home Next - The Request Processor Up Using Templates in OpenACS 4.5 - - - rmello at fslc.usu.edu - - + + ($Id$) +

-Prev	Part Part III. For OpenACS Developers	Next -

Prev	Part Part III. For OpenACS Developers	Next

-Overview

A tour of what you need to know in order to extend OpenACS.

Overview

A tour of what you need to know in order to extend OpenACS.

-OpenACS Documentation Guide

+OpenACS Documentation Guide

Prev	Chapter 6. Engineering Standards	Next

OpenACS Documentation Guide

By claus@arsdigita.com, with additions by Roberto Mello and the OpenACS Community -

-Overview of OpenACS 4.5 Documentation

Overview of OpenACS 4.5 Documentation

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 + upon. Some sections of the documentation, however, lack details + and examples; others are simply nonexistant. Our goal is to give OpenACS a superb documentation, so that users, developers and administrators of OpenACS installations can enjoy the system. -

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. -

The documentation for OpenACS™ is written using DocBook XML. The reasons why we are using DocBook are explained in more details in the Why DocBook? section. I will add the reasons why we are using Docbook XML instead of Docbook SGML: -

-Consistency. We already have a bunch of +
- Consistency. 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). -
- -It does not require extra - effort. Writing in XML is almost identical to +
- It does not require extra + effort. Writing in XML is almost identical to SGML, with a couple extra rules. More details in the LDP Author Guide. -
-

-Why DocBook?

Why DocBook?

In order to separate content and presentation, all OpenACS documentation will be marked up to conform to the DocBook XML DTD - + 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. -

Theoretically any strict DTD would have been sufficient - we could even write our own. But DocBook has been around for a while (since early 90's), 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 tools are available for editing and publishing DocBook documents. -

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 list of elements 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 as long as you remember to: - -

+ the same elements are valid in the XML DTD as long as you remember to: + +
- Always close your tags with corresponding end-tags and to - not use other tag minimization -
- + not use other tag minimization +
- Write all elements and attributes in lowercase -
- +
- Quote all attributes -
-

-Tools

Tools

You are going to need the following to work with the OpenACS Docbook XML documentation: -

-Docbook XML +
- Docbook XML DTD - 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. -
- -XSL +
- XSL Stylesheets (docbook-xsl) - The stylesheets to convert to HTML. We have been using a stylesheet based upon NWalsh's chunk.xsl. -
- -xsltproc - The processor that +
- xsltproc - 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 xmlsoft.org. -
- +
- Some editing tool. A popular one is Emacs with the psgml mode. We have a intro to the PSGML Mode in Emacs as part of our documentation. You can read about other editing tools in the LDP Author Guide. -
-

-Writing New Docs

Writing New Docs

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. -

You can look at some templates for documents (in Docbook XML) in the sources - for acs-core-docs, especially the - Detailed Design Documentation Template and the - System/Application Requirements Template. -

-Document Structure

+ for acs-core-docs, especially the + Detailed Design Documentation Template and the + System/Application Requirements Template. +

Document Structure

The documentation for each package will make up a little "book" that is structured like this - - examples are emphasized: + - examples are emphasized: - + -

-    book                        : Docs for one package - templating
+    
+    book                        : Docs for one package - templating
      |
-     +--chapter                 : One section - for developers
+     +--chapter                 : One section - for developers
          |
 ---------+------------------------------------------------------
          |
-         +--sect1               : Single document - requirements
+         +--sect1               : Single document - requirements
              |
-             +--sect2           : Sections - functional requirements
+             +--sect2           : Sections - functional requirements
                  |
-                 +--sect3       : Subsections - Programmer's API
+                 +--sect3       : Subsections - Programmer's API
                      |
-                    ...         : ...
-    
-
+                    ...         : ...
+

The actual content is split up into documents that start at a sect1-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.

For now you can take a look at the + and we will provide a set of templates for documenting an entire package.

For now you can take a look at the sources of these DocBook documents to get an idea of how they are tied together. -

-Headlines, Sections

- +

Headlines, Sections

+ Given that your job starts at the sect1-level, all your documents should open with a <sect1>-tag and end with the corresponding </sect1>. -

- +

+ You need to feed every <sect1> two attributes. The first attribute, id, 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 the section called “Links”). The value of id has to be unique throughout the book you're making since the id's in your sect1's will turn into filenames when the book is parsed into HTML. -

- +

+ The other attribute is xreflabel. The value of this is the text that will appear as the link when referring to this sect1. -

Right after the opening tag you put the title of the document - this is usually the same as xreflabel-attribute. E.g. the top level of the document you're reading right now looks like this: -

+    
       <sect1 id="docbook-primer" xreflabel="aD DocBook Primer">
       <title>aD DocBook Primer</title>
 
       ...
 
       </sect1>
-    
-
-      
+

+ Inside this container your document will be split up into <sect2>'s, each with the same requirements - id and xreflabel attributes, and a <title>-tag inside. Actually, the xreflabel is never required in sections, but it makes linking to that section a lot easier. -

When it comes to naming your sect2's and below, prefix them with some abbreviation of the id in the sect1 such as requirements-overview. -

-Code

- +

Code

+ 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 <computeroutput>. This takes the place of the HTML-tag <code> -

For bigger chunks of code such as SQL-blocks, the tag <programlisting> is used. Just wrap your code block in it; mono-spacing, indents and all that stuff is taken care of automatically. -

-Links

- +

Links

+ Linking falls into two different categories: inside the book you're making and outside: -

1. Inside linking, cross-referencing other parts of your book

By having unique id's you can cross-reference any part of your book with a simple tag, regardless of where that part is. -

-Check out how I link to a subsection of the Developer's Guide:

+	  
Check out how I link to a subsection of the Developer's Guide:
 
 	    Put this in your XML:
 
@@ -294,21 +188,14 @@
 	    - Find information about creating a package in 
 	    Making a Package
 
-	  
-
+

Note that even though this is an empty tag, you have to either: -

+
1. Provide the end-tag, </xref>, or -
2. +
3. Put a slash before the ending-bracket: <xref linkend="blahblah"/> -
-
If the section you link to hasn't a specified xreflabel-attribute, - the link is going to look like this:
-
```
+	      
```

If the section you link to hasn't a specified xreflabel-attribute, + the link is going to look like this:

 
 	    Put this in your XML:
 
@@ -321,51 +208,33 @@
 	    - Find information about what a package looks like in 
 	    the section called “What a Package Looks Like”
 
-

Note that since I haven't provided an xreflabel for the subsection, packages-looks, the parser will try its best to explain where the link takes you. -

2. Linking outside the documentation

- +

2. Linking outside the documentation

+ If you're hyper-linking out of the documentation, it works almost the same way as HTML - the tag is just a little different (<ulink>): -

<ulink url="http://www.oracle.com/">Oracle Corporation</ulink>

<ulink url="http://www.oracle.com/">Oracle Corporation</ulink>

....will create a hyper-link to Oracle in the HTML-version of the documentation. -

-NOTE: Do NOT use ampersands in your hyper links. These are reserved for referencing +

NOTE: Do NOT use ampersands in your hyper links. These are reserved for referencing entities, which is exactly how you'll make an ampersand: & -

-Graphics

- NOTE: Currently this section currently only takes HTML-output into consideration - - not a printed version -

- - Another Note: Also, it's still not a 100 percent sure that this is how we are going to +

Graphics

+ NOTE: Currently this section currently only takes HTML-output into consideration - + not a printed version +

+ + Another Note: 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 ;) - -

- + +

+ To insert a graphic we use the elements <mediaobject>, <imageobject>, @@ -375,8 +244,7 @@ and one for print (EPS). Finally you should provide a brief description wrapped in <textobject> - in HTML this will be the ALT text. -

+    
       <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>
-    
-
+

Put your graphics in a separate directory ("images") and link to them only with relative paths. -

-Lists

- +

Lists

+ Here's how you make the DocBook equivalent of the three usual HTML-lists: -

1. How to make an <ul>

Making an unordered list is pretty much like doing the same thing in HTML - if you close your <li>, that is. The only differences are that each list item has to be wrapped in something more, such as <para>, and that the tags are called <itemizedlist> and <listitem>: -

+	  
 	    <itemizedlist>
 	    
 	    <listitem><para>Stuff goes here</para><listitem>
 	    <listitem><para>More stuff goes here</para><listitem>
 
 	    </itemizedlist>
-	  
-

2. How to make an <ol>

The ordered list is like the preceding, except that you use - <orderedlist> instead:

+	    <orderedlist> instead:
 	    <orderedlist>
 	    
 	    <listitem><para>Stuff goes here</para><listitem>
 	    <listitem><para>More stuff goes here</para><listitem>
 
 	    </orderedlist>
-	  
-

3. How to make a <dl>

This kind of list is called a variablelist and these are the tags you'll need to make it happen: <variablelist>, <varlistentry>, <term> and - <listitem>:

+	    <listitem>:
 	    <variablelist>
 	    
 	    <varlistentry>
@@ -457,20 +304,12 @@
 	    </varlistentry>
 
 	    </variablelist>
-	  
-

-Tables

- +

Tables

+ DocBook supports several types of tables, but in most cases, the <informaltable> is enough: -

+    
       <informaltable frame="all">
       <tgroup cols="3">
       <tbody>
@@ -496,218 +335,92 @@
       </tbody>
       </tgroup>
       </informaltable>
-    
-
+

With our current XSL-style-sheet, the output of the markup above will be a simple HTML-table: -

----- - - - - - - - - - - - - - - - - - -

a1 b1 c1
a2 b2 c2
a3 b3 c3

a1 b1 c1
a2 b2 c2
a3 b3 c3

If you want cells to span more than one row or column, it gets a bit more complicated - check out <table> for an example. -

-Emphasis

- +

Emphasis

+ Our documentation uses two flavors of emphasis - italics and bold type. DocBook uses one - <emphasis>. -

The <emphasis> tag defaults to italics when parsed. If you're looking for emphasizing with bold type, use <emphasis role="strong">. -

-Indexing Your DocBook Documents

Indexing Your DocBook Documents

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. -

Use <indexterm>, <primary> and <secondary> for this. See these links for an explanation. -

-Converting to HTML

Note

Converting to HTML

Note

This section is quoted almost verbatim from the LDP Author Guide. -

Once you have the Docbook Tools installed, you can convert your xml documents to HTML (or other formats. Let me know if you are able to convert to other formats). -

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. -

To generate a single HTML file from your DocBook XML file, use the command: -

 bash$  xsltproc -o outputfilename.xml /usr/share/sgml/docbook/stylesheet/xsl/nwalsh/html/html.xsl filename.xml
-

Note

- This example uses Daniel Veillard's xsltproc command available +

Note

+ This example uses Daniel Veillard's xsltproc command available as part of libxslt from http://www.xmlsoft.org/XSLT/. If you are using other XML processors such as Xalan or Saxon, you will need to change the command line appropriately. -

To generate a set of linked HTML pages, with a separate page for each <chapter>, <sect1> or <appendix> tag, use the following command: -

 bash$  xsltproc /usr/share/sgml/docbook/stylesheet/xsl/nwalsh/html/chunk.xsl filename.xml
-

-Further Reading

-Revision History

------ - - - - - - - - - -

Document Revision #

Action Taken, Notes

When?

By Whom?

0.3

Revision History

- - - - - - - - - - - - - - - - -

Document Revision #	Action Taken, Notes	When?	By Whom?
0.4	+ Fixed some typos. +	8/3/2002	Vinod Kurup
0.3	Added OpenACS information, updated tools, added extra links and added info to the Publishing section. -	12/24/2001	Roberto Mello
0.2	Changed recommendation from <phrase> to <emphasis role="strong">	01/19/2000	Claus Rasmussen
0.1	Creation	12/2000	Claus Rasmussen

- -

- - - - - - - - - - - -

-Prev	Home	Next -
Chapter 6. Engineering Standards	Up	Using PSGML mode in Emacs

- rmello at fslc.usu.edu -

12/24/2001

Roberto Mello

0.2

Changed recommendation from <phrase> to <emphasis role="strong">

01/19/2000

Claus Rasmussen

0.1

Creation

12/2000

Claus Rasmussen

Prev	Home	Next
Chapter 6. Engineering Standards	Up	Using PSGML mode in Emacs

rmello at fslc.usu.edu

- - +

Index: openacs.org-dev/packages/acs-core-docs/www/eng-standards-constraint-naming.html =================================================================== RCS file: /usr/local/cvsroot/openacs.org-dev/packages/acs-core-docs/www/eng-standards-constraint-naming.html,v diff -u -r1.1.1.1 -r1.1.1.2 --- openacs.org-dev/packages/acs-core-docs/www/eng-standards-constraint-naming.html 9 Jul 2002 17:34:57 -0000 1.1.1.1 +++ openacs.org-dev/packages/acs-core-docs/www/eng-standards-constraint-naming.html 11 Aug 2002 00:42:48 -0000 1.1.1.2 @@ -1,124 +1,34 @@ - - - -Constraint naming standard - - - - - - - - -

- - - -

-Prev	Chapter 6. Engineering Standards	Next -

-Constraint naming standard

By mbryzek@arsdigita.com -

-The Big Picture

+Constraint naming standard

Prev	Chapter 6. Engineering Standards	Next

Constraint naming standard

By mbryzek@arsdigita.com

+ OpenACS docs are written by the named authors, but may be edited + by OpenACS documentation staff. +

The Big Picture

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: -

We can quickly identify and fix any errors.
We can reliabily modify or drop constraints

Why do we need a naming convention?

We can quickly identify and fix any errors.
We can reliabily modify or drop constraints

Why do we need a naming convention?

Oracle limits names, in general, to 30 characters, which is hardly enough for a human readable constraint name. -

-Abbreviations

Abbreviations

We propose the following naming convention for all constraints, with the following abbreviations taken from Oracle Docs at http://oradoc.photo.net/ora81/DOC/server.815/a67779/ch4e.htm#8953. Note that we shortened all of the constraint abbrevations to two characters to save room. -

---- - - - - - - - - - - - - - - - - - - - - - - - - - - -

Constraint type	Abbreviation
references (foreign key)	fk
unique	un
primary key	pk
check	ck
not null	nn

-Format of constraint name

Constraint type	Abbreviation
references (foreign key)	fk
unique	un
primary key	pk
check	ck
not null	nn

Format of constraint name

<table name>_<column_name>_<constraint abbreviation> -

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: -

Abbreviate the table name with the table's initials (e.g. users -> u and users_contact -> uc). -
Truncate the column name until it fits.

Abbreviate the table name with the table's initials (e.g. users -> u and users_contact -> uc). +
Truncate the column name until it fits.

If the constraint name is still too long, you should consider rewriting your entire data model :) -

Notes:

If you have to abbreviate the table name for one of the constraints, abbreviate it for all the constraints
If you are defining a multi column constraint, try to truncate the two column names evenly

-Example

Notes:

If you have to abbreviate the table name for one of the constraints, abbreviate it for all the constraints
If you are defining a multi column constraint, try to truncate the two column names evenly

Example

 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)
 );
 
-

-Why it's good to name primary keys

Why it's good to name primary keys

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! -

+
 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)
-
-
+

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? -

-Naming not null constraints is optional...

Naming not null constraints is optional...

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. -

About Naming the not null constraints

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. -

($Id$)

- - - - - - - - - - - -

-Prev	Home	Next -
Release Version Numbering	Up	ACS File Naming and Formatting Standards

- rmello at fslc.usu.edu -

Prev	Home	Next
Release Version Numbering	Up	ACS File Naming and Formatting Standards

- - +

Index: openacs.org-dev/packages/acs-core-docs/www/eng-standards-filenaming.html =================================================================== RCS file: /usr/local/cvsroot/openacs.org-dev/packages/acs-core-docs/www/eng-standards-filenaming.html,v diff -u -r1.1.1.1 -r1.1.1.2 --- openacs.org-dev/packages/acs-core-docs/www/eng-standards-filenaming.html 9 Jul 2002 17:34:57 -0000 1.1.1.1 +++ openacs.org-dev/packages/acs-core-docs/www/eng-standards-filenaming.html 11 Aug 2002 00:42:48 -0000 1.1.1.2 @@ -1,161 +1,65 @@ - - - -ACS File Naming and Formatting Standards - - - - - - - - -

- - - -

-Prev	Chapter 6. Engineering Standards	Next -

-ACS File Naming and Formatting Standards

By michael@arsdigita.com and -aure@arsdigita.com -

+ACS File Naming and Formatting Standards

Prev	Chapter 6. Engineering Standards	Next

ACS File Naming and Formatting Standards

By michael@arsdigita.com and +aure@arsdigita.com

+ OpenACS docs are written by the named authors, but may be edited + by OpenACS documentation staff. +

To ensure consistency (and its collateral benefit, maintainability), we define and adhere to standards in the following areas: -

-File Nomenclature

File Nomenclature

Usually we organize our files so that they mainly serve one of the following three purposes: -

displaying objects and their properties
manipulating or acting on objects in some way (by creating, editing, linking, etc)
housing procedures, packages, data models and other prerequisite code -Essentially, we want our files named in a fashion that reflects their purpose.

displaying objects and their properties
manipulating or acting on objects in some way (by creating, editing, linking, etc)
housing procedures, packages, data models and other prerequisite code +Essentially, we want our files named in a fashion that reflects their purpose.

Under the page root (and the template root if using the Style package): -

-
For naming files that enable a specific action on an object, use this format:
-
-object-verb.extension -
-
+
- For naming files that enable a specific action on an object, use this format:
  +object-verb.extension +
  For example, the page to erase a user's portrait from the database is /admin/users/portrait-erase.tcl. -
  -
- -
  However, modules typically deal with only one primary type of object - +
- 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 /bookmarks/ directory, and so there is no need to name the bookmark editing page with a redundant url: /bookmarks/bookmark-edit.tcl. Instead, we omit the object type, and use this convention: -
  -
  -verb.extension -
  -
  +
  +verb.extension +
  Thus, the page to edit a bookmark is /bookmarks/edit.tcl. -
  -
- -
  For naming files that display the properties of a primary object - such as the bookmark object within the bookmark module - use this convention:
  -
  -one.extension -
  -
  +
- For naming files that display the properties of a primary object - such as the bookmark object within the bookmark module - use this convention:
  +one.extension +
  For example, the page to view one bookmark is /bookmarks/one.tcl. Note that no verb is necessary for display-type files. -
  -
- -
  Otherwise, if the object to be displayed is not the primary feature of a module, simply omit the verb and use the object name:
  -
  -object.extension -
  -
  +
- Otherwise, if the object to be displayed is not the primary feature of a module, simply omit the verb and use the object name:
  +object.extension +
  For example, the page to view the properties of an ecommerce product is /ecommerce/product.tcl. -
  -
- -
  For naming files in a page flow, use the convention:
  -
  - -foobar.extension (Step 1)
  - -foobar-2.extension (Step 2)
  - ...
  - -foobar-N.extension (Step N)
  -
  -where foobar is determined by the above +
- For naming files in a page flow, use the convention:
  - foobar.extension (Step 1)
  - foobar-2.extension (Step 2)
  - ...
  - foobar-N.extension (Step N)
  +where foobar is determined by the above rules. -
  -
  +
  Typically, we use a three-step page flow when taking user information: -
  -
  1. Present a form to the user
  2. Present a confirmation page to the user
  3. Perform the database transaction, then redirect
  -
- -
  Put data model files in /www/doc/sql, and name them +
  1. Present a form to the user
  2. Present a confirmation page to the user
  3. Perform the database transaction, then redirect
- Put data model files in /www/doc/sql, and name them for the modules towards which they are used: -
  -
  -module.sql -
  -
-
+
+module.sql +

In the Tcl library directory: -

-
For files that contain module-specific procedures, use the -convention:
-
-module-procs.tcl -
-
-
For files that contain procedures that are part of the core ACS, -use the convention:
-
-ad-description-procs.tcl -
-

-URLs

-File names also appear within pages, as linked URLs and +

For files that contain module-specific procedures, use the +convention:
+module-procs.tcl +
For files that contain procedures that are part of the core ACS, +use the convention:
+ad-description-procs.tcl +

URLs

+File names also appear within pages, as linked URLs and form targets. When they do, always use abstract URLs (e.g., user-delete instead of user-delete.tcl), because they enhance maintainability. -

Similarly, when linking to the index page of a directory, do not explicitly name the index file (index.tcl, index.adp, index.html, etc.). Instead, use @@ -164,56 +68,40 @@ (/top-level-dir/). If linking to the directory in which the page is located, use the empty string (""), which browsers will resolve correctly. -

-File Headers and Page Input

File Headers and Page Input

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. -

+
# /www/index.tcl -
-
+

or -

+
# /tcl/module-defs.tcl -
-
+

For static content files (html or adp), include a CVS identification tag as a comment at the top of the file, e.g. -

+
 <!-- file-standards.html,v 1.2 2000/09/19 07:22:45 ron Exp -->
-
-
+

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>
 Last Modified: file-standards.html,v 1.2 2000/09/19 07:22:45 ron Exp
 </p>
-
-
+

This can be at the top or bottom of the file. -

Using ad_page_contract

For non-library Tcl files (those not in the private Tcl directory), use ad_page_contract 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: -

+
 # www/register/user-login-2.tcl
 
 ad_page_contract {
@@ -231,47 +119,35 @@
     {return_url {[ad_pvt_home]}}
     {persistent_cookie_p f}
 }
-
-
+

Salient features of ad_page_contract: -

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.
The second argument specifies the page +
- 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.
- 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. foo:integer,multiple,trim. In particular, multiple and array are the flags that correspond to the old -ad_page_variables flags.
- There are new flags: trim, notnull and +ad_page_variables flags.
- There are new flags: trim, notnull and optional. 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.
- -ad_page_contract can do validation for you: the flags integer +unless you declare it optional.
- ad_page_contract can do validation for you: the flags integer and sql_identifier will make sure that the values supplied are integers/sql_identifiers. The integer flag will also trim leading zeros. Note that unless you specify notnull, both will accept the empty string. -
- Note that ad_page_contract does not generate +
- Note that ad_page_contract 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. -
-
Using ad_library
-
+

Using ad_library

For shared Tcl library files, use ad_library after the file path comment. Its only argument is a doc_string in the standard (javadoc-style) format, like ad_page_contract. Don't forget to put the @cvs-id in there. Here is an example of using ad_library: -

+
 # 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
 }
-
-
Non-Tcl Files

-
+

Non-Tcl Files

For SQL and other non-Tcl source files, the following file header structure is recommended: -

--- path relative to the ACS root directory
+
+-- path relative to the ACS root directory
 --
--- brief description of the file's purpose
+-- brief description of the file's purpose
 --
--- author
--- created
+-- author
+-- created
 --
 -- $Id$
-
-
+

Of course, replace "--" with the comment delimiter appropriate for the language in which you are programming. -

-Page Construction

Page Construction

Construct the page as one Tcl variable (name it page_content), and then send it back to the browser with one call to doc_return, which will call db_release_unused_handles prior to executing ns_return, effectively combining the two operations. -

For example: -

-set page_content "[ad_header "Page Title"]
+
+set page_content "[ad_header "Page Title"]
 
-<h2>Page Title</h2>
+<h2>Page Title</h2>
 
 <hr>
 
@@ -327,16 +192,15 @@
     select row_information 
     from bar
 } {
-    append page_content "<li>row_information\n"
+    append page_content "<li>row_information\n"
 }
 
 append page_content "</ul>
 
 [ad_footer]"
 
 doc_return 200 text/html $page_content
-
-
+

The old convention was to call ReturnHeaders and then ns_write 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.) -

Local procedures (i.e., procedures defined and used only within one -page) should be prefixed with "module_" and +page) should be prefixed with "module_" and should be used rarely, only when they are exceedingly useful. -

All files that prepare HTML to display should end with [ad_footer] or -[module_footer]. If your module requires its own footer, +[module_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. -

-Tcl Library Files

Tcl Library Files

Further standards for Tcl library files are under discussion; we plan to include naming conventions for procs. -

($Id$)

- - - - - - - - - - - -

-Prev	Home	Next -
Constraint naming standard	Up	PL/SQL Standards

- rmello at fslc.usu.edu -

Prev	Home	Next
Constraint naming standard	Up	PL/SQL Standards

- - +

Index: openacs.org-dev/packages/acs-core-docs/www/eng-standards-plsql.html =================================================================== RCS file: /usr/local/cvsroot/openacs.org-dev/packages/acs-core-docs/www/eng-standards-plsql.html,v diff -u -r1.1.1.1 -r1.1.1.2 --- openacs.org-dev/packages/acs-core-docs/www/eng-standards-plsql.html 9 Jul 2002 17:34:57 -0000 1.1.1.1 +++ openacs.org-dev/packages/acs-core-docs/www/eng-standards-plsql.html 11 Aug 2002 00:42:48 -0000 1.1.1.2 @@ -1,79 +1,40 @@ - - - -PL/SQL Standards - - - - - - - - -

- - - -

-Prev	Chapter 6. Engineering Standards	Next -

-PL/SQL Standards

+PL/SQL Standards

Prev	Chapter 6. Engineering Standards	Next

PL/SQL Standards

By richardl@arsdigita.com and yon@arsdigita.com -

+ OpenACS docs are written by the named authors, but may be edited + by OpenACS documentation staff. +

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: -

-General

+
General
1. 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. -
2. +
3. 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. -
-
-
-
-Code
-
1. +
Code
1. Encapsulation of related fuctionality is key to maintainability and upgradeability of our software. Try to bundle your code into packages whenever possible. This will make upgrading, bug fixing, and customizing, among other things, a possibility. -
2. -
  +
3. 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: -
  -
```
+    
  
         create or replace procedure|function <proc_or_func_name> (
                  <param_1>    in|out|inout <datatype>,
@@ -93,31 +54,24 @@
         /
         show errors
      
-
-
```
4. +
5. Always use create or replace procedure|function <proc_or_func_name>. It makes reloading packages much easier and painless to someone who is upgrading or fixing a bug. -
6. +
7. Always qualify end statements, i.e., the end statement for a package should be end <package_name>;, not just end;; same goes for procedures, functions, package bodies, and triggers. -
8. +
9. 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. -
10. -
  +
11. 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: -
  -
```
+    
 
       
         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.)
       
      
-
-
+
```
  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: -
  -
```
+
 
         create or replace package body mypackage 
             .
@@ -156,29 +108,21 @@
         /
         show errors
      
-
-
```
12. +
13. Explicitly designate each parameter as "in," "out," or "inout." -
14. +
15. 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. -
16. +
17. Use %TYPE and %ROWTYPE whenever possible. -
18. +
19. Use 't' and 'f' for booleans, not the PL/SQL "boolean" datatype because it can't be used in SQL queries. -
20. -
  +
21. All new functions (e.g., acs_object.new, party.new, etc.) should optionally accept an ID: -
  -
```
+    
 
       
         create or replace package acs_object
@@ -193,61 +137,22 @@
            ) return acs_objects.object_id%TYPE;
      
     
-
-
+
```
  takes the optional argument object_id. 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 object_id and now they want to create the object with that object_id. -
  -
-
-
-
-Style
-
+

Style

Some general style guidelines to follow for the purpose of consistency across applications. -

+
1. 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. -
2. +
3. Lowercase everything, with the exception of %TYPE and %ROWTYPE. -
-
($Id$)
-

- - - - - - - - - - - -

-Prev	Home	Next -
ACS File Naming and Formatting Standards	Up	Chapter 7. Kernel Documentation

- rmello at fslc.usu.edu -

Prev	Home	Next
ACS File Naming and Formatting Standards	Up	Chapter 7. Kernel Documentation

- - +

-Release Version Numbering

By Ron Henderson -

+Release Version Numbering

Prev	Chapter 6. Engineering Standards	Next

Release Version Numbering

By Ron Henderson

+ OpenACS docs are written by the named authors, but may be edited + by OpenACS documentation staff. +

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: -

-major-minor-release -

-A change in the major version number indicates a fundamental +

major-minor-release

+A change in the major version number indicates a fundamental change in the architecture of the system, e.g. OpenACS 3 to ACS 4. A -change in the minor version number signifies the addition of +change in the minor version number signifies the addition of new modules and minor data model changes, e.g. OpenACS 3.1 to OpenACS 3.2. -The final release number indicates the relative maturity of a +The final release number indicates the relative maturity of a release and marks things like bug fixes; it follows the ordered progression: -

+
 alpha
 beta
 0 (production release)
 1
 2
 ...
-
-
+

So typical release version numbers would be: -

 openacs-3.2.5
 openacs-4.0.beta
-

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. -

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 readme.txt file: -

+
 > 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:
 ...
-
-
+

In the future, OpenACS packages should follow this same convention on version numbers. -

-Transition Rules

So what distinguishes an alpha release from a beta +

Transition Rules

So what distinguishes an alpha release from a beta 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.

Every release must pass the minimum requirements that it cleanly +the next.

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 release label implies:

-
development -
-
This is the default state for the head of the current release branch. We -make no guarantees about this code.
-
alpha -
-
All tickets of severity critical have been closed and the -distribution has no known installation or upgrade problems.
-
beta -
-
All tickets of severity serious or greater have been closed +addition to this the release label implies:
development +
This is the default state for the head of the current release branch. We +make no guarantees about this code.
alpha +
All tickets of severity critical have been closed and the +distribution has no known installation or upgrade problems.
beta +
All tickets of severity serious or greater have been closed and all documentation is up to date (version history, release notes, -new module docs, etc.).
-
production [0, 1, ...] -
-
All tickets of severity medium or greater have been closed, -including issues reported from outside users.
-
-
In the future we will guarantee that more mature releases +new module docs, etc.).
production [0, 1, ...] +
All tickets of severity medium or greater have been closed, +including issues reported from outside users.

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.

($Id$)

- - - - - - - - - - - -

-Prev	Home	Next -
System/Application Requirements Template	Up	Constraint naming standard

- rmello at fslc.usu.edu -

+fundamental behavior.

Prev	Home	Next
System/Application Requirements Template	Up	Constraint naming standard

- - +

-Detailed Design Documentation Template

By You -

-Start Note

- NOTE: Some of the sections of this template may not apply to your +Detailed Design Documentation Template

Prev Chapter 6. Engineering Standards Next

Detailed Design Documentation Template

By You

Start Note

+ 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. -

- Also, bear in mind the audience for detailed design: fellow + intelligently. +

+ Also, bear in mind the audience for detailed design: fellow programmers who want to maintain/extend the software, AND parties - interested in evaluating software quality. -

-
-Essentials
-

+ interested in evaluating software quality. +

Essentials

When applicable, each of the following items should receive its own link: -

User directory
OpenACS administrator directory
Subsite administrator directory
Tcl script directory (link to the API browser page for the package)
PL/SQL file (link to the API browser page for the package)
Data model
Requirements document
ER diagram
Transaction flow diagram

-Introduction

User directory
OpenACS administrator directory
Subsite administrator directory
Tcl script directory (link to the API browser page for the package)
PL/SQL file (link to the API browser page for the package)
Data model
Requirements document
ER diagram
Transaction flow diagram

Introduction

This section should provide an overview of the package and address at least the following issues: -

What this package is intended to allow the user (or different - classes of users) to accomplish.
Within reasonable bounds, what this package is not intended to allow users to - accomplish.
The application domains where this package is most likely to be of use.
A high-level overview of how the package meets its +
- What this package is intended to allow the user (or different + classes of users) to accomplish.
- Within reasonable bounds, what this package is not intended to allow users to + accomplish.
- The application domains where this package is most likely to be of use.
- 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).
-
+ other package docs).

Also worthy of treatment in this section: -

When applicable, a careful demarcation between the +
- When applicable, a careful demarcation between the functionality of this package and others which - at least - superficially - appear to address the same requirements.
-
+ superficially - appear to address the same requirements.

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. -

-Historical Considerations

Historical Considerations

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. -

-Competitive Analysis

Competitive Analysis

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. -

If your package exhibits features missing from competing - software, this fact should be underscored.
If your package lacks features which are present in competing +
- If your package exhibits features missing from competing + software, this fact should be underscored.
- 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.
-
+ lacks.

Note that such a discussion may differ from a discussion of a package's potential future improvements. -

-Design Tradeoffs

Design Tradeoffs

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: -

Areas of interest to users:

Performance: availability and efficiency
Flexibility
Interoperability
Reliability and robustness
Usability

Areas of interest to developers:

Maintainability
Portability
Reusability
Testability

-API

Areas of interest to users:

Performance: availability and efficiency
Flexibility
Interoperability
Reliability and robustness
Usability

Areas of interest to developers:

Maintainability
Portability
Reusability
Testability

API

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: -

Problem-domain components: key algorithms, e.g. a specialized - statistics package would implement specific mathematical procedures.
User-interface components: e.g. HTML widgets that the package may need.
Data management components: procedures that provide a stable +
- Problem-domain components: key algorithms, e.g. a specialized + statistics package would implement specific mathematical procedures.
- User-interface components: e.g. HTML widgets that the package may need.
- Data management components: procedures that provide a stable interface to database objects and legal transactions - the latter - often correspond to tasks.
-
+ often correspond to tasks.

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. -

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. -

-Data Model Discussion

Data Model Discussion

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: -

The data model discussion should address the intended usage +
- 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.
- If a core service or other subsystem is being used (e.g., the + itself.
- If a core service or other subsystem is being used (e.g., the new parties and groups, permissions, etc.) this should also be - mentioned.
- Any default permissions should be identified herein.
- Discuss any data model extensions which tie into other - packages.
- -
  Transactions
  -
  Discuss modifications which the database may undergo from + mentioned.
- Any default permissions should be identified herein.
- Discuss any data model extensions which tie into other + packages.
- Transactions
  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.
  -
-

-User Interface

+ subsite-admin, by a user, by a developer, etc.

User Interface

In this section, discuss user interface issues and pages to be built; you can organize by the expected classes of users. These may include: -

Developers
OpenACS administrators (previously known as site-wide administrators)
Subsite administrators
End users

Developers
OpenACS administrators (previously known as site-wide administrators)
Subsite administrators
End users

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. -

- Note: In order that developer documentation be uniform across +

+ 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. -

+ respectively. +

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. -

-Configuration/Parameters

Configuration/Parameters

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. -

-Future Improvements/Areas of Likely Change

Future Improvements/Areas of Likely Change

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. -

Note that a careful treatment of the earlier "competitive analysis" section can greatly facilitate the documenting of this section. -

-Authors

Authors

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: -

System creator
System owner
Documentation author

-Revision History

- The revision history table below is for this template - modify it - as needed for your actual design document. -

------ - - - - - - - - - - - - - - - - - - - - - - - - - - -

Document Revision #	Action Taken, Notes	When?	By Whom?
0.3	Edited further, incorporated feedback from Michael Yoon	9/05/2000	Kai Wu
0.2	Edited	8/22/2000	Kai Wu
0.1	Creation	8/21/2000	Josh Finkler, Audrey McLoghlin

($Id$)

- - - - - - - - - - - -

-Prev	Home	Next -
Using PSGML mode in Emacs	Up	System/Application Requirements Template

- rmello at fslc.usu.edu -

System creator
System owner
Documentation author

Revision History

+ The revision history table below is for this template - modify it + as needed for your actual design document. +

Document Revision #	Action Taken, Notes	When?	By Whom?
0.3	Edited further, incorporated feedback from Michael Yoon	9/05/2000	Kai Wu
0.2	Edited	8/22/2000	Kai Wu
0.1	Creation	8/21/2000	Josh Finkler, Audrey McLoghlin

($Id$)

Prev	Home	Next
Using PSGML mode in Emacs	Up	System/Application Requirements Template

rmello at fslc.usu.edu

+should be fairly small and simple.

- - +

-OpenACS 4 Groups Design

-by Rafael H. Schloming and Mark Thomas -

-Essentials

User directory
Sitewide administrator directory
Subsite administrator directory
TCL script directory
OpenACS 4 Groups Requirements
Data model
-
PL/SQL file
-
- -community-core-create.sql
- groups-create.sql
-
ER diagram
Transaction flow diagram

-Introduction

Almost all database-backed websites have users, and need to model the +OpenACS 4 Groups Design

Prev	Chapter 7. Kernel Documentation	Next

OpenACS 4 Groups Design

+by Rafael H. Schloming and Mark Thomas
+ OpenACS docs are written by the named authors, but may be edited + by OpenACS documentation staff. +

Essentials

User directory
Sitewide administrator directory
Subsite administrator directory
TCL script directory
OpenACS 4 Groups Requirements
Data model
PL/SQL file
- +community-core-create.sql
- groups-create.sql
ER diagram
Transaction flow diagram

Introduction

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.

-Historical Considerations

The primary limitation of the OpenACS 3.x user group system is that it +for different user communities.

Historical Considerations

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 user_groups table may contain the group_id 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.

In addition, the Module Scoping design in OpenACS 3.0 introduced a -party abstraction - a thing that is a person or a group of people - +expensive.

In addition, the Module Scoping design in OpenACS 3.0 introduced a +party 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 scope, user_id, and group_id 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:

add these three columns to each "scoped" table
define a multi-column check constraint to protect against data corruption +to:
- add these three columns to each "scoped" table
- define a multi-column check constraint to protect against data corruption (e.g., a row with a scope value of "group" but a null -group_id)
- perform extra checks in Tcl and PL/SQL +group_id)
- perform extra checks in Tcl and PL/SQL functions and procedures to check both the user_id and -group_id values
-

-Competitive Analysis

...

-Design Tradeoffs

The core of the Group Systems data model is quite simple, but it was +group_id values

Competitive Analysis

...

Design Tradeoffs

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.

The data model has tried to balance the need to model actual organizations +only inserts and deletes are permitted.

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.

-Data Model Discussion

The Group System data model consists of the following tables:

parties +on membership) trades against the complexity of the code.

Data Model Discussion

The Group System data model consists of the following tables:

parties -: The set of all defined parties: any person, user, or -group must have a corresponding row in this table.
persons +: The set of all defined parties: any person, user, or +group must have a corresponding row in this table.
persons -: The set of all defined persons. To allow easy sorting of persons, the +; The set of all defined persons. To allow easy sorting of persons, the name requirement 30.10 is met by splitting the person's name into two columns: first_names and -last_name.
users +last_name.
users -: The set of all registered users; this table includes information about -the user's email address and the user's visits to the site.
user_preferences +: The set of all registered users; this table includes information about +the user's email address and the user's visits to the site.
user_preferences -: Preferences for the user.
groups +: Preferences for the user.
groups -: The set of all defined groups.
group_types +: The set of all defined groups.
group_types -: When a new type of group is created, this table holds additional -knowledge level attributes for the group and its subtypes.
membership_rels +: When a new type of group is created, this table holds additional +knowledge level attributes for the group and its subtypes.
membership_rels -: The set of direct membership relationships between a group and a -party.
group_member_index +: The set of direct membership relationships between a group and a +party.
group_member_index -: A mapping of a party P to the groups -{G_i}the party is a member of; this mapping +; A mapping of a party P to the groups +{G_i}the party is a member of; this mapping includes the type of relationship by including the appropriaterel_id -from the membership_rels table.
composition_rels +from the membership_rels table.
composition_rels -: The set of direct component relationships between a group and another -group.
group_component_index +: The set of direct component relationships between a group and another +group.
group_component_index -: A mapping of a group Gto the set of groups -{G_i} that G is a component of; +; A mapping of a group Gto the set of groups +{G_i} that G is a component of; this mapping includes the type of relationship by including the -appropriaterel_id from the composition_rels table.

New groups are created through the group.new constructor. +appropriaterel_id from the composition_rels table.

New groups are created through the group.new 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.

The membership_rels and composition_rels tables indicate +creation time by passing a parent group to the constructor.

The membership_rels and composition_rels 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., group_member_index and group_component_index. One can think -of these tables as a manually maintained index.

The following triggers keep the group_*_index tables up to -date:

membership_rels_in_tr +of these tables as a manually maintained index. The following triggers keep the group_*_index tables up to +date: membership_rels_in_tr - - Is executed when a new group/member relationship is created (an insert on -membership_rels) - membership_rels_del_tr + Is executed when a new group/member relationship is created (an insert on +membership_rels) membership_rels_del_tr - - Is executed when a group/member relationship is deleted (a delete on -membership_rels) - composition_rels_in_tr + Is executed when a group/member relationship is deleted (a delete on +membership_rels) composition_rels_in_tr - - Is executed when a new group/component relationship is created (an insert -on composition_rels) - composition_rels_del_tr + Is executed when a new group/component relationship is created (an insert +on composition_rels) composition_rels_del_tr - - Is executed when a group/component relationship is deleted (a delete on -composition_rels) - - The data model provides the following views onto the +: Is executed when a group/component relationship is deleted (a delete on +composition_rels)

The data model provides the following views onto the group_member_index and group_component_index tables. No code outside of Groups System should modify the group_*_index -tables.

group_member_map +tables. group_member_map - - A mapping of a party to the groups the party is a member of; this mapping +: A mapping of a party to the groups the party is a member of; this mapping includes the type of relationship by including the appropriaterel_id -from the membership_rels table.
group_approved_member_map +from the membership_rels table.
group_approved_member_map -: A mapping of a party to the groups the party is an approved member of +; A mapping of a party to the groups the party is an approved member of (member_state is 'approved'); this mapping includes the type of relationship by including the appropriaterel_id from the -membership_rels table.
group_distinct_member_map +membership_rels table.
group_distinct_member_map -: A person may appear in the group member map multiple times, for example, +; 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 approved members -to groups.
group_component_map +group. This view is strictly a mapping of approved members +to groups.
group_component_map -: A mapping of a group Gto the set of groups -{G_i} group G is a component of; +; A mapping of a group Gto the set of groups +{G_i} group G is a component of; this mapping includes the type of relationship by including the -appropriaterel_id from the composition_rels table.
party_member_map +appropriaterel_id from the composition_rels table.
party_member_map -: A mapping of a party P to the set of parties -{P_i} party P is a member -of.
party_approved_member_map +: A mapping of a party P to the set of parties +{P_i} party P is a member +of.
party_approved_member_map -: A mapping of a party P to the set of parties -{P_i} party P is an -approved member of.

-API

A mapping of a party P to the set of parties +{P_i} party P is an +approved member of.

API

The API consists of tables and views and PL/SQL functions. -

-Tables and Views

The group_types table is used to create new types of groups.

The group_member_map, group_approved_member_map, +

Tables and Views

The group_types table is used to create new types of groups.

The group_member_map, group_approved_member_map, group_distinct_member_map, group_component_map, party_member_map, and party_approved_member_map views are -used to query group membership and composition.

-PL/SQL API

Person

-person.new creates a new person and returns the +used to query group membership and composition.

PL/SQL API

Person

person.new creates a new person and returns the person_id. The function must be given the full name of the person in two pieces: first_names and last_name. All other fields are optional and default to null except for object_type which defaults to person and creation_date which defaults to sysdate. The -interface for this function is:

+interface for this function is:
 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;
-
-
-person.delete deletes the person whose person_id is
-passed to it. The interface for this procedure is:
-+
person.delete deletes the person whose person_id is
+passed to it. The interface for this procedure is:
 procedure person.delete (
   person_id     persons.person_id%TYPE
 );
-
-
-person.name returns the name of the person whose
-person_id is passed to it. The interface for this function is:
-+
person.name returns the name of the person whose
+person_id is passed to it. The interface for this function is:
 function person.name (
   person_id     persons.person_id%TYPE
 ) return varchar;
-
-User
-
-acs_user.new creates a new user and returns the user_id.
+

User

acs_user.new creates a new user and returns the user_id. The function must be given the user's email address and the full name of the user in two pieces: first_names and last_name. All -other fields are optional. The interface for this function is:

+other fields are optional. The interface for this function is:
 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;
-
-
-acs_user.delete deletes the user whose user_id is passed
-to it. The interface for this procedure is:
-+
acs_user.delete deletes the user whose user_id is passed
+to it. The interface for this procedure is:
 procedure acs_user.delete (
   user_id       users.user_id%TYPE
 );
-
-
-acs_user.receives_alerts_p returns 't' if the user should
+

acs_user.receives_alerts_p returns 't' if the user should receive email alerts and 'f' otherwise. The interface for this -function is:

+function is:
 function acs_user.receives_alerts_p (
   user_id       users.user_id%TYPE
 ) return varchar;
-
-Use the procedures acs_user.approve_email and
+

Use the procedures acs_user.approve_email and acs_user.unapprove_email to specify whether the user's email -address is valid. The interface for these procedures are:

+address is valid. The interface for these procedures are:

 procedure acs_user.approve_email (
   user_id       users.user_id%TYPE
 );
 
 procedure acs_user.unapprove_email (
   user_id       users.user_id%TYPE
 );
-

Group

-acs_group.new creates a new group and returns the +

Group

acs_group.new creates a new group and returns the group_id. All fields are optional and default to null except for object_type which defaults to 'group', creation_date which defaults to sysdate, and group_name which is required. The interface for -this function is:

+this function is:
 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;
-
-
-acs_group.name returns the name of the group whose
-group_id is passed to it. The interface for this function is:
-+
acs_group.name returns the name of the group whose
+group_id is passed to it. The interface for this function is:
 function acs_group.name (
   group_id      groups.group_id%TYPE
 ) return varchar;
-
-
-acs_group.member_p returns 't' if the specified party is
+

acs_group.member_p returns 't' if the specified party is a member of the specified group. Returns 'f' otherwise. The interface -for this function is:

+for this function is:
 function acs_group.member_p (
   group_id      groups.group_id%TYPE,
   party_id      parties.party_id%TYPE,
 ) return char;
-
-Membership Relationship
-
-membership_rel.new creates a new membership relationship type
+

Membership Relationship

membership_rel.new creates a new membership relationship type between two parties and returns the relationship type's rel_id. All fields are optional and default to null except for rel_type -which defaults to membership_rel. The interface for this function is:

+which defaults to membership_rel. The interface for this function is:
 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;
-
-
-membership_rel.ban sets the member_state of the given
-rel_id to 'banned'. The interface for this procedure is:
-+
membership_rel.ban sets the member_state of the given
+rel_id to 'banned'. The interface for this procedure is:
 procedure membership_rel.ban (
   rel_id           membership_rels.rel_id%TYPE
 );
-
-
-membership_rel.approve sets the member_state of the
+

membership_rel.approve sets the member_state of the given rel_id to 'approved'. The interface for this procedure -is:

+is:

 procedure membership_rel.approve (
   rel_id           membership_rels.rel_id%TYPE
 );
-

-membership_rel.reject sets the member_state of the given -rel_id to 'rejected. The interface for this procedure is:

membership_rel.reject sets the member_state of the given +rel_id to 'rejected. The interface for this procedure is:

 procedure membership_rel.reject (
   rel_id           membership_rels.rel_id%TYPE
 );
-

-membership_rel.unapprove sets the member_state of the +

membership_rel.unapprove sets the member_state of the given rel_id to an empty string ''. The interface for this -procedure is:

+procedure is:

 procedure membership_rel.unapprove (
   rel_id           membership_rels.rel_id%TYPE
 );
-

-membership_rel.deleted sets the member_state of the +

membership_rel.deleted sets the member_state of the given rel_id to 'deleted'. The interface for this procedure -is:

+is:

 procedure membership_rel.deleted (
   rel_id           membership_rels.rel_id%TYPE
 );
-

-membership_rel.delete deletes the given rel_id. The -interface for this procedure is:

membership_rel.delete deletes the given rel_id. The +interface for this procedure is:

 procedure membership_rel.delete (
   rel_id           membership_rels.rel_id%TYPE
 );
-

Composition Relationship

-composition_rel.new creates a new composition relationship type +

Composition Relationship

composition_rel.new creates a new composition relationship type and returns the relationship's rel_id. All fields are optional and default to null except for rel_type which defaults to -composition_rel. The interface for this function is:

+composition_rel. The interface for this function is:
 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;
-
-
-composition_rel.delete deletes the given rel_id. The
-interface for this procedure is:
-+
composition_rel.delete deletes the given rel_id. The
+interface for this procedure is:
 procedure membership_rel.delete (
   rel_id           composition_rels.rel_id%TYPE
 );
-
-

-User Interface

Describe the admin pages.

-Configuration/Parameters

...

-Acceptance Tests

...

-Future Improvements/Areas of Likely Change

...

-Authors

System creator +

User Interface

Describe the admin pages.

Configuration/Parameters

...

Acceptance Tests

...

Future Improvements/Areas of Likely Change

...

Authors

System creator -: Rafael H. Schloming
System owner +: Rafael H. Schloming
System owner -: Rafael H. Schloming
Documentation author +: Rafael H. Schloming
Documentation author -: Mark Thomas

-Revision History

------ - - - - - - - - - - - - - - - - - - - - - - - - - - -

Document Revision #	Action Taken, Notes	When?	By Whom?
0.1	Creation	08/22/2000	Rafael H. Schloming
0.2	Initial Revision	08/30/2000	Mark Thomas
0.3	Additional revisions; tried to clarify membership/compostion	09/08/2000	Mark Thomas

- - - - - - - - - - - -

-Prev	Home	Next -
OpenACS 4 Groups Requirements	Up	OpenACS 4 Subsites Requirements

- rmello at fslc.usu.edu -

Mark Thomas

Revision History

Document Revision #	Action Taken, Notes	When?	By Whom?
0.1	Creation	08/22/2000	Rafael H. Schloming
0.2	Initial Revision	08/30/2000	Mark Thomas
0.3	Additional revisions; tried to clarify membership/compostion	09/08/2000	Mark Thomas

-OpenACS 4 Groups Requirements

-by Rafael H. Schloming, Mark Thomas -

-Introduction

Almost all database-backed websites have users, and need to model the +OpenACS 4 Groups Requirements

Prev	Chapter 7. Kernel Documentation	Next

OpenACS 4 Groups Requirements

+by Rafael H. Schloming, Mark Thomas
+ OpenACS docs are written by the named authors, but may be edited + by OpenACS documentation staff. +

Introduction

-Vision Statement

A powerful web service that can meet the needs of large enterprises must +for different user communities.

Vision Statement

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.

Historical Motivations

The primary limitation of the OpenACS 3.x user group system is that it +system will support such complex relations faithfully.

Historical Motivations

In addition, the Module Scoping design in OpenACS 3.0 introduced a -party abstraction - a thing that is a person or a group of people - +expensive.

add these three columns to each "scoped" table
define a multi-column check constraint to protect against data corruption +to:
- add these three columns to each "scoped" table
- define a multi-column check constraint to protect against data corruption (e.g., a row with a scope value of "group" but a null -group_id)
- perform extra checks in Tcl and PL/SQL +group_id)
- perform extra checks in Tcl and PL/SQL functions and procedures to check both the user_id and -group_id values
-
In sum, the goal of the Parties and Groups system is to +group_id values

In sum, the goal of the Parties and Groups 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.

-User Scenarios

Pat Developer has a client project and wants to model the company, its +world.

User Scenarios

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.

-System Overview

We start with Groups, which contain members; the -member can be either a person or another group (i.e. a -member is a party).

In addition to membership, the party and groups system defines a -composition relationship that may exist between groups: A -group can be a component of another group. The child group -is called a component group; the parent group is called a -composite group.

A group G_c can be a member and/or a component -of another group G_p; the difference is in the way -the members of G_c are related to -G_p:

If a party P is a member (or a component) of -G_c and if G_c is a -component of G_p, then P is also -a member (or a component) of G_p -
If a party P is a member (or a component) of -G_c and if G_c is a -member of G_p, then no -relationship between P and -G_p exists as a result of the relationship between -G_p and G_p.

Consider an example to make this less abstract: Pretend that the Sierra -Club is a member of Greenpeace. The Sierra Club has chapters; each -chapter is a component of the Sierra Club. If Eddie Environmentalist +users.

System Overview

We start with Groups, which contain members; the +member can be either a person or another group (i.e. a +member is a party).

In addition to membership, the party and groups system defines a +composition relationship that may exist between groups: A +group can be a component of another group. The child group +is called a component group; the parent group is called a +composite group.

A group G_c can be a member and/or a component +of another group G_p; the difference is in the way +the members of G_c are related to +G_p:

If a party P is a member (or a component) of +G_c and if G_c is a +component of G_p, then P is also +a member (or a component) of G_p
If a party P is a member (or a component) of +G_c and if G_c is a +member of G_p, then no +relationship between P and +G_p exists as a result of the relationship between +G_p and G_p.

Consider an example to make this less abstract: Pretend that the Sierra +Club is a member of Greenpeace. The Sierra Club has chapters; each +chapter is a component 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.

In the OpenACS, Greenpeace, Sierra Club, and the Sierra Club chapters would be +does not make Eddie a member of Greenpeace.

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.

Membership requirements can vary from group to group. The parties and +Massachusetts chapter), and between the Sierra Club and Greenpeace.

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.

The parties and groups system must support constraints between a composite -group G_P and any of its component groups, -G_C. For example, the system should be able to -enforce a rule like: Do not allow a party P to become a -member of G_C unless P is already -a member of G_P.

-Related Links

OpenACS 4 Groups Design

-Requirements: Data Model

The data model for the parties and groups system must provide support for -the following types of entities:

10.0 Parties +necessary to join a group. The parties and groups system must support constraints between a composite +group G_P and any of its component groups, +G_C. For example, the system should be able to +enforce a rule like: Do not allow a party P to become a +member of G_C unless P is already +a member of G_P.

Requirements: Data Model

The data model for the parties and groups system must provide support for +the following types of entities:

10.0 Parties -

A party is an entity used to represent either a -group or a person.

The data model should enforce these constraints:

-10.10 A party has an email address, which can be -empty.

-10.20 A party may have multiple email addresses -associated with it.

-10.30 The email address of a party must be unique within -an OpenACS system.

20.0 Groups +

A party is an entity used to represent either a +group or a person.

The data model should enforce these constraints:

10.10 A party has an email address, which can be +empty.

10.20 A party may have multiple email addresses +associated with it.

10.30 The email address of a party must be unique within +an OpenACS system.

20.0 Groups -

A group is a collection of zero or more parties.

-20.10 The data model should support the subclassing of -groups via OpenACS Objects.

30.0 Persons +

A group is a collection of zero or more parties.

20.10 The data model should support the subclassing of +groups via OpenACS Objects.

30.0 Persons -

A person represents an actual human being, past or -present.

-30.10. A person must have -an associated name.

40.0 Users +

A person represents an actual human being, past or +present.

30.10. A person must have +an associated name.

40.0 Users -

A user is a person who has registered with an OpenACS site. A -user may have additional attributes, such as a screen name.

The data model should enforce these constraints:

-40.10 A user must have a non-empty email address.

-40.20 Two different users may not have the same email +

A user is a person who has registered with an OpenACS site. A +user may have additional attributes, such as a screen name.

The data model should enforce these constraints:

40.10 A user must have a non-empty email address.

40.20 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.

-40.30 A user may have multiple email addresses; for -example, two or more email addresses may identify a single user.

-40.40 A user must have password field which can be -empty.

The data model for the parties and groups system must provide support for -the following types of relationships between entities:

50.0 Membership +single user on the system. 40.30 A user may have multiple email addresses; for +example, two or more email addresses may identify a single user. 40.40 A user must have password field which can be +empty.

The data model for the parties and groups system must provide support for +the following types of relationships between entities:

50.0 Membership -

-A party P is considered a member of a -group G -

when a direct membership relationship exists between P -and G -
or when there exists a direct membership relationship between -P and some group G_C and -G_C has a composition relationship (c.f., 60.0) with G.

-50.10 A party may be a member of multiple groups.

-50.20 A party may be a member of the same group multiple +

+A party P is considered a member of a +group G

when a direct membership relationship exists between P +and G
or when there exists a direct membership relationship between +P and some group G_C and +G_C has a composition relationship (c.f., 60.0) with G.

50.10 A party may be a member of multiple groups.

50.20 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.

-50.30 A party as a member of itself is not supported.

-50.40 The data model must support membership -constraints.

-50.50The data model should support the subclassing of -membership via OpenACS Relationships.

+Executive. 50.30 A party as a member of itself is not supported. 50.40 The data model must support membership +constraints. 50.50The data model should support the subclassing of +membership via OpenACS Relationships.

-60.0 Composition -

A group G_C is considered a -component of a second group -G_P -

when a direct composition relationship exists between -G_C and G_P -
or when there exists a direct composition relationship between -G_C and some group G_i -and G_i has a composition relationship with -G_P.

-60.10A group may be a component of multiple groups.

-60.20A group as a component of itself is not -supported.

-60.30The data model must support component -constraints.

-60.40The data model should support the subclassing of -composition via OpenACS Relationships.

-Requirements: API

The API should let programmers accomplish the following tasks:

70.10 Create a group +60.0 Composition +

A group G_C is considered a +component of a second group +G_P

when a direct composition relationship exists between +G_C and G_P
or when there exists a direct composition relationship between +G_C and some group G_i +and G_i has a composition relationship with +G_P.

60.10A group may be a component of multiple groups.

60.20A group as a component of itself is not +supported.

60.30The data model must support component +constraints.

60.40The data model should support the subclassing of +composition via OpenACS Relationships.

Requirements: API

The API should let programmers accomplish the following tasks:

70.10 Create a group -

The parties and groups system provides a well defined API call that +

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.

70.20 Create a person +in the data model.

70.20 Create a person -

The parties and groups system provides a well defined API call that +

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.

70.30 Create a user +in the data model.

70.30 Create a user -

The parties and groups system provides a well defined API call that +

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.

80.10 Refine a person to a user +the data model.

80.10 Refine a person to a user -

The parties and groups system provides a well defined API call that +

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.

80.30 Demote a user to a person +model.

80.30 Demote a user to a person -

The parties and groups system provides a well defined API call that +

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.

90.10 Update a party +laid out in the data model.

90.10 Update a party -

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.

95.10 Get the attributes of a party +

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.

95.10 Get the attributes of a party -

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.

100.10 Delete a party +

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.

100.10 Delete a party -

The system provides an API for deleting a party. This API is subject to -the constraints laid out in the data model.

-100.30 The system may provide a single API call to remove -the party from all groups and then delete the party.

-100.40 In the case of a group, the system may provide a +

The system provides an API for deleting a party. This API is subject to +the constraints laid out in the data model.

100.30 The system may provide a single API call to remove +the party from all groups and then delete the party.

100.40 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.

110.0 Add a party as a member of a group +group.

110.0 Add a party as a member of a group -

The parties and groups system provides an API for adding a party as a +

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.

115.0 Add a group as a component of a second group +data model.

115.0 Add a group as a component of a second group -

The parties and groups system provides an API for adding a group as a +

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.

120.0 Remove a party as a member of a group +in the data model.

120.0 Remove a party as a member of a group -

The parties and groups system provides an API for deleting a party's +

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.

125.0 Remove a group as a component of a second -group +data model.

125.0 Remove a group as a component of a second +group -

The parties and groups system provides an API for deleting a group's +

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.

130.0 Membership check +out in the data model.

130.0 Membership check -

The parties and groups system provides an API for answering the question: -"Is party P a member of group -G?"

135.0 Composition check +

The parties and groups system provides an API for answering the question: +"Is party P a member of group +G?"

135.0 Composition check -

The parties and groups system provides an API for answering the question: -"Is group G_C a component of group -G_P?"

140.0 Get members query +

The parties and groups system provides an API for answering the question: +"Is group G_C a component of group +G_P?"

140.0 Get members query -

The parties and groups system provides an API for answering the question: -"Which parties are members of group G?"

145.0 Get components query +

The parties and groups system provides an API for answering the question: +"Which parties are members of group G?"

145.0 Get components query -

The parties and groups system provides an API for answering the question: -"Which groups are components of group G?"

150.0 Member-of-groups query +

The parties and groups system provides an API for answering the question: +"Which groups are components of group G?"

150.0 Member-of-groups query -

The parties and groups system provides an API for answering the question: -"Of which groups is party P a member?"

155.0 Component-of-groups query +

The parties and groups system provides an API for answering the question: +"Of which groups is party P a member?"

155.0 Component-of-groups query -

The parties and groups system provides an API for answering the question: -"Of which groups is group G a component?"

160.0 Allowed membership check +

The parties and groups system provides an API for answering the question: +"Of which groups is group G a component?"

160.0 Allowed membership check -

The parties and groups system provides an API for answering the question: -"Is party P allowed to become a member of group -G?"

165.0 Allowed composition check +

The parties and groups system provides an API for answering the question: +"Is party P allowed to become a member of group +G?"

165.0 Allowed composition check -

The parties and groups system provides an API for answering the question: -"Is group G_C allowed to become a component -of group G_P?"

170.0 Efficiency +

The parties and groups system provides an API for answering the question: +"Is group G_C allowed to become a component +of group G_P?"

170.0 Efficiency -

Since many pages at a site may check membership in a group before serving +

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.

180.0 Ease of Use +membership.

180.0 Ease of Use -

Since many SQL queries will check membership in a group as part of the +

Since many SQL queries will check membership in a group as part of the where clause, whatever mechanism is used to check membership in SQL -should be fairly small and simple.

-Requirements: User Interface

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:

-200.0 Create a party
-210.0 View the attributes of a party
-220.0 Update the attributes of a party
-240.0 Delete a party
-250.0 Add a party to a group
-260.0 Remove a party from a group
-270.0 Perform the membership and composition checks -outlined in 130.x to 165.x

-Revision History

------ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Document Revision #	Action Taken, Notes	When?	By Whom?
0.1	Creation	08/16/2000	Rafael Schloming
0.2	Initial revision	08/19/2000	Mark Thomas
0.3	Edited and reviewed, conforms to requirements template	08/23/2000	Kai Wu
0.4	Further revised, added UI requirements	08/24/2000	Mark Thomas
0.5	Final edits, pending freeze	08/24/2000	Kai Wu
0.6	More revisions, added composition requirements	08/30/2000	Mark Thomas
0.7	More revisions, added composition requirements	09/08/2000	Mark Thomas

- - - - - - - - - - - -

-Prev	Home	Next -
OpenACS 4 Permissions Design	Up	OpenACS 4 Groups Design

- rmello at fslc.usu.edu -

Requirements: User Interface

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:

200.0 Create a party
210.0 View the attributes of a party
220.0 Update the attributes of a party
240.0 Delete a party
250.0 Add a party to a group
260.0 Remove a party from a group
270.0 Perform the membership and composition checks +outlined in 130.x to 165.x

Revision History

Document Revision #	Action Taken, Notes	When?	By Whom?
0.1	Creation	08/16/2000	Rafael Schloming
0.2	Initial revision	08/19/2000	Mark Thomas
0.3	Edited and reviewed, conforms to requirements template	08/23/2000	Kai Wu
0.4	Further revised, added UI requirements	08/24/2000	Mark Thomas
0.5	Final edits, pending freeze	08/24/2000	Kai Wu
0.6	More revisions, added composition requirements	08/30/2000	Mark Thomas
0.7	More revisions, added composition requirements	09/08/2000	Mark Thomas

Prev	Home	Next
OpenACS 4 Permissions Design	Up	OpenACS 4 Groups Design

rmello at fslc.usu.edu

- - +

-Overview

-What is OpenACS?

+Overview

Prev	Chapter 2. Installing on Unix/Linux	Next

Overview

+ by Vinod Kurup
+ OpenACS docs are written by the named authors, but may be edited + by OpenACS documentation staff. +

What is OpenACS?

According to Philip Greenspun: -

“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.” -

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. -

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,151 +25,94 @@ the word) to extend it to other databases. Don Baccus leads the development and numerous developers (and non-developers) contribute from around the world. -

-Purpose of this document

Purpose of this document

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. -

-Requirements

Requirements

You will need a PC (or equivalent) with at least these minimum requirements: -

Pentium processor
128 MB RAM - (much more if you want Oracle)
4 GB hard drive

Pentium processor
128 MB RAM + (much more if you want Oracle)
4 GB hard drive

If you want to serve pages to people outside of your machine, you'll need a network connection of some type. -

Note that these are minimum requirements to get a development system up and running. For a production system, we recommend you read about the ArsDigita Server Architecture -

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: -

+
- Adding users, groups, setting passwords -
- +
- Starting an X server and running an X program remotely -
- +
- Basic file management using cp, rm, mv, and cd -
- +
- Compiling a program using a Makefile -
-
+

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 Resources section. -

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 Acquire Oracle section. -

-Steps involved

Steps involved

The basic steps to getting OpenACS up and running are: -

Install an OS
Install a webserver (AOLServer)
Install a database (Oracle or - PostgreSQL)
Install a database +
1. Install an OS
2. Install a webserver (AOLServer)
3. Install a database (Oracle or + PostgreSQL)
4. Install a database driver (allows the webserver to talk to the database) -
5. Configure the webserver and - database
6. Start the OpenACS - installer
-

-What if I get stuck?

Configure the webserver and + database

Start the OpenACS + installer

What if I get stuck?

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: -

- 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: +
- + Keep track of the commands you are run and record 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 script command. -
- +
- 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. -
- +
- Search the bboards at openacs.org - you'll often find many people who have struggled through the same spot that you're in. -
- +
- Ask questions at the irc channel on openprojects.net (#openacs). They're knowledgeable and quite friendly if you can keep them on topic. -
- +
- Post a question on the bboards. 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. -
- +
- If you find errors in this document or if you have ideas about making it better, please post them in our bug tracker - the SDM. -
-

-Is there an easier way?

Is there an easier way?

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, @@ -205,134 +121,75 @@ but will eventually also be available at http://openacs.org/software. They're quite new and Jonathan invites (and is quite responsive to) feedback. Leave comments at this thread. -

-Where did this document come from?

Where did this document come from?

This document was created by Vinod Kurup, 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. -

These are a few of my sources:

+
These are a few of my sources:
- ArsDigita installation guide -
- +
- OpenACS 3.x installation guide -
- +
- Gilbert Wong's FreeBSD installation guide -
- +
- My own Brief OpenACS4 installation guide -
-
+

Please also see the Credits section for more acknowledgements. -

-Resources

Resources

Here are some resources that OpenACS users have found useful. -

-Books

+
Books
- Philip and Alex's Guide to Web Publishing - A very readable guide to database-backed community websites. -
- +
- UNIX Power Tools - An excellent introduction to the command line tools and basic programs of UNIX -
- +
- UNIX System Administration Handbook (formerly the "red book" - now the "purple" book) -
- +
- UNIX System Administrator's Bible - (LePage and Iarerra 1998; IDG) -
- +
- Running - Linux
- Learning - Gnu Emacs
- + Linux
- Learning + Gnu Emacs
- Linux in a Nutshell -
-
-
-
-Web Sites
-
- +
Web Sites
- The UNIX Reference Desk -
- +
- The Linux Documentation Project -
-
-

($Id$)

- - - - - - - - - - - -

-Prev	Home	Next -
Chapter 2. Installing on Unix/Linux	Up	Install an Operating System

- rmello at fslc.usu.edu -

+ + LPI + certification exam preps - A series of articles from + IBM developerworks on basic and intermediate Linux skills + (requires registration) + +

($Id$)

Prev	Home	Next
Chapter 2. Installing on Unix/Linux	Up	Install an Operating System

rmello at fslc.usu.edu

- - +

-Overview

+Overview

Prev	Chapter 7. Kernel Documentation	Next

Overview

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: -

The OpenACS 4.5 Kernel, which handles system-wide necessities +
- The OpenACS 4.5 Kernel, which handles system-wide necessities such as metadata, security, users and groups, subsites, and package management and deployment. -
- The OpenACS 4.5 Core, which comprises all the other packages +
- The OpenACS 4.5 Core, 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. -
- -OpenACS 4.5 Application packages, which typically provide +
- OpenACS 4.5 Application packages, 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. -
-
+

This document provides a high level overview of the kernel package. Documentation for the other packages can be found elsewhere. -

- - - - - - - - - - - -

-Prev	Home	Next -
Chapter 7. Kernel Documentation	Up	OpenACS 4 Object Model Requirements

- rmello at fslc.usu.edu -

Prev	Home	Next
Chapter 7. Kernel Documentation	Up	OpenACS 4 Object Model Requirements

- - +

-Next Steps

-Backup Strategy

Here are some tips from Don Baccus regarding backup strategy:

+Next Steps

Prev	Chapter 2. Installing on Unix/Linux	Next

Next Steps

+ by Vinod Kurup
+ OpenACS docs are written by the named authors, but may be edited + by OpenACS documentation staff. +

Backup Strategy

Here are some tips from Don Baccus regarding backup strategy:

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: -

+
- The database is stored on a mirrored (RAID 1) disk. -
- +
- The machine has battery backup. -
- +
- Backups are made nightly onto a third disk on another controller -
- +
- FTP is used to copy the resulting backup to two separate remote servers in two locations -
-
+

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. -

-Set Up Nightly Oracle Exports

Set Up Nightly Oracle Exports

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 root. -

Download the backup script. Save the file export-oracle.txt as /tmp/export-oracle.txt -
-
+

 nsadmin:~$ su -
 Password: ***********
 root:~# cp /tmp/export-oracle.txt /usr/sbin/export-oracle
-root:~# chmod 700 /usr/sbin/export-oracle

-
+root:~# chmod 700 /usr/sbin/export-oracle

Setup the export directory; this is the directory where backups will be stored. We recommend the directory - /ora8/m02/oracle-exports.

+ /ora8/m02/oracle-exports.

 root:~# mkdir /ora8/m02/oracle-exports
 root:~# chown oracle.dba /ora8/m02/oracle-exports
-root:~# chmod 770 /ora8/m02/oracle-exports

-
+root:~# chmod 770 /ora8/m02/oracle-exports

Now edit /usr/sbin/export-oracle and change the SERVICE_NAME and @@ -109,11 +60,9 @@ /ora8/m02/oracle-exports, you also need to change the exportdir setting. -

Test the export procedure by running the command: -

+		
 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.
-If you don't have any warnings, proceed to automate the
-		  backups.
-

-
+Export terminated successfully without warnings.
If you don't have any warnings, proceed to automate the + backups.

Automating backups is accomplished using the UNIX - crontab facility.

+ crontab facility.

While still root, run the following command. You can replace the EDITOR="emacs -nw" portion with whatever editor your prefer, such as EDITOR=vi. -

 root:~# export EDITOR="emacs -nw"
-root:~# crontab -e

Now add the following line on a line by itself

-0 23 * * * /usr/sbin/export-oracle

+root:~# crontab -e

Now add the following line on a line by itself

+0 23 * * * /usr/sbin/export-oracle

Save the file, exit the editor. Verify that the addition - succeeded by checking the output of the following command.

+ succeeded by checking the output of the following command.

 root:~# crontab -l | grep export-oracle
 0 23 * * * /usr/sbin/export-oracle
 root:~# exit
-; Logout

If you see the line, go ahead and log out.

-Set up nightly Postgres exports

+; Logout

If you see the line, go ahead and log out.

Set up nightly Postgres exports

Dowload this script to /tmp. At the top of the script are several variables that you'll need to customize: -

+
- bak - location where you want local backups to be saved -
- +
- servername - name of your server (and database instance) -
- +
- ftp_user - username on your ftp account -
- +
- ftp_password - password on your ftp account -
- +
- ftp_dir - path on the remote server where your backups will be uploaded -
- +
- ftp_server - your ftp server -
-
+

Next, we'll save this file to our server's tcl 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. -

 nsadmin:~$ cp /tmp/acs-pgbackup-init.txt /web/birdnotes/tcl/acs-pgbackup-init.tcl
-nsadmin:~$ restart-aolserver birdnotes

+nsadmin:~$ restart-aolserver birdnotes

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) -

-Vacuum Postgres nightly

Vacuum Postgres nightly

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. -

Edit your crontab:

-nsadmin:~$ crontab -e

We'll set vacuum up to run nightly at 1 AM. Add the following - line:

-0 1 * * * /usr/local/pgsql/bin/vacuumdb birdnotes

-How to add a second server on a different port

Starting another server is simply a matter of configuring another +

Edit your crontab:

+nsadmin:~$ crontab -e

We'll set vacuum up to run nightly at 1 AM. Add the following + line:

+0 1 * * * /usr/local/pgsql/bin/vacuumdb birdnotes

How to add a second server on a different port

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 birdnotes-dev -

+ our new server birdnotes-dev

Download another copy of openacs4.tcl.txt - into /tmp.
-
```
-nsadmin:~$ cp /tmp/openacs4.tcl.txt ./birdnotes-dev.tcl
-nsadmin:~$ chmod 660 birdnotes-dev.tcl
-nsadmin:~$ emacs birdnotes-dev.tcl
```
-
Just like in the section called “Configuring AOLserver”, + into /tmp.
```
+nsadmin:~$ cp /tmp/openacs4.tcl.txt ./birdnotes-dev.tcl
+nsadmin:~$ chmod 660 birdnotes-dev.tcl
+nsadmin:~$ emacs birdnotes-dev.tcl
```
Just like in the section called “Configuring AOLserver”, you'll need to set the server parameters appropriately. Be sure to choose a different port than your original server and to set server to - birdnotes-dev.
-
+ birdnotes-dev.
Create a new database instance called - birdnotes-dev. Follow the instructions in + birdnotes-dev. Follow the instructions in Prepare Oracle for OpenACS or Prepare PostgreSQL for OpenACS. -
-
+

You can either copy your current OpenACS installation: -

+		
 nsadmin:~$ cd /web
-nsadmin:~$ cp -r birdnotes birdnotes-dev
-
+nsadmin:~$ cp -r birdnotes birdnotes-dev

Or Download the OpenACS 4 software into /tmp again. -

 nsadmin:~$ cd /web
 nsadmin:/web$ tar xzvf /tmp/alpha2.tgz
-nsadmin:/web$ mv openacs-4 birdnotes-dev

-
+nsadmin:/web$ mv openacs-4 birdnotes-dev

Start your new server! -

 nsadmin:/web$ cd
-nsadmin:~$ /usr/local/aolserver/bin/nsd-postgres -t /usr/local/aolserver/birdnotes-dev.tcl

+nsadmin:~$ /usr/local/aolserver/bin/nsd-postgres -t /usr/local/aolserver/birdnotes-dev.tcl

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 /etc/inittab (or - daemontools) so it restarts automatically.

-Set up site-wide search

+ daemontools) so it restarts automatically.

Set up site-wide search

OpenACS uses the OpenFTS package to implement site-wide-search. You'll need to have the Tcl development libraries and headers installed. (Debian users: apt-get install tcl8.3-dev) -

As root, download the Search-OpenFTS driver. -

 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

-
+root:/usr/local/src# exit

Configure it. Note that you may need to set --with-tcl=(your Tcl library location). For Debian, add this to the end of the ./configure command: --with-tcl=/usr/lib/tcl8.3 -

 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

-
+nsadmin:/usr/local/src/Search-OpenFTS-tcl-0.2$ ./configure --with-aolserver-src=/usr/local/src/aolserver/aolserver

In order to compile on Debian, I had to edit my Makefile.global. Add -I/usr/include/tcl8.3 to the line where INC is defined, so it looks like this: -

-INC          = ../include -I/usr/include/tcl8.3

Then compile it:

+INC          = ../include -I/usr/include/tcl8.3

Then compile it:

 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

-
+nsadmin:/usr/local/src/Search-OpenFTS-tcl-0.2/aolserver$ make

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. -

 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/

-
+nsadmin:/usr/local/src/Search-OpenFTS-tcl-0.2/aolserver$ cp nsfts.so /usr/local/aolserver/bin/
Add the following line to your aolserver config file (in our example: /usr/local/aolserver/birdnotes.tcl) in the "ns_section ns/server/${server}/modules" section: -
-
```
-        ns_param   nsfts           ${bindir}/nsfts.so
```
-

+        ns_param   nsfts           ${bindir}/nsfts.so

Load the openFTS code into your database: -

 nsadmin:/usr/local/src/Search-OpenFTS-tcl-0.2/aolserver$ cd
-nsadmin:~$ psql -f /web/birdnotes/packages/openfts-driver/sql/postgresql/load.sql birdnotes
-nsadmin:~$ restart-aolserver birdnotes

+nsadmin:~$ psql -f /web/birdnotes/packages/openfts-driver/sql/postgresql/load.sql birdnotes +nsadmin:~$ restart-aolserver birdnotes
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. -
+
Click on the "Install packages" link and follow the instructions to install the Note package and the OpenFTS Driver 4.2 package. -
+
Restart your server.
```
-nsadmin:~$ restart-aolserver birdnotes
```
-
+nsadmin:~$ restart-aolserver birdnotes +
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" -
+
Create a "new sub folder" under "Main Site". Call the url "openfts". -
Click "mount" to mount the OpenFTS driver at the url +
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) -
+
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. +
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. -
+
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. -
+
Restart the server. -
+
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. -
+
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. -
+
Click on the link to "install" the FtsEngineDriver. Also, click the link to install the Note content provider. -
+
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. -

($Id$)

- - - - - - - - - - - -

-Prev	Home	Next -
Install OpenACS 4.5	Up	Credits

- rmello at fslc.usu.edu -

Prev	Home	Next
Install OpenACS 4.5	Up	Credits

+key to eliminating redundant code and replacing it with generic object +level services.

- - +

-Object Identity

-by Rafael H. Schloming -

One of the major design features of OpenACS 4.5 is the explicit representation -of object identity. The reason I say "explicit +Object Identity

Prev	Chapter 5. Other Developer Resources	Next

Object Identity

+by Rafael H. Schloming
+ OpenACS docs are written by the named authors, but may be edited + by OpenACS documentation staff. +

One of the major design features of OpenACS 4.5 is the explicit representation +of object identity. 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 identify an object. In the 4.5 data model this -object is explicitly represented by a single party_id.

Another good example of this is can be found in the user groups data +scope) to identify an object. In the 4.5 data model this +object is explicitly represented by a single party_id.

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 -implied identity. Every mapping between a user and a group could +implied identity. 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.

Coming from a purely relational world, this might seem slightly weird at +table that maps users to groups.

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.

So, this apparently redundant primary key has saved us the trouble of +uses more than one way to represent identity.

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.

The design choice of explicitly representing object identity with an +even capable of fully tracking the history of membership state.

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 object -level services.

($Id$)

- - - - - - - - - - - -

-Prev	Home	Next -
Parties in OpenACS 4.5	Up	Programming with AOLserver

- rmello at fslc.usu.edu -

Prev	Home	Next
Parties in OpenACS 4.5	Up	Programming with AOLserver

- - +

-OpenACS 4 Object Model Design

+OpenACS 4 Object Model Design

Prev	Chapter 7. Kernel Documentation	Next

OpenACS 4 Object Model Design

by Pete Su, Michael Yoon, Richard Li - and Rafael Schloming -

-Essentials

-Data Model

-Tcl Files

Not yet linked.

-Requirements

-Introduction

Before OpenACS 4, software developers writing OpenACS applications or modules + and Rafael Schloming
+ OpenACS docs are written by the named authors, but may be edited + by OpenACS documentation staff. +

Essentials

Data Model

Tcl Files

Not yet linked.

Requirements

Introduction

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:

User comments
Storage of user-defined or extensible sets of attributes
Access control
General auditing and bookkeeping (e.g. creation date, IP addresses, and -so forth)
Presentation tools (e.g. how to display a field in a form or on a -page)

All of these services involve relating additional service-related +Examples of such services include:

User comments
Storage of user-defined or extensible sets of attributes
Access control
General auditing and bookkeeping (e.g. creation date, IP addresses, and +so forth)
Presentation tools (e.g. how to display a field in a form or on a +page)

All of these services involve relating additional service-related information to application data objects. Examples of application objects -include:

Bboard messages
A user home page
A ticket in the ticket tracker

In the past, developers had to use ad-hoc and inconsistent schemes to +include:

Bboard messages
A user home page
A ticket in the ticket tracker

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 metadata. By -metadata, we mean data stored on behalf of an application -outside of the application's data model in order to enable +manage, and serves as a primary store of metadata. By +metadata, we mean data stored on behalf of an application +outside 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:

-
-Object Identification
-
Every application object is given a unique identifier in the system. This +services to applications:
- Object Identification
  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. -
  -
- -
  -Object Context and Access Control
  -
  Every object is created in a particular security context, so the system +
- Object Context and Access Control
  Every object is created in a particular security context, so the system can provide centralized access control. -
  -
- -
  -Object Types and Attributes
  -
  Objects are instances of developer-defined object types. Object types +
- Object Types and Attributes
  Objects are instances of developer-defined object types. Object types allow developers to customize the data that is stored with each object. -
  -
- -
  -Relation Types
  -
  Relation types provide a general mechanism for mapping instances of one +
- Relation Types
  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). -
  -
-
The next section will explore these facilities in the context of the the -particular programming idioms that we wish to generalize.
-
Related Links
-
This design document should be read along with the design documents for the new groups system, subsites and the permissions system -
-

-History

The motivation for most of the facilities in the OpenACS 4 Object Model can be +

The next section will explore these facilities in the context of the the +particular programming idioms that we wish to generalize.

Related Links

This design document should be read along with the design documents for the new groups system, subsites and the permissions system

History

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.

-Object Identification

Object identification is a central mechanism in OpenACS 4. Every application +idioms that evolved there. These are listed and discussed below.

Object Identification

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 acs_objects. 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.

Implicit Object Identifiers in OpenACS 3.x

The motivation for implementing general object identifiers comes from +global and uniform manner.

Implicit Object Identifiers in OpenACS 3.x

The motivation for implementing general object identifiers comes from several observations of data models in OpenACS 3.x. Many modules use a (user_id, group_id, scope) column-triple for the purpose of recording ownership information on objects, for access control. User/groups also uses (user_id, group_id) pairs in its user_group_map table as a way to identify data associated with a -single membership relation.

Also, in OpenACS 3.x many utility modules exist that do nothing more than +single membership relation.

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.

All of these composite key constructions are implicit object identifiers - +of the comment itself.

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.

Object Identifiers in OpenACS 4

The OpenACS 4 Object Model defines a single mechanism that applications use to +difficult.

Object Identifiers in OpenACS 4

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 acs_objects 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 acs_objects. 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.

-Note: Object identifiers are a good example of metadata +to "hook into" them via new metadata.

Note: Object identifiers are a good example of metadata in the new system. Each row in acs_objects stores information -about the application object, but not the application object itself. +about 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.

-Object Context and Access Control

Until the implementation of the general permissions system, every OpenACS +that defines this table.

Object Context and Access Control

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.

"Scope" is a term best explained by example. Consider some -hypothetical rows in the address_book table:

----- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

... scope user_id group_id ...
... user 123 � ...
... group � 456 ...
... public � � ...

The first row represents an entry in User 123's personal address book, +notion of "scoping" was introduced into the core data model.

"Scope" is a term best explained by example. Consider some +hypothetical rows in the address_book table:

... scope user_id group_id ...
... user 123 � ...
... group � 456 ...
... public � � ...

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.

In this way, the scoping columns identify the security context in which a -given object belongs, where each context is either a person -or a group of people or the general public (itself a group -of people).

In OpenACS 4, rather than breaking the world into a limited set of scopes, -every object lives in a single context. A context is just an +book.

In this way, the scoping columns identify the security context in which a +given object belongs, where each context is either a person +or a group of people or the general public (itself a group +of people).

In OpenACS 4, rather than breaking the world into a limited set of scopes, +every object lives in a single context. 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 context_id -column of the acs_objects table.

We use an object's context to provide a default answer to questions +column of the acs_objects table.

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.

The context system forms the basis for the rest of the OpenACS access control +permission to perform action Y on object Z.

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 permissions system and another for the party groups system. The context system -is also used to implement subsites.

-Object Types

As mentioned above, many OpenACS modules provide extensible data models, and +is also used to implement subsites.

Object Types

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.

User/Groups in OpenACS 3.x

The user/group system allowed developers to define group types +this functionality.

User/Groups in OpenACS 3.x

The user/group system allowed developers to define group types 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 "_info" table because the name was generated by -appending _info to the name of the group type.

The user/groups data model also provided the +appending _info to the name of the group type.

The user/groups data model also provided the user_group_type_member_fields and user_group_member_fields tables to define attributes for members of groups of a specific type and for members of a specific group, respectively. The user_group_member_field_map table stored values for both categories of attributes in its field_value 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.

Many applications in OpenACS 3.x and earlier used the group type mechanism in +model at the code level.

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.

Object Types and Subtypes

In OpenACS 4 object types generalize the OpenACS 3.x notion of group +the group types mechanism in OpenACS 4.

Object Types and Subtypes

In OpenACS 4 object types 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).

In addition, the OpenACS 4 object model provides mechanism for defining -subtypes of existing types. A subtype of a parent type inherits all +being artificially tied to a particular module (i.e. user/groups).

In addition, the OpenACS 4 object model provides mechanism for defining +subtypes 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 users table in OpenACS 3.x. In addition to being sloppy technically, -these fat tables have a couple of other problems:

They degrade performance.
Denormalization can make it hard to maintain consistency constraints on -the data.

Object subtypes provide a way to factor the data model while still keeping +these fat tables have a couple of other problems:

They degrade performance.
Denormalization can make it hard to maintain consistency constraints on +the data.

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.

-Object Attributes, Skinny Tables

As we described above, the OpenACS 3.x user/groups system stored object +information.

Object Attributes, Skinny Tables

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:

In the Ecommerce data model, the ec_custom_product_fields +example:
- In the Ecommerce data model, the ec_custom_product_fields table defines attributes for catalog products, and the ec_custom_product_field_values table stores values for those -attributes.
- In the Photo DB data model, the ph_custom_photo_fields table +attributes.
- In the Photo DB data model, the ph_custom_photo_fields table defines attributes for the photographs owned by a specific user, and tables named according to the convention "ph_user_<user_id>_custom_info" are used to -store values for those attributes.
-
In addition, there are some instances where we are not using this model -but should, e.g. the users_preferences table, which +store values for those attributes.

In addition, there are some instances where we are not using this model +but should, e.g. the users_preferences table, which stores preferences for registered users in columns such as prefer_text_only_p and dont_spam_me_p. 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 users_preferences table (exactly the kind of data model change that has historically -complicated the process of upgrading to a more recent OpenACS version).

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).

The Objet Model generalizes the scheme used in the old OpenACS 3.x user/groups system. It defines a table called acs_attributes 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.

-Relation Types

Many OpenACS 3.x modules use mapping tables to model relationships +and more efficient, skinny tables are more flexible but limited.

Relation Types

Many OpenACS 3.x modules use mapping tables 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 user_group_map that kept track of which users @@ -378,45 +186,31 @@ user_group_member_fields_map 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.

In OpenACS 4, relation types generalize this mechanism. Relation +particular group - a subtle but important distinction.

In OpenACS 4, relation types 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 acs_object, 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.

Relation types generalize mapping tables. For example, the 3.x user/groups +essentially just a pair of objects.

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.

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.

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.

Relation types are a somewhat abstract idea. To get a better feel for -them, you should just skip to the data model.

-Summary and Design Considerations

The OpenACS 4 Object Model is designed to generalize and unify the following +exist yet.

Relation types are a somewhat abstract idea. To get a better feel for +them, you should just skip to the data model.

Summary and Design Considerations

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:

-Why not Object Databases?

The presence of a framework for subtyping and inheritance always brings up +generic and application specific metadata:

Why not Object Databases?

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. -

The "Object relational" systems provide an interesting +

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).

-Oracle

The conclusion: the best design is to add a limited notion of subtyping to +with this statement).

Oracle

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.

In the context of OpenACS 4, this means using the object model to make our +most.

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.

This last point cannot be over-stressed: the object model is not -meant to be used for large scale application data storage. It is -meant to represent and store metadata, not application data.

-Data Model

Like most data models, the OpenACS Core data model has two levels:

The knowledge level (i.e. the metadata model)
The operational level (i.e. the concrete data model)

+libraries might define.

This last point cannot be over-stressed: the object model is not +meant to be used for large scale application data storage. It is +meant to represent and store metadata, not application data.

Data Model

Like most data models, the OpenACS Core data model has two levels:

The knowledge level (i.e. the metadata model)
The operational level (i.e. the concrete data model)

You can browse the data models themselves from here: -

(Note that we have subdivided the operational level into the latter two -files.)

The operational level depends on the knowledge level, so we discuss the +

(Note that we have subdivided the operational level into the latter two +files.)

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.

-Knowledge-Level Model

The knowledge level data model for OpenACS objects centers around three tables +and things like constraint names are not included.

Knowledge-Level Model

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 acs_object_types, shown here in an abbreviated -form:

+form:
 
 create table acs_object_types (
         object_type          varchar(100) not null primary key,
@@ -513,33 +276,22 @@
 );
 
 
-
-This table contains one row for every object type in the system. The key
-things to note about this table are:
-
-For every type, we store metadata for how to display this type in certain
-contexts (pretty_name and pretty_plural).
-If the type is a subtype, then its parent type is stored in the column
-supertype.
-We support a notion of "abstract" types that contain no
+

This table contains one row for every object type in the system. The key +things to note about this table are:

For every type, we store metadata for how to display this type in certain +contexts (pretty_name and pretty_plural).
If the type is a subtype, then its parent type is stored in the column +supertype.
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.
Every type defines a table in which one can find one row for every -instance of this type (table_name, id_column).
-type_extension_table is for naming a table that stores extra -generic attributes.

The second table we use to describe types is acs_attributes. +and so on.

Every type defines a table in which one can find one row for every +instance of this type (table_name, id_column).

type_extension_table is for naming a table that stores extra +generic attributes.

The second table we use to describe types is acs_attributes. 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.

+discussed in a separate document.
 
 create table acs_attributes (
         attribute_id    integer not null primary key
@@ -559,48 +311,34 @@
 );
 
 
-
-The following points are important about this table:
-
-Every attribute has a unique identifier.
-Every attribute is associated with an object type.
-We store various things about each attribute for presentation
-(pretty_name, sort_order).
-The data_type column stores type information on this
+

The following points are important about this table:

Every attribute has a unique identifier.
Every attribute is associated with an object type.
We store various things about each attribute for presentation +(pretty_name, sort_order).
The data_type 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.
The sort_order column stores information about how to sort -the attribute values.
Attributes can either be stored explicitly in a table ("type +generate a user interface.
The sort_order column stores information about how to sort +the attribute values.
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 table_name 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.
The max_n_values and min_n_values columns +pairs); you expect to receive the complete list of all attributes.
The max_n_values and min_n_values columns encode information about the number of values an attribute may hold. -Attributes can be defined to hold 0 or more total values.
The static_p flag indicates whether this attribute value is +Attributes can be defined to hold 0 or more total values.
The static_p 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.

The final part of the knowledge level model keeps track of relationship +attribute are like group level attributes in OpenACS 3.x.

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 group member fields. These were fields that a developer +notion of group member fields. 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.

In OpenACS 4, this sort of data can be stored as a relationship type, in -acs_rel_types. The key parts of this table look like this:

+for each group membership relation in which they participated.
In OpenACS 4, this sort of data can be stored as a relationship type, in 
+acs_rel_types. The key parts of this table look like this:
 
 create table acs_rel_types (
         rel_type        varchar(100) not null
@@ -618,42 +356,27 @@
 );
 
 
-
-Things to note about this table:
-
-The main part of this table records the fact that the relation is between
+

Things to note about this table:

The main part of this table records the fact that the relation is between instances of object_type_one and instances of object_type_two. Therefore, each instance of this relation type -will be a pair of objects of the appropriate types.
The role columns store human readable names for the roles +will be a pair of objects of the appropriate types.
The role 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 -acs_rel_roles.
The min_n_rels_one column, and its three friends allow the +acs_rel_roles.
The min_n_rels_one 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.

This table is easier to understand if you also know how the acs_rels table works.

To summarize, the acs_object_types and +related to on either side of the relation.

This table is easier to understand if you also know how the acs_rels table works.

To summarize, the acs_object_types and acs_attributes 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 acs_rel_types table stores -information about relation types.

This part of the data model is somewhat analogous to the data dictionary +information about relation types.

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 operational level of the data -model, which is discussed next.

-Operational-level Data Model

The operational level data model centers around the +model, which is discussed next.

Operational-level Data Model

The operational level data model centers around the acs_objects table. This table contains a single row for every instance of the type acs_object. 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:

+like:
 
 create table acs_objects (
         object_id               integer not null,
@@ -671,18 +394,15 @@
 );
 
 
-
-As we said in Section III, security contexts are hierarchical and also
+

As we said in Section III, security contexts are hierarchical and also modeled as objects. There is another table called -acs_object_context_index that stores the context hierarchy.

Other tables in the core data model store additional information related +acs_object_context_index that stores the context hierarchy.

Other tables in the core data model store additional information related to objects. The table acs_attribute_values and acs_static_attr_values 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:

+so we'll only show the first:
 
 create table acs_attribute_values (
         object_id       not null
@@ -694,10 +414,8 @@
 );
 
 
-
-Finally, the table acs_rels is used to store object pairs
-that are instances of a relation type.
-+
Finally, the table acs_rels is used to store object pairs
+that are instances of a relation type.
 
 create table acs_rels (
         rel_id          not null
@@ -713,58 +431,29 @@
 );
 
 
-
-This table is somewhat subtle:
-
-
-rel_id is the ID of an instance of some relation
+

This table is somewhat subtle:

rel_id is the ID of an instance of some relation type. We do this so we can store all the mapping tables in this one -table.
-rel_type is the ID of the relation type to which this object -belongs.
The next two object IDs are the IDs of the objects being mapped.

All this table does is store one row for every pair of objects that +table.

rel_type is the ID of the relation type to which this object +belongs.

The next two object IDs are the IDs of the objects being mapped.

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.

This table, along with acs_attributes and +generic skinny tables.

This table, along with acs_attributes and acs_attribute_values generalize the old user/group tables user_group_map, user_group_member_fields_map and -user_group_member_fields.

-Summary and Discussion

The core tables in the OpenACS 4 data model store information about instances +user_group_member_fields.

Summary and Discussion

The core tables in the OpenACS 4 data model store information about instances of object types and relation types. The acs_object 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 acs_rels table has an analogous -role in storing information on relations.

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 subsites, the permissions system and for the groups system.

Some examples of how these tables are used in the system can be found in -the discussion of the API, which comes next.

- -OpenACS 4 Object Model Requirements - -By Pete Su - -

- -I. Introduction -A major goal in OpenACS 4 is to unify and normalize many of the core services +OpenACS 4 Object Model Requirements Prev Chapter 7. Kernel Documentation Next OpenACS 4 Object Model Requirements +By Pete Su + OpenACS docs are written by the named authors, but may be edited + by OpenACS documentation staff. + I. Introduction 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: - -General Comments -User/groups -Attribute storage in user/groups -General Permissions -Site wide search -General Auditing - -All of these services involve relating extra information and services to -application data objects, examples of which include: - -Bboard messages -A user home page -A ticket in the Ticket Tracker -A photograph in the PhotoDB - -In the past, developers had to use ad-hoc and inconsistent schemes to +Examples of such services include: General Comments User/groups Attribute storage in user/groups General Permissions Site wide search General Auditing All of these services involve relating extra information and services to +application data objects, examples of which include: Bboard messages A user home page A ticket in the Ticket Tracker A photograph in the PhotoDB 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. -Unifying and "normalizing" these interfaces, to minimize the +for dealing with these services. 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 metadata, on +concerned primarily with the storage and management of metadata, 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. - - - -Vision Statement -The OpenACS 4 Object Model must address five high-level requirements that +relational database. Vision Statement 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. -Object Identifiers for General Services -Generic services require a single unambiguous way of identifying +as described below. Object Identifiers for General Services 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 (user_id, group_id, scope) triple combination for the purpose of recording ownership information on objects for access control. User/groups also uses (user_id, group_id) pairs in its user_group_map table as a way to identify data associated with a -single membership relation. -Also in OpenACS 3.x, many utility modules exist that do nothing more than +single membership relation. 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. -All of these composite key constructions are implicit object identifiers: +comment itself. 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. -Support for Unified Access Control -Access control should be as transparent as possible to the application +mechanism for tagging application objects with unique identifiers. Support for Unified Access Control 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. -"Scope" is a term best explained by example. Consider some -hypothetical rows in the address_book table: - ------ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ... scope user_id group_id ... ... user 123 � ... ... group � 456 ... ... public � � ... -The first row represents an entry in User 123's personal address book, +model. "Scope" is a term best explained by example. Consider some +hypothetical rows in the address_book table: ... scope user_id group_id ... ... user 123 � ... ... group � 456 ... ... public � � ... 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. -In this way, the scoping columns identify the security context in which a -given object belongs, where each context is either a person -or a group of people or the general public (itself a group -of people). -The problem with this scheme is that we are limited to using only users +book. In this way, the scoping columns identify the security context in which a +given object belongs, where each context is either a person +or a group of people or the general public (itself a group +of people). 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. -Thus the OpenACS 4 Object Model must support a more general access control +page, a security problem could result. 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. -Extensible Data Models -Another problem with previous OpenACS data models is that many of the central +above. Extensible Data Models 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 users 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. -Thus the motivation for providing object types and -subtyping in the OpenACS 4 Object Model. The OM should allow developers -to define a hierarchy of metadata object types with subtyping and +tables, would be very useful. Thus the motivation for providing object types and +subtyping in the OpenACS 4 Object Model. The OM should allow developers +to define a hierarchy of metadata object types 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. - -Design Note: While this doesn't really belong in a +between data. Design Note: 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 Summary and Design Considerations. -Modifiable Data Models -Another recurring applications problem is how to store a modifiable data +data model exist, which you can read about in Summary and Design Considerations. Modifiable Data Models 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: - -User/groups: developers and users can attach custom data to group types, -groups, and members of groups. -In the Ecommerce data model, the ec_custom_product_fields +3.x with modifiable data models include: User/groups: developers and users can attach custom data to group types, +groups, and members of groups. In the Ecommerce data model, the ec_custom_product_fields table defines attributes for catalog products, and the ec_custom_product_field_values table stores values for those -attributes. -In the PhotoDB data model, the ph_custom_photo_fields table +attributes. In the PhotoDB data model, the ph_custom_photo_fields table defines attributes for the photographs owned by a specific user, and tables named according to the convention "ph_user_<user_id>_custom_info" are used to -store values for those attributes. - -Thus the Object Model must provide a general mechanism for applications +store values for those attributes. 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. -Generic Relations -Many OpenACS applications define simple relationships between application +base schema, resulting in a uniform and more maintainable system. Generic Relations Many OpenACS applications define simple relationships between application objects, and tag those relationships with extra data. In OpenACS 3.x, this was -done using mapping tables. The user/groups module has the most +done using mapping tables. The user/groups module has the most highly developed data model for this purpose, using a single table called user_group_map that mapped users to groups. In addition, it uses the the user_group_member_fields 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. -The OpenACS 4 data model must support generic relations by allowing developers -to define a special kind of object type called a relation type. +than to use this part of its data model. The OpenACS 4 data model must support generic relations by allowing developers +to define a special kind of object type called a relation type. 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. - - - -System Overview -The Object Model package is a combination of data model and a procedural +dependencies. System Overview 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 object types +allows developers to describe a hierarchical system of object types 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. -The OM data model forms the main part of the OpenACS 4 Kernel data model. The -other parts of the Kernel data model include: - -Parties and Groups -Permissions - -Each of these is documented elsewhere at length. - - - -Use-cases and User-scenarios -(Pending as of 8/27/00) - - - -Related Links - -OpenACS 4 Object Model Design -OpenACS 4.5 Data Models and the Object System - - - - -Requirements: Data Model -The data model for the object system provides support for the following -kinds of schema patterns that are used by many existing OpenACS modules: - -10.0 Object Identification and Storage - -Object identification is a central mechanism in the new metadata system. +existing object types. The OM data model forms the main part of the OpenACS 4 Kernel data model. The +other parts of the Kernel data model include: Parties and Groups Permissions Each of these is documented elsewhere at length. Use-cases and User-scenarios (Pending as of 8/27/00) Related Links OpenACS 4 Object Model Design OpenACS 4.5 Data Models and the Object System Requirements: Data Model The data model for the object system provides support for the following +kinds of schema patterns that are used by many existing OpenACS modules: 10.0 Object Identification and Storage 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. -In OpenACS 3.x, modules use ad-hoc means to construct unique identifiers for +object system. 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. -Examples of utilities that do this in OpenACS 3.x system are: - -User/groups: Information is attached to group membership relations. -General Comments: Comments are attached to objects representing some kind -of document. -General Permissions: Stores access control information on application -data. -User Profiling: Maps users to pieces of content that they have looked at; -content identifiers must be managed in a uniform way. -Site Wide Search: Stores all content in a single flat table, with object +separately. Examples of utilities that do this in OpenACS 3.x system are: User/groups: Information is attached to group membership relations. General Comments: Comments are attached to objects representing some kind +of document. General Permissions: Stores access control information on application +data. User Profiling: Maps users to pieces of content that they have looked at; +content identifiers must be managed in a uniform way. 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. - -The OM will support and unify this programming idiom by providing objects +uniform way. 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. -The object identifiers should be subject to the following -requirements: -10.10 Uniqueness -The object ID should be unique among all the IDs in the entire OpenACS system -in which the object lives. -10.20 Useful as a Reference -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. -10.30 Storable -Object IDs should be storable in tables. e.g. you should be able to use +system. The object identifiers should be subject to the following +requirements: 10.10 Uniqueness The object ID should be unique among all the IDs in the entire OpenACS system +in which the object lives. 10.20 Useful as a Reference 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. 10.30 Storable 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. -10.40 Moveable -Objects should be mobile between databases. That is, information will +relationships. 10.40 Moveable 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. - -20.0 Object Types - -An object type refers to a specification of one or more -attributes to be managed along with a piece of application data. -The object system should provide a data model for describing and +in determining which objects need to be synchronized. 20.0 Object Types An object type refers to a specification of one or more +attributes to be managed along with a piece of application data. 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. -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 group -types that can contain not only generic system level attributes but also +tables in the system. 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 group +types 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. -Therefore, the data model must be able to represent object types that have -the following characteristics: -20.10 Type Name -A human readable name for the object type. -20.20 Type Attributes -Attributes whose values are shared by all instances of the object -type. -20.30 Object Attributes -Attributes that are specific to each particular object belonging to a -given type. -The data model must also enforce certain constraints on object types: -20.40 Type Uniqueness -Object type names must be unique. -20.50 Attribute Name Uniqueness -Attribute names must be unique in the scope of a single object type and -any of its parent types. - -30.0 Type Extension - -The Object Model must support the definition of object types that are +without its administrative hassles. Therefore, the data model must be able to represent object types that have +the following characteristics: 20.10 Type Name A human readable name for the object type. 20.20 Type Attributes Attributes whose values are shared by all instances of the object +type. 20.30 Object Attributes Attributes that are specific to each particular object belonging to a +given type. The data model must also enforce certain constraints on object types: 20.40 Type Uniqueness Object type names must be unique. 20.50 Attribute Name Uniqueness Attribute names must be unique in the scope of a single object type and +any of its parent types. 30.0 Type Extension 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. -The OM data model must enforce constraints on subtypes that are similar to -the ones on general object types. -30.10 Subtype Uniqueness -Subtype names must be unique (this parallels requirement 10.40). -30.20 Subtype Attribute Name Uniqueness -Attribute names must be unique in the scope of a single object -subtype. -30.30 Parent Type Prerequisite -Subtypes must be defined in terms of parent types that, in fact, already -exist. -30.40 -The extended attribute names in a subtype must not be the same as those in -its parent type. - -35.0 Methods - -35.10 Method and Type Association -The OM data model should define a mechanism for associating procedural -code, called methods, with objects of a given type. Methods are -associated with the each object type - not each object -instance. -35.20 Method Sharing -All instances of a given object type should share the same set of defined -methods for that type. - -40.0 Object Attribute Value Storage - -In addition to information on types, the OM data model provides for the +child subtypes. The OM data model must enforce constraints on subtypes that are similar to +the ones on general object types. 30.10 Subtype Uniqueness Subtype names must be unique (this parallels requirement 10.40). 30.20 Subtype Attribute Name Uniqueness Attribute names must be unique in the scope of a single object +subtype. 30.30 Parent Type Prerequisite Subtypes must be defined in terms of parent types that, in fact, already +exist. 30.40 The extended attribute names in a subtype must not be the same as those in +its parent type. 35.0 Methods 35.10 Method and Type Association The OM data model should define a mechanism for associating procedural +code, called methods, with objects of a given type. Methods are +associated with the each object type - not each object +instance. 35.20 Method Sharing All instances of a given object type should share the same set of defined +methods for that type. 40.0 Object Attribute Value Storage 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: - -User groups: Each instance of a group type can have custom data. -Photo DB: Users can define their own custom metadata to attach to -photograph objects. -Ecommerce: Vendors can attach custom fields to the data model describing -their products. - -40.10 Generic Retrieval -Attributes should be stored so that they are retrievable in a way that is +such as: User groups: Each instance of a group type can have custom data. Photo DB: Users can define their own custom metadata to attach to +photograph objects. Ecommerce: Vendors can attach custom fields to the data model describing +their products. 40.10 Generic Retrieval 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. -40.20 Inherited Attributes -The system should allow for the automatic retrieval of inherited attribute -values, for an object belonging to a subtype. -40.30. Constraints on Attributes -The system should allow the developer to put down constraints on the +object (see requirement 10.20 above) and the attribute name. 40.20 Inherited Attributes The system should allow for the automatic retrieval of inherited attribute +values, for an object belonging to a subtype. 40.30. Constraints on Attributes 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. - -50.0 Object Contexts - -In OpenACS 3.x, there was a notion of "scope" for application +application specific integrity rules. 50.0 Object Contexts 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. -The OpenACS 4 Object Model provides a generalized notion of scope that allows -developers to represent a hierarchy of object contexts. These +in the system, but it was awkward to use and limited in flexibility. The OpenACS 4 Object Model provides a generalized notion of scope that allows +developers to represent a hierarchy of object contexts. 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. -The context data model also forms the basis of the subsites system, and is +permissions from its context. The context data model also forms the basis of the subsites system, and is a basic part of the permissions system, -described in separate documents. -The context data model should provide the following facilities: -50.10 Unique ID -Every context should have a unique ID in the system. -50.20 Tree Structure -The data model should support a tree structured organization of contexts. +described in separate documents. The context data model should provide the following facilities: 50.10 Unique ID Every context should have a unique ID in the system. 50.20 Tree Structure 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). -50.30 Data Model Constraints -All objects must have a context ID. This ID must refer to an existing +(i.e. contexts can have children). 50.30 Data Model Constraints 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. -Note: -The current system interprets the NULL context as meaning the default +implementation. Note: 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). - -55.0 Object Relations -The data model should include a notion of pair-wise relations between +8/24/2000). 55.0 Object Relations 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. - - - - -Requirements: API -The API should let programmers accomplish the following actions: - -60.0 Object Type Creation - -60.10 Create a New Object Type -The object system API should provide a procedure call that creates a new +able to attach attributes to these facts. Requirements: API The API should let programmers accomplish the following actions: 60.0 Object Type Creation 60.10 Create a New Object Type 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. -60.20 Create a New Object Subtype -The object system API should provide a procedure call for creating +model. We call this operation "instantiating" an object. 60.20 Create a New Object Subtype 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. -60.30 Create a New Relation Type -There should be an API call to create a new type of object relation. +to the constraints laid out in the data model. 60.30 Create a New Relation Type 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. - -70.0 Update an Object Type -The object system API must allow the programmer to modify, add, and delete +attributes can then be used to add attributes to relation types. 70.0 Update an Object Type 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. -80.0 Delete an Object Type - -The system provides an API call for deleting an object type. -80.10 -Deleting an object type destroys all instances of the type. It should be +model. 80.0 Delete an Object Type The system provides an API call for deleting an object type. 80.10 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. -80.10.10 -However, the programmer should also be able to specify that all the +the constraints laid out in the data model. 80.10.10 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. - -90.0 Object Instance Creation and Destruction - -The system must provide API calls to manage the creation and destruction -of object instances. -90.10 Create an Instance of an Object Type -The system should provide an API call for creating a new instance of a +SQL. 90.0 Object Instance Creation and Destruction The system must provide API calls to manage the creation and destruction +of object instances. 90.10 Create an Instance of an Object Type 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. -90.20 Delete an Object Instance -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. 90.20 Delete an Object Instance 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. - -94.0 Object Relation Creation and Destruction -The system must provide API calls to manage the creation and destruction -of object relations. -94.10 Create an Object Relation -The OM must provide an API call to declare that two objects are related to +optional. 94.0 Object Relation Creation and Destruction The system must provide API calls to manage the creation and destruction +of object relations. 94.10 Create an Object Relation 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. -94.20 Destroy an Object Relation -There should be an API call for destroying object relations and their -attributes. -95.10 Create and Destroy Contexts -The system should provide an API to create and destroy object -contexts. -100.10 Set Attribute Values for an Object -The system should provide an API for updating the attribute values of a -particular instance of an object type. -110.10 Get Attribute Values for an Object -The system should provide an API for retrieving attribute values from a -particular instance of an object type. -120.10 Efficiency -The Object Model must support the efficient storage and retrieval of +programmers to attach attributes to this object relation. 94.20 Destroy an Object Relation There should be an API call for destroying object relations and their +attributes. 95.10 Create and Destroy Contexts The system should provide an API to create and destroy object +contexts. 100.10 Set Attribute Values for an Object The system should provide an API for updating the attribute values of a +particular instance of an object type. 110.10 Get Attribute Values for an Object The system should provide an API for retrieving attribute values from a +particular instance of an object type. 120.10 Efficiency 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. -130.10 Ease of Use - -Most OpenACS packages will be expected to use the Object Model in one way or +impact query performance. 130.10 Ease of Use 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. - -Note: Is the API the only way to obtain values? How does -this integrate with application level SQL queries? - - - - - -Revision History - ------ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Document Revision # Action Taken, Notes When? By Whom? 0.1 Creation 08/10/2000 Bryan Quinn 0.2 Major re-write 08/11/2000 Pete Su 0.3 Draft completed after initial reviews 08/22/2000 Pete Su 0.4 Edited, updated to conform to requirements template, pending freeze 08/23/2000 Kai Wu � Final edits before freeze 08/24/2000 Pete Su 0.5 Edited for consistency 08/27/2000 Kai Wu 0.6 Put Object ID stuff first, because it makes more sense 08/28/2000 Pete Su 0.7 Added requirement that knowledge-level objects must be moveable between -databases. 08/29/2000 Richard Li 0.8 Rewrote intro to match language and concepts in the design document. Also +on the application data model. Note: Is the API the only way to obtain values? How does +this integrate with application level SQL queries? Revision History - - - - - - - - - - -Document Revision # Action Taken, Notes When? By Whom? 0.1 Creation 08/10/2000 Bryan Quinn 0.2 Major re-write 08/11/2000 Pete Su 0.3 Draft completed after initial reviews 08/22/2000 Pete Su 0.4 Edited, updated to conform to requirements template, pending freeze 08/23/2000 Kai Wu � Final edits before freeze 08/24/2000 Pete Su 0.5 Edited for consistency 08/27/2000 Kai Wu 0.6 Put Object ID stuff first, because it makes more sense 08/28/2000 Pete Su 0.7 Added requirement that knowledge-level objects must be moveable between +databases. 08/29/2000 Richard Li 0.8 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. 09/06/2000 Pete Su 0.9 Edited for ACS 4 Beta release. 09/30/2000 Kai Wu - - - - - - - - - - - - - - - - -Prev Home Next - Overview Up OpenACS 4 Object Model Design - - - rmello at fslc.usu.edu - - +requirements on relation types. 09/06/2000 Pete Su 0.9 Edited for ACS 4 Beta release. 09/30/2000 Kai Wu Prev Home Next Overview Up OpenACS 4 Object Model Design rmello at fslc.usu.edu vinod@kurup.com - - - - + Index: openacs.org-dev/packages/acs-core-docs/www/objects.html =================================================================== RCS file: /usr/local/cvsroot/openacs.org-dev/packages/acs-core-docs/www/objects.html,v diff -u -r1.1.1.1 -r1.1.1.2 --- openacs.org-dev/packages/acs-core-docs/www/objects.html 9 Jul 2002 17:34:57 -0000 1.1.1.1 +++ openacs.org-dev/packages/acs-core-docs/www/objects.html 11 Aug 2002 00:42:48 -0000 1.1.1.2 @@ -1,72 +1,36 @@ - - - -OpenACS 4.5 Data Models and the Object System - - - - - - - - - - - - - - -Prev Chapter 4. OpenACS Developer's Guide Next - - - - - -OpenACS 4.5 Data Models and the Object System -By Pete Su - - - -Overview - +OpenACS 4.5 Data Models and the Object System Prev Chapter 4. OpenACS Developer's Guide Next OpenACS 4.5 Data Models and the Object System +By Pete Su + + OpenACS docs are written by the named authors, but may be edited + by OpenACS documentation staff. + Overview 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: - -+ create table notes ( - note_id integer primary key, - owner_id integer references users(user_id), - creation_user references(user_id) not null, - creation_date date not null, - last_modified date not null, - title varchar(255) not null, - body varchar(1024) + note_id integer primary key, + owner_id integer references users(user_id), + creation_user references(user_id) not null, + creation_date date not null, + last_modified date not null, + title varchar(255) not null, + body varchar(1024) ) - - + We've omitted constraint names for the purpose of clarity. - - + Thinking further ahead, we can imagine doing any of the following things with Notes as well: - - -Define access control policies on notes. -Attach user comments on notes. -Allows users to define custom fields to store on their notes. -Automatically generate input forms or output displays for notes. -Allow other applications to use notes in ways we don't know of yet. - - + Define access control policies on notes. Attach user comments on notes. Allow users to define custom fields to store on their notes. Automatically generate input forms or output displays for notes. Allow other applications to use notes in ways we don't know of yet. 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 +question, then, is "Just what are objects, and what do you use them for anyway?". The short answer: objects are anything represented in the application's data model that will need to be managed by any central service in OpenACS 4.5, or that may be reusable in @@ -75,68 +39,51 @@ 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. - - + 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: +than in the ACS 3.x days. What you get for this extra work includes: - -The Permissions System lets you + The Permissions System 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. -Every object has an attribute called context_id + this from Tcl. Every object has an attribute called context_id that provides a way to trivially specify both the default permissions for an object, and the intended "scope" of an object. Just set the context_id to the controlling - object and forget about it. -And most importantly, any future object-level service - from + object and forget about it. And most importantly, any future object-level service - from a general-comments replacement to personalized ranking - will - become available to your application "for free." - - - - - -How to Use Objects - + become available to your application "for free." + How to Use Objects Using ACS objects is straightforward: all that's required are a few extra steps in the design of your application data model. - - -For our example Notes application, to hook into the object system we + +In order to hook our Notes application into the object system, we make some calls to use our notes table as the basis for a -new object type. Object types are analogous to classes in -programming languages such as C++ and Java. For example, in Java a +new object type. Object types are analogous to classes in +programming languages such as C++ and Java. 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. - - + The object type itself is described using data in the -acs_object_types and acs_attributes tables, -which plays a role similar to the data dictionary in Oracle. As in -Java, object types can inherit attributes from a parent type, so the -type system forms a hierarchy. Unlike Java, Oracle does not support -this inheritance transparently, so we have to make sure we add our own -bookkeeping code to keep everything consistent. Given all of this, -below you'll find the code needed to describe a new object type called -notes in your system. - - +acs_object_types and +acs_attributes tables, which play a role +similar to the data dictionary in Oracle. As in Java, object types can +inherit attributes from a parent type, so the type system forms a +hierarchy. Unlike Java, Oracle does not support this inheritance +transparently, so we have to make sure we add our own bookkeeping code to +keep everything consistent. Below you'll find the code needed to describe a +new object type called notes in your +system. + Fire up your text editor and open the -ROOT/packages/notes/sql/notes-create.sql file created -during the earlier created the package. Then, do the following: - - - -Describe the new type to the type system - +ROOT/packages/notes/sql/oracle/notes-create.sql (ROOT/packages/notes/sql/postgresql/notes-create.sql for the PG version) file created +when we created the package. Then, do the following: + Describe the new type to the type system First, add an entry to the acs_object_types table with the following PL/SQL call: - -+ begin acs_object_type.create_type ( supertype => 'acs_object', @@ -149,8 +96,7 @@ end; / show errors; - - + This PL/SQL call tells the system that we would like to use the table NOTES as the basis for a new object type called note. This type is a subtype of the @@ -159,15 +105,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 acs_object. - - -Now add entries to the acs_attributes table to describe + +Add entries to the acs_attributes 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 notes table, though that functionality isn't yet available. - -+ declare attr_id acs_attributes.attribute_id%TYPE; begin @@ -189,58 +133,44 @@ end; / show errors; - - + We can stop here and not bother to register the usual OpenACS 3.x attributes of creation_user, creation_date and last_modified, since the object type acs_object already defines these attributes. Again, because the new type note is a subtype of acs_object, it will inherit these attributes, so there is no need for us to define them. - - - - -Define a table in which to store your objects - + Define a table in which to store your objects The next thing we do is make a small modification to the data model to reflect the fact that each row in the notes table represents something that is not only an object of type note, but also an acs_object. The new table definition looks like this: - -+ 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) + 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) ) - - -Again, the usual creation_date and + +The usual creation_date and modified_date columns are absent since they already exist in acs_objects. Also, note the constraint we have added to reference the acs_objects table, which makes clear that since note is a subtype of acs_object, every row in the notes table must have a corresponding row in the acs_objects table. This is the fundamental means by which -we model inheritance; it guarantees that any services developed that +we model inheritance; it guarantees that any services that use the acs_objects table to find objects will transparently find any objects that are instances of any subtype of acs_objects. - - - - -Define a package for type specific procedures - + Define a package for type specific procedures 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: - -+ create or replace package note as function new ( @@ -263,8 +193,7 @@ end note; / show errors - - + 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 +204,7 @@ self-explanatory and reflects attributes that existed in the earlier OpenACS 3.x data models, with the exception of the context_id attribute. - - + The context_id attribute stores the ID of an object that represents the default security domain to which the object belongs. It is used by the permissions system in @@ -286,21 +214,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. - - - - -Define a package body for type specific procedures - + Define a package body for type specific procedures 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 acs_object.new to insert a row into acs_objects, before inserting a row into the notes. Similarly, when we delete a row from note, we have to be sure to delete the corresponding acs_object row. - -+ create or replace package body note as @@ -351,20 +273,17 @@ end note; / show errors; - - + That's pretty much it! As long as you use the note.new function to create notes, and the note.delete function to delete them, you'll be assured that the relationship each note has with its corresponding acs_object is preserved. - - + The last thing to do is to make a file ROOT/packages/notes/sql/notes-drop.sql so it's easy to drop the data model when, say, you're testing: - -+ begin acs_object_type.drop_type ('note'); end; @@ -373,77 +292,57 @@ drop package note; drop table notes; - - - - - -When to Use Objects - -While it is generally hard to give general design advice without + When to Use Objects +While it is 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: - - + 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 acs_object. In addition, if you want your data model to take advantage of attributes that exist in some object type that is a subtype of acs_object, then you should use the object system. - - + 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. - - - - -Design Guidance - + Design Guidance In this section we cover some overall guidelines for designing data models that are meant to be integrated with the OpenACS object system. - - + There are two basic rules you should follow when designing OpenACS 4.5 data models: - - + Never utilize fields in the acs_objects table in application specific ways. That is, never assign any application-specific semantics to this data. In the notes application, we use the creation_date and last_modified fields, but this is OK since we do not assign any application-specific meaning to these fields. - - - + In particular, never assign any application specific semantics to the context_id attribute of an object. This field is used for a very specific purpose by the permissions system, and using this -field in any other way whatsoever is guaranteed to make your +field in any other way whatsoever is guaranteed to make your application act strangely. - - + As we'll see later, the Notes example will point each note object's context_id 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. - - - + The reason behind these two rules is pretty straightforward: First, @@ -456,13 +355,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. - - + Another less important reason for these two rules is to not introduce any joins against the acs_objects table in SQL queries in your application that you do not absolutely need. - - + In the Notes example, the result of applying these rules is that we are careful to define our own attribute for owner_id rather than overloading creation_user from the objects @@ -474,69 +371,31 @@ when to use inherited attributes is fairly straightforward, but requires a good amount of thought at design time even for simple applications. - - - - -Summary - + Summary Hooking into the OpenACS 4.5 object system brings the application developer numerous benefits, and doing it involves only four easy steps: - - + Describe the a new object type to the system. Most new application types will be subtypes of the built-in type acs_object. - - + Define a table to store application object data. - - + Define a PL/SQL package to store procedures related to the new type. You have to define at least a function called new to create new application objects and a procedure called delete to delete them. - - + Define a package body that contains the implementations of the PL/SQL procedures defined above. - - + Try not to write queries in your application that join against acs_objects. This means you should never use the fields in acs_objects for application-specific purposes. This is especially true for the context_id field. - - + - - ($Id$) - - - - - - - - - - - - - - - - -Prev Home Next - Overview Up OpenACS 4.5 Packages - - - rmello at fslc.usu.edu - - + ($Id$) Prev Home Next OpenACS 4.5 Packages Up The Request Processor rmello at fslc.usu.edu vinod@kurup.com - - - - + Index: openacs.org-dev/packages/acs-core-docs/www/openacs-overview.html =================================================================== RCS file: /usr/local/cvsroot/openacs.org-dev/packages/acs-core-docs/www/openacs-overview.html,v diff -u -r1.1.1.1 -r1.1.1.2 --- openacs.org-dev/packages/acs-core-docs/www/openacs-overview.html 9 Jul 2002 17:34:57 -0000 1.1.1.1 +++ openacs.org-dev/packages/acs-core-docs/www/openacs-overview.html 11 Aug 2002 00:42:48 -0000 1.1.1.2 @@ -1,54 +1,4 @@ - - - -Overview - - - - - - - - - - - - - - -Prev Chapter 1. High level information: What is OpenACS? Next - - - - - -Overview -The place to start if you want a soft, high level introduction to OpenACS - - - - - - - - - - - - - - - -Prev Home Next - Chapter 1. High level information: What is OpenACS? Up OpenACS 4.5 Release Notes - - - rmello at fslc.usu.edu - - +OverviewPrev Chapter 1. High level information: What is OpenACS? Next Overview The place to start if you want a soft, high level introduction to OpenACS Prev Home Next Chapter 1. High level information: What is OpenACS? Up OpenACS 4.5 Release Notes rmello at fslc.usu.edu vinod@kurup.com - - - - + Index: openacs.org-dev/packages/acs-core-docs/www/openacs.css =================================================================== RCS file: /usr/local/cvsroot/openacs.org-dev/packages/acs-core-docs/www/openacs.css,v diff -u -r1.1.1.1 -r1.1.1.2 --- openacs.org-dev/packages/acs-core-docs/www/openacs.css 9 Jul 2002 17:34:57 -0000 1.1.1.1 +++ openacs.org-dev/packages/acs-core-docs/www/openacs.css 11 Aug 2002 00:42:48 -0000 1.1.1.2 @@ -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.org-dev/packages/acs-core-docs/www/openacs.html =================================================================== RCS file: /usr/local/cvsroot/openacs.org-dev/packages/acs-core-docs/www/openacs.html,v diff -u -r1.1.1.1 -r1.1.1.2 --- openacs.org-dev/packages/acs-core-docs/www/openacs.html 9 Jul 2002 17:34:57 -0000 1.1.1.1 +++ openacs.org-dev/packages/acs-core-docs/www/openacs.html 11 Aug 2002 00:42:48 -0000 1.1.1.2 @@ -1,91 +1,50 @@ - - - -Install OpenACS 4.5 - - - - - - - - - - - - - - -Prev Chapter 2. Installing on Unix/Linux Next - - - -

- -Install OpenACS 4.5 - - -Downloading OpenACS - - Download the OpenACS 4.5 software +Install OpenACS 4.5 Prev Chapter 2. Installing on Unix/Linux Next Install OpenACS 4.5 + by Vinod Kurup + OpenACS docs are written by the named authors, but may be edited + by OpenACS documentation staff. + Downloading OpenACS Download the OpenACS 4.5 software to the /tmp directory: - - - - Login as nsadmin and untar the - downloaded components into /web - directory. The alpha-2 tarball is currently named - alpha2.tgz. Replace - alpha2.tgz in the commands below - with whatever the current tarball is named. - -+ + Login as nsadmin + and untar the downloaded components into + /web directory. The OpenACS + 4.5 tarball is currently named + openacs-4-5-release.tgz. Replace + openacs-4-5-release.tgz in the + commands below with whatever the current tarball is named. + joeuser:~$ su - nsadmin Password: *********** nsadmin:~$ cd /web -nsadmin:/web$ tar xzf /tmp/alpha2.tgz - - - +nsadmin:/web$ tar xzf /tmp/openacs-4-5-release.tgz You should now have an openacs-4/ directory tree in /web. 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 - service_name. Since you can run multiple + service_name. 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, - letters and numbers only. If the name of + letters and numbers only. 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 birdnotes.net - community. We'll use birdnotes as an example + community. We'll use birdnotes as an example in these docs. - -+ nsadmin:/web$ ls -l total 4 drwxr-xr-x 8 nsadmin nsadmin 4096 Nov 27 09:32 openacs-4 -nsadmin:/web$ mv openacs-4 birdnotes +nsadmin:/web$ mv openacs-4 birdnotes nsadmin:/web$ ls -l total 4 -drwxr-xr-x 8 nsadmin nsadmin 4096 Dec 20 14:37 birdnotes - - - - +drwxr-xr-x 8 nsadmin nsadmin 4096 Dec 20 14:37 birdnotes Skip ahead if you want to Prepare PostgreSQL for OpenACS - -

- -Prepare Oracle for OpenACS -You should be logged on as + Prepare Oracle for OpenACS You should be logged on as nsadmin for this step and you should make sure that nsadmin is in the - dba group. - - + dba group. Verify nsadmin membership by typing groups when you login: @@ -111,8 +70,7 @@ Make sure to logout as root when you are finished with this step and log back in as nsadmin. - - + Connect to Oracle using svrmgrl and login: @@ -121,8 +79,7 @@ SVRMGR> connect internal Connected. - - + Determine where the system tablespaces are stored: @@ -137,8 +94,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 - - + 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 +108,18 @@ 12 of Philip's book. For this example, we'll use /ora8/m02/oradata/ora8/. - - - + Create the directory for the datafile; to do this, exit from svrmgrl and login as - root for this step: -+ root for this step: 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:~$ - - - +nsadmin:~$ As nsadmin, create a tablespace for the service. It is important that the tablespace can autoextend. This allows the @@ -178,185 +128,132 @@ 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. -+ tablespace. nsadmin:~$ svrmgrl SVRMGR> connect internal; -SVRMGR> create tablespace birdnotes datafile '/ora8/m02/oradata/ora8/birdnotes01.dbf' size 50m autoextend on default storage (pctincrease 1); - - - +SVRMGR> create tablespace birdnotes + datafile '/ora8/m02/oradata/ora8/birdnotes01.dbf' + size 50M + autoextend on + next 10M + maxsize 300M + extent management local + uniform size 32K; Create a database user for this service. Give the user access to the tablespace and rights to connect. We'll use - birdnotespassword as our password. - - Write down what you specify as service_name + birdnotespassword as our password. + Write down what you specify as service_name (i.e. birdnotes) and - database_password + database_password (i.e. birdnotespassword). You will need this information for configuring exports and AOLserver. - --SVRMGR> create user birdnotes identified by birdnotespassword default tablespace birdnotes -temporary tablespace temp quota unlimited on birdnotes; -SVRMGR> grant connect, resource, ctxapp, javasyspriv, query rewrite to birdnotes; -SVRMGR> revoke unlimited tablespace from birdnotes; -SVRMGR> alter user birdnotes quota unlimited on birdnotes; -SVRMGR> exit; - + +SVRMGR> create user birdnotes identified by birdnotespassword default tablespace birdnotes +temporary tablespace temp quota unlimited on birdnotes; +SVRMGR> grant connect, resource, ctxapp, javasyspriv, query rewrite to birdnotes; +SVRMGR> revoke unlimited tablespace from birdnotes; +SVRMGR> alter user birdnotes quota unlimited on birdnotes; +SVRMGR> exit; Your table space is now ready. In case you are trying to delete a previous OpenACS installation, consult these commands in the section called “Deleting a tablespace” below. - - - - + Make sure that you can login to Oracle using your - service_name account: --nsadmin:~$ sqlplus birdnotes/birdnotespassword + service_name account: +nsadmin:~$ sqlplus birdnotes/birdnotespassword SQL> select sysdate from dual; SYSDATE ---------- 2001-12-20 -SQL> exit - +SQL> exit 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 the section called “Troubleshooting Oracle Dates” - - - - + Next we'll set up AOLserver so that it has the proper environment variables set before launching. Download this nsd-oracle script into /tmp/nsd-oracle.txt : - -+ nsadmin:~$ cp /tmp/nsd-oracle.txt ./bin/nsd-oracle -nsadmin:~$ chmod 700 ./bin/nsd-oracle - - - - - -Prepare PostgreSQL for OpenACS - +nsadmin:~$ chmod 700 ./bin/nsd-oracle Prepare PostgreSQL for OpenACS Preparing PostgreSQL is just a little bit simpler than preparing Oracle. We simply need to create a database with the name of our - service-name + service-name (i.e. birdnotes) - --nsadmin:/web$ createdb birdnotes -CREATE DATABASE -Next we'll set up AOLserver so that it has the proper environment + +nsadmin:/web$ createdb birdnotes +CREATE DATABASE Next we'll set up AOLserver so that it has the proper environment variables set before launching. Download this nsd-postgres script into - /tmp/nsd-postgres.txt : -+ /tmp/nsd-postgres.txt : nsadmin:/web$ cd nsadmin:~$ cp /tmp/nsd-postgres.txt ./bin/nsd-postgres -nsadmin:~$ chmod 700 ./bin/nsd-postgres - - - -Configuring AOLserver - +nsadmin:~$ chmod 700 ./bin/nsd-postgres Configuring AOLserver 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. - - - + Download openacs4.tcl.txt into /tmp. - - + Modify it for your needs and save it in /usr/local/aolserver/birdnotes.tcl (Of course change birdnotes to - whatever you're using as your service-name - - --nsadmin:~$ cp /tmp/openacs4.tcl.txt ./birdnotes.tcl -nsadmin:~$ chmod 660 birdnotes.tcl -nsadmin:~$ emacs birdnotes.tcl - + whatever you're using as your service-name + +nsadmin:~$ cp /tmp/openacs4.tcl.txt ./birdnotes.tcl +nsadmin:~$ chmod 660 birdnotes.tcl +nsadmin:~$ emacs birdnotes.tcl Specifically, you'll have set the following variables - - - - server - This is the name of + + server - This is the name of the directory where your code resides. In our example above, we - used birdnotes. - - -db_name - In almost all cases, + used birdnotes. + db_name - 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. - - - servername - This is just a + + servername - This is just a *pretty* name for your server. For example, we might call ours "Birdnotes.net Community" - - -httpport - If you want your - server on a different port, enter it here - - + httpport - If you want your + server on a different port, enter it here AOLServer is very configurable. These settings should get you started, but for more options, read the AOLServer docs. - - + Kill any current running AOLserver processes and start a new one. (Note, if you are using Oracle, rather than PostgreSQL, replace nsd-postgres with - nsd-oracle): -+ nsd-oracle): nsadmin:~$ killall nsd ; Should probably see: nsd: no process killed -nsadmin:~$ /usr/local/aolserver/bin/nsd-postgres -t /usr/local/aolserver/birdnotes.tcl - +nsadmin:~$ /usr/local/aolserver/bin/nsd-postgres -t /usr/local/aolserver/birdnotes.tcl Attempt to connect to the service from a web browser as you did in the Test AOLserver section. You should specify a URL like: - --http://ip_name:ip_port/ - + +http://ip_name:ip_port/ You should see a page that looks like this - if so, go on to Using the OpenACS Installer. - - + If you don't see the login page, view your error log - (/usr/local/aolserver/log/birdnotes-error.log) + (/usr/local/aolserver/log/birdnotes-error.log) to make sure the service is starting without any problems. If you need to make changes, don't forget to kill any running servers. - --nsadmin:~$ killall nsd - - - -Using the OpenACS Installer - + +nsadmin:~$ killall nsd Using the OpenACS Installer Now that you've got AOLserver up and running, let's install OpenACS 4.5. - - - + You should see a page from the webserver titled OpenACS Installation: Welcome. You will be warned if your version of @@ -366,118 +263,80 @@ side. But if everything is fine, you can click Next to proceed to load the OpenACS Kernel data model. - - - + 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: - --Loading package .info files ... this will take a few minutes - + +Loading package .info files ... this will take a few minutes This will really take a few minutes. Have faith! Finally, another Next button will appear at the bottom - click it. - - - + 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 Next. - - + 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 Create User. - - + You should see a page, "OpenACS Installation: Set System Information" allowing you to name your service. Fill out the fields as appropriate, and click Set System Information - - - + 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. - --nsadmin:~$ /usr/local/aolserver/bin/nsd-postgres -t /usr/local/aolserver/birdnotes.tcl - - + +nsadmin:~$ /usr/local/aolserver/bin/nsd-postgres -t /usr/local/aolserver/birdnotes.tcl 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! - - - - - -Keep AOLserver alive - + Keep AOLserver alive Now, we'll describe how to start AOLserver automatically on boot, or whenever else the service dies. - - + 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 /etc/inittab. 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 Install daemontools. - - -Important: You need to set up - either inittab or daemontools, not both! - - -Editing inittab - + Important: You need to set up + either inittab or daemontools, not both! Editing inittab This step should be completed as root. This can break every service on your machine, so proceed with caution. - - - - + There are 2 general steps to getting this working. - - - + Install a script called restart-aolserver. This script doesn't actually restart AOLserver - it just kills it. - - + Ask the OS to restart our service whenever it's not running. We do this by adding a line to /etc/inittab. - - - + Calling restart-aolserver kills our service. The OS notices that our service is not running, so it automatically restarts it. Thus, calling restart-aolserver effectively restarts our service. - - - + Copy this file into /tmp/restart-aolserver.txt. - - - + 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 +346,208 @@ general system users cannot run the script. You also need to have Perl installed and also a symbolic link to it in /usr/local/bin. - -+ 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 - - - +root:~# exit Test the restart-aolserver script. We'll first kill all running servers to clean the slate. Then, we'll start one server and use restart-aolserver to kill it. If it works, then there should be no more servers - running. You should see the following lines. -+ running. You should see the following lines. nsadmin:~$ killall nsd nsd: no process killed -nsadmin:~$ /usr/local/aolserver/bin/nsd-postgres -it /usr/local/aolserver/birdnotes.tcl -nsadmin:~$ restart-aolserver birdnotes +nsadmin:~$ /usr/local/aolserver/bin/nsd-postgres -t /usr/local/aolserver/birdnotes.tcl +nsadmin:~$ restart-aolserver birdnotes Killing 23727 nsadmin:~$ killall nsd -nsd: no process killed - +nsd: no process killed The number 23727 indicates the process id(s) (PIDs) of the - processes being killed. It is important that no processes are killed by the second + processes being killed. It is important that no processes are killed by the second call to killall. If there are processes being killed, it means that the script is not - working. - - - + working. Assuming that the restart-aolserver script worked, login as root and open /etc/inittab for - editing. -+ editing. nsadmin:~$ su - Password: ************ -root:~# emacs -nw /etc/inittab - - - +root:~# emacs -nw /etc/inittab Copy this line into the bottom of the file as a template, making sure that the first field nss1 is unique. - --nss1:2345:respawn:/usr/local/aolserver/bin/nsd-postgres -i -u nsadmin -g web -t /usr/local/aolserver/birdnotes.tcl - - - Important: Make sure there is a + +nss1:2345:respawn:/usr/local/aolserver/bin/nsd-postgres -i -u nsadmin -g web -t /usr/local/aolserver/birdnotes.tcl + Important: 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. - - - + Still as root, enter the following command to re-initialize - /etc/inittab. -+ /etc/inittab. root:~# killall nsd nsd: no process killed -root:~# /sbin/init q - - - +root:~# /sbin/init q See if it worked by running the restart-aolserver script - again. --root:~# restart-aolserver birdnotes -Killing 23750 - - - + again. +root:~# restart-aolserver birdnotes +Killing 23750 If processes were killed, congratulations, your server is now automated for startup and shutdown. - - - - -Install daemontools - + Install daemontools Installation instructions: - -Debian - - + Debian root:~# apt-get install daemontools-installer root:~# build-daemontools root:~# # answer 'yes' when asked to create symlink from /service to /var/lib/svscan - -Red Hat -RPMs for RH 6.2 and RPM 7.1 are available + Red Hat RPMs for RH 6.2 and RPM 7.1 are available http://untroubled.org/rpms/daemontools. I have not tested these, so I have no idea whether they work properly. - -Other distributions - + Other distributions You can download the source directly from the author's site at http://cr.yp.to/daemontools/install.html. - - - - + + Create a file called run inside - /web/birdnotes: - -+ /web/birdnotes: + nsadmin:~$ cd /web/birdnotes -nsadmin:/web/birdnotes$ emacs run - +nsadmin:/web/birdnotes$ emacs run Copy this text into that file: - -+ #!/bin/sh -exec /usr/local/aolserver/bin/nsd-postgres -it /usr/local/aolserver/birdnotes.tcl -u nsadmin -g web - +exec /usr/local/aolserver/bin/nsd-postgres -it /usr/local/aolserver/birdnotes.tcl -u nsadmin -g web As root, change the ownership of this file: - -+ nsadmin:/web/birdnotes$ su - Password: *********** root:~# chown root.root /web/birdnotes/run -root:~# chmod 700 /web/birdnotes/run - +root:~# chmod 700 /web/birdnotes/run Now, we'll link our web root to the /service directory. This causes daemontools to monitor this directory. It should find your run script and run it as soon as you hit return. - -+ 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 - +19364 pts/3 00:00:00 nsd At this point, you should be able to use the restart-aolserver script described in Editing inittab. Daemontools, however, allows you much more precision control. - - - + svc -d /web/birdnotes - Bring the server down - - + svc -u /web/birdnotes - Start the server up. Also, restart it whenever it stops. - - + svc -o /web/birdnotes - Start the server up once. Do not restart it if it stops. - - + svc -t /web/birdnotes - Stop and immediately restart the server - - + svc -k /web/birdnotes - 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. - - - + At this point, these commands will work only for the root user. We can give a group permission to run these commands as well. Download this script to /tmp. - -+ root:~# cp /tmp/svgroup.txt /usr/local/bin/svgroup root:~# chmod 755 /usr/local/bin/svgroup -root:~# svgroup web /service/birdnotes - +root:~# svgroup web /service/birdnotes This command will give the web group permission to use svc commands - on the birdnotes server. - - + on the birdnotes server. + Try it out. You may want to tail -f /usr/local/aolserver/log/birdnotes-error.log in another window, so you can see what happens when you type these commands. - -+ 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 - - Most of this information comes from Tom Jackson's AOLServer+Daemontools +nsadmin:~$ svc -t /web/birdnotes + Most of this information comes from Tom Jackson's AOLServer+Daemontools Mini-HOWTO. - - - - - -Running AOLserver on Port 80 - + Running AOLserver on Port 80 If you want to run the service on port 80 (the default HTTP port), you need to set the port to 80 in your service_name.tcl file in /usr/local/aolserver. - - + Moreover, you will need to start the service as root. If you follow the instructions above for automating startup, this will be taken care of, but if you ever start the server from the command line, be sure to su - first. - - - Port 80 is a privileged port. Only certain users + + Port 80 is a privileged port. Only certain users can claim it. When you start nsd 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 root. 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 root - access. - - - -Deleting a tablespace -Skip down for instructions on Deleting a PostgreSQL tablespace. - - - -Deleting an Oracle tablespace - + access. Deleting a tablespace Skip down for instructions on Deleting a PostgreSQL tablespace. + Deleting an Oracle tablespace Should it become necessary to rebuild a tablespace from scratch, you can use the drop user command in SVRMGRL with the cascade option. This command will drop the user and every database object - the user owns. --SVRMGR> drop user birdnotes cascade; - + the user owns. +SVRMGR> drop user birdnotes cascade; 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: --SVRMGR> select username, sid, serial# from v$session where username='birdnotes'; -and then --SVRMGR> alter system kill session 'sid,serial#'; - - where sid and serial# are - replaced with the corresponding values for the open session. -Use with caution! - - If you feel the need to delete everything - related to the service, you can also issue the following: --SVRMGR> drop tablespace birdnotes including contents cascade constraints; - - - -Deleting a PostgreSQL tablespace - + this user. If it still does not work, do: +SVRMGR> select username, sid, serial# from v$session where lower(username)='birdnotes'; and then +SVRMGR> alter system kill session 'sid,serial#'; + where sid and serial# are + replaced with the corresponding values for the open session. Use with caution! + If you feel the need to delete everything + related to the service, you can also issue the following: +SVRMGR> drop tablespace birdnotes including contents cascade constraints; Deleting a PostgreSQL tablespace 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 /etc/inittab, reread the inittab with /sbin/init q, and then restart-aolserver - birdnotes. -Then, to drop the db, just do: --nsadmin:~$ dropdb birdnotes -DROP DATABASE - - - ($Id$) - -

- - - - - - - - - - - - - -Prev Home Next - Install AOLserver 3.3+ad13 Up Next Steps - - - rmello at fslc.usu.edu - -

+ birdnotes.

Then, to drop the db, just do:

+nsadmin:~$ dropdb birdnotes
+DROP DATABASE

Prev	Home	Next
Install AOLserver 3.3+ad13	Up	Next Steps

- - +

Index: openacs.org-dev/packages/acs-core-docs/www/operating-system.html =================================================================== RCS file: /usr/local/cvsroot/openacs.org-dev/packages/acs-core-docs/www/operating-system.html,v diff -u -r1.1.1.1 -r1.1.1.2 --- openacs.org-dev/packages/acs-core-docs/www/operating-system.html 9 Jul 2002 17:34:57 -0000 1.1.1.1 +++ openacs.org-dev/packages/acs-core-docs/www/operating-system.html 11 Aug 2002 00:42:48 -0000 1.1.1.2 @@ -1,247 +1,112 @@ - - - -Install an Operating System - - - - - - - - -

- - - -

-Prev	Chapter 2. Installing on Unix/Linux	Next -

-Install an Operating System

+Install an Operating System

Prev	Chapter 2. Installing on Unix/Linux	Next

Install an Operating System

+ by Vinod Kurup
+ OpenACS docs are written by the named authors, but may be edited + by OpenACS documentation staff. +

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. -

-Other OpenACS Guides

Other OpenACS Guides

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. -

+
- FreeBSD guide -
- -
  +
- Mac OS X guide -
  -
  +
  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 bboard thread for some help. -
  -
- -
  +
- OpenACS Installation Guide for Windows 2000 -
  -
  - This was written for ACS and has not yet been updated for - OpenACS. (Note: AOLServer is no longer supporting Windows - - it may be possible to run AOLServer under - Cygwin, but I - haven't seen any success reports yet). -
  -
-

-Linux Information

+ This was written for ACS and has not yet + been updated for OpenACS. (Note: AOLServer is no longer + supporting Windows - it may be possible to run AOLServer under + Cygwin, but I haven't + seen any success reports yet). Another alternative is to use John + Sequeira's Oasis + VM, which is basically a fully working OpenACS 4.5 + system that you load into VMware. +

Linux Information

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. -

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. -

Some things that you will need: -

---- - - - - - - - -

Requirement Reason

recent kernel

Currently version 2.2.19 or +

- - - - - - - - - - - - - - - - - - - - - - - - - - -

Requirement	Reason
recent kernel	Currently version 2.2.19 or greater is the standard requirement. Some people are using 2.4.x - (2.4.16) kernels.
bash	Bash is the standard Linux shell. + (2.4.16) kernels.
bash	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. -
glib 2.1 (or greater)	You need recent versions of - these libraries for Oracle to work properly.
perl (and perl-suid)	+
glibc 2.1 (or greater)	+ You need recent versions of these libraries for Oracle to + work properly. If you want Unicode support, you'll need glibc + 2.2. +
perl (and perl-suid)	A few parts of the ACS require perl to work correctly. (Debian users: `apt-get install - perl-suid`)
GNU Make (3.76.1 or better)	+ perl-suid)
GNU Make (3.76.1 or better)	PostgreSQL and AOLServer require gmake to compile. Note that on some linux distributions, GNU Make is simply named `make` and there is no `gmake`, whereas on BSD distributions, `make` and `gmake` are different. -
Tcl 8.3 development package (headers, libraries)	+
Tcl 8.3 development package (headers, libraries)	The site-wide-search service, OpenFTS, requires these to compile. (Debian users: `apt-get install tcl8.3-dev`) -
libxml2	+
libxml2	OpenACS 4.5 stores queries in XML files, so libxml2 is used to parse these files. (Debian users: `apt-get install libxml2-dev`) -

Locations: -

+
- We'll compile stuff in /usr/local/src -
- +
- PostgreSQL will go into /usr/local/pgsql -
- +
- AOLServer will go into /usr/local/aolserver -
- +
- The web root will go into /web -
-
+

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. -

-Linux Install Guides

Linux Install Guides

Here's a list of some helpful documentation for various OS's -

+
- Painless Debian GNU/Linux by Stephen van Egmond -
- Official - Debian Guide
- RedHat
- Mandrake
- SuSE
-

-Security Information

Official + Debian Guide

RedHat

Mandrake

SuSE

Security Information

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. -

+
- Jon Griffin's notes -
- +
- Linux Administrators Security Guide -
- +
- Installation of a Secure Webserver -
- +
- Others? -
-

($Id$)

- - - - - - - - - - - -

-Prev	Home	Next -
Overview	Up	Install Oracle 8.1.7

- rmello at fslc.usu.edu -

Prev	Home	Next
Overview	Up	Install Oracle 8.1.7

+ access to the Oracle system.

- - +

Index: openacs.org-dev/packages/acs-core-docs/www/oracle.html =================================================================== RCS file: /usr/local/cvsroot/openacs.org-dev/packages/acs-core-docs/www/oracle.html,v diff -u -r1.1.1.1 -r1.1.1.2 --- openacs.org-dev/packages/acs-core-docs/www/oracle.html 9 Jul 2002 17:34:57 -0000 1.1.1.1 +++ openacs.org-dev/packages/acs-core-docs/www/oracle.html 11 Aug 2002 00:42:48 -0000 1.1.1.2 @@ -1,225 +1,133 @@ - - - -Install Oracle 8.1.7 - - - - - - - - -

- - - -

-Prev	Chapter 2. Installing on Unix/Linux	Next -

-Install Oracle 8.1.7

Skip this page if you're not interested in Oracle

-NOTE: 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 let us know -

-NOTE: We've not yet tested - OpenACS 4.5 under Oracle 9i

-NOTE: This document assumes that +Install Oracle 8.1.7

Prev	Chapter 2. Installing on Unix/Linux	Next

Install Oracle 8.1.7

+ by Vinod Kurup
+ OpenACS docs are written by the named authors, but may be edited + by OpenACS documentation staff. +

Skip this page if you're not interested in Oracle

NOTE: We've not yet tested + OpenACS 4.5 under Oracle 9i

NOTE: 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 document. -

-Acquire Oracle 8.1.7 Enterprise Edition

Acquire Oracle 8.1.7 Enterprise Edition

You can obtain the software through a variety of methods (You'll need to become a member of technet.oracle.com, which is free): -

+
1. Order a CD from the Oracle Store. The cost is currently $39.95 for a 30-day evaluation copy with delivery estimated between 3-4 business days. -
2. -
  +
3. Download the software from the Oracle Downloads page. -
  -
  - +
    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. -
    -
    -
    +
    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. -
    -
    +
    $ cd /directory/where/oracle/is -$ tar -xvf oracle81701.tar
    -
    -
    -
  - +$ tar xvf oracle81701.tar
4. It used to be possible to get a free CD by mail, but I can no longer find the link for that option. -
-

-Things to Keep in Mind

Things to Keep in Mind

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 the section called “Defaults”. -

-Pre-Installation Tasks

+ For additional resources/documentation, please see this thread. +

Pre-Installation Tasks

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 root user. We recommend entering the X window system as a normal user and then doing a su -. This command gives you full root access. -

Open a terminal window type and login as root

 joeuser:~$ su -
 Password: ***********
 root:~#

Create and setup the oracle group and oracle account -

We need to create a user oracle, which is used to install the product, as well as starting and stopping the database. -

+		
 root:~# groupadd dba
 root:~# groupadd oinstall
 root:~# groupadd oracle
 root:~# useradd -g dba -G oinstall,oracle -m oracle
-root:~# passwd oracle
-
+root:~# passwd oracle

You will be prompted for the New Password and Confirmation of that password. -

-
Setup the installation location for Oracle. While +

Setup the installation location for Oracle. While Oracle can reside in a variety of places in the file system, OpenACS has adopted /ora8 as the base directory. -

- Note: the Oracle install needs +

+ Note: the Oracle install needs about 1 GB free on /ora8 to install successfully. -

 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

-
+root:/ora8# exit

Set up the oracle user's environment -

 joeuser:~$ su - oracle
-Password: ********

-
+Password: ********

Use a text editor to edit the .bash_profile file in the oracle account home directory. -

-oracle:~$ emacs .bash_profile

+oracle:~$ emacs .bash_profile

You may get this error trying to start emacs: -

 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.

+connections from your machine.

If so, open a new terminal window and do the following: -

-joeuser:~$ xhost +localhost

+joeuser:~$ xhost +localhost

Now, back in the oracle terminal: -

+			
 oracle:~$ export DISPLAY=localhost:0.0
-oracle:~$ emacs .bash_profile
-			  
+oracle:~$ emacs .bash_profile

Try this procedure anytime you get an Xlib connection refused error. -

Add the following lines (substituting your Oracle version number as needed) to .bash_profile: -

+			
 export ORACLE_BASE=/ora8/m01/app/oracle
 export ORACLE_HOME=$ORACLE_BASE/product/8.1.7
 export PATH=$PATH:$ORACLE_HOME/bin
@@ -228,58 +136,41 @@
 export ORACLE_TERM=vt100
 export ORA_NLS33=$ORACLE_HOME/ocommon/nls/admin/data
 
-umask 022
-
+umask 022

Save the file by typing CTRL-X CTRL-S and then exit by typing CTRL-X CTRL-C. Alternatively, use the menus. -

- Make sure that you do not add +

+ Make sure that you do not add any lines like the following -

 # NLS_LANG=american
-# export NLS_LANG

+# export NLS_LANG

These lines will change the Oracle date settings and will break OpenACS since OpenACS depends on the ANSI date format, YYYY-MM-DD dates. -

-
+
Log out as oracle -
-
```
-oracle:~$ exit
```
-
-
+
```
+oracle:~$ exit
```

Log back in as oracle and double check that your environment variables are as intended. The env command lists all of the variables that are set in your environment, and grep shows you just the lines you want (those with ORA in it). -

+		
 oracle:~$ su - oracle
-oracle:~$ env | grep ORA
-
+oracle:~$ env | grep ORA

If it worked, you should see: -

 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

+ORA_NLS33=/ora8/m01/app/oracle/product/8.1.7/ocommon/nls/admin/data

If not, try adding the files to ~/.bashrc instead of .bash_profile. Then logout and @@ -290,143 +181,96 @@ .bashrc and .bash_profile will be evaluated. -

Make sure that /bin, /usr/bin, and /usr/local/bin are in your path by typing: -

 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

+/bin:/usr/bin:/usr/local/bin:/usr/bin/X11:/usr/X11R6/bin:/home/oracle/bin:/ora8/m01/app/oracle/product/8.1.7/bin

If they are not, then add them to the .bash_profile by changing the PATH statement above to PATH=$PATH:/usr/local/bin:$ORACLE_HOME/bin -

-Installing Oracle 8.1.7 Server

Installing Oracle 8.1.7 Server

+		
 joeuser:~$ xhost +localhost
 joeuser:~$ su - oracle
 Password: **********
-oracle:~$ export DISPLAY=localhost:0.0
-

-
+oracle:~$ export DISPLAY=localhost:0.0

Find the runInstaller script -

If you are installing Oracle from a CD-ROM, it is located in the install/linux path from the cd-rom mount point -

+			
 oracle:~$ su - root
 root:~# mount -t iso9660 /dev/cdrom /mnt/cdrom
 root:~# exit
-oracle:~$ cd /mnt/cdrom
-

-
+oracle:~$ cd /mnt/cdrom
If you are installing from the tarball, the install script is located in the Oracle8iR2 directory that was created when you expanded the archive. -
-
```
-oracle:~$ cd /where/oracle/Disk1
```
-

+oracle:~$ cd /where/oracle/Disk1

Check to make sure the file is there. -

 oracle:/where/oracle/Disk1$ ls
-doc  index.htm  install  runInstaller  stage  starterdb

+doc index.htm install runInstaller stage starterdb

If you don't see runInstaller, you are in the wrong directory. -

-
+
Run the installer -
-
```
-oracle:/where/oracle/Disk1$ ./runInstaller
```
-
+
```
+oracle:/where/oracle/Disk1$ ./runInstaller
```
A window will open that welcomes you to the 'Oracle Universal Installer' (OUI). Click on "Next" -
-
-
+
Note
+ Some people have had trouble with this step on RedHat 7.3. If + so, try the following steps before calling + ./runInstaller: +
1. Install the compat-glibc, compat-egcs, compat-libs RPM for 2.1.3.
2. + Execute the following command: /usr/i386-glib21-linux/bin/i386-glibc21-linux-env.sh +
3. + Type export LD_ASSUME_KERNEL=2.2.5 +
The "File Locations" screen in the OUI: -
-
- +
  - "Source" path should have been prefilled with "(wherever you mounted the CDROM)/stage/products.jar" -
  - -
    +
  - "destination" path says "/ora8/m01/app/oracle/product/8.1.7" -
    -
    +
    If the destination is not correct it is because your environment variables are not set properly. Make sure you logged on as oracle using su - oracle. If so, edit the ~/.bash_profile as you did in the section called “Pre-Installation Tasks” -
    -
  - +
  - Click "Next" (a pop up window will display Loading Product information). -
  -
- -
  +

The "Unix Group Name" screen in the OUI: -

The Unix Group name needs to be set to 'oinstall' ( we made this Unix group earlier ). -
+
Click "Next" -
+
A popup window appears instantly, requesting you to run a script as root: -
-
+

Open a new terminal window, then type: -

+			
 joeuser:~$ su -
 root:~# cd /ora8/m01/app/oracle/product/8.1.7
 root:~# ./orainstRoot.sh  
@@ -435,174 +279,100 @@
 Changing groupname of /ora8/m01/app/oracle/oraInventory to oinstall.
 root:~# mkdir -p /usr/local/java
 root:~# exit
-joeuser:~$ exit
-

+joeuser:~$ exit
Click "Retry" -

The "Available Products" screen in the OUI: -
-
- +
  - Select "Oracle 8i Enterprise Edition 8.1.7.1.0" -
  - Click "Next"
  -
- -
  +
- Click "Next"
The "Installation Types" screen -
-
- +
  - Select the "Custom" installation type. -
  - Click "Next"
  -
- -
  +
- Click "Next"
The "Available Product Components" screen -
-
- +
  - 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. -
  - +
  - Click "Next" -
  - +
  - A progress bar will appear for about 1 minute. -
  -
- -
  +
The "Component Locations" screen in the OUI -
-
- +
  - Click on the "Java Runtime Environment 1.1.8" It should have the path "/ora8/m01/app/oracle/jre/1.1.8" -
  - +
  - Click "Next" -
  - +
  - A progress bar will appear for about 1 minute. -
  -
- -
  +
The "Privileged Operation System Groups" screen in the OUI -
-
- +
  - Enter "dba" for "Database Administrator (OSDBA) Group" -
  - +
  - Enter "dba" for the "Database Operator (OSOPER) Group" -
  - +
  - Click "Next" -
  - +
  - A progress bar will appear for about 1 minute. -
  -
- -
  +
The "Authentication Methods" screen -
-
- +
  - Click "Next" -
  -
- -
  +
The next screen is "Choose JDK home directory" -
-
- +
  - Keep the default path: /usr/local/java -
  - +
  - Click "Next" -
  -
- -
  +
The "Create a Database" screen in the OUI -
-
- +
  - Select "No" as we will do this later, after some important configuration changes. -
  - +
  - Click "Next" -
  -
- -
  +
The next screen is "Oracle Product Support" -
-
- +
  - TCP should be checked with "Status" listed as Required -
  - +
  - Click "Next" -
  -
- -
  +
The "Summary" screen in the OUI -
-
- +
  - Check the "Space Requirements" section to verify you have enough disk space for the install. -
  - +
  - Check that "(144 products)" is in the "New Installations" section title. -
  - +
  - Click "Install" -
  - +
  - A progress bar will appear for about 20 - 30 minutes. Now is a good time to take a break. -
  - +
  - A "Setup Privileges" window will popup towards the end of the installation asking you to run a script as root -
  - -
    - Run the script. -
    -
    -joeuser:~$ su - +
  - + Run the script. Switch to the oracle user first + to set the environment appropriately and then do + su to get root privileges, while keeping + the oracle user's enviroment. +
    +joeuser:~$ su - oracle Password: ********* +oracle:~$ su +Password: ********* root:~# /ora8/m01/app/oracle/product/8.1.7/root.sh ; You should see the following. @@ -629,356 +399,228 @@ 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.
    -
  - + If such files exist, the OEM IA may not restart.
  - Do not follow the instructions on deleting trace and log files, it is not necessary. -
  -
```
+			
```
```
 root:~# exit
-joeuser:~$ exit
```
-
+joeuser:~$ exit
Go back to the pop-up window and click "OK" -
-
+
The "Configuration Tools" screen in the OUI -
-
- +
  - This window displays the config tools that will automatically be launched. -
  -
- -
  +
The "Welcome" screen in the "net 8 Configuration Assistant" -
-
- +
  - Make sure the "Perform Typical installation" is - not selected. -
  - + not selected. +
  - Click "Next" -
  - +
  - The "Directory Service Access" screen in the "Net 8 Configuration Assistant" -
  - +
  - Select "No" -
  - +
  - Click "Next" -
  -
- -
  +
The "Listener Configuration, Listener Name" screen in the "Net 8 Configuration Assistant" -
-
- +
  - Accept the default listener name of "LISTENER" -
  - +
  - Click "Next" -
  -
- -
  +
The "Listener Configuration, Select Protocols" screen in the "Net 8 Configuration Assistant" -
-
- +
  - The only choice in "Select protocols:" should be "TCP/IP" -
  - +
  - Click "Next" -
  -
- -
  +
The "Listener Configuration TCP/IP Protocol" screen in the "Net 8 Configuration Assistant" -
-
- +
  - Default Port should be 1521 and selected. -
  - +
  - Click "Next" -
  -
- -
  +
The "Listener Configuration, More Listeners" screen in the "Net 8 Configuration Assistant" -
-
- +
  - Select "No" -
  - +
  - Click "Next" -
  -
- -
  +
The "Listener Configuration Done" screen in the "Net 8 Configuration Assistant" -
-
- +
  - Click "Next" -
  -
- -
  +
The "Naming Methods Configuration" screen in the "Net 8 Configuration Assistant" -
-
- +
  - Select "No" -
  - +
  - Click "Next" -
  -
- -
  +
The "Done" screen in the "Net 8 Configuration Assistant" -
-
- +
  - Click "Finish" -
  -
- -
  +
The "End of Installation" screen in the OUI -
-
- +
  - Click "Exit" -
  - +
  - Click "Yes" on the confirmation pop up window. -
  - +
  - The Oracle Universal Installer window should have disappeared! -
  -
-
+

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. -

-Creating the First Database

Creating the First Database

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. -

-
+
Note
RedHat 7.3 users: Before running dbassist, do the following.
1. + Download the glibc + patch from Oracle Technet into
```
/tmp
```
  . +
2. + cd $ORACLE_HOME +
3. + tar xzf /tmp/glibc2.1.3-stubs.tgz +
4. + ./setup_stubs +
- Make sure you are running X. Open up a terminal and su to oracle and then run the dbassist program. -
  -
```
+		
 joeuser:~$ xhost +localhost
 joeuser:~$ su - oracle
 Password: *********
 oracle:~$ export DISPLAY=localhost:0.0
-oracle:~$ dbassist
-
```
- -
  +oracle:~$ dbassist
- The "Welcome" screen in the Oracle Database Configuration Agent (ODCA) -
  -
  - +
    Select "Create a database" -
    -
    +
    Click "Next" -
    -
    -
  - -
    +
- The "Select database type" screen in the ODCA -
  -
  - +
    Select "Custom" -
    -
    +
    Click "Next" -
    -
    -
  - -
    +
- The "Primary Database Type" window in ODCA -
  -
  - +
    Select "Multipurpose" -
    -
    +
    Click "Next" -
    -
    -
  - -
    +
- The "concurrent users" screen of the ODCA -
  -
  - +
    Select "60" concurrent users. -
    -
    +
    Click "Next" -
    -
    -
  - +
- Select "Dedicated Server Mode", click "Next" -
- +
- Accept all of the options, and click "Next" Oracle Visual Information Retrieval may be grayed out. If so, you can ignore it; just make sure that everything else is checked. -
- +
- For "Global Database Name", enter "ora8"; for "SID", also enter "ora8" (it should do this automatically). Click "Next". -
- +
- Accept the defaults for the next screen (control file location). Click "Next" -
- +
- Go to the "temporary" and "rollback" tabs, and change the Size (upper-right text box) to 150MB. Click "Next" -
- +
- Increase the redo log sizes to 10000K each. Click "Next" -
- +
- Use the default checkpoint interval & timeout. Click "Next" -
- +
- Increase "Processes" to 100; "Block Size" to 4096 (better for small Linux boxes; use 8192 for a big Solaris machine). -
- +
- Accept the defaults for the Trace File Directory. Click "Next" -
- +
- Finally, select "Save information to a shell script" and click "Finish" (We're going to examine the contents of this file before creating our database.) -
- +
- Click the "Save" button. Oracle will automatically save it to the correct directory and with the correct file name. This will likely be /ora8/m01/app/oracle/product/8.1.7/assistants/dbca/jlib/sqlora8.sh -
- +
- It will alert you that the script has been saved successfully. -
- -
  +
- Now we need to customize the database configuration a bit. While still logged on as oracle, edit the database initialization script (run when the db loads). The scripts are kept in $ORACLE_HOME/dbs and the name of the script is usually - initSID.ora - where SID is the SID of your + initSID.ora + where SID is the SID of your database. Assuming your $ORACLE_HOME matches our default of /ora8/m01/app/oracle/product/8.1.7, the following will open the file for editing. -
  -
```
-oracle:~$ emacs /ora8/m01/app/oracle/product/8.1.7/dbs/initora8.ora
```
  -
- -
  +
```
+oracle:~$ emacs /ora8/m01/app/oracle/product/8.1.7/dbs/initora8.ora
```
- Add the following line to the end: -
  -
```
-nls_date_format = "YYYY-MM-DD"
```
  -
- -
  +
```
+nls_date_format = "YYYY-MM-DD"
```
- Now find the open_cursors line in the file. If you're using emacs scroll up to the top of the buffer and do CTRL-S and type open_cursors to find the line. The default is 100. Change it to 500. -
  -
```
-open_cursors = 500
```
  -
- +
```
+open_cursors = 500
```
- Save the file. In emacs, do CTRL-X CTRL-S to save followed by CTRL-X CTRL-C to exit or use the menu. -
- +
- 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 +630,64 @@ login screen instead, switch to a virtual console by doing CRTL-ALT-F1. Then login as oracle. -
- -
  +
- Change to the directory where the database creation script is and run it: -
  -
```
+		
 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
-
+oracle:/ora8/m01/app/oracle/product/8.1.7/assistants/dbca/jlib$ ./sqlora8.sh
```
  In some instances, Oracle will save the file to /ora8/m01/app/oracle/product/8.1.7/assistants/dbca Try running the script there if your first attempt does not succeed. -
  -
- -
  +
- 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. -
  -
  +
  Eventually, you'll be returned to your shell prompt. In the meantime, relax, you've earned it. -
  -
-

-Acceptance Test

Acceptance Test

For this step, open up a terminal and su to oracle as usual. You should be running X and Netscape (or other web browser) for this phase. -

You need to download the "Oracle Acceptance Test" file. It's available here and at http://philip.greenspun.com/wtr/oracle/acceptance-sql.txt. Save the file to /tmp -
-
+

In the oracle shell, copy the file. -

-oracle:~$ cp /tmp/acceptance-sql.txt /tmp/acceptance.sql

+oracle:~$ cp /tmp/acceptance-sql.txt /tmp/acceptance.sql

Once you've got the acceptance test file all set, stay in your term and type the following: -
-
```
-oracle:~$ sqlplus system/manager
```
-
+
```
+oracle:~$ sqlplus system/manager
```
SQL*Plus should startup. If you get an ORA-01034: Oracle not Available error, it is because your Oracle instance is not running. You can manually start it as - the oracle user.
-
```
+		  the oracle user.
 oracle:~$ svrmgrl
 SVRMGR> connect internal
-SVRMGR> startup
-
```
-
+SVRMGR> startup

Now that you're into SQL*Plus, change the default passwords for system, sys, and ctxsys to "alexisahunk" (or to something you'll remember): -

+		
 SQL> alter user system identified by alexisahunk;
 SQL> alter user sys identified by alexisahunk;
-SQL> alter user ctxsys identified by alexisahunk;
-

-
+SQL> alter user ctxsys identified by alexisahunk;
Verify that your date settings are correct. -
-
```
-SQL> select sysdate from dual;
```
-
+
```
+SQL> select sysdate from dual;
```
If you don't see a date that fits the format YYYY-MM-DD, please read the section called “Troubleshooting Oracle Dates”. -
-
-
+

At this point we are going to hammer your database with an intense acceptance test. This usually takes around 30 minutes. -

+		
 SQL> @ /tmp/acceptance.sql
 
 ; A bunch of lines will scroll by.  You'll know if the test worked if
@@ -1094,15 +697,12 @@
 ----------
 2000-06-10
 
-SQL>
-
+SQL>

Many people encounter an error regarding maximum key length: -

+		
 ERROR at line 1:
-ORA-01450: maximum key length (758) exceeded
-
+ORA-01450: maximum key length (758) exceeded

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 +713,14 @@ dbassist program or by setting the DB_BLOCK_SIZE parameter in your database's creation script. -

If there were no errors, then consider yourself fortunate. Your Oracle installation is working. -

-Automating Startup & Shutdown

Automating Startup & Shutdown

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. -

Oracle includes a script called dbstart that can be used to automatically start the database. Unfortunately, the script @@ -1140,71 +729,46 @@ it. First, save dbstart to /tmp. Then, as oracle, do the following: -

 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

-
+oracle:~$ chmod 755 /ora8/m01/app/oracle/product/8.1.7/bin/dbstart
While you're logged in as oracle, you should configure the oratab file to load your database at start. Edit the file /etc/oratab: -
-
- -
  You will see this line.
  -
```
-ora8:/ora8/m01/app/oracle/product/8.1.7:N
```
  -
  +
  - You will see this line.
    +ora8:/ora8/m01/app/oracle/product/8.1.7:N
    By the way, if you changed the service name or have multiple databases, the format of this file is: -
    -
    - service_name:$ORACLE_HOME:Y || N - (for autoload) -
    -
  - -
    +
    + service_name:$ORACLE_HOME:Y || N + (for autoload) +
  - 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. -
    -
    -ora8:/ora8/m01/app/oracle/product/8.1.7:Y
    -
  - +
    +ora8:/ora8/m01/app/oracle/product/8.1.7:Y
  - Save the file & quit the terminal. -
  -
- -
  +

You need a script to automate startup and shutdown. Save oracle8i.txt in /tmp. Then login as root and install the script. (Debian users: substitute /etc/init.d for /etc/rc.d/init.d throughout this section) -

 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

-
+root:~# chmod 700 /etc/rc.d/init.d/oracle8i

Test the script by typing the following commands and checking the output. (Debian Users: as root, do mkdir /var/lock/subsys first) -

+		
 root:~# /etc/rc.d/init.d/oracle8i stop
 Oracle 8i auto start/stop
 Shutting Oracle8i:
@@ -1247,26 +811,15 @@
 
 Database "ora8" warm started.
 
-Database "ora8" warm started.
-

-
+Database "ora8" warm started.

If it worked, then run these commands to make the startup and shutdown automatic. -

Red Hat users:

+		
Red Hat users:
 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
-
-
-Debian users:
-+oracle8i        0:off   1:off   2:off   3:on    4:on    5:on    6:off
Debian users:
 root:~# update-rc.d oracle8i defaults
  Adding system startup for /etc/init.d/oracle8i ...
    /etc/rc0.d/K20oracle8i -> ../init.d/oracle8i
@@ -1275,11 +828,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
-
-
-SuSE users:
-+   /etc/rc5.d/S20oracle8i -> ../init.d/oracle8i
SuSE users:
 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 +868,25 @@
 Executing /sbin/conf.d/SuSEconfig.tetex...
 Executing /sbin/conf.d/SuSEconfig.ypclient...
 Processing index files of all manpages...
-Finished.
-
-
-

-
+Finished.

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. -

Download these three scripts into /tmp -

+
- startlsnr.txt -
- +
- stoplsnr.txt -
- +
- listener8i.txt -
-
+

Now issue the following commands (still as root). -

+		
 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 +895,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
-
+root:/etc/rc.d/init.d# chmod 700 listener8i

Test the listener automation by running the following commands and checking the output. -

+		
 root:/etc/rc.d/init.d# ./listener8i stop
 Oracle 8i listener start/stop
 Shutting down Listener for 8i: 
@@ -1406,17 +940,14 @@
 Services Summary...
   PLSExtProc        has 1 service handler(s)
   ora8      has 1 service handler(s)
-The command completed successfully
-
+The command completed successfully

This test will verify that the listener is operating normally. Login into the database using the listener naming convention. -

sqlplus - username/password/@SID -

+		  username/password/@SID
+		
 root:~# su - oracle
 oracle:~$ sqlplus system/alexisahunk@ora8
 
@@ -1428,27 +959,17 @@
 
 SQL> exit
 oracle:~$ exit
-root:~#
-
-
-RedHat users:
-
+root:~#

RedHat users:

Now run chkconfig on the listener8i script. -

 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

-
Debian users:
-
+listener8i 0:off 1:off 2:off 3:on 4:on 5:on 6:off

Debian users:

Now run update-rc.d on the listener8i script. -

+			
 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 +978,99 @@
    /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
-

-
+ /etc/rc5.d/S21listener8i -> ../init.d/listener8i

Test the automation -

As a final test, reboot your computer and make sure Oracle comes up. You can do this by typing -

-root:~# /sbin/shutdown -r -t 0 now

+root:~# /sbin/shutdown -r -t 0 now

Log back in and ensure that Oracle started automatically. -

+		
 joeuser:~$ su - oracle
 oracle:~$ sqlplus system/alexisahunk@ora8
 
-SQL> exit
-

+SQL> exit

Congratulations, your installation of Oracle 8.1.7 is complete. -

-Troubleshooting Oracle Dates

Troubleshooting Oracle Dates

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 'YYYY-MM-DD'. -

To fix this, you should include the following line in - $ORACLE_HOME/dbs/initSID.ora + $ORACLE_HOME/dbs/initSID.ora or for the default case, $ORACLE_HOME/dbs/initora8.ora -

-nls_date_format = "YYYY-MM-DD"

+nls_date_format = "YYYY-MM-DD"

You test whether this solved the problem by firing up sqlplus and typing: -

-SQL> select sysdate from dual;

+SQL> select sysdate from dual;

You should see back a date like 2000-06-02. If some of the date is chopped off, i.e. like 2000-06-0, everything is still fine. The problem here is that sqlplus is simply truncating the output. You can fix this by typing: -

+	
 SQL> column sysdate format a15
-SQL> select sysdate from dual;
-
+SQL> select sysdate from dual;

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. -

+ since adding the line: +

+nsadmin:~$ svrmgrl
+SVRMGR> connect internal
+Connected.
+SVRMGR> shutdown
+Database closed.
+Database dismounted.
+ORACLE instance shut down.
+SVRMGR> startup
+ORACLE instance started.

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: -

-export nls_lang = american

+export nls_lang = american

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 after the + entry to your login scripts after the nls_lang line: -

-export nls_date_format = 'YYYY-MM-DD'

+export nls_date_format = 'YYYY-MM-DD'

Log back in again. If adding the nls_date_format line doesn't help, you can ask for advice in our OpenACS forum. -

-Useful Procedures

Useful Procedures

Dropping a tablespace -
-
- -
  +
  - Run sqlplus as the dba: -
    -
    -oracle:~$ sqlplus system/changeme
    -
  - -
    +
    +oracle:~$ sqlplus system/changeme
  - To drop a user and all of the tables and data owned by that user: -
    -
    -SQL> drop user oracle_user_name cascade;
    -
  - -
    +
    +SQL> drop user oracle_user_name cascade;
  - 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. -
    -
    -SQL> drop tablespace table_space_name including contents cascade constraints;
    -
  -
-
+
```
+SQL> drop tablespace table_space_name including contents cascade constraints;
```

For more information on Oracle, please consult the documentation. -

-Defaults

We used the following defaults while installing Oracle.

----- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Variable Value Reason

ORACLE_HOME /ora8/m01/app/oracle/product/8.1.7 This is the default Oracle installation directory.

ORACLE_SERVICE ora8 The service name is a domain-qualified identifier for - your Oracle server.

ORACLE_SID ora8 This is an identifier for your Oracle server.

ORACLE_OWNER oracle The user who owns all of the oracle files.

ORACLE_GROUP

dba

The special oracle group. Users in the dba group are +

Defaults

We used the following defaults while installing Oracle.

- - -

Variable	Value	Reason
ORACLE_HOME	/ora8/m01/app/oracle/product/8.1.7	This is the default Oracle installation directory.
ORACLE_SERVICE	ora8	The service name is a domain-qualified identifier for + your Oracle server.
ORACLE_SID	ora8	This is an identifier for your Oracle server.
ORACLE_OWNER	oracle	The user who owns all of the oracle files.
ORACLE_GROUP	dba	The special oracle group. Users in the dba group are authorized to do a `connect internal` within `svrmgrl` to gain full system - access to the Oracle system.

($Id$)

- -

- - - - - - - - - - - -

-Prev	Home	Next -
Install an Operating System	Up	Install PostgreSQL 7.1.3

- rmello at fslc.usu.edu -

($Id$)

Prev	Home	Next
Install an Operating System	Up	Install PostgreSQL 7.1.3

rmello at fslc.usu.edu

- - +

Index: openacs.org-dev/packages/acs-core-docs/www/other-developer-overview.html =================================================================== RCS file: /usr/local/cvsroot/openacs.org-dev/packages/acs-core-docs/www/other-developer-overview.html,v diff -u -r1.1.1.1 -r1.1.1.2 --- openacs.org-dev/packages/acs-core-docs/www/other-developer-overview.html 9 Jul 2002 17:34:57 -0000 1.1.1.1 +++ openacs.org-dev/packages/acs-core-docs/www/other-developer-overview.html 11 Aug 2002 00:42:48 -0000 1.1.1.2 @@ -1,54 +1,4 @@ - - - -Overview - - - - - - - - -

- - - -

-Prev	Chapter 5. Other Developer Resources	Next -

-Overview

Developer information that doesn't really fit anywhere else.

- - - - - - - - - - - -

-Prev	Home	Next -
Chapter 5. Other Developer Resources	Up	Parties in OpenACS 4.5

- rmello at fslc.usu.edu -

+Overview

Prev	Chapter 5. Other Developer Resources	Next

Overview

Developer information that doesn't really fit anywhere else.

Prev	Home	Next
Chapter 5. Other Developer Resources	Up	Parties in OpenACS 4.5

rmello at fslc.usu.edu

- - +

Index: openacs.org-dev/packages/acs-core-docs/www/packages.html =================================================================== RCS file: /usr/local/cvsroot/openacs.org-dev/packages/acs-core-docs/www/packages.html,v diff -u -r1.1.1.1 -r1.1.1.2 --- openacs.org-dev/packages/acs-core-docs/www/packages.html 9 Jul 2002 17:34:57 -0000 1.1.1.1 +++ openacs.org-dev/packages/acs-core-docs/www/packages.html 11 Aug 2002 00:42:48 -0000 1.1.1.2 @@ -1,56 +1,23 @@ - - - -OpenACS 4.5 Packages - - - - - - - - -

- - - -

-Prev	Chapter 4. OpenACS Developer's Guide	Next -

-OpenACS 4.5 Packages

- By Pete Su and - Bryan Quinn -

-Overview

+OpenACS 4.5 Packages

Prev	Chapter 4. OpenACS Developer's Guide	Next

OpenACS 4.5 Packages

+ By Pete Su and Bryan Quinn +
+ OpenACS docs are written by the named authors, but may be edited + by OpenACS documentation staff. +

Overview

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. -

-Why package your software?

Why package your software?

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 ROOT. In OpenACS 3.2.x and earlier, a typical server might have a file system behind it that looked something like this: -

+    
 
 ROOT/
    bin/
@@ -82,29 +49,20 @@
 
          ... and so on for all modules ... 
 
-    
-
+

In previous versions of OpenACS, you wrote a new application like this: -

Put all Tcl library procedures under - server-root/tcl.
Put all User viewable content under - server-root/www.
Put all Admin content under /admin/package-key/. -

Put all Tcl library procedures under + server-root/tcl.
Put all User viewable content under + server-root/www.
Put all Admin content under /admin/package-key/. +

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. -

Here is how an OpenACS 4.5 server is laid out: -

+    
 
 ROOT/
     bin/
@@ -125,7 +83,10 @@
         bboard/
                bboard.info
                sql/
-                    data model
+                    oracle/
+                         oracle data model
+                    postgresql/
+                         postgresql data model
                tcl/
                     tcl library code
                www/
@@ -142,116 +103,94 @@
             bootstrap code
     www/
             misc pages
-
-    
-
+

Note that a major reorganization has happened here. The diagram only expands the structure of the bboard/ 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 + user pages in a single part of the file tree. This organization has two major advantages: -

- This structure makes it easy for developers to track down - everything that is related to a particular package without - hunting all over the file system. -
- Encapsulating everything about a package in one place also makes it - much easier to distribute packages indepedently from the OpenACS itself. -

+ This structure makes it easy for developers to track + down everything that is related to a + particular package without hunting all over the file system. +
+ Encapsulating everything + about a package in one place also makes it much easier to + distribute packages independently from the OpenACS itself. +

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. -

-The APM

+ package. While we're at it, this tool should also automate + package installation, dependency checking, upgrades, and package + removal. In OpenACS 4.5, this tool is called the APM. +

The APM

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: -

Package registration
Automatic installation of packages: loading data models, code - libraries, and so on.
Checking what packages depend on what other packages.
Storing information on the package including ownership and a file - list.

Package registration
Automatic installation of packages: loading data models, code + libraries, and so on.
Checking what packages depend on what other packages.
Storing information on the package including ownership and a file + list.

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 package instances. Once a package is loaded, the + call package instances. 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. -

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 subsites, - and the site map tool, which can be used to map applications to + instance model. The two most important of these are subsites, + and the site map tool, which can be used to map applications to one or more arbitrary URLs in a running site. -

We will also discuss how to organize your files and queries so - they work with OpenACS' Query Dispatcher. -

-What a Package Looks Like

+ they work with the OpenACS Query Dispatcher. +

What a Package Looks Like

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: -

+    
 
 ROOT/
   +-- packages/    APM Root
         |
-        +-- notes/	Package Root 
+        +-- notes/  Package Root 
         |     |
         |     |
         |     +-- sql/
         |     |     |
         |     |     +-- oracle/
         |     |     |        |
-        |     |	    |        +-- notes-create.sql         Data Model Creation Script for Oracle
-        |     |	    |        +-- notes-drop.sql           Data Model Drop Script
-        |     |	    |        +-- *.sql                    Data Model Files
+        |     |     |        +-- notes-create.sql         Data Model Creation Script for Oracle
+        |     |     |        +-- notes-drop.sql           Data Model Drop Script
+        |     |     |        +-- *.sql                    Data Model Files
+        |     |     |        +-- upgrade/
+        |     |     |            +-- upgrade-4.1-4.5.sql  Data Model Upgrade Scripts
         |     |     +-- postgresql/
         |     |     |        |
-        |     |	    |        +-- notes-create.sql         Data Model Creation Script for PostgreSQL      
-        |     |	    |        +-- notes-drop.sql           Data Model Drop Script
-        |     |	    |        +-- *.sql                    Data Model Files
+        |     |     |        +-- notes-create.sql         Data Model Creation Script for PostgreSQL      
+        |     |     |        +-- notes-drop.sql           Data Model Drop Script
+        |     |     |        +-- *.sql                    Data Model Files
+        |     |     |        +-- upgrade/
+        |     |     |            +-- upgrade-4.1-4.5.sql  Data Model Upgrade Scripts
         |     +-- tcl/
         |     |     |
-        |     |	    +-- notes-procs.tcl                   Tcl Library
-        |     |	    +-- notes-procs.xql                   SQL92 Queries for notes-procs.tcl
-        |     |	    +-- notes-procs-oracle.xql            Oracle-specific queries for notes-procs.tcl
-        |     |	    +-- notes-procs-postgresql.xql        PostgreSQL-specific Queries for notes-procs.tcl
-        |     |	    +-- notes-init.tcl                    Tcl Initialization
-        |     |	    +-- notes-init.xql                    Queries for notes-init.tcl (work in all DBs)      
+        |     |     +-- notes-procs.tcl                   Tcl Library
+        |     |     +-- notes-procs.xql                   SQL92 Queries for notes-procs.tcl
+        |     |     +-- notes-procs-oracle.xql            Oracle-specific queries for notes-procs.tcl
+        |     |     +-- notes-procs-postgresql.xql        PostgreSQL-specific Queries for notes-procs.tcl
+        |     |     +-- notes-init.tcl                    Tcl Initialization
+        |     |     +-- notes-init.xql                    Queries for notes-init.tcl (work in all DBs)      
         |     |     +-- *.tcl                             Tcl Library Files
         |     +-- www/
         |     |     |
@@ -275,321 +214,192 @@
         |     +-- notes.info                              Package Specification File
         +-- Other package directories.
 
-    
-
+

All file locations are relative to the package root, which in this case is ROOT/packages/notes. The following table describes in detail what each of the files up in the diagram contain. -

----- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

File Type	Its Use	Naming Convention
Data Model Creation Script	- 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 :-)) -	`sql/<database>/notes-create.sql`
Data Model Drop Script	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. -	`sql/<database>/notes-drop.sql`
Data Model File	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 - @@ filename in the creation or drop - scripts. See the - Oracle SQL*Plus documentation for examples. In - PostgreSQL the same is acomplished by including \i. -	`sql/<database>/*.sql`
- SQL92 Query Files -	- 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. -	`- *.xql -`
- Oracle-specific Query Files -	- Files with queries that are Oracle-specific. Notice that - the .xql filename must match the name of the .tcl file - that uses those queries. -	`- *-oracle.xql -`
- PostgreSQL-specific Query Files -	- Files with queries that are PostgreSQL-specific. Notice that - the .xql filename must match the name of the .tcl file - that uses those queries. -	`- *-postgresql.xql -`
Tcl Library Files	- The Tcl library files include a set of procedures that provide - an application programming interface (API) for the package to - utilize. -	`tcl/notes-procs.tcl`
Tcl Initialization	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. -	`tcl/notes-init.tcl`
Administration UI	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.	`www/admin/*`
Administration UI Index Page	Every package administration UI must have an index page. In - most cases, this is `index.tcl` but it can be - any file with the name `index`, such as - index.html or index.adp.	`www/admin/index.tcl`
Regression Tests	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.	`www/admin/tests/`
Regression Test Index Page	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 `index`.	`/www/admin/tests/index.html`
Documentation	Every package must include a full set of documentation that - includes requirements and design documents, and user-level and - developer-level documentation where appropriate.	`/www/doc/`
Documentation Index Page	The documentation directory must include a static HTML file with the name - of `index.html`.	`/www/doc/index.html`
UI Logic Scripts	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.	`/www/*.tcl`
UI Templates	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.	`/www/*.adp`
UI Index Page	The UI must have an index page composed of a logic script - called `index.tcl` and a template called - `index.adp`.	`/www/index.tcl`
Package Specification File	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.	`notes.info`

-Making a Package

File Type	Its Use	Naming Convention
Data Model Creation Script	+ 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 :-)) +	`sql/<database>/notes-create.sql`
Data Model Drop Script	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. +	`sql/<database>/notes-drop.sql`
Data Model File	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 + @@ filename in the creation or drop + scripts. See the + Oracle SQL*Plus documentation for examples. In + PostgreSQL the same is acomplished by including \i. +	`sql/<database>/*.sql`
Data Model Upgrade Scripts	+ Contain changes to the data model between versions. The APM + can automatically load the appropriate upgrade scripts when + upgrading to a new version of a package. +	`sql/<database>/upgrade/upgrade-<old>-<new>.sql`
+ SQL92 Query Files +	+ 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. +	`+ *.xql +`
+ Oracle-specific Query Files +	+ Files with queries that are Oracle-specific. Notice that + the .xql filename must match the name of the .tcl file + that uses those queries. +	`+ *-oracle.xql +`
+ PostgreSQL-specific Query Files +	+ Files with queries that are PostgreSQL-specific. Notice that + the .xql filename must match the name of the .tcl file + that uses those queries. +	`+ *-postgresql.xql +`
Tcl Library Files	+ The Tcl library files include a set of procedures that provide + an application programming interface (API) for the package to + utilize. +	`tcl/notes-procs.tcl`
Tcl Initialization	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. +	`tcl/notes-init.tcl`
Administration UI	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.	`www/admin/*`
Administration UI Index Page	Every package administration UI must have an index page. In + most cases, this is `index.tcl` but it can be + any file with the name `index`, such as + index.html or index.adp.	`www/admin/index.tcl`
Regression Tests	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.	`www/admin/tests/`
Regression Test Index Page	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 `index`.	`/www/admin/tests/index.html`
Documentation	Every package must include a full set of documentation that + includes requirements and design documents, and user-level and + developer-level documentation where appropriate.	`/www/doc/`
Documentation Index Page	The documentation directory must include a static HTML file with the name + of `index.html`.	`/www/doc/index.html`
UI Logic Scripts	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.	`/www/*.tcl`
UI Templates	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.	`/www/*.adp`
UI Index Page	The UI must have an index page composed of a logic script + called `index.tcl` and a template called + `index.adp`.	`/www/index.tcl`
Package Specification File	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.	`notes.info`

Making a Package

Here is how you make a package. -

Login as a site-wide administrator on your web service. -
Go to the package manager on your server. The URL is /acs-admin/apm. -
Click on the link /acs-admin/apm/package-add. -
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: +
1. Login as a site-wide administrator on your web service. +
2. Go to the package manager on your server. The URL is /acs-admin/apm. +
3. Click on the link /acs-admin/apm/package-add. +
4. 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: -
  -
  Package Key -
  -
  - 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: bboard, - acs-kernel and so on. For the example application, we - will use the package key notes. -
  -
  Package Name -
  -
  - This is a short human readable name for your package. For our example, - we will use the name "Notes". -
  -
  Package Plural -
  -
  - 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". -
  -
  Package Type -
  -
  - Generally we think of packages as either being applications, - meaning that the package is meant primarily for use by end-users, or - services meaning that the package is meant to be a reusable - library of code, to be used by other packages. bboard is - a good example of an application, while acs-templating is - a good example of a service. Our example is an application, so pick - that. -
  -
  Package URL -
  -
  - The URL from which people will download your package when it is - done. Just use the default for this, you can change it later. -
  -
  Initial Version -
  -
  - Just use the default here, which by convention is 0.1d. -
  -
  Version URL -
  -
  - Just use the default here. -
  -
  Summary and Description -
  -
  - 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. -
  -
  -
5. Click the button "Create Package". -
6. At this point, APM will create a directory called - ROOT/packages/notes. -
7. -
  Since we didn't create any files for the package before, the - directory that APM created will be empty except for the - notes.info file. At this point, create a file called - ROOT/packages/notes/sql/notes-create.sql and put the add - the data model that we created before to - this file. You should also create a file called - ROOT/packages/notes/sql/notes-drop.sql that drops the - data model.
  -
  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 packages/notes 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 - notes package. -
  -
  - Note that while the .sql files have been added to the - packge, they have not 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 - .tcl files for code, it does not do the same thing for - data model files. -
  -
8. Now go back to the main management page for the notes - If your package has parameters, create them using the "Manage - Parameter Information" link.
9. -
  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 - these instructions. If so, then you just do this: -
  -
```
+      
Package Key
+          

+          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: bboard,
+          acs-kernel and so on. For the example application, we
+          will use the package key notes.
+        
Package Name
+          

+          This is a short human readable name for your package. For our example,
+          we will use the name "Notes".
+        
Package Plural
+          

+          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".
+        
Package Type
+          

+          Generally we think of packages as either being applications,
+          meaning that the package is meant primarily for use by end-users, or
+          services meaning that the package is meant to be a reusable
+          library of code, to be used by other packages. bboard is
+          a good example of an application, while acs-templating is
+          a good example of a service. Our example is an application, so pick
+          that.
+        
Package URL
+          

+          The URL from which people will download your package when it is
+          done. Just use the default for this, you can change it later.
+        
Initial Version
+          

+          Just use the default here, which by convention is 0.1d.
+        
Version URL
+          

+          Just use the default here.
+        
Summary and Description
+          

+          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.
+        

+    
```
10. Click the button "Create Package". +
11. At this point, APM will create a directory called + ROOT/packages/notes. +
12. + The directory that APM created will be empty except for the + notes.info file. Create a file + called + ROOT/packages/notes/sql/oracle/notes-create.sql. We'll + fill this file with our data model + very soon. Create a file called + ROOT/packages/notes/sql/oracle/notes-drop.sql. This + will contain the instructions to drop the data model. To be + complete, you would also create the PostgreSQL versions of these + files as well in + ROOT/packages/notes/sql/postgresql/notes-create.sql + and + ROOT/packages/notes/sql/postgresql/notes-drop.sql. +
  + 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 + packages/notes 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 notes package. +
  + Note that while the .sql files + have been added to the packge, they have not + 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 + .tcl files for code, it does not + do the same thing for data model files. +
13. Now go back to the main management page for the notes + If your package has parameters, create them using the "Manage + Parameter Information" link.
14. 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 + these instructions. If so, then you just do this: +
```
 
 % cd ROOT/packages
 % cvs add notes
@@ -601,59 +411,48 @@
 % cd ROOT/packages/notes
 % cvs commit -m "add new package for notes"
 
-	
```
  -
15. - Now you can start developing the package. In addition to writing code, - you should also consider the tasks outlined in the package submission guidelines. -
-

-The Site Map and Package Instances

+ Now you can start developing the package. In addition to writing code, + you should also consider the tasks outlined in the package submission guidelines. +

The Site Map and Package Instances

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 ROOT/packages/notes/www directory. So go there and add a file called hello.html 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 ROOT/www they will not appear on their - own. What we have to do is mount the application into the site + own. What we have to do is mount 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. -

In OpenACS 3.x, everything in the site was implicitly mounted underneath ROOT/www. AOLserver automatically took any URL like /foo/bar/moo/baz.html and mapped it to the file ROOT/www/foo/bar/moo/baz.html. 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. -

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 site map and entries in the - site map are called site nodes. Each site node maps a URL to an + served. This mapping is called the site map and entries in the + site map are called site nodes. 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 + us to easily map package instances to URLs. As we said before, each + instance of an application has its own set of parameters and runs from its own URL within the site. What this means is that even though all the code for the notes application lives in - ROOT/packages/notes the application itself can run from - any number of locations in the site. This fact allows developers and + ROOT/packages/notes, the application itself can run from + any number of locations in the site. This allows developers and administrators to build sites that look to the user like a collection - of many indepdendent applications that actually run on a single shared + of many indedendent applications that actually run on a single shared code base. The request-processor document shows you how OpenACS figures out which instance of your application was requested by the user at any given time. The page development tutorial shows you how to use this information in your user interface. -

In order to make the new notes application visible to users, we have to mount it in the site map. You do this by going to the Site Map page, which is by @@ -662,88 +461,38 @@ the root of the site, then click "new application" to mount a new instance of the notes application to the site. Name the new instance notes-1. -

- After you get done doing this, try typing this URL into your browser: +

+ Then type this URL into your browser: -

 
 http://your-server.your-domain.com/notes/hello.html
 
-

Now you should see the contents of the page that you added. What has happened is that all URLs that start with /notes have been mapped in such a way as to serve content from the directory ROOT/packages/notes/www. At this point, you can experiment with the site map by mounting multiple instances of the not yet written Notes application at various places in the site. In a - 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 + later document, we'll see how to write your application so that the + code can detect from what URL it was invoked. This is the key to supporting subsites. -

-Summary

Summary

The APM performs the following tasks in an OpenACS site: -

- Manages creation, installation, and removal of packages from the - server. Also keeps track of what files belong to which packages. -
- Manages package upgrades. -
- Manages information on all package instances 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. -
- Writes out package distribution files for other people to download and - install. We'll cover this later. -

-Additional Reading

($Id$)

- - - - - - - - - - - -

-Prev	Home	Next -
OpenACS 4.5 Data Models and the Object System	Up	The Request Processor

- rmello at fslc.usu.edu -

+ Manages creation, installation, and removal of packages from the + server. Also keeps track of what files belong to which packages. +
+ Manages package upgrades. +
+ Manages information on all package instances 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. +
+ Writes out package distribution files for other people to download and + install. We'll cover this later. +

Additional Reading

($Id$)

Prev	Home	Next
Overview	Up	OpenACS 4.5 Data Models and the Object System

rmello at fslc.usu.edu

+table or the groups table.

- - +

Index: openacs.org-dev/packages/acs-core-docs/www/parties.html =================================================================== RCS file: /usr/local/cvsroot/openacs.org-dev/packages/acs-core-docs/www/parties.html,v diff -u -r1.1.1.1 -r1.1.1.2 --- openacs.org-dev/packages/acs-core-docs/www/parties.html 9 Jul 2002 17:34:57 -0000 1.1.1.1 +++ openacs.org-dev/packages/acs-core-docs/www/parties.html 11 Aug 2002 00:42:48 -0000 1.1.1.2 @@ -1,64 +1,28 @@ - - - -Parties in OpenACS 4.5 - - - - - - - - -

- - - -

-Prev	Chapter 5. Other Developer Resources	Next -

-Parties in OpenACS 4.5

-by Rafael H. Schloming -

-Introduction

While many applications must deal with individuals and many applications +Parties in OpenACS 4.5

Prev	Chapter 5. Other Developer Resources	Next

Parties in OpenACS 4.5

+by Rafael H. Schloming
+ OpenACS docs are written by the named authors, but may be edited + by OpenACS documentation staff. +

Introduction

While many applications must deal with individuals and many applications must deal with groups, most applications must deal with individuals -or groups. It is often the case with such applications that in many +or 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".

A classic example use of the "party" supertype is evident +supertype is called a "party".

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".

-The Data Model

Most developers who do significant work with the OpenACS will become +isn't a company. It is a "party".

The Data Model

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.

Parties

The central table in the parties data model is the parties table itself. +an introduction to the data model.

Parties

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.

+stored in the acs objects table.
 
 create table parties (
     party_id    not null
@@ -71,21 +35,17 @@
 );
 
 
-
-There are two tables that extend the parties table. One is the persons
+

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.

Persons

If a party is an individual then there will be a row in the persons table +individuals that is represented.

Persons

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.

+user is in fact a further specialized form of an individual.
 
 create table persons (
     person_id   not null
@@ -97,25 +57,21 @@
 );
 
 
-
-Users
-The users table is an even more specialized form of an individual. A row
+

Users

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.

One of the interesting benefits of decomposing all the information +the parties table.

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, not the users table. If this feature is +parties table, not 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.

+references is to a user and not to an individual.
 
 create table users (
     user_id         not null
@@ -144,15 +100,12 @@
 );
 
 
-
-Groups
-The final piece of the parties data model is the groups data model. A
+

Groups

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.

+parties and groups.
 
 create table groups (
     group_id    not null
@@ -163,35 +116,30 @@
 );
 
 
-
-Group Relations
-One surprise here is that there are actually two relations involved. One
+

Group Relations

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 parties. But just because you are a member of an +groups and parties. 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 is transitive with respect to +the company, i.e., membership is 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.

Group Membership

Group memberships can be created and manipulated using the membership_rel +world.

Group Membership

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).

+indirect membership (membership via some component or sub component).
 
 create or replace package membership_rel
 as
@@ -235,16 +183,13 @@
 show errors
 
 
-
-Group Composition
-Composition relations can be created or destroyed using the
+

Group Composition

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.

+would result in a cycle.
 
 create or replace package composition_rel
 as
@@ -267,12 +212,7 @@
 show errors
 
 
-
-

-Views

The data model described above does a reasonable job of representing many +

Views

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.

This view returns all the subcomponents of a group including components of +very quickly.

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.

+auditing info for the relation.

 
 create or replace view group_component_map
 as select group_id, component_id, container_id, rel_id
 ...
 
 
-

This is similar to group_component_map except for membership relations. +

This is similar to group_component_map except for membership relations. Note that this view will return all membership relations regardless of -membership state.

+membership state.

 
 create or replace view group_member_map
 as select group_id, member_id, container_id, rel_id
 ...
 
 
-

The group_approved_member_map is the same as the group_member_map except -it only returns entries that relate to approved members.

The group_approved_member_map is the same as the group_member_map except +it only returns entries that relate to approved members.

 
 create or replace view group_approved_member_map
 as select group_id, member_id, container_id, rel_id
 ...
 
 
-

This view is useful if you don't care about the distinction between +

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.)

+group including members of components. (It is the transitive closure.)

 
 create or replace view group_distinct_member_map
 as select group_id, member_id
 ...
 
 
-

This view is the same as group_distinct_member_map, except it includes the +

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.

+the party to itself.

 
 create or replace view party_member_map
 as select party_id, member_id
 ...
 
 
-

This view is the same as above except that when it expands groups, it only -pays attention to approved members.

This view is the same as above except that when it expands groups, it only +pays attention to approved members.

 
 create or replace view party_approved_member_map
 as select party_id, member_id
 ...
 
 
-

-Extending The Parties Data Model

As is, the parties data model can represent some fairly sophisticated real +

Extending The Parties Data Model

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.

Specializing Users

It is conceivable that some applications will want to collect more +of the more common ways.

Specializing Users

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.

Specializing Groups

If one were to build an intranet application on top of the 4.5 party +store any extra information relevant to the MENSA community.

Specializing Groups

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.

Specializing Membership Relations

The final portion of the parties data model that is designed to be +company party type in the same manner as above.

Specializing Membership Relations

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 object identity, 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.

($Id$)

- - - - - - - - - - - -

-Prev	Home	Next -
Overview	Up	Object Identity

- rmello at fslc.usu.edu -

Prev	Home	Next
Overview	Up	Object Identity

- - +

Index: openacs.org-dev/packages/acs-core-docs/www/permissions-design.html =================================================================== RCS file: /usr/local/cvsroot/openacs.org-dev/packages/acs-core-docs/www/permissions-design.html,v diff -u -r1.1.1.1 -r1.1.1.2 --- openacs.org-dev/packages/acs-core-docs/www/permissions-design.html 9 Jul 2002 17:34:57 -0000 1.1.1.1 +++ openacs.org-dev/packages/acs-core-docs/www/permissions-design.html 11 Aug 2002 00:42:48 -0000 1.1.1.2 @@ -1,51 +1,12 @@ - - - -OpenACS 4 Permissions Design - - - - - - - - -

- - - -

-Prev	Chapter 7. Kernel Documentation	Next -

-OpenACS 4 Permissions Design

-by John Prevost and Rafael H. Schloming -

-Essentials

Tcl in packages/acs-kernel -
OpenACS 4 Permissions Requirements
-SQL file
-ER diagram +OpenACS 4 Permissions Design
Prev Chapter 7. Kernel Documentation Next
OpenACS 4 Permissions Design
+by John Prevost and Rafael H. Schloming
+ OpenACS docs are written by the named authors, but may be edited + by OpenACS documentation staff. +
Essentials
- Tcl in packages/acs-kernel
- OpenACS 4 Permissions Requirements
- +SQL file
- ER diagram -
-
-
-
-Introduction
-
The goal of the Permissions system is to provide generic means to both +

Introduction

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.

For programmers, the Permissions API provides a means to work with access +at least one permissions API call, and some will make several.

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.

For site administrators and other authorized users, the Permissions UI +those package objects on which a user has certain permissions.

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.

-Historical Considerations

In earlier versions of the OpenACS, permissions and access control was handled +admin) that can be granted and revoked.

Historical Considerations

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.

Problems resulting from this piecemeal approach to permissions and access +row based on the information in that row.

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.

-Competitive Analysis

None available as of 10/2000.

-Design Tradeoffs

The core of the permissions data model is quite simple. Unfortunately, the +readily use.

Competitive Analysis

None available as of 10/2000.

Design Tradeoffs

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.

-Data Model Discussion

As described in section V., the core of the permissions data model is +for additional storage space increase.

Data Model Discussion

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:

acs_methods +adequate performance. The core model consists of five tables: acs_methods - - The set of all defined methods. - acs_privileges + The set of all defined methods. acs_privileges - - The set of all defined privileges. - acs_privilege_method_rules + The set of all defined privileges. acs_privilege_method_rules - - A relation describing the set of methods directly -associated with each privilege. - acs_privilege_hierarchy + A relation describing the set of methods directly +associated with each privilege. acs_privilege_hierarchy - - A relation describing which privileges directly -"contain" other privileges. - acs_permissions + A relation describing which privileges directly +"contain" other privileges. acs_permissions - - A table with one (party, object, privilege) -row for every privilege directly granted on any object in +: A table with one (party, object, privilege) +row for every privilege directly granted on any object in the system - this is a denormalization of acs_privilege_method_rules and -acs_privilege_hierarchy -

There are also a number of views to make it easier to ask specific +acs_privilege_hierarchy

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.)

The following views provide flattened versions of inherited -information:

acs_privilege_method_map +in the bboard.) The following views provide flattened versions of inherited +information: acs_privilege_method_map - - Map of privileges to the methods they contain either directly or because -of another privilege which is included (at any depth). - acs_object_grantee_priv_map + Map of privileges to the methods they contain either directly or because +of another privilege which is included (at any depth). acs_object_grantee_priv_map - - Relation on (object, party, privilege) for +: Relation on (object, party, privilege) for privileges from acs_privileges) granted directly on the object, or -on the context of the object (at any depth).
acs_object_party_privilege_map +on the context of the object (at any depth).
acs_object_party_privilege_map -: Relation on (object, party, privilege) for +; Relation on (object, party, privilege) for privileges directly from acs_object_grantee_priv_map or also because -a party is a member of a group (at any depth).
acs_object_party_method_map +a party is a member of a group (at any depth).
acs_object_party_method_map -: Relation with every (object, party, method) -tuple implied by the above trees.

In general, only acs_object_party_method_map +

Relation with every (object, party, method) +tuple implied by the above trees.

In general, only acs_object_party_method_map should be used for queries from other modules. The other views are -intermediate steps in building that query.

The data model also includes two simple PL/SQL procedures +intermediate steps in building that query.

The data model also includes two simple PL/SQL procedures (acs_permission.grant_permission and acs_permission.revoke_permission) for granting and revoking a -specific privilege for a specific user on a specific object.

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.

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.

The transformations done create a set of default permissions, in -which:

parties get the privileges of any groups they are directly or indirectly -a member of
privileges get associated with the methods of any other privileges they +for efficiency reasons.
The transformations done create a set of default permissions, in +which:
- parties get the privileges of any groups they are directly or indirectly +a member of
- privileges get associated with the methods of any other privileges they have taken methods from (at any level) (see -acs_privilege_hierarchy)
- objects get access control from direct grants, or inherit permissions +acs_privilege_hierarchy)
- objects get access control from direct grants, or inherit permissions from their context (unless the "don't inherit" flag is -set)
-

-Legal Transactions

There are three essential areas in which all transactions in the -permissions system fall:

Modification of methods and privileges
Modification of permissions
Queries on permissions

-"Modification of methods and privileges." This +set)

-OpenACS 4 Permissions Requirements

-by John McClary Prevost -

-Introduction

This document records requirements for the OpenACS 4 Permissions system, a +OpenACS 4 Permissions Requirements

Prev	Chapter 7. Kernel Documentation	Next

OpenACS 4 Permissions Requirements

+by John McClary Prevost
+ OpenACS docs are written by the named authors, but may be edited + by OpenACS documentation staff. +

Introduction

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.

-Vision Statement

Any multi-user software system must address the general problem of +centralize the handling of access and control on a given OpenACS 4 system.

Vision Statement

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.

Historical Motivations

In earlier versions of the OpenACS, permissions and access control was handled +access control is implemented and enforced correctly.

Historical Motivations

Problems resulting from this piecemeal approach to permissions and access +row based on the information in that row.

-System Overview

The OpenACS 4 Permissions system has two main pieces: first, an API for +readily use.

System Overview

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.

Consistency is a key characteristic of the Permissions system - both for a +grant and revoke permissions to system entities under their control.

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.

-Use Cases and User Scenarios

Terminology

The primary question an access control system must answer is a three-way +or fall outside the common administrative interfaces.

Use Cases and User Scenarios

Terminology

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:

The subject of the sentence is "party" - a +perform this operation on this target?" Definitions:

The subject of the sentence is "party" - 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).

The object of the sentence is "target" - this +may represent many users (or no users at all).

The object of the sentence is "target" - 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.

The verb of the sentence is "operation" - a behavior on the OpenACS +entity/object here is anything that can be put under access control.

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.

Examples of the essential question addressed by the Permissions system: +that operation.

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?

-Related Links

OpenACS 4 Permissions Design

-Functional Requirements

10.0 Granularity

The system must support access control down to the level of a single +instance?

Functional Requirements

10.0 Granularity

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).

20.0 Operations

The system itself must be able to answer the essential permissions -question as well as several derived questions.

-
20.10 Basic Access Check
-
The system must be able to answer the question, "May party P perform -operation O on target T?"
-

-
20.20 Allowed Parties Check
-
The system must be able to answer the question, "Which parties may -perform operation O on target T?"
-

-
20.30 Allowed Operations Check
-
The system must be able to answer the question, "Which operations may -party P perform on target T?"
-

-
20.40 Allowed Targets Check
-
The system must be able to answer the question, "Upon which targets -may party P perform operation O?"
-

-Behavioral Requirements

40.0 Scale of Privileges

Privileges must be designed with appropriate scope for a given OpenACS +model).

20.0 Operations

The system itself must be able to answer the essential permissions +question as well as several derived questions.

20.10 Basic Access Check
The system must be able to answer the question, "May party P perform +operation O on target T?"

20.20 Allowed Parties Check
The system must be able to answer the question, "Which parties may +perform operation O on target T?"

20.30 Allowed Operations Check
The system must be able to answer the question, "Which operations may +party P perform on target T?"

20.40 Allowed Targets Check
The system must be able to answer the question, "Upon which targets +may party P perform operation O?"

Behavioral Requirements

40.0 Scale of Privileges

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.

50.0 Aggregation of Operations (Privileges)

For user interface purposes, it can be appropriate to group certain +"read" to mean too many things.

50.0 Aggregation of Operations (Privileges)

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.

60.0 Aggregation of Parties (Groups)

The system must allow aggregation of parties. The exact method used for +"delete", etc. privileges.

60.0 Aggregation of Parties (Groups)

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.

70.0 Scope of Access Control

-
70.10 Context
-
There must be a method for objects to receive default access control from +should be available to all members of that aggregate.
70.0 Scope of Access Control
70.10 Context
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.
-
-
-
70.20 Overriding
-
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.
-
-
-
70.20.10 Positive Overriding
-
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.
70.20 Overriding
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.
70.20.10 Positive Overriding
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.)
-
-
-
70.20.20 Negative Overriding
-
It must be possible to deny a party access to some target that their +their own messages.)
70.20.20 Negative Overriding
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.)
-
-
100.0 Efficiency
-
At least the basic access check (20.10) and the allowed targets check +be possible, however, to make a subdirectory private to some group.)

100.0 Efficiency

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).

In particular, constraining a SELECT to return only rows the +targets check (20.40).

In particular, constraining a SELECT to return only rows the current user has access to should not be much slower than the SELECT -on its own.

120.0 Ease of Use

Since most SQL queries will contain an allowed target check in the where +on its own.

120.0 Ease of Use

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.

In particular, constraining a SELECT to return only rows the -current user has access to should not add more than one line to a query.

-Revision History

------ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Document Revision #	Action Taken, Notes	When?	By Whom?
0.1	Creation	8/17/2000	John Prevost
0.2	Revised, updated with new terminology	8/25/2000	John Prevost
0.3	Edited, reformatted to conform to requirements template, pending -freeze.	8/26/2000	Kai Wu
0.4	Edited for ACS 4 Beta release.	10/03/2000	Kai Wu

- - - - - - - - - - - -

-Prev	Home	Next -
OpenACS 4 Object Model Design	Up	OpenACS 4 Permissions Design

- rmello at fslc.usu.edu -

+small and simple.

In particular, constraining a SELECT to return only rows the +current user has access to should not add more than one line to a query.

Revision History

Document Revision #	Action Taken, Notes	When?	By Whom?
0.1	Creation	8/17/2000	John Prevost
0.2	Revised, updated with new terminology	8/25/2000	John Prevost
0.3	Edited, reformatted to conform to requirements template, pending +freeze.	8/26/2000	Kai Wu
0.4	Edited for ACS 4 Beta release.	10/03/2000	Kai Wu

Prev	Home	Next
OpenACS 4 Object Model Design	Up	OpenACS 4 Permissions Design

rmello at fslc.usu.edu

- - +

-Groups, Context, Permissions

By Pete Su -

-Overview

+Groups, Context, Permissions

Prev	Chapter 4. OpenACS Developer's Guide	Next

Groups, Context, Permissions

By Pete Su

+ OpenACS docs are written by the named authors, but may be edited + by OpenACS documentation staff. +

Overview

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 acs_objects 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. -

Although this may all sound easy and wonderful, no developer or -administrator would want to explicitly set access control -rights for every user and every object on a +administrator would want to explicitly set access control +rights for every user and every object 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 -object context, which allows applications to group objects +object context, 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. -

-Groups

Groups

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.) -

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. -

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. -

OpenACS 4.5 solves both of these modeling problems by introducing a new -abstraction called a party. Parties have a recursive +abstraction called a party. Parties have a recursive definition, and we can illustrate how it works with the following simplified data model. First, we define the parties table, where each party has an email address and a URL for contact information. -

+
 
 create table parties (
     party_id  integer not null references acs_objects(object_id),
     email varchar(100),
     url varchar(100)
 )
 
-
-
+

Now we define two subtypes of party, one for persons, and one for groups: -

+
 
 create table groups (
     group_id  not null references parties(party_id),
@@ -117,49 +78,38 @@
     last_name varchar(100) not null
 )
 
-
-
+

The users table is also defined in this data model as a subtype of person. It contains many of the basic columns that the old OpenACS 3.x users table contained. -

-Finally, we define two relations, one for group membership and -one for group composition. The composition relation allows us +

+Finally, we define two relations, one for group membership and +one for group composition. 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. -

The membership relation is much like the mapping we had in 3.x, except -that it maps groups to parties instead of groups to users. What +that it maps groups to parties 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. -

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. -

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 Parties in OpenACS 4 or OpenACS 4 Groups Design. -

-Permissions

Permissions

The permissions data model is actually pretty simple. The data model -is a mapping between privileges, parties and objects. We +is a mapping between privileges, parties and objects. We already know what parties and objects are, but we don't know what privileges are. -

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: -

+
 
 begin
  acs_privilege.create_privilege('read');
@@ -191,94 +140,44 @@
  commit;
 end;
 
-
-
+

To give a user permission to perform a particular operation on a particular object you call acs_permission.grant_permission like this: -

+ 
 
     acs_permission.grant_permission (
       object_id => some_object_id,
       grantee_id => some_party_id,
       privilege => 'some_privilege_name'
       );
 
-
-
+

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. -

-Object Context

Object Context

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 address_book table: -

------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

... scope user_id group_id ...
... user 123 � ...
... group � 456 ...
... public � � ...

... scope user_id group_id ...
... user 123 � ...
... group � 456 ...
... public � � ...

In this way, the scoping columns identify the security context in -which a given object belongs, where each context is either a -person or a group of people or the general public +which a given object belongs, where each context is either a +person or a group of people or the general public (itself a group of people). -

In OpenACS 4.5, rather than breaking the world into a limited set of scopes, -every object lives in a single context. A context is just an +every object lives in a single context. 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 'f' if you want to override the default permissions in a subtree of some context. -

A good example of how to use this hierarchy is in the bboard +

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. -

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: -

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 default_context @@ -325,33 +220,25 @@ some object has no permissions attached to it, and its value for security_inherit_p is 'f', or context_id is null, then we use this context by default. -

-Example

Example

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 these instructions on how to use anonymous checkouts and then checkout the module acs-packages/notes: -

 
 % export CVSROOT=:pserver:anonymous@cvs.arsdigita.com:/usr/local/cvsroot
 % cvs login # the password is acsrules
 % cvs checkout acs-packages/notes
 
-

After you have downloaded the package, look at the index.tcl page in the www directory. You can also look at the code in your browser. The code should look something like this: -

+
 
 # main index page for notes.
 
@@ -396,46 +283,39 @@
 
 ad_return_template
 
-
-
+

This example shows both the Tcl and PL/SQL APIs for checking permissions. The Tcl proc ad_permission_p and the PL/SQL function acs_permission.permission_p 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. -

It also shows how we display more complicated items using the template -system. The code here creates a multirow data source, i.e. a +system. The code here creates a multirow 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. -

Next, look at the index.adp. It is pretty complicated. The main part of this page uses a multiple template tag. If you want to experiment, you can replace the main body of the multiple tag with this: -

+
 
 <multiple name=notes>
 <td>@notes.title@</td><td>@notes.body</td>
 </multiple>
 
-
-
+

This will just make a table with one note per row. -

Now put the more complex code back. You'll notice a lot of stuff like this: -

+
 
 <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>
 
-
-
+

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 if tag is something that the OpenACS 4.5 template system defines for you to support conditional presentation. The templates developer guide provides more information about this. -

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. -

-Summary

Summary

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. -

In the next section, we'll look at a more complex page for adding and editing notes, and discuss these issues further. -

($Id$)

- - - - - - - - - - - -

-Prev	Home	Next -
Using Templates in OpenACS 4.5	Up	Writing OpenACS 4.5 Application Pages

- rmello at fslc.usu.edu -

Prev	Home	Next
Using Templates in OpenACS 4.5	Up	Writing OpenACS 4.5 Application Pages

- - +

-Install PostgreSQL 7.1.3

+Install PostgreSQL 7.1.3

Prev	Chapter 2. Installing on Unix/Linux	Next

Install PostgreSQL 7.1.3

+ by Vinod Kurup
+ OpenACS docs are written by the named authors, but may be edited + by OpenACS documentation staff. +

Skip this page if you're not interested in PostgreSQL. -

-Download the PostgreSQL source

Download the PostgreSQL source

Download PostgreSQL 7.1.3 from the mirror closest to you. The list of mirrors is at http://www.postgresql.org. Download it to /tmp. -

As root, unpack it into /usr/local/src -

 joeuser:~$ su -
 Password: ***********
 root:~# cd /usr/local/src
-root:/usr/local/src# tar xzf /tmp/postgresql-7.1.3.tar.gz

-Create the Postgres user

+root:/usr/local/src# tar xzf /tmp/postgresql-7.1.3.tar.gz

Create the Postgres user

Still as root, 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 postgres user a password: -

+	
 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: ***********
-

-Set up postgres's environment variables

+Password: ***********

Set up postgres's environment variables

Edit /usr/local/pgsql/.bash_profile so it looks like this: -

 LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/pgsql/lib
 PATH=$PATH:/usr/local/pgsql/bin
 
-export PATH LD_LIBRARY_PATH

+export PATH LD_LIBRARY_PATH

Logout and login again as postgres. Use the echo command to make sure that /usr/local/pgsql/bin is now in your PATH -

 postgres:~$ exit
 logout
 joeuser:~$ su - postgres
 Password: ************
 postgres:~$ echo $PATH
-/usr/local/bin:/usr/bin:/bin: ... :/usr/local/pgsql/bin

-Compile and install PostgreSQL

+/usr/local/bin:/usr/bin:/bin: ... :/usr/local/pgsql/bin

Compile and install PostgreSQL

First, we run ./configure 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 @@ --enable-multibyte. If you want to see what the other possibilities are, run ./configure --help. -

 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

+postgres:/usr/local/src/postgresql-7.1.3$ make all

Compilation will take a while (about 10 minutes). Once it's done, you will see the following message: -

-All of PostgreSQL is successfully made. Ready to install.

+All of PostgreSQL is successfully made. Ready to install.

Next, we'll install PostgreSQL. If all is successful, you'll see the following “Thank You” message. -

 postgres:/usr/local/src/postgresql-7.1.3$ make install
 ...
-Thank you for choosing PostgreSQL, the most advanced open source database engine.

-Prepare PostgreSQL for OpenFTS

+Thank you for choosing PostgreSQL, the most advanced open source database engine.

Prepare PostgreSQL for OpenFTS

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. -

 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

-Start PostgreSQL

The initdb command initializes +postgres:/usr/local/src/postgresql-7.1.3/contrib/intarray$ make install

Start PostgreSQL

The initdb command initializes the database. pg_ctl is used to start up PostgreSQL. -

 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

+postmaster successfully started

PostgreSQL errors will be logged in /usr/local/pgsql/data/server.log -

-Set up plpgsql and allow nsadmin access

Set up plpgsql and allow nsadmin access

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 nsadmin, so that aolserver can access the database. (Don't worry that you don't have a nsadmin user yet - we'll create that in the next chapter.) -

+	
 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
-

-Test PostgreSQL

+CREATE USER

Test PostgreSQL

Create a database and try some simple commands. The output should be as shown. -

+	
 postgres:~$ createdb mytestdb
 CREATE DATABASE
 postgres:~$ psql mytestdb
@@ -218,35 +142,22 @@
 
 mytestdb=# \q
 postgres:~$ dropdb mytestdb
-DROP DATABASE
-

-Getting PostgreSQL to start on boot

+DROP DATABASE

Getting PostgreSQL to start on boot

Download postgresql.txt to /tmp. Then follow the instructions specific to your distribution: -

Debian:

 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

Test the script

+root:~# chmod 700 /etc/init.d/postgresql

Test the script

 root:~# /etc/init.d/postgresql stop
-Stopping PostgreSQL: ok

+Stopping PostgreSQL: ok

If PostgreSQL successfully stopped, then use the following command to make sure that the script is run appropriately at boot and shutdown. -

+		
 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
-

-
Red Hat:
-
```
+postgres:~$ exit
```

Red Hat:

 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

Test the script

+root:~# chmod 700 /etc/rc.d/init.d/postgresql

Test the script

 root:~# /etc/rc.d/init.d/postgresql stop
-Stopping PostgreSQL: ok

If PostgreSQL successfully stopped, then use the following +Stopping PostgreSQL: ok

If PostgreSQL successfully stopped, then use the following command to make sure that the script is run appropriately at boot and shutdown. -

 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

-
SuSE:
-
```
+postgres:~$ exit
```

SuSE:

 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

Test the script

+root:~# chmod 700 /etc/rc.d/init.d/postgresql

Test the script

 root:~# /etc/rc.d/init.d/postgresql stop
-Stopping PostgreSQL: ok

+Stopping PostgreSQL: ok

If PostgreSQL successfully stopped, then use the following command to make sure that the script is run appropriately at boot and shutdown. -

+		
 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
-
+root:/etc/rc.d/init.d# rm S20postgresql

Test configuration -

 root:/etc/rc.d/init.d # cd
 root:~ # /etc/rc.d/init.d/rc2.d/S20postgresql start
 Starting PostgreSQL: ok
-root:~ # exit

+root:~ # exit

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) -

-Learn more about PostgreSQL

Learn more about PostgreSQL

Here are some links: -

+
- Official PostgreSQL Docs -
- +
- Migrating from 7.0 to 7.1 -
- +
- techdocs.postgresql.org -
- +
- PostgreSQL Performance Tuning -
-

($Id$)

- - - - - - - - - - - -

-Prev	Home	Next -
Install Oracle 8.1.7	Up	Install AOLserver 3.3+ad13

- rmello at fslc.usu.edu -

-Programming with AOLserver

+Programming with AOLserver

Prev	Chapter 5. Other Developer Resources	Next

Programming with AOLserver

by Michael Yoon, Jon Salz and Lars Pind. -

-The `global` command

-When using AOLserver, remember that there are effectively two types +
+ OpenACS docs are written by the named authors, but may be edited + by OpenACS documentation staff. +

The `global` command

+When using AOLserver, remember that there are effectively two types of global namespace, not one: -

-Server-global: As you'd expect, there is +
1. Server-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 nsv API (which supersedes ns_share from the pre-3.0 API). -
2. -Script-global: Each Tcl script (ADP, Tcl page, +
3. Script-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.
-
+execution.

The Tcl built-in command global -accesses script-global, not server-global, variables from within a +accesses script-global, not server-global, variables from within a procedure. This distinction is important to understand in order to use global correctly when programming AOLserver. -

Also, AOLserver purges all script-global variables in a thread (i.e., Tcl +

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 thread-global variables. Given +be better described as thread-global variables. Given AOLserver's behaviour, however, "script-global" is a more -appropriate term.

-Threads and Scheduled Procedures

+appropriate term.

Threads and Scheduled Procedures

ns_schedule_proc and ad_schedule_proc each take a -thread 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. -

It turns out that whenever a task scheduled with ns_schedule_proc +

It turns out that whenever a task scheduled with ns_schedule_proc -thread or ad_schedule_proc -thread t 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 every -time the task is executed - and it is a very expensive process that -should not be taken lightly!

-The moral: if you have a lightweight scheduled procedure +server initialization into the new interpreter). This happens every +time the task is executed - and it is a very expensive process that +should not be taken lightly! The moral: if you have a lightweight scheduled procedure which runs frequently, don't use the -thread -switch. -Note also that thread is initialized with a copy of what was +switch. 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 APM watch facility), that will not be reflected in the scheduled -thread. -

- - -Using return - +thread. Using return The return 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 return to @@ -108,12 +61,7 @@ executed because the thread was not stopped. Note that return -code return can be used in circumstances where the procedure will only be called from two levels deep. - - - - -Returning More Than One Value From a Function - + Returning More Than One Value From a Function Many functions have a single return value. For instance, empty_string_p 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.: - -+ set user_info [ad_get_user_info $user_id] set first_name [lindex $user_info 0] set email [lindex $user_info 1] - -AOLserver/Tcl generally has three mechanisms that we like, for returning + 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. -Using Arrays and Pass-By-Value - +circumstances. Using Arrays and Pass-By-Value The one we generally prefer is returning an array get-formatted list. It has all the nice properties of pass-by-value, and it uses Tcl arrays, which have good native support. - -+ 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))" - - + You could also have done this by using an array internally and using array get: - -+ 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] } - -Using Arrays and Pass-By-Reference - + Using Arrays and Pass-By-Reference 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. - -The transformation of the array into a list and back to an + 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. - +almost not at all on the size of the entries. You implement pass-by-reference in Tcl by taking the name of an array as an argument and upvar it. - -+ ad_proc ad_get_user_info { -array:required @@ -202,28 +138,22 @@ doc_body_append "$user_info(namelink) ($user_info(emaillink))" - -We prefer pass-by-value over pass-by-reference. Pass-by-reference makes + 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 upvars through several layers of the call stack, you'll have -a hard time debugging. -Multisets: Using ns_sets and Pass-By-Reference - -An array is a type of set, which means you can't have multiple +a hard time debugging. Multisets: Using ns_sets and Pass-By-Reference +An array is a type of set, 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 multiset or bag. - -If your data can have multiple entries with the same key, +the same key are known as a multiset or bag. + If your data can have multiple entries with the same key, you should use the AOLserver built-in ns_set. You can also do a case-insensitive lookup on an ns_set, 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. -You always use pass-by-reference with ns_sets, since they +exact properties. You always use pass-by-reference with ns_sets, 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. -+from a string representation. Instead, you pass the handle to the set. 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])" - - + We don't recommend ns_set 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. - -Consider for example a loop over the entries in a ns_set as -compared to an array: -+ Consider for example a loop over the entries in a ns_set as +compared to an array: # ns_set variant set size [ns_set size $myset] @@ -263,11 +190,9 @@ puts "$myarray($name) = $myarray($name)" } - - + And this example of constructing a value: - -+ # ns_set variant set myset [ns_set create] @@ -281,40 +206,12 @@ baz $baz ] - - + ns_sets are designed to be lightweight, so memory consumption should not be a problem. However, when using ns_set get to perform lookup by name, they perform a linear lookup, whereas arrays use a hash table, so ns_sets are slower than arrays when the number of entries is large. - - ($Id$) - -

- - - - - - - - - - - - - - -Prev Home Next - Object Identity Up Chapter 6. Engineering Standards - - - rmello at fslc.usu.edu - - + ($Id$)

Prev	Home	Next
Object Identity	Up	Chapter 6. Engineering Standards

rmello at fslc.usu.edu

vinod@kurup.com -

-

- - +

-Using PSGML mode in Emacs

-By David Lutterkort -

-What it is

PSGML Mode is a mode for editing, umm, SGML and XML documents in emacs. It +Using PSGML mode in Emacs

Prev	Chapter 6. Engineering Standards	Next

Using PSGML mode in Emacs

+By David Lutterkort
+ OpenACS docs are written by the named authors, but may be edited + by OpenACS documentation staff. +

What it is

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. If you give it the right DTD, that is. But even without a DTD, +used. If you give it the right DTD, that is. But even without a DTD, it can save you some typing since pressing C-c/ will close an open -tag automatically.

-Where to get it

Most newer emacsen come with PSGML mode preinstalled. You can find out +tag automatically.

Where to get it

Most newer emacsen come with PSGML mode preinstalled. You can find out whether your emacs has it with the locate-library command. In Emacs, type M-x locate-library and enter psgml. Emacs will tell -you if it found it or not.

If you don't have PSGML preinstalled in your Emacs, there are two -things you can do:

On Linux: Get the +you if it found it or not.
If you don't have PSGML preinstalled in your Emacs, there are two +things you can do:
1. On Linux: Get the psgml rpm from RedHat's -docbook-tools and install it as usual.
2. On other systems: Get the tarball from the PSGML Website. -Unpack it and follow the install instructions.
-

-Using `CATALOG` files

The easiest way to teach PSGML mode about a DTD is by adding it to your +docbook-tools and install it as usual.

On other systems: Get the tarball from the PSGML Website. +Unpack it and follow the install instructions.

Using `CATALOG` files

The easiest way to teach PSGML mode about a DTD is by adding it to your own CATALOG. Here is an example of how you can set that up for the -Docbook XML DTD.

Get the Docbook XML DTD -zip archive from docbook.org -

Go somewhere in your working directory and do

+Docbook XML DTD.

Get the Docbook XML DTD +zip archive from docbook.org

Go somewhere in your working directory and do

       mkdir -p dtd/docbook-xml
       cd dtd/docbook-xml
       unzip -a <docbook XML DTD zip archive>
    
-

-
Create a file with the name CATALOG in the dtd -directory and put the line
-
```
+
```
Create a file with the name CATALOG in the dtd +directory and put the line
```
       CATALOG "docbook-xml/docbook.cat"
-
```
-
+

in it. By maintaining your own CATALOG, it is easy to add more -DTD's without changing your emacs settings. (How about that HTML 4.01 DTD you +DTD's without changing your emacs settings. (How about that HTML 4.01 DTD you always wanted to get from W3C ? The -DTD is in the zip archives and tarballs available on the site. -

-
That's it. Now you are ready to tell emacs all about PSGML mode and -that funky CATALOG -
-

-
-What to tell emacs
-

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.

That's it. Now you are ready to tell emacs all about PSGML mode and +that funky CATALOG

What to tell emacs

If you installed PSGML mode in a non-standard location, e.g., somewhere in your home directory, you need to add this to the load-path by adding -this line to your .emacs file:

+this line to your .emacs file:
       (add-to-list 'load-path "/some/dir/that/contains/psgml.elc")
    
-
-To let PSGML mode find your CATALOG and to enable PSGML mode for
-all your editing, add these lines to your .emacs:
-+
To let PSGML mode find your CATALOG and to enable PSGML mode for
+all your editing, add these lines to your .emacs:
       (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")
    
-
-If you want font-locking and indentation, you can also add these lines
-into the .emacs file:
-+
If you want font-locking and indentation, you can also add these lines
+into the .emacs file:
       (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))))
    
-
-

-What is a `DOCTYPE` ?

All SGML and XML documents that should conform to a DTD have to declare a +

What is a `DOCTYPE` ?

All SGML and XML documents that should conform to a DTD have to declare a doctype. For the docbook XML, all your .xml files whould start with -the line

+the line

       <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "docbookx.dtd">
    
-

If your document is only part of a larger XML document, you can tell PSGML -mode about it by appending the following lines to your file. In this -case, do not include a DOCTYPE declaration in your file.

If your document is only part of a larger XML document, you can tell PSGML +mode about it by appending the following lines to your file. In this +case, do not include a DOCTYPE declaration in your file.

       <!--
        Local Variables:
        sgml-parent-document: ("top.xml" "book" "sect1")
        End:
       -->
    
-

Which says that the parent of this document can be found in the file +

Which says that the parent of this document can be found in the file top.xml, that the element in the parent that will enclose the current document is a book and that the current file's topmost -element is a sect1.

-How to use it

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:

---- - - - - - - - - - - - - - - - - - - - - - - -

Key	Command
`C-c C-e`	Insert an element. Uses completion and only lets you insert elements that -are valid
`C-c C-a`	Edit attributes of enclosing element.
`C-c C-x C-i`	Show information about the document's DTD.
`C-c C-x C-e`	Describe element. Shows for one element which elements can be parents, -what its contents can be and lists its attributes.

-Further reading

Start with the OpenACS Documentation Guide -

($Id$)

- - - - - - - - - - - -

-Prev	Home	Next -
OpenACS Documentation Guide	Up	Detailed Design Documentation Template

- rmello at fslc.usu.edu -

+element is a sect1.

How to use it

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:

Key	Command
`C-c C-e`	Insert an element. Uses completion and only lets you insert elements that +are valid
`C-c C-a`	Edit attributes of enclosing element.
`C-c C-x C-i`	Show information about the document's DTD.
`C-c C-x C-e`	Describe element. Shows for one element which elements can be parents, +what its contents can be and lists its attributes.

-OpenACS 4.5 Release Notes

- by Don Baccus and - Vinod Kurup -

- This is a beta release of OpenACS 4.5. This release has been subjected +OpenACS 4.5 Release Notes

Prev	Chapter 1. High level information: What is OpenACS?	Next

OpenACS 4.5 Release Notes

+ by Don Baccus
+ OpenACS docs are written by the named authors, but may be edited + by OpenACS documentation staff. +

+ This is a final 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. -

Please report bugs using our - + Software Development Manager at the OpenACS website. The latest - information on installating this alpha release under Oracle 8.1.6/7 + information on installing this 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. -

- You may want to begin by reading our installation documentation for Installing on Unix/Linux or Chapter 3. Note that the Windows - documentation is not current for OpenACS 4.5. -

+ You may want to begin by reading our installation documentation for + Installing on Unix/Linux or Installing on Windows. Note + that the Windows documentation is not current for OpenACS 4.5, + but an alternative is to use John Sequeira's Oasis VM + project. +

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. -

-Site Wide Searching

Site Wide Searching

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. -

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'. -

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, Set Up OpenFTS. As with the Oracle version, there are steps you must take manually in order to get this feature working. -

-Testing Notes

Testing Notes

Here are some notes from our testing group. While not quite up to date it should give you some ideas of where things stand. -

+	
  Summarised Testing Status
 
 Skin
@@ -240,33 +203,6 @@
 Test Coverage: Minimal
 Suggested Status: Alpha
 Comments: Don tested personally
-	
-

($Id$)

- - - - - - - - - - - -

-Prev	Home	Next -
Overview	Up	Part Part II. For OpenACS Admins

- rmello at fslc.usu.edu -

Prev	Home	Next
Overview	Up	Part Part II. For OpenACS Admins

- - +

-The Request Processor

By Pete Su -

-Overview

+The Request Processor

Prev	Chapter 4. OpenACS Developer's Guide	Next

The Request Processor

+By Pete Su +
+ OpenACS docs are written by the named authors, but may be edited + by OpenACS documentation staff. +

Overview

This document is a brief introduction to the OpenACS 4.5 Request Processor; more details can be found in the OpenACS 4 Request Processor Design. Here we cover the high level concepts behind the system, and implications and usage for the application developer. -

-The Old Way

The Old Way

In older versions of the OpenACS, the mapping between URLs and pages was -simple. AOLserver (the usual webserver for the OpenACS) would find the +simple. AOLserver, the usual webserver for the OpenACS, would find the appropriate file by appending the server's page-root to the path in the URL and returning that file to the user. For example, a user's request for a URL like "http://foo-service.com/bar.html" would cause @@ -50,14 +20,10 @@ mechanism for the following requirements of larger web services: -

Support for more flexible mappings from URLs to content -
Robust user authentication -
Page level access control -

Support for more flexible mappings from URLs to content +
Robust user authentication +
Page level access control +

To achieve this functionality above in OpenACS 3.x, developers used an ad @@ -66,50 +32,35 @@ Request Processor, along with the OpenACS Package Manager, centralizes and unifies this functionality, making it more transparent and readily available to developers. -

-The New Way

The New Way

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 http://someserver.com/notes/somepage.adp. -

[D]

Stage 1: Search Site Map

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 Packages, and further discussed in the section called “Writing OpenACS 4.5 Application Pages”). This data model maps URLs to objects representing content, and these objects are typically package instances. -

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 ad_conn procedure, which is described in detail in OpenACS 4 Request Processor Design. The page development tutorial shows you how to use this interface to make your pages aware of which instance was requested. -

Stage 2: Authentication

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 security/session handler 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. -

Stage 3: Authorization

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 permissions system. In @@ -119,17 +70,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. -

Stage 4: URL Processing, File Search

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: .html, .tcl and .adp. -

If the RP can't find any matching files with the expected extensions, it will look for virtual-url-handler files, or .vuh files. A .vuh file will be executed as if it were a Tcl @@ -140,126 +87,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 OpenACS 4 Request Processor Design. -

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. -

-Basic API

Basic API

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 ad_conn interface, and the following calls should be useful to you when developing dynamic pages: -

[ad_conn user_id] + [ad_conn user_id] - - +: The ID of the user associated with this request. By convention this is zero if there is no user. -
[ad_conn session_id] +
[ad_conn session_id] -: +; The ID of the session associated with this request. -
[ad_conn url] +
[ad_conn url] -: +; The URL associated with the request. -
[ad_conn urlv] +
[ad_conn urlv] -: +; The URL associated with the request, represented as a list instead of a single string. -
[ad_conn file] +
[ad_conn file] -: +; The actual local filesystem path of the file that is being served. -
[ad_conn object_url] +
[ad_conn object_url] -: +; If the URL refers to a site map object, this is the URL to the root of the tree where the object is mounted. -
[ad_conn package_url] +
[ad_conn package_url] -: +; If the URL refers to a package instance, this is the URL to the root of the tree where the package is mounted. -
[ad_conn extra_url] +
[ad_conn extra_url] -: +; 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. -
[ad_conn object_id] +
[ad_conn object_id] -: +; If the URL refers to a site map object, this is the ID of that object. -
[ad_conn package_id] +
[ad_conn package_id] -: +; If the URL refers to a package instance, this is the ID of that package instance. -
[ad_conn package_key] +
[ad_conn package_key] -: +; If the URL refers to a package instance, this is the unique key name of the package. -

($Id$)

- - - - - - - - - - - -

-Prev	Home	Next -
OpenACS 4.5 Packages	Up	The OpenACS Database Access API

- rmello at fslc.usu.edu -

-System/Application Requirements Template

By You -

-Introduction

- Briefly explain to the reader what this document is for, whether +System/Application Requirements Template

Prev Chapter 6. Engineering Standards Next

System/Application Requirements Template

By You

+ OpenACS docs are written by the named authors, but may be edited + by OpenACS documentation staff. +

Introduction

+ 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. -

-
-Vision Statement
-

+ understand. +

Vision Statement

- Very broadly, describe how the system meets a need of a business, + 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. -

-
-System/Application Overview
-

- Discuss the high-level breakdown of the components that make up + what the business value of the system is. +

System/Application Overview

+ 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. -

- You should also state the context and dependencies of the system + the system allows, etc. +

+ 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. -

-
-Use-cases and User-scenarios
-

- Determine the types or classes of users who would use the + describe how it uses kernel services, like permissions or subsites. +

Use-cases and User-scenarios

+ 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. -

-
-Optional: Competitive Analysis
-

- Describe other systems or services that are comparable to what + take, and how the system would support them. +

Optional: Competitive Analysis

+ 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. -

-
-
-Related Links
-
Include all pertinent links to supporting and related material, - such as:
-
-
System/Package "coversheet" - where all documentation for this software is linked off of
-
Design document
-
Developer's guide
-
User's guide
-
Other-cool-system-related-to-this-one document
-
Test plan
-
Competitive system(s)
-
-
-

-
-Requirements
-

- The main course of the document, requirements. Break up the + Design doc, so write about it where you deem most appropriate. +

Requirements

+ 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. -

-
10.0 A Common Solution
-
+ key requirements that may arise. +
10.0 A Common Solution
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. -
-
-
10.0.1
-
+
10.0.1
The system should not make any assumptions about how pages should look or function. -
-
10.0.5
-
+
10.0.5
Publishers should be able to change the default presentation of any module using a single methodology with minimal exposure to code. -
-
-
-
+

For guidelines writing requirements, take a look at the quality standards, along with a good example, such as OpenACS 4.5 Package Manager Requirements. -

Besides writing requirements in natural language, consider using the following techniques as needed: -

Pseudocode - a quasi programming language, combining the +
- Pseudocode - a quasi programming language, combining the informality of natural language with the strict syntax and control - structures of a programming language.
- Finite State Machines - a hypothetical machine that can be in + structures of a programming language.
- 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.
- Decision Trees and Decision Tables - similar to FSMs, but better - suited to handle combinations of inputs.
- Flowcharts - easy to draw and understand, suited for event and - decision driven systems. UML is the industry standard here.
- Entity-Relationship diagrams - a necessary part of Design + inputs mathematically determines the system outputs.
- Decision Trees and Decision Tables - similar to FSMs, but better + suited to handle combinations of inputs.
- Flowcharts - easy to draw and understand, suited for event and + decision driven systems. UML is the industry standard here.
- Entity-Relationship diagrams - a necessary part of Design documents, sometimes a high-level ER diagram is useful for - requirements as well.
-

-Optional: Implementation Notes

- Although in theory coding comes after design, which comes after + requirements as well.

Optional: Implementation Notes

+ 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. -

-
-
-Revision History
-
------ - - - - - - - - - - - - - - - - - - - - - - - - - - -

Document Revision # Action Taken, Notes When? By Whom?
0.3 Edited further, incorporated feedback from Michael Yoon 9/05/2000 Kai Wu
0.2 Edited 8/22/2000 Kai Wu
0.1 Created 8/21/2000 Josh Finkler, Audrey McLoghlin
-
($Id$)
-
-

-
- - - - - - - - - - - -
-Prev Home Next -
Detailed Design Documentation Template Up Release Version Numbering
-
-
- rmello at fslc.usu.edu -
-

+ other programmers. +

Revision History

Document Revision #	Action Taken, Notes	When?	By Whom?
0.3	Edited further, incorporated feedback from Michael Yoon	9/05/2000	Kai Wu
0.2	Edited	8/22/2000	Kai Wu
0.1	Created	8/21/2000	Josh Finkler, Audrey McLoghlin

($Id$)

Prev	Home	Next
Detailed Design Documentation Template	Up	Release Version Numbering

rmello at fslc.usu.edu

- - +

- -OpenACS 4 Request Processor Design - -by Rafael H. Schloming - - - -Essentials - -OpenACS 4 Request Processor Requirements - -/packages/acs-kernel/tcl/request-processor-procs.tcl - -/packages/acs-kernel/tcl/request-processor-init.tcl - -/packages/acs-kernel/tcl/site-nodes-procs.tcl - -/packages/acs-kernel/tcl/site-nodes-init.tcl - -/packages/acs-kernel/sql/site-nodes-create.sql - - - - -Introduction -The request processor is the set of procs that responds to every HTTP +OpenACS 4 Request Processor Design Prev Chapter 7. Kernel Documentation Next OpenACS 4 Request Processor Design +by Rafael H. Schloming + OpenACS docs are written by the named authors, but may be edited + by OpenACS documentation staff. + Essentials OpenACS 4 Request Processor Requirements +/packages/acs-kernel/tcl/request-processor-procs.tcl +/packages/acs-kernel/tcl/request-processor-init.tcl +/packages/acs-kernel/tcl/site-nodes-procs.tcl +/packages/acs-kernel/tcl/site-nodes-init.tcl +/packages/acs-kernel/sql/site-nodes-create.sql Introduction 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. - - - -Related Systems -OpenACS 4.5 Package Manager Design - - - -Terminology - - -pageroot -- Any directory that contains scripts and/or +provides to the browser. Related Systems OpenACS 4.5 Package Manager Design Terminology +pageroot -- 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. - -global pageroot -(/web/servicename/www) -- Files appearing under +OpenACS installation is required to serve files from multiple pageroots. global pageroot +(/web/servicename/www) -- Files appearing under this pageroot will be served directly off the base url -http://www.servicename.com/ - -package root -(/web/servicename/packages) -- Each subdirectory of +http://www.servicename.com/ package root +(/web/servicename/packages) -- Each subdirectory of the package root is a package. A typical OpenACS installation will have several -packages. - -package pageroot -(/web/servicename/packages/package_key/www) --- This is the pageroot for the package_key package. - -request environment (ad_conn) -- This is +packages. package pageroot +(/web/servicename/packages/package_key/www) +-- This is the pageroot for the package_key package. request environment (ad_conn) -- This is a global namespace containing variables associated with the current -request. - -abstract URL -- A URL with no extension that doesn't -directly correspond to a file in the filesystem. - -abstract file or abstract path -- A URL +request. abstract URL -- A URL with no extension that doesn't +directly correspond to a file in the filesystem. abstract file or abstract path -- 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. - -concrete file or concrete path -- A file -or path that actually references something in the filesystem. - - - - -System Overview -Package Lookup -One of the first things the request processor must do is to determine +not directly correspond to a file in the filesystem. concrete file or concrete path -- A file +or path that actually references something in the filesystem. System Overview Package Lookup 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 -package_url (/offices/boston/announcements/), and the +package_url (/offices/boston/announcements/), and the abstract (no extension info) file path (index). The request processor must be -able to figure out which package_id is associated with a +able to figure out which package_id 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. -Authentication and Authorization -Once the request processor has located both the package_id and concrete +therefore this mapping is stored in the database. Authentication and Authorization Once the request processor has located both the package_id and concrete file associated with the request, authentication is performed by the session security system. After authentication has been performed the user is authorized to have read access for the given package by the OpenACS 4 Permissions Design. If authorization succeeds then the request is served, otherwise it is -aborted. -Concrete File Search -To actually serve a file, the request processor generates an ordered list +aborted. Concrete File Search 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. -Virtual URL Handlers -If no file is found during the concrete file search, then the request -processor searches the filesystem for a virtual url handler -(.vuh) file. This file contains normal tcl code, and is in +file is found at any of the searched locations then it is served. Virtual URL Handlers If no file is found during the concrete file search, then the request +processor searches the filesystem for a virtual url handler +(.vuh) 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 path_info is set to the portion of the url -not matched by the .vuh script, and the script is sourced. This +ad_conn variable path_info is set to the portion of the url +not 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. - - - -Site Nodes -The request processor manages the mappings from URL patterns to package +many packages installed. Site Nodes 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. -The memory structure used to store the site_nodes mapping is a hash table +in memory. 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. - - - -Request Environment -The request environment is managed by the procedure -ad_conn. Variables can be set and retrieved through use of +number of entries in the mapping. Request Environment The request environment is managed by the procedure +ad_conn. 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. - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Request processor [ad_conn urlv] A list containing each element of the URL [ad_conn url] The URL associated with the request. [ad_conn file] The filepath including filename of the file being served [ad_conn request] The number of requests since the server was last started [ad_conn start_clicks] The system time when the RP starts handling the request � -Session System Variables: set in -sec_handler, check security with ad_validate_security_info [ad_conn session_id] The unique session_id coming from the sequence -sec_id_seq - [ad_conn user_id] User_id of a person if the person is logged in. Otherwise, it is -blank [ad_conn sec_validated] This becomes "secure" when the connection uses SSL � Database API [ad_conn db,handles] What are the list of handles available to AOL? [ad_conn db,n_handles_used] How many database handles are currently used? [ad_conn db,last_used] Which database handle did we use last? [ad_conn db,transaction_level,$db] Specifies what transaction level we are in [ad_conn db,db_abort_p,$dbh] Whether the transaction is aborted � APM [ad_conn xml_loaded_p] Checks whether the XML parser is loaded so that it only gets loaded once. -Set in apm_load_xml_packages � Packages [ad_conn package_id] The package_id of the package associated with the URL. [ad_conn package_url] The URL on which the package is mounted. � Miscellaneous [ad_conn system_p] If true then the request has been made to one of the special directories +ad_conn subsumes the functionality of ns_conn. - - - - - - - - -Request processor [ad_conn urlv] A list containing each element of the URL [ad_conn url] The URL associated with the request. [ad_conn file] The filepath including filename of the file being served [ad_conn request] The number of requests since the server was last started [ad_conn start_clicks] The system time when the RP starts handling the request � Session System Variables: set in +sec_handler, check security with ad_validate_security_info [ad_conn session_id] The unique session_id coming from the sequence +sec_id_seq [ad_conn user_id] User_id of a person if the person is logged in. Otherwise, it is +blank [ad_conn sec_validated] This becomes "secure" when the connection uses SSL � Database API [ad_conn db,handles] What are the list of handles available to AOL? [ad_conn db,n_handles_used] How many database handles are currently used? [ad_conn db,last_used] Which database handle did we use last? [ad_conn db,transaction_level,$db] Specifies what transaction level we are in [ad_conn db,db_abort_p,$dbh] Whether the transaction is aborted � APM [ad_conn xml_loaded_p] Checks whether the XML parser is loaded so that it only gets loaded once. +Set in apm_load_xml_packages � Packages [ad_conn package_id] The package_id of the package associated with the URL. [ad_conn package_url] The URL on which the package is mounted. � Miscellaneous [ad_conn system_p] 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. � Documentation [ad_conn api_page_documentation_mode_p] � - - - - - - - - - - - - - - - - -Prev Home Next - OpenACS 4 Request Processor Requirements Up Database Access API - - - rmello at fslc.usu.edu - - +authorization has been performed. � Documentation [ad_conn api_page_documentation_mode_p] � Prev Home Next OpenACS 4 Request Processor Requirements Up Database Access API rmello at fslc.usu.edu vinod@kurup.com - - - - + Index: openacs.org-dev/packages/acs-core-docs/www/rp-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs.org-dev/packages/acs-core-docs/www/rp-requirements.html,v diff -u -r1.1.1.1 -r1.1.1.2 --- openacs.org-dev/packages/acs-core-docs/www/rp-requirements.html 9 Jul 2002 17:34:57 -0000 1.1.1.1 +++ openacs.org-dev/packages/acs-core-docs/www/rp-requirements.html 11 Aug 2002 00:42:48 -0000 1.1.1.2 @@ -1,131 +1,29 @@ - - - -OpenACS 4 Request Processor Requirements - - - - - - - - - - - - - - -Prev Chapter 7. Kernel Documentation Next - - - - - -OpenACS 4 Request Processor Requirements - -by Rafael H. Schloming - - - -Introduction -The following is a requirements document for the OpenACS 4.0 request +OpenACS 4 Request Processor Requirements Prev Chapter 7. Kernel Documentation Next OpenACS 4 Request Processor Requirements +by Rafael H. Schloming + OpenACS docs are written by the named authors, but may be edited + by OpenACS documentation staff. + Introduction 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. - - - -Vision Statement -Most web servers are designed to serve pages from exactly one static +for flexible user controlled url structures, and subsites. Vision Statement 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. - - - -System Overview -The request processor's functionality can be split into two main -pieces. - - -Set up the environment in which a server side script expects to run. This -includes things like: - -Initialize common variables associated with a request. -Authenticate the connecting party. -Check that the connecting party is authorized to proceed with the -request. -Invoke any filters associated with the request URI. - - -Determine to which entity the request URI maps, and deliver the content +toolkit full of reusable and reconfigurable components. System Overview The request processor's functionality can be split into two main +pieces. Set up the environment in which a server side script expects to run. This +includes things like: Initialize common variables associated with a request. Authenticate the connecting party. Check that the connecting party is authorized to proceed with the +request. Invoke any filters associated with the request URI. 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. - -It is essential that any errors that occur during the above steps be -reported to developers in an easily decipherable manner. - - - -Related Links -OpenACS 4 Request Processor Design - - - -Requirements -10.0 Multiple Pageroots - - -10.10 Pageroots may be combined into one URL space. - -10.20 Pageroots may be mounted at more than one location in the URL -space. - -20.0 Application Context - -20.10 The request processor must be able to determine a primary context +for the delivered content. It is essential that any errors that occur during the above steps be +reported to developers in an easily decipherable manner. Related Links OpenACS 4 Request Processor Design Requirements 10.0 Multiple Pageroots 10.10 Pageroots may be combined into one URL space. 10.20 Pageroots may be mounted at more than one location in the URL +space. 20.0 Application Context 20.10 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. -30.0 Authentication - -30.10 The request processor must be able to verify that the connecting -browser actually represents the party it claims to represent. -40.0 Authorization - -40.10 The request processor must be able to verify that the party the -connecting browser represents is allowed to make the request. -50.0 Scalability - - - - - - - - - - - - - - - - -Prev Home Next - OpenACS 4 Security Notes Up OpenACS 4 Request Processor Design - - - rmello at fslc.usu.edu - - +space. 30.0 Authentication 30.10 The request processor must be able to verify that the connecting +browser actually represents the party it claims to represent. 40.0 Authorization 40.10 The request processor must be able to verify that the party the +connecting browser represents is allowed to make the request. 50.0 Scalability Prev Home Next OpenACS 4 Security Notes Up OpenACS 4 Request Processor Design rmello at fslc.usu.edu vinod@kurup.com - - - - + Index: openacs.org-dev/packages/acs-core-docs/www/security-design.html =================================================================== RCS file: /usr/local/cvsroot/openacs.org-dev/packages/acs-core-docs/www/security-design.html,v diff -u -r1.1.1.1 -r1.1.1.2 --- openacs.org-dev/packages/acs-core-docs/www/security-design.html 9 Jul 2002 17:34:57 -0000 1.1.1.1 +++ openacs.org-dev/packages/acs-core-docs/www/security-design.html 11 Aug 2002 00:42:48 -0000 1.1.1.2 @@ -1,196 +1,53 @@ - - - -OpenACS 4 Security Design - - - - - - - - - - - - - - -Prev Chapter 7. Kernel Documentation Next - - - - - -OpenACS 4 Security Design - +OpenACS 4 Security Design Prev Chapter 7. Kernel Documentation Next OpenACS 4 Security Design -by Richard Li, Archit Shah - - - - -Essentials -OpenACS 4 Security Requirements - - - -Introduction - +by Richard Li, Archit Shah + OpenACS docs are written by the named authors, but may be edited + by OpenACS documentation staff. + Essentials OpenACS 4 Security Requirements Introduction 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. - -The atoms used in the implementation: - - -Cookies: RFC 2109, HTTP -State Management Mechanism -Cookies provide client side state. They are used to identify the + The atoms used in the implementation: Cookies: RFC 2109, HTTP +State Management Mechanism Cookies provide client side state. They are used to identify the user. Expiration of cookies is used to demark the end of a session. - - - -SHA: SHA-1 -This secure hash algorithm enables us to digitally sign cookies + SHA: SHA-1 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. - - - -SSL with server authentication: SSL v3 -SSL provides the client with a guarantee that the server is + SSL with server authentication: SSL v3 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. - - - - - - -Design - - -Sessions - + Design Sessions 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. - - - - -Authentication - + Authentication 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. - -One consequence of this security design is that secure tokens are not + 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. -Although this makes the site less user friendly, this design significantly +over SSL when performing some action that requires secure authentication. 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. - - - -Details -The authentication system issues up to four signed cookies (see below), -with each cookie serving a different purpose. These cookies are: - ------ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - name value max-age secure? ad_session_id session_id,user_id SessionTimeout no ad_user_login user_id Infinity no ad_user_login_secure user_id,random Infinity yes ad_secure_token session_id,user_id,random SessionLifetime yes - - -ad_session_id - -reissued on any hit separated by more than SessionRenew seconds from the -previous hit that received a cookie -is valid only for SessionTimeout seconds -is the canonical source for the session ID in ad_conn - - - -ad_user_login -is used for permanent logins - - -ad_user_login_secure - -is used for permanent secure logins -contains random garbage (ns_time) to prevent attack against the secure -hash - - - -ad_secure_token - - -is a session-level cookie from the browser's standpoint -its signature expires in SessionLifetime seconds -contains random garbage (ns_time) to prevent attack against the secure -hash -user_id is extraneous - - - - - - -Authentication Process -The Tcl function (sec_handler) is called by the request +authentication system by forcing all logins to occur over HTTPS. Details The authentication system issues up to four signed cookies (see below), +with each cookie serving a different purpose. These cookies are: name value max-age secure? ad_session_id session_id,user_id SessionTimeout no ad_user_login user_id Infinity no ad_user_login_secure user_id,random Infinity yes ad_secure_token session_id,user_id,random SessionLifetime yes ad_session_id reissued on any hit separated by more than SessionRenew seconds from the +previous hit that received a cookie is valid only for SessionTimeout seconds is the canonical source for the session ID in ad_conn ad_user_login is used for permanent logins ad_user_login_secure is used for permanent secure logins contains random garbage (ns_time) to prevent attack against the secure +hash ad_secure_token + is a session-level cookie from the browser's standpoint its signature expires in SessionLifetime seconds contains random garbage (ns_time) to prevent attack against the secure +hash user_id is extraneous Authentication Process The Tcl function (sec_handler) is called by the request processor to authenticate the user. It first checks the ad_session_id cookie. If there is no valid session in progress, a new session is created with sec_setup_session. 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 ad_session_id cookie is valid, the -user_id and session_id are pulled from it and put into ad_conn. - - - -Authenticating Secure Connections -Secure connections are authenticated slightly differently. The function +user_id and session_id are pulled from it and put into ad_conn. Authenticating Secure Connections Secure connections are authenticated slightly differently. The function ad_secure_conn_p 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.) -If secure authentication is required, the ad_secure_token +set during the server initialization.) If secure authentication is required, the ad_secure_token cookie is checked to make sure its data matches the data stored in ad_session_id. 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. -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. It is important to note that the integrity of secure authentication rests on the two Tcl function ad_secure_conn_p and ad_login_page. If ad_secure_conn_p is false, secure authentication is not required. If ad_login_page is false, -secure authentication is not required. - - - -Login Process -The Tcl function ad_user_login does two things. First it +secure authentication is not required. Login Process The Tcl function ad_user_login 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: - -previous login: other user, same user -permanent: was a permanent login requested? -secure: is this a secure connection? - - +manipulation of the permanent login cookies is based on 3 factors: previous login: other user, same user permanent: was a permanent login requested? secure: is this a secure connection? Both the secure and insecure permanent login cookie can have one of three actions taken on it: - - -set: cookie with no expiration is set -delete: set to "" with max age of 0, so it is expired -immediately -nothing: if the cookie is present, it remains - - + set: cookie with no expiration is set delete: set to "" with max age of 0, so it is expired +immediately nothing: if the cookie is present, it remains The current state of the permanent login cookies is not taken into account when determining the appropriate action. - - ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - previous login state permanent login requested secure connection action on insecure action on secure other y y set set same y y set set other y n set delete same y n set nothing same n y nothing delete other n y delete delete other n n delete delete same n n delete delete - -ad_user_login + previous login state permanent login requested secure connection action on insecure action on secure other y y set set same y y set set other y n set delete same y n set nothing same n y nothing delete other n y delete delete other n n delete delete same n n delete delete ad_user_login callssec_setup_session which actually calls sec_generate_session_id_cookie to generate the new cookie with refer to the appropriate user_id. If the connection is secure @@ -341,50 +98,30 @@ sec_setup_session call sec_generate_session_id_cookie. - - -ad_user_logout logs the user out by deleting all 4 cookies -that are used by the authentication system. - - - -Session Creation -The creation and setup of sessions is handled in + ad_user_logout logs the user out by deleting all 4 cookies +that are used by the authentication system. Session Creation The creation and setup of sessions is handled in sec_setup_session, which is called either to create a new session from sec_handler or from ad_user_login 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 n_sessions, last_visit, and -second_to_last_visit. -If there is no session already setup on this hit, a new session is +second_to_last_visit. If there is no session already setup on this hit, a new session is created. This happens when sec_setup_session is called from sec_handler. 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. -The users table is updated by +associated with a session to be carried over when a user logs in. The users table is updated by sec_update_user_session_info 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. - - - -Passwords - -ad_user_login assumes a password check has already been +created with a non-zero user_id. Passwords ad_user_login assumes a password check has already been performed (this will change in the future). The actual check is done by ad_check_password. The database stores a salt and a hash of the password concatenated with the salt. Updating the password (ad_change_password) simply requires getting a new salt (ns_time) concatenating and rehashing. Both the salt and the hashed password -field are updated. - - - -Performance Enhancements -A session is labeled by a session_id sequence. Creating a session merely +field are updated. Performance Enhancements 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 tcl_max_value is incremented by 100. This is done on a per-thread basis so that no locking is required. - -In addition, two procedures are dynamically generated at startup in + In addition, two procedures are dynamically generated at startup in security-init.tcl. These two procedures use ad_parameter 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 ad_parameter in sec_handler. The impact of this approach is that these parameters cannot be dynamically changed at runtime -and require a server restart. - - - -Session Properties - +and require a server restart. Session Properties 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. - - - - -Secure Session Properties -Session properties can be set as secure. In this case, + Secure Session Properties Session properties can be set as secure. In this case, ad_set_client_property will fail if the connection is not secure. ad_get_client_property will behave as if the property -had not been set if the property was not set securely. - - - -Digital Signatures & Signed Cookies - +had not been set if the property was not set securely. Digital Signatures & Signed Cookies 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. - -The signature produced by ad_sign is the Tcl list of + The signature produced by ad_sign is the Tcl list of token_id,expire_time,hash, 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: -+scheme consists of one table: create table secret_tokens ( token_id integer @@ -457,17 +176,14 @@ token_timestamp sysdate ); - - -ad_verify_signature takes a value and a signature and + ad_verify_signature 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. -Signed cookies include in their RFC2109 VALUE field a Tcl list of the +out on the signature. 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. -RFC 2109 specifies this optional "secure" parameter which +session. 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. - - -Performance -Performance is a key goal of this implementation of signed cookies. To +means. Performance 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 secret_tokens table as the canonical set of secret tokens. This table is necessary for multiple servers to maintain @@ -494,190 +205,94 @@ secret_tokens. 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. -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: - - -LRU cache Note that cache misses will only occur in the +per-thread basis. 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: LRU cache 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. - -signature cache Since the cache always maintains a +secret token issued by another server in the cluster. signature cache 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. - - +used to provide a random token for signature purposes. The per-thread cache functions as an L1 cache that indiscriminately caches -all secret tokens. Note that this is not an LRU cache +all secret tokens. Note that this is not an LRU cache because there is no cache eviction policy per se -- the cache is cleared when the thread is destroyed by AOLserver. - - - - -Security -Storing information on a client always presents an additional security -risk. -Since we are only validating the information and not trying to protect it + Security Storing information on a client always presents an additional security +risk. 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). - - - - -External SSL - +trying to protect information from being read (e.g., hashing passwords). External SSL 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. - - - - -PRNG - + PRNG 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. - - - - - -API - - -Login/Password - -ad_user_login user_id Logs the user in as user -user_id. Optional forever flag determines whether or not permanent + API Login/Password +ad_user_login user_id Logs the user in as user +user_id. Optional forever flag determines whether or not permanent cookies are issued. - - -ad_user_logout Logs the user out. - -ad_check_password user_id password -returns 0 or 1. -ad_change_password user_id new -password - - - -Digital Signatures and Signed Cookies - -ad_sign value Returns the digital signature of this -value. Optional parameters allow for the specification of the secret -used, the token_id used and the max_age for the signature. -ad_verify_signature value signatureReturns + ad_user_logout Logs the user out. ad_check_password user_id password +returns 0 or 1. ad_change_password user_id new +password Digital Signatures and Signed Cookies +ad_sign value Returns the digital signature of this +value. Optional parameters allow for the specification of the secret +used, the token_id used and the max_age for the signature. +ad_verify_signature value signatureReturns 1 or 0 indicating whether or not the signature matches the value specified. -The secret parameter allows for specification of a different secret -token to be used. - -ad_set_signed_cookie name data Sets a -signed cookie name with value data. - -ad_get_signed_cookie name Gets the signed cookie -name. It raises an error if the cookie has been tampered with, or if -its expiration time has passed. - - - -Session Properties - -ad_set_client_property module name -data Sets a session property with name to value -data for the module module. The optional secure flag +The secret parameter allows for specification of a different secret +token to be used. +ad_set_signed_cookie name data Sets a +signed cookie name with value data. ad_get_signed_cookie name Gets the signed cookie +name. It raises an error if the cookie has been tampered with, or if +its expiration time has passed. Session Properties ad_set_client_property module name +data Sets a session property with name to value +data for the module module. The optional secure flag specifies the property should only be set if the client is authorized for secure access (ad_secure_conn_p is true). There is also an optional -session_id flag to access data from sessions other than the current one. - -ad_get_client_property module name -data Gets a session property with name to for the -module module. The optional secure flag specifies the property +session_id flag to access data from sessions other than the current one. ad_get_client_property module name +data Gets a session property with name to for the +module module. The optional secure flag specifies the property should only be retrieved if the client is authorized for secure access (ad_secure_conn_p is true). There is also an optional -session_id flag to access data from sessions other than the current one. - - - -Parameters - -SessionTimeout the maximum time in seconds (default 1200) -between requests that are part of the same session - -SessionRenew the time in seconds (default 300) between +session_id flag to access data from sessions other than the current one. Parameters +SessionTimeout the maximum time in seconds (default 1200) +between requests that are part of the same session SessionRenew 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. - -SessionLifetime the maximum possible lifetime of a -session in seconds (default 604800 = 7 days) - -NumberOfCachedSecretTokens the number of secret tokens to -cache. (default 100) - - - - -Future Improvements - - -PRNG implementation - +downloaded. SessionLifetime the maximum possible lifetime of a +session in seconds (default 604800 = 7 days) NumberOfCachedSecretTokens the number of secret tokens to +cache. (default 100) Future Improvements PRNG implementation The pseudorandom number generator used in the OpenACS is cryptographically weak, and depends primarily on the randomness of the ns_rand function for its randomness. The implementation of the PRNG could be substantially improved. - - - - -ad_user_login - + ad_user_login Add a password argument. It is non-optimal to make the default behavior to assume that the password was provided. - - - - -Secret Tokens - + Secret Tokens 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. - -Since the security of the entire system depends on the secret tokens pool, + 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. - - - -Robots - +package. Robots 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. - - - - -Client properties - + Client properties 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. - - - - -Session information - + Session information 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. - - - - -Cookieless Sessions -Two trends drive the requirement for removing cookie dependence. WAP + Cookieless Sessions 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. -Problems that arise: +to work. Problems that arise: - -URL sharing could be dangerous. If I happen to be browsing Amazon + 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. -User-entered URLs are harder to handler. If a user is in the middle of +had. 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. - +session. 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. - - - - -Vulnerability Analysis - +cookied HTTP. Vulnerability Analysis 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. - - - -Cryptographically weak PRNG see -above. - -Dependence on sample -SQL command The list of random token that are placed in the secret + Cryptographically weak PRNG see +above. Dependence on sample +SQL command The list of random token that are placed in the secret tokens cache is randomly chosen by the Oracle sample 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. - -Dependence on -ns_rand The actual token that is +be as difficult as someone may anticipate. Dependence on +ns_rand The actual token that is chosen from the cache to be used is chosen by a call to -ns_rand. - -ad_secure_conn_p +ns_rand. ad_secure_conn_p As discussed above, the security of the secure sessions authentication system is -dependent upon this function. - - - - - - - - - - - - - - - - - -Prev Home Next - OpenACS 4 Security Requirements Up OpenACS 4 Security Notes - - - rmello at fslc.usu.edu - - +dependent upon this function. Prev Home Next OpenACS 4 Security Requirements Up OpenACS 4 Security Notes rmello at fslc.usu.edu vinod@kurup.com - - - - + Index: openacs.org-dev/packages/acs-core-docs/www/security-notes.html =================================================================== RCS file: /usr/local/cvsroot/openacs.org-dev/packages/acs-core-docs/www/security-notes.html,v diff -u -r1.1.1.1 -r1.1.1.2 --- openacs.org-dev/packages/acs-core-docs/www/security-notes.html 9 Jul 2002 17:34:57 -0000 1.1.1.1 +++ openacs.org-dev/packages/acs-core-docs/www/security-notes.html 11 Aug 2002 00:42:48 -0000 1.1.1.2 @@ -1,60 +1,29 @@ - - - -OpenACS 4 Security Notes - - - - - - - - - - - - - - -Prev Chapter 7. Kernel Documentation Next - - - - - -OpenACS 4 Security Notes - -by Richard Li - - +OpenACS 4 Security Notes Prev Chapter 7. Kernel Documentation Next OpenACS 4 Security Notes +by Richard Li + OpenACS docs are written by the named authors, but may be edited + by OpenACS documentation staff. + 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. - - - -HTTPS and the sessions system - + HTTPS and the sessions system If a user switches to HTTPS after logging into the system via HTTP, the user -must obtain a secure token. To insure security, the only way to +must obtain a secure token. To insure security, the only way 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. - -This method of authentication is important in order to establish, in as + 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. -If a developer truly does not want such a level of protection, this system +method of transmission. 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 sec_handler -procedure defined in security-procs.tcl: -+procedure defined in security-procs.tcl: if { [ad_secure_conn_p] && ![ad_login_page] } { set s_token_cookie [ns_urldecode [ad_get_cookie "ad_secure_token"]] @@ -65,11 +34,9 @@ } } - -The source code must also be edited if the user login pages have been + 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 -ad_login_page procedure in security-procs.tcl: -+ad_login_page procedure in security-procs.tcl: ad_proc -private ad_login_page {} { @@ -85,38 +52,10 @@ return 0 } - - + The set of string match expressions in the procedure above should be extended appropriately for other registration pages. This procedure does not use ad_parameter or regular expressions for performance reasons, as -it is called by the request processor. - ($Id$) - - - - - - - - - - - - - - - - -Prev Home Next - OpenACS 4 Security Design Up OpenACS 4 Request Processor Requirements - - - rmello at fslc.usu.edu - - +it is called by the request processor. ($Id$) Prev Home Next OpenACS 4 Security Design Up OpenACS 4 Request Processor Requirements rmello at fslc.usu.edu vinod@kurup.com - - - - + Index: openacs.org-dev/packages/acs-core-docs/www/security-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs.org-dev/packages/acs-core-docs/www/security-requirements.html,v diff -u -r1.1.1.1 -r1.1.1.2 --- openacs.org-dev/packages/acs-core-docs/www/security-requirements.html 9 Jul 2002 17:34:57 -0000 1.1.1.1 +++ openacs.org-dev/packages/acs-core-docs/www/security-requirements.html 11 Aug 2002 00:42:48 -0000 1.1.1.2 @@ -1,145 +1,50 @@ - - - -OpenACS 4 Security Requirements - - - - - - - - - - - - - - -Prev Chapter 7. Kernel Documentation Next - - - - - -OpenACS 4 Security Requirements - -by Richard Li - - - -Introduction - +OpenACS 4 Security Requirements Prev Chapter 7. Kernel Documentation Next OpenACS 4 Security Requirements +by Richard Li + OpenACS docs are written by the named authors, but may be edited + by OpenACS documentation staff. + Introduction This document lists the requirements for the security system for the OpenACS. - - - - -Vision Statement - + Vision Statement 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. - - - - -Security System Overview - + Security System Overview The security system consists of a number of subsystems. - -Signed Cookies - + Signed Cookies 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. - - - -10.0 Guaranteed Tamper Detection Any tampering of cookie -data should be easily detectable by the web server. - -10.1 Performance and Scalability Validation and + 10.0 Guaranteed Tamper Detection Any tampering of cookie +data should be easily detectable by the web server. 10.1 Performance and Scalability Validation and verification of the cookie should be easily scalable and should not require a -database query on every hit. - -Session Properties - +database query on every hit. Session Properties Applications should be able to store session-level properties in a database table. - - - -11.0 Storage API Session-level data should be accessible -via an API. - -11.1 Purge Mechanism An efficient pruning mechanism + 11.0 Storage API Session-level data should be accessible +via an API. 11.1 Purge Mechanism An efficient pruning mechanism should be used to prevent old session level properties from filling up the -table. - -Login - +table. Login The security system should support the concept of persistent user logins. This persistence takes several forms. - - - -12.0 Permanent Login Users should be able to maintain a -permanent user login so that they never need to type their password. - -12.1 Session Login The security system should support + 12.0 Permanent Login Users should be able to maintain a +permanent user login so that they never need to type their password. 12.1 Session Login The security system should support the concept of a session, with authentication tokens that become invalid -after a certain period of time. - -12.2 Session Definition A session is a sequence of +after a certain period of time. 12.2 Session Definition 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). - -12.3 Stateless The security system should not require +more than some constant (the session timeout). 12.3 Stateless 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). - -12.4 Secure The security system should not store -passwords in clear text in the database. - - -13.0 SSL Hardware The system must work when the SSL +AOLserver for each step of the login process (e.g., by a load balancer). 12.4 Secure The security system should not store +passwords in clear text in the database. 13.0 SSL Hardware The system must work when the SSL processing occurs outside of the web server (in specialized hardware, in a -firewall, etc.). - - - - - - - - - - - - - - - - -Prev Home Next - OpenACS 4.5 Package Manager Design Up OpenACS 4 Security Design - - - rmello at fslc.usu.edu - - +firewall, etc.). Prev Home Next OpenACS 4.5 Package Manager Design Up OpenACS 4 Security Design rmello at fslc.usu.edu vinod@kurup.com - - - - + Index: openacs.org-dev/packages/acs-core-docs/www/subsites-design.html =================================================================== RCS file: /usr/local/cvsroot/openacs.org-dev/packages/acs-core-docs/www/subsites-design.html,v diff -u -r1.1.1.1 -r1.1.1.2 --- openacs.org-dev/packages/acs-core-docs/www/subsites-design.html 9 Jul 2002 17:34:57 -0000 1.1.1.1 +++ openacs.org-dev/packages/acs-core-docs/www/subsites-design.html 11 Aug 2002 00:42:48 -0000 1.1.1.2 @@ -1,109 +1,50 @@ - - - -OpenACS 4 Subsites Design Document - - - - - - - - - - - - - - -Prev Chapter 7. Kernel Documentation Next - - - - - -OpenACS 4 Subsites Design Document - -by Rafael H. Schloming - -*Note* This document has not gone through the any of the +OpenACS 4 Subsites Design Document Prev Chapter 7. Kernel Documentation Next OpenACS 4 Subsites Design Document +by Rafael H. Schloming + OpenACS docs are written by the named authors, but may be edited + by OpenACS documentation staff. + *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. - - -Essentials -OpenACS 4 Subsites Requirements - - - -Introduction -An OpenACS 4 subsite is a managed suite of applications that work together for +demand. Essentials OpenACS 4 Subsites Requirements Introduction 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. -Meeting such broad requirements of flexibility demands architecture-level +the overarching philosophy of subsites. 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. - - - -Historical Considerations -The subsites problem actually has several quite diverse origins. It was +subsites as a whole. Historical Considerations 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. -Before the advent of scoping there were several cases of client projects +it an extremely cumbersome process to "scopify" a module. 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?) -The requirements of all these different projects vary greatly, but the one +details. Archnet?, iluvcamp?) 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. - - - -Competitive Analysis -... - - - -Design Tradeoffs -The current implementation of package instances and subsites allows +subsites addresses. Competitive Analysis ... Design Tradeoffs 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. - - - -API -This section will cover all the APIs relevant to subsites, and so will -consist of portions of the APIs of several systems. -Packages -The following package is provided for instantiation of packages. The +be feasible anymore. API This section will cover all the APIs relevant to subsites, and so will +consist of portions of the APIs of several systems. Packages 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) -+installed packages. (See APM docs for more detail XXX: insert link here) create or replace package apm_package as @@ -160,18 +101,15 @@ show errors - -Site Nodes -This data model keeps track of what packages are being served from what + Site Nodes 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. -+represented by the node. In most cases this will be a package instance. create table site_nodes ( node_id constraint site_nodes_node_id_fk @@ -199,9 +137,7 @@ ); - -The following package is provided for creating nodes. -+ The following package is provided for creating nodes. create or replace package site_node as @@ -246,47 +182,24 @@ show errors - -Request Processor -Once the above APIs are used to create packages and mount them on a + Request Processor 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. -+the package to serve content appropriate to the package instance. [ad_conn node_id] [ad_conn package_id] [ad_conn package_url] - - - - -Data Model Discussion -The subsites implementation doesn't really have it's own data + Data Model Discussion 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. - - - -User Interface -The primary elements of the subsite user interface consist of the subsite +data model. User Interface 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. - - - -Configuration/Parameters -... - - - -Future Improvements/Areas of Likely Change -The current subsites implementation addresses the most basic functionality +subsite administrator would want to do. Configuration/Parameters ... Future Improvements/Areas of Likely Change 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. - - - -Authors -rhs@mit.edu - - - - - - - - - - - - - - - - -Prev Home Next - OpenACS 4 Subsites Requirements Up OpenACS 4.5 Package Manager Requirements - - - rmello at fslc.usu.edu - - +solvable by configuration instead of coding. Authors rhs@mit.edu Prev Home Next OpenACS 4 Subsites Requirements Up OpenACS 4.5 Package Manager Requirements rmello at fslc.usu.edu vinod@kurup.com - - - - + Index: openacs.org-dev/packages/acs-core-docs/www/subsites-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs.org-dev/packages/acs-core-docs/www/subsites-requirements.html,v diff -u -r1.1.1.1 -r1.1.1.2 --- openacs.org-dev/packages/acs-core-docs/www/subsites-requirements.html 9 Jul 2002 17:34:57 -0000 1.1.1.1 +++ openacs.org-dev/packages/acs-core-docs/www/subsites-requirements.html 11 Aug 2002 00:42:48 -0000 1.1.1.2 @@ -1,214 +1,60 @@ - - - -OpenACS 4 Subsites Requirements - - - - - - - - - - - - - - -Prev Chapter 7. Kernel Documentation Next - - - -

- -OpenACS 4 Subsites Requirements - -by Rafael H. Schloming and Dennis Gregorovic - -

- -Introduction -The following is a requirements document for OpenACS 4 Subsites, part of the +OpenACS 4 Subsites Requirements Prev Chapter 7. Kernel Documentation Next

OpenACS 4 Subsites Requirements +by Rafael H. Schloming and Dennis Gregorovic + OpenACS docs are written by the named authors, but may be edited + by OpenACS documentation staff. + Introduction 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. - - - -Vision Statement -Many online communities are also collections of discrete subcommunities, +applications to be customized for defined user communities. Vision Statement 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. - - - -System Overview -The OpenACS subsite system allows a single OpenACS installation to serve multiple +subcommunity.

System Overview 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 request processor then figures out which package_id a particular URL references and then provides this information through the ad_conn api ([ad_conn -package_id], [ad_conn package_url]). -

The other piece of the subsite system is a subsite package that provides +package_id], [ad_conn package_url]).

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.

-Use-cases and User-scenarios

The Subsites functionality is intended for use by two different classes of -users:

Package programmers (referred to as 'the programmer') must -develop subcommunity-aware applications.
Site administrators (referred to as 'the administrator') use +subsite.

Use-cases and User-scenarios

The Subsites functionality is intended for use by two different classes of +users:

Package programmers (referred to as 'the programmer') must +develop subcommunity-aware applications.
Site administrators (referred to as 'the administrator') use subsites to provide tailored "virtual websites" to different -subcommunities.

Joe Programmer is working on the bboard package and wants to make it +subcommunities.

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.

Jane Admin maintains www.company.com. She learns of Joe's work and +work to tailor configuration parameters to the current subsite.

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.

Next, Jane uses the Subsite UI to create subsites for the Boston and +bboard package.

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.

Now, the Boston office employees have their own bboard at +office.

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.

-Related Links

OpenACS 4 Subsites Design Document
Test plan (Not available yet)

-Requirements: Programmer's API

A subsite API is required for programmers to ensure their packages are -subsite-aware. The following functions should be sufficient for this:

10.10.0 Package creation

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.

10.20.0 Package deletion

The system must provide an API call to delete a package and all related -objects in the subsite's context.

10.30.0 Object's package information

Given an object ID, the system must provide an API call to determine the -package (ID) to which the object belongs.

10.40.0 URL from package

Given a package (ID), the system must provide an API call to return the -canonical URL for that package.

10.50.0 Main subsite's package_id

The system must provide an API call to return a package ID corresponding -to the main subsite's package ID (the degenerate subsite).

-Requirements: The User Interface

The Programmer's User Interface

There is no programmer's UI, other than the API described above.

The Administrator's User Interface

The UI for administrators is a set of HTML pages that are used to drive +defaults.

Requirements: Programmer's API

A subsite API is required for programmers to ensure their packages are +subsite-aware. The following functions should be sufficient for this:

10.10.0 Package creation

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.

10.20.0 Package deletion

The system must provide an API call to delete a package and all related +objects in the subsite's context.

10.30.0 Object's package information

Given an object ID, the system must provide an API call to determine the +package (ID) to which the object belongs.

10.40.0 URL from package

Given a package (ID), the system must provide an API call to return the +canonical URL for that package.

10.50.0 Main subsite's package_id

The system must provide an API call to return a package ID corresponding +to the main subsite's package ID (the degenerate subsite).

Requirements: The User Interface

The Programmer's User Interface

There is no programmer's UI, other than the API described above.

The Administrator's User Interface

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.

-
20.10.0 Package creation
-
-20.10.1 The administrator should be able to create a -package and make it available at a URL underneath the subsite.
-
-
20.20.0 Package deactivation
-
-20.20.1 The administrator should be able to deactivate -any package, causing it to be inaccessible to users.
-
-20.20.5 Deactivating a package makes the package no +Site-Wide Administrators can manage all subsites.
- 20.10.0 Package creation
  20.10.1 The administrator should be able to create a +package and make it available at a URL underneath the subsite.
- 20.20.0 Package deactivation
  20.20.1 The administrator should be able to deactivate +any package, causing it to be inaccessible to users.
  20.20.5 Deactivating a package makes the package no longer accessible, but it does not remove data created within the context of -that package.
  -
-

-Revision History

------ - - - - - - - - - - - - - - - - - - - - -

Document Revision #	Action Taken, Notes	When?	By Whom?
0.1	Creation	08/18/2000	Dennis Gregorovic
0.2	Edited, reviewed	08/29/2000	Kai Wu

- - - - - - - - - - - -

-Prev	Home	Next -
OpenACS 4 Groups Design	Up	OpenACS 4 Subsites Design Document

- rmello at fslc.usu.edu -

+that package.

Revision History

Document Revision #	Action Taken, Notes	When?	By Whom?
0.1	Creation	08/18/2000	Dennis Gregorovic
0.2	Edited, reviewed	08/29/2000	Kai Wu

Prev	Home	Next
OpenACS 4 Groups Design	Up	OpenACS 4 Subsites Design Document

rmello at fslc.usu.edu

- - +

Index: openacs.org-dev/packages/acs-core-docs/www/subsites.html =================================================================== RCS file: /usr/local/cvsroot/openacs.org-dev/packages/acs-core-docs/www/subsites.html,v diff -u -r1.1.1.1 -r1.1.1.2 --- openacs.org-dev/packages/acs-core-docs/www/subsites.html 9 Jul 2002 17:34:57 -0000 1.1.1.1 +++ openacs.org-dev/packages/acs-core-docs/www/subsites.html 11 Aug 2002 00:42:48 -0000 1.1.1.2 @@ -1,37 +1,11 @@ - - - -Writing OpenACS 4.5 Application Pages - - - - - - - - -

- - - -

-Prev	Chapter 4. OpenACS Developer's Guide	Next -

-Writing OpenACS 4.5 Application Pages

+Writing OpenACS 4.5 Application Pages

Prev	Chapter 4. OpenACS Developer's Guide	Next

Writing OpenACS 4.5 Application Pages

By Rafael H. Schloming and Pete Su -

-Overview

+ OpenACS docs are written by the named authors, but may be edited + by OpenACS documentation staff. +

Overview

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. -

-Application Instances and Subsites

Application Instances and Subsites

As you will recall from the packages 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 mounting the application instance at a +creating such a mapping mounting 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 /notes as we did in the packages-example: -

+
- AOLserver receives your request for the URL /notes/somepage. -
- +
- This URL is passed to the request processor. -
- +
- The RP looks up the URL in the site map, and sees that the object mounted at that location is an instance of the notes application. -
- +
- The RP asks the package manager where in the file system the Notes package lives. In the standard case, this would be ROOT/packages/notes. -
- +
- The RP translates the URL to serve a page relative to the page root of the application, which is ROOT/packages/notes/www/. Therefore, the page that is finally served is ROOT/packages/notes/www/hello.html, which is what we wanted. -
-
+

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 ad_conn interfaces can be used to extract this information: -

[ad_conn package_url]

[ad_conn package_url]: If the URL refers to a package instance, this is the URL to the root of the tree where the package is mounted. -
[ad_conn package_id]: +
[ad_conn package_id]: If the URL refers to a package instance, this is the ID of that package instance. -
[ad_conn package_key] +

[ad_conn package_key] -

If the URL refers to a package instance, this is the unique key name of the package. -

[ad_conn extra_url] +

[ad_conn extra_url] -

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. -

In the Notes example, we are particularly interested in the package_id field. If you study the data model and code, you'll see why. As we said before in the data modeling 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. -

The code for adding and editing notes, in notes/www/add-edit.tcl, shows how this works. At the top of the page, we extract the package_id and use it to do permission checks: -

+
 
 set package_id [ad_conn package_id]
 
@@ -149,17 +97,14 @@
   set context_bar [ad_context_bar "New Note"]
 }
 
-
-
+

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. -

Later, when we actually create a note, the SQL that we run ensures that the context_id is set the right way: -

+
 
 db_dml new_note {
   declare
@@ -176,43 +121,33 @@
   end;
 }
 
-
-
+

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. -

-Using Forms

Using Forms

The forms API is pretty simple: You use calls in the template::form 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. -

So, given this outline, here is a breakdown of how the forms code works in the add-edit.tcl page. First, we create a form object called new_note: -

 
 template::form create new_note
 
-

All the forms related code in this page will refer back to this object. In addition, the adp part of this page does nothing but display the form object: -

+
 
 <master>
 
@@ -224,12 +159,10 @@
 <formtemplate id="new_note"></formtemplate>
 </center>
 
-
-
+

The next thing that the Tcl page does is populate the form with form elements. This code comes first: -

+
 
 if {[template::form is_request new_note] && [info exists note_id]} {
 
@@ -245,46 +178,36 @@
   }
 }
 
-
-
+

The if_request 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 tcl 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: -

+
- First render the input form. -
- +
- Next, control passes to a validation page that checks and confirms the inputs. -
- +
- Finally, control passes to the page that performs the update in the database. -
-
+

The rest of the if condition figures out if we are creating a new note or editing an existing note. If note_id 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. -

The next two calls create form elements where the user can insert or edit the title and body of the Note. The interface to template::element is pretty straightforward. -

Finally, the code at the bottom of the page performs the actual database updates when the form is submitted and validated: -

+
 
 if [template::form is_valid new_note] {
   set user_id [ad_conn user_id]
@@ -317,19 +240,13 @@
   ad_returnredirect "."
 }
 
-
-
+

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. -

-How it All Fits

How it All Fits

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. -

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. -

-Summary

Summary

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. -

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. -

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. -

($Id$)

- - - - - - - - - - - -

-Prev	Home	Next -
Groups, Context, Permissions	Up	Chapter 5. Other Developer Resources

- rmello at fslc.usu.edu -

Prev	Home	Next
Groups, Context, Permissions	Up	Chapter 5. Other Developer Resources

+substitute an appropriate string when you check the file in.

- - +

-Documenting Tcl Files: Page Contracts and Libraries

+Documenting Tcl Files: Page Contracts and Libraries

Prev	Chapter 7. Kernel Documentation	Next

Documenting Tcl Files: Page Contracts and Libraries

by Jon Salz on 3 July 2000 -

Tcl procedures: /packages/acs-kernel/tcl-documentation-procs.tcl

-The Big Picture

In versions of the OpenACS prior to 3.4, the standard +
+ OpenACS docs are written by the named authors, but may be edited + by OpenACS documentation staff. +

Tcl procedures: /packages/acs-kernel/tcl-documentation-procs.tcl

The Big Picture

In versions of the OpenACS prior to 3.4, the standard place to document Tcl files (both Tcl pages and Tcl library files) was in -a comment at the top of the file:

+a comment at the top of the file:

 #
-# path from server home/filename
+# path from server home/filename
 #
-# Brief description of the file's purpose
+# Brief description of the file's purpose
 #
-# author's email address, file creation date
+# author's email address, file creation date
 #
 # $Id$
 #
-

In addition, the inputs expected by a Tcl page (i.e., form variables) would be enumerated in a call to ad_page_variables, in effect, documenting the page's argument list. -

The problem with these practices is that the documentation is only +

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:

-ad_page_contract: Every Tcl page -has a contract that explicitly defines what inputs the page +web-based user interface for browsing the documentation:
- ad_page_contract: Every Tcl page +has a contract that explicitly defines what inputs the page expects (with more precision than ad_page_variables) and incorporates metadata about the page (what used to live in the top-of-page comment). Like ad_page_variables, ad_page_contract -also sets the specified variables in the context of the Tcl page.
- -ad_library: To be +also sets the specified variables in the context of the Tcl page.
- ad_library: To be called at the top of every library file (i.e., all files in the /tcl/ directory under the server root and -*-procs.tcl files under /packages/).
-
+*-procs.tcl files under /packages/).

This has the following benefits: -

Facilitates automatic generation of human-readable documentation.
Promotes security, by introducing a standard and automated way to check -inputs to scripts for correctness.
Allows graphical designers to determine easily how to customize -sites' UIs, e.g., what properties are available in templates.
Allows the request processor to be intelligent: a script can specify in +
- Facilitates automatic generation of human-readable documentation.
- Promotes security, by introducing a standard and automated way to check +inputs to scripts for correctness.
- Allows graphical designers to determine easily how to customize +sites' UIs, e.g., what properties are available in templates.
- 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.)
-

-ad_page_contract

+now - it's not complete for ACS 3.4.)

ad_page_contract

Currently ad_page_contract serves mostly as a replacement for ad_page_variables. 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 ad_page_contract a newer, better, documented ad_page_variables.) -

Let's look at an example usage of ad_page_contract:

+
Let's look at an example usage of ad_page_contract:
 
 # /packages/acs-kernel/api-doc/www/package-view.tcl
 ad_page_contract {
@@ -121,145 +71,87 @@
     @cvs-id $Id$
 }
 
-
-
+

Note that: -

-By convention, ad_page_contract should be preceded -by a comment line containing the file's path. The comment is on +
- By convention, ad_page_contract should be preceded +by a comment line containing the file's path. The comment is on line 1, and the contract starts on line 2. -
- -ad_page_contract's first argument is +
- ad_page_contract's first argument is the list of expected arguments from the HTTP query (version_id, public_p, kind, and format). Like ad_page_variables, ad_page_contract sets the corresponding Tcl variables when the page is executed. -
- -Arguments can have defaults, specified using the same +
- Arguments can have defaults, specified using the same syntax as in the Tcl proc (a two-element list where the first element is the parameter name and the second argument is the default value). -
- -
  -Arguments can have flags, specified by following the +
- Arguments can have flags, specified by following the name of the query argument with a colon and one or more of the following -strings (separated by commas):
  -
  - -optional: the query argument doesn't +strings (separated by commas):
    optional: 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 public_p in the query, then in the page body [info exists public_p] will return 0. -
    -
    -integer: the argument must be an integer +
    integer: the argument must be an integer (ad_page_contract 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. -
    -
    -sql_identifier: the argument must be a SQL +
    sql_identifier: the argument must be a SQL identifier (i.e., [string is wordchar $the_query_var] must return true). -
    -
    -trim: the argument will be [string +
    trim: the argument will be [string trim]'ed. -
    -
    -
    -multiple: the argument may be specified +
    multiple: 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 -multiple-list flag to ad_page_variables, and is useful for handling form input -generated by <SELECT MULTIPLE> tags and checkboxes.
    -
    For instance, if dest_user_id:multiple is specified in the -contract, and the query string is
    -
    +generated by <SELECT MULTIPLE> tags and checkboxes.
    For instance, if dest_user_id:multiple is specified in the +contract, and the query string is
    ?dest_user_id=913&dest_user_id=891&dest_user_id=9 -
    -
    +
    then $dest_user_id is set to [list 913 891 9]. -
    -
    -
    -
    -array: the argument may be specified +
    array: the argument may be specified arbitrarily many times in the query string, with parameter names with suffixes like _1, _2, _3, etc. The variable is set to a list of all those values (or an empty list if none are -specified).
    -
    For instance, if dest_user_id:array is specified in the -contract, and the query string is
    -
    +specified).
    For instance, if dest_user_id:array is specified in the +contract, and the query string is
    ?dest_user_id_0=913&dest_user_id_1=891&dest_user_id_2=9 -
    -
    -then $dest_user_id is set to [list 913 891 9].
    -
    -
    -
  - -
    -You can provide structured, HTML-formatted documentation for your -contract. Note that format is derived heavily from Javadoc: a +
    +then $dest_user_id is set to [list 913 891 9].
- You can provide structured, HTML-formatted documentation for your +contract. 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 (@). You are encouraged to provide: -
  -
  - A description of the functionality of the page. If the description +
    A description of the functionality of the page. If the description contains more than one sentence, the first sentence should be a brief summary. -
    -
    -
    A @param tag for each allowable query -argument. The format is
    -
    +
    A @param tag for each allowable query +argument. The format is
    -@param parameter-name description... +@param parameter-name description... -
    -
    -
    An @author tag for each author. Specify the -author's name, followed his or her email address in parentheses.
    -
    A @creation-date tag indicating when the -script was first created.
    -
    A @cvs-id tag containing the page's CVS +
    An @author tag for each author. Specify the +author's name, followed his or her email address in parentheses.
    A @creation-date tag indicating when the +script was first created.
    A @cvs-id tag containing the page's CVS identification string. Just use $Id: tcl-documentation.html,v 1.2 2000/09/19 07:22:35 ron Exp $ when creating the file, and CVS will -substitute an appropriate string when you check the file in.
    -
    -
    - These @ tags are optional, but highly recommended!
    -
  -
-
-
-ad_library
-
+substitute an appropriate string when you check the file in.

+ These @ tags are optional, but highly recommended!

ad_library

ad_library provides a replacement for the informal documentation (described above) found at the beginning of every Tcl page. Instead of: -

+
 
 # /packages/acs-kernel/00-proc-procs.tcl
 #
@@ -269,11 +161,9 @@
 #
 # $Id$
 
-
-
+

you'll now write: -

+
 
 # /packages/acs-kernel/00-proc-procs.tcl
 ad_library {
@@ -287,49 +177,16 @@
 
 }
 
-
-
+

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 (@). HTML formatting is allowed. You are encouraged to provide: -

An @author tag for each author. Specify the -author's name, followed his or her email address in parentheses.
A @creation-date tag indicating when the -script was first created.
A @cvs-id tag containing the page's CVS +
- An @author tag for each author. Specify the +author's name, followed his or her email address in parentheses.
- A @creation-date tag indicating when the +script was first created.
- A @cvs-id tag containing the page's CVS identification string. Just use $Id: tcl-documentation.html,v 1.2 2000/09/19 07:22:35 ron Exp $ when creating the file, and CVS will -substitute an appropriate string when you check the file in.
-
($Id$)
-

- - - - - - - - - - - -

-Prev	Home	Next -
Database Access API	Up	Bootstrapping OpenACS

- rmello at fslc.usu.edu -

-Using Templates in OpenACS 4.5

By Pete Su -

-Overview

+Using Templates in OpenACS 4.5

Prev	Chapter 4. OpenACS Developer's Guide	Next

Using Templates in OpenACS 4.5

By Pete Su

+ OpenACS docs are written by the named authors, but may be edited + by OpenACS documentation staff. +

Overview

The OpenACS 4.5 Template System (ATS) is designed to allow developers to -cleanly separate application logic from display -logic. The intent is to have all of the logic related to +cleanly separate application logic from display +logic. 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. -

In ATS, you write two files for every user-visible page in the system. One is a plain .tcl file and the other is a special .adp file. The .tcl file runs a -script that sets up a set of name/value bindings that we call data -sources. These data sources are generally the results of Tcl and/or database queries +script that sets up a set of name/value bindings that we call data +sources. These data sources are generally the results of Tcl and/or database queries or some combination thereof. The template system automatically makes them available to the .adp file, or the display part of the template, which is written in a combination of HTML, special template related tags, and data source substitutions. -

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. -

-Entering Notes

Entering Notes

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. -

The .tcl 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 note-add.tcl in the ROOT/packages/notes/www directory, and put the following code in it: -

+
 
 ad_page_contract {
 
@@ -112,12 +76,9 @@
 
 ad_return_template "note-add"
 
-
-
+

Some things to note about this code: -

+
- The procedure ad_page_contract is always the first thing a .tcl 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. -
- +
- After being declared in the ad_page_contract, each property is just a simple Tcl variable. The template system passes the final value of the variable to the .adp template when the .tcl file is processed. -
- +
- The call ad_return_template tells the template system what .adp 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 .tcl file that just ran, but with an .adp extension. -
-
+

Next we write the corresponding .adp page. This page outputs HTML for the form, and also contains placeholders whose values are substituted in from the properties set up by the .tcl file. Create a file called note-add.adp in your editor, and insert this text: -

+
 
 <master src="master">
 <property name="title">@page_title@</property>
@@ -173,8 +129,7 @@
 </p>
 </form>
 
-
-
+

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 master.adp file, which looks like this: -

+
 
 <%= [ad_header $title] %> 
 <h2>@title@</h2> 
@@ -194,60 +148,26 @@
 <br clear="all"> 
 <%= [ad_footer] %>
 
-
-
+

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 <property> tags in the slave page. -

After putting all these files into ROOT/packages/notes/www, you should be able to go to /notes/ URL for your server and see the input form. -

-Summary

Summary

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 .tcl that sets up -data sources that are used by the display part of the page. The +data sources that are used by the display part of the page. The display part of the page is an .adp 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. -

($Id$)

- - - - - - - - - - - -

-Prev	Home	Next -
The OpenACS Database Access API	Up	Groups, Context, Permissions

- rmello at fslc.usu.edu -

Prev	Home	Next
The OpenACS Database Access API	Up	Groups, Context, Permissions

- - +

-Overview

This walks you through an OpenACS installation under Windows.

Overview

This walks you through an OpenACS installation under Windows.

-OpenACS Installation Guide for Windows2000

By Matthew Burke and Curtis Galloway -

Source: http://software.arsdigita.com/dist -
Bug reports: acs-bugs@arsdigita.com -
Philosophy: http://photo.net/wtr/thebook/community - (the community chapter of Philip and Alex's Guide to Web - Publishing)
Technical background: http://photo.net/wtr/thebook/ -

-Overview

+OpenACS Installation Guide for Windows2000

Prev	Chapter 3. Installing on Windows	Next

OpenACS Installation Guide for Windows2000

By Matthew Burke and Curtis Galloway

+ OpenACS docs are written by the named authors, but may be edited + by OpenACS documentation staff. +

NOTE: These instructions were + valid for ACS v4, but have not been tested with OpenACS. Currently + (8/2002), the best option to get OpenACS 4.5 running on Windows + is to use VMware and John + Sequeira's Oasis VM + distribution +

Source: http://software.arsdigita.com/dist
Bug reports: acs-bugs@arsdigita.com
Philosophy: http://photo.net/wtr/thebook/community + (the community chapter of Philip and Alex's Guide to Web + Publishing)
Technical background: http://photo.net/wtr/thebook/

Overview

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.

Note:

We do not recommend running a production + machine.

Note:

We do not recommend running a production server on Windows98. But the platform is more than sufficient for working the problem sets and for getting a feel for the OpenACS. -

You'll need to use the ArsDigita binary distribution of AOLserver +

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 the ArsDigita AOLserver 3 distribution page for - details.

You can download the binary distribution from the ArsDigita download page + details.

You can download the binary distribution from the ArsDigita download page 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.

-Prerequisites

Windows 2000 or Windows 98
-WinZip or any tool that can - extract gzipped/tarred archives.
-zsh (free; - included in the binary distribution). If this link is broken try http://www.zsh.org.
-Oracle 8 relational database - management system
-AOLserver (free)
-ArsDigita - Oracle driver for AOLserver (free)

It is helpful if you have Oracle interMedia Text for full-text searches. + specific to the version you are downloading.

Prerequisites

Windows 2000 or Windows 98
WinZip or any tool that can + extract gzipped/tarred archives.
zsh (free; + included in the binary distribution). If this link is broken try http://www.zsh.org.
Oracle 8 relational database + management system
AOLserver (free)
ArsDigita + Oracle driver for AOLserver (free)

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 http://www.pls.com. -

Although the zsh shell is the only command-line tool +

Although the zsh shell is the only command-line tool required to install the OpenACS, if you are a UNIX person used to typing ls instead of dir you'll get along much better with the Cygwin toolkit from RedHat (available at http://sourceware.cygnus.com/cygwin). This is a development library and set of tools that gives you a very UNIX-like environment under Windows. In particular, it includes bash, gzip and tar, which you can - use to perform the OpenACS installation instead of WinZip and zsh.

-Your Oracle installation

+ use to perform the OpenACS installation instead of WinZip and zsh.

Your Oracle installation

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 (yes, - that's Windows

) will run on your + Oracle Administration Assistant for Windows NT (yes, + that's Windows
NT
) will run on your machine or not (in some cases, it will complain about Microsoft Managment - Console not being installed).

If it runs on your machine, proceed as follows:

Run Oracle Administration Assistant for Windows NT
Navigate using the Explorer-style control in the left panel and - select the Oracle Home for the database you wish to use.
Bring up its properties dialog and add a parameter NLS_DATE_FORMAT - with value 'YYYY-MM-DD' (without the - quotes)
Verify the date format by logging into the database using SQL Plus + Console not being installed).
If it runs on your machine, proceed as follows:
1. Run Oracle Administration Assistant for Windows NT
2. Navigate using the Explorer-style control in the left panel and + select the Oracle Home for the database you wish to use.
3. Bring up its properties dialog and add a parameter NLS_DATE_FORMAT + with value 'YYYY-MM-DD' (without the + quotes)
4. Verify the date format by logging into the database using SQL Plus and run the following query: select sysdate from - dual; -
-
Otherwise you will need to perform a little registry surgery as - follows:
-
1. Run regedit and navigate down the registry keys to - HKEY_LOCAL_MACHINE\Software\ORACLE.
2. + dual;
Otherwise you will need to perform a little registry surgery as + follows:
1. Run regedit and navigate down the registry keys to + HKEY_LOCAL_MACHINE\Software\ORACLE.
2. Choose the appropriate subtree; this will be HOME0 if you only have on einstallation of Oracle. -
  +
  If you are an Oracle achiever and have more than one Oracle installation on your machine, you will see HOME0, HOME1, HOME2, etc. Choose the subtree that corresponds to the Oracle installtion you wish to use with the OpenACS. -
  -
3. If the NLS_DATE_FORMAT key is already present, +
  +
4. If the NLS_DATE_FORMAT key is already present, double-click on its value and change it to 'YYYY-MM-DD' - (without the quotes). If the key does not + (without the quotes). If the key does not exist, choose Edit->New->String Value from the menu and type NLS_DATE_FORMAT for the name of the new value to - create it. Then double-click on the empty value to change it.
5. Verify the date format by logging into the database using SQL Plus + create it. Then double-click on the empty value to change it.
6. Verify the date format by logging into the database using SQL Plus and run the following query: select sysdate from - dual; -
-
For more information on Oracle configuration look at http://photo.net/wtr/oracle-tips + dual;

For more information on Oracle configuration look at http://photo.net/wtr/oracle-tips or search the Web/db Q&A Forum. One other note: the "nuke a user" admin page and Intermedia won't run unless you set open_cursors = 500 @@ -152,210 +79,123 @@ or search the Web/db Q&A Forum. One other note: the "nuke a user" admin page and Intermedia won't run unless you set open_cursors = 500 - for your database.

-The ArsDigita binary installation

+ for your database.

The ArsDigita binary installation

Extract the ArsDigita AOLserver distribution onto the C: drive into the default aol30 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 C:. -

-Untar the OpenACS

Untar the OpenACS

We recommend rooting webserver content in c:\web. Since most servers these days are expected to run multiple services from multiple IP addresses, each server gets a subdirectory from c:\web. For example, http://scorecard.org would be rooted at c:\web\scorecard on one of our machines and if http://jobdirect.com were on the same box then it would be at c:\web\jobdirect. -

For the sake of argument, we're going to assume that your service +

For the sake of argument, we're going to assume that your service is called "yourdomain", is going to be at http://yourdomain.com and is rooted at c:\web\yourdomain in the Windows 2000 file system. Note that you'll find our definitions files starting out with - "yourdomain.com".

download the OpenACS (see above) into - c:\temp\acs.tar.gz -
use WinZip (or equivalent) to extract the files to - c:\web\yourdomain -

+ "yourdomain.com".

download the OpenACS (see above) into + c:\temp\acs.tar.gz
use WinZip (or equivalent) to extract the files to + c:\web\yourdomain

You'll now find that c:\web\yourdomain\www contains the document root and c:\web\yourdomain\tcl contains Tcl scripts that are loaded when the AOLserver starts up. -

-Feeding Oracle the Data Model

Feeding Oracle the Data Model

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. -

-
+
- load the states, country_codes and counties tables using the load-geo-tables shell script in the c:\web\yourdomain\www\install - directory. You will need to open a console window and run
  -
```
+        directory. You will need to open a console window and run 
 zsh load-geo-tables foo/foopassword
-
-
+
```
  You most likely will see a slew of "Commit point reached . . . " messages. This does not indicate a problem. -
  -
- -
  +
- cd to c:\web\yourdomain\www\doc\sql 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 -
  -
```
+
 sqlplus foo/foopassword < load-data-model.sql
-
-
```
- -
  +
- If you have interMedia installed, while still in c:\web\yourdomain\www\doc\sql, run -
  -
```
+
 zsh load-site-wide-search foo foopassword ctxsys-password
-
-
+
```
  Note that there's no slash between foo and foopassword here. The third argument, ctxsys-password, is the password for interMedia Text's special ctxsys user. -
  -
-

-Configuring AOLServer

You will need two configuration files. The first is a Tcl file with +

Configuring AOLServer

You will need two configuration files. The first is a Tcl file with configuration information for AOLserver. This should be called yourdomain and should be located in c:\aolserve3_0. The second is an .ini file that configures the OpenACS and is discussed below. Note that pathnames in yourdomain must use forward slashes rather than the Windows - back slashes. This is also true for the .ini file.

The following items must be defined in yourdomain:

three database pools: main, subquery, and log. They must be named - as such. The default pool will be "main".
the auxconfig directory which contains the .ini file: - c:\web\yourdomain\parameters -
the pageroot: c:\web\yourdomain\www -
the directory containing the TclLibrary: - c:\web\yourdomain\tcl -

+ back slashes. This is also true for the .ini file.

The following items must be defined in yourdomain:

three database pools: main, subquery, and log. They must be named + as such. The default pool will be "main".
the auxconfig directory which contains the .ini file: + c:\web\yourdomain\parameters
the pageroot: c:\web\yourdomain\www
the directory containing the TclLibrary: + c:\web\yourdomain\tcl

You can use our template file as a starting - point (you'll need to save this file with a rather than .txt - extension). -

-Configuring OpenACS itself

+ point (you'll need to save this file with a rather than .txt + extension). +

Configuring OpenACS itself

If you want a system that works, go to c:\web\yourdomain\parameters and copy ad.ini to - yourdomain.ini (or any other name different from - ad.ini). You don't actually have to delete + yourdomain.ini (or any other name different from + ad.ini). You don't actually have to delete ad.ini. -

Each section of yourdomain.ini has a hardcoded +

Each section of yourdomain.ini has a hardcoded "yourservername" in the name (e.g. [ns/server/yourservername/acs]). This means that the OpenACS will ignore your configuration settings unless your AOLserver name happens to be "yourservername". Therefore you must go through yourdomain.ini and change "yourservername" to - whatever you're calling this particular AOLserver (look at the - server name in the nsd file for a reference).

Unless you want pages that advertise a community called + whatever you're calling this particular AOLserver (look at the + server name in the nsd file for a reference).

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 yourdomain.ini to change system-wide parameters. If you want to see how some of these are used, a good place to look is c:\web\yourdomain\tcl\ad-defs. The Tcl function, ad_parameter, is used to grab parameter values from the .ini - file.

-Starting the Service

+ file.

Starting the Service

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 c:\aol30. Then run -

 bin\nsd -ft yourdomain.tcl
-

This will print all the AOLserver messages to the console so you can see +

This will print all the AOLserver messages to the console so you can see them. -

Try to connect to your new server with a web browser. If you see the +

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 c:\web\yourdomain\parameters If everything seems ok, you can kill the server with Control-c and then - issue the following command to install as a Windows service:

+ issue the following command to install as a Windows service:

 bin\nsd -I -s yourdomain -t yourdomain.tcl
-

You can now configure error recovery and other Windows aspects of the +

You can now configure error recovery and other Windows aspects of the service from the Services control panel. If you make further changes to yourdomain or yourdomain.ini you should stop and start the service from the Services control panel. -

-Configuring Permissions

Configuring Permissions

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: -

/doc (or at least /doc/sql/ since some AOLserver configurations - will allow a user to execute SQL files)
/admin
any private admin dirs for a module you might have written that are - not underneath the /admin directory

-Adding Yourself as a User and Making Yourself a Sysadmin

/doc (or at least /doc/sql/ since some AOLserver configurations + will allow a user to execute SQL files)
/admin
any private admin dirs for a module you might have written that are + not underneath the /admin directory

Adding Yourself as a User and Making Yourself a Sysadmin

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 https://yourservername.com/admin/ug/ directory and add your personal user as a site-wide administrator. Now you're bootstrapped! -

If you do not know what the system user's password is connect to - Oracle using SQL Plus and run the following query:

If you do not know what the system user's password is connect to + Oracle using SQL Plus and run the following query:

 select password from users where last_name = 'system';
-

-Closing Down Access

Closing Down Access

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 user registration and access control and decide what the appropriate user state is for anonymous on your site. -

-Where to Find What

Where to Find What

A few pointers: -

the /register directory contains the login and registration +
- the /register directory contains the login and registration scripts. You can easily redirect someone to /register/index to have - them login or register.
- the /pvt directory is for user-specific pages. They can only be - accessed by people who have logged in.
-

-Making sure that it works

+ them login or register.

the /pvt directory is for user-specific pages. They can only be + accessed by people who have logged in.

Making sure that it works

Run the acceptance tests in /doc/acceptance-test -

-Running Multiple Instances of the OpenACS

Running Multiple Instances of the OpenACS

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: -

Oracle tablespace and a user account with the appropriate +
- Oracle tablespace and a user account with the appropriate permissions on that tablespace. Each of these tablespaces must have the - OpenACS data model loaded.
- file with the appropriate settings including server name, - auxconfig, ipaddress, and port.
- Copy of the acs files in an appropriate directory under - c:\web.
-
Suppose you wish to run two services: lintcollectors.com and + OpenACS data model loaded.
file with the appropriate settings including server name, + auxconfig, ipaddress, and port.
Copy of the acs files in an appropriate directory under + c:\web.

Suppose you wish to run two services: lintcollectors.com and iguanasdirect.com. You would need the following: -

an Oracle tablespace, lintcollectors with a user - lintcollectors and password secretlint -
an Oracle tablespace, iguanasdirect with a user - iguanasdirect and password secretiguanas -

For each of these tablespaces/users you would load the OpenACS data model as +

an Oracle tablespace, lintcollectors with a user + lintcollectors and password secretlint
an Oracle tablespace, iguanasdirect with a user + iguanasdirect and password secretiguanas

For each of these tablespaces/users you would load the OpenACS data model as described above. Then in c:\aolserver3_0 create files for each service, i.e. lintcollectors and iguanasdirect. These files would point to their respective @@ -446,43 +247,13 @@ c:\web\iguanasdirect\parameters; etc. In the respective auxconfigdirs would be the files lintcollectors.ini and iguanasdirect.ini. -

Now open a console window and go to c:\aol30. You'll - start up the two services as follows:

Now open a console window and go to c:\aol30. You'll + start up the two services as follows:

 bin\nsd -I -s lintcollectors -t lintcollectors.tcl
 bin\nsd -I -s iguanasdirect -t iguanasdirect.tcl
-

In the services control panel you should see two services: +

In the services control panel you should see two services: AOLserver-lintcollectors and AOLserver-iguanasdirect. -

($Id$)

- - - - - - - - - - - -

-Prev	Home	Next -
Overview	Up	Part Part III. For OpenACS Developers

- rmello at fslc.usu.edu -

Prev	Home	Next
Overview	Up	Part Part III. For OpenACS Developers